1 / 1

CC Research
Playbook

AI Researcher 的 CLI Agent 实践指南

Yuanbo Yang  •  2026-03-16

同一个模型，不同的 Harness

Cursor、Codex、Claude Code 底层使用相同模型 — 能力差异来自 harness 设计。

IDE 内嵌助手
单轮问答，用户驱动
文本生成，作用于当前文件
无工具调用，无自主验证
≠
CLI Agent (ReAct Loop)
自主循环：plan → act → verify
工具调用：编辑、搜索、执行、部署
跨项目感知，自我验证
"The model didn't change. The harness around it did."

[1] Anthropic, "Effective Harnesses for Long-Running Agents" — anthropic.com ↗
[2] OpenAI, "Harness Engineering" — openai.com ↗

Context is All You Need

CLI Agent 的一切工程化手段，都围绕一个核心：如何管理 context。

INPUT

Feed sufficient context

用 Brainstorming 明确需求
用 Paper Agent 管理文献
用 Skills 注入领域知识

Skills · MCP · CLAUDE.md

OUTPUT

Drive efficient decisions

自动化 Code Review
Hook 驱动的质量门禁
Pipeline 串联工作流

Hooks · Subagents · Loop

MANAGEMENT

Keep the agent clear-headed

知识内化为文档 (CLAUDE.md)
及时压缩 (/compact)
重活外包给 Subagent

Memory · /compact · Subagent

Skills, Hooks, Sub-Agent, MCP — 都服务于同一目标：engineering the context.

[3] Anthropic, "Effective Context Engineering for AI Agents" — anthropic.com ↗
[4] Manus, "Context Engineering" — manus.im ↗

Key Tips 精选

WORKFLOW

git worktree 多会话并行

同时运行多个 Claude 实例，互不干扰

先 Plan Mode 再实现

一个 Claude 写计划，另一个审计划

"use subagents" 投入更多计算

主 context 保持干净，重活外包

定义终点

测试驱动 / CONTRACT.md 验收标准

DISCIPLINE

每次纠正后更新 CLAUDE.md

同类错误不再复现

日常操作做成 Skills

每天 >1 次的操作 → 自定义 slash command

利用讨好倾向

用中立 Prompt，防止 Agent 编造

定期清理 CLAUDE.md

让 Agent 自我整理，删除矛盾规则

[5] @bcherny, "10 Tips for Claude Code" — x.com/bcherny ↗
[6] @systematicls, "9 Coding Agent Principles" — x.com/systematicls ↗

现状：最佳实践在快速迭代

CLI Agent 生态每周都在变 — 新 feature、新 pattern、新 workflow 层出不穷。

COMMUNITY VOICES

  • @bcherny — 10 Tips for Claude Code ↗
  • @trq212 — Anthropic 内部 Skills 九大分类 ↗
  • @systematicls — 9 Coding Agent Principles ↗
  • @HiTw93 — 六层架构深度解析 ↗
  • 胡渊鸣 — 如何给 10 个 Claude Code 打工 ↗
  • AReaL — 32 天零手打代码构建分布式 RL ↗

THE PROBLEM

新 feature 不断涌现
每个人的 workflow 都不一样
不知道从哪里开始

OUR APPROACH

不追单个 feature
围绕 Context 理解每个工具的角色
建立可复用的工作流

常见失败模式

失败模式 问题 解决方案
厨房水槽 Session 无关任务混入同一会话，context 污染 切换任务前 /clear
反复纠正 失败尝试堆积，全是错误历史 纠正 2 次后 /clear，重新给干净 context
CLAUDE.md 过长 内容太多被忽略，规则互相矛盾 无情删减 + IF-ELSE 目录 + Skills
信任验证差距 边界 case 未覆盖，Agent 悄悄走错路 提供可验证的完成标准 (CONTRACT.md)
无限探索 context 耗尽前仍在漫无目的探索 缩小范围 或 subagent 隔离探索

所有失败模式的根因都是同一个：context 管理失控

Source: code.claude.com/docs/en/best-practices ↗

Connect the Dots：Features Serve Context

Skills、Hooks、Sub-agent、Loop — 不是凭空出现的功能，而是服务于 context 三个维度的工具。

INPUT

把足够的信息交给 Agent

Skills MCP CLAUDE.md

OUTPUT

让 Agent 做高效决策和执行

Hooks Sub-agents Loop

