docs: make AGENTS.md the only agent guide, restructured into five sections

AGENTS.md now holds the instructions and CLAUDE.md and GEMINI.md are
pointers to it. Three files of instructions become three files that
disagree; one file every agent reads cannot.

The content is reorganised rather than rewritten, into: the invariants,
the guards that fail the build, the validation this codebase deliberately
does not perform, the environment, and where to read next. Every guard
now names the test that catches it, and the two rules with no test behind
them are called out as such, because "only review catches this" is
information the reader needs.

Restructuring surfaced one rule that was missing here entirely — sw.js
must stay unhashed and be served no-cache — which had only ever been
written down in ARCHITECTURE.md.

Dropped: the `bun init` boilerplate code samples. Every rule they carried
is still stated; the hello-world test and the three frontend snippets are
not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lucas WintherandClaude Opus 5 committed 2026-09-02 21:57:38 +02:00
1 parent d83edccc79
commit 824c2f5f59
13 files changed
+227 -263

No files matched your search

+5 -5
View File
@@ -72,7 +72,7 @@ Tests are co-located: `src/domain/money.test.ts` beside `src/domain/money.ts`.
**Files:**
- Create: `package.json`, `tsconfig.json`, `bunfig.toml`, `build.ts`, `src/index.ts`, `src/index.html`, `src/frontend.tsx`, `src/index.css` (all via `bun init`)
- Modify: `CLAUDE.md` (append project invariants), `.gitignore`
- Modify: `AGENTS.md` (append project invariants), `.gitignore`
- Delete: `src/APITester.tsx`, `src/logo.svg`, `src/react.svg`
- Test: `src/domain/smoke.test.ts`
@@ -158,9 +158,9 @@ Expected: PASS, 1 test.
Run: `bun --hot src/index.ts`
Expected: server starts, and the printed URL shows "Budget 2.0". Stop it with Ctrl-C.
- [ ] **Step 7: Append project invariants to CLAUDE.md**
- [ ] **Step 7: Append project invariants to AGENTS.md**
The scaffolded `CLAUDE.md` documents Bun idioms. Append the rules specific to this project:
The scaffolded `AGENTS.md` documents Bun idioms. Append the rules specific to this project:
```markdown
## Project invariants (Budget 2.0)
@@ -196,7 +196,7 @@ git add -A
git commit -m "chore: scaffold Bun + React + shadcn project
bun init --react=shadcn, with the demo API routes removed since this app
has no backend. Adds project invariants to CLAUDE.md and a smoke test
has no backend. Adds project invariants to AGENTS.md and a smoke test
proving the domain layer imports with no DOM."
```
@@ -253,7 +253,7 @@ export const CURRENCY_DIGITS: Record<Currency, number> = {
EUR: 2,
};
/** A float amount paired with its currency. See CLAUDE.md for rounding rules. */
/** A float amount paired with its currency. See AGENTS.md for rounding rules. */
export interface Money {
amount: number;
currency: Currency;