$ Your Docs Are Not the Prompt: How AI Coding Agents Really Use Project Context

AI coding agents have made an old engineering debate feel urgent again: how much documentation does a project really need?

For years, teams have struggled with stale design docs, outdated architecture notes, half-maintained onboarding guides, and README files that drift away from reality. This was already a problem before AI. Now that coding agents can read those same files and use them as part of a coding session, the question feels sharper: should we invest much more time keeping docs perfectly current because AI agents depend on them?

My answer is: not as much as people think.

That does not mean documentation is useless. It means we should understand what kind of signal documentation provides to an AI coding agent, and how that signal compares to other parts of the session.

The strongest user-controlled signal is still the user prompt. After that comes the actual project: the source files, the file structure, the conventions, the tests, the build system, the errors, and whatever the agent can discover through local tool use. Documentation matters, but it is not equal to code. It is usually a secondary orientation layer.

This distinction changes how I think about engineering docs in the age of AI.

The prompt is still the highest-leverage input

When I give a coding agent a task, the user prompt is the most direct steering mechanism I control.

A bad prompt can waste the entire session. A clear prompt can make the same agent look dramatically better. This is not surprising. The prompt defines the problem, the desired outcome, the constraints, the acceptable trade-offs, and the level of autonomy expected from the agent.

For coding work, assuming the request is within the model’s intended behavior and does not run into safety or policy restrictions, the prompt has enormous influence. It tells the model what to optimize for.

That does not mean the model ignores the project. It means the project context is interpreted through the task.

A vague prompt plus perfect docs can still produce a confused session. A strong prompt plus imperfect docs often produces a useful result, especially when the agent can inspect files, run commands, ask clarifying questions, and reason from the actual codebase.

This is why I do not believe documentation should be treated as the primary steering layer for coding agents.

The prompt comes first.

Code is primary context; docs are proxy context

When an agent works inside a repository, the most important information is usually not in a markdown file. It is in the code.

The project structure tells the agent what kind of system it is looking at. The source files reveal naming conventions, framework choices, architectural boundaries, testing patterns, and implementation style. TypeScript files, package boundaries, test files, routes, schemas, migrations, and configuration files often carry more reliable signal than a design doc written three months ago.

Docs are still useful, but they are often proxy information. They describe intent, direction, decisions, and team preferences. They are not usually the ground truth of the system.

This matters because modern coding agents do not only read a documentation file and blindly obey it. They explore. They list files. They read source. They inspect nearby implementations. They infer patterns. They compare the requested task against what already exists.

The docs help orient the model, but the code anchors it.

That is why I would rank the practical signals roughly like this:

1. The user prompt.
2. The current code and project structure.
3. Local tool results from reading, searching, testing, and inspecting the project.
4. Rules, memories, and agent-specific instruction files.
5. Documentation.
6. External tools, MCPs, links, articles, and remote context.

flowchart TD
  P[1. User prompt<br/>defines the task]
  C[2. Code &amp; project structure<br/>ground truth]
  T[3. Local tool results<br/>read, search, test]
  R[4. Rules &amp; memories<br/>steering constraints]
  D[5. Documentation<br/>orientation layer]
  X[6. External: MCPs, links, articles<br/>weakest signal]

  P --> C --> T --> R --> D --> X

  classDef strong fill:#0A0A0A,stroke:#00FFFF,color:#E0E0E0
  classDef weak fill:#0A0A0A,stroke:#666,color:#999
  class P,C,T strong
  class D,X weak

The exact order can vary by agent and workflow, but the main point remains: not every piece of context has the same weight.

A note on what this ordering means. It is roughly the order of practical influence per session, not absolute authority per token. Rules can have higher per-token authority than docs, because they are short, direct, and explicitly framed as constraints. But the agent reaches them only after the prompt and the surrounding code are already shaping the session. So a great rule cannot rescue a vague prompt, and a good prompt rarely needs much help from docs.

About MCPs and external context: tools like Model Context Protocol servers, fetched URLs, knowledge-base lookups, and pasted articles can be useful, but they tend to sit furthest from the model’s training distribution for this codebase. The model has not seen your private MCP responses or your internal wiki page during training. It treats them as foreign material and weights them accordingly. They are valuable when the local project genuinely lacks the information, but they are not a substitute for code the agent can read directly.

Imperfect docs are not the same as bad docs

A lot of the documentation debate collapses two very different cases.

