How to Write Documentation for an AI Coding Agent

Who This Is For

You already use Claude Code, Codex CLI, Cursor, or another AI coding agent to write code. You have noticed that an Agent sometimes performs very well and sometimes behaves inexplicably. The same model is reliable in Project A and reckless in Project B. You suspect that the problem is not the model but the “environment” you give it.

Your suspicion is correct.

In February 2026, OpenAI published an article titled Harness Engineering: Leveraging Codex in an Agent-First World, describing its experience using Codex agents to build a million-line product from scratch. Its central finding was that the bottleneck was never the model’s ability to code, but the absence of structure, tools, and feedback mechanisms. LangChain’s Terminal Bench 2.0 experiment validated the same conclusion. With the same model and only the harness—the environment and constraints—changed, the score jumped from 52.8% to 66.5%, moving from the middle of the leaderboard directly into the top five.

This article focuses on the most important part of that system: project documentation—the Agent’s “eyes” and “map.”

First Principle: If the Agent Cannot See It, It Does Not Exist

Before discussing any specific practice, establish one fundamental understanding.

OpenAI states clearly in its Harness Engineering article that from an Agent’s perspective, any knowledge it cannot access in context does not exist. Knowledge stored in Slack conversations, Google Docs, or a person’s mind is invisible to the Agent unless you deliberately materialize it somewhere the Agent can reach.

The most reliable method is to materialize knowledge in the code repository, where it is versioned, reviewable, and testable. The repository becomes the single source of truth.

This means that if you want an Agent to follow a rule, writing it in Confluence is ineffective; it needs to appear in documentation inside the repository.

The Entry-Point File: Give the Agent a Map, Not an Encyclopedia

The Lesson: Why One Large File Failed

OpenAI’s earliest approach was “one large AGENTS.md” containing every instruction. It predictably failed for three reasons:

1. Context is a scarce resource. A huge instruction file consumes space needed for the task description, code, and relevant documentation, causing the Agent to miss essential constraints or optimize in the wrong direction.
2. When everything is “important,” nothing is important. The Agent degrades from global pattern matching to local pattern matching.
3. A monolithic manual decays immediately. Outdated and current rules become mixed together, and the Agent cannot distinguish them.

The HumanLayer team found another crucial detail. When Claude Code injects CLAUDE.md, it appends a system message stating that the context may or may not be relevant to the task and should not be addressed unless highly relevant. This means that the more irrelevant material CLAUDE.md contains for the current task, the more likely the Agent is to ignore the instructions as a whole.

Best Practice: A Short Entry Point with Progressive Disclosure

OpenAI’s eventual solution was an AGENTS.md of roughly 100 lines that acts as an entry point. It is essentially a map pointing to deeper documentation.

Anthropic’s official documentation recommends the same approach: run /init to create an initial CLAUDE.md, then keep trimming it. It should contain shell commands, coding style, and workflow rules—the persistent context that an Agent cannot infer from the code itself.

The industry consensus is to keep CLAUDE.md or AGENTS.md below 300 lines, and shorter is better. HumanLayer’s own root CLAUDE.md contains fewer than 60 lines.

An entry-point file should include:

• A one-sentence project description and technology stack, including concrete versions: “React 18 + TypeScript + Vite + Tailwind CSS,” not merely “a React project”
• Copy-and-paste build, test, and lint commands, such as npm run test and npm run build
• A project-structure overview, such as “src/ contains application code, tests/ contains tests, and docs/ contains documentation”
• Absolute boundaries, including anything the Agent must never touch, such as secrets, vendor directories, and production configuration
• Navigation links to deeper documents, such as “See docs/architecture.md for architecture”

A good entry-point file should read like the onboarding checklist given to a new employee on their first day, not a compilation of every company policy.

Documentation Layers: OpenAI’s Knowledge-Base Structure

In its Harness Engineering practice, OpenAI organized in-repository documentation into a layered directory structure:

AGENTS.md                 ← Directory index (about 100 lines)
ARCHITECTURE.md            ← Top-level domain map
docs/
├── design-docs/           ← Indexed and validated architecture decisions
├── exec-plans/
│   ├── active/            ← Active execution plans
│   ├── completed/         ← Completed execution plans
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md       ← Automatically generated reference documentation
├── product-specs/         ← Product specifications
├── references/            ← External references
└── ...

This structure embodies several important design principles:

1. Progressive Disclosure. The Agent starts from a small, stable entry point and is told where to look next instead of being overwhelmed with all information at once. In OpenAI’s words, active plans, completed plans, and known technical debt are all versioned and live together in the repository, allowing the Agent to work without relying on external context.

