CLAUDE.md is project memory; AGENTS.md is the contract. It's the one file that holds the toolchain, the commands, and the code style every agent and human must follow — so the rules live in exactly one place and never drift between tools.
# AGENTS.md — the single source of truth for project rules.
CLAUDE.md and editor configs only point here. Keep this current;
put feature detail in docs/ and link it, never inline it.
## Commands
- install: `bun install` (CI uses --frozen-lockfile)
- check: `bun run typecheck && bun run lint && bun run format:check`
- run a job: `bun <file>.ts`
## Toolchain
bun (runtime + pm) · tsgo (typecheck) · oxlint · oxfmt.
Do NOT reintroduce npm/yarn, ts-node, eslint, or prettier —
they were removed on purpose.
## Code style
- Formatting is enforced by the formatter. Never hand-format — run format.
- Strict TypeScript. No `any`. Fix the type, don't cast it.
- Prefer runtime-native APIs over a dependency for the same job.
## Patterns
- One concern per file; add a job = file + script + workflow.
- Bounded concurrency for network fan-out, never unbounded Promise.all.
- A feature that needs a secret no-ops with a log line when it's absent.One file, everything else points to it#
The rule that pays off most is the first line: CLAUDE.md, editor configs, and contributor docs only reference AGENTS.md. The moment a rule is written twice it starts contradicting itself. Keeping conventions in one place means an agent and a teammate read the identical source.
Name what was deliberately removed#
"Do not reintroduce npm/yarn/eslint" stops the most common regression cold. An agent reaching for a familiar tool will happily re-add the thing you spent a day deleting. Recording the intentional absences, not just the current stack, is what makes a toolchain decision stick.