I stopped asking coding agents to guess where they could edit

Most mistakes I see from coding agents do not begin with bad code.

They begin one step earlier.

The agent opens the wrong documentation, assumes a neighboring package owns the
change, edits a directory that was supposed to be out of scope, and finishes by
running a repository-wide test that says very little about the package it
changed.

Adding another paragraph to AGENTS.md helps, but it does not answer every
package-level question in a large repository. A global instruction file can say
“respect package boundaries.” It cannot always tell an agent which package owns
authentication, which file should be read first, or which two checks prove that
an authentication change is safe.

I wanted that answer to be data rather than advice.

The handoff I wanted before an edit

For a task involving an auth package, the useful context is surprisingly
small:

{
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": [
    "pnpm --filter @demo/auth test",
    "pnpm --filter @demo/auth lint"
  ],
  "humanDoc": "/docs/guides/auth"
}

This does not tell the agent how to solve the task. It answers four questions
that should not require creativity:

1. Where should I start reading?
2. Where am I allowed to edit?
3. Which checks prove the change?
4. Which human-facing guide describes the same feature?

That distinction matters. I still want an agent to reason about the
implementation. I do not want it to invent repository ownership.

Reproduce the idea in one minute

I built Doc Bridge around this
handoff. The deterministic layer does not require an LLM or an API key.

You can run its bundled monorepo fixture without preparing a repository:

npx --yes @agentskit/doc-bridge@1.2.4 demo --fixture monorepo --text

The demo begins with the failure mode:

Before (agent guesses package)
  ✗ edits packages/billing when task mentions "auth"
  ✗ runs repo-wide test instead of package checks

It then resolves the handoff:

After (handoff.resolve / query --agent)
  ✓ target:  auth (packages/auth)
  ✓ start:   docs/for-agents/packages/auth.md
  ✓ edit:    packages/auth
  ✓ checks:  pnpm --filter @demo/auth test
             pnpm --filter @demo/auth lint
  ✓ human guide: /docs/guides/auth

The fixture also demonstrates the gate moving from a missing index to a fresh
one. That part is important. A correct handoff generated six months ago is not
necessarily correct today.

A real monorepo answer

I also ran the same query in the public AgentsKit monorepo:

pnpm exec ak-docs query package core --agent

The relevant output was:

{
  "target": {
    "type": "package",
    "id": "core",
    "path": "packages/core"
  },
  "startHere": "apps/docs-next/content/docs/for-agents/core.mdx",
  "readBeforeEditing": [
    "apps/docs-next/content/docs/for-agents/core.mdx",
    "AGENTS.md"
  ],
  "editRoots": ["packages/core"],
  "checks": [
    "pnpm --filter @agentskit/core test",
    "pnpm --filter @agentskit/core lint"
  ],
  "humanDoc": "/docs/reference/packages/core"
}

That result is useful because core has stricter rules than most packages in
the repository. It has zero runtime dependencies and a size budget. An agent
working there should not discover those constraints after changing a sibling
package or running the wrong test.

The global rules still matter. The handoff explicitly includes AGENTS.md in
readBeforeEditing. The point is not to replace repository instructions. It is
to route the task into the right part of them.

Documentation drift needs to fail visibly

Generating an index is not enough. Ownership changes. Packages move. Human
guides are renamed. A team can end up with a polished machine-readable answer
that points to yesterday's repository.

That is why I treat freshness as a CI concern:

pnpm docs:bridge:gate

On the same AgentsKit checkout, the gate reported:

• the index was fresh;
• 25 human-documentation links resolved;
• 25 handoffs had a starting document, edit roots, checks, and a human link;
• all seven required Documentation Standard v1 rules passed.

If the inputs change without a regenerated index, the freshness hash changes
and the gate fails. It does not silently rebuild the file inside CI and pretend
the committed context was current.

That behavior is deliberate. A gate that repairs its own evidence before
checking it can hide the drift it was supposed to detect.

Why I did not start with RAG

Repository search and RAG are useful when the question is open-ended:

• Where is rate limiting discussed?
• What changed in the authentication design?
• Which documents mention a migration?

Ownership is a different kind of question. If the repository already knows
that packages/auth owns authentication, semantic similarity should not be
allowed to decide that packages/billing looks almost as relevant.

My preferred order is:

1. resolve an exact ownership handoff;
2. read the specified starting documents;
3. use search or RAG for additional context;
4. edit only inside the declared roots;
5. run the declared checks.

The deterministic answer comes first. Probabilistic retrieval expands it
instead of replacing it.

What this approach costs

The contract is small, but it is not free.

Someone has to define ownership. Package checks need to be accurate. Human
documentation links need to exist. The index must be committed and kept fresh.
A badly maintained routing map gives an agent false confidence, which can be
worse than admitting that the answer is unknown.

There are also tasks that cross legitimate boundaries. A breaking contract
change may require coordinated edits in several packages. In that case the
handoff should describe the larger scope or force a human decision. It should
not squeeze a cross-cutting change into one convenient directory.

The goal is not to make every task local. It is to make scope explicit.

Add it without changing your agent stack

The smallest adoption path is:

npm install --save-dev @agentskit/doc-bridge@1.2.4
npx ak-docs init
npx ak-docs index
npx ak-docs query package example --agent
npx ak-docs gate run

The same handoff can then be exposed through the CLI or MCP. A coding agent does
not need a Doc Bridge-specific reasoning strategy. It needs to resolve the
handoff before editing, read startHere, stay inside editRoots, and run
checks.

I am Emerson Braun, and I created and maintain Doc Bridge, so I am not a neutral
observer of the tool. The reason I am sharing the contract is that it is easy to
test without trusting the product description: run the fixture, inspect the
JSON, make the index stale, and watch the gate fail.

If your repository has a shape this contract handles badly, I would rather see
that example than another feature request written in the abstract. The awkward
repositories are where the routing model becomes more honest.

Preparation disclosure: I used AI tools to help organize and critique this
draft. I ran the commands, checked the captured outputs against the public
repositories, reviewed every technical claim, and stand behind the final text.