harness-deepseek-harness
AGENTS.md2 starsChanged 40 days agoMITView on GitHub
This file defines the document tiers, writing rules, and the documentation-gate budgets; docs/i18n/README.md owns the bilingual pairing contract itself. Use documenting for placement and validation, and editing-prose for required coverage and editorial judgment. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only…
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 32,671 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 repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/rfcs/AGENTS.mdAGENTS.md
- .agents/rfcs/archived/AGENTS.mdAGENTS.md
- .agents/rfcs/implemented/AGENTS.mdAGENTS.md
- archiving-rfcsSkill
- documentingSkill
- editing-proseSkill
- finding-simplificationsSkill
- merging-stacked-prsSkill
- pushingSkill
- reviewingSkill
- translating-docsSkill
- trimming-cot-leakageSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Distinctive: line 11
Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced.
- Very specific: line 35
Every in-scope document is an English + Simplified Chinese pair — foo.md, foo.zh.md, and the foo.i18n.yaml record in the same directory — …
- Distinctive: line 44
Write directly: name actors and facts instead of metaphorical placeholders.
- Distinctive: line 54
When the gate goes red:
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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.
Files
AGENTS.md — The documentation standard
This file defines the document tiers, writing rules, and the documentation-gate budgets; docs/i18n/README.md owns the bilingual pairing contract itself. Use documenting for placement and validation, and editing-prose for required coverage and editorial judgment.
Document structure
A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject.
Classify every in-scope document as a tutorial or a reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
The tier taxonomy: one home per fact
Each fact has one home: the tier whose job it is; elsewhere, link there.
| Tier | Job | Does NOT belong there |
Root AGENTS.md | Standing orders an agent needs in context in every session, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
Subtree AGENTS.md (docs/, .agents/rfcs/) | Orders specific to that subtree | Repo-wide rules the root file already carries |
| architecture.md | Ordered map: domains, the unified CLI, and where new behavior goes; read before changing src/hdsh/ | Per-domain detail (→ the owning document), decision rationale (→ RFCs), implementation-status annotations |
| development.md | Contributor setup, daily workflow, Git integrations, and a summary of CI; a bilingual pair under the i18n contract | Runtime/version rationale (→ RFCs), check-by-check lists that drift from the command inventory |
| Community files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, SUPPORT.md) | GitHub-recognized community health files in docs/, maintained as bilingual pairs | Restated rules of the tiers that own them (→ link there instead) |
| ADOPT.md | The consumer-side adoption manual: ordered phases with verify steps and the out-of-git checklist | Internal contributor process (→ development.md), restated contract rules (→ link their homes) |
| cookbook/ | Step-by-step how-tos with observable verify steps | Design rationale (→ the RFC each guide links) |
.agents/rfcs/** | Decision records: the why, what was given up, required verification (rules) | Current-state contracts (→ docs), procedures (→ cookbooks) |
Skills (.agents/skills/) | Reusable workflow instructions | Product and runtime contracts (→ docs or source) |
Placement: rationale → RFCs; procedures → cookbooks; contracts → the owning reference (architecture.md, the i18n README, the RFC rules); standing orders → root AGENTS.md with a rationale link.
Pairing rules
- Every in-scope document is an English + Simplified Chinese pair —
foo.md,foo.zh.md, and thefoo.i18n.yamlrecord in the same directory — under the pairing contract, enforced byuv run hdsh pairing verify. - Instruction files are English-only and exempt from pairing: every
AGENTS.mdand everything under.agents/skills/; never create a.zh.mdor.i18n.yamlfor them. - Pairs update together in one PR: a PR that changes either side updates the other side terminology-guided and re-records with
uv run hdsh pairing record <pair>. - Archived RFC triplets are frozen and outside the pairing corpus (archive policy).
Writing rules
- Current-state prose: document what is, not change history; put change stories in RFCs and commits.
- Concise titles that name their subject.
- Write directly: name actors and facts instead of metaphorical placeholders. Name the exact check, command, type, or behavior instead of a generic label.
- One physical line per prose paragraph, enforced by
uv run hdsh docs wrap; use editor soft-wrap. Code blocks, tables, and list structure keep their formatting. - Cross-reference documents by relative Markdown link, never bare prose or a number, so
uv run hdsh docs linkscan prove every target and#fragmentresolves (rationale). - Standing docs stay under the
wc -wceilings in.hdsh/docs.manifest.json(uv run hdsh docs budgets --list); relocate or condense instead of raising a ceiling. - Files end with exactly one trailing newline.
Wordcount budgets
.hdsh/docs.manifest.json sets standing-doc ceilings; uv run hdsh docs budgets rejects excess or missing files.
When the gate goes red:
- Relocate content that belongs in another tier; leave a one-line link if needed.
- Condense content that belongs here but can be shorter.
- Raise the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Review governs unbudgeted documents.
The slop checklist
Hunt these in any document:
- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an RFC when needed.
- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and the command inventory carry it.
- Hand-restated catalogs, inventories of files, gates, or tests when source or a gate output is authoritative.
- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
- Rationale repeated beside sibling methods instead of once at the owning capability.
- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
- Spec-speak in implemented RFCs: "should", migration plans, acceptance checklists. An implemented RFC describes what is.
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.

