Claude Skill

spec-direction-gate

技术方案文档的方向确认关卡。在 specs/<id>/TECH.md 草稿完成、进入实施之前,先确认方向、再确认内容,两次确认分开且有序;把关卡结论写回 TECH.md 作为批准状态的显式记录。拒绝语义:没有人在场就停止并报告,绝不自动放行。用于任何"文档获批才能开始写代码"的环节之前。

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download chenweil-skillcaddy-skills_spec-pipeline_spec-direction-gate-c14ddfd.zip · 5 KB

Install

skills CLI npx skills add https://github.com/chenweil/skillcaddy/tree/main/skills/spec-pipeline/spec-direction-gate
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install chenweil-skillcaddy@llmmart
Git git clone https://github.com/chenweil/skillcaddy.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole chenweil/skillcaddy collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

方向确认关卡(B)

一条流程只有在"方向"这一格真的会挡住它的时候才算成立。这个技能就是那一格。

输入是 specs/<id>/TECH.md 的草稿,输出是写回 TECH.md 的批准状态记录。中间没有任何自动放行的路径。

何时使用

  • TECH.md 草稿已写完,尚未开始实施
  • 需要在实施前留下"谁在什么时候批准了方向"的可核验记录
  • 复盘时需要确认某个实施是否真的经过方向批准,而不是默认通过

何时不使用

  • 纯 UI 改动、单文件修复等低复杂度变更,TECH.md 本身就不必产出
  • 方向已经单独确认过、这次只是修订若干小节时,改用下面的"增量修订"路径

硬性约束

  1. 两次确认,不合并。 先确认方向,确认通过之后才确认内容。合并这一步会破坏关卡:把大纲和方向放在同一次确认里,人会锚定在已经看到的具体大纲上,而不再重新考虑它上位的那个问题。
  2. 拒绝语义。 没有人在场就停止并报告这个技能需要人,不要"先按草稿往下走,回头再确认"。
  3. 批准要落盘。 两次确认的结论写进 TECH.md,不只留在对话里。实施阶段的验收要能读到"批准后文档仍存活"的证据。
  4. 批准的是方向,不是逐字内容。 方向确认通过后,作者仍可改实现细节;实施者不得改方向。

流程

第 0 步:确认在场

先确认当前是有人可以回答的交互会话。

不是交互式会话时:停下并报告"这个关卡需要人在场确认方向",然后结束。不要用默认值代替确认,也不要因为草稿看起来已经足够好就跳过。

第 1 步:确认方向

读 TECH.md,然后只向人提出方向层面的问题,不要展示具体大纲或章节结构:

  • 这份文档要解决的问题,和仓库当前状态对得上吗
  • 选定的方案,是这几个候选里最合适的那个吗
  • 哪些明确不在这次范围内
  • 还有什么上位问题,是这份文档答不了的

把问题一次问完,然后等回答。

方向被拒时的处理:记录被拒的方向和原因,停止。不要改写成新的大纲再问第二遍——那等于把第一次确认作废。修改草稿后必须从第 1 步重来。

第 2 步:确认内容

只有在第 1 步通过后才进入这一步。展示文档的实际章节和每节承担的内容,然后等确认。

内容被拒时:按意见修订,同样从第 1 步重新开始(内容修订可能改变方向)。

第 3 步:写回批准状态

两次都通过后,把结论追加到 TECH.md 末尾:

## Approval

- 方向确认:通过 / 拒绝(时间:YYYY-MM-DD HH:MM CST,确认人:__)
- 内容确认:通过 / 拒绝(时间:YYYY-MM-DD HH:MM CST,确认人:__)
- 本次确认的范围:仅方向与结构。实现细节可由作者调整,方向变更须重新过本关卡。

批准状态是显式记录,不是推断依据。没有这段内容,验收阶段必须按"未批准"处理。

写完用同目录的校验脚本自查:

python3 check-approval.py specs/<id>/TECH.md

