blueprint-derive-adr

通过分析代码结构、依赖项和文档，为现有项目生成架构决策记录（ADR）。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 blueprint-derive-prd……
你要根据代码追溯记录隐含的架构决策	你要从 README 中提取需求／角色，而不是决策
你需要将框架、数据库、状态管理选择记录为 ADR	改用 blueprint-derive-plans，一并生成 PRD、ADR 和 PRP
你正在熟悉现有项目，并希望记录决策	在编写／验证单个 ADR 时，改用 adr-relationships

用例：将现有项目接入 Blueprint Development 系统，并记录隐含的架构决策。

前提条件：

• 已初始化 Blueprint Development（存在 docs/blueprint/）
• 最好已存在 PRD（先运行 /blueprint:derive-prd）

步骤：

阶段 1：发现

1.1 检查前提条件

ls docs/blueprint/manifest.json
ls docs/prds/

如果尚未初始化 blueprint → 建议运行 /blueprint:init 如果没有 PRD → 建议先运行 /blueprint:derive-prd（推荐，但非必需）

1.2 创建 ADR 目录

mkdir -p docs/adrs

1.3 分析项目结构

探索代码库，识别架构模式：

使用 Explore Agent：

<Task subagent_type="Explore" prompt="Analyze project architecture: directory structure, major components, frameworks used, design patterns">

需要检查的关键领域：

• 目录结构：代码的组织方式
• 入口点：主文件、索引文件
• 配置：配置文件、环境处理
• 依赖项：包清单、导入项
• 数据层：数据库、ORM、数据模型
• API 层：路由、控制器、处理程序
• 测试：测试结构和框架

阶段 1.5：冲突分析

生成新 ADR 之前，检查是否存在可能冲突或相关的现有决策。

1.5.1 检查现有 ADR

