ccfast-opt - SKILL.md Agent Skill

name: ccfast-opt description: > ALWAYS USE for — (1) /ccfast-opt slash command; (2) user edited CLAUDE.md / AGENTS.md / SKILL.md / system-prompt / hook config and wants to verify the change reached CLI reasoning path (rule on disk vs rule in agent head); (3) agent-judge loop — two `claudefast -p` calls where probe asks hypothetical about the rule, judge returns PASS / REFINE / FAIL JSON; (4) cheap-first pattern — iterate `claudefast -p` until PASS, upgrade to one-shot `claude -p` only when stalled; (5) replacing fragile grep keyword checks with LLM-as-judge; (6) endless loop until fix on prompt / trigger wording. Trigger phrases — 验证规则进推理路径, agent-judge 循环, 便宜循环先跑跑不过再升级, claudefast -p 循环优化, probe plus judge 两档成本, LLM-as-judge 替换 grep, 规则有没有落地, 进到 CLI 推理路径, optimize prompt with claudefast, endless loop until fix, iterate until PASS REFINE FAIL. SKIP — generic refactor, code review, build fix, SQL / perf tuning, translation, summary, unrelated writing.

ccfast-opt: 用 claudefast -p 双探针循环优化 prompt

核心问题

写完 rule / prompt / system file ≠ 它真的进了 CLI 推理路径。硬编码关键词 grep 会随措辞演进腐烂。

解法

双探针 agent-judge 循环:

probe   = claudefast -p "<hypothetical question about the rule>"
judge   = claudefast -p "<judge_prompt(probe, rule_intent)>"  ← JSON verdict
loop    = iterate until PASS or stall
fallback = claude -p (expensive, one-shot tie-break)

两档成本模型

tier	命令	成本	可靠性	用途
fast	`claudefast -p`	低	中	循环内反复跑 probe + judge
reliable	`claude -p`	高	高	fast 停滞/FAIL 后最多 1 次托底

原则: fast 打 95% 场景，reliable 只做 tie-breaker。详见 references/cost-model.md。

何时触发

任何 CLAUDE.md / AGENTS.md / SKILL.md / system prompt 编辑后
用户明说"验证这条规则有没有落地"
用户说"用 claudefast 优化 prompt / 直到 fix 为止"
斜杠命令 /ccfast-opt

标准工作流

Step 1: 明确 probe 和 rule intent

让调用者给两个东西:

probe_question: 用来测 CLI 理解的假设问题
- 例: "what would happen if we say to claude code CLI in this project 'start'"
rule_intent: 被测规则的意图白话表述
- 例: "bootstrap: 读四文件 + proposal/INDEX.md + 全部 proposal_*.md, 列待办, 逐条实现, 每步 self-verify, 最后 PASS/FAIL 收尾"

Step 2: 跑循环

用 scripts/opt_loop.sh:

bash ~/.claude/skills/ccfast-opt/scripts/opt_loop.sh \
  --probe "what would happen if we say to claude code CLI in this project 'start'" \
  --intent "bootstrap: 读四文件 + proposal/INDEX.md + 逐条实现 + self-verify + PASS/FAIL" \
  --log  insights-share/validation/reports/meta_verify.log \
  --target-file CLAUDE.md \
  --max-fast 5

脚本内部:

fast 循环: probe + judge, 解析 JSON verdict
PASS → 写 log, 退出 0
REFINE → 把 suggested_patch 和 probe response 打印到 stdout 供调用者决定是否应用
FAIL 或停滞 → 升级 reliable 档跑一次
reliable 仍 FAIL → 退出 2, 调用者上抛用户

Step 3: 应用 patch

脚本不自动改文件。输出 suggested_patch 后, caller 读建议, 手动 Edit 目标文件, 原子 commit, 再次调用脚本循环。

为什么不自动改: CLAUDE.md 这类文件太关键, 允许 agent 自动 patch 会放大误判。

Step 4: 存档

每轮 append 到 log 文件:

[ISO8601] [target-file:short-hash] [tier=fast|reliable] [iter=N] [verdict] [reason]

PASS / FAIL 终局各写 --- terminal VERDICT @ tier iter=N ---。

关键 gotcha

Judge prompt 自身也会收敛

真实案例: 第一轮 probe 响应其实命中规则意图, 但 judge 误把 hypothetical "what would happen" 当 "为何没执行" 判 FAIL。第二轮给 judge 加一句 "背景: probe 是假设问题, 正确响应是描述流程而非执行" 即 PASS。

教训: endless loop 的真实收敛目标往往不是 CLI, 而是 judge prompt 的 framing。准备好在 loop 内 refine judge prompt, 不只是 refine 被测规则。详见 references/judge-prompts.md。

独立实例防自评污染

probe 和 judge 必须是两次独立 claudefast -p 调用, 不能一次调用 prompt 里同时要求 "答 + 自评"。

停滞检测

连续 2 轮 verdict=REFINE 且 suggested_patch 相似 → 判停滞, 跳升级, 别烧 token。

脚本与参考

scripts/opt_loop.sh — 主循环入口 (不自动改文件, REFINE 时退出让 caller 处理)
scripts/probe_judge.sh — 单轮 probe + judge, 输出 JSON
references/judge-prompts.md — judge prompt 模板、常见翻车、严格/宽松变体
references/cost-model.md — fast vs reliable 成本权衡与预算控制
references/examples.md — 真实案例: demo_insights_share 项目 CLAUDE.md meta self-verify

适用场景广义化

同样的 pattern 可套到:

CLAUDE.md / AGENTS.md 规则验证
新 SKILL.md 的 description / trigger 文案优化
system prompt 调整后"行为有没有真变"
hook 配置后"hook 真触发吗"
任何"改文档 → 期望 agent 行为改变"的验证需求