smithery.ai

requirement-analysis

>- Requirement design workflow - mandatory before any creative development (new features, components, behavior changes, API/DB design): triage, parallel exploration, one-question-at-a-time clarification, adversarial validation and 2-3 option comparison produce a spec, then hand off to writing-plans. Use exploring first while the idea is unsettled; not for pure Q&A, test runs, or no-design-space small fixes (use quick-fix). / 需求设计工作流——在任何创造性开发工作(新功能、新组件、行为变更、API/数…

First seen Mar 11, 2026

Installation

$ npx skills add https://smithery.ai

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

Also in this package

Other skills from smithery.ai · top by installs.

npx skills add https://smithery.ai

Browse all from smithery.ai

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Skill metadata

Parsed from SKILL.md frontmatter.

Declared agents claude-code

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 28,174 B
  • docs SUMMARY.md 457 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 35 installs

SKILL.md

Language Protocol / 语言协议: Respond in the user's conversation language — an explicit user instruction (including the platform language setting) takes precedence, then the language of the user's recent messages; default to English when neither indicates a language. All deliverables written to the repo (specs, plans, reports, notes) follow the conversation language at creation; incremental edits keep the artifact's existing language. Fixed-wording prompts in this skill are semantic templates — express their meaning in the conversation language, don't quote them verbatim.
语言协议:以对话语言输出——用户显式指定(含平台 language 设置)优先,其次跟随用户近期消息语言;均无法判定时默认英语。落盘产物以创建时对话语言为准,增量修改保持产物既有语言。本 skill 中的固定话术是语义模板,用对话语言表达其意,不逐字照搬。

需求设计工作流

通过自然的协作对话,把想法转化为经过验证的完整设计与 spec。

先理解项目现状,再逐题澄清打磨想法;理解到位后做对抗验证、给出多方案对比;用户批准设计后落盘 spec,最终交接 writing-plans 生成实施计划。

<HARD-GATE> 在设计展示给用户并获得批准之前,不得调用任何实施类 skill、不得编写任何代码、不得搭建任何脚手架、不得采取任何实施动作。此门槛适用于所有项目,无论看起来多简单。 </HARD-GATE>

反模式:"这需求太简单,不需要设计"

所有需求都要走完本流程。加一个字段、改一处文案、一个单函数工具——都一样。"简单"需求恰恰是未经检验的假设造成返工最多的地方。设计可以很短(light 档几句话即可),但必须展示并获得批准

Checklist

必须为以下每一项创建任务(Claude Code 用 TaskCreate,Codex 用 update_plan),按序完成;被跳过的项标记完成并注明原因:

  1. 需求理解与分诊 — 理解意图,判定档位,标记外部探索/视觉候选
  2. 并行探索 — 内部代码 + 外部资源同一波次 fan-out,深度按档位
  3. 澄清问题 — 一次一个问题,不限轮数;视觉问题 JIT 提议 visual-preview
  4. 对抗验证 + 提出 2-3 方案 — sequential-thinking 校验信息后给方案与推荐,用户选定
  5. 展示完整设计 — 整篇展示不分章节,获得用户批准
  6. 写 spec 并提交 — 落盘 .spec-dev/YYYY-MM-DD-NN-<feature>/spec/<feature>-design.md 并 git commit
  7. Spec self-review + 对抗验证 — inline 自检 + 审查子代理;有修改则请用户再 review
  8. 交接 writing-plans — 唯一终态;经用户确认后调用 writing-plans 生成实施计划

流程图

digraph requirement_analysis {
    "1 需求理解与分诊" [shape=box];
    "2 并行探索(内部+外部)" [shape=box];
    "3 澄清问题(逐题)" [shape=box];
    "4 对抗验证 + 2-3 方案" [shape=box];
    "用户选定方案?" [shape=diamond];
    "5 展示完整设计" [shape=box];
    "用户批准设计?" [shape=diamond];
    "6 写 spec 并提交" [shape=box];
    "7 self-review + 对抗验证" [shape=box];
    "用户 review 通过?" [shape=diamond];
    "8 调用 writing-plans" [shape=doublecircle];

    "1 需求理解与分诊" -> "2 并行探索(内部+外部)";
    "2 并行探索(内部+外部)" -> "3 澄清问题(逐题)";
    "3 澄清问题(逐题)" -> "4 对抗验证 + 2-3 方案";
    "4 对抗验证 + 2-3 方案" -> "用户选定方案?";
    "用户选定方案?" -> "4 对抗验证 + 2-3 方案" [label="要求调整"];
    "用户选定方案?" -> "5 展示完整设计" [label="选定"];
    "5 展示完整设计" -> "用户批准设计?";
    "用户批准设计?" -> "5 展示完整设计" [label="否,修订"];
    "用户批准设计?" -> "6 写 spec 并提交" [label="是"];
    "6 写 spec 并提交" -> "7 self-review + 对抗验证";
    "7 self-review + 对抗验证" -> "用户 review 通过?";
    "用户 review 通过?" -> "6 写 spec 并提交" [label="要求修改"];
    "用户 review 通过?" -> "8 调用 writing-plans" [label="通过"];
}

终态是调用 writing-plans。 不得调用 executing-plans、acceptance-qa 或任何其他实施类 skill——本 skill 之后唯一可调用的 skill 是 writing-plans。

执行档位

档位在阶段 1 判定,向用户声明并允许覆盖;它只调节探索规模与 spec 篇幅,不豁免任何 Checklist 项与 HARD-GATE

light    — 单文件/单模块、无新依赖、无方案分歧(如加字段、改文案)
           探索:主线程直查或 1 个子代理;方案可收敛为 1 个(说明为何无分歧);spec 几句话到半页
standard — 默认档。跨 2-3 模块或有方案取舍
           探索:按架构层次或功能模块 3-5 个子代理;完整 2-3 方案对比
deep     — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
           探索:multi-modal sweep,按模态数派发、不设上限;方案对比含更完整的风险分析

判定依据:涉及文件数与模块数(阶段 1 初判、阶段 2 修正)、是否引入新依赖、是否存在多解取舍、用户措辞强度。声明格式:「本需求判定为 {档位}(理由),如需更彻底/更轻量请告知」。

执行环境兼容性

本 skill 同时兼容 Claude Code 和 Codex。核心工具映射:

用途 Claude Code Codex
用户澄清/确认 AskUserQuestion(单题带选项) 对话消息提问并等待回复
进度跟踪 TaskCreate / TaskUpdate update_plan
并行子任务 Agent(单响应一次性发起) spawnagent(继承上下文,参数见 codex-compat)+ waitagent
项目规范文件 CLAUDE.mdAGENTS.md AGENTS.mdCLAUDE.md
网页搜索 anysearch skill(内嵌)→ WebSearch 降级 anysearch skill(内嵌)→ 内置 web 搜索降级(托管 web_search 工具)

Codex 环境的完整规则见 [codex-compat.md](references/codex-compat.md)。


阶段 1: 需求理解与分诊

目标:理解意图,给流程定参。

  • 理解核心功能、业务实体、约束与成功标准;描述模糊或多模块时用 sequential-thinking skill(插件内嵌)分解
  • 意图承诺检查:用户仍在"要不要做"的犹豫期(探索性措辞、无交付承诺)→ 建议切换 exploring skill,不硬拉八阶段;存在相关的 .spec-dev/explorations/ 探索笔记时作为本阶段输入,已探索过的部分阶段 2 不重做
  • 小修检查:需求其实是"已决定要修、无设计空间"的小 bug 修复/小调整(单点 bug、单常量、单文案,无方案取舍、不跨模块、不引入新依赖)→ 建议切换 quick-fix skill,不硬拉八阶段;这是意图承诺检查的对偶——那边挡"还没决定要不要做",这边挡"决定了但不值得走完整设计"。建议式(不自动切换),由用户裁决。大小/设计空间拿不准的已承诺开发请求,同样建议先走 quick-fix——其步骤 2.5 基于根因证据的升级门(含上下文交接)比入口猜测更准,升级便宜、降级浪费
  • 任务类型检查(报告通道权威定义):需求已承诺交付、但交付物不是代码变更(调研报告、方案对比、日志分析等非开发交付)→ 建议走报告通道,不硬拉八阶段:不建特性目录、不写 spec/plan;需要时按 clarifying 纪律澄清关注点;主线程产出结论后问一次「落盘为 .spec-dev/reports/YYYY-MM-DD-NN-<topic>.md 吗」(结构从轻:问题、结论、依据来源;目录随首个报告创建;同一 NN 序列全 .spec-dev/ 日期前缀产物共用),用户婉拒则只留对话、零落盘。建议式,由用户裁决。结论要落地成代码时回归正常分诊——报告通道不是实施后门
  • 范围分解检查:需求的意图必须能用一句话说清——说不清就该拆。出现过大信号(范围读起来像不相关功能清单、审查一份 spec 要一下午、两人同时做会撞车、一半任务可独立交付)或描述了多个独立子系统(如"做一个带聊天、文件存储、计费、分析的平台")时立即指出,先帮用户分解为子项目(各自独立的 spec → plan → 实施周期)——不要在一个需要分解的项目上浪费澄清轮次。分解说完不算完,两个配套动作:

- 分解登记(roadmap):拆分方案(子项目清单、一句话范围、依赖顺序)经用户确认后,按 [roadmap-template.md](assets/roadmap-template.md) 落盘 .spec-dev/roadmaps/YYYY-MM-DD-NN-<project>.md(同一 NN 序列全 .spec-dev/ 日期前缀产物共用)并 git commit(登记时同步填写「原始需求」节——用户原话全文,与每子项目「上下文胶囊」——关键裁决/探索指针/已扫范围),然后只对第一个(或用户指定的)子项目走本流程。roadmap 是分解决策唯一的持久化位置——不落盘,其余子项目就只活在本次对话里,会话一结束静默蒸发 - 续接检查:需求命中某 active roadmap 的既有子项目时(用户点名"继续 <项目>",或 .spec-dev/roadmaps/ 下某 active roadmap 的 pending 子项目与本需求对得上)→ 载入该 roadmap 的目标/分解边界/备注,并读取该子项目上下文胶囊指向的前置产物(前置子项目 spec 的「背景与目标」与验收报告结论、探索指针文件),以此为阶段 1-2 输入直接走本流程、不重新分解、不要求用户重新提供原始需求;阶段 2 探索对胶囊「已扫范围」登记过的模态不重扫、只补缺口;依赖的前置子项目未交付时先向用户指出。roadmap 目录不存在或无命中 → 本条零动作,正常走流程

  • 判定档位并声明(见"执行档位")
  • 打标记,供后续阶段消费:

- 需要外部探索?——涉及新第三方库/框架、需要行业最新实践、内部示例不足,任一满足即标记 - 视觉候选?——需求涉及 UI 布局、页面结构、视觉风格等"看比说清楚"的题材时标记;此标记只影响阶段 3 的 JIT 提议时机,不在此时提议 - 契约姿态判定:需求措辞含破坏性重构信号("重构""推翻""可破坏""不留兼容"等)且预计触及既有 active spec/ADR 时,在本阶段(先于阶段 2 派发)以一道澄清题当场确认这些旧契约是硬约束(默认)还是仅现状输入——姿态结论决定探索派发词,不能等到阶段 3。确认降格后:阶段 2 主波次与回补探索的派发词均须携带该姿态结论,子代理不得把降格契约当设计约束报告(仅作现状与迁移分析输入);阶段 4 方案对比不因"违反旧 spec 契约"排除选项

阶段 2: 并行探索

目标:一个波次拿齐内部代码事实与外部最佳实践。

首要任务:查找并阅读项目规范文件(优先级按环境映射表)。

编排:内部与外部探索相互独立,必须在单条消息中一次性发起全部子代理——分批发起会退化为串行等待。子代理数量不设上限,按档位与需求结构决定:

  • light:主线程直查(Glob/Grep/Read 或 codegraph),或 1 个 code-explorer
  • standard:按架构层次或功能模块拆 3-5 个 code-explorer;阶段 1 标记了外部探索时,同波次加 1-2 个 external-resource-explorer
  • deep:multi-modal sweep——每个模态一个 code-explorer 彼此盲扫,模态数由项目形态决定、不设上限;外部按主题拆多个 external-resource-explorer 同波次发起

外部探索工具优先级:AnySearch(通用/垂直/批量,插件内嵌)优先 → WebSearch / WebFetch 兜底;派发外部探索子代理时须在派发词中主动重申此优先级(不依赖 agent 定义文件生效,Codex 端尤其如此);降级链与模态定义、契约校验、失败隔离规则见 [exploration-patterns.md](references/exploration-patterns.md)。

每个子代理必须给定:清晰的主题或模态、相关文件线索、期望输出格式、工具优先级与文档时效规则提醒(后两项定义见 exploration-patterns 派发要求)。失败的子代理先缩小范围重试 1 次,再失败由主线程接管。

阶段 3: 澄清问题

目标:解决所有模糊、歧义与多解取舍。

提问纪律遵循 clarifying skill 的核心纪律(被引用模式,纪律定义以 clarifying 为准):提问前自我披露(假设/关键信息/易犯错三段先行)、一次只问一个问题、选择题优先且推荐项放首位(Claude Code 用 AskUserQuestion)、事实自查决策交用户、按决策依赖排序、术语挑战、不编造问题——无疑点则明确记录"需求已清晰,无需澄清"后进入阶段 4。本阶段是引用方:澄清完成后直接进入阶段 4,不触发 clarifying 的共识摘要与三出口。Codex 逐题提问规范见 clarifying 内嵌的 Codex 规范节;三道门的对话呈现要求见 [codex-compat.md](references/codex-compat.md)。

  • 优先覆盖:目的、约束、成功标准;阶段 1-2 暴露的歧义、约束冲突、隐含假设、边缘场景
  • 术语挑战裁决出的规范术语全程沿用,并在 spec 术语表中记录规范名、一句话定义与 Avoid 别名(挑战动作属 clarifying 纪律,术语表落盘是本阶段职责)

可视化预览(JIT 提议):不要在开场提议。当某个问题用看的比用说的更清楚时(真实的 mockup/布局/图示问题,而不只是"话题涉及 UI"),首次出现的那一刻单独发一条消息提议使用 visual-preview skill——该消息只含提议、不夹带其他问题。用户接受则按 visual-preview skill 执行;拒绝则继续纯文字,不再重复提议。逐题判断浏览器 vs 终端:内容本身是视觉的(线框、布局对比、架构图)用浏览器,内容是文字的(需求、取舍、概念选择)留在终端。

回补探索:澄清或方案期发现新库/新领域,允许回补一轮外部探索(同样单响应发起),回补后继续当前阶段。

阶段 4: 对抗验证 + 提出 2-3 方案

目标:先证伪自己的信息,再给出可比较的方案。

零子代理:本阶段全部在主线程完成,用 sequential-thinking skill(插件内嵌,bun/tsx → scripts/think.mjs Node 端口自动降级)结构化推进;该 skill 及其运行时均不可用时降级为在回复中显式分点推演并注明工具降级原因,不得因工具缺失跳过分析。

第一步——信息对抗验证。对阶段 1-3 收集的每条承重结论(将直接决定方案取舍的事实)逐条质询:

  • 来源可靠吗?(外部结论:官方文档还是二手博客?版本时效?)
  • 与代码库事实冲突吗?(外部最佳实践与项目现有模式矛盾时,回读代码裁决)
  • 是未验证的假设吗?(是→标记,能在代码中验证的立即验证,只能由用户裁决的回到阶段 3 补问)

冲突未消解前不进入方案设计。

第二步——提出 2-3 个方案。基于验证后的信息给出方案对比:

  • 每个方案:核心思路、与现有模式的契合度、改动半径、风险、成本、设计原则符合度(对照 writing-plans/references/design-principles.md 八条——尤其"是否引入投机抽象""是否留兼容垫片""是否权宜之计"三问)
  • 推荐方案放首位并说明理由,以对话方式呈现,不堆砌表格
  • YAGNI:从所有方案中删掉没人要求的功能
  • light 档确无分歧时可收敛为 1 个方案,但必须说明"为何无分歧"
  • 用户选定方案后才进入阶段 5;用户提出调整则修订方案重新呈现

阶段 5: 展示完整设计

目标:把选定方案展开为完整设计,整篇获得批准。

  • 整篇展示、不分章节逐节确认——一次性给出全文,用户整体反馈
  • 覆盖:架构与组件划分、数据流、关键接口/数据结构、错误处理、测试策略、风险与边缘情况
  • 篇幅与复杂度匹配:light 档几句话,复杂设计每节最多两三百词——设计文档不是越长越好
  • 面向隔离与清晰设计:拆成职责单一、接口明确、可独立理解与测试的单元;每个单元能回答"做什么、怎么用、依赖什么";不读内部实现就能理解一个单元、改内部实现不破坏消费者——做不到就重划边界;整体设计对照 design-principles.md 八条自检
  • 在既有代码库中:跟随现有模式;当前工作触及的既有问题(文件过大、边界混乱)可纳入设计做定向改进,但不做无关重构
  • 用户批准前不进入阶段 6;有修改意见则修订后重新整篇展示

阶段 6: 写 spec 并提交

  • 为本需求创建特性目录 .spec-dev/YYYY-MM-DD-NN-<feature>/(所有 spec-dev 产物统一收纳在项目根目录 .spec-dev/ 下;NN 为当日两位序号——扫描 .spec-dev/ 下当日已有的日期前缀产物(特性目录,及 reports/roadmaps/ 下的文件名)取最大加一、01 起步,落盘前重扫一次防并发撞号:发现同号已被占则顺延并同步修正自引路径;feature 取需求主题的短语义名,跟随项目语言;存量旧命名 YYYY-MM-DD-<feature> 目录不改名(grandfather);同一 NN 序列由全部 .spec-dev/ 日期前缀产物共用),将批准的设计写入其 spec/<feature>-design.md(用户对 spec 位置的偏好优先于此默认值)
  • spec 与后续 writing-plans 的计划(同目录 plan/ 分文件形态:index.md + tasks/ + progress.yaml)共用这一个特性目录——一个需求的全部产物收纳在一处
  • 决策分流(ADR):检查"已确认的关键决策"中是否有同时满足三判据的决策——难以逆转(事后改主意成本高)、缺上下文会费解(未来读者会问"当初为什么这么做")、真实取舍(存在真正的备选且因具体理由选定其一)——满足者每条沉淀为仓库级 .spec-dev/adr/NNNN-<slug>.md(全项目共用一个目录、统一编号:扫描现有最高编号递增,目录不存在时随首个 ADR 创建;落盘前重扫一次目录防撞号——并行会话可能已用掉同号,发现同号文件已存在则顺延取下一号并同步修正正文与链接中的自引编号;正文 1-3 句写清背景、决定与理由即可,值得记住的被否方案附一行),spec 决策节保留一行摘要并链接过去;三判据缺一即不建 ADR——ADR 泛滥和没有 ADR 一样没用。ADR 状态纪律:每条 ADR 标题下带状态行,封闭三态——Status: Accepted (YYYY-MM-DD) / Status: Deprecated (YYYY-MM-DD) — <一句原因,强制> / Status: Superseded by [ADR-NNNN](NNNN-<slug>.md) (YYYY-MM-DD)(同目录文件名相对链接,编号强制;缺状态行的历史 ADR 视同 Accepted)。判据一句话:有替代决策用 Superseded,无替代者且决策语境消失用 Deprecated。Accepted 后正文不可变(仅 status 行、错别字、坏链可改);不做部分推翻——推翻既有 ADR 的任何部分时,新 ADR 完整重述仍有效的结论并整体取代,标题下声明 Supersedes: ADR-NNNN 行,且在本阶段同一提交把旧 ADR 状态行回写为 Superseded by(ADR 取代随裁决即时生效,不等实施交付)
  • 取代分流(supersede triage):对阶段 2 探索命中的每份行为相交 active spec 做三分类判定并写入 spec——完全取代(新 spec 整体替换旧特性)与部分取代(替换旧 spec 的部分 Requirement)登记进 frontmatter supersedes(仓库根相对路径)与正文「取代与共存」节(部分取代必须列出被取代的具体 Requirement 标题清单,每条附一句取代理由);分面共存(同文件不同行为切面、无冲突)不登记 supersedes,记一行判定理由并各自声明 covers。节模板与标注形制见 [spec-template.md](assets/spec-template.md)。用户要求删除整个特性且无新行为承接时,产出仅含 REMOVED Requirements 的轻量 spec 作为后继(记录删除理由,交付时按完全取代回写旧 spec)。spec 的取代回写随交付生效(executing-plans 最终任务),与 ADR 的即时回写构成双轨
  • 结构参考 [spec-template.md](assets/spec-template.md),按需增删节;行为需求必须用 Requirement + Scenario 结构表达### Requirement: 一条一个 SHALL 且可观察,#### Scenario: 用 GIVEN/WHEN/THEN——它们是后续 TDD 测试与验收的直接锚点);修改既有功能时行为部分改用差量三节(ADDED/MODIFIED/REMOVED Requirements,见模板)
  • 漂移守卫锚点(必填):落盘时保留模板顶部的 spec_dev frontmatter,填写 featurecovers(本特性拥有的代码路径 glob;纯文档特性留空数组 [])——此阶段 status 保持 draft。该 frontmatter 是 pre-commit / CI 漂移守卫的锚点,缺失或永停 draft 意味着该特性代码不受"改了代码却没同步 spec"的拦截保护
  • roadmap 回填(仅当本特性是某 active roadmap 的子项目):把特性目录路径回填至 roadmap 对应子项目行、状态置 in-progress;不属于任何 roadmap 则无此步
  • git commit 该 spec 文件、本次新增的 ADR 文件与 roadmap 回填(仅这些文件;非 git 仓库则跳过并向用户说明)

阶段 7: Spec self-review + 对抗验证

第一步——inline 自检(自己以新鲜眼光重读,发现即改,无需复审):

  1. 占位符扫描:有无 "TBD"、"TODO"、未写完的节、含糊的需求?
  2. 内部一致性:各节是否互相矛盾?架构是否与功能描述匹配?术语是否全篇沿用术语表的规范名、未混入 Avoid 别名?
  3. 范围检查:整份 spec 的意图能否一句话说清?是否聚焦到单个实施计划能承载?出现过大信号(不相关功能清单、一半任务可独立交付)则回到分解。警惕伪聚焦:spec 正文自行写了"第一阶段/Phase 1、第二阶段/Phase 2……"或"先做 X 再做 Y"这类阶段化结构——这是未登记的分解伪装成一份聚焦 spec(读起来聚焦,实则把多个实施周期塞进一份 spec,下游 writing-plans 只会为第一阶段写 plan、其余阶段无声蒸发)。命中即回到阶段 1 范围分解检查:把阶段拆成 roadmap 子项目,本 spec 只保留第一阶段的内容
  4. 歧义检查:有无可以两种方式解读的需求?有则选定一种写明
  5. Requirement 质量:每条 Requirement 是否一个 SHALL 且可观察?每条是否至少有一个真正检验它的 Scenario(不是复述)?最怕坏掉的场景有没有命名的 Scenario?差量三节(如使用)分类是否与既有行为对得上?

第二步——对抗验证:派 1 个临时子代理(Claude Code 用 general-purpose,Codex 用 spawn_agent),提示词按 [spec-reviewer-prompt.md](references/spec-reviewer-prompt.md) 模板构造,对 spec 做独立审查(完整性/一致性/清晰度/范围/YAGNI)。审查回报的问题逐条处置:成立则修 spec,不成立则记录理由。

第三步——用户 review 门

「Spec 已写入并提交至 <路径>。请 review,如需修改请告诉我,确认后我们开始编写实施计划。」

等待用户回复。若第一/二步曾修改 spec,必须让用户重新 review 修改后的版本;用户要求修改则改完重跑本阶段。用户确认后才进入阶段 8。

阶段 8: 交接 writing-plans

  • 前置确认:须持有用户对「开始编写实施计划」的明确同意——阶段 7 的确认话术已包含此询问;用户仅认可 spec、未表态是否继续时,先问「现在开始编写实施计划吗?」,同意后才交接
  • 激活漂移守卫:交接前把 spec frontmatter 的 status: draft 翻为 active 并 commit(仅 active 参与漂移拦截——不翻转则守卫对本特性静默失效)
  • 打取代预告(仅当 spec 的 supersedes 非空):翻 active 的同一提交内,向每份被指向的旧 spec H1 标题下写入 Superseded-pending 标注(形制见 spec-template「取代标注形制」节;部分取代写明将被取代的 Requirement 标题)——窗口期的双 active 状态由此对全部消费方显式可判定;后续该计划若被废弃,由 executing-plans 意图级偏差收尾回收此标注
  • 调用 writing-plans skill,基于已批准的 spec 生成实施计划
  • 不得调用任何其他 skill——writing-plans 是本流程唯一的下一步;实施纪律(worktree 隔离、TDD、审查编排)由 writing-plans → executing-plans 链路承接

Key Principles

  • 一次一个问题——不要用一串问题淹没用户
  • 选择题优先——能给具体选项就不问开放式问题
  • YAGNI 无情裁剪——从所有设计里删掉不必要的功能
  • 先证伪再方案——承重信息未经对抗验证不得进入方案设计
  • 多方案对比——定稿前必出 2-3 个方案(light 档例外需说明理由)
  • 增量验证——方案选定、设计批准、spec review 三道门逐一通过
  • 随时回退——发现理解有误就回到对应阶段澄清,不带着错误假设前进
  • 原则先于偏好——方案对比与设计定稿以 design-principles.md 为共同裁决维度

Red Flags

出现以下想法时,停下来重新对照 Checklist:

  • "这太简单了,直接写代码吧" → HARD-GATE 适用于一切需求
  • "一次多问几个问题效率高" → 一次一个
  • "外部搜到的做法直接用" → 先对抗验证,与代码库事实对照
  • "方案很明显,不用对比" → 除 light 档且说明理由外,必出 2-3 方案
  • "设计批准了,spec 就不用再让用户看了" → self-review 后有修改必须让用户再 review
  • "顺手把代码也写了" → 终态只有 writing-plans,实施是后续 skill 的职责
  • "先开工,档位/任务清单回头补" → Checklist 每项建任务,跳过要注明原因
  • "项目太大,先做第一部分,剩下的以后再说" → 分解必须落盘 roadmap:"以后"没有登记就等于不存在
  • "spec 里分个阶段(Phase 1/2/3)就能装下大目标" → 阶段化 spec 是未登记的分解,拆成 roadmap 子项目、spec 只留第一个