Make commands exact.
Replace every bracketed command with the command a new contributor can run from the repo root. If the command depends on setup, name that setup in Operational Notes.
Start with a compact skeleton for project facts, hard rules, communication, principles, and enforcement. Then delete anything that does not make your agent more reliable.
# CLAUDE.md
## Project
- Name: [project name]
- Purpose: [one sentence about what this repo ships]
- Primary users: [who depends on this working]
- Stack: [frameworks, runtime, package manager, database]
- Source root: [main app directory]
- Test command: [exact command]
- Build command: [exact command]
- Local run command: [exact command]
## Non-negotiables
- Preserve user work. Do not overwrite unrelated local changes.
- Do not print secrets, tokens, customer data, or private keys.
- Do not run destructive data commands without explicit approval.
- Keep edits scoped to the requested behavior.
- Prefer the existing architecture before adding new abstractions.
- Fix root causes rather than masking failing tests.
- If two materially different fixes fail, stop and report what was tried.
## Language & Style
- Match the surrounding code style and naming.
- Keep comments sparse and useful.
- Use TypeScript types already present in the codebase.
- Avoid broad refactors unless the task requires them.
- Keep user-facing copy direct and concrete.
- Code, comments, and commits stay in English unless requested otherwise.
- Do not introduce new dependencies without a clear reason.
## Operational Notes
- Package manager: [npm/pnpm/yarn/bun]
- Node version: [version or .nvmrc]
- Environment file: [where env vars are documented]
- CI source of truth: [workflow path]
- Formatting command: [exact command]
- Lint command: [exact command]
- Database migration command: [exact command or none]
- Generated files: [paths agents should not hand edit]
- Release branch: [branch or release process]
## Communication
- Start by stating the concrete files or systems being inspected.
- For implementation work, make the smallest complete change.
- Report verification commands and their results.
- When blocked, name the blocker and the next useful choice.
- Do not claim a command passed unless it was run in this session.
- Keep summaries short and focused on behavior changed.
## Principles
- Evidence beats assurance.
- Durable rules belong in code, tests, CI, or this file.
- Repo-specific instructions beat generic agent advice.
- Prefer reversible changes with clear verification.
- Keep the harness short enough that agents can actually use it.
## Enforcement
- Required before handoff: [test command]
- Required before UI handoff: [build or screenshot command]
- Required before release changes: [release checklist command]
- Security-sensitive paths: [paths needing extra review]
- Protected commands: [commands requiring explicit approval]
- If verification cannot run, explain why and name the residual risk.
Replace every bracketed command with the command a new contributor can run from the repo root. If the command depends on setup, name that setup in Operational Notes.
This section is for rules that protect user work, data, releases, or repo integrity. Preferences belong in style sections or local docs.
When a rule can be checked by CI, a hook, or a script, name that mechanism. A prose rule without enforcement is weaker than a failing command.
The template is useful only while it stays current. Remove historical notes, old package-manager references, and migration leftovers as soon as they stop guiding work.
The skeleton is a starting point. AgentLint checks whether the final harness is specific, aligned, enforceable, and current.
Install AgentLint