Agent Skills: 需求设计工作流

输出语言：用户显式指定（含平台语言设置）优先，其次跟随近期对话，否则使用英语。新产物使用创建时语言，增量修改沿用原文语言；固定话术按语义表达。

插件根：${CLAUDE_PLUGIN_ROOT}——本 skill 正文与其 references 中的插件根命令以此为准；若上式仍为变量字面量（平台未替换），按 requirement-analysis 的 references/exploration-patterns.md「插件根解析」序列推导。

外部搜索统一入口：外部检索先用 anysearch；不可用时按搜索与降级规则执行。

需求设计工作流

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

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

进入本流程先取得适用入口规则：实际读取 clarifying 核心纪律 与 共享入口，再开始项目材料读取或提问；已有当前定义直接复用。按共享入口区分内部材料、外部事实与下一动作，再在动作前取得对应完整专题，不无条件加载全部外部派发和恢复细则。澄清按被引用模式消费。

首次材料读取前分类：按共享入口核对事实归属；本地存放的第三方材料仍属外部事实。外部研究前取得来源纪律，派发、插件命令与结果消费前分别取得适用专题。

反模式："这需求太简单，不需要设计"

需求不论大小都要经过设计批准（HARD-GATE），但设计的篇幅与流程按档位裁剪：light 档一次成稿一次批准（阶段 5 与阶段 7 合并，不派 spec-reviewer 子代理）；standard 档走完整八阶段；deep 档在 standard 之上扩大探索与方案分析。"简单"需求恰恰是未经检验的假设造成返工最多的地方——所以 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 自检；standard/deep 派审查子代理；有修改则请用户再 review（light 档并入第 5 项，一次批准）
8. 交接 writing-plans — 唯一终态；经用户确认后调用 writing-plans 生成实施计划

阶段导航

分诊 → 探索 → 澄清 → 信息对抗与方案选择 → 完整设计批准 → spec 生成 → spec 审查 → 计划交接。

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

执行档位

档位在阶段 1 判定，向用户声明并允许覆盖；它调节探索规模、spec 小节集合与批准门的合并方式，不豁免 HARD-GATE（任何档位都在用户批准前零实施动作）；light 档把 Checklist 第 5 与第 7 项合并为一次批准。

light    — 单文件/单模块、无新依赖、无方案分歧（如加字段、改文案）
           探索：主线程直查或 1 个子代理；方案可收敛为 1 个（说明为何无分歧）
           spec：五节——背景与目标 / 非目标 / 已确认的关键决策 / 行为规范 / 测试与验收策略
           批准：完整设计与 spec 草稿同一条消息呈现，用户一次批准 → 落盘、激活、交接；不派 spec-reviewer
standard — 默认档。跨 2-3 模块或有方案取舍
           探索：按架构层次或功能模块 3-5 个子代理；完整 2-3 方案对比
           spec：light 五节 + 术语表 / 参与者与适用行为 / 影响面 / 约束归属与拒绝的解读 / 取代与共存 / 方案设计 / 风险与边缘情况
           批准：阶段 5 设计批准 + 阶段 7 一次整体 review
deep     — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
           探索：主题按需求确定，在途代理数受平台容量限制，必要时分批完成；方案对比含更完整的风险分析
           spec：全模板；批准同 standard，spec-reviewer 子代理必派

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

执行环境兼容性

本 skill 同时兼容 Claude Code 和 Codex。工具映射（澄清 AskUserQuestion↔对话消息、进度 TaskCreate↔update_plan、并行 Agent↔spawn_agent+wait_agent、规范文件 CLAUDE.md↔AGENTS.md 优先序、搜索 anysearch 降级链）以 codex-compat.md 的工具映射总表为准——全 skill 共用的单一定义点，此处不复述整表；Codex 环境的完整规则同见该文件。

入口判断

先消费明确入口或恢复信息；新请求按最终交付目标、开发承诺与设计空间判断。报告通道不是实施后门，路由建议仍由用户裁决，已有决定不重复询问。

flowchart TD
    E{"明确入口或恢复?"} -->|有| R["沿已确认入口与记录继续"]
    E -->|无| G{"最终交付目标?"}
    G -->|报告或分析| Report["建议报告通道"]
    G -->|功能落地| C{"已承诺开发?"}
    C -->|未承诺| Explore["建议 exploring"]
    C -->|已承诺| D{"有设计空间?"}
    D -->|有| Design["requirement-analysis"]
    D -->|无或需据根因再判| Fix["建议 quick-fix"]

阶段 1: 需求理解与分诊

目标：理解意图，给流程定参。

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

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

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

