| name | claude-code-feature-validation |
| description | Use this skill automatically whenever validating a Claude Code repository change: a new feature, modified feature, bug fix, refactor, CLI command, tool, Agent/Workflow behavior, task lifecycle, React Ink/TUI interaction, packaging, or official/local compatibility. Runtime changes, including internal or not directly user-visible changes, require both related bun tests and current-binary scripted tmux coverage of affected entry points, adjacent consumers, and side effects. Also trigger for Chinese requests mentioning feature 验收、改动验证、回归、CLI/TUI 验收、构建验证或官方对照. Delegate strict binary-side Agent/Workflow/slash-command/task/TUI evidence to claude-agent-workflow-validation; parent-assistant tools never count as binary evidence. |
Claude Code Feature Validation
为 Claude Code 新增或修改 feature 后，根据真实改动和风险选择最小但充分的验证路径，并输出可审计结论。不要把“命令退出 0”“测试通过”或“runtime done”单独等同于 feature 已通过验收。
核心原则
- 先理解改动，再选择验证。 阅读相关 diff、实现、调用链、测试和项目脚本，不对未读代码设计具体断言。
- 从 feature 契约和调用链反推 assertions。 同时验证内部契约、真实 runtime 入口、相邻消费者、用户可见行为和副作用，而不只是实现细节。
- 验证层级与风险匹配。 默认从最小范围开始；只有当前层不能证明行为时才升级。
- 测试和运行时证据互补。 自动化测试证明可重复逻辑；真实 CLI/TUI 验收证明进程内集成和用户可见行为。
- 所有 runtime feature 必须双重通过。 无论改动是否直接用户可见，只要进入
built-claude 并影响功能或共享 runtime 路径，就必须同时通过相关 bun test 与本轮 binary 的 scripted tmux 交互验收。内部改动要通过其真实调用入口触发，并覆盖直接受影响的相邻组件和副作用。任一失败、仍在运行或证据不足时，整体 feature 必须标记为 failed、running 或 not covered；build、make release-check、L4 或 parent-side 工具均不能替代交互证据。
- 结论必须绑定证据。 缺少必要证据时标记
not covered，仍运行标记 running，不得用推测补齐。
- 不制造额外副作用。 不 commit、push、创建 PR、发布、修改共享配置或删除用户状态，除非用户明确授权。
- 尊重当前工作区。 不覆盖或清理既有未提交改动。验证前后检查 Git 可见状态，将构建产物与被测运行副作用分开。
第一步：建立变更契约
开始验证前，写出精简 validation scope：
- changed behavior：新增、修改或修复了什么；
- affected surfaces：纯函数、状态、组件、命令、tool schema、CLI 入口、TUI、Agent/Workflow、构建或发布产物；
- user-visible contract：用户输入、状态迁移、输出、错误行为和副作用；
- regressions at risk：最可能被破坏的相邻行为；
- interaction impact：改动进入 binary 后的真实调用入口、直接消费者、相邻组件和可能副作用；
- exclusions：本轮明确不验证的内容及原因。进入
built-claude 的受影响 runtime 流程不能仅因“用户不可见”而排除。
从 git diff、相关文件和测试中确认这些事实，不仅依赖用户描述或 commit message。
第二步：声明 assertions
每条 assertion 至少记录：
assertion_idsubjectpredicaterequired_evidenceobserved_evidence_pathsruntime_state（不适用时写 n/a）validation_verdictreason_if_not_passed
Verdict 仅使用：
passed：必要证据完整且与 assertion 关联；failed：观察结果明确违反 assertion；running：验证仍运行，尚无终态；stopped：验证被明确停止；not covered：未执行、无法安全触发或证据不足。
Binary runtime state 使用 running | done | failed | stopped。done 不自动等于 validation passed。
第三步：选择验证阶梯
按改动 surface 选择必要层级，不机械执行全部层级。详细路由见 references/validation-routing.md。
L0 — 静态审查
始终执行：
- 查看相关 diff 和调用链；
- 检查引用、schema、注册入口、导入导出和删除残留；
- 检查调试日志、无关改动、敏感信息和明显安全问题；
- 从
package.json、Makefile 或现有测试模式确认验证命令，不猜测脚本。
L0 只能证明静态事实，不能证明运行时行为。
L1 — 聚焦自动化测试
实现逻辑、状态、组件或 bug fix 变化时执行：
- 优先运行最小相关测试文件或 pattern；
- bug fix 优先添加或更新可复现问题的最小失败测试；
- 新 feature 覆盖主路径、关键状态转换和任务要求中的边界；
- 不删除、跳过、弱化断言或吞异常来使测试变绿。
报告精确命令、exit code、通过/失败数量和关键失败信息。测试通过只覆盖其断言范围。
普通测试文件按实际相关路径直接聚焦运行：
bun test path/to/foo.test.ts path/to/Foo.test.tsx
先从 diff、用户指定路径和相邻实现确定测试文件；不要仅按扩展名扩大到全量 suite。出现 .test.tsx 只说明它是测试文件，不代表仅凭文件类型触发 L5；但只要改动进入 built-claude 并影响功能或共享 runtime 路径，无论是否直接用户可见，都必须同时执行 L5，不能因 L1 已通过而省略交互验收。
L2 — 类型、lint 与仓库检查
涉及 TypeScript 类型、跨模块接口、schema、registry、公共入口或较大范围代码时，运行项目已有相关检查。优先小范围；需要仓库级保证时再运行 make release-check 或其现有组成命令。
本项目只使用 bun、bunx 和 make，不使用 npm。
L3 — 构建与制品检查
涉及 CLI 入口、运行时行为、打包、类型定义、命令/tool 注册或发布制品时必须构建：
- 读取根目录
Makefile，确认当前 VERSION、命令和产物路径；
- 保存 build 前
git status --short；
- 本轮运行
make build；
- 保存 build 后状态，并记录
built-claude path、version、mtime、SHA-256；
- 构建失败时停止依赖新制品的后续验收，不得回退旧 binary 并声称通过。
仅文档、纯测试或不进入 binary 的局部改动通常不需要 L3，除非用户要求。
L4 — 非交互运行时验证
适用于 --print、stdout/stderr、exit code、debug flags、settings/env 或无需持续 TTY 的单进程行为。使用最小、确定、无副作用输入，保存命令、输出、exit code 和相关 debug log。
L4 是非交互断言的补充证据，不能替代 runtime 改动必须执行的 L5。行为只存在于交互式 CLI 进程内时也不能用 L4 替代 L5。快速单进程诊断使用 claude-runtime-debug；网络问题使用 claude-network-debug。
L5 — Scripted tmux 真实交互验收
进入 built-claude 并影响功能或共享 runtime 路径的改动必须执行 L5，并与相关 L1 bun test 共同构成通过门槛。先从 diff 和调用链列出真实入口、直接消费者、相邻组件和可能副作用，再逐项执行相关交互流程；内部实现不得以“用户不可见”为由跳过。以下类型一旦受本轮改动影响，必须覆盖：
- slash command stdin dispatch；
- Agent 启动、路由或生命周期：直接 Agent、Workflow/WorkflowTool 内 Agent、nested Agent、foreground/background continuation、task/notification；共享启动或执行路径发生变化时，这些关联流程必须逐项尝试，不能只验直接 Agent；
/deep-research、/code-review；- task lifecycle、foreground/background continuation、notification、scheduling；
- React Ink/TUI、按键、resize、signal、terminal preview；
- 必须在真实 CLI 中确认的交互状态。
此层必须通过 Skill 工具调用并遵循 claude-agent-workflow-validation，不能只在报告中提到它或自行用简化交互替代。它要求 tmux 中运行本轮新构建的 built-claude，通过脚本完成 readiness、literal stdin、分阶段 pane capture、debug marker 和终态检查。每个流程还要检查重复启动/通知、遗留 task/process、错误状态、配置或工作区污染等与改动相关的副作用。
调用专项 skill 前先完成 L0/L1，并在需要当前 binary 时完成 L3。调用后由专项 skill 驱动 tmux；不要在 parent-side 启动 Agent 来模拟被测 Agent。当前 assistant 会话的 Agent、Workflow、Skill、Task/Run 查询均不能作为 binary-side 证据；无法在 binary 中触发时必须报告 not covered。
L6 — Official/local parity
仅当需求涉及官方兼容性、行为对照或回归基准时执行。遵循 claude-agent-workflow-validation 的 parity 规则，为 official-claude 与 built-claude 使用独立 session/evidence/config roots，并保持 prompt、terminal dimensions、settings、auth、model env 和 flags 等价。官方成功不能替代本地通过。
改动类型路由
| 改动类型 | 最低建议层级 | 必须关注 |
|---|
| 文档/说明 | L0 | 内容与实现一致、链接和命令准确 |
| 纯函数/内部逻辑 | L0 + L1；进入 binary runtime 时加 L3 + L5 | 主路径、边界、真实调用入口、相邻消费者、副作用 |
| bug fix | L0 + L1 + 对应 runtime 层级 | 最小失败测试复现根因；进入 binary 时必须尝试相关交互流程 |
| React Ink 组件/状态 | L0 + L1 + L3 + L5 | render/state、真实交互、相邻状态与终端副作用 |
| command/tool/schema/注册 | L0 + L1 + L2 + L3；进入 runtime 时加 L5 | 注册可达、schema、构建制品、真实调用流程 |
--print/非交互 CLI | L0 + L1 + L3 + L4 + L5 | 非交互输出证据，以及相关真实 CLI 流程和副作用 |
| slash command/TUI | L0 + L1 + L3 + L5 | stdin、pane、prompt 恢复、终端状态 |
| Agent/Workflow/task 调度 | L0 + L1 + L3 + L5 | binary-side ID、进度、通知、debug marker |
| packaging/release path | L0 + L2 + L3 | 制品路径、版本、release checks |
| official parity | 对应层级 + L6 | 两侧环境等价、证据隔离 |
矩阵给出最低建议，不是上限。改动跨多个 surface 时取并集。
证据充分性
| Assertion | 必要证据 | 证据不足 |
|---|
| 源码路径已实现 | diff + 相关源码/注册引用 | not covered |
| 自动化行为正确 | exact test command + exit code + test result | failed / not covered |
| build 产物来自当前源码 | 本轮 build log + binary metadata + Git baselines | not covered |
| CLI 入口已接收 | exact input + submitted pane/output + 无解析错误 | failed / not covered |
| Agent/Workflow 已启动 | running pane + 稳定 binary-side ID | not covered |
| routing/handoff/ownership 正确 | 同次运行 debug marker + 关联 ID | not covered |
| 相关交互流程终态正常 | terminal pane/output + prompt/exit + process/task state | running / failed / stopped |
| 无非预期副作用 | 重复启动/通知、遗留 task/process、配置及 CLI 前后 Git 状态检查 | not covered |
普通运行无法稳定触发的故障路径，明确写为“自动化测试覆盖”“受控 fault injection”或 not covered，不能假称真实交互已覆盖。
失败处理
- 先读取失败输出并定位阶段：test、typecheck、build、readiness、dispatch、runtime 或 assertion evidence。
- 不盲目重复相同命令。
- 允许重试时记录原因；L5 必须使用新 session、evidence 和 config roots，保留旧证据。
- 测试失败不污染无关 assertion；但相关 L1
bun test 或必要 L5 交互验收任一失败时，整体 feature 不得标记为 passed。
- 环境阻塞时标记
not covered，说明阻塞和用户可执行的最小后续命令。
Skill 边界
| Skill | 负责 |
|---|
claude-code-feature-validation | 通用变更契约、验证路由、自动化检查、构建和最终证据汇总 |
claude-agent-workflow-validation | 最新 binary、scripted tmux、slash command、Agent/Workflow、task/TUI lifecycle、official parity |
claude-runtime-debug | --print、stdout/stderr/exit、debug flags/log、settings/env 的快速诊断 |
claude-network-debug | proxy/OAuth/network、SSE/WebSocket、CONNECT、MITM/CCH wire summary |
claude-source-binary-analysis | 静态源码/二进制分析、Bun section、反混淆、symbol/section、离线 checksum |
本 skill 负责选择和汇总路径；专项 skill 输出只能证明其实际覆盖的 assertion。
报告格式
## 范围与变更契约
- Changed behavior:
- Affected surfaces:
- Interaction impact:
- Validation ladder:
- Exclusions:
## Assertions
| ID | Subject / predicate | Required evidence | Observed evidence | Runtime | Verdict / reason |
|---|---|---|---|---|---|
## 执行结果
| Layer | Command / binary-side entry | Result | Evidence |
|---|---|---|---|
## 受影响交互流程与副作用
| Flow / consumer | Trigger | Runtime verdict | Side-effect checks | Evidence |
|---|---|---|---|---|
## 发现
1. ...
## 未覆盖与限制
- ...
## Git 状态对照
- validation/build 前：
- CLI 前（如适用）：
- validation 后：
只声称证据实际证明的内容。列出精确命令、关键 exit code、测试结果、binary metadata、tmux target 和绝对 evidence path；避免粘贴敏感配置或凭证。
