An ADR for AI-assisted development should contain a stable ID, status, context, decision, rejected alternatives, consequences, scope, relationships and reconsideration triggers. Add discovery terms agents are likely to query and classify each consequence as guidance, review-required or deterministically enforceable.
The template
Keep the record readable as Markdown while validating the fields needed for lifecycle and retrieval. Adapt names to the repository's existing ADR convention rather than inventing a second format without cause.
---
id: ADR-024
title: Preserve account restoration window
status: accepted
decided: 2026-08-03
scope: [services/accounts]
relates_to: [ADR-011]
discovery: [delete account, hard delete, retention, restore user]
---
## Context
What forces a choice now?
## Decision
What has the team accepted?
## Rejected alternatives
What plausible options were rejected, and why?
## Consequences
What must change? Classify objective checks separately.
## Reconsider when
Which changed assumption should reopen this decision?Fields that improve agent use
Stable IDs make citations reviewable. Explicit status prevents a proposed idea from being presented as accepted. Discovery terms bridge the difference between the title a human wrote and the question an agent asks. Scope keeps a valid decision from being applied to unrelated code.
Describe rejected alternatives neutrally
Agents frequently rediscover reasonable-looking options. Record why each serious alternative was unsuitable under the stated constraints, and include evidence where available. Avoid turning a contextual rejection into a universal claim.
Be honest about enforcement
A consequence such as 'all access must be intuitive' cannot be proven by a simple gate. A prohibition on importing a specific package within a path may be mechanically checkable. Classifying the boundary prevents documentation from overstating what CI guarantees.