architect-clarify

architect-clarify

此技能的作用

找出现有 ADR 中尚未充分说明的部分，并通过有针对性的澄清问题加以完善。确保 ADR 完整、一致，并可用于生成架构。

你将担任架构审查员，通过以下方式确保 ADR 质量：

• 验证 ADR 是否符合 MADR 标准
• 识别后果或备选方案方面的缺漏
• 检测 ADR 之间或 ADR 与宪章之间的冲突
• 完善决策，提出有针对性的澄清问题

适用场景

在以下情况下使用此技能：

• 在 /architect-init 之后：在生成架构前完善初始 ADR
• ADR 审查：在重要里程碑前验证 ADR
• 新团队成员加入：确保新成员也能理解 ADR
• 解决冲突：解决已发现的不一致问题

在以下情况下不要使用此技能：

• 不存在 ADR：先使用 /architect-init 创建 ADR
• 棕地项目：使用 /architect-init 从代码中反向推导 ADR

流程

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（如果不为空）。

用户输入示例：

• "重点关注数据架构决策——我们正在重新考虑数据库选择"
• "安全相关的 ADR 需要更多细节，以便进行合规审查"
• "ADR-003 中的后果似乎不完整"
• 空输入：检查所有 ADR 的完整性

目标

找出现有 ADR 中尚未充分说明的部分，并通过有针对性的澄清问题加以完善。确保 ADR 完整、一致，并可用于生成架构。

ADR 质量检查清单

每份 ADR 都应包含：

• 清晰的背景，说明问题或机遇
• 明确的决策陈述
• 正面和负面后果
• 记录常见备选方案（中立地权衡利弊，而非写成“因……而拒绝”）
• 识别风险并提出缓解策略
• 状态准确（Proposed/Accepted/Deprecated/Superseded/Discovered）
• 与其他 ADR 不存在冲突
• 符合宪章原则
• 对于反向推导的 ADR，不得编造拒绝理由

大纲

1. 加载当前状态：从 {REPO_ROOT}/.adlc/drafts/adr/（单独文件格式）和 {REPO_ROOT}/docs/adlc/memory/constitution.md（旧版 {REPO_ROOT}/.adlc/memory/constitution.md 回退路径——双路径读取）解析 ADR

重要——路径解析：

• 设置脚本会输出 REPO_ROOT，请据此确定正确路径
• 从当前目录向上查找 .adlc 目录，以确定 REPO_ROOT
• 绝不要使用 .adlc/drafts/adr.md 之类的相对路径；始终使用 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
• 设置脚本会从 adr/ 目录读取单独的 ADR 文件
• 从子目录（例如子项目目录）运行时，.adlc 可能位于父目录中

2. 分析 ADR：根据质量检查清单检查每份 ADR
3. 识别缺漏：列出需要澄清的部分
4. 交互式完善：提出有针对性的问题以补足缺漏
5. 更新 ADR：将完善后的 ADR 写回文件

执行步骤

阶段 1：加载上下文

目标：确定当前 ADR 状态

1. 运行先决条件脚本：

   • 从仓库根目录执行 scripts/bash/setup-architect.sh
   • 解析 JSON，获取记忆文件的路径
   • 如果文件不存在，妥善处理错误

2. 加载 ADR 文件：

   • 读取 {REPO_ROOT}/.adlc/drafts/adr/adr.md 中的 ADR 列表
   • 从 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md 读取单独的 ADR 文件
   • 统计 ADR 总数，并确定各状态的分布

3. 加载宪章：

   • 如果 {REPO_ROOT}/docs/adlc/memory/constitution.md 或旧版 {REPO_ROOT}/.adlc/memory/constitution.md 回退路径存在，则读取相应文件
   • 提取原则以检查是否保持一致
   • 记录治理约束

4. 用户关注点：

   • 如果用户指定了特定 ADR 或关注领域，则缩小范围
   • 否则，审查所有 ADR

步骤 0：检测轻量级草稿格式

检查正在审查的草稿是否使用轻量级草稿模板（即 frontmatter 中包含 type、evidence、source、revisit-when 字段，且正文包含 ## Rejected Alternatives / ## Reason 章节，但不包含完整的正式模板章节）。

如果是轻量级草稿：

1. 阅读草稿中记录的字段（Context、Decision、Rejected Alternatives、Reason）
2. 转换为完整的正式模板：
   • ADR：完整的 MADR 格式，包含 Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs
   • PDR：完整的 PDR 格式，包含 Market Forces、Consequences、Alternatives Considered、Links
   • ChDR：完整的 ChDR 格式，包含 Issue Links、Commits、Consequences、Evidence
   • CDR：完整的 CDR 格式，包含 Context Type、Target Module、Descriptor、Evidence
   • EVAL：完整的评估格式，包含 Error Analysis、Pass/Fail Examples、Implementation Notes
