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
Install
spencerpauly/awesome-cursor-skills/architecture-decision-records · repository language: Python
git clone https://github.com/spencerpauly/awesome-cursor-skills
cp -r awesome-cursor-skills ~/.claude/skills/architecture-decision-recordsgenerated, unverified - the skill's exact subdirectory could not be determined; check the repository on GitHub
npx skillfed install spencerpauly/awesome-cursor-skills/architecture-decision-recordsFrequently 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.