agentleFS
jukanntennjukanntenn/harness-deepseek-harness/docs/AGENTS.md

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…

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

    Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced.

    line 11
  2. Very specific:

    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 — …

    line 35
  3. Distinctive:

    Write directly: name actors and facts instead of metaphorical placeholders.

    line 44
  4. Distinctive:

    When the gate goes red:

    line 54

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.

TierJobDoes NOT belong there
Root AGENTS.mdStanding orders an agent needs in context in every session, linking its homeStories, worked examples, situational procedures, anything restated from a linked home
Subtree AGENTS.md (docs/, .agents/rfcs/)Orders specific to that subtreeRepo-wide rules the root file already carries
architecture.mdOrdered 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.mdContributor setup, daily workflow, Git integrations, and a summary of CI; a bilingual pair under the i18n contractRuntime/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 pairsRestated rules of the tiers that own them (→ link there instead)
ADOPT.mdThe consumer-side adoption manual: ordered phases with verify steps and the out-of-git checklistInternal contributor process (→ development.md), restated contract rules (→ link their homes)
cookbook/Step-by-step how-tos with observable verify stepsDesign 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 instructionsProduct 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 the foo.i18n.yaml record in the same directory — under the pairing contract, enforced by uv run hdsh pairing verify.
  • Instruction files are English-only and exempt from pairing: every AGENTS.md and everything under .agents/skills/; never create a .zh.md or .i18n.yaml for 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 links can prove every target and #fragment resolves (rationale).
  • Standing docs stay under the wc -w ceilings 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:

  1. Relocate content that belongs in another tier; leave a one-line link if needed.
  2. Condense content that belongs here but can be shorter.
  3. 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.

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.