3. 根据会话上下文补充内容（添加轻量级草稿中可能省略的细节）
4. 呈现补充完善后的草稿以供审查

如果已经是完整格式，则按常规流程进行审查。

阶段 2：ADR 分析

目标：找出每份 ADR 中的质量缺口

需检查的质量维度

1. 上下文完整性：

   • 问题是否表述清晰？
   • 是否记录了影响因素和驱动因素？
   • 决策范围是否明确？

2. 决策清晰度：

   • 决策是否可执行？
   • 实施方面的影响是否清晰？
   • 是否可以验证或测试该决策？

3. 后果覆盖度：

   • 是否记录了积极结果？
   • 是否承认了负面权衡？
   • 是否识别了风险并提出缓解措施？

4. 备选方案文档记录：

   • 是否至少列出 2 个备选方案？
   • 是否清楚说明了拒绝每个方案的理由？
   • 是否考虑过合理的选项？

5. ADR 之间的一致性：

   • 决策是否与其他 ADR 冲突？
   • 是否记录了 ADR 之间的依赖关系？
   • 术语是否一致？

6. 与宪章的一致性：

   • 决策是否符合 MUST 原则？
   • 是否处理了 SHOULD 原则？
   • 是否明确说明了违规情况的理由？

阶段 2.5：风险与缺口分析（跨领域）

目标：识别所有视图中未记录的运营缺口、技术债务、单点故障和安全问题

分析维度：

维度	检查的视图	检查内容
运营缺口	运营（3.7）、部署（3.6）	缺少监控、未定义值班安排、没有运行手册、回滚流程不清晰
技术债务	开发（3.5）、信息（3.3）	已弃用的依赖项、没有测试、遗留代码、架构模式债务
单点故障	部署（3.6）、并发（3.4）	单个数据库实例、没有冗余、关键路径瓶颈
安全问题	所有视图	数据未加密、没有身份验证、机密信息暴露、缺少审计跟踪

缺口识别流程：

1. 扫描每个视图：检查视图是否存在，找出缺失的关键章节，标记 [TODO]/[TBD] 区域
2. 跨视图分析：找出不一致之处（例如，声称“高可用”，但图中只显示单个实例）
3. 风险严重程度：CRITICAL（中断/泄露/损失）、HIGH（运营负担）、MEDIUM（债务）、LOW（文档记录）

缺口 ID 格式：基于章节编号（例如，3.6.1 = 部署视图，缺口 #1）

阶段 2.6：章程交叉引用

目标：检查 ADR 是否与章程重复，以及是否符合章程

分析：

1. 重复性检查：ADR 是否重述了章程原则？该决策是否已被章程规定？
2. 合规性检查：该决策是否违反 MUST 原则？是否在没有说明理由的情况下忽略了 SHOULD 原则？
3. 覆盖分类：这是否是有意偏离？理由是否充分？

章程交叉引用表：

问题类型	ADR	章程原则	所需操作
重复	ADR-002	§DataStorage 规定使用 PostgreSQL	删除或改为引用
违规	ADR-003	§Security 要求使用 JWT	添加覆盖理由或修改决策
不明确	ADR-004	未涉及缓存	明确两者的关系

阶段 3：识别差距

目标：确定需要澄清的事项的优先级

生成差距报告：

## ADR Clarification Report

### Summary
- Total ADRs: [N]
- Complete: [N]
- Needs Clarification: [N]

### Gaps by ADR

| ADR | Title | Gap Type | Severity | Priority |
|-----|-------|----------|----------|----------|
| ADR-001 | [Title] | Missing alternatives | HIGH | 1 |
| ADR-002 | [Title] | Incomplete consequences | MEDIUM | 2 |

### Cross-ADR Issues

| Issue | ADRs Affected | Description |
|-------|---------------|-------------|
| [Conflict] | ADR-001, ADR-003 | [Description of conflict] |

差距优先级

• 严重：违反章程、缺少决策声明
• 高：未记录备选方案、缺少后果
• 中：风险不完整、上下文不明确
• 低：措辞略需改进、可选细节

阶段 4：交互式完善

目标：通过有针对性的问题弥补差距

问题格式

对于每项需要澄清的差距：

## Clarification [N]: [ADR-XXX] - [Gap Type]

**Current State**: 
[Quote current ADR content]

