01
Decision infrastructure for coding agents
Decision infrastructure gives coding agents a durable, reviewable and enforceable record of what a software team has already decided.
AS DECIDED / NOTES40 FIELD RECORDS
Decision infrastructure
The code moves quickly.The decision should survive it.
Practical, evidence-led notes on giving AI coding agents durable project context, reproducible decisions and constraints that mean what they claim.
Maintained by Tom Ballard · Initial library published 3 August 2026 · Read the decision-governance pillar
Canonical collection answer
What are AsDecided Notes?
AsDecided Notes are evidence-led explanations of the decisions that let software teams work with AI coding agents without losing project authority. The collection covers architecture decision records, persistent context, deterministic retrieval, decision provenance, exceptions and enforcement in CI. Each note gives a focused answer, identifies the boundary of the claim and links to the canonical product documentation or source material. Five canonical guides are the collection’s durable answers; shorter notes support them with comparisons, worked examples and implementation questions. Notes are editorial guidance rather than product guarantees, so the current specification, documentation and changelog remain the source of truth for released behaviour.
Decision infrastructure
Decision infrastructure for coding agents
Decision infrastructure is the repository-level system that records an engineering decision, makes the relevant decision retrievable by coding agents, and verifies any machine-checkable constraint against the code. It turns project memory from optional prose into maintained engineering infrastructure.
Read the field notePILLAR INDEX
Start with the answer, then follow the evidence.
These five records define the main topics in the collection. The supporting notes link back to them so a reader or answer system can move from a specific question to the broader source of authority.
- 01Decision infrastructure for coding agentsDecision infrastructure gives coding agents a durable, reviewable and enforceable record of what a software team has already decided.
- 02AGENTS.md vs CLAUDE.md vs ADRs: where engineering decisions belongAGENTS.md and CLAUDE.md guide particular coding agents; ADRs preserve durable decisions. They solve related but different problems.
- 03Deterministic retrieval vs RAG for engineering decisionsRAG is flexible for broad knowledge discovery; deterministic retrieval is useful when engineering decisions need reproducible results and citations.
- 04How to enforce architectural decisions in CIEnforce an architectural decision in CI by translating one objective consequence into a deterministic check linked to the accepted record.
- 05Decision provenance for AI-generated codeDecision provenance links an AI-assisted change to the reviewed records, repository state and evidence that governed it.
01
Decision infrastructure
11 notes02
What is decision drift in AI-assisted development?
Decision drift happens when later code changes gradually stop reflecting an engineering decision that the team still considers valid.
03
Why coding agents rewrite architectural decisions
Coding agents often reverse valid architectural decisions because the rationale and rejected alternatives are missing from the task context.
04
How to record negative engineering decisions
Negative decisions document approaches a team deliberately rejected so people and coding agents do not repeatedly reintroduce them.
05
Why the repository should be the system of record for coding agents
Repository-local decisions travel with the code, inherit review and remain available across agent vendors and execution environments.
06
How to stop AI coding agents repeating failed approaches
Record rejected approaches with scope, evidence and reconsideration conditions so coding agents do not rediscover the same failure.
07
An architecture decision record template for AI-assisted development
An agent-ready ADR adds explicit scope, lifecycle, rejected alternatives, retrieval terms and machine-checkable consequences.
08
How to migrate engineering decisions between repositories
Migrate decisions by preserving identifiers and provenance, then deliberately rescoping, accepting or rejecting them in the destination repository.
09
What is an architectural decision control plane for AI coding agents?
An architectural decision control plane connects reviewed decisions, agent context, code changes and deterministic verification without replacing Git or CI.
10
How to monitor architectural decision health
Monitor whether accepted decisions remain owned, retrievable, enforced where claimed and aligned with the code they govern.
11
How to govern architectural decisions across multiple repositories
Combine local repository authority with explicit organisation-level decisions, versioned distribution and deterministic precedence.
02
Persistent agent context
10 notes01
How to give coding agents persistent project context
Use layered instructions, repository decision records and deterministic retrieval to give coding agents persistent context without one enormous prompt.
02
AGENTS.md vs CLAUDE.md vs ADRs: where engineering decisions belong
AGENTS.md and CLAUDE.md guide particular coding agents; ADRs preserve durable decisions. They solve related but different problems.
03
Project instructions are not enforcement
Agent instruction files shape model behaviour, but they do not prove that a patch complies with an engineering decision.
04
How do coding agents remember architectural decisions?
Coding agents remember architectural decisions reliably only when the repository can retrieve a current, cited record for each task.
05
How to share decisions between Cursor, Claude Code and Codex
Keep decisions in one vendor-neutral repository record and use each agent's instruction file only as a route into that shared authority.
06
AGENTS.md examples for software teams
A practical AGENTS.md should teach Codex how to work in a repository while routing durable engineering decisions to their authoritative records.
07
CLAUDE.md examples for architecture rules
Use CLAUDE.md to route Claude Code toward current architecture decisions, not to duplicate an entire decision history.
08
How to keep multiple coding agents consistent
Multiple agents stay consistent when they share authority, retrieval and verification—not when prompts happen to resemble one another.
09
How should AI coding agents cite architectural decisions?
Decision citations should identify the exact reviewed record, its repository revision, applicability and the files or claims it influenced.
10
Decision-aware planning for AI coding agents
Make applicable decisions, conflicts, required checks and citations visible in an agent plan before implementation begins.
03
ADRs and requirements
2 notes01
Architecture decision records for coding agents
ADRs become more useful to coding agents when they are validated, discoverable by task language, lifecycle-aware and connected to checks.
02
Requirements as code for AI coding agents
Requirements as code makes important product constraints versioned, validated, discoverable and testable alongside the implementation.
04
Retrieval and MCP
2 notes01
Deterministic retrieval vs RAG for engineering decisions
RAG is flexible for broad knowledge discovery; deterministic retrieval is useful when engineering decisions need reproducible results and citations.
02
Why read-only MCP matters for engineering decisions
A read-only MCP boundary lets coding agents discover and cite accepted decisions without silently changing the authority they depend on.
05
Enforcement and CI
2 notes01
How to enforce architectural decisions in CI
Enforce an architectural decision in CI by translating one objective consequence into a deterministic check linked to the accepted record.
02
Deterministic agent governance without an LLM judge
Deterministic checks make agent governance reproducible by evaluating explicit constraints without asking another model for a compliance opinion.
06
Worked examples
5 notes01
A soft-delete decision record for coding agents
A worked example showing how to record, retrieve and enforce a 30-day account-restoration decision for coding agents.
02
A decision-readiness checklist for coding-agent repositories
Use this checklist to assess whether a repository gives coding agents durable decisions, reproducible retrieval and honest enforcement.
03
Coding-agent governance tools compared
Instruction files, ADRs, MCP servers, RAG and CI policy engines govern different stages; dependable systems combine them without confusing guidance with proof.
04
How to benchmark project instructions vs enforced decisions
A reproducible benchmark can measure whether instructions improve agent behaviour and whether deterministic checks catch the violations that remain.
05
A structured schema for agent-readable architectural decisions
Add stable identity, lifecycle, scope, agent instructions and enforcement references to human-readable decision records.
07
Deterministic enforcement
6 notes01
How to prevent coding agents changing database conventions
Record the database convention, expose its rationale before planning, and enforce only the structural consequences that CI can prove.
02
How to test whether an AI coding agent followed project instructions
Test observable outcomes—decision retrieval, citations, commands, policy results and patch behaviour—rather than asking the agent whether it complied.
03
Decision provenance for AI-generated code
Decision provenance links an AI-assisted change to the reviewed records, repository state and evidence that governed it.
04
How to manage exceptions to architectural decisions
Treat architectural exceptions as scoped, approved and expiring records instead of disabled checks or permanent temporary workarounds.
05
What audit evidence should an AI-assisted code change preserve?
Preserve repository state, retrieved decisions, citations, check results, approvals and exceptions as an inspectable evidence chain.
06
How to link ADRs to policy-as-code checks
Connect each deterministic policy rule to the reviewed architectural decision that explains its purpose, scope and remediation.
08
Retrieval and protocol
2 notes01
RAG vs repository-native context for coding agents
Repository-native context is the safer authority layer for engineering decisions; RAG remains useful for broader discovery across large, mixed corpora.
02
How to resolve which architectural decisions apply to a code change
Resolve applicable decisions with deterministic repository and path signals first, then use semantic signals only to improve discovery.