using-aisdlc（在 sdlc-dev 中使用 AI SDLC / Spec Pack 流程）

概览

这是一个“导航 + 门禁”型 Skill：用于在 sdlc-dev 的 Spec Pack（{num}-{short-name}）流程里，选对下一步要用的 skill，并用硬门禁防止上下文漂移与写错目录。

开始时宣布：「我正在使用 using-aisdlc 技能导航 Spec Pack 流程并执行门禁校验。」

本 Skill 现在同时覆盖两条链路：

• 需求链路（R0–R4）：raw.md → solution.md → prd.md → prototype.md → demo/
• 开发链路（I1–I2 + Finish）：solution.md → implementation/plan.md → 执行实现 → finishing-development

核心原则：

• 先上下文，再读写：凡读写 {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/*、{FEATURE_DIR}/implementation/*（或 R4 写 demo）→ 先 spec-context 得到 FEATURE_DIR（失败就停止）。
• 一个节点 = 一个 skill = 一个落盘产物：R0/R1/R2/R3/R4 分步执行，禁止“一次性把 PRD+原型+Demo 全做了”。
• 渐进式披露：先读项目级 memory/ 与相关契约索引；明确处理某个 Spec 后再读写 {FEATURE_DIR}/requirements/*。
• 不确定性不写“待确认问题清单”：统一进入“验证清单”（Owner/截止/信号/动作）。
• 回流闭环：R3/R4 的验证发现会回流更新 R1/R2/R3（必要时再做 R4）。
• 实现侧 SSOT：实现阶段以 {FEATURE_DIR}/implementation/plan.md 作为唯一执行清单与状态 SSOT（checkbox + 审计信息）；执行状态只回写到 plan.md。

何时使用 / 不使用

• 使用时机
  • 你要开始/继续一个 Spec：生成或更新 raw.md / solution.md / prd.md / prototype.md / demo
  • 你要把一个“简单需求”直接推进到开发闭环：solution.md → plan.md → execute → finishing
  • 你不确定“现在该跑哪个 spec-product-* skill”
  • 你不确定“现在该跑 spec-implementation-plan / spec-implementation-execute 还是先补需求输入”
  • 用户在施压时提出：不想跑脚本、直接给你路径、要求你先写再补上下文
• 不要用在
  • 仅讨论概念、不涉及本仓库 Spec Pack 的落盘文件与目录结构

唯一门禁（必须遵守）

规则：只要任务会读写以下任意内容，就必须先跑 spec-context 并回显 FEATURE_DIR=...：

• {FEATURE_DIR}/requirements/raw.md
• {FEATURE_DIR}/requirements/solution.md
• {FEATURE_DIR}/requirements/prd.md
• {FEATURE_DIR}/requirements/prototype.md
• {FEATURE_DIR}/design/*.md（例如 design/design.md、design/research.md）
• {FEATURE_DIR}/implementation/plan.md
• {REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/...（R4）

即使用户口头给了 FEATURE_DIR 也不例外。（基线压测中最常见的违规点：把“用户给的路径”当成可信上下文。）

命令书写约定：默认面向 PowerShell；同一行多命令请用 ; 分隔（不要用 &&）。

你要的最短闭环（简单需求开发）：raw → solution.md → plan.md → execute → finishing-development

适用前提（满足其一即可）：

• 范围单一、边界清晰，风险低，不需要额外设计阶段决策文档（可按 design/aisdlc_spec_design.md 的 D0 判定跳过 design）
• 验收口径可追溯：至少能在 solution.md（或更完整的 prd.md）里写清楚验收点

最短闭环（建议先跑通）：

1. R0：落盘 raw（如尚未建包）
   • 用什么：spec-init
   • 输出：{FEATURE_DIR}/requirements/raw.md
2. 门禁：定位 Spec 上下文
   • 用什么：spec-context
   • 要求：对话中必须回显 FEATURE_DIR=...；失败即停止
3. R1：raw → solution（收敛方案）
   • 用什么：spec-product-clarify
   • 输出：{FEATURE_DIR}/requirements/solution.md
   • 兼容说明：用户可能会说 solutions.md，但本仓库需求侧 SSOT 以 solution.md（单数） 为准；不要新建 solutions.md 造成双 SSOT
4. I1：solution → plan（写到可执行）
   • 用什么：spec-implementation-plan
   • 输出：{FEATURE_DIR}/implementation/plan.md（唯一执行清单与状态 SSOT）
5. I2：按 plan 分批执行（实现 + 回写状态/审计）
   • 用什么：spec-implementation-execute
   • 规则：执行状态只回写 implementation/plan.md；遇到 NEEDS CLARIFICATION / 阻塞即停
6. Finish：开发收尾确认（仅验证，全绿才算完成）
   • 用什么：finishing-development
   • 输出：一份“完成确认报告”（包含实际运行的命令与结果）

核心工作流（需求侧 R0 → R4；实现侧 I1 → I2 → Finish）

digraph aisdlc_flow {
  rankdir=LR;
  node [shape=box];
  "要处理某个需求（Spec）" -> "是否已有合法 spec 分支/Spec Pack？";
  "是否已有合法 spec 分支/Spec Pack？" [shape=diamond];
  "是否已有合法 spec 分支/Spec Pack？" -> "R0: spec-init" [label="否 / 不确定"];
  "R0: spec-init" -> "运行 spec-context" ;
  "是否已有合法 spec 分支/Spec Pack？" -> "运行 spec-context" [label="是"];
  "运行 spec-context" -> "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT";
  "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "选择需求链路 R1-R4（可选）";
  "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "选择开发链路 I1-I2（必做）";
  "选择需求链路 R1-R4（可选）" -> "R1: raw->solution";
  "R1: raw->solution" -> "R2: solution->prd（可选）";
  "R2: solution->prd（可选）" -> "R3: prd->prototype（可选）";
  "R3: prd->prototype（可选）" -> "R4: prototype->demo（可选）";
  "R1: raw->solution" -> "I1: spec-implementation-plan";
  "R2: solution->prd（可选）" -> "I1: spec-implementation-plan";
  "R3: prd->prototype（可选）" -> "I1: spec-implementation-plan";
  "I1: spec-implementation-plan" -> "I2: spec-implementation-execute";
  "I2: spec-implementation-execute" -> "Finish: finishing-development";
}

R0：初始化新 Spec Pack

• 用什么：spec-init
• 什么时候：还没有 {num}-{short-name} 分支与 .aisdlc/specs/{num}-{short-name}/ 目录
• 输出：{FEATURE_DIR}/requirements/raw.md（UTF-8 with BOM）
• 下一步：spec-context → R1

R1：澄清 + 方案决策（raw → solution）

• 用什么：spec-product-clarify
• 前置输入：spec-context 成功；{FEATURE_DIR}/requirements/raw.md 存在且非空
• 关键纪律：一次一问（优先选择题）+ 增量回写 raw.md/## 澄清记录 + 停止机制
• 输出：{FEATURE_DIR}/requirements/solution.md
• 下一步：
  • 需求还不够“可交付规格”→ R2（PRD，可选）
  • 交互/流程有歧义→ R3/R4（可选）
  • 简单需求要开发→ 直接进入 I1（实现计划）

R2：PRD（solution → prd，可选）

• 用什么：spec-product-prd
• 前置输入：{FEATURE_DIR}/requirements/solution.md 必须存在
• 输出：{FEATURE_DIR}/requirements/prd.md
• 下一步：按需 R3 或直达 design

R3：原型（prd → prototype，可选）

• 用什么：spec-product-prototype
• 前置输入：{FEATURE_DIR}/requirements/prd.md 必须存在
• 输出：{FEATURE_DIR}/requirements/prototype.md
• 下一步：原型评审/最小验证；按需 R4；发现问题回流 R1/R2/R3

R4：可交互 Demo（prototype → demo，可选）

• 用什么：spec-product-demo
• 前置输入：{FEATURE_DIR}/requirements/prototype.md 必须存在；Demo 工程根目录可定位（找不到就停止并要 DEMO_PROJECT_ROOT）
• 输出：默认 {REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/
• 下一步：运行走查；发现问题回流更新 R1/R2/R3/R4

I1：实现计划（solution/prd/design → plan.md，必做）

• 用什么：spec-implementation-plan
• 前置输入：spec-context 成功；{FEATURE_DIR}/requirements/solution.md 或 prd.md 至少其一存在（否则必须在 plan.md 标注 NEEDS CLARIFICATION 并阻断进入 I2）
• 输出：{FEATURE_DIR}/implementation/plan.md（唯一执行清单与状态 SSOT）
• 下一步：I2

I2：执行（按 plan.md 分批实现并回写，必做）

• 用什么：spec-implementation-execute
• 前置输入：{FEATURE_DIR}/implementation/plan.md 必须存在且可执行；不存在/不可执行则回到 I1
• 输出：代码与配置变更 + plan.md checkbox/审计信息回写（唯一状态来源）
• 下一步：Finish

Finish：开发收尾确认（仅验证，全绿才算完成）

• 用什么：finishing-development
• 输出：完成确认报告（实际运行的命令与结果可复现）

Quick reference（高频速查）

只要会读写 {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/*、{FEATURE_DIR}/implementation/*，或 R4 写 demo：先 spec-context，失败就停止。

红旗清单（出现任一条：停止并纠正）

• 没跑 spec-context 就开始读写 {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/*、{FEATURE_DIR}/implementation/*（或开始 R4 写 demo）
• 用户口头给了 FEATURE_DIR，你就“信了并跳过脚本”
• spec-context 报错仍继续（例如 main 分支也要“先写一版”）
• 为了赶进度先生成文档，事后再补上下文/再回头澄清
• 在 R4 找不到可运行 demo 工程根目录时，自行初始化 Vite/Next.js 工程“放你觉得合适的位置”
• 没有 {FEATURE_DIR}/implementation/plan.md（或 plan 不可执行）就开始“直接写代码”
• 执行中把状态/审计写到别处（issue/聊天记录/另一个文件），而不是回写 implementation/plan.md

常见错误（以及怎么修）

• 把“用户给的路径/分支名”当作上下文：仍然必须 spec-context 回显 FEATURE_DIR=...；无法执行就停止。
• 先生成再回头澄清/补证据：先完成 R1 澄清循环（一次一问 + 回写），达到 DoD 后再生成产物。
• 越级执行：缺 solution.md 就写 prd.md，缺 prd.md 就写 prototype.md，缺 prototype.md 就做 demo → 一律停止并回到上一步。
• 越级开发：缺 implementation/plan.md 就开始实现 → 回到 I1 写到“可执行 + 可验证 + 可审计”，再进入 I2。

常见借口与反制（来自基线压测）

一个好例子（最短路径的正确开场）

用户：“我要做一个新需求，先出方案（solution.md），我不想自己找目录。”

正确做法（第一轮）：

• 若尚未创建 spec 分支/Spec Pack → 先 spec-init（把原始需求落到 raw.md）
• 然后执行 spec-context 并回显 FEATURE_DIR=...
• 进入 R1：对用户只问 1 个最高杠杆选择题；回答后增量回写 raw.md/## 澄清记录
• DoD 达标或触发停止机制后生成 solution.md，并给出下一步：
  • 简单需求要开发：I1 spec-implementation-plan → I2 spec-implementation-execute → finishing-development
  • 需要更完整规格/原型：R2/R3/R4（按需）后再进入 I1/I2