agentleFS
Sign inStart free
NemesLaszloNemesLaszlo/claude-code-harness/AGENTS.md

claude-code-harness

AGENTS.md1 starsChanged 11 days agoMITView on GitHub

Every task moves through the same six beats. Each beat is backed by a skill in .claude/skills/, and the implementation beats delegate to the agents in .claude/agents/. This file is tool-agnostic (Claude Code, Cursor, Codex and others read AGENTS.md); Claude Code imports it from CLAUDE.md. Drop it into a repo with the .claude/ folder and fill in the repo-specific sections at the bottom. Ship-beat notes: Apply /unslop to anything a person will read before you commit, post, or send it:…

  • Commits and pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. NemesLaszlo/Agent-Collection★ 1100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository16 other files it gives its agents.

The file

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

11 rules. About 0 are common, 6 are distinctive, and 5 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.

  • 5

    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:

    Never commit directly to main.

    line 28
  2. Very specific:

    Scope check: before starting: skim open PRs' changed files (gh pr list, gh pr diff <n> --name-only) and look for uncommitted work in shared …

    line 30
  3. Very specific:

    Never force-push to main, and never plain --force anywhere.

    line 31
  4. Distinctive:

    If a conflict can't be resolved confidently, stop and report instead of guessing.

    line 34
  5. Distinctive:

    Keep changes limited to the assigned task.

    line 40
  6. Distinctive:

    Run the repo's checks (see *Commands and checks* below).

    line 41
  7. Very specific:

    Commit with a clear message, rebase onto the latest origin/main, and rerun the checks.

    line 43
  8. Very specific:

    Run /greploop (--apps for PRs over Greptile's file-count limit) until 5/5 with zero unresolved comments, when Greptile is installed.

    line 46
  9. Distinctive:

    Do not merge the PR unless explicitly instructed.

    line 49
  10. Very specific:

    All endpoints require authorization unless listed in docs/public-endpoints.md

    line 65
  11. Distinctive:

    No direct DbContext access outside the Infrastructure project -->

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.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
AGENTS.md

Agent workflow

Every task moves through the same six beats. Each beat is backed by a skill in .claude/skills/, and the implementation beats delegate to the agents in .claude/agents/. This file is tool-agnostic (Claude Code, Cursor, Codex and others read AGENTS.md); Claude Code imports it from CLAUDE.md. Drop it into a repo with the .claude/ folder and fill in the repo-specific sections at the bottom.

Workflow

#BeatSkillWhat happens
1Isolate/new-featureFresh worktree and branch from origin/main, scope check against open PRs. Never build on main.
2Plan/plan-feature (medium or large work) or /investigate (unknowns first)Feature Planner validates specs, tasks, and the implementation plan. Small, obvious changes skip this beat.
3Build/implement, guided by /code-structureBackend Architect and Frontend Developer execute the plan task by task. Actions own the "why/when", a service layer owns the reusable "how". Capture the before state while reproducing a bug, before fixing it.
4Review/cross-review then /fix-issuesRuns automatically at the end of /implement: fable and opus review independently, findings are merged, consensus items are must-fix.
5Prove/evidence-driven-testingVerify with the repo's checks plus runtime evidence: an annotated recording of the live test session, scripted captures when headless, measured numbers for non-UI work.
6Ship/ship, then /greploop when Greptile is installed, /security-scan before deployChecks, evidence assembly, commit, rebase, push, PR with before/after proof. Loop until Greptile reports 5/5 with zero unresolved comments. Finish by presenting the PR URL.

Ship-beat notes:

  • /before-and-after drives the @vercel/before-and-after CLI. --markdown uploads the pair and prints a PR-ready table; it also accepts existing PNGs, so evidence gathered while developing can be reused.
  • In containers or VMs where Chrome fails with "No usable sandbox", set AGENT_BROWSER_ARGS="--no-sandbox" for the capture.
  • The default upload host (0x0.st) is public. Fine for ordinary UI shots; pass --upload-url or IMAGE_ADAPTER=gist for anything sensitive.

Writing for humans

Apply /unslop to anything a person will read before you commit, post, or send it: commit messages, the PR title and body, README and doc edits, code comments, and the closing reply. It strips AI tells (em dashes, filler, hedging, chatbot phrases, puffery, bold-label lists) and swaps fancy words for plain ones and passive voice for active. Apply it to text you wrote or changed, not to prose you didn't touch.

Multi-agent rules

  • Never commit directly to main.
  • One worktree and one branch per task and per agent. Never reuse or modify another agent's worktree, branch, or uncommitted work.
  • Scope check before starting: skim open PRs' changed files (gh pr list, gh pr diff <n> --name-only) and look for uncommitted work in shared checkouts. On overlap, stop and ask for direction.
  • Never force-push to main, and never plain --force anywhere. Only --force-with-lease, only on your own task branch.
  • Resolve lockfile conflicts by regenerating, never by hand-merging.
  • Worktrees don't isolate shared resources: confirm a dev-server port answers your process before trusting it, and don't run schema experiments against a shared database.
  • If a conflict can't be resolved confidently, stop and report instead of guessing.

Completing a task

/ship runs this list. When shipping by hand:

  1. Keep changes limited to the assigned task.
  2. Run the repo's checks (see Commands and checks below).
  3. Assemble the evidence captured along the way into before/after pairs.
  4. Commit with a clear message, rebase onto the latest origin/main, and rerun the checks.
  5. Push (git push -u origin <branch>; after rebasing an already-pushed branch, --force-with-lease).
  6. Open the PR. The body explains what changed, how it was tested (every claim backed by evidence), before/after proof, and risks or follow-up work. Run the title and body through /unslop before posting.
  7. Run /greploop (--apps for PRs over Greptile's file-count limit) until 5/5 with zero unresolved comments, when Greptile is installed.
  8. End by presenting the PR URL.

Do not merge the PR unless explicitly instructed. Keep the worktree until the PR is merged or closed.

Repo-specific sections

Fill these in when dropping this file into a project. Agents read them to execute the beats.

Commands and checks

<!-- Exact commands, in order. Example: - `dotnet build` and `dotnet test` - `npm run lint` and `npm test` -->

Hard invariants

<!-- Security and architecture rules that must never be broken. Example: - All endpoints require authorization unless listed in docs/public-endpoints.md - No direct DbContext access outside the Infrastructure project -->

Environment quick reference

<!-- Ports, env files, local services, how to seed data. -->

Local test infrastructure

<!-- Stubs, fixtures, fake providers, what cannot be tested locally. -->

Skill sources

SkillSource
plan-feature, implement, cross-review, fix-issues, investigate, review, security-scan, explore, shipthis collection
new-feature, code-structure, evidence-driven-testingadapted from michaelshimeles/skills
before-and-aftervendored from vercel-labs/before-and-after (PolyForm Shield 1.0.0, license in folder)
greploopvendored from greptileai/skills (MIT); frontmatter gains disable-model-invocation: true so only a person starts the push loop, and a local --apps flag covers PRs over Greptile's file-count limit
unslopvendored from cursor/plugins (pstack) (MIT); frontmatter edited upstream-style so agents apply it unprompted

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.

Check your setup, free