develop-adr
This skill guides you through creating an Architecture Decision Record that captures the reasoning behind significant technical or architectural choices. It follows Michael Nygard's lightweight format to ensure decisions are documented with their context, rationale, and trade-offs—preserving institutional knowledge for future team members. Use it when selecting technologies, establishing development patterns, or documenting constraints that shape your system.
develop-adr documents significant technical decisions using the Nygard format to capture context, rationale, and consequences.
AI-generated summary based on this skill's SKILL.md
Install
product-on-purpose/pm-skills/develop-adr · repository language: JavaScript
git clone https://github.com/product-on-purpose/pm-skills
cp -r pm-skills/skills/develop-adr ~/.claude/skills/develop-adrnpx skillfed install product-on-purpose/pm-skills/develop-adrFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write an architecture decision record?
develop-adr guides you through creating an Architecture Decision Record using Michael Nygard's lightweight format. Start by numbering your ADR sequentially, then document the decision's context (what problem you faced), the decision itself (what you chose), consequences (trade-offs and impacts), and alternatives considered. Include the status (Proposed, Accepted, Deprecated, Superseded) so teams understand the decision's current standing. This structured approach ensures your reasoning is preserved for future team members.
What should an ADR template for technical decisions include?
develop-adr's template covers: Title, Status, Context (the issue or problem), Decision (what was chosen), Consequences (positive and negative outcomes), and Alternatives (options that were rejected). Some ADRs also include Rationale (why this choice) and Related Decisions (links to dependent ADRs). This format keeps documentation lightweight yet complete, making it easy for teams to understand not just what was decided, but why and what trade-offs were accepted.
How do I record architectural decisions with develop-adr?
develop-adr helps you document architectural decisions by providing a structured, numbered format that captures context and consequences. Create a new ADR file for each significant choice—whether it's technology selection, design patterns, or system constraints. Include the decision's background, what you chose, and the trade-offs involved. Store ADRs in version control alongside your code so they evolve with your system and remain accessible to all team members.
Why document technical choices and preserve decision reasoning?
develop-adr emphasizes that documenting technical choices preserves institutional knowledge when team members leave or projects shift focus. Recording the context and rationale behind decisions prevents teams from re-debating settled choices or unknowingly repeating past mistakes. ADRs capture trade-offs explicitly, helping future developers understand constraints and assumptions. This lightweight documentation format makes it practical to maintain a decision history without heavyweight process overhead.
What's the difference between ADR numbering and status tracking?
develop-adr uses sequential numbering (ADR-001, ADR-002, etc.) to create an immutable audit trail of decisions in chronological order. Status tracking marks each ADR as Proposed (under consideration), Accepted (approved), Deprecated (no longer used), or Superseded (replaced by another ADR). Together, numbering and status let teams quickly find decisions, understand their evolution, and see which choices remain active versus historical.
When should I use develop-adr for database selection?
develop-adr is ideal for documenting database selection decisions because these choices have long-term architectural impact. Create an ADR that explains the problem (scalability, consistency, query patterns), the database you chose, consequences (operational overhead, learning curve, cost), and alternatives you rejected. This record helps onboard new team members, justifies the choice to stakeholders, and provides a reference if you later need to reconsider the decision.
SKILL.md
rendered from the published skill — quoted content, verbatim
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Architecture Decision Record (ADR)
An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.
When to Use
- Making significant technical decisions that affect system architecture
- Choosing between technology options (frameworks, databases, services)
- Establishing patterns that future development should
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 7 files
skills/develop-adr/HISTORY.md
skills/develop-adr/SKILL.md
skills/develop-adr/evals/output-scenarios/event-streaming.md
skills/develop-adr/evals/output-scenarios/search-datastore.md
skills/develop-adr/evals/trigger-fixtures.json
skills/develop-adr/references/EXAMPLE.md
skills/develop-adr/references/TEMPLATE.md