2. Execution plans are also documentation. Traditional software engineering stores planning state in Jira, Confluence, or Slack. In Agent-first development, this is a fundamental architectural defect because the Agent cannot reach information outside its context. The OpenAI team treats execution plans as versioned repository artifacts. An Agent working on a later task can infer the decisions, rationale, and current state of earlier work.

3. Documentation maintenance is automated too. Dedicated linters and CI jobs verify whether the knowledge base is current, cross-references are correct, and structure conforms to policy. A scheduled “documentation-gardening Agent” scans for stale or outdated documents and opens repair PRs. This means using an Agent to maintain documentation written for Agents.

It is worth noting that OpenAI’s primary repository currently contains 88 AGENTS.md files, one for every major subsystem. This is deliberate rather than accidental: instructions remain local and minimal.

Anthropic’s Approach: Documentation for Agents Across Sessions

Anthropic approached the same problem from another angle. In Effective Harnesses for Long-Running Agents, it describes a central challenge: Agents work in discrete sessions, and each new session remembers nothing that happened previously. It resembles shift work in which every engineer arrives with no memory of the preceding shift.

Its solution is a two-Agent architecture:

Initializer Agent (first run) establishes the environmental foundation:

• feature_list.json: more than 200 granular features, all marked “failing,” using JSON instead of Markdown because Agents are less likely to modify structured JSON data improperly
• init.sh: a one-command startup script
• claude-progress.txt: a progress log
• An initial Git commit

Coding Agent (every subsequent run) follows a fixed opening routine:

1. Read the Git log and progress file to understand the current state.
2. Run the development server and end-to-end tests.
3. Select one feature to implement.
4. Create a commit with a descriptive message.
5. Update the progress file.

The key insight is that external artifacts become the Agent’s memory. The progress file, Git history, and structured feature list persist across sessions. Every Agent session reconstructs context from these artifacts before beginning work.

This provides an important lesson for documentation design. Documentation should not be only a “rulebook”; it should also include state-tracking files that tell the Agent “how far the work has progressed,” not merely “how the work should be done.”

The Responsibility and Style of Each Documentation Type

Combining practices from OpenAI, Anthropic, and the community, project documentation can be divided into the following categories. Each has a different responsibility and writing principle.

1. Entry-Point Files (AGENTS.md / CLAUDE.md)

Responsibility: Map and navigation. Tell the Agent what the project is, which commands matter, and where to find details.

Writing principles:

• Keep it between 100 and 300 lines.
• Prioritize commands; copy-and-paste shell commands are much more useful than descriptive prose.
• Demonstrate style with real code examples instead of describing it in prose. One authentic code snippet is worth three paragraphs of explanation.
• State absolute boundaries explicitly. “Never commit secrets” has been shown to be the most effective single constraint.

2. Architecture Documentation (ARCHITECTURE.md / docs/architecture.md)

Responsibility: Define system-layering rules, dependency direction, and module boundaries.

Writing principles:

• Define layers and dependency direction explicitly, such as Types → Config → Repo → Service → Runtime → UI.
• Enforce the same constraints mechanically with a linter. Documentation is a “soft constraint” for the Agent; the linter is a “hard constraint.”
• When the linter fails, the error message should include instructions for fixing the problem. The error itself becomes a “teaching moment” for the Agent.

OpenAI uses custom linters, generated by Codex itself, and structural tests to enforce these rules. It emphasizes that these rules may appear overly rigid in a human-first workflow, but become force multipliers in an Agent-first environment. Once encoded, they apply everywhere at the same time.

3. Coding Conventions (docs/conventions.md)

Responsibility: Naming conventions, code style, and Git workflow.

Writing principles:

• Show rather than tell. Provide real code snippets as examples.
• Make the Git workflow concrete: branch-naming format, commit-message format, and PR requirements.
• Identify the shared toolkit the Agent should prefer instead of allowing it to write another helper. Manage invariants centrally.

4. State-Tracking Files (Progress Logs and Feature Lists)

Responsibility: Help an Agent in a new session understand how far the work has progressed quickly.

Writing principles:

• Use JSON rather than Markdown; Anthropic found that Agents are less likely to modify JSON’s structured data improperly.
• Have the Agent update the file at the end of every session.
• Use it with Git commit history. A descriptive commit message is itself excellent progress documentation.

5. Design Decision Records (ADRs / Design Docs)

Responsibility: Record “why”: why pgvector was chosen instead of Pinecone, or why the authentication flow was designed this way.

Writing principles:

