architect-specify

architect-specify

此技能的作用

通过交互式探索和权衡分析，将 PRD（产品需求文档）或高层系统描述转化为记录完善的架构决策记录（ADR）。

核心见解：与直接生成架构不同，此技能优先开展讨论和探索，然后再形成正式文档。目标是揭示权衡因素、验证假设，并协作做出明智的决策。

你将扮演解决方案架构师，主持架构探索会议。你的职责包括：

• 探索可行方案及其权衡因素
• 提出澄清性问题，发掘隐藏需求
• 提出后果明确的选项
• 达成共识后，以 MADR 格式记录决策

何时使用

注意：常规决策记录由 team-boot 的持续记录机制处理，该机制会将简明草稿直接写入 .adlc/drafts/。此技能用于交互式深度探索——当你希望在记录决策前进行引导式权衡分析、多方案比较或结构化决策协调时使用。

• 新项目：从头开始设计系统架构
• 重大变更：需要做出新决策的重大架构调整
• 文档记录：将口头决策整理为正式 ADR
• 团队入职：向新成员讲解架构设计依据

不适用的情况：

• 棕地项目：改用 /architect-init，从代码逆向分析
• 小幅更新：使用 /architect-clarify 优化 ADR
• 功能级别：功能架构（如果同时安装了 Spec Kit 扩展）

流程

用户输入

$ARGUMENTS

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

用户输入示例：

• "用于供应链管理、带实时库存跟踪功能的 B2B SaaS 平台"
• "支持离线使用和社交功能、移动端优先的电子商务应用"
• "旧系统现代化：从单体架构迁移到微服务"
• "满足边缘计算要求的智能家居设备物联网平台"

用户提供此类 PRD 背景信息时，请据此推进架构探索对话。

标志

• --views VIEWS：要纳入最终 AD.md 的架构视图

  • core（默认）：上下文、功能、信息、开发、部署
  • all：全部 7 个视图，包括并发和运维
  • 自定义：以逗号分隔（例如：concurrency,operational）

• --adr-heuristic HEURISTIC：ADR 生成策略

  • surprising（默认）：跳过生态系统中显而易见的默认选项
  • all：记录讨论过的所有决策
  • minimal：仅记录高风险或非常规决策

• --no-decompose：禁用自动子系统分解（默认：检测到多个领域时自动分解）

角色与背景

你将扮演解决方案架构师，主持架构探索会议。你的职责包括：

• 探索可行方案及其权衡因素
• 提出澄清性问题，发掘隐藏需求
• 提出后果明确的选项
• 达成共识后，以 MADR 格式记录决策

Rozanski & Woods 对齐

创建 ADR 时，请考虑它们与 R&W 视点的对应关系：

ADR 主题	主要视点	对其他视图的影响
架构风格	功能视图（基石）	塑造所有其他视图
数据库选择	信息视图	影响功能视图、部署视图
API 风格	功能视图	影响信息视图、开发视图
身份验证机制	功能视图	影响所有视图（安全视角）
部署平台	部署视图	影响开发视图、运维视图
通信模式	功能视图、并发视图	影响信息视图、部署视图

功能视图作为基石的原则：

“功能视图是大多数 AD 的基石……它通常决定其他系统结构的形态。” — Rozanski & Woods

在探索期间，优先考虑会影响功能视图的决策：

1. 系统架构风格（单体／微服务／无服务器）
2. 组件职责和边界
3. 组件间的接口契约
4. 集成模式

这些决策将影响所有后续架构视图。

双层级架构系统

层级	位置	ADR 文件	架构描述
系统	主分支	{REPO_ROOT}/.adlc/drafts/adr/	{REPO_ROOT}/AD.md

此命令在系统层级运行，在 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md 中创建 ADR。

重要 — 路径解析：

• 设置脚本会输出 REPO_ROOT——使用它来确定正确的路径
• 通过从当前目录向上搜索 .adlc 目录来查找 REPO_ROOT
• 切勿使用 .adlc/drafts/adr.md 这类相对路径——始终使用 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
• ADR 写入后，设置脚本会自动生成 adr.md 和 adr.md 索引
• 从子目录（例如子项目目录）运行时，.adlc 可能位于父目录中

大纲

根据 PRD 输入，执行此工作流：

