caveman investigate-first：Agent 技能体系中“先取证、后动手“的证据优先技能实现

caveman investigate-firstAgent 技能体系中先取证、后动手的证据优先技能实现【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman本篇技术文章以 skills/investigate-first/SKILL.md 为核心讲解 caveman 项目如何把一个调查先于修改的工程纪律实现为一条可在多个 Agent 宿主Claude Code、Codex、Gemini、opencode、aider、hermes上自动分发的 native 技能包括技能正文的五条调查规则、注册表 中对入口/停止条件与护栏的形式化定义、编译管线 的字节预算强制与多目标打包机制。读完后你能理解这类工作模式技能的完整生命周期——从单一 Markdown 事实源到各宿主激活钩子并掌握如何在自己的 Agent 工作流中复用同一套证据优先纪律。定位六条工作模式技能中的调查分支caveman 的 README 将investigate-first与lean-build、surgical-patch、safe-refactor、migration、verify-and-stop并列为一组工作模式技能work patternsWork patterns that write less code, so the agent bills fewer tokens. Your agent picks these up on its own when a task fits.项目内部 CLAUDE.md 对这条设计取向有明确说明这一组技能与 caveman 的输出压缩是同一个目标更少的输出 token作用于代码量而非措辞并且刻意不加品牌化deliberately un-branded使其在模型眼中读起来像一条通用的工程模式而不是某个插件的私有指令。从 skills/registry.json 可以看到investigate-first的定位是六条技能中唯一认领investigation任务类型的分支元数据字段取值含义delivery[native]不走 CLI 分发随 native pack 注入宿主activationclassified由任务分类而非用户显式调用触发task_types[investigation]仅在任务被归类为调查时激活entry_conditioncause is ambiguous入口条件成因不明stop_conditioncause or exact blocker is evidence-backed停止条件成因或确切阻塞点已被证据支撑guardrailsno_edit_before_credible_hypothesis、diagnosis_does_not_authorize_fix两条硬护栏下文详述prompt_byte_budget900注入提示词的正文字节上限evidence_statusstructural-test-only仅有结构性测试证据无行为级评测precedence100同任务类型下的优先级无冲突项conflicts为空frontmatter 中的description则给出了面向模型的路由描述Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.——即它瞄准的正是未知成因、间歇性故障、性能回退这类无法直接指认责任层的失败。技能正文逐条解读技能正文全文如下完整内容见 skills/investigate-first/SKILL.md# Investigate first Gather evidence before changing product code. - Separate observed symptom from inferred cause. - Trace inputs, state transitions, ownership boundaries, and failure output. - Rank hypotheses by evidence and cheap falsification value. - Do not edit until one credible mechanism explains evidence. - Stop exploration when evidence is sufficient to name cause or exact blocker. Report cause and proof. Make no fix unless task authorizes implementation.这段不到 900 字节的正文上限由注册表强制见下文编译管线一节可以拆解为一条总纲 五条过程规则 一条输出契约总纲取证先于改码Gather evidence before changing product code。整条技能的唯一目的是把编辑产品代码这个写操作置于证据收集这个读操作之后。症状与成因分离Separate observed symptom from inferred cause。要求 Agent 在记录时区分我看到了什么如接口偶发 500与我猜为什么如可能是连接池耗尽避免把推断当观测写入调查笔记。追踪四个维度Trace inputs, state transitions, ownership boundaries, and failure output输入数据流、状态迁移、所有权边界哪个模块/层拥有该不变量、失败输出错误信息、退出码、日志形态。这四者恰好覆盖了一个故障从产生到暴露的完整路径。假设排序的判据是证据强度 廉价可证伪价值Rank hypotheses by evidence and cheap falsification value。这条规则把科学方法中的可证伪性翻译成了工程优先级优先做那些便宜、且能一次性排除某个假设的检查而不是先做成本最高的验证。编辑门禁Do not edit until one credible mechanism explains evidence。只有当某个机制能解释全部已收集证据时才允许进入编辑阶段——注意是one credible mechanism而非one plausible guess这与护栏no_edit_before_credible_hypothesis一一对应。反过度调查条款Stop exploration when evidence is sufficient to name cause or exact blocker。技能不仅防止先改后查也防止查而不止一旦证据足以命名成因或确切阻塞点探索立即停止。这对应注册表中的stop_condition也是控制调查阶段 token 开销的关键。输出契约Report cause and proof. Make no fix unless task authorizes implementation.。交付物是成因 证据而不是补丁修复必须获得任务显式授权。这与第二条护栏diagnosis_does_not_authorize_fix完全对应——诊断行为本身不构成修改授权读/写权限在语义上被切开了。编译管线一份 SKILL.md 如何变成六端交付物caveman 的技能体系遵循单一事实源每条技能的正文只存在于skills/id/SKILL.mdskills/compile.mjs 负责校验并把正文编译进各交付面。对该管线的关键机制逐段说明入口与元数据校验。编译器以 registry.json 为唯一注册表skills/compile.mjs严格限制注册表顶层与每条技能条目的字段集合investigate-first携带的activation、task_types、guardrails等字段仅当delivery含native时才合法skills/compile.mjs。格式门禁。每个SKILL.md必须以 YAML frontmatter 开头、name必须与目录名一致、正文禁止出现TODO/FIXME等未完成标记skills/compile.mjs——这保证了技能正文是发布态而非草稿态。字节预算强制。对 native 技能frontmatter 之后的正文字节数不得超过prompt_byte_budgetskills/compile.mjs。investigate-first的预算是 900 字节这正是上文那段正文如此凝练的原因预算在构建期就封死了技能越长越好的冲动。同样机制下mandatory 的 Native Core 使用ceil(UTF8字节数/3)作为保守 token 估计并对照 560 token 预算校验skills/compile.mjs。skills-verbs 门禁。写入任何生成物之前编译器会扫描技能正文拒绝任何引用了当前 CLI 命令、MCP 工具或 SDK 表面中不存在的调用skills/compile.mjs。漂移即构建失败a drift fails the build closed防止技能向模型灌输一条宿主实际无法执行的指令。investigate-first正文中不含任何命令引用天然满足此门禁。多目标产物。一次编译至少产出四类交付物产物路径消费者CLI 嵌入 TypeScriptpackages/cli/src/agent-skills.generated.ts、packages/cli/src/native-pack.generated.tsCaveman CLInative pack JSONproxy/internal/nativepack/native-pack.generated.jsonGo 代理运行时proxy/internal/nativepack/pack.go配套测试 pack_test.go各宿主 packskills/generated/claude/pack.json 等六个目标各 Agent 宿主的注入器在 skills/generated/claude/pack.json 中可以核对最终注入形态instructions字段就是上文引用的完整正文summary、guardrails、entry_condition、stop_condition原样来自注册表schema为caveman.native-pack.v1、pack 版本2.2.0。宿主激活钩子。同一份 native pack 在不同宿主上使用不同的注入点映射表由 skills/compile.mjs 硬编码宿主Core 注入点任务技能注入点claudeSessionStartUserPromptSubmitcodexdeveloper_instructionsSessionStartUserPromptSubmithermespre_llm_callpre_llm_callgeminiBeforeAgentBeforeAgentopencodeexperimental.chat.system.transformchat.messageaiderread_only_conventionsnative_repository_map_authoritative也就是说investigate-first在 Claude Code 中随UserPromptSubmit钩子按任务分类注入而在 Gemini 中随BeforeAgent注入——技能文本不变宿主接线不同。此外该技能还提供了一条面向 OpenAI 兼容界面的调用元数据skills/investigate-first/agents/openai.yaml 中的default_prompt为Use $investigate-first to diagnose this failure before proposing edits.展示了显式引用技能名$investigate-first的用法。与 Native Core 及姊妹技能的协作关系native pack 中 mandatory 的 Core 指令源文件 skills/native-core.md全文见 pack.json已经包含一条调查性默认Trace behavior and invariants before editing并规定系统、用户与仓库指令优先于该默认。investigate-first可视为对 Core 这条默认在成因不明场景下的强化与操作化Core 给出方向技能给出条目化的执行清单和停止条件。从注册表的六条 native 技能看它们构成一条隐含的任务流水线各自认领互不重叠的任务类型investigate-firstinvestigation在成因不明时建立可信机制产出成因 证据不改代码surgical-patchbugfix拿到成因后修改最窄责任层其正文第一步恰是 Reproduce failure first when economical; otherwise capture strongest available evidence——与调查技能的输出形成衔接skills/surgical-patch/SKILL.mdverify-and-stopverification运行最小充分证明集后即停止区分 pass/fail/unavailable/blocked且Do not edit product code unless verification request includes fixesskills/verify-and-stop/SKILL.md。三者共同实现 README 所说的让 Agent 写更少的代码、从而消耗更少的 token调查阶段不产出无依据的补丁修复阶段不扩散到无关清理验证阶段不追加计划外工作。证据边界与适用前提使用或引用这套机制时需要注意仓库内已声明的两条边界证据等级是structural-test-only注册表中investigate-first的evidence_status表明当前仓库对它的验证是结构性的注册表一致性、预算、门禁、pack 编译见 proxy/internal/nativepack/pack_test.go 与 skills/compile.mjs 的构建期校验仓库内没有为这条技能提供行为级评测数据。因此不应将其写成已证明降低调查 token 消耗 X%之类的事实。适用前提该技能随 native pack 分发给上表六类宿主prompt_byte_budget900 字节与core_prompt_token_budget560 token是构建期常量若你自行扩写技能正文超预算会直接让 skills/compile.mjs 构建失败而非静默截断。小结investigate-first的价值不在于正文的长度而在于它把先取证、后动手拆解成了可判定、可注入、可构建期验证的形式正文给出五条过程规则与一条输出契约registry.json 把入口条件、停止条件和两条护栏字段化compile.mjs 以字节预算与表面门禁保证技能短小且不含宿主无法执行的指令skills/generated 与各宿主激活钩子完成最后一公里分发。这条技能与surgical-patch、verify-and-stop共同构成 caveman调查 → 修复 → 证明三段式工作模式的入口也是把通用工程纪律以最低 token 成本注入多宿主 Agent 的一个完整样本。【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考