TinyUSB 仓库 `.claude/` 指令面审计设计：让 AI Agent 指令与源码逐条对账

• 嵌入式
• 驱动开发
• 通信
• 物联网

导读

本文系统解析 TinyUSB 仓库中 docs/superpowers/specs/2026-08-18-claude-doc-audit-design.md 所定义的一次"指令面（instruction surface）"审计：即对.claude/下供 AI Agent 执行的技能说明（SKILL.md）、Agent 定义、工作流脚本与根目录CLAUDE.md中每一句可证伪声明，对照仓库源码逐条给出带引证的判定并修正漂移。读完本文，你将掌握一套可复用的"声明分类 → 机械扫描 → 代码精读 → 交叉一致性 → 编辑 → 门禁"六段式审计方法论，并理解为什么"代码是代码的权威、经验是硬件的权威"这一原则决定了哪些内容可删、哪些必须保留。

一、审计的起因：两个互相矛盾的指令与 8 处漂移路径

1.1hil-operator.md的自锁矛盾

审计的导火索是一份hil-operator.md在同一修订里写下了两条相互对立的规则：一条禁止预先持有板卡锁（因为hil_test.py会自锁），另一条又规定锁正是防止并发操作者抢占同一块硬件的机制。一个遵循第二条的操作者一旦抢先持锁，自己的运行反而会立即失败——"遵循文档"直接导致"运行失败"。虽然该分支合并前两条语句都已被修正，没有遗留到历史记录中，但真正的教训是：没有任何机制检查这些指令文件与其所描述的代码是否一致。

1.2 36 个被引用路径中的 8 个不可解析

对.claude/全量引用的 36 个仓库路径进行扫描后，发现 8 个无法解析，分两类：

• 5 个属于合理情形（legitimate），不应算作漂移：
  • 占位符：docs/changelog/X.Y.Z.md、src/portable/x/dcd_x.c、test_*.py通配符；
  • 生成文件：examples/cmake-build-pvs/compile_commands.json；
  • 每台主机 gitignore 的本地配置：test/hil/local.json（其缺失已被对应技能显式处理）。
• 3 个属于真实漂移（drift），全部位于 .claude/skills/usbtest/SKILL.md：
  • 第 24、50 行引用的src/usb_descriptors.h与src/tusb_config.h实际是示例相对路径（位于各 example 的src/下），却被写成了仓库根路径；
  • 第 101 行引用的tools/usb/testusb.c是Linux 内核源码路径，被当作仓库文件呈现。

设计文档的结论是：交叉引用（cross-reference）状况良好——每个 workflow 中的agentType都能解析到.claude/agents/下的某个 agent，每个被引用的.claude/skills/<name>都存在，工作流脚本只调用真实存在的 harness 函数。漂移集中在"关于行为的散文式声明"（prose claims about behavior）——正是这一类声明制造了hil-validate在错误的层级上并行化的失败：底层hil_test.py早已在每控制器许可（per-controller permit）下把各板调度到不同主机控制器上（见 test/hil/helper/hil_lock.py）。

二、审计范围界定：什么在范围内，什么明确排除

