The Harness of the Agent Harness

When I wrote A Tale of Two Harnesses, most of my attention went to the obvious difference between Pi and DeepSeek Harness (DSH). But after spending more time inside the DSH repository, I found something more interesting than the harness itself: the documentation system around it. Even calling it “documentation” probably does not capture what DeepSeek has built.

What Caught My Eye

What pulled me deeper into DSH was not an architecture document or a particularly clever abstraction. It was the Git history. The commit graph looked almost absurd: dozens of parallel lines, repeated synchronization merges, and multiple streams of work advancing at the same time. It was less like the history of a conventional repository and more like a map of a system coordinating many agents at once.

Then I opened GitHub’s commit-activity view, and the scale was staggering. Just look at it. 3,646 commits in a week! How does a repository handle work at that pace without losing track of its architecture or the thinking behind it? And all of this is happening in a repo with just over 20 contributors.

That question led me past the code and into the repository’s documentation system. The more I explored it, the more the dense Git history began to make sense: DSH is not relying on traditional software engineering tools to keep all of that insane amount of parallel work sustainable and understandable. And remember: this is the team reaching for the stars and beyond.

Not Just Docs

Most repositories have documentation because software needs explanation. There is usually a README, perhaps an architecture document, some API references, and a handful of guides. As the project grows, the documentation grows with it, often unevenly: some pages become stale, others duplicate the code, and important design decisions disappear into old pull requests.

DSH handles the problem differently by giving each kind of written knowledge a specific job. Architecture documents explain how the major pieces fit together, subsystem docs describe individual concepts and contracts, package READMEs keep information close to the code, cookbooks walk through recurring engineering tasks, and generated catalogs pull facts directly from source code. The repository also includes two less common categories—Agent Notes and postmortems—so this feels like more than a well-documented project. It feels like an external memory system built around the codebase.

AGENTS.md: The Control Plane

Start with AGENTS.md. These files are not documentation in the usual sense; they are instructions for the coding agent working inside the repository. The root file lays out repository-wide rules for architecture, development commands, testing, documentation, package conventions, and what an agent should or should not change. Individual parts of the repository can then add more focused instructions of their own.

Conceptually, it looks like this:

                       AGENTS.md
                           │
                  repository rules
                           │
             ┌─────────────┼─────────────┐
             │             │             │
             ▼             ▼             ▼
       packages/       docs/         notes/
       AGENTS.md       AGENTS.md     AGENTS.md

The important part is what DeepSeek avoids: a child AGENTS.md should not copy the parent. It only adds rules that matter in its own area. That sounds small, but it reflects an idea that shows up across the repository: every piece of knowledge should have one home.

For an agent, this creates context in layers. It gets the global rules first, then more local ones as it moves deeper into the codebase. Instead of putting everything into one enormous system prompt, the repository itself becomes part of the prompt.

Architecture Explains Relationships

Traditional architecture docs still exist, but DeepSeek gives them one main job: explain how the system fits together. They cover composition, core packages, the agent loop, capability boundaries, lifecycle, and other system-wide relationships without trying to become a giant encyclopedia of everything.

Architecture documents in large projects often collect everything—APIs, implementation details, old reasoning, workarounds, and more—until nobody knows which parts to trust. DSH puts those other kinds of knowledge elsewhere. Architecture tells you how the pieces relate; it does not need to tell you everything about every piece.

Subsystem Docs Explain What Things Mean

Below architecture is a more detailed subsystem layer, with dedicated documents for sessions, persistence, permissions, and other internal concepts. This creates a useful split: if I want to understand how session persistence fits into the overall agent lifecycle, I should start with architecture; if I want to know what a session projection is and exactly how it behaves, I should go to the subsystem docs.

This distinction matters more than it might seem for coding agents. An LLM searching a repository does not always need more information; it needs the right kind of information for the question it is asking. DeepSeek seems to be designing its docs with that search problem in mind.

Some Documentation Is Compiled From Code

Another category looks like documentation but works more like a build artifact. DSH generates configuration catalogs, tool catalogs, persistence references, and parts of its API docs from the code or schemas that actually define them. That changes where the truth comes from:

Code / schema
     │
     ▼
 Generator
     │
     ▼
Reference documentation

People are not expected to keep those inventories in sync by hand; CI can check whether the generated output is still current. This solves one of the oldest documentation problems in software engineering: copying facts from code into Markdown and hoping someone remembers to update both. DeepSeek’s answer is simple: don’t maintain the same fact twice; if it can be derived from code, derive it.

Package READMEs Keep Knowledge Local

Package-level README files form another layer. They cover what someone working directly with a package needs to know about its configuration, behavior, extension points, semantics, and limitations. Keeping that information nearby matters: an agent editing one package should not have to read the architecture of the entire harness just to understand a local contract. The repository can give it a smaller slice of context:

package/
    src/
    tests/
    README.md

The README becomes a bridge between source code and higher-level architecture. It is a compact way to give the agent the context it needs.

Cookbooks Store Procedures

Cookbooks answer another kind of question: How do I actually do this? They explain how to add a tool, integrate an LLM adapter, or introduce another package. A cookbook is deliberately step-by-step, which gives DeepSeek a useful split: cookbooks explain how, while decision records explain why. That brings us to one of the most interesting parts of the repository.

