Generate Architecture Decision Records from existing project structure and documentation
Analyzes project structure and code to generate Architecture Decision Records documenting key technical choices.
/plugin marketplace add laurigates/claude-plugins/plugin install blueprint-plugin@lgates-claude-pluginsGenerate Architecture Decision Records (ADRs) for an existing project by analyzing code structure, dependencies, and documentation.
Use Case: Onboarding existing projects to Blueprint Development system, documenting implicit architecture decisions.
Prerequisites:
docs/blueprint/ exists)/blueprint:prd first)Steps:
ls docs/blueprint/manifest.json
ls docs/prds/
If blueprint not initialized → suggest /blueprint:init
If no PRD → suggest /blueprint:prd first (recommended, not required)
mkdir -p docs/adrs
Explore the codebase to identify architectural patterns:
Use Explore agent:
<Task subagent_type="Explore" prompt="Analyze project architecture: directory structure, major components, frameworks used, design patterns">
Key areas to examine:
| Category | What to Look For | Example Decisions |
|---|---|---|
| Framework | package.json, imports | React vs Vue, Express vs Fastify |
| Language | File extensions, tsconfig | TypeScript vs JavaScript |
| State Management | Store patterns, context | Redux vs Zustand vs Context |
| Styling | CSS files, styled imports | Tailwind vs CSS-in-JS vs SCSS |
| Testing | Test files, test config | Vitest vs Jest, Playwright vs Cypress |
| Build | Build config, bundlers | Vite vs Webpack, esbuild |
| Database | ORM config, migrations | PostgreSQL vs MongoDB, Prisma vs Drizzle |
| API Style | Route patterns, schemas | REST vs GraphQL, tRPC |
| Deployment | Docker, CI config | Container vs serverless |
| Monorepo | Workspace config | Turborepo vs Nx vs none |
For each identified technology choice:
Use AskUserQuestion for key decisions:
question: "I found the project uses {technology}. Why was this chosen over alternatives?"
options:
- "Performance requirements" → document performance rationale
- "Team familiarity" → document team expertise factor
- "Ecosystem/community" → document ecosystem benefits
- "Specific feature needs" → ask for details
- "Legacy/inherited decision" → document as inherited
- "Other" → custom rationale
question: "Are there any architecture decisions you'd like to document that aren't visible in the code?"
options:
- "Yes, let me describe" → capture additional decisions
- "No, the inferred decisions are sufficient" → proceed
For each significant decision, create an ADR:
# ADR-{number}: {Title}
**Date**: {date}
**Status**: Accepted | Superseded | Deprecated
**Deciders**: {who made the decision}
## Context
{Describe the issue motivating this decision}
{What is the problem we're trying to solve?}
{What constraints exist?}
## Decision Drivers
- {driver 1, e.g., "Performance under high load"}
- {driver 2, e.g., "Developer experience"}
- {driver 3, e.g., "Maintainability"}
## Considered Options
1. **{Option 1}** - {brief description}
2. **{Option 2}** - {brief description}
3. **{Option 3}** - {brief description}
## Decision Outcome
**Chosen option**: "{Option X}" because {justification}.
### Positive Consequences
- {positive outcome 1}
- {positive outcome 2}
### Negative Consequences
- {negative outcome / tradeoff 1}
- {negative outcome / tradeoff 2}
## Pros and Cons of Options
### {Option 1}
- ✅ {pro 1}
- ✅ {pro 2}
- ❌ {con 1}
### {Option 2}
- ✅ {pro 1}
- ❌ {con 1}
- ❌ {con 2}
## Links
- {Related ADRs}
- {External documentation}
- {Discussion threads}
---
*Generated from project analysis via /blueprint:adr*
Generate ADRs for these common decisions (if applicable):
| ADR | When to Create |
|---|---|
0001-project-language.md | Language/runtime choice |
0002-framework-choice.md | Main framework selection |
0003-testing-strategy.md | Test framework and approach |
0004-styling-approach.md | CSS/styling methodology |
0005-state-management.md | State handling (if applicable) |
0006-database-choice.md | Database and ORM (if applicable) |
0007-api-design.md | API style and patterns |
0008-deployment-strategy.md | Deployment approach |
Generate an ADR index file:
# Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions for this project.
## Index
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-project-language.md) | {Title} | Accepted | {date} |
| [0002](0002-framework-choice.md) | {Title} | Accepted | {date} |
## Template
New ADRs should follow the [MADR template](https://adr.github.io/madr/).
## Creating New ADRs
Use `/blueprint:adr` or the `architecture-decisions` agent to create new ADRs.
✅ ADRs Generated: {count} records
**Location**: `docs/adrs/`
**Decisions documented**:
- ADR-0001: {title} - {status}
- ADR-0002: {title} - {status}
...
**Sources analyzed**:
- {list of analyzed files/patterns}
**Confidence levels**:
- High confidence: {list - clear from code}
- Inferred: {list - reasonable assumptions}
- Needs review: {list - uncertain}
**Recommended next steps**:
1. Review generated ADRs for accuracy
2. Add rationale where marked as "inferred"
3. Run `/blueprint:prp-create` for feature implementation
4. Run `/blueprint:generate-skills` for project skills
/blueprint:prd/blueprint:prp-createUpdate docs/blueprint/manifest.json:
has_adrs: true to structuregenerated_artifactsupdated_at timestampTips:
question: "ADRs generated. What would you like to do next?"
options:
- label: "Create a PRP for feature work (Recommended)"
description: "Start implementing a specific feature with /blueprint:prp-create"
- label: "Generate project skills"
description: "Create skills from PRDs for Claude context"
- label: "Review and add rationale"
description: "Edit ADRs marked as 'inferred' or 'needs rationale'"
- label: "Document another architecture decision"
description: "Manually add a new ADR"
- label: "I'm done for now"
description: "Exit - ADRs are saved"
Based on selection:
/blueprint:prp-create (ask for feature name)/blueprint:generate-skillsError Handling: