{"enrichment":{"faq":[{"a":"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.","q":"How to write architecture decision records?"},{"a":"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.","q":"What should an ADR template for technical decisions include?"},{"a":"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.","q":"Why document design rationale instead of just the code?"},{"a":"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.","q":"When should you write an ADR?"},{"a":"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.","q":"How does documentation-and-adrs help prevent repeated debates?"},{"a":"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.","q":"What documentation conventions does this skill establish?"}],"shadow_tags":["decision-capture","architectural-rationale","knowledge-preservation","design-trade-offs","team-onboarding","technical-context","decision-lifecycle","future-proofing","intent-documentation"],"summary_rewrite":"This skill guides you to document decisions that matter\u2014architectural choices, API shifts, and feature launches\u2014by 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."},"files":[{"bytes":9782,"path":"skills/documentation-and-adrs/SKILL.md","sha256":"b867bb80fb681257c7625ae59a0dfd849b1fc0f0a2f0338e7923f38030df9793","url":"https://skillfed.io/files/addyosmani/agent-skills/documentation-and-adrs/2cac2932/SKILL.md"}],"id":"addyosmani/agent-skills/documentation-and-adrs","links":{"html":"https://skillfed.io/addyosmani/agent-skills/documentation-and-adrs","md":"https://skillfed.io/addyosmani/agent-skills/documentation-and-adrs.md","repo":"https://github.com/addyosmani/agent-skills"},"meta":{"agents_supported":[],"first_seen":"2026-07-28","forks":8697,"language":"JavaScript","last_updated":"2026-07-26","license":"MIT","name":"documentation-and-adrs","publisher":"addyosmani","stars":80654},"relations":{"categories":["documentation","software-engineering","knowledge-management"],"similar":[{"id":"shashankswe2020-ux/whoop-mcp/documentation-and-adrs"},{"id":"addyosmani/agent-skills/api-and-interface-design"},{"id":"wshobson/agents/architecture-decision-records"},{"id":"addyosmani/agent-skills/using-agent-skills"},{"id":"ancoleman/ai-design-components/generating-documentation"},{"id":"yonatangross/orchestkit/architecture-decision-record"},{"id":"Jeffallan/claude-skills/architecture-designer"},{"id":"tech-leads-club/agent-skills/create-adr"},{"id":"lyndonkl/claude/adr-architecture"},{"id":"softspark/ai-toolkit/architecture-decision"}]},"slug":{"owner":"addyosmani","repo":"agent-skills","skill":"documentation-and-adrs"},"version":"2cac2932"}