用途
Feature Boundary Planner 是 ZCode 仓库中的技能,应在实现之前、从仓库根目录使用。当请求需要功能影响发现、产品边界澄清、覆盖规划或 E2E 交接时使用它。
该技能把影响发现和边界规划视为两项相互关联的工作:
- 确定某能力出现在哪些位置,以及一次改动会影响什么。
- 决定受影响状态应如何表现,以及哪些组合需要覆盖。
它强调不要一开始就构建庞大的笛卡尔积,而应先建立紧凑的语义影响图,对照实时代码进行验证,然后只提出会改变结果的问题。
主要能力与运行模式
技能提供三种运行模式:
- impact-only:产出 Impact Brief,不修改产品代码或现有产品规格。用于扫描、解释、诊断或报告影响的请求。
- planning:产出 Impact Brief,澄清产品语义,并在写代码前更新规格或规划文档。用于变更或构建类请求(除非用户明确限制范围)。
- implementation-handoff:完成规划,并把已接受的用例交给实施或 e2e-case-lifecycle。
核心工作流包括:
- 变更层分类:在扩展影响图之前,将拟议变更归类为 presentation(展示)、option-source(选项来源)、draft-default(草稿默认值)、validation(校验)、commit-effect(提交效果)、persistence(持久化)、recovery(恢复)中的一类或多类。
- 发现功能与 UI 影响:通过功能图匹配能力别名,加载 UI 界面、共享实现、状态所有者、不变式、文档与一跳语义邻居;对已索引代码优先使用 codegraph 而非文本搜索;默认以深度 2 运行影响分析,仅在关键所有者或汇点未解决时扩展到深度 3。
- 构建 UI Surface Matrix:为每个 UI 入口记录用户场景、入口组件、共享组件/选项构建器/hook/store/service、显示值与本地草稿所有者、默认与继承及回退来源、校验与门控、提交命令/服务、权威运行时所有者或持久化汇点、桌面/Web/移动与本地/远程差异、必须保持隔离的行为。
- 澄清产品边界:仅把未定义或冲突的关系转化为问题,每轮提出 3–7 个具体问题,附带小候选答案集并说明每个答案包含、排除或留待定义的内容;覆盖触发条件、允许状态、目标、禁止副作用、隔离边界与证明证据。
- 整理功能图:把已确认的扫描结果转化为可复用检索数据;在 impact-only 模式下只提出图增量建议而不编辑;在 planning 和 implementation-handoff 模式下于语义确认后更新 references/zcode-feature-graph.yaml。
- 枚举与剪枝:仅在 planning 或 implementation-handoff 模式下运行,选择 1–4 个主域与高风险交叉产品,只提取会改变行为的维度,按 state -> candidate -> guard -> effect -> case 枚举,优先成对与高风险组合而非全局展开,并将每个候选用例分类为 accepted、undefined、pruned、ignored 或 bug-candidate。
- 先写文档后写代码:在规划模式下先更新或创建特性规格、目录、矩阵、决策工作表或待办;对话相关 E2E 工作需先更新对话用例目录与覆盖矩阵,获得剪枝决策后再写测试。
使用方式
每次影响扫描需阅读 docs/feature-impact-discovery.md、references/zcode-feature-graph.yaml、references/impact-brief-template.md 以及 references/zcode-domain-cross-products.md 中的相关行。planning 或 implementation-handoff 模式还需阅读 packages/formal-proof/README.md、references/case-planning-template.md,以及当前特性规格、相近用例目录、覆盖矩阵、决策工作表和测试工作流。涉及会话/会话行为时,还需阅读对话协议声明、产品状态空间、会话用例目录、E2E 覆盖矩阵与开发工作流等文档。
输出时始终使用 references/impact-brief-template.md,包含功能摘要与变更层分类、UI Surface Matrix、共享实现与差异行为、排序后的上下游关系、状态所有者/校验点/提交汇点/持久化、必须保留的不变式、codegraph 种子与直接调用者及影响深度和测试证据、图漂移候选、已确认或拟议的图增量、会改变范围但尚未解决的问题。规划模式还需追加澄清日志、维度、候选组合、剪枝决策、已接受用例、覆盖行与 E2E 交接说明,并保持用例 ID 稳定。
适用场景
适合在 ZCode 仓库中评估一次功能或行为改动的爆炸半径、明确产品边界、规划覆盖面,或将已确认的 E2E 用例交接给实施流程。
限制
- 静态可达性不等于产品依赖,必须有明确的语义边。
- 共享组件、hook、标签或字段不能证明共享状态或提交效果。
- 语义扩展保持为一跳,codegraph 影响默认深度 2,不得从深度 5 开始。
- 不得把 impact-only 请求变成代码或产品规格修改。
- 不得在首轮影响与澄清之前枚举大型矩阵。
- 不得猜测未定义的产品行为,应记录决策并询问用户。
- 在文档中存在已接受的语义之前不得编写 E2E 代码;缺少 setup、action、assertion 的路径不得声称已覆盖。
- 实现与规格冲突应标记为 bug-candidate,未经确认不得改写契约以匹配当前代码。
- 桌面端的 desktop-continuous 语义与移动端的 web-remote-replayable 语义须分开处理;工作区隔离使用 workspaceIdentity?.trim() || workspacePath,执行与展示使用 workspacePath。