{"slug": "i-stopped-asking-coding-agents-to-guess-where-they-could-edit", "title": "I stopped asking coding agents to guess where they could edit", "summary": "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.", "body_md": "Most mistakes I see from coding agents do not begin with bad code.\n\nThey begin one step earlier.\n\nThe agent opens the wrong documentation, assumes a neighboring package owns the\n\nchange, edits a directory that was supposed to be out of scope, and finishes by\n\nrunning a repository-wide test that says very little about the package it\n\nchanged.\n\nAdding another paragraph to `AGENTS.md`\n\nhelps, but it does not answer every\n\npackage-level question in a large repository. A global instruction file can say\n\n“respect package boundaries.” It cannot always tell an agent which package owns\n\nauthentication, which file should be read first, or which two checks prove that\n\nan authentication change is safe.\n\nI wanted that answer to be data rather than advice.\n\nFor a task involving an `auth`\n\npackage, the useful context is surprisingly\n\nsmall:\n\n```\n{\n  \"startHere\": \"docs/for-agents/packages/auth.md\",\n  \"editRoots\": [\"packages/auth\"],\n  \"checks\": [\n    \"pnpm --filter @demo/auth test\",\n    \"pnpm --filter @demo/auth lint\"\n  ],\n  \"humanDoc\": \"/docs/guides/auth\"\n}\n```\n\nThis does not tell the agent how to solve the task. It answers four questions\n\nthat should not require creativity:\n\nThat distinction matters. I still want an agent to reason about the\n\nimplementation. I do not want it to invent repository ownership.\n\nI built [Doc Bridge](https://github.com/AgentsKit-io/doc-bridge) around this\n\nhandoff. The deterministic layer does not require an LLM or an API key.\n\nYou can run its bundled monorepo fixture without preparing a repository:\n\n```\nnpx --yes @agentskit/doc-bridge@1.2.4 demo --fixture monorepo --text\n```\n\nThe demo begins with the failure mode:\n\n```\nBefore (agent guesses package)\n  ✗ edits packages/billing when task mentions \"auth\"\n  ✗ runs repo-wide test instead of package checks\n```\n\nIt then resolves the handoff:\n\n```\nAfter (handoff.resolve / query --agent)\n  ✓ target:  auth (packages/auth)\n  ✓ start:   docs/for-agents/packages/auth.md\n  ✓ edit:    packages/auth\n  ✓ checks:  pnpm --filter @demo/auth test\n             pnpm --filter @demo/auth lint\n  ✓ human guide: /docs/guides/auth\n```\n\nThe fixture also demonstrates the gate moving from a missing index to a fresh\n\none. That part is important. A correct handoff generated six months ago is not\n\nnecessarily correct today.\n\nI also ran the same query in the public AgentsKit monorepo:\n\n```\npnpm exec ak-docs query package core --agent\n```\n\nThe relevant output was:\n\n```\n{\n  \"target\": {\n    \"type\": \"package\",\n    \"id\": \"core\",\n    \"path\": \"packages/core\"\n  },\n  \"startHere\": \"apps/docs-next/content/docs/for-agents/core.mdx\",\n  \"readBeforeEditing\": [\n    \"apps/docs-next/content/docs/for-agents/core.mdx\",\n    \"AGENTS.md\"\n  ],\n  \"editRoots\": [\"packages/core\"],\n  \"checks\": [\n    \"pnpm --filter @agentskit/core test\",\n    \"pnpm --filter @agentskit/core lint\"\n  ],\n  \"humanDoc\": \"/docs/reference/packages/core\"\n}\n```\n\nThat result is useful because `core`\n\nhas stricter rules than most packages in\n\nthe repository. It has zero runtime dependencies and a size budget. An agent\n\nworking there should not discover those constraints after changing a sibling\n\npackage or running the wrong test.\n\nThe global rules still matter. The handoff explicitly includes `AGENTS.md`\n\nin\n\n`readBeforeEditing`\n\n. The point is not to replace repository instructions. It is\n\nto route the task into the right part of them.\n\nGenerating an index is not enough. Ownership changes. Packages move. Human\n\nguides are renamed. A team can end up with a polished machine-readable answer\n\nthat points to yesterday's repository.\n\nThat is why I treat freshness as a CI concern:\n\n```\npnpm docs:bridge:gate\n```\n\nOn the same AgentsKit checkout, the gate reported:\n\nIf the inputs change without a regenerated index, the freshness hash changes\n\nand the gate fails. It does not silently rebuild the file inside CI and pretend\n\nthe committed context was current.\n\nThat behavior is deliberate. A gate that repairs its own evidence before\n\nchecking it can hide the drift it was supposed to detect.\n\nRepository search and RAG are useful when the question is open-ended:\n\nOwnership is a different kind of question. If the repository already knows\n\nthat `packages/auth`\n\nowns authentication, semantic similarity should not be\n\nallowed to decide that `packages/billing`\n\nlooks almost as relevant.\n\nMy preferred order is:\n\nThe deterministic answer comes first. Probabilistic retrieval expands it\n\ninstead of replacing it.\n\nThe contract is small, but it is not free.\n\nSomeone has to define ownership. Package checks need to be accurate. Human\n\ndocumentation links need to exist. The index must be committed and kept fresh.\n\nA badly maintained routing map gives an agent false confidence, which can be\n\nworse than admitting that the answer is unknown.\n\nThere are also tasks that cross legitimate boundaries. A breaking contract\n\nchange may require coordinated edits in several packages. In that case the\n\nhandoff should describe the larger scope or force a human decision. It should\n\nnot squeeze a cross-cutting change into one convenient directory.\n\nThe goal is not to make every task local. It is to make scope explicit.\n\nThe smallest adoption path is:\n\n```\nnpm install --save-dev @agentskit/doc-bridge@1.2.4\nnpx ak-docs init\nnpx ak-docs index\nnpx ak-docs query package example --agent\nnpx ak-docs gate run\n```\n\nThe same handoff can then be exposed through the CLI or MCP. A coding agent does\n\nnot need a Doc Bridge-specific reasoning strategy. It needs to resolve the\n\nhandoff before editing, read `startHere`\n\n, stay inside `editRoots`\n\n, and run\n\n`checks`\n\n.\n\nI am Emerson Braun, and I created and maintain Doc Bridge, so I am not a neutral\n\nobserver of the tool. The reason I am sharing the contract is that it is easy to\n\ntest without trusting the product description: run the fixture, inspect the\n\nJSON, make the index stale, and watch the gate fail.\n\nIf your repository has a shape this contract handles badly, I would rather see\n\nthat example than another feature request written in the abstract. The awkward\n\nrepositories are where the routing model becomes more honest.\n\nPreparation disclosure: I used AI tools to help organize and critique this\n\ndraft. I ran the commands, checked the captured outputs against the public\n\nrepositories, reviewed every technical claim, and stand behind the final text.", "url": "https://wpnews.pro/news/i-stopped-asking-coding-agents-to-guess-where-they-could-edit", "canonical_source": "https://dev.to/agentskit/i-stopped-asking-coding-agents-to-guess-where-they-could-edit-206k", "published_at": "2026-07-28 16:23:47+00:00", "updated_at": "2026-07-28 16:36:04.810569+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Doc Bridge", "AgentsKit", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/i-stopped-asking-coding-agents-to-guess-where-they-could-edit", "markdown": "https://wpnews.pro/news/i-stopped-asking-coding-agents-to-guess-where-they-could-edit.md", "text": "https://wpnews.pro/news/i-stopped-asking-coding-agents-to-guess-where-they-could-edit.txt", "jsonld": "https://wpnews.pro/news/i-stopped-asking-coding-agents-to-guess-where-they-could-edit.jsonld"}}