What does this skill do?

The Skill Architectural Decision Log captures architectural decisions made during development sessions and generates structured ADR documents that include context, alternatives, and consequences. Each record is documented alongside the code in `docs/adr/`, so that the reasoning behind each choice is understandable to any future developer.

Record a decision
When the user says "record this decision" or "create an ADR," the skill extracts the core choice and generates the complete document.
Compare Alternatives
Document what other options were considered (framework, library, database, pattern) and why they were ruled out.
View Existing ADRs
When someone asks, "Why did we choose X?", look up the entry in the index and present the context and the corresponding ADR decision.
Planning with Trade-offs
During planning phases when architectural trade-offs are discussed, document the reasoning for the team.

Usage examples

🏗️ Log a database decision
We're going to use PostgreSQL instead of MongoDB because we need ACID transactions and strong relationships. Make a note of this decision.
⚖️ Decision on the framework
We've decided to use FastAPI instead of Flask because we need type validation and automatic OpenAPI documentation. Create an ADR.
🔍 Check Existing ADR
Why did we choose REST over GraphQL? Look up the corresponding ADR.
📋 Initialize the ADR repository
Initialize the docs/adr/ folder with the index and template to start documenting decisions.

Features

Structured ADR Format Generate documents with sections on Context, Decision, Alternatives Considered, and Consequences (positive, negative, risks).
Automatic Numbering Scan the existing ADRs and increment the counter to assign the correct number to each new record.
Index Maintained Update docs/adr/README.md with each new ADR to maintain a navigable index of all decisions.
Smart Query Search the index and provide the context and the decision for existing ADRs when someone asks about a past election.
Model by Michael Nygard Follow the concise format adapted for AI-assisted development: brief, written in the present tense, and readable in less than two minutes.

Frequently asked questions

ADRs are stored in the `docs/adr/` directory within the project repository, with the filename format `NNNN-title.md` and an entry in the `README.md` index.
No. The skill works only with access to the file system to create and read Markdown files in docs/adr/.
Yes. Ask, "Why did we choose X?" and the skill will search the ADR index and show you the context and the decision from the corresponding document.
No. The skill presents a draft to the user and only saves the file after explicit approval.
Architectural Decision Records — ADR Documentation with Claude AI

¿Prefieres escuchar el contenido? Genera la narración de audio con un clic.