architectural-knowledge-management

---
name: architectural-knowledge-management
description: >
 Architectural Knowledge Management (AKM) via Architectural Decision Records (ADRs).
 Use this capability to create, review, update, query, supersede, or deprecate ADRs that document significant technical decisions. Each ADR should capture: context, decision, alternatives considered, rationale, and consequences (positive and negative).
 Trigger when users mention: “ADR,” “decision record,” “architecture decision,” “decision log,” “why did we choose,” “document this decision,” “what was the rationale,” “record this choice,” “capture the decision,” or “AKM.” Also trigger when making major technical choices (e.g., framework, database, API style, deployment, auth), even if ADR isn’t explicitly requested.
 Especially important in persistent, agentic, or multi-session workflows where decisions must remain referenceable. Integrates with architecture-design-spec (Architectural Decisions section feeds ADRs) and ears-planning-method (ADR outcomes constrain requirements and plans).

---

# Architectural Knowledge Management (AKM)

Capture, maintain, and query architectural decisions so they persist as first-class project
artifacts. Every ADR is a conversation with a future developer (or a future Claude session)
explaining *why* a choice was made, not just *what* was chosen.

## Why This Matters for Agentic Workflows

In Claude Code and similar agentic contexts, decisions made in one session evaporate by the
next. ADRs solve this: they are the persistent memory of architectural intent. When Claude
encounters an existing decision log, it can ground its work in established constraints rather
than re-deriving (or contradicting) past choices. This makes ADRs a **context management
tool**, not just documentation.

---

## Modes of Operation

| Mode | Trigger | What happens |
|------|---------|-------------|
| **Create** | User is making a decision or asks to record one | Draft a new ADR |
| **Query** | User asks "why did we…" or "what was the decision on…" | Search the decision log, summarize relevant ADRs |
| **Update** | Decision needs amendment, superseding, or deprecation | Update status, link to successor ADR |
| **Review** | User asks to audit decisions or prepare for a review | Assess ADR coverage, flag stale or missing records |
| **Initialize** | No decision log exists yet | Set up `docs/decisions/` structure with ADR-0000 |

---

## 1. ADR Format — MADR 4.0 (Default)

Use MADR 4.0 as the default template. It balances structure with leanness. Read
`references/templates.md` for the full template, the minimal template, and alternative
formats (Nygard, Y-Statement) if the project already uses a different convention.

### Mandatory Sections (Minimal ADR)

Every ADR MUST include at minimum:

```markdown
---
status: "{proposed | accepted | rejected | deprecated | superseded}"
date: {YYYY-MM-DD}
---

# {Short Noun Phrase — the Decision Title}

## Context and Problem Statement

{What is the issue? What forces are at play? Value-neutral facts.}

## Considered Options

1. {Option A}
2. {Option B}
3. {Option C}

## Decision Outcome

Chosen option: "{Option B}", because {1-2 sentence justification}.
```

### Full ADR (Standard)

Add these sections when the decision warrants deeper analysis. Omit empty sections — don't
pad.

```markdown
---
status: "{proposed | accepted | rejected | deprecated | superseded}"
date: {YYYY-MM-DD}
decision-makers: {list of people or roles}
consulted: {stakeholders consulted}
informed: {stakeholders informed after the fact}
---

# {Short Noun Phrase — the Decision Title}

## Context and Problem Statement

{The forces at play — technical, organizational, political, economic. State facts,
not opinions. Name the ASR(s) this addresses if applicable.}

## Decision Drivers

* {Driver 1 — e.g., "Must support 10k concurrent connections"}
* {Driver 2 — e.g., "Team has no Go experience"}
* {Driver 3 — e.g., "Budget ceiling of $500/mo for infrastructure"}

## Considered Options

1. {Option A}
2. {Option B}
3. {Option C}

## Decision Outcome

Chosen option: "{Option B}", because {justification linking back to drivers}.

### Consequences

* Good, because {positive consequence}
* Good, because {another positive consequence}
* Bad, because {negative consequence or tradeoff accepted}
* Neutral, because {consequence that is neither clearly good nor bad}

### Confirmation

{How will compliance with this decision be verified? Code review checklist item,
automated test, ArchUnit rule, deployment gate, etc.}

## Pros and Cons of the Options

### {Option A}

{Brief description or example.}

* Good, because {argument}
* Bad, because {argument}

### {Option B}

{Brief description or example.}

* Good, because {argument}
* Good, because {argument}
* Bad, because {argument}

### {Option C}

{Brief description or example.}

* Good, because {argument}
* Bad, because {argument}

## More Information

{Links to spikes, RFCs, benchmarks, related ADRs, or external references.
Also record follow-up decisions needed.}
```

