documentation-and-adrs
This skill guides you to document decisions that matter—architectural choices, API shifts, and feature launches—by capturing the reasoning, constraints, and alternatives considered. It includes templates for Architecture Decision Records (ADRs) that preserve historical context, inline documentation patterns that explain intent rather than restating code, and structures for API and README documentation that help current and future engineers understand not just what was built, but why.
Documentation and ADRs records architectural decisions and their reasoning so future engineers understand the why behind technical choices.
AI-generated summary based on this skill's SKILL.md
Install
addyosmani/agent-skills/documentation-and-adrs · repository language: JavaScript
git clone https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills/documentation-and-adrs ~/.claude/skills/documentation-and-adrsnpx skillfed install addyosmani/agent-skills/documentation-and-adrsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
documentation-and-adrs guides you to create ADRs that capture the reasoning behind architectural choices. An ADR records a decision, its context (constraints and alternatives considered), and the consequences of choosing that path. Rather than just documenting what was built, ADRs preserve why that choice was made, preventing repeated debates and helping future developers understand the trade-offs your team weighed. Use templates that include title, status, context, decision, and consequences sections.
What should an ADR template for technical decisions include?
documentation-and-adrs recommends ADR templates with these core sections: a clear title, status (proposed/accepted/superseded), context explaining constraints and alternatives, the decision itself, and consequences (both positive and negative). This structure ensures you capture not just what you chose, but why you rejected other options and what impact your choice has. Templates help teams establish consistent documentation conventions for both human and agent collaboration.
Why document design rationale instead of just the code?
documentation-and-adrs emphasizes that code shows what was built, but rationale explains why. Documenting trade-offs and alternatives prevents your team from re-debating settled decisions and helps new engineers understand constraints that may no longer be obvious. Inline documentation focused on intent rather than restating syntax, combined with ADRs for major decisions, captures the reasoning that code alone cannot convey.
When should you write an ADR?
documentation-and-adrs suggests writing ADRs for significant architectural choices, API design decisions, major technology shifts, and feature launches that involve trade-offs. ADRs are most valuable when a decision affects multiple systems, has long-term consequences, or involves choosing between viable alternatives. Recording these decisions early prevents future confusion and creates a searchable history of your codebase's evolution.
How does documentation-and-adrs help prevent repeated debates?
documentation-and-adrs preserves historical decision context by capturing the constraints, alternatives, and reasoning behind each choice. When a decision is recorded with its rationale and consequences, team members and future developers can reference that context instead of re-litigating the same trade-offs. This creates institutional memory and accelerates onboarding for engineers joining the project.
What documentation conventions does this skill establish?
documentation-and-adrs provides patterns for ADR templates, inline documentation that explains intent, API design documentation, and README structures that help teams collaborate consistently. These conventions ensure that both human developers and AI agents can understand not just what code does, but why architectural choices were made, creating a shared foundation for team and agent collaboration.
SKILL.md
rendered from the published skill — quoted content, verbatim
Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Architecture Decision Records (ADRs)
ADRs capture the
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/documentation-and-adrs/SKILL.md