design-code-implement

设计代码实现方案

确定如何构建某项功能，其要实现什么已经确定。通过并行子 Agent 探索仓库中实际的架构惯例，揭示新需求与这些惯例之间的冲突，并提出至少三个方案供用户选择。

此技能不会编写生产代码。选择并记录方案后，流程即结束。

1. 确认输入

无论需求以何种形式提供，都予以接受：文件路径、上游技能移交的内容，或对话中的文字。绝不要要求用户提供文件。阅读用户指出的内容，并用一句话复述所需结果；只要存在任何歧义，就请用户确认。

不要询问用户那些可以通过仓库、运行时或工具查明的信息。

2. 确定探索范围

根据 §1 中确认的需求，自行决定要探索哪些方面。不要先派出侦察子 Agent，也不要让用户批准方面列表——在了解仓库的实际情况之前，用户无法判断，而错误的方面会在报告中显现。

方面列表的限制：

• 始终包含领域语言：现有概念如何命名，以及需求是否引入了代码库中尚不存在的术语。
• 仅限架构惯例：层次如何划分、错误如何向上传递、数据如何进入和离开、测试放在哪里，以及现有的接缝在哪里。排除表层风格——命名大小写、文件位置、格式。Linter 和相邻代码已足以说明这些，不会有人仅因 camelCase 而选择不同的实现方案。
• 最多五个子 Agent。 如果需求似乎需要更多，就合并相关方面。确实涉及八个架构方面的需求，应在设计前拆分。
• 控制影响范围。 只探索需求涉及的区域，以及 git log --oneline 中近期的热点。不要扫描整个仓库；无关的惯例会冲淡真正的冲突。

3. 派发并收集结果

为每个子 Agent 指定相同的工具优先级：

• 如果有代码库知识图谱 MCP，优先使用；如果仓库尚未建立索引，先完成索引。
• 否则，优先使用其他了解仓库结构的导航工具。
• 如果上述工具返回陈旧或不适用的结果，则退回内置搜索，用于查找字符串字面量、配置、脚本和非代码文件。

要求每个子 Agent 针对每项发现，严格报告以下三项：

1. 现有惯例——仓库在这一方面已有的做法。
2. 证据——文件和行号（path/to/file.ts:42）。没有路径的说法不可用。
3. 冲突——新需求与该惯例之间的冲突之处。如果没有冲突，请明确说明。

冲突字段是此流程的重点。没有冲突的惯例只是背景信息；方案方向源于冲突。

4. 提出方向

如果探索未发现可供继承的现有规范，请说明这一点并停止；本技能没有可据以提出方向的基础。不要提出方向。

在对话中依次提出至少三个方向，让用户逐一了解后再进行比较。

• 方向 1 始终是基准方案：遵循所有现有规范，不开辟新的切入点，采取最保守的路径。提出这个方向几乎不费成本，而且其他方向都要以它为衡量基准——没有它，用户就无法判断额外成本是否值得付出。
• 方向 2 和方向 3 应源自已报告的矛盾，而不是套用模板。 不要给方向预设限制；让代码库中的实际摩擦决定它们的分歧之处。

每个方向必须恰好包含以下四个字段：

1. 定位——一句话。
2. 影响范围——涉及哪些文件和切入点。
3. 成本——具体需要付出什么。
4. 不适用情况——在什么条件下，选择这个方向会是个错误。

第四个字段为必填项，它能迫使你坦诚。没有失败条件的方向，说明还没有经过周全考虑。

最后给出建议：说明你会选择哪个方向，以及决定这一选择的矛盾或要求。选择权仍在用户手中。

如果这些矛盾不足以支撑三个真正不同的方向，请直言：现有规范已经决定了实现方法，然后停止。绝不要用牵强的变体凑数——用户一旦无法分辨真正的选择和刻意制造的选择，就会不再信任所有方向。

允许组合。 如果用户想要某个方向的整体方案，同时采用另一个方向的错误处理方式，就按此组合——然后完整重述组合后的方向，并在编写任何内容前获得确认。双方理解各异的组合，比没有组合更糟。

5. 记录决策

编写 design.md。

放置位置：编写前询问用户要将文件放在哪里。

内容——只写将要做的事情，按照 references/template.md 中的格式组织：

• 用图表而非文字描述所选方向。
  • 每条跨越组件的流程：为每个触发条件绘制一个 ASCII 流程图。步骤自上而下排列并编号，每步后跟一行缩进的 ↳，注明实际负责处理的函数和文件。右侧保持留白，只使用左侧箭头和缩进，避免宽字符破坏对齐。只绘制成功路径；在图表下方，以“步骤 N 失败 → 后续处理”的格式列出需求所隐含的每一种失败情况。属于独立流程的步骤要单独绘制流程图，并以“→ 流程 N”引用。
  • 每个状态发生变化的实体：绘制一个 Mermaid stateDiagram-v2。
  • 图表无法体现的变更（迁移、配置、接口形状）：用简短列表说明。
• 本工作必须遵循的规范，每条一行，并附上证据路径。
• 不得包含其他内容。不要写被否决的方向，也不要写否决理由。 下游实现 Agent 会把此文件当作指令；描述未采用的方案会诱使其采用该方案。

如果 design.md 已存在：先阅读，再更新——保留仍然适用的内容。绝不要未经查看就覆盖。

6. 交接并停止

报告：

• 所选方向的简短摘要。
• design.md 的路径。

然后停止。如何以及使用什么来实现，由用户决定；不要开始实现，也不要提及下一条命令。