编排：内部与外部主题在无依赖、输入齐全时尽早并发；同波次可多次调用，容量不足分批完成全部已选主题。不要为满足单条消息而超容量派发，也不要无故逐个启动后立即等待；策略见 exploration-patterns.md。

• 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 同波次发起

外部研究沿入口的首次材料分类和规则取得要求执行；分类、定义加载与派发细则以 exploration-patterns.md 为单点。

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

每个子代理必须给定：有界主题、来源线索、可判定的完成条件、显式排除项、期望输出及适用的工具优先级/文档时效提醒；按 exploration-patterns.md「完成条件与排除项」和派发要求校准，不复制定义。失败先缩小范围重试 1 次，再失败主线程接管（定义见 exploration-patterns「派发要求与失败隔离」）。

阶段 3: 澄清问题

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

提问纪律遵循 clarifying skill（被引用模式，纪律定义以 clarifying 为准）：用单题澄清与可见清单处理当前范围，不在此复述核心纪律枚举。澄清后直接进入阶段 4，不触发独立共识摘要或三出口；Codex 逐题规则见 clarifying，三道门呈现见 codex-compat.md。

• 优先覆盖：目的、约束、成功标准；阶段 1-2 暴露的歧义、约束冲突、隐含假设、边缘场景
• 术语挑战裁决出的规范术语全程沿用；共享术语及冲突处理遵循 context-reuse.md，特性局部术语留在 spec，完整设计批准后再按该约定保存词汇表。

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

回补探索：澄清或方案期发现新库/新领域，允许回补一轮外部探索（同样按实际容量尽早派发），回补后继续当前阶段。

需求完备性与约束归属

standard 档在既有有界探索主题内核对相邻测试、公共行为入口与 fixture/mock 惯例，或单独分配这个主题；细则见 exploration-patterns，不将 standard 升成 deep 多模态盲扫。

在方案定型前枚举实际参与者及其适用行为/错误路径，包括真实的后台或系统触发者；独立约束分别映射负责边界和验证位置。判据沿 writing-plans/references/design-principles 的迁移过渡与约束归属单点，spec 模板保存参与者及有依据的拒绝解读。没有真实 actor/歧义时不为凑数发明，也不重开获批 seam。参与者盘点只记录有来源的能力与边界，不把后台身份推成已有凭据或授权策略。下游先读采用理解及裁决来源；已有完整记录且需求无冲突就直接消费，不因存在拒绝记录而假定 spec 写错、缺项或必须重新批准。确实缺记录或存在冲突时才按原修订流程处理。

阶段 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: 展示完整设计

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

• 整篇展示、不分章节逐节确认——一次性给出全文，用户整体反馈
• 覆盖：架构与组件划分、数据流、关键接口/数据结构、错误处理、测试策略、风险与边缘情况
• 测试落点声明：在本次完整设计中一并展示公共接口与签名/协议、覆盖 Scenario、允许替换的外部依赖（无则写无）和来源。按 test-driven-development 的落点规则优先复用、选择仍可稳定观察行为的较高层接口、减少新接口；获批后写入 spec 测试策略，不增加独立 seam 批准门。
• 篇幅与复杂度匹配：light 档几句话，复杂设计每节最多两三百词——设计文档不是越长越好
• 面向隔离与清晰设计：拆成职责单一、接口明确、可独立理解与测试的单元；每个单元能回答"做什么、怎么用、依赖什么"；不读内部实现就能理解一个单元、改内部实现不破坏消费者——做不到就重划边界；整体设计对照 design-principles.md 八条自检
• 在既有代码库中：跟随现有模式；当前工作触及的既有问题（文件过大、边界混乱）可纳入设计做定向改进，但不做无关重构
• light 档：按 light 五节写好的 spec 草稿随完整设计同一条消息呈现；用户批准即视为阶段 5 与阶段 7 双门通过，直接进入阶段 6 落盘并按阶段 8 激活、交接
• 用户批准前不进入阶段 6；有修改意见则修订后重新整篇展示

阶段 6: 写 spec 并提交

完整设计获批后，先读 Spec 生命周期 和适用的 文档规范，再按实际授权保存。保留日期编号、frontmatter、可观察 Requirement/Scenario、取代分流与限定文件提交；不从摘要推定已执行。

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

完整自检、独立审查与一次整体用户 review 见 Spec 审查。仍须持有最新版的明确确认，不把保存/提交话术当事实。

阶段 8: 交接 writing-plans

持有用户对开始编写实施计划的明确同意；已有同范围决定不重复问。 按 Spec 生命周期 完成 active 激活及适用的取代预告，再调用 writing-plans。 仅认可 spec 内容不等于授权实施，不能直接调用 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 只留第一个