ls docs/adrs/*.md 2>/dev/null | wc -l

如果存在 ADR，请分析其是否可能与即将记录的决策冲突。

1.5.2 确定新 ADR 的领域

将决策类别映射到领域：

决策类别	领域标签
状态管理	state-management
数据库／ORM	data-layer
框架选择	frontend-framework
API 设计	api-design
身份验证	authentication
测试策略	testing
样式方案	styling
构建工具	build-tooling
部署	deployment

1.5.3 扫描同一领域中的现有 ADR

对于每个要记录的领域：

grep -l "^domain: {domain}" docs/adrs/*.md

对于每个匹配且 status: Accepted 的 ADR：

• 提取 ADR 编号和标题
• 提取决策结果（所选选项）
• 计算冲突分数：
  • 领域相同：+0.3
  • 两者均为 Accepted：+0.2
  • 结果相反／不同：+0.4
  • 时间超过 6 个月：+0.1

1.5.4 显示潜在冲突

如果冲突分数 >= 0.7，提示用户：

question: "Found existing ADR in same domain: ADR-{XXXX} - {title}. How should the new decision relate?"
options:
  - label: "Supersede ADR-{XXXX}"
    description: "New ADR replaces the existing decision"
  - label: "Extend ADR-{XXXX}"
    description: "New ADR builds on the existing decision"
  - label: "Mark as related"
    description: "Decisions are connected but independent"
  - label: "No relationship"
    description: "Continue without linking"

保存关系选择，以便写入生成的 ADR 前置元数据。

1.5.5 处理多个冲突

如果同一领域存在多个潜在冲突：

• 逐一呈现，让用户决定
• 提供批量“全部取代”选项，以取代多个过时决策

阶段 2：识别架构决策

2.1 常见决策类别

类别	查找内容	决策示例
框架	package.json、导入语句	React 与 Vue、Express 与 Fastify
语言	文件扩展名、tsconfig	TypeScript 与 JavaScript
状态管理	Store 模式、上下文	Redux 与 Zustand 与 Context
样式	CSS 文件、样式导入	Tailwind 与 CSS-in-JS 与 SCSS
测试	测试文件、测试配置	Vitest 与 Jest、Playwright 与 Cypress
构建	构建配置、打包工具	Vite 与 Webpack、esbuild
数据库	ORM 配置、迁移	PostgreSQL 与 MongoDB、Prisma 与 Drizzle
API 风格	路由模式、架构	REST 与 GraphQL、tRPC
部署	Docker、CI 配置	容器与无服务器
Monorepo	工作区配置	Turborepo 与 Nx 与无

2.2 从代码推断决策

对于每个已识别的技术选择：

1. 记录当前实现
2. 考虑常见替代方案
3. 根据上下文／注释推断理由

2.3 与用户确认

对关键决策使用 AskUserQuestion：

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

阶段 3：生成 ADR

3.1 ADR 模板（MADR 格式）

为每项重要决策创建 ADR：

---
id: ADR-{NNNN}                          # Derived from filename (0003-*.md → ADR-0003)
date: {YYYY-MM-DD}
status: Accepted | Superseded | Deprecated | Proposed
deciders: {who made the decision}
domain: {domain-tag}                    # Optional: state-management, data-layer, etc.
supersedes: ADR-{XXXX}                  # Optional: if superseding another ADR
extends: ADR-{XXXX}                     # Optional: if extending another ADR
relates-to:                             # Cross-document references
  - PRD-{NNN}                           # Related PRDs
  - ADR-{YYYY}                          # Related ADRs
github-issues: []                       # Linked GitHub issues
name: blueprint-derive-adr
---

# ADR-{number}: {Title}

## 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:derive-adr*

3.2 生成标准 ADR

为以下常见决策生成 ADR（如适用）：

ADR	创建时机
0001-project-language.md	语言／运行时选择
0002-framework-choice.md	主框架选择
0003-testing-strategy.md	测试框架和方法
0004-styling-approach.md	CSS／样式方法
0005-state-management.md	状态处理（如适用）
0006-database-choice.md	数据库和 ORM（如适用）
0007-api-design.md	API 风格和模式
0008-deployment-strategy.md	部署方法

3.3 创建 ADR README

使用 blueprint-plugin/templates/adr-readme.md 中的模板，将 ADR README 模板写入 docs/adrs/README.md。

README 会自我说明：其中包含一个以编程方式运行的 fd + awk 命令，可按需生成 ADR 索引，从而避免静态表格与实际内容不一致。

编写时的自定义项：

• 如果在阶段 2 分析期间发现了未记录的决策，而用户选择不为其创建完整 ADR，请将其添加到 Proposed ADRs 部分：

  ## Proposed ADRs
  
  Decisions identified but not yet documented as full ADRs:
  
  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  

• 保留编程方式生成列表的命令原样不动——它可以替代静态索引

阶段 4：关系更新与验证

4.0 更新已取代的 ADR（双向一致性）

如果任何新 ADR 取代了现有 ADR：

1. 读取被取代的 ADR 文件

2. 更新其 frontmatter：

   • 将 status: Accepted 改为 status: Superseded
   • 添加 superseded_by: ADR-{new_number}

3. 更新 Links 部分（如果缺失则添加）：

   ## Links
   - Superseded by [ADR-{number}](./{filename}.md)
   

4. 报告更新：

   Updated ADR-{old_number}:
   - Status: Accepted → Superseded
   - Added: superseded_by: ADR-{new_number}
   - Updated Links section
   

示例：如果 ADR-0012 取代 ADR-0003：

• 在 ADR-0012 中：supersedes: ADR-0003
• 在 ADR-0003 中：
  • status: Superseded
  • superseded_by: ADR-0012
  • Links 部分引用 ADR-0012

4.1 更新清单

为每个 ADR 更新 docs/blueprint/manifest.json ID 注册表：

{
  "id_registry": {
    "documents": {
      "ADR-0003": {
        "path": "docs/adrs/0003-database-choice.md",
        "title": "Database Choice",
        "status": "Accepted",
        "domain": "data-layer",
        "relates_to": ["PRD-001"],
        "github_issues": [],
        "created": "{date}"
      }
    }
  }
}

4.2 提交摘要

✅ ADRs Generated: {count} records

**Location**: `docs/adrs/`

**Decisions documented**:
- ADR-0001: {title} - {status} [{domain}]
- ADR-0002: {title} - {status} [{domain}]
...

**Relationships established**:
- ADR-{new} supersedes ADR-{old} (status updated)
- ADR-{new} extends ADR-{existing}
- ADR-{new} related to ADR-{other}

**ADRs updated** (bidirectional consistency):
- ADR-{old}: status → Superseded, superseded_by → ADR-{new}

**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:derive-adr-validate` to check relationship consistency
4. Run `/blueprint:prp-create` for feature implementation
5. Run `/blueprint:generate-skills` for project skills

4.2 建议后续步骤

• 如果缺少 PRD → 建议使用 /blueprint:derive-prd
• 如果已准备好实施 → 建议使用 /blueprint:prp-create
• 如果架构正在演进 → 说明如何添加新的 ADR

阶段 5：更新清单

更新 docs/blueprint/manifest.json：

• 在 structure 中添加 has_adrs: true
• 将 ADR 添加到 generated_artifacts
• 更新 updated_at 时间戳

提示：

• 关注存在实际替代方案的决策（而非显而易见的选择）
• 将继承而来／遗留的决策标明为此类决策
• 将不确定的理由标记出来供用户审阅
• 保持 ADR 简洁——聚焦于“为什么”，而非实现细节
• 决策相关联时，引用相关 ADR

4.3 下一步提示词（使用 AskUserQuestion）：

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"

根据选择：

• “创建 PRP” → 运行 /blueprint:prp-create（询问功能名称）
• “生成项目技能” → 运行 /blueprint:generate-skills
• “审查并补充依据” → 显示需要关注的 ADR 文件
• “记录另一项决策” → 针对特定决策重新启动第 2 阶段
• “完成” → 退出

错误处理：

• 如果代码库规模较小 → 创建数量较少、范围较广的 ADR
• 如果存在冲突的模式 → 询问用户哪一种是有意采用的
• 如果依据不明确 → 标记为“需要补充依据”，以便用户提供输入