• Use numbered indexes so the Agent can consult them on demand.
• Include the decision context, alternatives considered, and final rationale.
• Version them so later Agents can infer the chain of earlier decisions.

6. Submodule Documentation (AGENTS.md in Subdirectories)

Responsibility: Local context. When an Agent works in the backend/ directory, it should see only backend-specific constraints.

Writing principles:

• The Agent automatically reads the nearest file in the directory tree, with the nearest file taking priority.
• Submodule documentation may override rules in the root document.
• Keep information local. Include only context specific to that submodule.

Antipatterns: How Documentation Makes an Agent Worse

Experience from multiple teams shows that the following practices substantially reduce Agent performance:

1. Information overload. Research has verified an “instruction curse”: as instructions accumulate, the model’s ability to follow each one deteriorates. Several teams independently found that performance begins to degrade once context utilization exceeds roughly 40%. Excessive tools, lengthy documentation, and accumulated history make an Agent worse rather than better.

2. Contradictory rules. One document says “use Tailwind” while another says “use CSS Modules.” An Agent behaves unpredictably when it encounters conflicting information.

3. Stale information is never removed. Creating documentation is easy; maintaining it is the real challenge. A CLAUDE.md that appears complete may start lying only weeks after it is generated. The project structure changes, the technology stack is upgraded, and conventions evolve, but the documentation does not follow. Anthropic’s internal teams found that the more accurate CLAUDE.md is, the better Claude Code performs.

4. Description instead of examples. “Use functional components” is less effective than pasting a component that follows the requirement. Agents learn through pattern matching, and real code is the strongest pattern signal.

5. Keeping technical documentation outside the repository. Documentation for external APIs, libraries, or frameworks should live beside the code. Agents often fail when searching external resources because of version mismatches. Embed essential reference documentation in the repository.

Documentation Maintenance: The Hardest Part

Almost every practitioner emphasizes the same point: creating the initial guiding context is not the challenge; maintaining it is.

Running /init can create CLAUDE.md in seconds. This produces an illusion of completeness: the file exists, contains information, and looks professional. But it may begin to decay within weeks.

Recommended maintenance strategies:

1. Documentation as code. Include documentation in CI validation. OpenAI uses linters and CI jobs to verify whether documentation is current and cross-references are correct.

2. Use Agents to maintain documentation for Agents. OpenAI runs scheduled “documentation-gardening Agents” that scan for stale documentation no longer reflecting real code behavior and open repair PRs. This uses automation to counteract documentation entropy.

3. Treat specifications as living documents. Update a specification whenever you and an Agent make a decision or discover new information. If the data model changes or a feature is removed, reflect that in the document.

4. Check documentation consistency during PR review. Every PR that changes code should ask, “Does this change require related documentation to be updated?” Ideally, CI should check automatically.

An Actionable Starting Plan

If you want to begin now, you do not need to build an 88-file system like OpenAI’s all at once. Start with a minimum viable approach:

Week 1: Create or simplify the root CLAUDE.md / AGENTS.md. Ensure it contains the project description, technology stack, essential commands, and absolute boundaries. Keep it under 100 lines.

Week 2: Move architecture rules into docs/architecture.md and link to it from the entry-point file. If the project has explicit layering rules, add a basic linter to enforce them.

Week 3: If the project spans multiple modules, place local AGENTS.md files in the major subdirectories. Include only context specific to each module.

Ongoing: Whenever an Agent makes a mistake you do not want repeated, ask yourself: which documentation or constraint is missing? Then encode the fix in the repository. This is the central loop of harness engineering.

Mitchell Hashimoto, the founder of Terraform, summarized it most precisely: “Every time you find an Agent making a mistake, you spend time designing a solution that prevents the Agent from ever making that mistake again. That is Harness Engineering.”

Summary

One final sentence: Better models make harness engineering more important, not less. Stronger models unlock greater autonomy, and greater autonomy requires better guardrails. The documentation system you build for an Agent is the most basic layer of those guardrails.

References:

• OpenAI, “Harness Engineering: Leveraging Codex in an Agent-First World”, 2026.02
• Anthropic, “Effective Harnesses for Long-Running Agents”, 2025.11
• Anthropic, “Best Practices for Claude Code”, 2026
• AGENTS.md Standard (agents.md), Linux Foundation
• Addy Osmani, “How to Write a Good Spec for AI Agents”, 2026.02
• Martin Fowler / Birgitta Böckeler, “Harness Engineering”, 2026.02
• HumanLayer, “Writing a Good CLAUDE.md”, 2025.11
• Marmelab, “Agent Experience: Best Practices for Coding Agent Productivity”, 2026.01