MANAGEMENT

保持 Agent 头脑清醒

Memory /compact Sub-agent
接下来逐一介绍：Skills → Hooks → Sub-agents → Loop

Skills — 可复用工作流的分发单元

Markdown 文件（可含脚本、数据、模板），按需加载到 context，用完即释放。

WHAT IS A SKILL?

一段 Agent 可直接消费的结构化知识
定义了 何时触发、做什么、怎么做
本质：工作流的可重复化分发

ANTHROPIC OFFICIAL

Anthropic 内部有几百个活跃 Skills
覆盖从代码审查到运维手册的全流程

POPULAR SKILLS

Source: code.claude.com/docs/en/skills ↗  |  HF Paper Skill: github.com/huggingface/skills ↗

Skills 对研究者的价值

01

Context 满了？整理成 Skill

当你发现反复在 session 开头粘贴同样的背景信息，
说明这些知识该固化为 Skill — 按需加载，不占常驻 context

02

重复的 Workflow → 一键 Skill

跑实验、写周报、做 slides、review 论文 — 只要做过两次以上的流程，
都值得写成 Skill，之后 /skill-name 一键复用，持续迭代优化

03

告别漫长 Prompt，维护 Skill 即可

不需要每次都写 500 字的 prompt 描述需求和约束，
Skill 内已编码了所有流程、踩坑点和质量标准 — 用时加载，用完释放

TIP description 写「何时触发」而非「我是什么」
TIP 踩坑点章节 = Skill 中信息量最大的部分
TIP 渐进式披露 — 用子目录按需加载

Tips: @trq212 ↗  |  Source: code.claude.com/docs/en/skills ↗

新的重复劳动

Claude Code 消灭了写代码的重复劳动 — 但践行 Best Practice 这件事本身，又成了新的重复劳动。

WE KEEP FORGETTING TO...

  • ✗ 开 worktree 隔离工作 → 直接在 main 上改
  • ✗ 把重复 context 整理成 Skill → 每次重新粘贴
  • ✗ 按规范写 commit message → 随手一句话
  • ✗ push 前 review diff → 直接 push
  • ✗ 清理 console.log → 带着调试代码上线

INCONSISTENCY

有些 repo 执行了规范
有些没有
执行力取决于记忆力

THE IRONY

我们用 AI 消灭了代码的重复劳动
却在管理 AI 这件事上
制造了新的重复劳动

Hooks — 确定性地消灭重复劳动

"Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle."

— code.claude.com/docs/en/hooks

4 HANDLER TYPES

command

Shell 脚本 via stdin/stdout

http

POST 到 HTTP endpoint

prompt

单轮 LLM 判断

agent

Spawn subagent 执行

KEY EVENTS (13+)

SessionStart 会话开始 PreToolUse 工具执行前 PostToolUse 执行后 Stop 回复结束 PreCompact 压缩前 SubagentStart 子代理启动 UserPromptSubmit 提交前 ConfigChange 配置变更
matcher 用正则过滤触发条件
exit 2 = 阻止操作，exit 0 = 放行
3 层配置 User / Project / Local

Hook = 把 Best Practice 从"记忆"变成"机制" — 在所有 repo 一致执行

Source: code.claude.com/docs/en/hooks ↗

Hook 实践案例

几个我们日常在用的 Hook，覆盖安全护栏、质量门禁和实验管理

PreToolUse → git push 审查

推送前自动打开 diff，人工确认后再执行

PostToolUse → 自动格式化

编辑 .ts/.tsx 后自动 prettier + tsc 检查

Stop → console.log 审计

会话结束前扫描所有修改文件，阻止残留调试代码

Stop → Skill 沉淀提醒

检测到 10+ 文件编辑 → 提醒运行 /writing-skills

CASE: EXPERIMENT MANAGEMENT

exp/
  exp01a/  # major=01, minor=a
    docs/   # 实验设计 + 结论
    scripts/ # 运行脚本
    summary.md # 结果总结
  exp01b/  # 同大版本的变体
  exp02a/  # 新大版本
SessionStart 自动检测当前实验 ID，加载对应 context
PostToolUse 新建实验时自动创建标准目录结构
Stop 实验结束前提醒填写 summary.md

Hook 如何服务 Context 三维度

INPUT

Stop 检测到大量编辑 → 提醒把新知识沉淀为 Skill → 下次 session 自动可用

OUTPUT

