Appearance

Architecture Decision Records ​

Architecture Decision Records (ADRs) document the decisions behind your architecture. They're the historical record of why your system is built the way it is — captured once, immutable after acceptance, and compiled into directives the model follows every session.

ADRs were formalized by Michael Nygard in 2011 as lightweight records of significant architectural decisions. The format has since been adopted widely — Joel Parker Henderson maintains a comprehensive collection of templates and examples.

edikt adopts ADRs as a first-class governance artifact and extends them with a compile pipeline that transforms decisions into enforcement directives the model follows automatically.

ADRs vs Invariant Records vs Guidelines ​

ADRInvariant RecordGuideline
DocumentsA decision that was madeA constraint that must hold continuouslyA team convention or preference
Written whenA decision is made (one-time)A hard constraint needs enforcementA pattern needs consistency
AlternativesYes — central to the formatNo — invariants don't have alternativesNo
MutabilityImmutable once accepted. Supersede via new ADR.Content immutable. Status can change.Editable any time.
Compiles toMUST/NEVER directives in topic filesPathless invariants land in the ambient core (.claude/rules/governance.md); path-scoped invariant directives land in directive-index.yamlImplementation directives in topic files
Typical sourceDesign review, team discussion, tech lead decisionRegulation, incident, foundational principleTeam agreement, code review pattern

The template ​

edikt's ADR template follows the structure from Nygard's original proposal (Context → Decision → Consequences) and adds Alternatives Considered (common in practice). Compiled directives live in a co-located sidecar (<ADR>.edikt.yaml), not in the prose body — see Sidecar Architecture. The template is customizable — see Extensibility.

markdown
# ADR-NNN: Short imperative title

**Date:** YYYY-MM-DD
**Status:** Draft | Accepted | Superseded by ADR-NNN

## Context

What is the situation? What forces are at play? What problem needs solving?

## Decision

What we decided to do. This is the section the sidecar extractor reads.
Use MUST/NEVER language for hard constraints.
Name specific tools, patterns, file paths, thresholds.

## Consequences

What changes as a result of this decision?
Positive and negative. What becomes easier, what becomes harder?

## Alternatives Considered

What else was evaluated and why it was rejected?

Lifecycle ​

  • Draft — under discussion, not yet enforced. Editable.
  • Accepted — decision is final. Content is immutable. Compile reads it. To change an accepted decision, create a new ADR that supersedes it.
  • Superseded by ADR-NNN — replaced by a newer decision. Compile skips it. The superseding ADR explains what changed and why.

Once accepted, an ADR is immutable. If a decision changes, you write a new ADR — the history stays intact.

How ADRs compile into governance (v0.6.0) ​

Every ADR has a co-located <ADR>.edikt.yaml sidecar that holds compiled directives — edikt does not write to your prose .md. /edikt:adr:compile <id> regenerates exactly that one sidecar in a fresh subagent context with a locked extraction prompt. /edikt:gov:compile Phase A auto-resyncs stale sidecars (parallel, concurrency 8); Phase B merges them into topic files deterministically (no LLM, no Task dispatch).

The ## Decision section is what the extractor reads. It pulls every enforceable statement and transforms it into a directive:

Decision section (human, 150 lines):
  "Build edikt as a lean context engine for coding harnesses, starting
   with Claude Code — it has path-conditional rules, hooks, and slash
   commands other harnesses still lack..."

Compiled directive (the model, 1 line):
  "All public API routes MUST be versioned under /vN/. NEVER break
   a published contract. (ref: ADR-001)"

The compile pipeline also generates:

  • Reminders — "Before changing an API route → MUST keep the published version stable (ref: ADR-001)"
  • Verification items — "[ ] No breaking changes to published /v1/ endpoints (ref: ADR-001)"

These land in the directive's topic file (.claude/rules/governance/<topic>.md), under its ## Reminders and ## Verification Checklist sections — not in the ambient core (.claude/rules/governance.md), which carries only pathless-invariant statements and a one-line topic index.

See How Governance Compiles for the full pipeline.

Writing effective ADRs ​

The Decision section is what becomes a directive. Write it for both audiences:

For humans — explain the decision clearly with enough context that a new team member understands it.

For compile — use MUST/NEVER language, name specific things (tools, patterns, file paths, thresholds), and make each statement verifiable. Writing good ADRs works the same Decision section through both phrasings and shows what each one compiles into.

The compile pipeline scores each generated directive on token specificity, MUST/NEVER usage, grep-ability, and ambiguity. Run /edikt:adr:review after writing to check both human quality and directive quality.

User extension points ​

The co-located <ADR>.edikt.yaml sidecar has two lists you can modify:

  • manual_directives: — add rules compile missed. These always ship into the topic file.
  • suppressed_directives: — reject auto-generated rules you disagree with. These are always filtered out.

directives[] is extractor-owned but editable: add an entry with a real source_excerpts quote to backfill a missed rule, or delete an entry to suppress one. /edikt:adr:review cross-checks the sidecar against the prose body and warns on drift.

See Extensibility for the full extension surface.

Commands ​

CommandWhat it does
/edikt:adr:newCreate a new ADR from natural language input
/edikt:adr:compileRegenerate the ADR's sidecar (<ADR>.edikt.yaml)
/edikt:adr:reviewReview language quality + directive LLM compliance

Next steps ​

Released under the Elastic License 2.0. Free to use, not for resale.

Created by @dcsg