---

## 2. Creating ADRs

### When to Create

Create an ADR when a decision:
- Affects the system's structure, non-functional properties, dependencies, or interfaces
- Has multiple viable alternatives that were (or should be) evaluated
- Would be non-obvious to a new team member encountering the codebase
- Constrains future implementation choices
- Represents a significant cost, risk, or irreversibility

**Err on the side of capturing.** A 5-minute ADR now saves hours of archaeology later.

### Sizing

| Decision weight | ADR depth | Example |
|----------------|-----------|---------|
| **Lightweight** | Minimal template (3 sections) | "Use pnpm over npm" |
| **Standard** | Full template | "PostgreSQL over DynamoDB for the order service" |
| **Heavyweight** | Full template + linked spike/RFC | "Event sourcing for the audit trail subsystem" |

### Numbering and Naming

```
docs/decisions/
├── 0000-use-madr-for-decision-records.md
├── 0001-use-postgresql-for-order-service.md
├── 0002-adopt-event-driven-architecture.md
└── ...
```

- **NNNN** — zero-padded sequential number
- **title-with-dashes** — present-tense imperative verb phrase preferred (e.g.,
  `use-postgresql`, `adopt-event-sourcing`, `separate-auth-service`)
- Extension: `.md`

### Writing Rules

1. **One decision per ADR.** If you're writing "and" between two distinct choices, split
   them into separate ADRs that reference each other.

2. **Context is value-neutral.** State facts and forces, not preferences. The Decision
   section is where you take a position.

3. **Name all considered options.** Including the ones you rejected. Future readers need to
   know what was evaluated, not just what won.

4. **Consequences are honest.** List the bad alongside the good. Every decision has
   tradeoffs — pretending otherwise erodes trust in the log.

5. **Write for a future reader.** Full sentences, active voice, enough context that someone
   unfamiliar with the discussion can understand the reasoning. Nygard's original guidance:
   write as if having a conversation with a future developer.

6. **Keep it short.** One to two pages. If you need more, link to a spike document or RFC
   and summarize the key findings in the ADR.

7. **Link related ADRs.** Use "Supersedes ADR-NNNN" in status metadata or "See also
   ADR-NNNN" in the More Information section to maintain the decision graph.

---

## 3. ADR Lifecycle

```
Proposed → Accepted
              ↓
         [active use]
              ↓
    Deprecated ←or→ Superseded by ADR-NNNN
```

### Status Transitions

| From | To | When | Action |
|------|----|------|--------|
| Proposed | Accepted | Team agrees | Update status, set date |
| Proposed | Rejected | Team decides against | Update status, document why in Consequences |
| Accepted | Deprecated | Decision no longer relevant (tech removed, feature killed) | Update status, note reason |
| Accepted | Superseded | New decision replaces this one | Update status with `superseded by ADR-NNNN`, create new ADR with `supersedes ADR-NNNN` |

### Mutability Guidance

ADRs are append-friendly, not immutable. When new information arrives:
- Add a dated amendment note to the existing ADR
- If the amendment changes the decision, create a new ADR that supersedes the original
- Never silently edit the Decision Outcome of an accepted ADR — that destroys the historical
  record

---

## 4. Querying the Decision Log

When the user asks about past decisions:

1. **Scan** `docs/decisions/` (or the project's configured ADR directory) for all `.md` files
2. **Read titles and status metadata** to build an index
3. **Search** for keywords in Context, Decision Drivers, and Decision Outcome sections
4. **Summarize** relevant ADRs, citing the ADR number and linking to the file
5. **Flag conflicts** if the user's current direction contradicts an accepted ADR

When working in Claude Code, always check for an existing decision log before making
architectural choices. If one exists, ground your work in it.

---

## 5. Reviewing and Auditing

### Coverage Check

For each major component or subsystem, verify:
- [ ] Technology choices are captured (language, framework, database, infra)
- [ ] Integration patterns are captured (sync vs async, REST vs gRPC, etc.)
- [ ] Security-relevant decisions are captured (auth approach, encryption, data residency)
- [ ] Decisions with known expiration are flagged (e.g., "revisit after v2 launch")

### Staleness Indicators

Flag ADRs that may need revisiting:
- Status is `accepted` but the technology/pattern is no longer in the codebase
- Decision is older than 18 months and references fast-moving dependencies
- Context mentions constraints that no longer apply (e.g., "budget limited to X" when budget
  has changed)
- Multiple recent changes work around or contradict the decision

### Decision Gaps

When reviewing a codebase or architecture, identify significant choices that lack ADRs:
- "The system uses Redis for caching but there's no ADR explaining why Redis over Memcached
  or application-level caching"
- "Authentication uses OAuth2 + PKCE but the decision isn't recorded"

Propose retrospective ADRs for these gaps.

---

## 6. Integration with Other Skills

### From architecture-design-spec

The `Architectural Decisions` section of a design spec is the natural input for ADRs:

| Design Spec produces | AKM consumes as |
|---------------------|-----------------|
| Architectural Decision (decision + rationale + constraints) | Seed for a new ADR (Context → Decision Outcome) |
| Component Responsibilities | Context for technology-choice ADRs |
| Open Questions | Triggers for future Proposed ADRs |

When a design spec includes architectural decisions, offer to formalize them as ADRs.

### Into ears-planning-method

Accepted ADRs constrain EARS plans:

| AKM produces | EARS consumes as |
|-------------|-----------------|
| Accepted ADR (decision + constraints) | Architectural constraint on implementation steps |
| ADR Consequences (bad) | Risk items or `[USER]` checkpoint triggers |
| ADR Confirmation criteria | Verification items (V#) |

When creating an EARS plan, scan accepted ADRs for constraints that affect the work.

### Decision Flow

```
[architecture-design-spec]    [ad-hoc decision during implementation]
         ↓                                  ↓
    Architectural                    Developer/agent
     Decisions                      recognizes choice
         ↓                                  ↓
         └──────────── AKM: Create ADR ─────┘
                            ↓
                    Decision Log updated
                            ↓
                 [ears-planning-method]
                 reads accepted ADRs as
                 constraints on plans
```

---

## 7. Initializing a Decision Log

When no decision log exists, set up the structure:

```bash
mkdir -p docs/decisions
```

Create `docs/decisions/0000-use-madr-for-decision-records.md` as the bootstrapping ADR —
it records the meta-decision of adopting ADRs using the MADR format. This serves as both
documentation and a working example of the format.

---

## 8. Anti-Patterns

| Don't | Do Instead |
|-------|-----------|
| Record every trivial choice ("use tabs vs spaces") | Focus on architecturally significant decisions — those with measurable impact on quality attributes |
| Write ADRs after the fact from memory months later | Capture decisions close to when they're made, even as rough drafts |
| Make the ADR a design document (pages of diagrams) | Keep the ADR focused on the decision; link to design docs for details |
| Silently edit accepted ADRs | Supersede with a new ADR that references the original |
| Store ADRs in a wiki nobody checks | Store ADRs in the repo, close to the code they govern |
| Skip the "Considered Options" section | Always list alternatives — it's the most valuable section for future readers |
| Treat "Proposed" as permanent | ADRs should move to Accepted or Rejected within a reasonable timeframe |
| Ignore ADRs during code review | Reference relevant ADRs when reviewing changes that touch decided areas |

---

## Calibrating Depth

| Context | Approach |
|---------|----------|
| User explicitly asks for an ADR | Create one at appropriate depth |
| User is making a significant choice during implementation | Suggest capturing it as an ADR; draft one if they agree |
| User asks "why did we choose X" | Query the decision log; if no ADR exists, offer to create a retrospective one |
| User asks for a decision log audit | Review mode — scan for coverage and staleness |
| User starts a new project | Offer to initialize the decision log structure |
| Working in Claude Code on a repo with `docs/decisions/` | Read the log before making architectural choices |