Smithery is now a part of Arcade.dev! Read more in our announcement here
提供系统化的 9 阶段需求分析与实施工作流（需求理解、代码探索、外部资源研究、澄清问题、深度分析、展示计划、实施开发、代码审查、总结）。适用于复杂功能开发、多方案对比、新技术栈研究等需要深度规划和完整实施的场景。当用户提出复杂功能开发、API设计、数据库设计且需要深度分析和外部资源研究时触发。
语言协议：以对话语言输出——用户显式指定（含平台
language设置）优先，其次跟随用户近期消息语言；均无法判定时默认英语。落盘产物以创建时对话语言为准，增量修改保持产物既有语言。本 skill 中的固定话术是语义模板，用对话语言表达其意，不逐字照搬。
插件根：
${CLAUDE_PLUGIN_ROOT}——本 skill 正文与其 references 中的插件根命令以此为准；若上式仍为变量字面量（平台未替换），按 requirement-analysis 的 references/exploration-patterns.md「插件根解析」序列推导。
通过自然的协作对话，把想法转化为经过验证的完整设计与 spec。
先理解项目现状，再逐题澄清打磨想法；理解到位后做对抗验证、给出多方案对比；用户批准设计后落盘 spec，最终交接 writing-plans 生成实施计划。
进入本流程先取得适用入口规则：实际读取 clarifying 核心纪律 与 共享入口，再开始项目材料读取或提问；已有当前定义直接复用。按共享入口区分内部材料、外部事实与下一动作，再在动作前取得对应完整专题，不无条件加载全部外部派发和恢复细则。澄清按被引用模式消费。
首次材料读取前分类：按共享入口核对事实归属；本地存放的第三方材料仍属外部事实。外部研究前取得来源纪律，派发、插件命令与结果消费前分别取得适用专题。
需求不论大小都要经过设计批准（HARD-GATE），但设计的篇幅与流程按档位裁剪：light 档一次成稿一次批准（阶段 5 与阶段 7 合并，不派 spec-reviewer 子代理）；standard 档走完整八阶段；deep 档在 standard 之上扩大探索与方案分析。"简单"需求恰恰是未经检验的假设造成返工最多的地方——所以 light 档省的是文书，不省批准。
必须为以下每一项创建任务（Claude Code 用 TaskCreate，Codex 用 update_plan），按序完成；被跳过的项标记完成并注明原因：
.spec-dev/YYYY-MM-DD-NN-<feature>/spec/<feature>-design.md 并 git commit分诊 → 探索 → 澄清 → 信息对抗与方案选择 → 完整设计批准 → 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 — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
探索：multi-modal sweep，按模态数派发、不设上限；方案对比含更完整的风险分析
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 环境的完整规则同见该文件。
目标：理解意图，给流程定参。
.spec-dev/explorations/ 探索笔记时作为本阶段输入，已探索过的部分阶段 2 不重做.spec-dev/reports/YYYY-MM-DD-NN-<topic>.md 吗」（结构从轻：问题、结论、依据来源；目录随首个报告创建；同一 NN 序列全 .spec-dev/ 日期前缀产物共用），用户婉拒则只留对话、零落盘。建议式，由用户裁决。结论要落地成代码时回归正常分诊——报告通道不是实施后门.spec-dev/roadmaps/YYYY-MM-DD-NN-<project>.md（同一 NN 序列全 .spec-dev/ 日期前缀产物共用）并 git commit（登记时同步填写「原始需求」节——用户原话全文，与每子项目「上下文胶囊」——关键裁决/探索指针/已扫范围），然后只对第一个（或用户指定的）子项目走本流程。roadmap 是分解决策唯一的持久化位置——不落盘，其余子项目就只活在本次对话里，会话一结束静默蒸发.spec-dev/roadmaps/ 下某 active roadmap 的 pending 子项目与本需求对得上）→ 载入该 roadmap 的目标/分解边界/备注，并读取该子项目上下文胶囊指向的前置产物（前置子项目 spec 的「背景与目标」与验收报告结论、探索指针文件），以此为阶段 1-2 输入直接走本流程、不重新分解、不要求用户重新提供原始需求；阶段 2 探索对胶囊「已扫范围」登记过的模态不重扫、只补缺口；依赖的前置子项目未交付时先向用户指出。roadmap 目录不存在或无命中 → 本条零动作，正常走流程目标：一个波次拿齐内部代码事实与外部最佳实践。
首要任务：查找并阅读项目规范文件（优先级按环境映射表）。
编排：内部与外部主题在无依赖、输入齐全时尽早并发；同波次可多次调用，容量不足分批完成全部已选主题。不要为满足单条消息而超容量派发，也不要无故逐个启动后立即等待；策略见 exploration-patterns.md。
code-explorercode-explorer；阶段 1 标记了外部探索时，同波次加 1-2 个 external-resource-explorercode-explorer 彼此盲扫，模态数由项目形态决定、不设上限；外部按主题拆多个 external-resource-explorer 同波次发起外部研究沿入口的首次材料分类和规则取得要求执行；分类、定义加载与派发细则以 exploration-patterns.md 为单点。
外部探索工具优先级：AnySearch（通用/垂直/批量，插件内嵌）优先 → WebSearch / WebFetch 兜底；派发外部探索子代理时须在派发词中主动重申此优先级（不依赖 agent 定义文件生效，Codex 端尤其如此）；降级链与模态定义、契约校验、失败隔离规则见 exploration-patterns.md。
每个子代理必须给定：有界主题、来源线索、可判定的完成条件、显式排除项、期望输出及适用的工具优先级/文档时效提醒；按 exploration-patterns.md「完成条件与排除项」和派发要求校准，不复制定义。失败先缩小范围重试 1 次，再失败主线程接管（定义见 exploration-patterns「派发要求与失败隔离」）。
目标：解决所有模糊、歧义与多解取舍。
提问纪律遵循 clarifying skill（被引用模式，纪律定义以 clarifying 为准）：用单题澄清与可见清单处理当前范围，不在此复述核心纪律枚举。澄清后直接进入阶段 4，不触发独立共识摘要或三出口；Codex 逐题规则见 clarifying，三道门呈现见 codex-compat.md。
可视化预览（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 写错、缺项或必须重新批准。确实缺记录或存在冲突时才按原修订流程处理。
目标：先证伪自己的信息，再给出可比较的方案。
零子代理：本阶段全部在主线程完成，用 sequential-thinking skill（插件内嵌，bun/tsx → scripts/think.mjs Node 端口自动降级）结构化推进；该 skill 及其运行时均不可用时降级为在回复中显式分点推演并注明工具降级原因，不得因工具缺失跳过分析。
第一步——信息对抗验证。对阶段 1-3 收集的每条承重结论（将直接决定方案取舍的事实）逐条质询：
冲突未消解前不进入方案设计。
第二步——提出 2-3 个方案。基于验证后的信息给出方案对比：
目标：把选定方案展开为完整设计，整篇获得批准。
完整设计获批后，先读 Spec 生命周期 和适用的 文档规范，再按实际授权保存。保留日期编号、frontmatter、可观察 Requirement/Scenario、取代分流与限定文件提交；不从摘要推定已执行。
完整自检、独立审查与一次整体用户 review 见 Spec 审查。仍须持有最新版的明确确认，不把保存/提交话术当事实。
持有用户对开始编写实施计划的明确同意；已有同范围决定不重复问。 按 Spec 生命周期 完成 active 激活及适用的取代预告，再调用 writing-plans。 仅认可 spec 内容不等于授权实施，不能直接调用 executing-plans。
出现以下想法时，停下来重新对照 Checklist：
