快速参考

• 硬门禁（第一优先级） ：任何读写 {FEATURE_DIR}/design/*.md 之前，必须先执行 spec-context 获取上下文并回显 FEATURE_DIR=...（允许 (reuse)）；失败立刻停止。

• D2 强制输入（第二优先级） ：D2 必须读取 {FEATURE_DIR}/requirements/solution.md#impact-analysis，并据此强制读取受影响模块组件页全文与相关 ADR 全文；读不到必须显式标注 CONTEXT GAP，不得静默跳过。

• 输出位置

  • D2（必做，未跳过时）：{FEATURE_DIR}/design/design.md

• 最小化模板

  • D2：<本SKILL.md目录>/assets/design-template.md（复制到 {FEATURE_DIR}/design/design.md 再填写）

提醒：出现“是否跳过 design / 是否需要 research”的讨论时，请回到 using-aisdlc 做路由判定；本技能只执行 D2。

实施步骤（Agent 行为规范）

0) 门禁（必须先过，否则停止）

REQUIRED SUB-SKILL：正在执行spec-context 获取上下文，并回显 FEATURE_DIR=...（允许 (reuse)）。

• spec-context 失败 → 停止

若上面报错 → 立刻停止 （不要生成/写任何 design/*.md 内容）。

1) 读取最小必要输入（缺失则停止）

• 必读（需求侧 SSOT） ：{FEATURE_DIR}/requirements/solution.md
• 必读（影响分析 SSOT） ：{FEATURE_DIR}/requirements/solution.md#impact-analysis（从中提取：受影响模块清单、需遵守的不变量、相关 ADR、跨模块影响）
• 按需 ：{FEATURE_DIR}/requirements/prd.md、{FEATURE_DIR}/requirements/prototype.md
• 必读（项目级，强制） ：
  • project/memory/*（业务/技术/结构/术语）
  • project/components/index.md（跨模块依赖关系图/交互方式入口）
  • project/adr/index.md（ADR 索引）
  • 从影响分析得到的受影响模块：读取 project/components/{module}.md 全文 （包含 ## API Contract / ## Data Contract / ## State Machines & Domain Events 等稳定锚点）
  • 从影响分析得到的相关 ADR：读取 project/adr/{adr-id}.md 全文
• 若存在 ：{FEATURE_DIR}/design/research.md、{FEATURE_DIR}/design/design.md

停止条件（不得脑补继续）：

• 找不到或无法读取 requirements/solution.md。
• 需求的 In/Out、验收口径、关键约束无法从输入追溯。

硬要求（不得降级为“只读索引/只读一部分”）：

• 受影响模块的组件页与相关 ADR 要么全文读取成功，要么在design/design.md 中显式标注为 CONTEXT GAP。
• 禁止 用“impact-analysis 的摘要/索引页”替代全文阅读，并宣称“已对齐/已合规”。
• 如果压力导致无法完成全文读取：必须在 D2 输出中把 DoD 标为未满足，并明确阻塞项（而不是“先勾选通过，后续再补”）。

2) D2：design（决策文档 / RFC）

2.1 D2 的定位（写“决策”，不写“实现”）

• 只写 ：为什么这样做、边界怎么裁切、方案与权衡、对外承诺要点、怎么验证、影响与迁移/回滚要点。
• 不写 ：实现步骤、任务拆分、代码级细节、接口字段逐一罗列、DDL 细节。
  • 若必须对外承诺字段/兼容性：在本文写“要点 + 追溯链接”，细节下沉到 project/contracts/ 或 ADR。
  • 若项目以组件页作为契约 SSOT：优先把细节下沉到对应 project/components/{module}.md#api-contract/#data-contract（与本仓库的 Discover 模块页结构对齐）。

2.2 design/design.md 建议最小结构（模板）

必须使用最小化模板 生成 design.md（避免结构漂移）：

1. 复制 <本SKILL.md目录>/assets/design-template.md 的内容
2. 粘贴到 {FEATURE_DIR}/design/design.md
3. 按模板把占位符补齐（尤其是 C4 L1–L3、备选方案、风险与验证清单、追溯链接）

写作约束：只保留支撑决策/验收/演进的最小信息；不要新增“待确认问题/TODO”章节；不要写实现细节/任务拆分/字段清单/DDL。

2.3 D2-DoD（缺一不可）

• In/Out 明确，且能追溯到 solution.md
• 推荐方案用 C4 L1+L2+L3 说清楚，层次可追溯
• 关键决策说明“为什么选它/备选为何不选”
• 与现有系统的对齐已完成 （基于 solution.md#impact-analysis）：
  • 每个受影响模块：完成契约兼容性声明 （兼容/扩展/破坏性变更），并引用对应组件页 #api-contract / #data-contract 的具体不变量
  • 每个相关 ADR：完成ADR 合规声明 （遵守/需新增/需修改）
  • 对涉及的状态机/领域事件：完成影响说明 （引用组件页 ## State Machines & Domain Events）
  • 基于依赖关系图：完成跨模块影响确认
• 不确定性已收敛：未知全部进入“假设 + 验证清单”（Owner/截止/动作明确）

DoD 判定规则（防止“拿 CONTEXT GAP 当完成”）：

• 若任何受影响模块组件页或相关 ADR 出现 CONTEXT GAP，则“与现有系统的对齐已完成”这一项不得勾选通过 ；必须在 D2 中明确这是阻塞/风险，并给出补齐路径（读到全文/补齐知识库/新增 ADR）。

红旗（出现任一即停止并纠偏）

• 没有先拿到 FEATURE_DIR=... 就开始写 design/*.md
• 找不到 requirements/solution.md 还继续写设计（=脑补）
• 用“待确认问题清单 / TODO”悬空未知（应改为“假设 + 验证清单”）
• 把 D2 写成实现规格：任务拆分、实现步骤、字段/DDL 细节
• 缺少备选方案或缺少验证清单（导致无法评审/无法落地）
• 只读 project/adr/index.md / project/components/index.md 就宣称“已对齐现有系统”
• 只读部分受影响模块或只读部分 ADR，就宣称“已对齐/已合规”
• 用 impact-analysis 摘要替代组件页/ADR 全文，但未标注 CONTEXT GAP
• 把 CONTEXT GAP 当作“对齐已完成”的理由（这是 DoD 失败信号，不是通过信号）

压力下的反合理化（常见借口 → 对应动作）

常见错误（以及修复）

• 错误 ：在压力下“先写了再说”，先生成文档再补输入。
  修复 ：先执行 spec-context 获取上下文，并满足 solution.md 门禁；缺失就停止，写清楚阻塞项。
• 错误 ：把 research 当成“查资料”，写了很多背景但没有验证清单。
  修复 ：把未知全部转成“风险/假设 → 验证方式 → 信号 → Owner/截止/动作”。
• 错误 ：PM 要求把任务/接口/表结构写进设计，于是混层。
  修复 ：设计文档只保留“对外承诺要点 + 追溯链接”；实现细节移入 implementation 或 contracts/ADR。
• 错误 ：只读索引（components/index.md、adr/index.md 或 impact-analysis 摘要），就写“已对齐/已合规”。
  修复 ：对每个受影响模块与 ADR：必须全文读取并引用具体不变量/条款；读不到就写 CONTEXT GAP，且 DoD 不得通过。

完成后输出与自动路由（必须执行）

design.md 落盘后，必须 完成以下动作（按顺序，不可省略）：

1. 输出 ROUTER_SUMMARY （YAML 形态，供 Router 决策）：

ROUTER_SUMMARY:

  stage: D2
  artifacts:
    - "{FEATURE_DIR}/design/design.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "RFC 建议评审通过后再进入 I1（spec-plan）"

2. 立即执行using-aisdlc：将上述 ROUTER_SUMMARY 作为路由输入传递给 using-aisdlc，由 Router 判定下一步并自动推进 （无需等待用户说「继续」）。

 * 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 I1 等）
 * 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步

3. 对话输出 ：在调用 using-aisdlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aisdlc 路由下一步。」

Weekly Installs

93

Repository

zixun-github/aisdlc

GitHub Stars

6

First Seen

Feb 25, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

claude-code92

cursor89

gemini-cli22

github-copilot22

codex22

kimi-cli22