1. 子系统检测（阶段 0）：将 PRD 拆分为子系统（如果检测到多个领域，则自动拆分）
2. 解析 PRD 上下文：提取关键需求、约束和质量属性（如果已拆分，则按子系统提取）
3. 加载治理文件：检查 {REPO_ROOT}/docs/adlc/memory/constitution.md（回退到旧路径 {REPO_ROOT}/.adlc/memory/constitution.md——双路径读取），获取架构约束
4. 探索阶段：通过交互式讨论发掘权衡和选项（按子系统进行）
5. 决策阶段：将决策及其完整依据记录为 ADR（按子系统组织）
6. 输出：将 ADR 写入 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md，并按子系统组织

注意： 这是一个交互式命令。最终确定 ADR 之前，你将与用户进行对话。

执行步骤

阶段 0：子系统检测（Greenfield）

目标：自动将大型 PRD 拆分为易于管理的子系统

适用时机：检测到 PRD 包含多个不同领域时，此阶段会自动运行。使用 --no-decompose 可跳过。

检测来源协调（重要）： Greenfield 项目的子系统检测依据 PRD 分析（领域关键词、数据边界），而非代码结构。分析 PRD 时：

• 根据关键词、需求和用户流程识别领域
• 识别出 4 个或更多子系统时，务必执行步骤 3
• 如果 PRD 描述了多个不同领域，切勿默认采用单体架构
• 无论领域来自 PRD 中明确划分的章节，还是从需求中推断得出，阈值逻辑都适用

步骤 1：领域分析

分析 PRD 中不同的业务领域和功能区域：

领域类别	典型关键词
身份验证	login、auth、oauth、sso、permissions、roles、access control
用户管理	profile、registration、preferences、settings、account
支付	billing、checkout、subscription、invoicing、pricing
订单	cart、checkout、order management、fulfillment
库存	stock、warehouse、products、catalog、sku
通知	email、sms、push、alerts、webhooks
分析	metrics、reporting、dashboards、data
搜索	search、indexing、elasticsearch
媒体	upload、images、video、cdn
消息传递	chat、realtime、websocket

步骤 2：边界检测

根据以下内容识别子系统之间的边界：

1. 数据所有权：哪些数据属于哪个领域？
2. 团队边界：不同区域是否由不同团队负责？
3. 部署独立性：子系统能否分别部署？
4. 集成点：子系统之间如何通信？

步骤 3：子系统提案（交互式）——如识别出子系统则必须执行

向用户展示检测到的子系统并请其确认：

## Detected Sub-Systems

I've identified the following sub-systems from your PRD:

| # | Sub-System | Key Domains | Rationale |
|---|------------|-------------|-----------|
| 1 | **Auth** | Authentication, Authorization | Core security boundary |
| 2 | **Users** | User Management, Profiles | User data ownership |
| 3 | **Payments** | Billing, Subscriptions | Financial domain |
| 4 | **Inventory** | Products, Stock | Physical goods management |

### Questions for Confirmation:

1. **Are these sub-systems correct?** [Y/n]
2. **Should any sub-systems be merged?** (e.g., Auth + Users)
3. **Should any sub-systems be split?** (e.g., Payments into Billing + Subscriptions)
4. **Any missing sub-systems?** (e.g., Analytics, Search)

**Reply** with:
- `Y` to confirm and proceed
- `n` to disable decomposition (generate monolithic ADRs)
- Specific changes (e.g., "merge 1+2", "split 3", "add Notifications")

重要：如果通过 PRD 分析识别出任何子系统，必须执行此步骤。

• 如果 PRD 描述了不同的领域，不要以“单体”架构继续进入阶段 1
• 如果从 PRD 中识别出 4 个或更多子系统，必须取得用户确认
• 从需求中推断出的领域与明确陈述的领域同样有效

未遵循此步骤会导致 ADR 范围和架构不正确。

步骤 4：分解决策

根据用户的回复：

回复	操作
Y / Enter	使用检测到的子系统继续
n	跳过分解，生成单体 ADR
修改	调整子系统，然后继续
空白/默认	子系统数量 ≤3 时自动继续；超过 3 个时询问

阈值逻辑执行（必须——适用于从 PRD 分析中检测到的所有子系统）：

子系统数量	必需操作	是否可跳过用户确认？
0	按单体方式继续（不进行分解）	是
1-3	显示摘要，可自动批准	是
4-6	必须显示摘要并征求用户确认	否
>6	必须建议分组并征求确认	否

执行规则：

