claude-code-feature-validation v0.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/305c8203eacc6490.

---
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.
version: 0.1.0
---

# Claude Code Feature Validation

为 Claude Code 新增或修改 feature 后，根据真实改动和风险选择最小但充分的验证路径，并输出可审计结论。不要把“命令退出 0”“测试通过”或“runtime done”单独等同于 feature 已通过验收。

## 核心原则

1. **先理解改动，再选择验证。** 阅读相关 diff、实现、调用链、测试和项目脚本，不对未读代码设计具体断言。
2. **从 feature 契约和调用链反推 assertions。** 同时验证内部契约、真实 runtime 入口、相邻消费者、用户可见行为和副作用，而不只是实现细节。
3. **验证层级与风险匹配。** 默认从最小范围开始；只有当前层不能证明行为时才升级。
4. **测试和运行时证据互补。** 自动化测试证明可重复逻辑；真实 CLI/TUI 验收证明进程内集成和用户可见行为。
5. **所有 runtime feature 必须双重通过。** 无论改动是否直接用户可见，只要进入 `built-claude` 并影响功能或共享 runtime 路径，就必须同时通过相关 `bun test` 与本轮 binary 的 scripted tmux 交互验收。内部改动要通过其真实调用入口触发，并覆盖直接受影响的相邻组件和副作用。任一失败、仍在运行或证据不足时，整体 feature 必须标记为 `failed`、`running` 或 `not covered`；build、`make release-check`、L4 或 parent-side 工具均不能替代交互证据。
6. **结论必须绑定证据。** 缺少必要证据时标记 `not covered`，仍运行标记 `running`，不得用推测补齐。
7. **不制造额外副作用。** 不 commit、push、创建 PR、发布、修改共享配置或删除用户状态，除非用户明确授权。
8. **尊重当前工作区。** 不覆盖或清理既有未提交改动。验证前后检查 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_id`
- `subject`
- `predicate`
- `required_evidence`
- `observed_evidence_paths`
- `runtime_state`（不适用时写 `n/a`）
- `validation_verdict`
- `reason_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`](references/validation-routing.md)。

### L0 — 静态审查

始终执行：

- 查看相关 diff 和调用链；
- 检查引用、schema、注册入口、导入导出和删除残留；
- 检查调试日志、无关改动、敏感信息和明显安全问题；
- 从 `package.json`、`Makefile` 或现有测试模式确认验证命令，不猜测脚本。

L0 只能证明静态事实，不能证明运行时行为。

### L1 — 聚焦自动化测试

实现逻辑、状态、组件或 bug fix 变化时执行：

- 优先运行最小相关测试文件或 pattern；
- bug fix 优先添加或更新可复现问题的最小失败测试；
- 新 feature 覆盖主路径、关键状态转换和任务要求中的边界；
- 不删除、跳过、弱化断言或吞异常来使测试变绿。

报告精确命令、exit code、通过/失败数量和关键失败信息。测试通过只覆盖其断言范围。

普通测试文件按实际相关路径直接聚焦运行：

```bash
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 注册或发布制品时必须构建：

1. 读取根目录 `Makefile`，确认当前 `VERSION`、命令和产物路径；
2. 保存 build 前 `git status --short`；
3. 本轮运行 `make build`；
4. 保存 build 后状态，并记录 `built-claude` path、version、mtime、SHA-256；
5. 构建失败时停止依赖新制品的后续验收，不得回退旧 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。

## 报告格式

```markdown
## 范围与变更契约
- 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；避免粘贴敏感配置或凭证。