There is a big difference between imperfect documentation and actively misleading documentation.

Imperfect docs are common. They may be slightly stale, repetitive, incomplete, vague in places, or missing the newest implementation detail. Most real projects live here. Even strong teams rarely maintain perfect documentation for long.

Bad docs are different. Bad docs point the agent in the wrong direction. They describe an architecture that no longer exists. They name systems incorrectly. They contradict the code. They encode abandoned decisions as if they were still active.

My argument is not that bad documentation is safe. Very bad docs can absolutely damage an agent session.

My argument is narrower: mostly correct but imperfect docs are often good enough.

They give the agent shape. They communicate direction. They reduce the amount of repeated explanation required from the user. They help the model locate the project inside a familiar pattern space: this is a frontend app, this is a service-oriented backend, this is a monorepo, this is an API layer, this is a design system, this is a migration path.

That orientation has value, even when the docs are not perfect.

The model has seen messy projects before

One reason imperfect docs still work is that the model’s training data almost certainly contains a lot of imperfect software projects.

That is important. Real repositories are messy. They contain old READMEs, abandoned plans, inconsistent comments, half-finished migrations, TODOs, deprecated files, and documentation that lags behind implementation. The model has learned from this kind of material. It has seen the contradiction between what docs claim and what code does.

This does not make the model immune to bad context. It does mean that imperfection itself is not unusual input.

When an agent encounters a stale doc, it does not necessarily collapse. A capable agent can cross-check. It can inspect implementation. It can notice that a documented file no longer exists. It can ask whether a described pattern is still preferred. It can reconcile docs with tests and source code.

That is why I am more worried about unclear prompts than slightly stale docs.

A bad prompt gives the model the wrong job.

An imperfect doc usually just creates friction.

Clarifying questions are not failure

People often treat clarifying questions from agents as a negative outcome. I do not see it that way.

If the agent asks a good question, that is often a sign that the session is working. It means the agent found ambiguity and did not silently choose a path that might be wrong.

Could better docs reduce the number of questions? Yes.

Is that always worth the documentation effort? Not necessarily.

Answering questions keeps the human engaged in the session. That matters. The worst workflow is often not the one where the agent asks questions. It is the one where the human gives a vague task, disengages, and returns to a large diff built on misunderstood assumptions.

Clarifying questions create checkpoints. They surface ambiguity. They let the human correct direction before too much code is written.

For fully autonomous workflows, this is a different problem. If the goal is to run agents without human involvement, then ambiguity must be encoded more aggressively into rules, tests, specs, and evaluation systems — the same control surfaces I covered in The Feedback Loop Series Part 3: AI Agents. But for interactive development, questions are not necessarily waste. They can be part of the control loop.

Better docs have diminishing returns

Of course, better docs are better.

A clear architecture document helps humans. A good onboarding guide helps new engineers. A concise decision record helps the team remember why something exists. A current integration guide reduces repeated explanations. None of this disappears because AI agents exist.

But the question is not whether better docs are good. The question is whether making docs perfect is the best use of engineering time.

Usually, it is not.

There is a point where the effort required to keep docs perfectly aligned exceeds the value gained in agent performance. The agent still needs the actual code. The agent still needs the prompt. The agent still needs to inspect the repository. The agent still needs tests or feedback.

For day-to-day coding, I suspect the gain from perfect docs is often smaller than people expect.

The gain from good prompts is larger.

The gain from clear rules is larger.

The gain from executable tests is larger.

The gain from consistent project structure is larger.

This does not mean docs should be neglected. It means docs should be kept useful, not worshipped.

What should go into project docs?

The best project docs for AI agents are not necessarily long. In fact, verbose AI-generated documentation can become its own problem. If every file has a long explanation and every decision is repeated in five places, the agent gets more text but not necessarily more signal.

The goal is not to maximize documentation volume. The goal is to provide stable orientation.

Good project docs should answer questions like:

• What kind of project is this?
• What are the main architectural boundaries?
• What conventions should be followed?
• What should not be changed casually?
• Where are the important entry points?
• How should the agent validate its work?
• What common mistakes should be avoided?
• Which docs are authoritative, and which are historical?

That is enough to steer many sessions.

Docs do not need to explain every implementation detail. The code can do that. Docs should explain the shape of the system, the team’s preferences, and the traps that are not obvious from the code alone.

