ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

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

TinyUSB 仓库 `.claude/` 指令面审计设计:让 AI Agent 指令与源码逐条对账 嵌入式驱动开发通信物联网【免费下载链接】tinyusbAn open source cross-platform USB stack for embedded system项目地址https://gitcode.com/gh_mirrors/ti/tinyusb点击查看免费下载导读本文系统解析 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。二、审计范围界定什么在范围内什么明确排除范围内容规模In.claude/agents/*.md7 个、.claude/workflows/*.jscheck.sh7 个、.claude/skills/*/SKILL.md16 个及 8 个辅助脚本、仓库根目录CLAUDE.md约 4,700 行其中散文 2,874 行其余为辅助脚本与etm-trace/boards.mdOutdocs/superpowers/**历史记录——修正它们等于改写历史而非修复未来会话实际执行的指令、.claude/settings*.json与 hooks、memory index、任何对脚本本身的行为变更—关键判断docs/superpowers/**被明确排除因为修正历史记录与修复未来将执行的指令是两回事审计只对后者负责。三、声明分类学只有可证伪的声明才配得上判定审计只对**可证伪falsifiable**的声明下结论纯指导性语句如bias toward caution只检查是否与下列类别矛盾不单独判定。类别 Class判定手段Settled by示例Path 路径ls/find并显式指明基准目录src/tusb_config.h——示例相对、读起来像仓库相对Interface 接口在指定源码中做 argparse/grep-b是actionappendhil_test.pyBehavior 行为阅读实现代码引用file:line许可permits是进程内信号量hil_lock.pyNumber 数值常量的定义处FLASH_PARALLEL4hil_lock.pyRig state 硬件状态只读ssh ci.lan探测总线拓扑、探针 uid、sudoers 条目、已装工具Cross-doc 跨文档对同一规则的两个表述做 diffhil-operator.md第 18 行与第 37 行四、四类判定语义CONFIRMED / REFUTED / EARNED / UNVERIFIABLE判定含义处置CONFIRMED当前源码确实如此引用file:line原文不动REFUTED当前源码证明并非如此引用出处并修正文档EARNED范围内无源码可判定且属于用真金白银换来的硬件经验文档原样保留见下文规则UNVERIFIABLE范围内无源码可判定也不是 earned 知识占位符、生成文件、仓库之外的声明如实标注五、核心原则硬经验证据Hard-earned evidence就是事实源这是整份设计最具方法论价值的一条一条没有代码支撑的声明只要它是 earned rig knowledge实测到的硬件怪癖、花过设备停机时间才换来的故障模式、其理由只存在于促成它的那次事故中的 workaround就不是删除候选。代码对代码有权威经验对硬件有权威——而硬件不会自己写文档。由此得出三条执行后果只有被当前源码主动反驳actively refutes的声明才被修正。我找不到支撑永远不构成删除理由已经过时的硬件状态声明bus map、probe uid要做重新推导并更新或改写成推导配方如总线每次重启都会重新编号——用 X 重新推导绝不直接丢弃当 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 个并行工作包#集群行数1.claude/agents/*.md7 个文件3132.claude/workflows/*.jscheck.sh6593hil、hil-pool-check2234usb-kernel-recover、usb-kernel-debug 2 个脚本253 脚本5target-debug、esp-target-debug4966usbtest、usbmon、usb-snifferusbcap.sh382 脚本7etm-traceboards.md 2 个脚本203 文件8build-doc、code-size、pvs、make-release、read-doc、pre-pr 2 个脚本345 脚本9CLAUDE.md139按行数 × 主题独立性切分确保每个 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 语义。CLIhold/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_SLOTS12 个锁槽与PERMIT_TIMEOUT900 秒单次许可等待上限。这些数值正是审计中 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-corroboration0 处引证错误行为类扫描刻意从不发出 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 examples 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赞分享嵌入式驱动开发通信物联网【免费下载链接】tinyusbAn open source cross-platform USB stack for embedded system项目地址https://gitcode.com/gh_mirrors/ti/tinyusb点击查看免费下载相关推荐TinyUSB .claude/ 指令面审计基于可验证声明台账与双重防幻觉校验器的 Agent 文档重构实践TinyUSB .claude/ 指令面审计基于可验证声明台账与双重防幻觉校验器的 Agent 文档重构实践 本文以 TinyUSB 仓库中 docs/sup嵌入式驱动开发通信物联网Ponytail 的 /ponytail-audit面向整个仓库的过度工程审计命令设计与实现Ponytail 的 /ponytail audit面向整个仓库的过度工程审计命令设计与实现 /ponytail audit 是 Ponytail 在 Ope人工智能AI 技能AI 插件提示工程AI 评测Ultralytics 仓库工程全景指南架构设计、开发命令与 AI Agent 协作规范Ultralytics 仓库工程全景指南架构设计、开发命令与 AI Agent 协作规范 本文以 AGENTS.md https://link.gitcode人工智能深度学习计算机视觉预训练上一篇使用 LlamaIndex 的 AlibabaCloudMySQLVectorStore 构建 MySQL 向量检索应用下一篇OpenResearch如何导入浏览器CookiemacOS Keychain AES解密解析创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表