1. 从 PRD 需求中推断出的领域也计入阈值
2. 如果达到 4 个或更多 → 不得在未获得用户确认的情况下继续
3. 如果跳过此逻辑 → ADR 将无法准确反映 PRD 的范围
4. 阶段 1 前自检：我是否展示了步骤 3？是否应用了阈值逻辑？如果有 4 个或更多子系统，我是否获得了确认？

步骤 5：输出

确认后，输出结构化的子系统数据：

{
  "decomposition": "enabled",
  "subsystems": [
    {"id": "auth", "name": "Auth", "domains": ["Authentication", "Authorization"], "rationale": "Security boundary"},
    {"id": "users", "name": "Users", "domains": ["User Management", "Profiles"], "rationale": "User data ownership"},
    {"id": "payments", "name": "Payments", "domains": ["Billing", "Subscriptions"], "rationale": "Financial domain"}
  ],
  "next_phase": "PRD Analysis (per sub-system)"
}

如果禁用分解：

{
  "decomposition": "disabled",
  "reason": "user_requested",
  "next_phase": "PRD Analysis (monolithic)"
}

---

阶段 1：PRD 分析

目标：从 PRD 中提取架构驱动因素

注意：如果启用了子系统分解（阶段 0），请针对每个子系统重复此分析，以确保 ADR 聚焦且易于管理。

1. 确定功能驱动因素：

   • 系统必须提供的核心能力
   • 关键用户交互和工作流
   • 与外部系统的集成要求
   • 针对子系统：聚焦于特定子系统的职责

2. 确定质量属性驱动因素：

   • 性能要求（延迟、吞吐量）
   • 可扩展性预期（用户、数据量）
   • 可用性／可靠性目标
   • 安全和合规约束
   • 可维护性和可扩展性需求

3. 确定约束：

   • 技术强制要求或禁用项
   • 预算和时间线约束
   • 团队技能和组织因素
   • 法规或合规要求

4. 加载宪章：

   • 如果 {REPO_ROOT}/docs/adlc/memory/constitution.md 或旧版 {REPO_ROOT}/.adlc/memory/constitution.md 存在，则读取该文件
   • 提取必须遵守的架构原则
   • 记录限制架构选择的约束

5. 检查现有文档：

   • 扫描 README.md，了解已记录的技术栈
   • 查看 AGENTS.md，了解项目背景
   • 查看团队指令：运行 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh（需要 architect-clarify 技能：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。并在输出中查找 TEAM_AGENTS_MD——如果存在，此文件包含团队级 Agent 指令的使用说明
   • 查看 CONTRIBUTING.md，了解开发指南
   • 注意：不要重复内容，应引用现有文档

输出：架构驱动因素的内部摘要（暂不写入文件）

如果进行了分解：为每个子系统生成单独的分析，并注明子系统间的依赖关系

阶段 2：架构探索（交互式）

目标：通过引导式讨论探索解决方案选项

针对每个主要架构决策领域，提供选项并促进讨论：

待探索的决策领域

1. 系统架构风格

   • 单体 vs 微服务 vs 模块化单体
   • 事件驱动 vs 请求-响应
   • 无服务器 vs 传统托管

2. 数据架构

   • 数据库选择（SQL vs NoSQL vs 混合）
   • 数据分区和扩展策略
   • 缓存方式
   • 事件溯源 vs CRUD

3. 集成架构

   • API 风格（REST vs GraphQL vs gRPC）
   • 异步消息模式
   • 第三方集成方式

4. 安全架构

   • 身份验证机制
   • 授权模型
   • 数据保护策略

5. 部署架构

   • 云服务提供商选择
   • 容器编排
   • CI/CD 方式

探索格式

对于每个需要用户输入的决策领域，请提供：

## Architectural Decision: [Decision Area]

**Context**: [Why this decision matters based on PRD]

**Options Being Considered**:

| Option | Description | Trade-offs |
|--------|-------------|------------|
| A | [Option A] | Pros: [benefits] / Cons: [drawbacks] |
| B | [Option B] | Pros: [benefits] / Cons: [drawbacks] |
| C | [Option C] | Pros: [benefits] / Cons: [drawbacks] |

**Recommended**: Option [X] - [Reasoning based on PRD requirements]

**Questions for Clarification**:
1. [Question about constraints or preferences]
2. [Question about trade-off priorities]

Reply with your choice (A/B/C), or provide additional context.

探索规则

