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…
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- awb-config-guardSkill
- awb-cookSkill
- awb-dead-code-auditSkill
- awb-debugSkill
- awb-external-refSkill
- awb-handoverSkill
- awb-install-and-verifySkill
- awb-lessons-captureSkill
- awb-optimizeSkill
- awb-output-guardSkill
- awb-plan-then-codeSkill
- awb-researchSkill
- awb-reviewSkill
- awb-session-closeSkill
- awb-stress-testSkill
- awb-tddSkill
- awb-uninstallSkill
- awb-using-skillsSkill
- awb-verify-docsSkill
- prompt-refinerSkill
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
- Distinctive: line 47
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 …
- Distinctive: line 78
Do not add AI-assistant co-author trailers.
≈ “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
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)
- 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 likeacme-, a--brand-*token), paid-product references, and example paths. When committing ported or branded content, grep the source's own namespace yourself first. - The reusable core stays stdlib-only (
scripts/,tools/,.claude/hooks/). Dependencies live inexamples/and tests. - Every tool ships a runnable
examples/entry and has tests. - 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/mainwhile parallel sessions merge PRs. Before implementing a fix,git fetchand checkgit rev-list --left-right --count origin/main...HEADplus 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 viapre-commit run --all-filesand auditgit config --local --listafter — committing from a linked worktree can leak an absoluteGIT_DIRand 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--watchfalse-greens before CI registers;mergeablefalse-conflicts before GitHub recomputes). Watch the run by id (gh run watch <id> --exit-status, conclusionsuccess) and confirm mergeability viagit log HEAD..origin/main+git merge-tree— not the just-pushed PR fields. Detail indocs/workflow.md. - Match the surrounding code's style rather than importing your own conventions.
Project map
| Area | Path |
| Safety hooks (+ how they're wired) | .claude/hooks/, .claude/settings.json |
| Reusable tools | tools/, scripts/ |
| Repo-operation tools (stdlib, not installed) | ops/ — dashboard control, LAN/autostart setup, release pack, tree snapshot |
| Skill system | .claude/skills/README.md |
| Memory system | memory/README.md |
| Tests | tests/ |
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.
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.

