agents-md

# Maintaining AGENTS.md Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100. ## Workflow 1. Inspect before writing: - package manager: lock files and manifests - commands: `package.json`, `Makefile`, task runners, CI workflows - docs/specs/policies: `README.md`, `CONTRIBUTING.md`, `docs/`, `specs/`, `policies/`, `SECURITY.md`, `.github/` - conventions: current code patterns, test layout, generated files, legacy areas to avoid 2. Choose scope: - root `AGENTS.md`: repo-wide defaults - nested `AGENTS.md`: only when a subtree has different commands or rules - closest instruction file wins; keep narrower files shorter than root files 3. Write the smallest useful file. 4. Verify exact paths and commands exist. ## File Setup - Create `AGENTS.md` at the repository root. - If a Claude-compatible entrypoint is required, symlink `CLAUDE.md` to `AGENTS.md`. - Do not maintain divergent `AGENTS.md` and `CLAUDE.md` copies. ## Default Sections Use only sections that add non-obvious value. ````markdown # Agent Instructions ## Package Manager - Use **pnpm**: `pnpm install` ## Commands | Task | Command | |------|---------| | Test file | `pnpm vitest run path/to/file.test.ts` | | Lint file | `pnpm eslint path/to/file.ts` | ## External References | Need | File | |------|------| | Setup | `CONTRIBUTING.md` | | Architecture | `docs/architecture.md` | | Security policy | `SECURITY.md` | ## Key Conventions - Generated files: update with `pnpm generate`; do not edit by hand. ## Commit Attribution AI commits MUST include: ``` Co-Authored-By: (the agent's name and attribution byline) ``` ```` ## Writing Rules - Use headings, bullets, and tables; avoid paragraphs. - Use repo-relative paths; avoid vague references like "see docs". - Reference existing docs/specs/policies instead of copying them. - List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist. - Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists. - Put commands in tables when there is more than one. - Keep one rule per bullet. - Keep rationale out unless it prevents a likely mistake. - Do not restate linter, formatter, or typechecker config. - Do not list installed skills or plugins. - Do not include generic quality slogans. ## External Reference Rules Good: ```markdown ## External References | Need | File | |------|------| | API contract | `docs/api.md` | | Release process | `docs/releasing.md` | ``` ## Anti-Patterns - welcome text, intros, conclusions, or pleasantries - long prose explaining why instructions matter - duplicated content from `README.md`, `CONTRIBUTING.md`, or policy docs - project-wide commands when file-scoped commands are available - nested `AGENTS.md` files that repeat root instructions