
Caveman 的 surgical-patch 技能bugfix 任务如何被约束为“最小改动 回归证明”【免费下载链接】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/cavemansurgical-patch 是 caveman 仓库内置的六个“原生工作模式”native work patterns之一专门用于 bug 修复类任务它不改变模型说话的方式而是约束模型改代码的方式——先复现、再定位到最小责任层、只做修复本身的改动、并留下与任务相关的回归证明。读完本文你将理解这条技能在 caveman 的 registry 元数据、编译管线、native pack 运行时选择机制中的完整位置以及它如何在 Claude、Codex、Gemini、Hermes、OpenCode、Aider 六类宿主中按需注入。技能本体16 行指令的全部规则技能正文位于 skills/surgical-patch/SKILL.md。它由 YAML frontmattername与description加正文两部分组成正文就是会进入提示词的“指令体”# Surgical patch Reproduce failure first when economical; otherwise capture strongest available evidence. - Trace symptom to responsible mechanism. - Change narrowest layer that owns incorrect behavior. - Preserve unrelated behavior and user changes. - Avoid cleanup, renaming, and abstraction outside fix. - Add only regression proof relevant to task. Run focused proof plus nearest affected gate. Stop when failure is fixed and regression proof passes.frontmatter 的description字段说明了技能的触发画像Fix bugs and small behavior changes at the narrowest responsible layer. Use when regression proof, preserved surrounding behavior, and task-relevant tests matter.正文按“证据 → 定位 → 改动边界 → 验证”的顺序给出六条硬规则逐条拆解如下先复现失败但只在“经济上合理”时。Reproduce failure first when economical; otherwise capture strongest available evidence.这条规则刻意留了口子复现成本过高比如需要完整生产环境、长周期压测时不强迫复现转而采集“当前能拿到的最强证据”日志、堆栈、失败截图等避免为了仪式感复现而浪费整轮上下文。把症状追到责任机制。Trace symptom to responsible mechanism.不满足于“错误出现在哪一行”要求解释是哪一层、哪个机制产生了错误行为这是后续“最小层”判定的前提。只改拥有错误行为的最小层。Change narrowest layer that owns incorrect behavior.责任归属是核心判据错误在谁手里就改谁不允许“顺手”改到上游或下游。保留无关行为与用户的未提交改动。Preserve unrelated behavior and user changes.修复不得破坏邻近功能也不得吞掉开发者本地的在途修改。修复之外不做清理、重命名和抽象。Avoid cleanup, renaming, and abstraction outside fix.这是对 agent 常见的“扩散式重构”冲动的直接拦截——diff 里不该出现与修复无关的行。只加与任务相关的回归证明。Add only regression proof relevant to task.测试是证明这次失败不会复发的工具不是顺手扩建测试套件的理由。结尾的收尾指令规定了验证与停止条件Run focused proof plus nearest affected gate. Stop when failure is fixed and regression proof passes.——运行聚焦证明加“最近一层受影响的门禁”对应仓库中最贴近该改动的测试/lint/构建关卡当“失败已修复且回归证明通过”时停止不多做一步。同目录下还有 skills/surgical-patch/agents/openai.yaml提供展示名与默认调用话术Use $surgical-patch to fix this bug with a narrow verified change.用于宿主侧的技能列表展示不参与提示词注入。registry 元数据surgical-patch 的机器可读契约技能正文本身很短但它的行为契约由 skills/registry.json 中surgical-patch条目完整定义#L129-L142{ id: surgical-patch, summary: Fix the narrowest responsible layer with regression proof., delivery: [native], suites: [], activation: classified, task_types: [bugfix], evidence_status: structural-test-only, prompt_byte_budget: 850, conflicts: [], precedence: 100, guardrails: [avoid_unrelated_cleanup, preserve_surrounding_behavior], entry_condition: task fixes incorrect behavior, stop_condition: failure is fixed and regression proof passes }各字段与正文规则的对应关系值得逐条说明delivery: [native]该技能只通过 native pack 交付不进入 CLI 技能表或 Web 端即它作为宿主 agent 的原生策略层注入而不是作为可显式调用的 CLI 命令。activation: classified编译管线强制 native 技能只能声明classified激活方式skills/compile.mjs 中if (meta.activation ! classified) die(...)即技能在任务类型被分类为bugfix之后才激活而非无条件常驻。task_types: [bugfix]它是bugfix任务类型的唯一属主。同一任务类型若被多个技能声明编译期要求它们必须互相声明冲突且 precedence 不同否则构建直接失败skills/compile.mjssurgical-patch 的conflicts: []说明bugfix域当前没有竞争者。prompt_byte_budget: 850正文指令体的 UTF-8 字节数上限。编译期以Buffer.byteLength(instructions) meta.prompt_byte_budget做硬校验skills/compile.mjs。实测该技能正文指令体约 470 余字节远小于 850 上限留有余量。guardrailsavoid_unrelated_cleanup与preserve_surrounding_behavior两条护栏恰好是正文第 4、5 条规则不做修复外清理、保留无关行为的机器可读形式。entry_condition/stop_condition入口条件“任务修复错误行为”、停止条件“失败已修复且回归证明通过”与正文结尾的停止指令完全一致构成“进入—退出”闭环。这些元数据同时受到严格的结构校验skills/compile.mjs 白名单SKILL_KEYS限定条目只能出现这 12 个键任何未知键都会让agent-skill compile failed终止构建正文必须带 YAML frontmatter、name必须与目录同名、且不能包含TODO/FIXME/not implemented等占位标记skills/compile.mjs。也就是说surgical-patch 的正文在“进包”之前就通过了完整性与预算两道门禁。从源文件到六类宿主编译与注入链路SKILL.md是唯一权威来源。skills/compile.mjs 文件头注释写明Every skill body lives once at skills/ /SKILL.md. registry.json decides which delivery surfaces receive it and which install suites include it. The CLI and web import generated TypeScript; neither hand-copies prompts.编译产物有三条线skills/id/SKILL.md skills/registry.json → CLI 端生成packages/cli/src/agent-skills.generated.ts与 packages/cli/src/native-pack.generated.ts六个 native 目标claude、codex、hermes、gemini、opencode、aider各自生成一份 skills/generated/ 下的pack.json汇总写入 proxy/internal/nativepack/native-pack.generated.json被 Go 端以//go:embed内嵌进二进制。surgical-patch 在生成文件 proxy/internal/nativepack/native-pack.generated.json 中的完整形态含instructions字段与 SKILL.md 正文逐字一致可作查证。pack 顶层还携带强制 Coreschema为caveman.native-pack.v1version2.2.0core.prompt_token_budget560、estimated_tokens556估算基准ceil_utf8_bytes_divided_by_3。Core 全文来自 skills/native-core.md其中两条与 surgical-patch 直接咬合Run smallest sufficient proof.最小充分证明呼应“focused proof plus nearest affected gate”与Fix root cause.呼应“trace symptom to responsible mechanism”。六类宿主的注入挂载点由 skills/compile.mjs 的NATIVE_ACTIVATION表定义并原样进入 pack 的targets字段native-pack.generated.json宿主Core 挂载任务策略挂载claudeSessionStartUserPromptSubmitcodexdeveloper_instructionsSessionStartUserPromptSubmithermespre_llm_callpre_llm_callgeminiBeforeAgentBeforeAgentopencodeexperimental.chat.system.transformchat.messageaiderread_only_conventionsnative_repository_map_authoritativeCore 在会话开始时注入而 surgical-patch 这类任务策略则在任务被分类为bugfix后经任务挂载点追加为“动态尾”。CLI 端测试 packages/cli/tests/hooks.runtime.mjs 验证了这一形态prompt.submit事件携带context: Caveman task contract (dynamic tail): policysurgical-patch说明运行时确实按任务策略名把 surgical-patch 挂接到本次提示上同文件 L385 还断言 Gemini 宿主的hookSpecificOutput.additionalContext得到同样的策略尾。运行时选择Select(bugfix) 如何命中 surgical-patchproxy 侧的加载与选择逻辑在 proxy/internal/nativepack/pack.go。要点Load()用sync.Once单次反序列化内嵌 JSON并跑validate()校验 schema 标识、Core 预算、每个技能的activation classified、指令体字节数不超预算、conflicts 必须指向已知技能且同一任务类型的竞争者必须互相声明冲突、precedence 不得相同pack.go——与编译期的同构约束在运行时再查一遍属于“双保险”。Select(taskType)对任务类型做小写化与裁剪后线性匹配各技能的task_types多候选时取precedence更高者pack.go。未登记的任务类型 fail-closedSelect(review)返回okfalse即不注入任何任务策略只保留强制 Core。测试 proxy/internal/nativepack/pack_test.go 把这张映射表固化下来#L16-L19wants : map[string]string{ feature: lean-build, bugfix: surgical-patch, investigation: investigate-first, refactor: safe-refactor, migration: migration, verification: verify-and-stop, }断言要求bugfix选择结果必须是 surgical-patch、evidence_status必须是structural-test-only、指令体长度不得超过字节预算且 pack 形状为 6 技能 × 6 宿主#L13-L15。六个 native 技能恰好覆盖六种任务类型一对一、无冲突因此全部conflicts: []、precedence: 100即可通过校验。与其他工作模式的边界README.md 将这六个技能统一描述为Work 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 so they read as generic patterns to the model——刻意不带品牌词让模型读到的是通用工程纪律而非项目话术。这也是 surgical-patch 正文通篇没有任何 “caveman” 字样、只有中性工程语言的深层原因。对照 registry 中各技能的入口条件可以看清 surgical-patch 的分工边界原因不明、入口条件是“cause is ambiguous”的调查任务归 investigate-first护栏no_edit_before_credible_hypothesis甚至禁止先改代码结构变更、行为不变的任务归 safe-refactor停止条件是“前后证明一致”只有“任务修复错误行为”才进入 surgical-patch修复完成后的验证阶段若单独提出则命中 verify-and-stop 的“最小充分证明集”。换句话说surgical-patch 解决的是“bug 已经定位或易于定位”区间内的改动纪律它的上游是 investigate-first 的证据下游是 verify-and-stop 的收口。预算与门禁为什么正文必须只有 16 行这套技能体系的约束哲学是“提示词本身也是被审计的代码”。对 surgical-patch 而言可验证的门禁有字节预算硬校验正文指令体 850 字节即构建失败保证任何单条任务策略的注入成本有上界skills/compile.mjs、pack.go 双重检查。表面一致性门禁skills-verbs gate编译前会用loadSurfacesscanSkillBody扫描技能正文若正文引用了 CLI/MCP/SDK 并不存在的命令或工具构建“fail closed”skills/compile.mjs。surgical-patch 正文不引用任何具体命令天然通过。Core 预算联动Core 估算 token 超 560 即失败skills/compile.mjs运行时再核对EstimatedTokens PromptTokenBudgetpack.go。占位内容封禁TODO、FIXME、not implemented标记直接让技能出包失败防止草稿状态混入生产包。复现与验证方式只读操作在本地仓库中可按以下只读路径走查 surgical-patch 的完整生命周期阅读源文件skills/surgical-patch/SKILL.md、skills/surgical-patch/agents/openai.yaml核对元数据skills/registry.json运行技能编译管线观察校验输出与生成文件刷新node skills/compile.mjs需要 Node.js 运行环境该脚本会重新校验预算、frontmatter、verbs gate 并覆写生成产物查看编译产物proxy/internal/nativepack/native-pack.generated.json、skills/generated/claude/pack.json其余五类宿主同构运行选择逻辑测试在proxy/下执行go test ./internal/nativepack/验证bugfix → surgical-patch映射与 fail-closed 行为查看注入形态的测试证据packages/cli/tests/hooks.runtime.mjs、packages/cli/tests/hooks.runtime.mjs。小结surgical-patch 的价值不在文字量——16 行正文、约 470 字节——而在它把“修 bug”这一高频 agent 场景压缩成一份可编译、可校验、可注入的契约入口条件修复错误行为、护栏不扩散清理、保留周围行为、停止条件失败修复且回归证明通过三者在 SKILL.md 正文、registry 元数据、编译产物与 Go 运行时测试之间四处互证。对使用方而言只需让宿主接入 native packbugfix 类任务即自动获得这层最小改动纪律对扩展者而言task_types、prompt_byte_budget、guardrails、entry/stop_condition这组字段加上 compile 门禁就是新增一个原生工作模式的完整模板。【免费下载链接】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),仅供参考