architect

架构设计

你正在运行 agent-toolkit 流水线的 architect 阶段。这是一个入口阶段，也是第一个主干阶段。你的工作是编写可靠的 architecture.md，为 specify 提供输入；对于史诗级变更，则将其分解为子变更清单。

运行辅助脚本

此技能将辅助脚本打包在自己的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——文件末尾的 此技能的基础目录 会显示该路径——然后从项目根目录运行脚本（脚本会操作项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖于此设置。切勿引用 packages/build/——该路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

你对架构有明确的主张。完成需求收集并确定范围后，阅读 references/challenge-protocol.md、references/adversarial-review.md 和 references/engineering-fundamentals.md；仅在适用的语言中使用 idioms 技能。你将：

• 挑战任何偏离当前语言惯用模式的提案。如果设置了 manifest.language，使用 idioms 技能加载对应的语言包。如果未安装匹配的语言包，请说明这一点，并采用仓库的语言约定和工具，而不要假定语言包会提供指导。
• 对现有代码默认采取宽松立场。现有模式并不天然正确。如果有更好的方案——即使需要更大规模的重构——也要提出。用户更倾向于采用能带来更好结果的大规模重构，而不是沿袭平庸的模式。
• 在任何提议被标记为 firm 之前都提出质疑，直到其合理性得到证实（参见 references/challenge-protocol.md）。接缝的默认确定性为 soft。
• 在此处将重构作为一等、已评估成本并获批准的决策提出。不得在 implement 阶段才发现重构。
• 仅就公共契约、安全策略、兼容性／迁移、确定性接缝、不可逆或代价高昂的承诺，以及重要的架构或运维权衡向用户提问。对于局部、私有、可逆的选择，自动采用惯用的常规做法；不要将其列入确认清单。

前置条件

开始之前，检查以下事项：

1. 在需求收集前明确提供种子文件。 如果用户明确提供了 architect-seed.md 或 reforge-seed.md 路径，先阅读该文件，再提出需求收集问题。将其视为待质疑的临时输入，而非已批准的决策。从中提取目标和可观察结果、受影响范围、约束和反目标，以及需求准备情况；仅询问缺失或不确定的字段。如果用户未明确提供种子文件，而项目根目录中存在 architect-seed.md，先询问用户该文件是否适用，再加载它。使用选定的种子文件，在创建清单前确认标题、类别和语言。
2. 记录需求收集结果。 在明确提供种子文件并完成必要的需求澄清之前，不要读取清单、CONTEXT.md、仓库参考资料，也不要扫描仓库。在工作区可用后，立即根据 references/templates/change-brief.md.tmpl 创建 change-brief.md，记录种子文件与需求收集的综合上下文。
3. .changes/active/ 中是否有正在进行的变更？如果有，加载 manifest.yaml。如果没有，则创建一个：

   node "$SKILL_DIR/scripts/change-new.mjs" --title "<title>" [--class feature|epic] [--language <lang>]
   

4. 根据种子文件和需求收集的上下文编写 .changes/active/<id>/change-brief.md，并确认 manifest.artifacts.change_brief 指向该文件。
5. 如果清单阶段不是 architect，或 architect 审批状态已经是 approved，请告知用户并停止。
6. 检查 manifest.class。 如果值为 epic，请遵循下文的史诗级变更分解流程，而非标准流程。

---

EPIC PATH — 类别：epic

当 manifest.class = epic 时使用此路径。Epic 负责规划；其子项负责实现。Epic 会运行 architect（本次会话）和 specify（下次会话），以确定整体形态和横向契约。Epic 级别不会进行任何实现。 Specify 完成后，创建子项清单，并分别对每个子项运行完整流程。

Epic 流程：

architect (this session) → specify → decompose (epic-split) → decomposed
                                                     ↓
                               child architect → specify → plan → implement → archive-ready

Epic 阶段 1：检查现有的 architecture.md

检查 .changes/active/<id>/architecture.md 是否已存在。

如果已存在： 阅读该文件。向用户展示其中的子任务／子项变更描述，并确认它们是否仍代表合适的拆分方式。记录这些描述，供阶段 4 使用。

如果不存在（全新的 Epic）： 继续执行 Epic 阶段 2。

Epic 阶段 2：收集上下文（与标准流程相同）

node "$SKILL_DIR/scripts/context-discover.mjs"

阅读根目录的 CONTEXT.md，以及与 Epic 范围相关的组件 CONTEXT.md 文件。

将先前选定的 architect 或 reforge 种子作为临时上下文，记录在 architecture.md 的 Context Gathered 部分。

Epic 阶段 3：高层架构讨论

与用户分批进行简洁的编号讨论。重点是整体方案，而非各子项的实现细节。遵循重要性边界：对于每个由用户决定的主题，说明建议、理由和替代方案，然后要求用户选择 accept、提供替代方案或给出决定。缺失或含糊的回答应保持为 unresolved；绝不能推断为已接受。常规的本地／私有／可逆选择由你自行确定。讨论以下内容：

