A structured framework for documenting the context, rationale, and consequences of significant technical choices within a project.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install architecture-decision-records
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install architecture-decision-records using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Architecture Decision Records (ADRs)?
Architecture Decision Records (ADRs) are lightweight documentation files that capture the 'why' behind technical decisions. By implementing these Openclaw Skills, teams can build a permanent institutional memory that survives developer turnover and project scaling. Unlike traditional documentation that grows stale, ADRs represent a point-in-time record of a decision, its drivers, and the resulting trade-offs, ensuring that future maintainers understand the forces that shaped the current architecture.
ADRs are stored directly in version control, making them a first-class citizen of the codebase. They provide a clear audit trail of how a system evolved, covering everything from framework adoption to database selection. This approach replaces tribal knowledge with a transparent, searchable history of engineering logic.
Architecture Decision Records (ADRs) Use Cases
- Adopting new frameworks, programming languages, or major libraries.
- Deciding between architectural patterns like microservices versus monoliths.
- Selecting database technologies, cloud providers, or infrastructure tools.
- Defining API design standards, security protocols, and integration patterns.
- Documenting any technical choice that would be difficult or costly to reverse later.
How Architecture Decision Records (ADRs) Works
- Identify a decision point that impacts the project's long-term structure or maintenance.
- Create a new record using a standardized template to document the context and problem statement.
- Outline the considered options, weighing the pros and cons of each potential solution.
- Formalize the decision and explicitly list the positive and negative consequences.
- Submit the ADR for peer review to gain team consensus and ensure all risks are identified.
- Merge the record into the repository and update the central index for visibility.
- Follow the lifecycle from Proposed to Accepted, or use new ADRs to Supersede outdated decisions.
Architecture Decision Records (ADRs) Setup
The most efficient way to manage these records is through the use of dedicated CLI tools that integrate with your existing workflow.
# Install the adr-tools utility
brew install adr-tools
# Initialize the directory structure within your project
adr init docs/adr
# Create a new record for a technical decision
adr new "Adopt PostgreSQL for Primary Storage"
# Update the central index to reflect recent changes
adr generate toc > docs/adr/README.md
Architecture Decision Records (ADRs) Data Schema & Taxonomy
Architecture Decision Records follow a strict organizational taxonomy to ensure they remain accessible and parseable by both humans and automation tools.
| Component | Format | Purpose |
|---|---|---|
| ID & Title | NNNN-title.md |
Provides a chronological, unique identifier for every decision. |
| Status | String | Tracks the current state (Proposed, Accepted, Rejected, Deprecated, Superseded). |
| Context | Markdown | Describes the forces at play and the specific problem being solved. |
| Consequences | List | Explicitly details the trade-offs, including positive gains and negative risks. |
| Index | Table | A README.md file that maps IDs to titles and statuses for quick navigation. |
Architecture Decision Records (ADRs) Advanced Features
- Automated Superseding: Use Openclaw Skills tools to automatically link new decisions to the records they replace, maintaining a clear lineage.
- Y-Statement Summaries: Implement high-density one-liner formats for rapid alignment on complex microservice architectural choices.
- CI/CD Integration: Automatically validate ADR formatting and index synchronization during the pull request process.
- Cross-Linking: Reference related ADRs to create a web of technical dependencies and contextual history.
SKILL.md
Loading
Related Openclaw Skills
API Versioning Patterns
A comprehensive guide to implementing resilient API versioning strategies, deprecation cycles, and seamless migration patterns.
Rate Limiting Patterns
A comprehensive technical guide from Openclaw Skills for implementing robust rate limiting algorithms and distributed throttling strategies to protect APIs.
Error Handling Patterns
A comprehensive framework for implementing resilient error management strategies across various programming languages and architectural layers.
API Development
A comprehensive meta-skill that orchestrates the entire API lifecycle from initial design and specification to testing and deployment.
Architecture Patterns
A comprehensive guide to implementing Clean Architecture, Hexagonal, and DDD patterns for robust backend systems using Openclaw Skills.
Article Illustrator
A specialized agent skill that analyzes written content to generate and insert consistent, contextually relevant illustrations using a unique Type x Style framework.
Featured*
