AGENTS.md · diff
git:20260917.9484eaf to git:20260917.a589e3f
21 added, 24 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
- # Acme
+ # Project
- Instructions for AI coding agents, whatever the tool. Tool-specific layers build on this file: Claude Code adds `CLAUDE.md` and `.claude/`, Cursor adds `.cursor/`.
+ <!-- TODO(adapt): replace the heading with the project name and write 1-2 sentences on what it is, its stack, and its shape (single package, monorepo, services). Run /adapt-to-project to fill every TODO(adapt) in this repo. -->
- Acme is a fictional real-time messaging platform used as a worked example for this configuration. It is a strict-convention pnpm + Turborepo monorepo.
+ Instructions for AI coding agents, whatever the tool. Tool-specific layers build on this file: Claude Code adds `CLAUDE.md` and `.claude/`, Cursor adds `.cursor/`.
## Role
- Expert TypeScript / Node.js / React architect working in a strict-convention pnpm monorepo.
+ <!-- TODO(adapt): the expertise to bring, e.g. "Expert Python / FastAPI engineer working in a strict-convention service". -->
**Core rule:** Before creating or modifying code, read 2-3 similar files in the same directory and match their patterns exactly.
## Conventions
`docs/conventions/` is the single source of truth. The conventions for every area covering a file must be in context before you touch it: Claude Code injects them through `.claude/rules/`; other tools read them from this table.
| Area | Paths | Conventions |
| --- | --- | --- |
- | Core | any `*.ts` / `*.tsx` | `docs/conventions/core.md` |
- | Backend | `apps/acme-api/**`, `packages/acme-db/**` | `docs/conventions/backend.md` |
- | Frontend | `apps/acme-web/**` | `docs/conventions/frontend.md` |
- | Services | `services/acme-gateway/**`, `services/acme-session-engine/**`, `packages/acme-rpc/**`, `packages/acme-providers/**` | `docs/conventions/services.md` |
- | Testing | `**/*.test.ts`, `**/*.test.tsx`, `**/*.mock.ts`, `**/test/**`, `**/vitest*.config.ts`, `tools/vitest/**` | `docs/conventions/testing.md` |
+ | Core | any source file | `docs/conventions/core.md` |
+ | Testing | test files and test directories | `docs/conventions/testing.md` |
+ <!-- TODO(adapt): add one row per area with its own rules (e.g. API, database, frontend), each with a matching docs/conventions/<area>.md and .claude/rules/<area>-conventions.md. -->
+
`docs/README.md` (Diátaxis-structured) covers anything outside these areas; shared vocabulary lives in `docs/glossary.md`.
## Layout
- Topology + end-to-end session flow: `docs/reference/backend-architecture.md`.
+ Topology, components and data flow: `docs/reference/architecture.md`.
## Comments
- Default to no inline comment. Add `//` only for a non-obvious WHY (invariant, unit, ordering, gotcha), never to narrate WHAT the code does. If removing a comment wouldn't confuse a competent reader, delete it. A WHY comment that restates the callee's JSDoc or class doc is a duplicate: read the callee's docs before keeping it; if the seam already says it, delete the call-site copy.
+ Default to no inline comment. Add one only for a non-obvious WHY (invariant, unit, ordering, gotcha), never to narrate WHAT the code does. If removing a comment wouldn't confuse a competent reader, delete it. A WHY comment that restates the callee's doc comment is a duplicate: read the callee's docs before keeping it; if the seam already says it, delete the call-site copy.
- ```ts
- retries++; // increment the retry counter (BAD: restates the code)
- retries++; // 429s are transient, so retry first (GOOD: explains the why)
```
+ retries += 1 # increment the retry counter (BAD: restates the code)
+ retries += 1 # 429s are transient, so retry first (GOOD: explains the why)
+ ```
## Altitude
- Build the smallest thing that works; the obligation lives in `docs/conventions/core.md` §Altitude / YAGNI. Before finishing a change that introduced any discretionary construct (new file, helper, wrapper, option, param, interface, generic, or defensive branch), list each one with a keep-or-inline verdict; keep means you can name a second caller or a real WHY. Default to inline/delete. Don't list prescribed taxonomy roles, and skip the audit silently when a change added none. Unjustifiable bloat is a `/simplify` candidate.
-
- ## Frontend
-
- Single SPA at `apps/acme-web/`. Conventions in `docs/conventions/frontend.md`; architecture in `docs/reference/frontend-architecture.md`.
+ Build the smallest thing that works; the obligation lives in `docs/conventions/core.md` §Altitude / YAGNI. Before finishing a change that introduced any discretionary construct (new file, helper, wrapper, option, param, interface, generic, or defensive branch), list each one with a keep-or-inline verdict; keep means you can name a second caller or a real WHY. Default to inline/delete. Don't list constructs a convention prescribes, and skip the audit silently when a change added none. Unjustifiable bloat is a `/simplify` candidate.
## Git workflow (CRITICAL)
- - NEVER work on or push to `main`. PRs only.
- - ALWAYS use `pnpm worktree:create <name>` (creates `.worktrees/<name>` with `feature/<name>`). NEVER `git checkout -b` in the main worktree.
- - `git branch --show-current` MUST NOT be `main` before committing.
+ - NEVER work on or push to the trunk (`GIT_TRUNK` in `.claude/project.env`, default `main`). PRs only.
+ - ALWAYS use `scripts/worktree-create.sh <name>` (creates `.worktrees/<name>` on `feature/<name>`). NEVER `git checkout -b` in the main worktree.
+ - `git branch --show-current` MUST NOT be the trunk before committing.
## Key commands
- `pnpm test:integration` runs in-process (no services need to be up); `pnpm dev` reads `.env`.
+ Lint, typecheck, test and install commands live in `.claude/project.env` (`LINT_CMD`, `TYPECHECK_CMD`, `TEST_CMD`, `INSTALL_CMD`).
- **Formatting/typechecking:** run `pnpm lint` and `pnpm typecheck` before handing work back. (Claude Code only: don't run them manually; its `Stop` hook runs Biome + tsc automatically.)
+ <!-- TODO(adapt): list the commands an agent needs beyond those (dev server, integration tests, codegen, migrations) and any gotcha (services that must be up, env files). -->
+
+ **Formatting/typechecking:** run the lint and typecheck commands before handing work back. (Claude Code only: don't run them manually; its `Stop` hook runs them automatically.)