Stop AI agents from building the wrong thing by putting an authorized product decision in intent.md before implementation starts. Let an agent draft it from your description, codebase, and evidence; have a human review the judgment; then give the coding agent the objective, observable outcomes, hard constraints, edge cases, and verification it must preserve.
A team asked Claude Code to “add a bulk-export button to the reports page.” It shipped—clean, tested, merged. Two weeks later the support queue made the actual need obvious: users wanted a scheduled email digest. The agent built exactly what it was told. The product decision had been compressed into the wrong task before the agent arrived.
Correct code can still serve the wrong decision
An implementation agent is good at turning instructions into code. It should not silently invent the product judgment missing from those instructions. The faster and more autonomous the agent, the more important it becomes to separate two responsibilities:
- The agent can propose. It can inspect the repository, synthesize evidence, expose assumptions, and draft the intent.
- A human authorizes. Someone accountable for the product confirms the objective, outcomes, and boundaries before implementation proceeds.
Agent-authored does not mean agent-authorized.
Put the decision where the agent works
Save the authorized IntentSpec as intent.md in the repository. That gives every implementation session the same load-bearing context:
- Objective — the problem to solve and why it matters.
- Observable outcomes — what must be true for users when the change succeeds.
- Hard constraints — rules the implementation cannot violate.
- Edge cases — failure modes and expected behavior.
- Verification — concrete checks that can prove the implementation and guard regressions.
- Evidence references — enough provenance to inspect the reasoning without committing private raw material to git.
Pathmode's preflight grades six readiness gates deterministically before the first edit. It does not decide whether the feature is wise; it tells the human and agent where the stated decision is still too thin to build from.
Keep the two records in the right places
The repo should contain the decision the code is expected to honor. Private customer evidence, named guest feedback, signed-in authorization, and cross-repository context often should not be committed. Connected Pathmode teams can retain that material behind the IntentSpec while intent.md remains the content authority for the repository.
That boundary makes the work both executable and accountable: the agent can read the decision locally, and a reviewer can trace how the team arrived there when the judgment needs to be challenged.
Frequently asked questions
- Isn't a detailed prompt enough?
- Sometimes. A detailed prompt is appropriate for small, reversible, disposable work. For maintained product changes, intent.md gives the decision a durable home in the repository, so the next session and reviewer see the same outcomes and boundaries.
- Where does the intent come from?
- An agent can draft it from the product description, repository, and available evidence such as support tickets, interviews, observed friction, and metrics. A human then corrects and authorizes the decision. Evidence grounds judgment; it does not automatically determine what to build.
- Does this slow the agent down?
- It adds a short decision step before implementation. For consequential work, that is usually cheaper than re-explaining the goal, reviewing a strategically wrong diff, or unwinding a regression after merge. The preflight makes the step concrete instead of ceremonial.
- How is this different from a PRD?
- A PRD can remain the broader human narrative. intent.md is the compact, repo-native decision an implementation agent can repeatedly read and verify against. They can coexist; Pathmode does not require replacing every product document.