Teaching Agents Living Rules: One Home Per Fact

This is the third essay in the 【DSH Engineering Philosophy】 series. The first established that judicial arbitration belongs to deterministic machines; the second showed how to build durable decision memory via ADRs. This installment tackles the question every engineer asks when transitioning to AI-assisted full-stack development: Why does an agent repeatedly ignore or violate a 5,000-word team engineering guide? The answer is not that prompts are too brief, but that the way we write and organize documentation breaks how agents consume context.

If the previous essays inspired you to sit down and write a thorough repository guide, you have likely run into this exact wall:

To prevent your agent from refactoring outside its scope or touching unrelated dependencies, you pack every rule into an exhaustive 5,000-word REPO_GUIDE.md. The agent still routinely strays. Worse, because its context window is now crowded with procedural prose, it begins tripping over basic type assertions it previously handled with ease.

The failure is not model intelligence. It is a fundamental mismatch: human documentation is meant to be opened on demand; agent rules are meant to be loaded automatically into context. A 5,000-word manual is a reference book for a human, but a wall of noise for an agent.

DeepSeek Harness resolves this not by making guides shorter, but by erecting a strict Tier Taxonomy: every fact has exactly one home, and the agent loads only the few lines it actually needs.

I. First Principle: P3 Carrier Separation

In the methodology underpinning the deepseek-harness repository, this practice rests on P3, the Carrier Separation Principle:

Distinct kinds of information must occupy distinct carriers and never be co-mingled.

Under P3, engineering knowledge cleanly splits into four categories, each with a designated carrier:

Mixing these four into a monolithic "developer guide" is why documentation rots: rationale is mistaken for current status, procedural tutorials are mistaken for constraints, and constraints are drafted as soft suggestions. Inside a 5,000-word file, an agent cannot distinguish standing law from historical narrative.

II. Carrier Separation: AGENTS.md vs README

On top of P3, DSH introduces a second split: who reads the document:

• AGENTS.md (root, subtree, and per-package): The carrier for automated agent consumption. When an agent processes any file, the AGENTS.md files in that directory and every ancestor directory automatically merge into its context window. Standing orders, triggers, and doc standards belong here. If they live anywhere else, the agent will never read them unless explicitly instructed.
• README (root and per-package): The human-facing contract. It hosts configuration, semantics, limitations, and Model Experience. Humans read it; agents inspect it only when explicitly requested. It does not host standing governance rules.

Summed up in one sentence:

Put rules you want the agent to see on every turn into AGENTS.md; put contracts humans inspect into README. Never mix them.

Putting "do not modify unrelated files" into a package README protects nothing: humans might nod, but the agent never sees it.

flowchart TD
    subgraph AgentContext["Agent Context Window"]
        A1[Ancestor AGENTS.md] -->|Auto-merged| C[Active Context]
        A2[Current AGENTS.md] -->|Auto-merged| C
    end
    subgraph HumanRead["Human-Facing Contracts"]
        B1[Root README] --> D[Human On-Demand]
        B2[Package README] --> D
    end
    E[Governance Rules] -->|Exclusive Home| A1
    E -->|Exclusive Home| A2
    F[Config & Semantics] -->|Exclusive Home| B2
    C --> G[Standing Orders<br/>Every Session]
    D --> H[Lookups & Details<br/>On Request]

III. The 12-Tier Taxonomy: One Home Per Fact

With reading audiences decoupled, DSH formalizes a 12-tier matrix mapping every category of knowledge to its home:

Placement rule: bug → postmortem; why → note; procedure → cookbook; types → subsystems; package contract → README; standing orders → root AGENTS.md.

This matrix enforces One Home Per Fact: any rule exists in exactly one authoritative location; everywhere else links to it. Duplicate rules trigger governance alarms because duplicate facts inevitably diverge.

IV. Wordcount Budgets: Doc Inflation Makes Models Dull

Tiering alone is insufficient. DSH enforces an unexpected hard gate: Wordcount Budgets.

scripts/doc-budgets.manifest.json caps word counts for every standing document. If a file breaches its ceiling, pnpm run verify-doc-budgets fails CI with a non-zero exit:

• Root AGENTS.md ≤ 2,080;
• architecture.md ≤ 2,400;
• packages/AGENTS.md ≤ 810; docs/AGENTS.md ≤ 1,430;
• packages/README.md ≤ 994;
• cordis-primer.md ≤ 600; testing.md ≤ 1,300.

When the budget gate fires, the author must follow a strict three-step order:

1. Relocate: move content that belongs to another tier, leaving at most a one-line link;
2. Condense: tighten prose that genuinely belongs here;
3. Raise: increase the ceiling only when genuine scope expansion demands it, justifying the manifest diff in the PR—an artificially tight budget is treated as a bug.

Ceilings are guardrails, not targets. The system mandates keeping at least 5% headroom below the ceiling. The hard truth behind this discipline is clear: no matter how large the context window grows, every word of unneeded documentation degrades an agent's attention on the code it is writing.

V. The Slop Checklist: Cleaning Prose Hygiene

The final line of defense is the Slop Checklist, an editorial filter every document must pass:

• Duplicated rules: same rule in multiple homes (keep one, link the rest);
• History in prose: previously, now, PR links (status rots; history belongs in commits and postmortems);
• Implementation status notes: implemented!, future: (layout and manifests track status);
• Hand-restated inventories: typed catalog tables, test lists (source code is authoritative);
• Reasoning transcripts: step-by-step narratives, proof of obvious branches (keep the contract, delete derivation);
• Paragraph walls: run-on clauses packed with parentheses (split or push down to its tier);
• Emphasis inflation: excessive bold and CAPS (shouting everywhere equals shouting nowhere);
• Spec-speak: using should in implemented notes (implemented describes what is, not what ought to be).

The checklist turns "writing clean docs" from a vague aesthetic ambition into a checklist that can be audited mechanically.

VI. From Principle to Practice: Three Actions for Tomorrow

This system sounds rigorous, but an individual developer can harvest half the value through three straightforward moves:

1. Move standing rules into AGENTS.md: take the three to five non-negotiable rules you expect your agent to follow and write them into root AGENTS.md, one line each, linking out to deeper explanations. The agent will immediately behave more reliably because those rules now enter its context on every turn.
2. Purge your README: treat your README as a clean contract for humans (how to run, how to configure, known limitations), stripping out prompts aimed at the agent.
3. Enforce a word ceiling: set an explicit 500-word limit on your root AGENTS.md. If you want to add a rule, you must condense or delete an existing one.

When every fact has exactly one home, documentation ceases to be noise for the model—it becomes its most dependable compass.

🛠️ Practical Implementation: Documentation tiering and wordcount budgeting are built directly into the scaffolding of the PonyGo AI Coding quality control meta-framework. Through its automated ponygo audit documentation checks, projects gain a baseline for tier governance and anti-entropy from day one. Reference: https://github.com/lanhui100/ponygo