Write specs your coding agents can actually follow

Hand a coding agent a vague ticket and you get vague code — confidently written, plausible on the surface, wrong in the ways the ticket was silent about. The agent did not fail; it did exactly what it was told, which was not enough. The bottleneck was never the agent's ability to write code. It was the quality of the description it was given to write from.

That gap gets wider the moment the work spans more than one repository. An agent pointed at a single repo can read that repo. What it cannot do is know that a field it is renaming is consumed by two other services it was never shown, or that the notification it is adding already half-exists in a worker it has no reason to open. Neither can a person, working from the same partial view. The missing input is not more code. It is context the code alone does not carry.

The bottleneck is the input, not the writer

Whatever writes the code — your engineer, your agent — needs the same thing before it starts: a description of the change that is complete across every repository it touches, and honest about where each claim comes from. Give it that and both do good work. Give it a ticket that describes three of the four affected services and both produce something that breaks in the fourth.

This is why "make the agent smarter" is the wrong lever to reach for first. A more capable model still cannot infer a connection that is nowhere in the repository it was handed. The seam between services — the event one emits and another consumes, the contract the API changed and the client still expects — lives between repositories, so it has to be discovered by reading across them and then written down. Skipping that step does not remove the work; it just defers it to the moment the code is already wrong.

A good spec closes that gap in a way that happens to serve humans and agents identically. When each claim is anchored to a file, a line, a commit, a person can verify it and an agent can ground on it instead of guessing. When the affected repositories are enumerated rather than assumed, neither one is surprised by the fourth service in review. Clarity is not a nicety here; it is the difference between a spec that produces working code and one that produces a plausible near-miss.

Reading is a different job from writing

Producing that description is analysis, not authorship — and keeping those two jobs separate is what makes the description trustworthy. WeaveSpec connects to your repositories read-only. It clones, analyses, and describes; it does not change a line, open a pull request, or touch your workflows, and the access it holds does not permit any of those. Its output is a map of the work, with the source attached.

That boundary is the point, not a limitation. The thing that writes your code — your team, your coding agent — is not something WeaveSpec replaces or competes with; it is the thing WeaveSpec hands a better input to. A tool that only ever reads can be trusted to describe the system accurately precisely because describing it changes nothing. You keep the writer you already have. What changes is the quality of what it is asked to build from.

What actually makes a spec agent-ready

• Anchor every claim to the code. A file, a line, a commit behind each statement. This is what lets a reviewer check it in seconds and an agent ground on it instead of hallucinating the parts that were left implicit.
• Enumerate the repositories, do not assume them. The value is naming the fourth service before the work starts, not discovering it in review. Cross-repo scope belongs in the spec, not in someone's memory.
• Derive the tasks from the same analysis as the doc. When the product description and the per-repo task breakdown come from one reading of the repositories, the thing an agent is told to build and the thing the spec describes cannot quietly disagree.
• Keep a human at the outward edge. Generating a clear description is safe to automate; acting on it is where a named person says yes. The map is produced by reading; the decision to build, and anything written to your tools, stays a human call.

The uncomfortable truth of the last few years is that better models raised the ceiling on writing code and left the floor — the quality of the instructions — exactly where it was. WeaveSpec works on the floor. Read the repositories, describe the work clearly enough that a person or an agent can act on it without guessing, and change nothing in the process. The writing gets easier when the spec finally carries what the writer could never have inferred alone.