Skip to content

Commit d697f2e

Browse files
feat(skills): add architecture-decision-records skill (anomalyco#555)
* feat(skills): add architecture-decision-records skill Adds a skill that captures architectural decisions made during coding sessions as structured ADR documents (Michael Nygard format). Features: - Auto-detects decision moments from conversation signals - Records context, alternatives considered with pros/cons, and consequences - Maintains numbered ADR files in docs/adr/ with an index - Supports ADR lifecycle (proposed → accepted → deprecated/superseded) - Categorizes decisions worth recording vs trivial ones to skip - Integrates with planner, code-reviewer, and codebase-onboarding skills Includes Antigravity support via .agents/skills/ and openai.yaml. * fix: address review feedback on ADR skill - Add missing "why did we choose X?" read-ADR trigger to .agents/ copy - Add canonical-reference link to .agents/ SKILL.md pointing to full version - Remove integration reference to non-existent codebase-onboarding skill * fix: add initialization step and sync .agents/ trigger - Add Step 1 to workflow: initialize docs/adr/ directory, README.md index, and template.md on first use when directory doesn't exist - Add "API design" to .agents/ alternatives trigger to match canonical version * fix: address ADR workflow gaps and implicit signal safety - Init step: seed README.md with index table header so Step 8 can append rows correctly on first ADR - Add read-path workflow: graceful handling when docs/adr/ is empty or absent ("No ADRs found, would you like to start?") - Implicit signals: add "do not auto-create without user confirmation" guard, tighten triggers to require conclusion/rationale not just discussion, remove overly broad "testing strategy" trigger * fix: require user confirmation before creating files - Canonical SKILL.md: init step now asks user before creating docs/adr/ - .agents/ condensed version: add confirmation gate for implicit signals and explicit consent step before any file writes * fix: require user approval before writing ADR file, add refusal path * fix: remove .agents/ duplicate, keep canonical in skills/ --------- Co-authored-by: vazidmansuri005 <[email protected]>
1 parent 0efd6ed commit d697f2e

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

  • skills/architecture-decision-records
Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
name: architecture-decision-records
3+
description: Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
4+
origin: ECC
5+
---
6+
7+
# Architecture Decision Records
8+
9+
Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.
10+
11+
## When to Activate
12+
13+
- User explicitly says "let's record this decision" or "ADR this"
14+
- User chooses between significant alternatives (framework, library, pattern, database, API design)
15+
- User says "we decided to..." or "the reason we're doing X instead of Y is..."
16+
- User asks "why did we choose X?" (read existing ADRs)
17+
- During planning phases when architectural trade-offs are discussed
18+
19+
## ADR Format
20+
21+
Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:
22+
23+
```markdown
24+
# ADR-NNNN: [Decision Title]
25+
26+
**Date**: YYYY-MM-DD
27+
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
28+
**Deciders**: [who was involved]
29+
30+
## Context
31+
32+
What is the issue that we're seeing that is motivating this decision or change?
33+
34+
[2-5 sentences describing the situation, constraints, and forces at play]
35+
36+
## Decision
37+
38+
What is the change that we're proposing and/or doing?
39+
40+
[1-3 sentences stating the decision clearly]
41+
42+
## Alternatives Considered
43+
44+
### Alternative 1: [Name]
45+
- **Pros**: [benefits]
46+
- **Cons**: [drawbacks]
47+
- **Why not**: [specific reason this was rejected]
48+
49+
### Alternative 2: [Name]
50+
- **Pros**: [benefits]
51+
- **Cons**: [drawbacks]
52+
- **Why not**: [specific reason this was rejected]
53+
54+
## Consequences
55+
56+
What becomes easier or more difficult to do because of this change?
57+
58+
### Positive
59+
- [benefit 1]
60+
- [benefit 2]
61+
62+
### Negative
63+
- [trade-off 1]
64+
- [trade-off 2]
65+
66+
### Risks
67+
- [risk and mitigation]
68+
```
69+
70+
## Workflow
71+
72+
### Capturing a New ADR
73+
74+
When a decision moment is detected:
75+
76+
1. **Initialize (first time only)** — if `docs/adr/` does not exist, ask the user for confirmation before creating the directory, a `README.md` seeded with the index table header (see ADR Index Format below), and a blank `template.md` for manual use. Do not create files without explicit consent.
77+
2. **Identify the decision** — extract the core architectural choice being made
78+
3. **Gather context** — what problem prompted this? What constraints exist?
79+
4. **Document alternatives** — what other options were considered? Why were they rejected?
80+
5. **State consequences** — what are the trade-offs? What becomes easier/harder?
81+
6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment
82+
7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files.
83+
8. **Update the index** — append to `docs/adr/README.md`
84+
85+
### Reading Existing ADRs
86+
87+
When a user asks "why did we choose X?":
88+
89+
1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
90+
2. If it exists, scan `docs/adr/README.md` index for relevant entries
91+
3. Read matching ADR files and present the Context and Decision sections
92+
4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
93+
94+
### ADR Directory Structure
95+
96+
```
97+
docs/
98+
└── adr/
99+
├── README.md ← index of all ADRs
100+
├── 0001-use-nextjs.md
101+
├── 0002-postgres-over-mongo.md
102+
├── 0003-rest-over-graphql.md
103+
└── template.md ← blank template for manual use
104+
```
105+
106+
### ADR Index Format
107+
108+
```markdown
109+
# Architecture Decision Records
110+
111+
| ADR | Title | Status | Date |
112+
|-----|-------|--------|------|
113+
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
114+
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
115+
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |
116+
```
117+
118+
## Decision Detection Signals
119+
120+
Watch for these patterns in conversation that indicate an architectural decision:
121+
122+
**Explicit signals**
123+
- "Let's go with X"
124+
- "We should use X instead of Y"
125+
- "The trade-off is worth it because..."
126+
- "Record this as an ADR"
127+
128+
**Implicit signals** (suggest recording an ADR — do not auto-create without user confirmation)
129+
- Comparing two frameworks or libraries and reaching a conclusion
130+
- Making a database schema design choice with stated rationale
131+
- Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
132+
- Deciding on authentication/authorization strategy
133+
- Selecting deployment infrastructure after evaluating alternatives
134+
135+
## What Makes a Good ADR
136+
137+
### Do
138+
- **Be specific** — "Use Prisma ORM" not "use an ORM"
139+
- **Record the why** — the rationale matters more than the what
140+
- **Include rejected alternatives** — future developers need to know what was considered
141+
- **State consequences honestly** — every decision has trade-offs
142+
- **Keep it short** — an ADR should be readable in 2 minutes
143+
- **Use present tense** — "We use X" not "We will use X"
144+
145+
### Don't
146+
- Record trivial decisions — variable naming or formatting choices don't need ADRs
147+
- Write essays — if the context section exceeds 10 lines, it's too long
148+
- Omit alternatives — "we just picked it" is not a valid rationale
149+
- Backfill without marking it — if recording a past decision, note the original date
150+
- Let ADRs go stale — superseded decisions should reference their replacement
151+
152+
## ADR Lifecycle
153+
154+
```
155+
proposed → accepted → [deprecated | superseded by ADR-NNNN]
156+
```
157+
158+
- **proposed**: decision is under discussion, not yet committed
159+
- **accepted**: decision is in effect and being followed
160+
- **deprecated**: decision is no longer relevant (e.g., feature removed)
161+
- **superseded**: a newer ADR replaces this one (always link the replacement)
162+
163+
## Categories of Decisions Worth Recording
164+
165+
| Category | Examples |
166+
|----------|---------|
167+
| **Technology choices** | Framework, language, database, cloud provider |
168+
| **Architecture patterns** | Monolith vs microservices, event-driven, CQRS |
169+
| **API design** | REST vs GraphQL, versioning strategy, auth mechanism |
170+
| **Data modeling** | Schema design, normalization decisions, caching strategy |
171+
| **Infrastructure** | Deployment model, CI/CD pipeline, monitoring stack |
172+
| **Security** | Auth strategy, encryption approach, secret management |
173+
| **Testing** | Test framework, coverage targets, E2E vs integration balance |
174+
| **Process** | Branching strategy, review process, release cadence |
175+
176+
## Integration with Other Skills
177+
178+
- **Planner agent**: when the planner proposes architecture changes, suggest creating an ADR
179+
- **Code reviewer agent**: flag PRs that introduce architectural changes without a corresponding ADR

0 commit comments

Comments
 (0)