I stopped asking coding agents to guess where they could edit

A developer built Doc Bridge, a deterministic tool that provides coding agents with precise package-level context—such as which file to read first, which directories to edit, and which tests to run—rather than relying on agents to guess repository ownership. The tool, available on GitHub, includes a freshness gate that fails CI when the index is out of date, preventing agents from acting on stale information.

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. 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: That distinction matters. I still want an agent to reason about the implementation. I do not want it to invent repository ownership. I built Doc Bridge https://github.com/AgentsKit-io/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. 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. 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: 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. Repository search and RAG are useful when the question is open-ended: 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: The deterministic answer comes first. Probabilistic retrieval expands it instead of replacing it. 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. 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.