用途
Scope(/scope)是一个并行变更范围分析器。它的目标是在真正动手修改代码之前,先对一个需求、缺陷描述或功能请求做范围评估:哪些文件需要改、哪些地方可能被破坏、推荐用什么方式实现。
它的核心卖点是速度:不采用串行分析(约 5 分钟),而是一次性并发启动所有分析代理,两轮并行执行后汇总,目标总耗时约 90 秒。
输入
用户提供一个需求、缺陷描述或功能请求,例如:
- “我想重构 hook 系统”
- “给 check 技能添加自动修复功能”
- “spec.json 校验太慢了”
如果需求过于模糊、无法用于检索(例如“改进一下东西”),只追问一个澄清问题;否则立即开始。
主要能力与执行流程
阶段一:状态发现
分两步:先并行代理,再调用 /check 技能。
步骤 1A:并行代理(3 个并发)
在单条消息中同时启动三个代理,使其并发运行:
- 代理 1:code-explorer,查找与需求直接相关的所有代码,聚焦入口点、核心逻辑、数据流和测试文件。
- 代理 2:docs-researcher,查找与变更相关的内部文档、ADR 和约定,关注架构决策、约定、约束、相关历史变更。
- 代理 3:code-explorer(git 状态),了解受影响区域的当前 git 状态和近期变更,包括运行
git log --oneline -10、git diff --name-only,并识别可能产生交互的进行中工作。
实现方式:使用三个并行的 Agent 工具调用,代理 1 和 3 的 subagent_type 设为 code-explorer,代理 2 设为 docs-researcher。
步骤 1B:/check 技能
三个并行代理完成后,通过 Skill 工具调用 /check 技能,对 .hoyeon/rules/ 执行完整的基于规则的校验,以发现受影响区域中可能存在的级联变更需求或规则违规。
调用:Skill("check")
等待 /check 完成,其 PASS/WARN 结果作为 check_results 进入阶段二。
跳过条件:如果 .hoyeon/rules/ 不存在,则跳过步骤 1B,直接进入阶段二,并在报告中注明“no rules configured”。
阶段二:深度分析(并行)
阶段一(步骤 1A + 1B)完成后,在单条消息中再启动三个代理,并把阶段一的发现作为上下文注入每个提示词:
- 代理 4:gap-analyzer,分析缺口,聚焦遗漏的需求、边界情况、绝对不能改动的内容。
- 代理 5:tradeoff-analyzer,分析权衡,聚焦每个文件/模块的风险、更简单的替代方案、过度工程警告;跳过 decision_point YAML,只给出风险表和替代方案。
- 代理 6:codex-strategist,综合出战略视角,聚焦盲点、横切关注点、架构契合度。
关于阶段二的顺序:代理 4、5、6 可以一起启动,因为它们都直接接收阶段一的结果。代理 6(codex-strategist)基于阶段一结果工作,不需要等待代理 4 的输出;它提供独立的战略综合,而不是对缺口分析的复核。
阶段三:汇总
所有代理完成后,由主流程自行把结果汇总成一份报告,不需要额外的子代理。
输出格式
报告结构如下:
- 变更映射(Change Map):表格列出文件/模块、变更类型(MODIFY/CREATE 等)、风险等级、原因。
- 影响半径(Impact Radius):分为直接(必须改的文件)、间接(可能需要调整的文件)、测试(需更新/创建的测试文件)、文档(需更新的文档)。
- 风险汇总(Risk Summary):按 HIGH/MED/LOW 统计数量并列出关键项。
- 缺口与警告(Gaps & Warnings):来自 gap-analyzer 的缺口或警告、来自 tradeoff-analyzer 的过度工程警告、来自 codex-strategist 的盲点。
- 推荐方案(Recommended Approach):1-3 句话给出最简单的实现路径,并附建议执行顺序(第 1、2、3 步)。
- 不应做的事项(Must NOT Do):来自 gap-analyzer 和 tradeoff-analyzer 的禁止项。
输出规则:
- 每个文件路径必须是绝对路径或仓库相对路径,不能是模糊引用。
- 风险等级必须有依据,不能随意标注。
- 报告控制在 80 行以内,简洁是重点。
- 如果任何代理返回 DEGRADED/SKIPPED,需注明但不阻塞报告。
适用场景
- 在重构某个系统(如 hook 系统)前评估影响范围。
- 为某个技能添加新功能(如给 check 技能加自动修复)前做风险排查。
- 定位性能问题(如 spec.json 校验过慢)时梳理相关代码与文档。
- 任何希望在动手前快速获得“改哪里、风险多大、怎么做最简单”结论的变更评估。
限制
- 不生成 spec.json——它比 /specify 更轻量。
- 不开始实施变更,只做分析。
- 除一个澄清问题外,不对用户做更多访谈。
- 能在并行时运行的代理,不允许串行执行。
- 目标墙钟时间约 90 秒(两轮并行)。
- 依赖 .hoyeon/rules/ 目录进行规则校验;该目录不存在时跳过校验步骤。
- 具体支持的平台、收费方式、价格等信息暂未提供。