# Scope > Scope product or code changes before implementation when requirements or material technical decisions remain unresolved, including vague requests to create, change, design, plan, or review behavior. Use debug for bugs and failures; use implement for approved specs and confirmed implementation contracts. - Skill: `swm8023/scope` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add swm8023/scope` - Raw SKILL.md: https://api.skillmd.com/api/skills/swm8023/scope/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: swm8023 (https://skillmd.com/u/swm8023) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/swm8023/scope --- # scope —— 把需求拷问清楚 ## 概览 先快速理解项目当前状态与需求规模，然后通过决策树式提问把未决策点拷问清楚。对用户进行不留情面的访谈，直到我们达成共同理解。 ## 硬性关口 阶段 3 确认出口前，不调用实施类 skill，不写代码或执行其他实现动作；此前只允许用户点名的元技能 / 审查技能、必要的只读仓库探索（含 wiki 摘要预检）和 scope 所需的澄清。此关口适用于所有 scope 任务。 ## 流程 ### 阶段 1：判断规模与必要探索 根据预估代码改动量自行判断规模，不问用户： - **小需求**：预估代码改动量足够小，通常只涉及一个局部行为和少量文件，不引入或改变架构、跨模块接口、数据结构、部署或迁移。 - **中大需求**：预估代码改动量较大，涉及多个行为或模块，或包含架构、接口、数据、部署、迁移等重大决策；必要探索后仍无法界定改动规模时按中大需求处理，不因尚未探索就直接升级。 所有规模都允许最小充分探索：搜索相关代码和测试，读取最相关的文件，并按需查看历史提交；已掌握足够事实的小需求可跳过重复探索。不要把代码能回答的问题交给用户。`docs/wiki/` 存在且有助于定位上下文时，先扫描路径和首行摘要，再按需读取少量候选正文；wiki 不能代替代码事实，也不作为阶段 1 的必要条件。 确定需求规模，并掌握建立阶段 2 的决策账本所需的事实后，阶段 1 完成。 ### 阶段 2：拷问式连续提问 #### 入口 根据当前对话和阶段 1 获得的事实建立内部**决策账本**，只跟踪需求边界和技术决策；每项标记为“已确认”“待决策”或“不适用”。账本只用于控制访谈和防止遗漏，不直接抄入实施契约或 spec。 若不存在适用的待决策项，不重新发起访谈，直接检查完成条件。 #### 收敛顺序 先收敛需求，再收敛技术落地： - **需求收敛**：明确目标、支持与排除边界、可观察的正常与失败行为，以及必须保持的兼容行为。 - **技术收敛**：基于已确认需求做针对性只读探索，只确认影响职责、架构、接口、数据、部署、迁移、安全或兼容性的高阶技术决策；局部实现细节留给 implement。 技术方案与已确认需求冲突时，重新打开对应的需求决策。用户推翻已确认结论时，也重新打开对应项。 #### 核心规则 - **决策树式深挖**。每次只选择影响最高的一个待决策项，不重问已确认内容，也不追问“不适用”项；用户回答后更新决策账本，A 的回答决定下一题问 B 还是 B'。 - **每题给推荐答案**。让用户审核而不是白板思考。 - **代码库能答的不问用户**。 - **不擅自揣测**。遇到无法由当前对话或代码事实唯一确定的内容、相互矛盾的结论或多种合理解释时，标记为“待决策”并交由用户决定。 - **优先多选题**（A/B/C + 推荐），开放式次之。 - **选项之间空一行**，确保每个选项是独立 Markdown 段落。 - **关注目的、约束、成功标准**。需求问题不问实现方式；技术问题只问存在实质取舍的落地方案。 #### 完成条件 需求边界和技术决策中的所有适用项均已确认或不适用，且已具备形成设计视图和预估改动面的必要事实后，阶段 2 完成。 ### 阶段 3：总结确认 + 出口选择 #### 入口 只有决策账本中的所有适用项均已确认或不适用，才能进入本阶段。 #### 设计确认 根据阶段 2 已确认的内容，简短呈现双方已经达成一致的目标、需求边界、技术方案，以及理解整体方案所必需的关键结构或流程。 设计呈现只用于暴露理解偏差，不要求达到 spec 的详细度；不展开完整验收证据、预估改动面、文件范围或实施步骤，除非它们会影响已确认决策。 这一轮只做设计确认，不同时给出 A/B 出口。呈现后按以下格式确认： ```markdown 如有偏差，请直接指出；理解一致时确认继续。 确认以上理解并继续选择执行路径？ ``` 用户纠正需求边界或技术方案时，回到阶段 2 重新打开对应决策；仅修正表述时，在本阶段更新后重新呈现。 #### 出口选择 用户确认设计呈现后，按「wiki 落地判断」生成建议，并在同一条消息中按以下格式确认出口和 wiki 目标： ```markdown **wiki 更新建议：** <更新 path / 新建 path / 不更新 wiki> **A. 落 spec** —— 写入 `docs/scope/<日期>-.md`；批准后交给 implement 规划并执行 **B. 不落 spec** —— 在当前对话中生成实施契约；确认后直接交给 implement 执行，不生成 scope 或 plan 文档；契约只存在于本次对话，会话中断即丢失 **推荐路径：** ，<简短理由> 下一步走哪条路径？如需调整 wiki 目标，请一并说明。 ``` 默认依据阶段 1 的规模判断推荐路径：中大需求推荐 A，小需求推荐 B；有明确理由时可以偏离并说明原因。用户选择优先于推荐；路径与 wiki 目标均确认后，才能进入出口执行。 #### 出口执行 正式契约只在用户选择路径并确认 wiki 目标后生成。以决策账本、当前对话中的已确认结论和代码事实为依据，不把设计呈现当作完整契约来源。 验收由 AI 根据需求边界、技术决策和代码事实推导，不要求用户提供；如果推导过程中发现需要用户决定的实质需求或技术歧义，返回阶段 2。 **A. 落 spec** 1. 写 spec 文件前调用 `git-workflow` 的 `prepare` 阶段。 2. 写 `docs/scope/-.md`，按下文模板组织；`slug` 是根据主题生成的 kebab-case 英文短标题。 3. 按下文清单执行完整自我审查并就地修复。 4. 请用户审阅；审阅与修改期间沿用第 1 步建立的 Git 上下文。用户要求修改时，修改后重新完整自审；如果修改导致 wiki 更新目标变化，先向用户确认新的 wiki 文件。 5. 用户批准后，把 spec 头部状态回写为 `> 状态：已批准 `，再调用 `checkpoint` 只处理当前 spec。 6. 调用 `implement`，传入 `source_kind: approved-spec`、`source: `、已确认的 wiki 目标和 `git_state: prepared`；implement 生成 plan 后直接执行，不再二次确认计划。 **B. 不落 spec** 1. 不写 spec 文件；参考下方 spec 模板及通用规则，在对话中生成其精简版，包含目标、决策基线、设计视图（功能设计、技术设计）、预估改动面和验收；只展开本次实施所需内容，关键结构或实现流程按需补充。 2. 按下文清单执行完整自我审查并就地修复。 3. 请用户确认实施契约。 4. 用户确认后调用 `implement`，传入 `source_kind: confirmed-conversation`、`source: <完整对话契约>`、已确认的 wiki 目标和 `git_state: unprepared`；不生成 `docs/scope/` 或 `docs/plans/` 文档，由 implement 直接规划并执行。 #### 完成条件 阶段 3 只允许两种出口：已确认对话契约交给 implement，或已批准 spec 交给 implement。 ## wiki 落地判断 离开 scope、进入 implement 前，必须完成 wiki 落地判断；这个判断不以是否落 spec 为前提。 - **扫描方式**：先读 `docs/wiki/` 路径和每个 `.md` 第一行摘要，再按需读取少量候选正文，形成具体且有事实依据的目标建议；不全库读取正文。 - **确认时机**：阶段 3 询问是否落 spec 时，同时让用户确认 wiki 目标；把结果作为 implement 输入，后续只同步用户确认过的文件。 - **建议类型**：`更新 `、`新建 `、`不更新 wiki`。 - **落 spec**：大任务默认建议同步 wiki。可更新已有页面；也可在用户确认后新建最小必要目录或页面。 - **不落 spec**：小任务只建议更新已有 wiki；没有匹配页面时不新建，除非用户明确要求沉淀。 - **可写入内容**：已确认的架构、约定、术语、稳定流程、模块背景、决策背景。 - **不可写入内容**：未确认猜测、一次性任务步骤、执行 checklist、对话过程。 阶段 3 生成建议前必须已有上述摘要扫描和必要候选正文的判断结果；阶段 1 已获取则复用，否则此时补做。没有匹配页面时，小任务默认“不更新 wiki”，中大任务才可建议在用户确认后新建最小必要页面。不要把“建议更新”当成用户已经授权。 wiki 同步是 implement 的第一个实施工作单元，不改变 scope 出口。 ## spec.md 模板 spec 是 scope 与 implement 之间的设计基线，只保留约束实现或决定验收的结论，不记录访谈过程，也不提前展开 plan。 尖括号内容是字段说明，生成时替换并移除；标注“按需”的章节不适用时省略。 ```markdown > 由 scope skill 于 生成 > 状态：待批准 # <主题> ## 目标 <用一段话说明当前问题和预期结果，不重复边界或方案> ## 决策基线 ### 需求边界 <记录支持场景、正常与失败行为、明确不做及兼容要求；不讨论组件和文件> ### 技术决策 <记录职责、状态所有权、核心机制、接口、数据、存储、迁移、安全等 plan 不得自行改变的高阶结论；只为真实取舍保留必要理由> ## 设计视图 ### 功能设计 <将需求边界综合为完整功能，说明入口、交互、状态、正常与失败行为及功能间关系；不逐条复述需求> ### 技术设计 <将技术决策综合为端到端实现方案，说明系统如何实现功能设计；足以指导 implement 细化实施，但不展开任务步骤> #### 整体方案 <说明系统组成、组件职责、状态与数据所有权、接口边界、依赖关系及协作方式；存在跨模块拓扑、数据流、控制流或状态迁移时，可使用 Mermaid 图辅助，但图不代替关键职责和约束的文字说明> #### 关键结构（按需） <展开影响实现的数据模型、状态、接口或组件关系> #### 实现流程 <从入口到结果写清主要调用、状态变化、异步处理、失败收敛和清理，形成全局实施指导而不是任务清单> ### 预估改动面 <按模块或目录说明预计变化、测试范围和已确认的 wiki 目标；作为 implement 的探索起点，不是硬边界> ## 验收 <覆盖正常行为、重要失败场景和兼容性；逐项使用以下格式> - <场景或约束 → 可观察结果；验证证据> ``` ### 通用规则 - 每项结论只有一个权威定义；决策基线定义不可改变的需求边界和技术选择，设计视图负责将其综合为功能与技术方案，不引入未确认决策或与基线冲突。 - 以最少文字完整表达所有影响实现或验收的已确认结论；合并重复信息，不省略理解方案所需的背景、需求边界、技术选择、关键结构与流程、预估改动面和验收证据；不展开 plan 级任务拆分。 ### 自我审查 1. **覆盖**：所有已确认需求和技术结论都有权威定义，并在功能设计、技术设计和验收中得到完整落实。 2. **分层**：决策基线定义边界与选择，功能设计说明功能如何工作，技术设计说明系统如何实现，验收验证最终结果；各层没有矛盾或重复定义。 3. **交接**：功能与技术设计足以让 implement 理解入口、职责、状态、流转、失败收敛和兼容边界，并据此细化文件和任务，无需重新决定核心实现方案。 4. **闭合**：验收均有可观察结果和验证证据，文档中不存在占位符、未决项或可产生两种理解的表述。 发现问题就地修复，通过后再交给用户审阅。