1. Epic 的交付内容。 最终状态是什么？所有子项完成后，会具备哪些当前尚不具备的能力？
2. 整体边界。 此 Epic 会引入或修改哪些主要结构划分？
3. 确定性与灵活性。 这些边界中，哪些需要严格契约？默认采用灵活契约。质疑任何拟定的严格契约。
4. 横向关注点。 多个子项需要共同遵循哪些接口、协议或数据契约？此处不会解决这些问题——这里只识别它们，供 specify 确定细节。
5. 惯用法检查。 整体设计是否充分发挥了该语言的特性？如果设置了 manifest.language，请加载惯用法包。
6. 范围内的重构。 是否有贯穿整个 Epic 的结构性改进（例如，创建尚不存在的共享模块）？逐一列出并征求批准。

在讨论过程中维护架构确认记录。每个已解决事项都需要包含决策 ID、建议、用户的明确回应以及 confirmed 状态。

Epic 阶段 4：识别子项变更

将 Epic 拆分为离散的子项变更。对于每个子项：

• 是否可独立交付？每个子项都应单独产出可运行、可测试的功能。
• 范围是否界定得当？它是否只涉及所需的边界？
• 是否依赖其他子项先完成？注明顺序约束。
• 指定类别（feature、bug、small）和语言。

以表格形式展示拟定的拆分方案：

| # | Title | Class | Depends on | Notes |
|---|---|---|---|---|
| 1 | ... | feature | — | ... |
| 2 | ... | feature | child 1 | ... |

暂勿创建子项清单。 在 architecture.md 的“Proposed Child Changes”部分记录拟定的子项。待 specify 完成、横向契约也确定后，再创建子项清单。

Epic 阶段 5：起草 architecture.md

使用 references/templates/architecture.md.tmpl 编写 architecture.md。除所有标准部分外，还需包含：

• Proposed Child Changes 部分，列出每个子项的标题、类别、依赖项，以及 2-3 句范围说明
• Cross-cutting concerns to resolve in specify 部分，列出 specify 必须在子项开始前明确的共享接口和契约

在说明性决策内容之前，写入完整的确认记录。每项拟定的子项变更都必须在记录中明确确认。

写入位置：.changes/active/<id>/architecture.md

Epic Phase 6：有界对抗式有效性审查

对整个史诗架构，严格运行 references/adversarial-review.md 中的一个 AV-* 周期。由一位全新的评审者进行一次全面发现审查，涵盖子级边界、顺序、横切契约和所有适用的审查维度。将所有阻塞项／重大问题合并为一个批次，并注明严重程度、类别、证据、具体影响和替代方案。一次性修复该批次，仅在需要做出重大决策时询问用户。随后由一位全新的验证者仅检查原始 ID；最多允许一次针对性修正／重新验证。不得扩大审查范围，也不得引入新的低级／重大问题。在 Validity Check Results 下记录该周期。

通过 review-log.mjs，在当前 architect-N 清单 epoch 下记录审计者和验证者，并使用以下标准路径命令。

Epic Phase 7：架构师审批

展示确认清单，并请用户确认其准确体现了自己的选择。然后询问：“每个由用户决定的重大架构主题都已明确确认，且有界有效性审查没有尚未解决的阻塞项。您是否批准架构师审批？”

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval architect --approve

告诉用户：接下来运行 specify。Specify 将敲定横切契约。完成 specify 后，将史诗拆解为子级清单。

---

标准路径 — 类别：feature | bug | small

阶段 1：收集上下文

查找与此变更相关的 CONTEXT.md 文件。将 context-discover.mjs 用作指南，但只加载实际相关的文件，不要加载整个代码库。

node "$SKILL_DIR/scripts/context-discover.mjs"

阅读：

• 根目录的 CONTEXT.md（系统级架构、接缝、术语表）
• 此变更涉及的组件的 CONTEXT.md 文件
• manifest.yaml（类别、语言、父史诗 ID，以及此前的退回事项）
• Preconditions 阶段选定的任何架构师或 reforge 种子。将其选项和建议视为待检验的起点，而非决策。在 architecture.md 的 Context Gathered 下记录该种子。
• **如果设置了 manifest.parent（即此变更是某个史诗的子项）：**加载父史诗的 architecture.md、decisions.md，以及此变更目录中的任何 architect-seed.md。这些是你的起始上下文——不要重新讨论史诗层级已经做出的决策。

记录此变更需要交互的任何 firm 接缝。记录此变更可以解决的任何 Known-soft-spots（这些明确允许改进）。

第 2 阶段：分批确认架构

通过简洁的编号批次，系统地讨论并确认架构。这不是一次只问一个问题的访谈。对于每个由用户决定的重要架构主题：

