agentleFS
doivamongdoivamong/agent-workbench/CLAUDE.md

agent-workbench

CLAUDE.md2 starsChanged 6 months agoMITView on GitHub

Project instructions for Claude Code (and, via AGENTS.md, other AI coding agents). This file is loaded into context every session, so keep it short and high-signal — link out to detail instead of inlining it. The notes in italics explain why each section earns its place; delete them when you adapt this for your own project. Agent Workbench — a kit of tools + methodology for running an AI coding agent safely and consistently on a long-lived codebase. It is…

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    One session per working tree: Never run two agent/Claude sessions on the same checkout — they race the git index and switch HEAD under each …

    line 47
  2. Distinctive:

    Do not add AI-assistant co-author trailers.

    line 78

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

CLAUDE.md

Project instructions for Claude Code (and, via AGENTS.md, other AI coding agents). This file is loaded into context every session, so keep it short and high-signal — link out to detail instead of inlining it. The notes in italics explain why each section earns its place; delete them when you adapt this for your own project.

What this project is

Agent Workbench — a kit of tools + methodology for running an AI coding agent safely and consistently on a long-lived codebase. It is the generic layer distilled from a private codebase, shared so whoever needs it skips avoidable mistakes. Why it exists and how it must behave is canonical in PHILOSOPHY.md. The reusable core is stdlib-only. See README.

Lead with one or two sentences. The agent should know what it's working on before any rule.

Golden rules (the few that must never break)

  1. No secrets, identifiers, or absolute machine paths in committed files. The leak scanner gates this (python tools/leak_scan.py . --entropy --fail-on-find --respect-gitignore) — but a green scan is not proof. It misses a brand identifier used as a code namespace (a CSS class prefix like acme-, a --brand-* token), paid-product references, and example paths. When committing ported or branded content, grep the source's own namespace yourself first.
  2. The reusable core stays stdlib-only (scripts/, tools/, .claude/hooks/). Dependencies live in examples/ and tests.
  3. Every tool ships a runnable examples/ entry and has tests.
  4. Best-fit, honest about limits, not gospel — every tool states what it does not do. The four tenets are canonical in PHILOSOPHY.md; this kit is one developer's context.

Keep this list to ~5 items. If everything is a golden rule, nothing is. Put the rest in path-scoped rule files (see .claude/rules/).

How to work here

  • Plan before non-trivial changes, then implement, then test, then review. The example skills in .claude/skills/ encode this.
  • Verify against ground truth, don't trust framing — run the demo/tests and read the output; check the load-bearing claim against the source. A framing you didn't author (a tool/skill's description, an external audit) is just an unchecked claim — right on the facts ≠ right on cause / severity / fix.
  • In a linked worktree, sync before you build — agent worktrees drift behind origin/main while parallel sessions merge PRs. Before implementing a fix, git fetch and check git rev-list --left-right --count origin/main...HEAD plus whether your target files already changed upstream; fast-forward/rebase first, and if a merged PR already did the work, switch to review instead of re-doing it. (Verify the work isn't already done — not just that a claim is true.)
  • One session per working tree. Never run two agent/Claude sessions on the same checkout — they race the git index and switch HEAD under each other (silently sweeping uncommitted work into the wrong commit, or mis-basing a new branch). Give each concurrent session its own git worktree (commit via pre-commit run --all-files and audit git config --local --list after — committing from a linked worktree can leak an absolute GIT_DIR and corrupt the shared .git/config), or a separate clone for full isolation.
  • When a safety hook blocks an action, relay it in plain language — tell the user what was stopped and why, and offer a safe next step; never suggest re-running it outside the guard (to them or to yourself). A hook's deny reason is shown to the agent, not directly to the user.
  • Verify a push against ground truth before merging — gh's post-push reads lag the real state (a --watch false-greens before CI registers; mergeable false-conflicts before GitHub recomputes). Watch the run by id (gh run watch <id> --exit-status, conclusion success) and confirm mergeability via git log HEAD..origin/main + git merge-tree — not the just-pushed PR fields. Detail in docs/workflow.md.
  • Match the surrounding code's style rather than importing your own conventions.

Project map

AreaPath
Safety hooks (+ how they're wired).claude/hooks/, .claude/settings.json
Reusable toolstools/, scripts/
Repo-operation tools (stdlib, not installed)ops/ — dashboard control, LAN/autostart setup, release pack, tree snapshot
Skill system.claude/skills/README.md
Memory systemmemory/README.md
Teststests/

Commit conventions

  • Conventional-commit style summary (feat:, fix:, docs:, chore:, test:).
  • Imperative mood, explain why in the body when it isn't obvious.
  • Do not add AI-assistant co-author trailers.

Adapt this file: replace the project description, golden rules, and map with your own. The shape — short always-loaded core + links to detail — is what keeps an agent consistent over months without paying a huge context cost every session.

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.