agentleFS
Sign inStart free
chocomyongchocomyong/harness-kit/templates/AGENTS.md

harness-kit / templates

AGENTS.md2 starsChanged 28 days agoMITView on GitHub

Budget: keep this file under ~150 lines. It is loaded on every session, and longer always-loaded rules cost context and lower adherence. This file holds RULES ("do X, never Y"). FACTS about the repo (layout, entry points, ports, names) live in docs/REPO_MAP.md and are read on demand - see section 1. Test for every line: "would a capable engineer who does not know this repo's history get this wrong without it?" If not, cut it. --> Every rule here exists…

  • 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 repository6 other files it gives its agents.

The file

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

9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

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

    Test for every line: "would a capable engineer who does not know this repo's history get this wrong without it?" If not, cut it.

    line 12
  2. Distinctive:

    Every rule here exists because breaking it cost someone real time.

    line 25
  3. Distinctive:

    No such thing? Delete the bold line and keep the safe default below.

    line 36
  4. Distinctive:

    Structure: - read the relevant code and docs now.

    line 62
  5. Distinctive:

    Ask first: only for: anything section 0 covers, destructive or irreversible operations, sending anything outside the machine, and requests …

    line 81
  6. Distinctive:

    When you ask, ask once, with your recommendation, and do the parts that do not depend on the answer.

    line 83
  7. Distinctive:

    Author is not verifier: after a batch of changes or an autonomous loop, an independent reviewer (fresh session or subagent) reads the full …

    line 99
  8. Very specific:

    Every claim about the code comes from something read or run this session.

    line 110
  9. Distinctive:

    Do not write counts, line numbers, or versions into docs - they rot and get quoted.

    line 113

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

AGENTS.md - operating rules for coding agents in this repo

<!-- harness-kit template v0.2. HTML comments like this one are guidance for the human and the bootstrapping agent; Claude Code strips them before loading, and every engine can ignore them. Delete them once the canon is filled. Budget: keep this file under ~150 lines. It is loaded on every session, and longer always-loaded rules cost context and lower adherence. This file holds RULES ("do X, never Y"). FACTS about the repo (layout, entry points, ports, names) live in docs/REPO_MAP.md and are read on demand - see section 1. Test for every line: "would a capable engineer who does not know this repo's history get this wrong without it?" If not, cut it. --><!-- Agent bootstrap - while <PLACEHOLDER> marks remain, filling them is your first task. Survey the repo (tree, git log, existing docs) and propose measured values: every value comes from something you read in THIS repo. Propose top-invariant candidates when you see them, but a human confirms section 0 - never invent it. Show the diff before saving. Until filled, follow the safe default in section 0. -->

Every rule here exists because breaking it cost someone real time. A rule or guard you do not understand is load-bearing until proven otherwise: ask before "cleaning it up".

0. Top invariant

<INVARIANT - the one thing whose loss is unrecoverable>. Before any work that could touch it, <the guard you confirm first>.

<!-- Examples: a production database never overwritten from a dev copy; a payment path that never runs in tests; a dataset that only syncs one way. No such thing? Delete the bold line and keep the safe default below. -->

Safe default (always on, filled or not): treat every destructive or irreversible operation - deleting files, dropping schema, bulk overwrite, force-push, sending data off the machine - as possibly touching an invariant you have not found yet. Name what could be lost, then ask.

1. Where things are

This file is rules only. Read these when the task needs them:

You needReadWhen
layout, entry points, live vs retired, informal namesdocs/REPO_MAP.mdbefore scoping any change
how to reason, verify, and get unstuckWORK_PROTOCOL.mdat the start of substantial work
why a weird-looking thing is that wayPATTERNS.md (index first)before planning a change
<other doc><path><trigger>

One fact lives in one place. When you move a fact, delete the old copy and leave a link - two copies age at different speeds and contradict.

2. Work loop - leave the repo better than you found it

Substantial work (features, fixes, refactors, deploys) runs this loop. Questions and trivial one-line edits skip it.

  1. Structure - read the relevant code and docs now; do not work from memory.
  2. Context - git log, the changelog, and PATTERNS.md tell you why it is shaped this way.
  3. Plan - change, blast radius (shared code, data, deploy), risk. Write the done-check first, as something runnable. If it involves a measurement, also write where the sample comes from, the noise floor, and whether a higher number is actually better. A check written after seeing the result is not a check.
  4. Execute - minimal change; <version bump + changelog> ride in the same commit.
  5. Verify - answer three questions with evidence (WORK_PROTOCOL section 4): did it run, would it fail if the change were wrong, is it measured in the right place.
  6. Record - the adjacent defect or tacit rule you found goes into PATTERNS.md or the changelog, and if cheap, harden one thing now.

Done means both: the request is handled, and the repo is better than before.

3. Autonomy - act, or ask

  • Decide and report for reversible, routine choices: which file to read, running tests, delegating a search, committing finished work, picking between equivalent options. "Shall I?" on a reversible step wastes the human's turn.
  • Ask first only for: anything section 0 covers, destructive or irreversible operations, sending anything outside the machine, and requests that stay ambiguous after you read the code.
  • When you ask, ask once, with your recommendation, and do the parts that do not depend on the answer.

4. Commits and changes

  • Format: <your format, e.g. [vX.Y.Z] area: summary>. Never omit <required parts>.
  • Companion files: a behavior change updates <CHANGELOG> in the same commit; a schema or interface change updates <the interface doc> in the same commit.
  • Engine trailer: agent-authored commits end with Co-Authored-By: <engine> <email>.
  • Destructive commands name their target (dataset, table, path, region) explicitly - never lean on a tool's default. Force-push, hard reset, and branch deletion need a human yes.
  • Shared working tree: another session's commit can absorb your uncommitted edits, and commit -a or --amend can swallow its staged files. git add <path> does not prevent this. Right before committing, read git diff --staged --name-only in full (or git commit -- <paths>). To recover, git reset --soft HEAD~1; never --hard, never force-push.
  • Parallel subagents: split work by non-overlapping paths; children do not run git; the parent reviews and commits.
  • Author is not verifier: after a batch of changes or an autonomous loop, an independent reviewer (fresh session or subagent) reads the full diff before push.

5. Pattern registry

PATTERNS.md holds one 4-block card per lesson (symptom / debug path / root cause / prevention rule). Before planning a change, read its index, open the cards for your area, and name them in the plan. Do not copy a card's rule into this file - link it.

6. Facts and claims

  • Every claim about the code comes from something read or run this session. No file:line, no claim.
  • "X does not exist / is dead / has no backup" needs an exhaustive search (other names, moved code, places your tools do not show). Otherwise say "could not confirm" (WORK_PROTOCOL section 7).
  • Do not write counts, line numbers, or versions into docs - they rot and get quoted. Count at the point of use. A fact that must be written carries its date and the command that re-measures it.
  • External formats (API fields, webhook payloads, CLI flags) get one verification run before they go into code. If you must assume, mark it UNVERIFIED: in the code.
  • Can a hook, test, or linter enforce a rule? Then enforce it there, and do not restate it here.

7. Reporting and style

  • Result first, then reasoning. Failures are reported with their actual output.
  • "Verified: <command> -> <observed output>." Could not run it? Say "unverified".
  • <house style: language, emoji policy, forbidden phrases>.

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