Rules are better than docs for repeated agent mistakes

When an agent repeatedly makes the same mistake, I would not bury the correction inside a long documentation file.

I would turn it into a rule.

Rules are better for behavioral constraints. They should be short, direct, and specific. For example:

• Do not introduce a new state management library.
• Prefer existing API client wrappers over raw fetch calls.
• Always add or update tests for changed business logic.
• Do not modify generated files directly.
• Use the existing design system components before creating new UI primitives.

These are different from docs. They are not explanations of the project. They are steering instructions for the agent.

This connects to a broader argument I made in Skills, Pipes, and the Unix Philosophy: the agent’s value comes from composing small, well-scoped pieces — skills, rules, tools — rather than from one monolithic instruction file trying to do everything. Rules are the small Unix-style pipes of project context. Docs are the prose around them.

This distinction matters. Documentation provides orientation. Rules provide constraints. Tests provide verification. Prompts provide task direction.

Trying to make one layer do all of these jobs leads to bloated docs and inconsistent agent behavior.

Update docs during the session, not as a separate ritual

One practical workflow I like is to let agent sessions reveal documentation gaps.

If the agent asks a clarifying question, answer it. If the answer represents a durable team preference, ask the agent to update the relevant doc or rule file in the same session.

This keeps documentation work connected to real ambiguity.

Instead of scheduling a large documentation cleanup that may or may not improve future agent behavior, update the docs when the missing information actually affects a task.

This is a better feedback loop:

1. Give the agent a clear task.
2. Let it inspect the project.
3. Notice where it gets confused.
4. Answer the clarification.
5. Ask why it got confused.
6. Update a doc, rule, or test only if the issue is likely to repeat.

This turns documentation into a byproduct of development rather than a parallel maintenance burden.

Why not remove docs entirely?

A fair question follows: if docs are lower-signal than code, why not remove them?

Because lower-signal does not mean no-signal.

Docs still provide structure. They help the agent orient itself faster. They reduce repeated explanation. They help humans understand the project. They create named places for durable knowledge. They make the repository feel intentional.

Even a lightweight docs folder can be useful because it tells both humans and agents that certain concepts exist: architecture, conventions, workflows, deployment, testing, data model, product decisions.

Empty docs are not enough, but the structure itself is not worthless. A well-named file can serve as an invitation to fill in durable knowledge when it appears.

The mistake is assuming that every doc must be polished before it has value.

The practical position

My position is pragmatic:

Keep docs good enough to orient humans and agents.

Do not spend disproportionate time making them perfect.

Invest more in prompts, rules, tests, and consistent project structure.

Use agent confusion as a signal for what needs to be documented.

Treat clarifying questions as part of the workflow, not automatically as failure.

Do not allow docs to become actively misleading.

This is especially important in fast-moving projects. AI can generate code quickly. It can also generate documentation quickly. But humans still need to verify whether that documentation is true, useful, and worth maintaining. If AI accelerates both code and docs, the risk is not only stale docs. The risk is a flood of plausible but low-signal text.

The answer is not more documentation by default.

The answer is better placement of information.

Prompts should define the task.

Code should remain the source of truth.

Tests should verify behavior.

Rules should encode repeated constraints.

Docs should orient the reader.

When each layer does its job, the agent does not need perfect documentation to be effective.

It needs enough structure to understand the project, enough code to infer the real patterns, enough rules to avoid repeated mistakes, and enough human engagement to resolve ambiguity at the right moments.

That is a healthier standard than trying to keep every doc perfectly aligned with a codebase that is changing faster than ever.

A simple experiment

This is easy to test.

Take the same coding task and run it under different conditions:

1. Bad prompt, good docs.
2. Good prompt, imperfect docs.
3. Good prompt, bad docs.
4. Good prompt, improved docs.
5. Good prompt, no docs, but strong project structure.
6. Good prompt, strong rules, and imperfect docs.

Measure not only whether the task succeeds, but how the session behaves. How many clarifying questions does the agent ask? How much code does it inspect? Does it follow existing patterns? Does it make wrong assumptions? Does it recover when the docs conflict with the code?

My expectation is that the prompt and the codebase will dominate more often than the docs. Good docs will reduce friction. Bad docs will create risk. Imperfect docs will usually be tolerable.

That is the distinction I care about.

The future of AI-assisted development is not documentation maximalism. It is context design.

And in context design, not all context is equal.