agentleFS
junhjangjunhjang/claude-harness/CLAUDE.md

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

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

    Default working principles for any repo that uses this harness.

    line 13
  2. Distinctive:

    If you're not sure what's being asked, say so before writing code.

    line 22
  3. Distinctive:

    If two interpretations are reasonable, name both and ask which.

    line 23
  4. Distinctive:

    If a simpler approach exists, say so.

    line 24
  5. Distinctive:

    If the request looks contradictory or underspecified, stop.

    line 25
  6. Distinctive:

    No abstractions until two concrete callers exist.

    line 32
  7. Distinctive:

    No try/catch for failure modes that cannot occur.

    line 33
  8. Distinctive:

    No configurability for a single caller.

    line 34
  9. Distinctive:

    If 200 lines could be 50 with the same behavior, write the 50.

    line 35
  10. Distinctive:

    Ask yourself: "Would a senior engineer reading this diff say it's overbuilt?" If yes, simplify.

    line 37
  11. Distinctive:

    When the file is unfamiliar:

    line 43
  12. Distinctive:

    Read the file end-to-end if it's small.

    line 44
  13. Distinctive:

    Look at neighboring functions and callers — your edit may break their assumptions.

    line 45
  14. Distinctive:

    Read the test file alongside the source — tests reveal intent.

    line 47
  15. Distinctive:

    When modifying existing code:

    line 55
  16. Distinctive:

    Don't reformat / rename / refactor adjacent code.

    line 56
  17. Distinctive:

    Don't "tidy up" things that aren't broken.

    line 57
  18. Distinctive:

    If you spot dead code, mention it — don't delete without being asked.

    line 58
  19. Distinctive:

    When your edits orphan something:

    line 60
  20. Distinctive:

    Remove imports and variables your changes made dead.

    line 61
  21. Distinctive:

    Don't touch pre-existing dead code.

    line 62
  22. Distinctive:

    If you can't verify (no test exists, dependency unavailable), say so explicitly rather than assuming the change is correct.

    line 90
  23. Distinctive:

    When you hit something you didn't create — a failing build, an unfamiliar branch, a lock file, a config that disagrees with the docs:

    line 96
  24. Very specific:

    Don't reach for rm -rf, git reset --hard, --force, or --no-verify to "make the problem go away."

    line 98
  25. Distinctive:

    When in doubt: ask. The cost of pausing to confirm is low.

    line 101
  26. Distinctive:

    When you need a tool, look here first — don't reinvent inline.

    line 111

≈ “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
<!-- 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-verify to "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 the Agent tool.
  • Skills at .claude/skills/ — slash-invocable workflows. The SessionStart meta-index hook prints the current catalogue at session start.
  • Hooks at .claude/hooks/, wired in settings.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. Read principles.md before 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.

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.