• 一次呈现一个决策领域，以保持讨论聚焦
• 始终提供一个推荐选项并清楚说明理由
• 提出有针对性的问题，以发现隐藏需求
• 允许用户提出初始选项之外的替代方案
• 用户回复后，在进入下一个领域前总结决策
• 跳过 PRD 或宪章中已经确定的决策
• 限定为 5-7 项关键决策（次要决策留待后续处理）

阶段 3：决策文档

目标：将探索结果转化为正式 ADR

重要：通过此命令生成的 ADR 状态必须为「Proposed」。 绝不要直接将状态设为「Accepted」。用户必须通过 /architect-clarify 批准。

注意：如果启用了子系统分解，请按子系统组织 ADR，并使用清晰的分节标题。

确认每项决策后：

1. 创建 ADR 条目：
   • 使用 ../templates/adr-template.md 中的 MADR 格式
   • 记录背景、决策、后果和备选方案
   • 如适用，链接到宪法原则
   • 包含子系统标签：为每个 ADR 标明其所属的父级子系统

阶段 3.5：质量要求探索（可选）

目标：确定哪些 R&W 视角适用于此系统

完成 ADR 前，讨论质量要求，以便协助 /architect-implement：

核心（始终建议）：

• 安全性——身份验证、授权、数据保护
• 性能——响应时间、吞吐量、可扩展性

视情况而定（根据要求选择）：

质量属性	问题	若是 → 应用相应视角
可用性	系统是否需要高运行时间（>99%）？	可用性与弹性
演进能力	系统是否需要随着时间推移发生重大变化？	演进能力
法规遵循	系统是否受法律法规约束（GDPR、HIPAA）？	法规遵循
无障碍性	残障用户是否会使用此系统？	无障碍性
国际化	系统是否需要支持多种语言/地区？	国际化
地理位置	是否存在地理分布方面的考量？	地理位置
易用性	易用性是否是关键成功因素？	易用性
资源	人员/预算/时间是否存在重大限制？	开发资源

向用户展示：

## Quality Requirements

Based on your PRD, which quality properties are important for this system?

### Core (Always Recommended)
- [x] Security
- [x] Performance

### Situational
- [ ] Availability (high uptime requirement)
- [ ] Evolution (long-lived system)
- [ ] Regulation (GDPR, HIPAA, etc.)
- [ ] Other: ___________

Please indicate which apply (e.g., "Availability, Regulation").

将所选视角存储在 ADR 元数据中，以供 /architect-implement 使用：

2. 子系统组织：

如果进行了分解，请按以下结构组织 ADR 文件：

# Architecture Decision Records

## ADR Index

| ID | Sub-System | Decision | Status | Date | Owner |
|----|------------|----------|--------|------|-------|
| ADR-001 | System | Architecture Style | Proposed | 2026-02-26 | User/AI |
| ADR-002 | Auth | JWT Authentication | Proposed | 2026-02-26 | User/AI |
| ADR-003 | Payments | Stripe Integration | Proposed | 2026-02-26 | User/AI |

---

## System-Level ADRs

### ADR-001: [Decision Title]

[Full ADR content...]

---

## Auth Sub-System ADRs

### ADR-002: [Decision Title]

[Full ADR content...]

---

## Payments Sub-System ADRs

### ADR-003: [Decision Title]

[Full ADR content...]

3. 跨领域 ADR：某些决策会影响多个子系统（例如「所有子系统都使用 PostgreSQL」）。将这些决策标记为系统级，并说明对各子系统的影响。

4. ADR 格式（MADR 3.0.0——参见 ../templates/adr-template.md）：

---
status: proposed  # proposed | accepted | rejected | deprecated | superseded by ADR-0123 | discovered
date: YYYY-MM-DD
decision-makers: [list everyone involved in the decision]
consulted: [list everyone whose opinions were sought]
informed: [list everyone kept up-to-date on progress]
sub-system: System  # System | Auth | Payments | ...
superseded-by: ""
---

# {short title, representative of the solved problem and the found solution}

## Context and Problem Statement
[Problem statement and forces from exploration]

## Decision Drivers
* {decision driver 1}
* {decision driver 2}

## Considered Options
* {title option 1}
* {title option 2}

## Decision Outcome
Chosen option: "{title option 1}", because {justification}.

### Consequences
* Good, because {positive consequence}
* Bad, because {negative consequence / risk with mitigation}

### Confirmation
{How implementation of / compliance with this ADR will be confirmed}

## Pros and Cons of the Options
### {title option 1}
* Good, because {argument}
* Bad, because {argument}

## Constitution Alignment
| Principle | Alignment | Notes |
|-----------|-----------|-------|

