adr-gen

What This Skill Does

The adr-gen skill is an intelligent documentation assistant designed to streamline the creation of Architecture Decision Records (ADRs). By leveraging AI, it transforms a brief description of a technical decision into a professional, structured document that captures the 'why' behind your engineering choices. It automates the extraction of context, the listing of considered alternatives, the justification for the selected path, and the identification of long-term consequences or trade-offs. This eliminates the burden of manual documentation while ensuring your team maintains a high-quality historical archive of system design choices, making onboarding and architecture reviews significantly more efficient.

Installation

To integrate this skill into your OpenClaw environment, execute the following command in your terminal:

clawhub install openclaw/skills/skills/lxgicstudios/ai-adr

No complex configuration is required. Once installed, ensure you have Node.js 18 or higher available in your environment, as the tool leverages npx for execution, ensuring you are always running the most current version of the generator without manual updates.

Use Cases

This skill is indispensable for engineering teams aiming to build a culture of documentation without sacrificing velocity. Use it when you are initiating a new project, selecting a new database vendor, migrating from a monolithic architecture to microservices, or adopting a new language ecosystem like TypeScript. It is also highly effective during technical debt assessments, helping teams justify refactoring efforts by documenting the evolution of architectural constraints over time.

Example Prompts

1. "Generate an ADR for our decision to switch from REST to GraphQL for the public-facing API, focusing on our need for flexible data fetching and reduced bandwidth."
2. "Create an ADR document for migrating our storage layer to PostgreSQL, ensuring you mention our constraints regarding relational data integrity and high availability."
3. "Write an ADR for choosing Tailwind CSS for our new frontend project, highlighting the tradeoff between rapid UI development and increased bundle size."

Tips & Limitations

To maximize the utility of adr-gen, be as specific as possible in your initial prompt. The AI functions best when provided with concrete constraints and the specific alternatives you evaluated during the decision-making process. While the tool generates excellent documentation, treat the output as a draft; always review the generated consequences to ensure they align with your specific infrastructure and project goals. Remember to follow the best practice of numbering your ADRs sequentially to maintain an organized repository structure.