caveman 的 caveman-review 技能详解行级代码评审的输出契约、严重度标记与 Hook 接线机制【免费下载链接】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/cavemancaveman 项目中的caveman-review是一个压缩式代码评审技能它把传统冗长的 PR 评审意见压缩为L行号: 问题. 修复建议.的单行格式每条发现一行只保留位置、问题与修复方案。本文以 skills/caveman-review/README.md 和 skills/caveman-review/SKILL.md 为主体结合 模式解析器 与 技能注册表 等仓库源码完整讲清该技能的输出契约、严重度体系、Auto-Clarity 放松规则、调用方式以及底层接线原理。读完后你可以准确复述该技能的格式规范并能从源码层面解释/caveman-review命令是如何被 Claude Code hook 和 OpenCode 插件识别并激活的。技能定位只做输出不做任何副作用caveman-review的核心定义是单行式 PR 评论只写位置、问题、修复不写任何寒暄铺垫No throat-clearing。根据仓库文档 docs/technical/skills-hooks-and-plugins.md 中的Focused skills契约表该技能的边界被明确登记为Skill输出契约副作用caveman-review行级line-scoped评审发现不 approve、不 request-changes、不跑 linter这与 skills/caveman-review/SKILL.md 结尾的 Boundaries 一节完全一致评审只做输出——不代写修复代码、不执行 approve / request-changes、不运行 linter产物是可直接粘贴进 PR 的评论。README 中也再次强调 Output only — does not approve, request changes, or run linters。这种纯输出契约使该技能可以安全地嵌入任何已有评审流程不与 CI、lint 工具链或 PR 状态机产生耦合。在主 README.md 的命令总表中/caveman-review被列在一次性安装附带的小工具里描述为 One-line, actionable review findings与/caveman-commit简洁提交信息、/caveman-compress file压缩记忆文件等并列为独立命令。输出格式一行一个发现技能的输出格式是严格的结构化契约来自 SKILL.md 的 Rules 一节基础格式Lline: problem. fix.—— 评审多文件 diff 时扩展为file:Lline: ...。严重度前缀可选混合严重度时建议带上前缀含义 bug:行为已损坏会引发事故 risk:能跑但脆弱竞态、缺空值检查、吞异常 nit:风格、命名、微优化作者可忽略❓ q:真正的问题question不是建议README 给出的标准输出示例可直接作为格式基准L42: bug: user can be null after .find(). Add guard before .email. L88-140: nit: 50-line fn does 4 things. Extract validate/normalize/persist. L23: risk: no retry on 429. Wrap in withBackoff(3). L107: ❓ q: why drop the cache here? Reads on next request will miss.四个示例恰好覆盖全部四种严重度并展示了两种行号写法单行L42与行区间L88-140。注意每条都满足位置 问题 具体修复三段式 bug给出可定位的.find()与需保护的.email nit给出可执行的拆分方案extractvalidate/normalize/persist risk给出具体包裹函数withBackoff(3)❓ q则说明不确定的因果下次请求会 miss 缓存。Drop / Keep 规则删掉什么、留下什么格式规范之外SKILL.md 还定义了两张清单这是该技能区别于普通简短评审的关键。必须删掉DropI noticed that...、It seems like...、You might want to consider... 这类开场白This is just a suggestion but... —— 改用nit:前缀表达Great work!、Looks good overall but... —— 总体评价只允许在开头说一次不能出现在每条评论里复述代码行本身在做什么 —— 评审者自己会读 diff一切模糊措辞hedgingperhaps、maybe、I think —— 不确定就用q:。必须保留Keep精确行号精确的符号 / 函数 / 变量名且用反引号包裹具体修复方案而不是 consider refactoring this 这类空话当修复方案无法从问题本身直接推出时附上why。SKILL.md 中给出了一组 ❌/✅ 对照展示了删词前后的差异值得完整参考❌ 冗长版✅ 压缩版I noticed that on line 42 youre not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here.L42: bug: user can be null after .find(). Add guard before .email.It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability.L88-140: nit: 50-line fn does 4 things. Extract validate/normalize/persist.Have you considered what happens if the API returns a 429? I think we should probably handle that case.L23: risk: no retry on 429. Wrap in withBackoff(3).对照可见压缩版不是简单截断而是把描述现象 猜测后果 委婉建议三句合并为现象带精确符号 动作带具体函数名两句并去掉全部模糊词。Auto-Clarity该详细时必须详细纯压缩式输出有一个天然风险在安全类发现、架构分歧或新人上手场景中一行话可能不足以传达why。为此技能内置了Auto-Clarity机制README 与 SKILL.md 均有说明遇到以下三类情况时自动退出 terse 模式写正常段落其余发现恢复 terseCVE 级安全发现—— 需要完整解释加引用依据SKILL.md 表述为 CVE-class bugs need full explanation reference架构分歧architectural disagreements—— 需要理由阐述一行不够onboarding 场景—— 作者是新成员需要知道why而不只是what。README 对这一机制的表述是drops terse mode for CVE-class security findings, architectural disagreements, and onboarding contexts where the author needs thewhy. Resumes terse for the rest. 这与主技能caveman的 Auto-clarity 设计一脉相承——压缩永远让位于安全警告和不可逆操作的清晰度见 docs/technical/skills-hooks-and-plugins.md 对主技能 Auto-clarity relaxes compression 的说明。调用方式与触发词主命令/caveman-review自然语言触发词来自 SKILL.md 的 frontmatter descriptionreview this PR、code review、review the diff。退出评审风格说 stop caveman-review 或 normal mode 即可恢复冗长verbose评审风格SKILL.md Boundaries 一节。源码解析/caveman-review如何被解析为模式激活技能的调用不是魔法仓库中有明确的解析链路。核心在共享模式解析器 src/hooks/caveman-parse.jsparseModeChange函数它被 Claude Code 的 hook 与 OpenCode 插件共同复用文件头部注释说明其目的正是让 hook 和插件不会与 tracker 的正则行为漂移。1.review是独立模式不能通过/caveman arg选择。解析器中定义// Modes handled by their own slash commands (/caveman-commit, etc.) — not // selectable via /caveman arg. const INDEPENDENT_MODES new Set([commit, review, compress]);见 src/hooks/caveman-parse.js#L51-L53。这意味着如果你输入/caveman review解析器不会激活评审模式而是返回unresolved并提示使用/caveman-review这个专属命令——独立模式只能走自己的斜杠命令入口。2. 斜杠命令分支同时支持 marketplace 命名空间形式。在parseModeChange的斜杠命令匹配段src/hooks/caveman-parse.js#L213-L232if (cmd /caveman-review || cmd /caveman:caveman-review) { return { action: set, mode: review }; }两种形态都被识别直接输入/caveman-review或以 marketplace 插件命名空间形式出现的/caveman:caveman-review代码注释指出此前只有 compress 和 stats 处理了命名空间变体后来补齐了全部技能。匹配成功后返回{ action: set, mode: review }由调用方hook 或插件激活 review 模式。3. OpenCode 路径模板展开前的文字识别。OpenCode 会把用户键入的/caveman-review展开为命令文件的正文文本后再触发事件因此解析器提供了expandedTpl选项来反向识别src/hooks/caveman-parse.js#L170-L182if (/^review the current diff\b/.test(prompt)) { return { action: set, mode: review }; }即当提示词以 review the current diff 开头时这是评审命令模板的固定前缀同样解析为激活review模式。注释特别强调这段逻辑必须在通用自然语言激活匹配之前运行否则模板正文里的 Activate caveman mode 之类措辞会抢先触发默认模式。4. 自然语言触发与防误触。解析器还会对整段提示词做自然语言匹配如 activate caveman 类短语并做了多重防护引号包裹的文本和界定在匹配前被置空避免引用触发词例如粘贴帮助卡片内容误触模式切换以/开头的命令文本不会反过来切换模式疑问句what is caveman mode? 等被识别为提问而非激活命令。相关回归测试见 tests/test_caveman_parse.js 与 tests/test_mode_tracker.pyOpenCode 插件侧的安装/行为测试见 tests/installer/opencode.test.mjs。注册与校验技能在仓库中的登记状态caveman-review在 skills/registry.json 中被列入preserved_skill_idspreserved_skill_ids: [ cavecrew, caveman-commit, caveman-compress, caveman-help, caveman-review, caveman-stats ]从注册表结构看skills数组登记的是参与 native pack 分发的技能带delivery与suites字段如caveman、caveman-setup等而preserved_skill_ids是保留的传统技能集合——caveman-review属于后者即它是通过常规 skill 安装路径分发、被注册表显式保留的技能而非 native packcaveman-local的一部分。仓库的完整性校验脚本 tests/verify_repo.py 也会检查skills/caveman-review/SKILL.md路径存在确保该技能目录不被意外删除。技能的 SKILL.md 采用标准 frontmatter 描述name: caveman-reviewdescription声明了三个触发场景/caveman-review、review this PR、review the diff供 LLM 路由使用。压缩评审的实际收益仓库基准主 README.md 的基准表中包含一项与安全评审直接相关的任务TaskNormalCavemanSavedReview PR for security issues67839841%这说明在PR 安全评审这一典型场景下caveman 风格的评审输出相对普通输出约有 41% 的 token 差该数字来自主 README 的基准表适用于仓库所述测试条件。需要注意的是该技能同时内置了 Auto-Clarity对 CVE 级安全发现会主动放宽压缩、写完整段落因此实际收益会随发现类型浮动。适用前提与限制技能面向评审输出不改变任何文件、不执行 lint、不改变 PR 状态——它的输出契约在 docs/technical/skills-hooks-and-plugins.md 中登记为无副作用斜杠命令/caveman-review依赖宿主 agent 的命令路由Claude Code、Codex、Gemini、Cursor 等具体可用命令取决于宿主支持的插件/hook 形态自然语言触发词 review this PR / review the diff 则依赖 LLM 对 SKILL.md frontmatter 的路由理解严重度前缀是可选、混合时建议带全 的 diff 可以不带前缀想退出评审风格直接说 stop caveman-review 或 normal mode。延伸阅读skills/caveman-review/README.md — 技能概览本文主体来源skills/caveman-review/SKILL.md — 完整的 LLM 面向指令Drop/Keep 清单、Auto-Clarity、Boundariessrc/hooks/caveman-parse.js — 模式解析器/caveman-review到review模式激活的解析链路skills/registry.json — 技能注册表与preserved_skill_idsdocs/technical/skills-hooks-and-plugins.md — 技能/钩子/插件的集成边界总览README.md — 仓库总览与命令表【免费下载链接】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），仅供参考