Architecture Decision Records
Capture significant technical choices in a structured format that explains the problem, alternatives weighed, and reasoning behind your decision. Use the provided template to create numbered records in your docs folder, then reference them from code comments when relevant. This ensures your team understands not just what was decided, but why—making it easier to revisit or build on those choices later.
Architecture Decision Records helps you document technical decisions with context, options, and rationale for future reference.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-04-28
Architecture Decision Records helps you document technical decisions with context, options, and rationale for future reference. Capture significant technical choices in a structured format that explains the problem, alternatives weighed, and reasoning behind your decision. Use the provided template to create numbered records in your docs folder, then reference them from code comments when relevant. This ensures your team understands not just what was decided, but why—making it easier to revisit or build on those choices later.
Use it when
- Architecture Decision Records should follow a structured format with key sections: a title and status.
- Architecture Decision Records enable you to track architectural choices by maintaining a numbered sequence of decisions in your repository.
Install
spencerpauly/awesome-cursor-skills/architecture-decision-records · repository language: Python
generated, unverified - the skill's exact subdirectory could not be determined; check the repository on GitHub
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I create architecture decision records?
Architecture Decision Records (ADRs) capture significant technical choices in a structured format. Start by creating a numbered file in your docs folder using the standard template, which includes sections for the decision context, alternatives considered, and your chosen solution with its rationale. Each ADR explains the problem you faced, the options you weighed, and why you selected your approach—making it easy for your team to understand not just what was decided, but why.
What should an ADR template for software projects include?
Architecture Decision Records should follow a structured format with key sections: a title and status, the decision context explaining the problem, the alternatives you considered, the chosen solution, and the rationale behind it. This template ensures consistency across your documentation and helps capture the reasoning behind design choices. By using this format consistently, your team can quickly understand the thinking behind each architectural decision and reference it when building on those choices later.
How can I track architectural choices over time?
Architecture Decision Records enable you to track architectural choices by maintaining a numbered sequence of decisions in your repository. Each ADR becomes a timestamped record of what was decided and why. Reference these records from your code comments when relevant, creating a living history of your system's evolution. This approach lets you audit past decisions, understand their outcomes, and revisit them if circumstances change—all while keeping your team aligned on the reasoning behind major technical directions.
What are ADR format best practices?
Architecture Decision Records work best when you keep them concise, focused on a single significant decision, and stored in version control alongside your code. Use a consistent numbering scheme and status indicators (Proposed, Accepted, Deprecated, Superseded). Write the rationale clearly so future team members understand not just the decision but the constraints and trade-offs involved. Reference ADRs from relevant code sections, and update them when decisions change to maintain an accurate record of your architectural evolution.
How does Architecture Decision Records help document design choices in code?
Architecture Decision Records provide a formal way to document design choices by capturing the problem, alternatives, and reasoning in structured files. You then reference these ADRs directly from code comments at decision points, creating a bridge between your implementation and its justification. This approach ensures your team understands the context behind each choice and can quickly locate the reasoning when reviewing or modifying code—making architectural knowledge explicit and persistent rather than lost in conversations or outdated emails.
Can Architecture Decision Records be shared with team members?
Yes, Architecture Decision Records are designed for team collaboration. Store them in your version control system so all team members can access, review, and discuss them. The structured format makes it easy for new team members to onboard by understanding past decisions and their rationale. ADRs serve as a shared reference point for architectural discussions, helping your team make informed decisions about future changes and avoiding revisiting settled questions without understanding the original context.
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Create and manage architecture decision records to document design choices”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Create and maintain Architecture Decision Records that capture the reasoning behind significant technical choices. This skill provides multiple templates—from standard MADR format to lightweight Y-statements—and guidance on when ADRs matter most, helping teams establish clear decision-making processes and onboard members through documented architectural history.
ADR Writer guides you through building comprehensive Architecture Decision Records that capture the reasoning behind key technical choices. It provides a structured template covering context, decision rationale, alternatives evaluated, tradeoffs made, and consequences—helping teams document and communicate architecture decisions clearly.
Documentation and ADRs helps teams record the reasoning behind significant technical decisions through structured Architecture Decision Records. Store decisions in `docs/decisions/` with context, alternatives considered, and consequences so future engineers and AI agents understand not just what was built, but why.
ADR Writer helps teams document architectural decisions in a structured, numbered format that captures context, alternatives considered, and consequences. It guides you through identifying decision-worthy choices, articulating constraints, evaluating options, and projecting impacts—ensuring future readers understand not just what was decided, but why.
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.
This skill captures architectural decisions made during coding sessions as structured ADR documents that live alongside your codebase. It detects decision moments, gathers context and alternatives, and maintains a searchable log so future developers understand the reasoning behind your architecture.
More skills Create Adr (NOASSERTION) · Adr Architecture (unlicensed) · adr (MIT)