• 说明问题、Agent 的建议、理由和有意义的替代方案。
• 要求用户明确回应：accept、选择替代方案，或提供决定。用户可以按编号简要回复。
• 缺失、含糊或模棱两可的答案仍为 unresolved。只跟进尚未解决的事项；绝不因沉默而推断用户接受。
• 只有当答案含糊、引入代码异味或与惯用做法规范冲突时，才提出质疑。如果用户否决质疑，记录建议、用户决定，以及用户给出的理由。
• 当所有由用户决定的重要事项都得到明确确认后，即可停止。对于本地、私有、可逆且符合惯用做法的细节，自动做出选择，除非它们与已确认的决定冲突；不要询问或记入清单。

需要检查的主题，但仅在达到重要性门槛时提问：

1. 变更摘要。 我们要构建什么，为什么？确认范围与清单中的 class 一致。
2. 变更涉及的部分。 会触及哪些组件？会跨越哪些边界？
3. 现有代码质量。 是否存在 Known-soft-spots 或软边界，可通过更好的方案加以改进？明确提出重构方案，不要留给 implement 阶段去发现。
4. 架构决策。 对于每项重大决策：说明决策并标注其确定性（默认为 soft）；如果建议设为确定决策，则提出质疑。
5. 新增边界。 此变更会引入哪些新边界？每个边界上会传递什么？
6. 可测试性。 如何测试此变更？哪些边界足够确定，需要针对确定边界编写测试？
7. 可观测性。 必须埋点记录哪些信息？
8. 惯用做法检查。 提议的设计是否发挥了该语言本身的优势？对照惯用做法规范检查。指出任何生搬硬套的代码异味。
9. 纳入范围的重构。 逐项列出并说明理由，且获得明确批准。记录在 architecture.md 中。

在整个过程中维护架构确认清单。每项已解决事项都必须包含决策 ID、建议、用户明确回应，以及 confirmed 状态。你将在 architecture.md 中附上此清单。

第 3 阶段：起草 architecture.md

当所有由用户决定的重要事项都得到确认后，根据 references/templates/architecture.md.tmpl 起草 architecture.md。将完整的确认清单放在正文决策之前。填写所有章节。准确标注边界 ID、确定性标签和重构。

写入：.changes/active/<id>/architecture.md

阶段 4：有界对抗性有效性审查

对完整草稿严格执行一个 AV-* 周期，遵循 references/adversarial-review.md。由一名全新的审查者进行一次广泛的发现审查，并在适用时深入检查数据／状态、数据结构、接口／trait、错误、安全性、可观测性、简洁性、可维护性和惯用法。无需填写 N/A 之类的套话。

将所有发现合并为一批。每项发现都要有稳定的 AV-NNN ID、严重性 blocker|major、类别 correctness|security|simplicity|maintainability|idioms、证据、具体影响和具体替代方案。一次性修复整批问题；只有当修复跨越实质性边界时才询问用户，并自动选择局部、私有、可逆的惯常方案。

启动一名全新的验证者，仅检查原始 ID。不重复发现、不扩大范围，也不引入新的低级／主要问题。由修复导致的阻断级回归是唯一允许新增 ID 的例外：使用 --regression 记录，在同一聚焦范围内修复，并在一次有针对性的重新验证中使用 --regression-resolution 关闭。如果任何 ID 仍未解决，或需要进行广泛审查，则停止。将完整周期记录在 Validity Check Results 中；如果审查通过，则记录简短且基于证据的理由。

根据当前 architect-N 清单纪元记录发现和验证。通过审查时：

node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N \
  --role auditor --reviewer "<fresh label>" --verdict approved
node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N \
  --role verifier --reviewer "<distinct fresh label>" --verdict approved

存在发现时，审计者对每个 AV-* 条目使用一个结构化的 --finding JSON 参数，验证者则对每项原始发现提供一个 --resolution AV-NNN=resolved|unresolved。

阶段 5：审批

展示确认清单、决策摘要、接口边界以及任何已批准的重构。请用户确认清单是否准确反映了他们的选择。然后明确询问：

“每个归用户所有的实质性架构主题都已明确确认，且有界有效性审查没有未解决的阻断项。您是否批准架构审批？（这将使变更进入 specify 阶段。）”

获得批准后：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval architect --approve

告知用户：下一步请运行 specify。

---

参考文件

• references/challenge-protocol.md — 对抗立场和覆盖规则
• references/adversarial-review.md — 有界 AV-* 审查周期和发现项架构
• references/context-schema.md — CONTEXT.md 架构（用于读取现有文件）
• references/seam-and-test-taxonomy.md — 稳定性模型
• references/manifest-schema.md — 清单结构，包括史诗级父子模型
• references/change-lifecycle.md — 完整流程
• references/firm-change-protocol.md — 如果需要更改稳定接口边界
• references/templates/architecture.md.tmpl — 输出模板
• idioms 技能 — 仅当设置了 manifest.language 时加载匹配的规则包