Decision-aware planning requires an AI coding agent to retrieve applicable architectural decisions before implementation, cite them in its plan, translate them into concrete steps and checks, and disclose conflicts with the existing code. The plan should be revalidated when the patch introduces new files or changes scope.
Move architectural reasoning before code generation
If the first visible architecture check happens in pull-request review, the expensive part of the work has already occurred. Planning creates a smaller intervention point: reviewers can correct a missing decision, mistaken scope or invalid approach before the agent produces a large patch.
The plan should show the link between a governing decision and an implementation action. Merely listing ADR titles demonstrates retrieval, not understanding.
A compact plan contract
Ask for a stable structure that can be reviewed by a human and parsed by automation. Keep retrieved context concise and allow the agent to open the full record when it needs rationale or alternatives.
- Applicable decisions with IDs and match reasons.
- Implementation steps tied to those decisions.
- Prohibited approaches or known rejected alternatives.
- Required tests and policy checks.
- Conflicts, uncertainty and any exception required.
Treat conflicts as useful output
A codebase may already violate an accepted decision. The agent should not quietly copy the local pattern or silently redesign the surrounding system. It should identify the conflict, state whether the task can comply without broad migration and request a decision when the evidence is ambiguous.
This is also where negative decisions earn their keep. A rejected approach with reconsideration conditions can stop the agent from proposing the same attractive failure again.
Re-resolve after the plan changes
Initial retrieval uses the task and expected files. Once implementation changes the dependency graph or touches another service, run applicability again. Preserve both the plan-time citations and the final citation set so reviewers can see how the architectural surface evolved.
1. Retrieve active decisions for the task and expected paths.
2. Cite each decision beside the step it constrains.
3. Run declared checks after implementation.
4. Re-resolve decisions for the final changed-file set.