agent-template
CLAUDE.md0 starsChanged 4 months agoMITView on GitHub
The line above inlines AGENTS.md at session start - Claude Code's @ import. Shared rules live there; only Claude-specific behavior lives below (ADR-0001).
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- knowledge-baseSkill
- llm-cachingSkill
- new-endpointSkill
- security-auditSkill
The file
We split this CLAUDE.md into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Only genuinely Claude-only behavior lives here.
- Very specific: line 14
After a series of edits, run make check and show the output - evidence, not assertion.
- Very specific: line 15
Before declaring a task done, use the verifier subagent.
- Distinctive: line 16
Use subagents for high-volume output (full test-suite runs, large searches) to keep this context clean.
- Distinctive: line 17
After ~3 failed attempts at the same fix: stop, record the attempts in ERRORS.md, question the approach, and escalate to me.
- Distinctive: line 22
Before debugging anything that feels familiar, read ERRORS.md first.
- Very specific: line 23
If MEMORY.md can't hold its ~200-line cap despite pruning (or ERRORS.md outgrows grep), graduate to the SQLite kb - see the knowledge-base …
- Distinctive: line 24
NEVER guess external facts (decimals, indices, rate limits, API shapes).
- Distinctive: line 32
When I correct you, or a review catches something you should have known: add one line to AGENTS.md (shared rules) or this file …
- Very specific: line 33
If a rule must hold 100% of the time, don't write prose - add a hook in .claude/settings.json instead.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
@AGENTS.md
The line above inlines AGENTS.md at session start - Claude Code's @ import. Shared rules live there; only Claude-specific behavior lives below (ADR-0001).
Claude-specific instructions
<!-- AGENTS.md (imported above) is the single source of truth.
Only genuinely Claude-only behavior lives here. Keep this file tiny. -->Workflow
- Non-trivial tasks: Explore → Plan → Code → Commit. Start in plan mode; if you could describe the diff in one sentence, skip the plan.
- Larger features: interview me first (
/interview-spec), write the result toSPEC.md(created on demand - doesn't exist until then), then implement from the spec in a fresh session. - After a series of edits, run
make checkand show the output - evidence, not assertion. - Before declaring a task done, use the
verifiersubagent. For review, usecode-reviewer(fresh context, sees only the diff). - Use subagents for high-volume output (full test-suite runs, large searches) to keep this context clean.
- After ~3 failed attempts at the same fix: stop, record the attempts in ERRORS.md, question the approach, and escalate to me.
Memory protocol
MEMORY.md(context, verified facts, lessons) andERRORS.md(bugs with root causes, failed approaches) are the project's long-term memory. These are the repo-root files, NOT your auto-memory directory. Update them after every significant task -/update-memorywalks through it.- Before debugging anything that feels familiar, read ERRORS.md first.
- If MEMORY.md can't hold its ~200-line cap despite pruning (or ERRORS.md outgrows grep), graduate to the SQLite kb - see the
knowledge-baseskill and ADR-0002. - NEVER guess external facts (decimals, indices, rate limits, API shapes). Verify against the source, then record in MEMORY.md → "Verified facts".
Reporting
- Report progress in plain sentences: what changed, what failed, what comes next. No emoji checkmarks, no "Successfully", no "Perfect", no wall of bullets. Start with three lines; add detail only when it changes the next action.
Self-improvement
- When I correct you, or a review catches something you should have known: add one line to AGENTS.md (shared rules) or this file (Claude-only). Apply the pruning test - budget ~1k tokens per file; when a new model releases, re-prune (smarter models need fewer instructions).
- If a rule must hold 100% of the time, don't write prose - add a hook in
.claude/settings.jsoninstead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