PostToolUse Skill 完成后自动推进 pipeline 阶段 → 提醒生成报告 / slides

MANAGE

PreCompact context 压缩前自动保存 pipeline 状态到 state.json

EXPERIMENT PIPELINE (HOOK-DRIVEN)

new-exp →hook scaffold →hook run →hook analyze →hook summary →hook commit

每个阶段由 hook 自动推进 — 你只需要关注当前实验

Sub-agent — Context Isolation 的功能分区

你想把论文知识输入到 repo，但读论文会污染你当前的 coding context。怎么办？

WITHOUT ISOLATION

[Main Context]
coding task ...50K tokens
+ paper content ...80K tokens
+ experiment logs ...30K tokens
= context 被无关内容淹没
= coding 质量下降
→

WITH SUBAGENTS

[Main] coding task ...50K
[Agent A] 读论文 → 写入 repo
[Agent B] 监控 jobs → 后台运行
[Agent C] 管理实验 → 独立 context
= 主 context 保持干净
= 后台任务不停
核心：专有 agent 获取专有 memory — 主 context window 干净的同时，也能获取之前 session 的 context

Sub-agent 研究场景

PAPER READER

读论文 → 沉淀到 repo

独立 context 读取 PDF
提取方法论 + 关键公式
写入 docs/papers/
主 agent 只收到 summary

domain-expert agent + HF Paper Skill

BACKGROUND MONITOR

后台监测运行中的 job

/loop 定期访问 tmux
获取 GPU 使用率 + loss
异常时通知主 agent
正常时静默运行

background agent + loop + tmux

EXPERIMENT MANAGER

管理实验生命周期

创建 exp##x/ 目录结构
追踪实验状态 (state.json)
生成 summary + slides
归档完成的实验

exp-manager agent + pipeline hooks

