agentleFS
nada-rnada-r/agent-template/CLAUDE.md

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).

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
  1. Distinctive:

    Only genuinely Claude-only behavior lives here.

    line 8
  2. Very specific:

    After a series of edits, run make check and show the output - evidence, not assertion.

    line 14
  3. Very specific:

    Before declaring a task done, use the verifier subagent.

    line 15
  4. Distinctive:

    Use subagents for high-volume output (full test-suite runs, large searches) to keep this context clean.

    line 16
  5. Distinctive:

    After ~3 failed attempts at the same fix: stop, record the attempts in ERRORS.md, question the approach, and escalate to me.

    line 17
  6. Distinctive:

    Before debugging anything that feels familiar, read ERRORS.md first.

    line 22
  7. Very specific:

    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 …

    line 23
  8. Distinctive:

    NEVER guess external facts (decimals, indices, rate limits, API shapes).

    line 24
  9. Distinctive:

    When I correct you, or a review catches something you should have known: add one line to AGENTS.md (shared rules) or this file …

    line 32
  10. Very specific:

    If a rule must hold 100% of the time, don't write prose - add a hook in .claude/settings.json instead.

    line 33

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

@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 to SPEC.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 check and show the output - evidence, not assertion.
  • Before declaring a task done, use the verifier subagent. For review, use code-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) and ERRORS.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-memory walks 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-base skill 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.json instead.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.