关键判断：docs/superpowers/**被明确排除，因为"修正历史记录"与"修复未来将执行的指令"是两回事，审计只对后者负责。

三、声明分类学：只有可证伪的声明才配得上判定

审计只对**可证伪（falsifiable）**的声明下结论；纯指导性语句（如"bias toward caution"）只检查是否与下列类别矛盾，不单独判定。

四、四类判定语义：CONFIRMED / REFUTED / EARNED / UNVERIFIABLE

五、核心原则：硬经验证据（Hard-earned evidence）就是事实源

这是整份设计最具方法论价值的一条：

一条没有代码支撑的声明，只要它是 earned rig knowledge（实测到的硬件怪癖、花过设备停机时间才换来的故障模式、其理由只存在于促成它的那次事故中的 workaround），就不是删除候选。代码对代码有权威，经验对硬件有权威——而硬件不会自己写文档。

由此得出三条执行后果：

1. 只有被当前源码主动反驳（actively refutes）的声明才被修正。"我找不到支撑"永远不构成删除理由；
2. 已经过时的硬件状态声明（bus map、probe uid）要做"重新推导并更新"，或改写成"推导配方"（如"总线每次重启都会重新编号——用 X 重新推导"），绝不直接丢弃；
3. 当 earned 知识与当前代码冲突时，那是一个"待报告发现"（finding to report），而不是一次可执行的编辑：二者必有一个是 bug，而判定谁是 bug 超出本次审计范围。

六、五遍流水线：从扇出提取到门禁

Pass 1：提取（扇出，9 个 Agent，零判定）

每个集群一个 Agent，只把**逐条声明台账（ledger）**写入 scratchpad，返回计数与台账路径。每条声明记录file:line、逐字原文、类别、判定该声明所需的源码、以及"疑似 earned 证据"标志。Agent 不返回任何判定——这样就不会产生任何需要事后回退的"伪判定"。

Pass 2：验证（由主会话亲自完成）

每条声明由主会话本人对照源码核实：路径/接口/数值用脚本化检查，行为用代码精读，硬件状态用只读ssh ci.lan探测（ls、--help、which、lspci、lsusb、hil_lock.py status、sudo -l、uname -r——不持锁、不烧录、不uhubctl、不做恢复操作）。任何将被执行的处置都不采纳提取者的转述。

Pass 3：跨文档一致性（主会话本人）

构建规则清单（rule inventory）：板锁、超时、输出契约、重试策略、配置选择、强制手段等每条规则的所有陈述位置逐一列出并 diff。这一步没有任何单文件 Agent 能做——hil-operator的自锁矛盾正是只存在于这一步能发现的维度。

Pass 4：编辑

只删除三类内容：被源码反驳的、只是在重复其前置命令的、以及重复了别处已有规范归属（canonical home）的规则（保留一处并引用它）。保留：源码确认且影响行为的每条声明、每条 earned 观察、每条非显然规则背后的"为什么"。文档结构保持不变。

Pass 5：门禁

重跑路径与接口扫描；对每个 workflow 跑check.sh；对所有 8 个辅助脚本做bash -n与py_compile；跑通test/hil四个测试套件；最后pre-commit run --all-files。

七、提取集群划分：9 个并行工作包

按"行数 × 主题独立性"切分，确保每个 Agent 的阅读预算可控、可并行、产出可单独验证。

八、交付物与成功标准

交付物：按表面拆分提交（agents / workflows / skills / CLAUDE.md 各自一个 commit，分支claude/claude-doc-audit，保持评审可追踪）；一份 findings 报告，覆盖每条 REFUTED 声明及其引证、以及 Pass 2 中发现的所有 earned-knowledge-vs-code 分歧。特别地：当被反驳的声明其"代码"才是错误的一半时，不做静默代码修改——按仓库的 deferred-work 规则，改写为docs/superpowers/followup/下的交接文档。

成功标准：

• 范围内每条可证伪声明都带引证的判定；
• 树中不再存在被当前源码反驳的声明；
• 没有任何 earned 观察被删除；过时的硬件状态被重新推导或改写成推导配方；
• 没有一条规则在两个地方以两种含义存在；
• Pass 5 的门禁全部通过。

九、仓库源码佐证：审计对象背后的真实实现

为印证这份设计的现实基础，可以直接在仓库中对照审计所依据的两处关键事实：

1. 板锁与控制器许可确实是两种不同机制：test/hil/helper/hil_lock.py 的模块注释（第 3-9 行）写明：板锁是BOARD_LOCK_DIR下的内核 flock，在开发会话与 CI 的hil_test.py之间仲裁硬件访问；控制器许可（permit）是进程内信号量，用于按主机控制器预算烧录与 usbtest 批次的并发度，没有 CLI 语义。CLI（hold/release/status）只管理板锁。这正是审计文档中"permits are in-process semaphores"这一 Behavior 声明（引用hil_lock.py:7）的出处。

2. 并发预算常量：同一文件第 132-137 行定义了FLASH_PARALLEL（默认 4，经HIL_FLASH_PARALLEL环境变量可调）与USBTEST_PARALLEL（默认 2，经HIL_USBTEST_PARALLEL可调）、CONTROLLER_SLOTS（12 个锁槽）与PERMIT_TIMEOUT（900 秒单次许可等待上限）。这些数值正是审计中 Number 类声明的标准判定对象——"查找常量定义，字面量相等即 CONFIRMED"。

3. 漂移的原始文本：三处漂移（src/usb_descriptors.h、src/tusb_config.h、tools/usb/testusb.c）在 .claude/skills/usbtest/SKILL.md 第 24、50、101 行仍然可见——它们以"示例相对"或"内核路径"的身份出现，印证了审计文档对路径类漂移的定性（"example-relative but read as repo paths"）。

十、落地数据：审计执行的实测结果

配套的执行计划 docs/superpowers/plans/2026-08-18-claude-doc-audit.md 记录了这次审计的真实产出，可作为方法论有效性的实证：

• Task 1的反幻觉验证器完成，6 个自测全部通过（包括拒绝一条幻觉引文）；
• Task 2提取完成：1,387 条声明、0 条验证错误；
• Task 3机械扫描：647 个判定，验收测试通过；
• Task 6交叉一致性：全量 1,387 条声明最终逐条都带判定行（233 CONFIRMED / 340 EARNED / 39 REFUTED / 775 UNVERIFIABLE-with-corroboration），0 处引证错误；行为类扫描刻意从不发出 CONFIRMED——"在命名文件中找到该声明的 token"只证明词汇存在，不证明声明成立；
• Task 6 跨文档：token 索引发现 185 个 token 跨 2+ 文件陈述，规则清单见rules.md，发现并修复 4 处矛盾；
• Task 9 门禁：check.sh×6、bash -n/py_compile×8、4 个 HIL 套件、pre-commit --all-files全部通过；
• Task 10 复发防护被构建、实测并最终否决：路径 lint 在已审计树上标出 11 个路径、全部为误报（docs/_build、docs/examples/等生成目录，以及散文中的斜杠词如interrupt src/sink）；更致命的是它本要捕获的缺陷（Key files: src/tusb_config.h）与正确文本（the example's own src/usb_descriptors.h）词法上完全相同——差异只在上下文。任何低到能上线的阈值都会同时漏掉这个 bug，因此未提交，也不重建。

结语：可复用的工程教训

这份设计文档的价值不止于 TinyUSB 仓库本身。它示范了如何在"AI Agent 长期维护硬件在环测试集群"的场景下，为自然语言指令建立与代码同等的可验证性：提取时不带判定、验证只由主会话完成、机械检查先行以节省精读预算、跨文档一致性必须由全局视角承担、硬经验证据不可删除只可重推导、门禁与业务门禁同一套。对任何维护"Agent 指令 + 真实硬件 + 持续集成"三角关系的项目，这套审计骨架都值得照搬。

关联文件索引：

• 设计文档：docs/superpowers/specs/2026-08-18-claude-doc-audit-design.md
• 执行计划与实测数据：docs/superpowers/plans/2026-08-18-claude-doc-audit.md
• 板锁与许可实现：test/hil/helper/hil_lock.py
• 漂移文本出处：.claude/skills/usbtest/SKILL.md
• 调度核心：test/hil/hil_test.py
• 根级 Agent 指令：CLAUDE.md

• 嵌入式
• 驱动开发
• 通信
• 物联网