**Gap Identified**: 
[Explain what's missing or unclear]

**Question**:
[Specific question to address the gap]

**Suggested Options** (if applicable):

| Option | Description |
|--------|-------------|
| A | [Option A] |
| B | [Option B] |
| C | [Custom response] |

Reply with your choice or provide additional context.

章程交叉引用问题

检测到章程问题时：

对于重复项：

## Clarification [N]: Constitution Duplication Detected

**Question**: How should this duplicate ADR be handled?

**ADR**: ADR-XXX - [Title]
**Constitution Principle**: §[Section] - [Principle Name]
**Issue**: This ADR documents a decision already mandated by constitution

**Options**:
| Option | Action | Result |
|--------|--------|--------|
| A | Remove ADR | Decision covered by constitution only |
| B | Convert to Reference | Keep ADR as "See Constitution §X" |
| C | Add Context | Keep ADR with "Aligns with Constitution §X" |
| D | Extend | Keep ADR as "Extends Constitution §X" |

Reply with your choice (A/B/C/D).

对于违规项（选项 A 为首选——修订章程）：

## Clarification [N]: Constitution Violation Detected ⭐

**Question**: How should this constitutional violation be resolved?

**ADR**: ADR-XXX - [Title]
**Decision**: [What the ADR decides]
**Constitution Principle**: §[Section] - [Principle]
**Conflict**: [How they conflict]

**The constitution should evolve with the project's needs.**

**⭐ RECOMMENDED: A. Amend Constitution**
Update constitution §[Section] to accommodate this decision. This establishes a new principle for future decisions.

**Alternative Options**:
B. Override in ADR - Document justification for deviation
C. Revise ADR - Change decision to comply with constitution
D. Remove ADR - Delete and follow existing constitution

**Consider Amendment If**:
- [ ] This decision will be used again in the future
- [ ] Team's approach has evolved since constitution was written
- [ ] Existing principle is too restrictive for current needs

**Amendment Text**: [If choosing A, provide the specific constitutional amendment]

Reply with: "A [amendment text]" or "B/C/D [reasoning]"

澄清规则

• 每次只提出一个澄清问题
• 按严重程度排序——优先处理严重/高优先级差距
• 对于章程违规，选项 A（修订）为首选
• 每个会话最多进行 5 项澄清（如果存在架构，则增加到 10 项）
• 允许用户跳过非关键澄清
• 每次回答后总结更改
• 用户可以说“done”以提前结束澄清

阶段 5：更新 ADR

目标：将完善后的 ADR 写回文件

1. 应用澄清结果：

   • 使用新内容更新 ADR 章节
   • 保留结构和格式
   • 更新“Last Updated”时间戳

2. 解决冲突：

   • 如果发现 ADR 之间存在冲突，提出解决方案
   • 记录优先采用某个 ADR 而非另一个的决定
   • 在相关 ADR 之间添加交叉引用

3. 更新索引：

   • 如果标题发生变化，刷新 ADR 索引表
   • 在适用时更新状态

4. 写入文件：

   • 以原子方式写入各个 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md 文件
   • 保留所有未修改的 ADR
   • 更新后，设置脚本会自动重新生成 adr.md 和 adr.md 索引

阶段 5.5：ADR 批准 ⭐

目标：在生成架构之前，获得用户确认以批准 ADR

此步骤至关重要，因为 implement 只会处理状态为“Accepted”的 ADR。状态为“Discovered”或“Proposed”的 ADR 会被跳过。

批准请求

## ADR Approval ⭐

**Total ADRs**: [N]
**Status Distribution**:
- Accepted: [N]
- Proposed: [N]
- Discovered: [N]

**⚠️ Important**: Only "Accepted" ADRs will be processed by `/architect-implement`

### Options

| Option | Action |
|--------|--------|
| A | Accept All - Change Proposed/Discovered → Accepted |
| B | Review Specific - Select individual ADRs to accept |
| C | Defer - Keep current status, decide later |

**Note**: You can also run `/architect-clarify` again later to approve additional ADRs.

Reply with A, B, or C (or "done" to skip).

批量批准（选项 A）

如果用户选择选项 A：

## Confirm Bulk Approval

Change [N] ADRs from Proposed/Discovered → Accepted?

| ADR | Current Status | New Status |
|-----|----------------|-------------|
| ADR-001 | Proposed | Accepted |
| ADR-002 | Discovered | Accepted |

Reply with "yes" to confirm or "no" to cancel.

选择性批准（选项 B）

如果用户选择选项 B，逐一展示 ADR：

## ADR Approval: ADR-XXX

**Title**: [Title]
**Current Status**: [Proposed/Discovered]
**Context**: [Brief summary]

**Options**:
| Option | Action |
|--------|--------|
| A | Accept - Change to "Accepted" |
| B | Keep - Keep current status |
| C | Skip - Move to next ADR |

Reply with A, B, or C for ADR-XXX.

批准后

批准后（或用户选择 C 暂缓后）：

## ADRs Approved

**Status Changes Applied**:
- ADR-001: Proposed → Accepted
- ADR-002: Discovered → Accepted
- ADR-007: Kept as Proposed

**Ready for Implementation**:
- Accepted ADRs: [N]
- Pending Approval: [N]

Run `/architect-implement` to generate AD.md from accepted ADRs.

批准后的状态更新

批准后，必须写入工作流状态文件。如果目录不存在，则创建该目录，然后写入 {REPO_ROOT}/.adlc/architect/state.json：

mkdir -p {REPO_ROOT}/.adlc/architect

将以下 JSON 内容写入文件（将 [N] 替换为实际批准的 ADR 数量，并将时间戳替换为当前时间）：

{
  "workflow": {
    "clarify_completed": true,
    "clarify_completed_at": "2024-01-20T10:30:00Z",
    "adrs_approved_count": [N],
    "implement_started": false,
    "implement_started_at": null
  }
}

重要：执行 /architect-implement 前，必须先创建此工作流状态文件。 implement 命令会在预检验证期间检查此状态。如果跳过此步骤，implement 命令将因验证错误而停止。

关键规则

非破坏性完善

• 绝不删除现有 ADR，除非用户明确批准
• 更新措辞时保留原始意图
• 添加，不要替换后果和备选方案
• 使用更新时间戳标记更改

有针对性的澄清

• 一次只问一个问题
• 确保问题具体且可回答
• 尽可能提供建议选项
• 尊重用户的时间——最多进行 5 次澄清

宪章权威性

• 始终标记违反宪章的情况
• 未经明确说明理由，ADR 不能覆盖 MUST 原则
• 如果冲突具有系统性，建议更新宪章

质量优先于数量

• 重点关注影响实施的实质性差距
• 除非用户提出要求，否则跳过表面改进
• 如果仍存在重大差距，暂缓处理次要问题

完成报告

澄清结束后（所有差距均已解决，或用户表示“完成”）：

## ADR Clarification Complete

**Changes Made**:
- ADR-001: Updated consequences section
- ADR-002: Added Common Alternatives (neutral trade-offs)
- ADR-003: Resolved conflict with ADR-001
- Constitution: Amended §DataStorage to allow NoSQL for document flexibility

**Risks & Gaps Status**:
- Critical gaps identified: [N] → [N resolved]
- High priority gaps: [N] → [N resolved]
- Cross-view inconsistencies: [N] → [N resolved]
- Integration with AD sections: [N updates]

**Remaining Gaps** (deferred):
- 3.6.2: Minor operational documentation (LOW)

**Cross-ADR Consistency**: ✅ Verified

**Constitution Alignment**:
- Duplicates resolved: [N]
- Violations addressed: [N]
- Constitution amended: [N] (if applicable)
- References added: [N]

**Recommended Next Steps**:
1. Review updated ADRs in `{REPO_ROOT}/.adlc/drafts/adr/adr.md`
2. Run `/architect-implement` to generate AD.md
3. Or run `/architect-specify` to create new ADRs for additional decisions

工作流状态

⚠️ 必需：在运行 /architect-implement 批准 ADR 之前，必须先运行 /architect-clarify。

状态工作流：

• init → “Discovered”（棕地）
• specify → “Proposed”（绿地）
• clarify → 请求批准 → “Accepted” ⭐
• implement → 仅读取“Accepted”，跳过 Discovered/Proposed

注意：不要虚构“Validated”等中间状态。用户批准后，ADR 会直接从 Discovered/Proposed 变为 Accepted。

上下文

$ARGUMENTS

后续步骤

clarify 完成后，运行 /architect-implement 以生成架构说明（AD.md）。

只有状态为 Accepted 的 ADR 才会纳入架构生成。如有需要，可在继续之前重新运行此技能以批准其他 ADR。

验证

此技能的具体输出：

• ADR 文件已更新，包含澄清后的内容，路径为 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
• ADR 索引已刷新，路径为 {REPO_ROOT}/.adlc/drafts/adr/adr.md
• 如果修订已获批准，则宪章已更新
• 工作流状态已写入 {REPO_ROOT}/.adlc/architect/state.json，其中 clarify_completed: true
• 至少有一个 ADR 的状态已变更为 Accepted，或已明确记录延期处理
• 跨 ADR 冲突已解决或记录
• 差距报告显示关键/高优先级差距已得到处理