退出码 0 = 已批准可进入实施;1 = 挡住(缺 ## Approval、结论仍是 通过 / 拒绝 模板、缺时间戳、方向被拒、结论无法判定);2 = 用法错误。

模板里的 通过 / 拒绝 必须二选一写死。两个候选都留着会被判为未批准——这是有意的,模板没填就等于没确认。

实施前的机械检查

上面的约束是文字。文字挡不住无人值守运行,所以本技能附带一个退出码校验:

python3 check-approval.py specs/<id>/TECH.md

进入实施之前跑一次,退出码非 0 就不要开始写代码。脚本只读不写,不会改文档。

被挡住的常见情况:

  • 文件不存在
  • 没有 ## Approval 段
  • 有 ## Approval 段但里面没有方向确认结论(摄入技能产出的就是这个状态)
  • 结论仍是 通过 / 拒绝 模板
  • 通过但没写时间戳(批准必须可核验到"谁在什么时候批准")
  • 方向被明确拒绝
  • 既不是通过也不是拒绝——按未批准处理

## Approval 之后如果还有别的章节,脚本只读到下一个章节标题为止;把"方向确认:通过"藏在后面的章节里不算数。## Source draft 之类段落里出现的"通过"也不会被误读成批准。

增量修订路径

只改了措辞、补充了行级引用、调整了不影响方向的实施顺序时,不必重走两次确认。在现有的 ## Approval 段下面追加一条修订记录,写明改了什么、为什么不需要重新确认方向。

判断权在人手上。拿不准就走完整路径。

与其他技能的衔接

  • 上游:write-tech-spec 产出 TECH.md(specs/<id>/ 目录约定)
  • 下游:implement-specs 的前置条件只是"approved enough"这种软条件,不构成关卡。真正的关卡在这里,跑完本技能才算进入实施
  • 实施期间:write-tech-spec 的 Keep the spec current 要求 TECH.md 随实施同 PR 更新,且不得删掉 ## Approval 段——批准状态是验收阶段要核验的东西
  • 验收阶段:新会话中对照文档验收,不对照对话

验收用例

要能构造"方向被拒"的用例,流程必须停止并报告,不得自动续跑。判定依据是对照 write-feature-docs 第 449–454 行的拒绝语义:不得重新加入无人值守路径,须停下并报告该技能需要人工在场。

Files (skillcaddy)
  • check-approval.py 3.9 KB
    Loading…
  • SKILL.md 6 KB
    ---
    name: spec-direction-gate
    description: 技术方案文档的方向确认关卡。在 specs/<id>/TECH.md 草稿完成、进入实施之前,先确认方向、再确认内容,两次确认分开且有序;把关卡结论写回 TECH.md 作为批准状态的显式记录。拒绝语义:没有人在场就停止并报告,绝不自动放行。用于任何"文档获批才能开始写代码"的环节之前。
    disable-model-invocation: true
    ---
    
    # 方向确认关卡(B)
    
    一条流程只有在"方向"这一格真的会挡住它的时候才算成立。这个技能就是那一格。
    
    输入是 `specs/<id>/TECH.md` 的草稿,输出是写回 `TECH.md` 的批准状态记录。中间没有任何自动放行的路径。
    
    ## 何时使用
    
    - `TECH.md` 草稿已写完,尚未开始实施
    - 需要在实施前留下"谁在什么时候批准了方向"的可核验记录
    - 复盘时需要确认某个实施是否真的经过方向批准,而不是默认通过
    
    ## 何时不使用
    
    - 纯 UI 改动、单文件修复等低复杂度变更,`TECH.md` 本身就不必产出
    - 方向已经单独确认过、这次只是修订若干小节时,改用下面的"增量修订"路径
    
    ## 硬性约束
    
    1. **两次确认,不合并。** 先确认方向,确认通过之后才确认内容。合并这一步会破坏关卡:把大纲和方向放在同一次确认里,人会锚定在已经看到的具体大纲上,而不再重新考虑它上位的那个问题。
    2. **拒绝语义。** 没有人在场就停止并报告这个技能需要人,不要"先按草稿往下走,回头再确认"。
    3. **批准要落盘。** 两次确认的结论写进 `TECH.md`,不只留在对话里。实施阶段的验收要能读到"批准后文档仍存活"的证据。
    4. **批准的是方向,不是逐字内容。** 方向确认通过后,作者仍可改实现细节;实施者不得改方向。
    
    ## 流程
    
    ### 第 0 步:确认在场
    
    先确认当前是有人可以回答的交互会话。
    
    不是交互式会话时:**停下并报告**"这个关卡需要人在场确认方向",然后结束。不要用默认值代替确认,也不要因为草稿看起来已经足够好就跳过。
    
    ### 第 1 步:确认方向
    
    读 `TECH.md`,然后只向人提出**方向层面**的问题,不要展示具体大纲或章节结构:
    
    - 这份文档要解决的问题,和仓库当前状态对得上吗
    - 选定的方案,是这几个候选里最合适的那个吗
    - 哪些明确不在这次范围内
    - 还有什么上位问题,是这份文档答不了的
    
    把问题一次问完,然后等回答。
    
    **方向被拒时的处理**:记录被拒的方向和原因,停止。不要改写成新的大纲再问第二遍——那等于把第一次确认作废。修改草稿后必须从第 1 步重来。
    
    ### 第 2 步:确认内容
    
    只有在第 1 步通过后才进入这一步。展示文档的实际章节和每节承担的内容,然后等确认。
    
    内容被拒时:按意见修订,同样从第 1 步重新开始(内容修订可能改变方向)。
    
    ### 第 3 步:写回批准状态
    
    两次都通过后,把结论追加到 `TECH.md` 末尾:
    
    ```markdown
    ## Approval
    
    - 方向确认:通过 / 拒绝(时间:YYYY-MM-DD HH:MM CST,确认人:__)
    - 内容确认:通过 / 拒绝(时间:YYYY-MM-DD HH:MM CST,确认人:__)
    - 本次确认的范围:仅方向与结构。实现细节可由作者调整,方向变更须重新过本关卡。
    ```
    
    批准状态是**显式记录**,不是推断依据。没有这段内容,验收阶段必须按"未批准"处理。
    
    写完用同目录的校验脚本自查:
    
    ```bash
    python3 check-approval.py specs/<id>/TECH.md
    ```
    
    退出码 `0` = 已批准可进入实施;`1` = 挡住(缺 `## Approval`、结论仍是 `通过 / 拒绝` 模板、缺时间戳、方向被拒、结论无法判定);`2` = 用法错误。
    
    模板里的 `通过 / 拒绝` 必须二选一写死。**两个候选都留着会被判为未批准**——这是有意的,模板没填就等于没确认。
    
    ## 实施前的机械检查
    
    上面的约束是文字。文字挡不住无人值守运行,所以本技能附带一个退出码校验:
    
    ```bash
    python3 check-approval.py specs/<id>/TECH.md
    ```
    
    进入实施之前跑一次,退出码非 `0` 就不要开始写代码。脚本只读不写,不会改文档。
    
    被挡住的常见情况:
    
    - 文件不存在
    - 没有 `## Approval` 段
    - 有 `## Approval` 段但里面没有方向确认结论(**摄入技能产出的就是这个状态**)
    - 结论仍是 `通过 / 拒绝` 模板
    - 通过但没写时间戳(批准必须可核验到"谁在什么时候批准")
    - 方向被明确拒绝
    - 既不是通过也不是拒绝——按未批准处理
    
    `## Approval` 之后如果还有别的章节,脚本只读到下一个章节标题为止;把"方向确认:通过"藏在后面的章节里不算数。`## Source draft` 之类段落里出现的"通过"也不会被误读成批准。
    
    ## 增量修订路径
    
    只改了措辞、补充了行级引用、调整了不影响方向的实施顺序时,不必重走两次确认。在现有的 `## Approval` 段下面追加一条修订记录,写明改了什么、为什么不需要重新确认方向。
    
    判断权在人手上。拿不准就走完整路径。
    
    ## 与其他技能的衔接
    
    - 上游:`write-tech-spec` 产出 `TECH.md`(`specs/<id>/` 目录约定)
    - 下游:`implement-specs` 的前置条件只是"approved enough"这种软条件,**不构成关卡**。真正的关卡在这里,跑完本技能才算进入实施
    - 实施期间:`write-tech-spec` 的 *Keep the spec current* 要求 `TECH.md` 随实施同 PR 更新,且**不得删掉 `## Approval` 段**——批准状态是验收阶段要核验的东西
    - 验收阶段:新会话中对照文档验收,不对照对话
    
    ## 验收用例
    
    要能构造"方向被拒"的用例,流程必须停止并报告,不得自动续跑。判定依据是对照 `write-feature-docs` 第 449–454 行的拒绝语义:不得重新加入无人值守路径,须停下并报告该技能需要人工在场。
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.