claude-harness
CLAUDE.md0 starsChanged 6 months agoMITView on GitHub
Local additions: section 3 (Read Before You Edit), section 6 (Verify Before Claiming Done), section 7 (Recover, Don't Escalate), and the entire "Harness Routing" section. --> Default working principles for any repo that uses this harness. Tradeoff: Caution is the default; speed second. Skip these for trivial or one-line tasks. Surface assumptions and ambiguity; don't paper over them. Before implementing: - If you're not sure what's being asked, say so before writing code. - If two interpretations are reasonable, name…
- Deletes or force-pushes
In this repository18 other files it gives its agents.
- audit-docs-semanticSkill
- audit-docsSkill
- audit-harness-coverageSkill
- budget-statusSkill
- cavemanSkill
- configurationSkill
- critic-reviewSkill
- doc-patternSkill
- error-taxonomySkill
- grill-meSkill
- grill-with-docsSkill
- new-docSkill
- python-failure-modesSkill
- review-changesSkill
- review-docSkill
- rust-failure-modesSkill
- verification-before-completionSkill
- zoom-outSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
26 rules. About 0 are common, 25 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 13
Default working principles for any repo that uses this harness.
- Distinctive: line 22
If you're not sure what's being asked, say so before writing code.
- Distinctive: line 23
If two interpretations are reasonable, name both and ask which.
- Distinctive: line 24
If a simpler approach exists, say so.
- Distinctive: line 25
If the request looks contradictory or underspecified, stop.
- Distinctive: line 32
No abstractions until two concrete callers exist.
- Distinctive: line 33
No try/catch for failure modes that cannot occur.
- Distinctive: line 34
No configurability for a single caller.
- Distinctive: line 35
If 200 lines could be 50 with the same behavior, write the 50.
- Distinctive: line 37
Ask yourself: "Would a senior engineer reading this diff say it's overbuilt?" If yes, simplify.
- Distinctive: line 43
When the file is unfamiliar:
- Distinctive: line 44
Read the file end-to-end if it's small.
- Distinctive: line 45
Look at neighboring functions and callers — your edit may break their assumptions.
- Distinctive: line 47
Read the test file alongside the source — tests reveal intent.
- Distinctive: line 55
When modifying existing code:
- Distinctive: line 56
Don't reformat / rename / refactor adjacent code.
- Distinctive: line 57
Don't "tidy up" things that aren't broken.
- Distinctive: line 58
If you spot dead code, mention it — don't delete without being asked.
- Distinctive: line 60
When your edits orphan something:
- Distinctive: line 61
Remove imports and variables your changes made dead.
- Distinctive: line 62
Don't touch pre-existing dead code.
- Distinctive: line 90
If you can't verify (no test exists, dependency unavailable), say so explicitly rather than assuming the change is correct.
- Distinctive: line 96
When you hit something you didn't create — a failing build, an unfamiliar branch, a lock file, a config that disagrees with the docs:
- Very specific: line 98
Don't reach for rm -rf, git reset --hard, --force, or --no-verify to "make the problem go away."
- Distinctive: line 101
When in doubt: ask. The cost of pausing to confirm is low.
- Distinctive: line 111
When you need a tool, look here first — don't reinvent inline.
≈ “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
<!--
Sections 1–7 below adapt and extend the four-principle structure from
"Karpathy-Inspired Claude Code Guidelines" by Forrest Chang (MIT, per README):
https://github.com/forrestchang/andrej-karpathy-skills
Local additions: section 3 (Read Before You Edit), section 6 (Verify Before
Claiming Done), section 7 (Recover, Don't Escalate), and the entire
"Harness Routing" section.
-->CLAUDE.md
Default working principles for any repo that uses this harness.
Tradeoff: Caution is the default; speed second. Skip these for trivial or one-line tasks.
1. Pause Before You Type
Surface assumptions and ambiguity; don't paper over them.
Before implementing:
- If you're not sure what's being asked, say so before writing code.
- If two interpretations are reasonable, name both and ask which.
- If a simpler approach exists, say so. Push back when it's the right call.
- If the request looks contradictory or underspecified, stop. Don't guess.
2. Minimum That Works
Write only what the request needs. Speculative work is debt.
- No "flexibility" you weren't asked for.
- No abstractions until two concrete callers exist.
- No try/catch for failure modes that cannot occur.
- No configurability for a single caller.
- If 200 lines could be 50 with the same behavior, write the 50.
Ask yourself: "Would a senior engineer reading this diff say it's overbuilt?" If yes, simplify.
3. Read Before You Edit
Understand the surrounding context before changing anything.
When the file is unfamiliar:
- Read the file end-to-end if it's small. Skim heading-level if it's large.
- Look at neighboring functions and callers — your edit may break their assumptions.
- Match the existing style; don't introduce a different idiom.
- Read the test file alongside the source — tests reveal intent.
The test: every change should make sense to someone who only read the existing code, not just your diff.
4. Edit Narrowly
Every changed line should map to the user's request.
When modifying existing code:
- Don't reformat / rename / refactor adjacent code.
- Don't "tidy up" things that aren't broken.
- If you spot dead code, mention it — don't delete without being asked.
When your edits orphan something:
- Remove imports and variables your changes made dead.
- Don't touch pre-existing dead code; that's a separate cleanup.
5. Define Done Before Starting
Turn a task into a verifiable check before writing code.
Restate the request as a concrete success condition before you write any code:
- "Add a feature flag" → assertions covering both branches pass; default branch unchanged behavior.
- "Investigate a perf regression" → a benchmark captures the regression numerically; optimize until the target metric returns to baseline.
- "Migrate a schema field" → tests pass on old shape, the migration runs, tests pass on new shape — both green at the same commit.
For multi-step tasks, write the plan first:
1. <step> · check: <how you'll know it worked>
2. <step> · check: <how you'll know it worked>A concrete check lets you self-loop without re-asking. A vague target like "make it work" forces a clarification round mid-task.
6. Verify Before Claiming Done
Don't say "fixed" until you've actually run it.
- Made a code change? Run the test or build. Did it pass?
- Wrote a function? Call it with the inputs that matter, including edge cases.
- Edited a config? Restart whatever consumes it.
- Distinguish "I made the change" from "the change works."
If you can't verify (no test exists, dependency unavailable), say so explicitly rather than assuming the change is correct.
7. Recover, Don't Escalate
On unexpected state, investigate before destroying.
When you hit something you didn't create — a failing build, an unfamiliar branch, a lock file, a config that disagrees with the docs:
- Investigate the cause first. Unexpected state usually has a reason.
- Don't reach for
rm -rf,git reset --hard,--force, or--no-verifyto "make the problem go away." - Destructive shortcuts hide bugs and often delete the user's in-progress work.
When in doubt: ask. The cost of pausing to confirm is low; the cost of an unwanted destructive action can be very high.
Signs these defaults are landing: diffs touch only the relevant lines; "fixed" claims survive verification; ambiguous requests surface as questions before code, not after; unexpected state gets investigated, not erased.
Harness Routing
When you need a tool, look here first — don't reinvent inline.
- Subagents at
.claude/agents/— single-contract specialists with fresh context windows. Invoke via theAgenttool. - Skills at
.claude/skills/— slash-invocable workflows. The SessionStartmeta-indexhook prints the current catalogue at session start. - Hooks at
.claude/hooks/, wired insettings.json— block at write time (secret-guard,tdd-check), at PR creation (pr-create-gate), or surface session-start context. Hooks block — if one stops you, fix the root cause rather than bypassing. - Rules at
.claude/rules/— LLM-authoring failure-mode catalogues, auto-loaded when relevant skills fire. - Methodology at
docs/harness/— principles (P1–P12), architecture, doc-pattern matrix, behavior-verification, and component PRD+SPEC pairs. Readprinciples.mdbefore designing any new harness component.
The full catalogue with per-skill descriptions lives in README.md. Read each SKILL.md / agent.md frontmatter before relying on its guarantees.
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.