Main Context (clean, focused on current task)
  ├── spawn → Paper Agent → writes docs/papers/*.md → returns 5-line summary
  ├── spawn → Monitor Agent → runs in background → alerts only on anomaly
  └── spawn → Exp Agent → manages exp lifecycle → returns status update

Source: code.claude.com/docs/en/sub-agents ↗  |  AReaL 最佳实践: zhuanlan.zhihu.com/p/2003269671630165191 ↗

Loop — 循环自主执行

$ /loop 5m <command> █

Source: code.claude.com/docs/en/cli-reference ↗ (/loop)

Superpowers — Context is All You Need, in Practice

人不擅长列计划，Agent 不擅长自我约束 — Superpowers 用一套完整 workflow 同时解决 context 的输入、输出和管理。

INPUT

Brainstorming 产生丰富 context

不靠人写长 prompt
而是 Agent 逐个提问来澄清需求
自动生成完整的 spec 文档

Brainstorming → Spec

OUTPUT

Sub-agent 驱动高效输出

细化任务切分 + 制定计划
交给 subagent 并行执行
双重 review 确保输出质量

Plan → Execute → Review

MANAGEMENT

所有 context 落盘为文档

需求 → spec.md
计划 → plan.md
跨 session 完整保留，永不丢失

Spec + Plan + Git history

Brainstorming → Spec → Plan → Worktree → TDD → Review → Verify & Merge

Source: github.com/obra/superpowers ↗

Think: Brainstorming → Spec → Plan

Prompt Engineering 的痛点：人往往说不清自己要什么。Superpowers 用结构化提问解决这个问题。

1. BRAINSTORMING

  • ▸ 探索项目上下文（文件、文档、commits）
  • ▸ 逐个提问，澄清需求和约束
  • ▸ 提出 2-3 个方案 + 推荐理由
  • ▸ 逐节呈现设计，逐节确认

OUTPUT

docs/specs/YYYY-MM-DD-design.md
经 spec-reviewer 自动审查 + 用户确认

2. WRITING PLANS

  • ▸ 映射文件结构，识别依赖
  • ▸ 拆分为独立任务（每个 2-5 分钟）
  • ▸ plan-reviewer 自动审查一致性
  • ▸ 每个任务可独立交给 subagent 执行

OUTPUT

docs/plans/YYYY-MM-DD-plan.md
经 plan-reviewer 审查 + 用户确认

关键：所有思考过程落盘为文档 — 不再只存在于对话历史中，跨 session 永不丢失

Build & Verify: Execute → Review → Merge

3. EXECUTE (Subagent-Driven)

  • ▸ 创建隔离 git worktree
  • ▸ 每个任务分发给独立 subagent
  • ▸ 强制 TDD: RED → GREEN → REFACTOR
  • ▸ 每个任务完成后自动 commit

4. REVIEW (双重审查)

  • ▸ Spec 合规性审查：代码是否符合设计？
  • ▸ 代码质量审查：实现是否可维护？
  • ▸ 两者都通过才进入下一步

5. VERIFY (证据优先)

$ npm test
Tests: 42 passed, 0 failed
$ git diff --stat
12 files changed, 340(+), 28(-)

无实际运行证据 → 不允许声称完成

6. FINISH (4 种路径)

Merge
Push + PR
Keep branch
Discard

worktree 自动清理

整个流程完全通用 — 不限于编程，任何需要 spec → plan → execute 的任务都适用

Labmate — Context is All You Need, Fully Realized

把前面所有实践融入一个 Claude Code plugin — 开箱即用的研究项目 harness

INPUT

专有 Agent 喂 Context

  • ▸ domain-expert 读论文 → 写入 docs/papers/
  • ▸ project-advisor 追踪实验历史
  • ▸ SessionStart hook 自动注入项目 context
OUTPUT

Skill 驱动标准化输出

  • ▸ /new-experiment 标准目录脚手架
  • ▸ /analyze-experiment 分析 + slides
  • ▸ exp-manager 后台监控 + 重试
MANAGEMENT

知识进 repo，不留聊天

  • ▸ /update-project-skill 压缩知识到 SKILL.md
  • ▸ PreCompact hook 提醒保存状态
  • ▸ .pipeline-state.json 跨 session 持久
$ claude plugin install freemty/labmate   →   7 agents + 7 skills + 5 hooks + experiment infra

Source: github.com/freemty/labmate ↗

Labmate — 解决了什么问题

AI 研究者用 Claude Code 跑实验时，反复遇到的 4 个痛点

CONTEXT LOSS

每次开 session 都要从头说

"上次跑到哪了？结论是什么？下一步做什么？"
实验越多，重复交代背景的时间越长

NO STRUCTURE

实验目录随手建，越来越乱

exp1/ test_v2/ final_final/
没有统一命名、没有标准结构，跨实验对比靠记忆

KNOWLEDGE EVAPORATES

实验结论只存在于聊天记录

论文笔记、调参心得、失败教训 —
session 结束就消失了，下次又踩同样的坑

MANUAL EVERYTHING

每个环节都要手动推进

建目录、跑实验、写总结、commit、生成 slides —
流程没有自动化，全靠人记着下一步是什么

Labmate 的答案：一条命令安装，获得完整的研究项目 harness — 7 agents + 7 skills + 5 hooks

github.com/freemty/labmate ↗  |  First user: PostTrainBench — 迭代 auto post-training 的 agent

Labmate — 元素一览

7 AGENTS

domain-expert — 读论文、写笔记
project-advisor — 实验建议
exp-manager — 后台监控 + 重试
slides-maker — 生成分析 slides
+ 3 个辅助 agent (reviewer, etc.)

设计原则：4/7 只读，最小权限

7 SKILLS

/new-experiment — 4 问 → 脚手架
/analyze-experiment — 分析 + slides
/commit-changelog — 标准 commit
/update-project-skill — 知识压缩
+ init-project, weekly-progress, etc.

完整实验周期：建 → 跑 → 分析 → 沉淀

5 HOOKS + INFRA

SessionStart — 注入项目 context
PreCompact — 保存 pipeline 状态
Stop — 提醒下一步
.pipeline-state.json — 状态机
exp/{NN}{x}/ — 标准目录

hook 只提醒不拦截，知识进 repo

$ claude plugin install freemty/labmate  →  /init-project  →  /new-experiment  →  run  →  /analyze  →  /commit  →  ↩ repeat

github.com/freemty/labmate ↗

数据驱动的 Skill 生成

用 /insights 分析历史对话 → 自动发现高频痛点 → 生成 Skill 建议

PROCESS

1. /insights 分析 92 sessions 的对话历史
2. 识别高频操作、重复摩擦、失败模式
3. 生成 Skill + Hook + Cron 建议（含优先级）
4. 实现 → 部署 → 下一轮 insights 验证效果

又一个 Meta Layer：
用 AI 分析你的 AI 使用模式 → 生成更好的 AI 工作流

EXAMPLE: TOP SKILL RECOMMENDATIONS

/fleet-monitor — 30 次 monitor 操作 → GPU 集群健康巡检
/web-extract — #1 摩擦源 → URL 智能路由，跳过 fallback
/session-wrap — 23 次 git 操作 → 标准化收尾仪式
/exp-resume — 166 篇论文多轮 → 断点续跑自动化
URL Router Hook — PreToolUse 拦截 → 事前路由替代事后补救

Workflow: @JamesAI — /insights → Skills pipeline ↗

CLAUDE.md 最佳实践

项目的路由入口 — 精简、精确、可路由

DO 写进去

  • ✓ 构建命令 (build / test / lint)
  • ✓ 代码风格偏好 (const/let, types)
  • ✓ 测试指南 (框架、覆盖率)
  • ✓ 架构决策 (目录结构、分层)
  • ✓ IF-ELSE 逻辑目录 → 指向 Skills

DON'T 不要写

  • ✗ Claude 能自行推断的内容
  • ✗ 标准行业惯例 (众所周知)
  • ✗ 详细 API 文档 (用 Skills)
  • ✗ 频繁变化的配置 (易失效)
  • ✗ 百科全书式罗列 (会被忽略)
Hooks > CLAUDE.md (100% 执行)
Skills > CLAUDE.md (按需加载)
Token 预算: <200 行

Source: code.claude.com/docs/en/best-practices ↗

Always Hold the "Meta" Mindset in Agent Era

"Steel. Steam. Infinite minds.
The next skyline is there, waiting for us to build it."

— Ivan Zhao (Notion), "Steam, Steel, and Infinite Minds"

1790 年，改良蒸汽机让煤矿挖出更多的煤、炼出更好的铁、造出更好的蒸汽机 — 飞轮第一次自锁转动。
我们即将进入一个 Agent 迭代 Agent 的时代，这像极了那个起点。

THE META LAYER

每当 AI workflow 能帮我们加速一件事，
我们就可以往上跳一层 —
思考如何在更 Meta 的层面
用 AI 加速 workflow 本身

CASE IN POINT

Labmate 的第一个用户是一个 Claude Agent，
正在加速一个 Language Model
Post-Training Agent 的工作效率

Agent 构建的 harness，
正在被用来加速下一个 Agent

Harness 让人和 Agent 都实现 scalable 的自我觉察 — 维护着让个体保持反思和明确目标的基础设施，而不只是执行任务

[1] Ivan Zhao, "Steam, Steel, and Infinite Minds" — notion.com/zh-cn/blog/steam-steel-and-infinite-minds-ai ↗

参考阅读

HARNESS / CONTEXT ENGINEERING

Anthropic — Effective Harnesses
Anthropic — Context Engineering
Anthropic — Demystifying Evals
OpenAI — Harness Engineering
Manus — Context Engineering
Ivan Zhao — Steam, Steel, Infinite Minds

OFFICIAL DOCS

KEY PEOPLE & POSTS

@bcherny — Boris Cherny, 10 Tips
@trq212 — Thariq, Skills 九大分类
@HiTw93 — Tw93, 六层架构
@systematicls — 9 Agent Principles
@JamesAI — /insights 数据驱动
胡渊鸣 — 给 10 个 CC 打工

CASE STUDY

AReaL — 32 天零手打代码, 72 万行 (知乎)
inclusionAI/AReaL — 分布式 RL 框架

SKILLS ECOSYSTEM

skills.sh — Skill 市场
anthropics/skills — 官方 Skill 编写指南
NanoBanana-PPT — PPT 生成
frontend-slides — HTML 演示文稿
notebooklm-skill — NotebookLM 集成
manim_skill — 数学动画

GITHUB REPOS

freemty/labmate — 研究项目 plugin
obra/superpowers — 软件工程 14 Skills
huggingface/skills — Daily Paper Skill
everything-claude-code — 资源汇总
cc-nano-banana — 图片生成

TOOLS & MISC

Jina Reader — r.jina.ai/<URL>
OpenClaw — Model Failover
ClawHub — Agent Reach
OpenAI Codex — Codex App (对比)
CC Costs — 费用参考

Questions?▌

"We want humans to supervise the loops
from a leveraged point, not be in them."

— Ivan Zhao

Yuanbo Yang  •  2026-03-16  •  github.com/freemty/labmate