Agent Notes: The Repository’s Long-Term Memory

For non-trivial changes, DSH requires an Agent Note. This is not supposed to be a long description of the implementation. Its job is to save the reasoning that would otherwise disappear after a pull request is merged.

A typical note captures things like:

• the problem
• the decision
• alternatives considered
• consequences or tradeoffs

Notes are organized by status and type. A decision may be proposed, implemented, rejected, or archived, and it may cover architecture, a feature, simplification, testing, process, or a bug fix. This lets the repository remember something source code usually cannot tell you: Why is the system like this instead of some apparently simpler alternative?

That question is especially important with coding agents. Imagine an agent finding an awkward-looking abstraction and deciding, without any history, I can simplify this. Maybe three engineers already tried that six months ago and learned that it broke an important extension boundary. Maybe the current design looks awkward because it protects against a failure that is hard to see from one small part of the code.

Code does not naturally preserve this history. Pull requests do, but they are noisy and hard to search. An Agent Note turns that reasoning into a durable record—a kind of long-term memory for the codebase.

Postmortems Store Scar Tissue

Postmortems have a different job. An Agent Note says, We chose X because of Y, while a postmortem says, We thought the system would behave like X. It did not. Here is what failed and why our safeguards missed it. A mature system carries two kinds of shared memory: decisions and scars. Design documents preserve the first; production failures create the second.

Most repositories preserve scars informally. Someone remembers an incident, a strange validation check stays in the code, or a comment warns, “do not remove this,” but eventually the original context disappears. DSH saves that context on purpose through postmortems that record not only what broke, but also what guardrail should stop the same kind of failure from coming back. For humans, that is shared memory; for agents, it is something even more useful—a list of tempting mistakes they should not rediscover.

Skills Turn Knowledge Into Behavior

Then there are skills. Instead of just explaining something, they turn recurring engineering tasks into workflows an agent can follow. Translation maintenance can be a skill, as can documentation standards, archiving decision records, or specialized maintenance work. This is where the line between documentation and execution starts to blur. A traditional repository might contain:

docs/how-to-review-x.md

DSH can instead give the agent a reusable workflow for doing that task. The progression looks something like:

Documentation → tells the agent what to know
AGENTS.md     → tells the agent what rules to follow
Skills        → tell the agent how to perform recurring work

At this point, documentation is no longer just supporting the harness; it is becoming part of the harness.

Why Everything Appears Three Times

While browsing the repository, I noticed another pattern that made the documentation look even bigger. Many files appear in groups like:

architecture.md
architecture.zh.md
architecture.i18n.yaml

At first glance, that looks like three versions of the same document, but it is really two documents and one synchronization record. architecture.md is English, architecture.zh.md is Simplified Chinese, and the .i18n.yaml file records the exact versions of both files when someone last confirmed that they matched. It is less like another translation and more like a lockfile.

Suppose both documents are synchronized:

English v1  ←→  Chinese v1

Then someone changes the English version:

English v2  ←→  Chinese v1

The recorded Git hash no longer matches, so CI can catch something reviewers often miss: the translation may be stale. The Chinese document must then be updated—or at least checked against the change—and the synchronization record refreshed. The .i18n.yaml is not documentation content; it is the machinery that keeps the documentation in sync.

Documentation Without Documentation Slop

There is an obvious danger here: if every meaningful change needs written context, every package has documentation, every important document has two languages, and agents can generate text almost for free, couldn’t the repository drown in Markdown? DeepSeek seems very aware of this. Its rules push back against repeated instructions, play-by-play implementation history, hand-copied catalogs, stale status updates, and duplicated API inventories. Some standing documents even have size limits.

That detail caught my attention because the philosophy is not simply write more documentation. It is closer to preserve more knowledge while repeating fewer words, which is much harder. LLMs make it incredibly cheap to add another page, paragraph, or explanation. The difficult part is deciding what should exist, where it belongs, and what can be deleted because the same fact already has a better home. DSH applies the same discipline to its documentation that it applies to its code.

The chart below shows how all these pieces fit together.

The Difference Between Pi and DSH Runs Deeper

This brings me back to what I still admire about Pi: its restraint. Pi asks a powerful question—How little infrastructure does an intelligent model actually need?—and answers with a small loop, good primitives, clear code, and a strong resistance to unnecessary abstraction.

DSH asks a different question: Once the system gets large, how do we keep an agent from getting lost inside it? Its answer is not just more architecture, but memory outside the model. The code contains implementation, architecture contains relationships, subsystem docs contain concepts, generated references contain facts, Agent Notes contain reasoning, postmortems contain scars, skills contain procedures, and AGENTS.md contains rules. None of these pieces is remarkable on its own; the interesting part is how carefully DeepSeek separates them.

Pi tries to keep the system small enough that reading the code is still enough. DSH seems to assume that beyond a certain scale, it will not be. Instead of asking the agent to rebuild its understanding from source code every time, DeepSeek builds a structured memory around it. That may be the hidden gem inside the DSH repository: the harness is not only the agent loop, the plugins, or the tools. The repository itself is part of the harness.