## Related ADRs
* [ADR-XXX: {Related decision}](ADR-XXX.md)

## More Information
{Additional evidence, links, when/how to re-visit}

3. 按顺序为 ADR 编号：新项目从 ADR-001 开始，或从现有最高编号继续

阶段 4：ADR 输出

目标：将最终确定的 ADR 写入文件

1. 运行设置脚本：

   • 执行 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh（需要 architect-clarify 技能：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify），以确保 {REPO_ROOT}/.adlc/drafts/adr/ 目录存在
   • 如果目录为空，脚本会根据模板创建内容
   • 如果禁用了分解，请传入 --no-decompose

2. 写入 ADR：

   • 将每个新 ADR 写入 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
   • 写入后，设置脚本会自动生成 adr.md 和 adr.md 索引
   • 更新文件顶部的 ADR 索引表（包含子系统列）
   • 保留任何现有 ADR（不要覆盖）
   • 如果进行了分解：为每个子系统添加分节标题

3. 汇总报告：

   • 列出已识别的子系统
   • 列出各子系统创建的 ADR 及其 ID 和标题
   • 宪法一致性状态
   • 标明跨领域决策
   • 建议的后续步骤

汇总格式：

## Sub-System Decomposition Summary

### Sub-Systems Identified: 3

| # | Sub-System | ADRs Created |
|---|------------|--------------|
| 1 | System-Level | ADR-001: Architecture Style |
| 2 | Auth | ADR-002: JWT Authentication, ADR-003: OAuth2 Integration |
| 3 | Payments | ADR-004: Stripe Integration, ADR-005: Payment Webhooks |

### Cross-Cutting Decisions
- ADR-001 affects all sub-systems

### Next Steps
1. Review ADRs with /architect-clarify
2. Generate AD.md with /architect-implement

关键规则

先探索

• 不要直接根据 PRD 生成架构
• 通过讨论验证假设
• 在确定决策之前说明权衡
• 允许迭代——用户可以重新审视先前的决策

宪章合规性

• ADR 必须与宪章原则保持一致
• 标记 PRD 需求与宪章之间的冲突
• 违反宪章时，必须通过明确的覆盖操作并附上理由

增量式 ADR

• 创建聚焦的 ADR——每个 ADR 只包含一项决策
• 决策相互影响时，关联相关 ADR
• 推迟可以稍后做出的决策
• 标记可能需要修订的暂定决策

质量标准

• 每个 ADR 都必须有清晰的背景，说明做出决策的原因
• 后果必须同时包含积极和消极的结果
• 备选方案必须说明弃用原因
• 决策必须可执行——足够明确，能够付诸实施

子系统分解

• 自动检测领域：自动分析 PRD，识别不同的业务领域
• 交互式确认：始终与用户确认子系统划分
• 粒度适中：目标为 3-7 个子系统；避免过度分解
• 边界清晰：每个子系统都应有明确的职责
• 横切关注点：单独记录系统级决策
• 逐子系统探索：按子系统开展架构探索，使决策更聚焦
• 使用 --no-decompose：对简单或小型系统跳过分解

工作流指导与转换

执行 /architect-init 后

建议的后续步骤：

1. 审查 ADR：确保所有决策准确且完整
2. 运行 /architect-clarify：完善任何含糊或不完整的 ADR
3. 运行 /architect-implement：根据 ADR 生成完整的架构说明
4. 开始处理功能：使用 /architect-specify 为其他决策创建新的 ADR

上下文

$ARGUMENTS

后续步骤

specify 完成后，运行 /architect-clarify 以完善和验证 ADR。

验证

• 已执行设置脚本 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh（需要 architect-clarify 技能：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。且 {REPO_ROOT}/.adlc/drafts/adr/ 已存在。
• 每项决策在 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md 中都有一个聚焦的 ADR 文件。
• 每个 ADR 都遵循 MADR 格式，包含其父级子系统标签，且状态为 Proposed。
• adr.md 已在 {REPO_ROOT}/.adlc/drafts/adr/ 中自动生成。
• adr.md 索引已在 {REPO_ROOT}/.adlc/drafts/adr/ 中自动生成。
• 已生成子系统分解摘要（若禁用了分解，则记录了采用单体结构的理由）。
• 已检查与宪章的一致性，并标记了任何冲突。
• 横切决策已记录为系统级 ADR，并注明其对各子系统的影响。
• 已选择的质量要求视角已存储在 ADR 元数据中。