本文综合了 Harness Engineering 系列两本书的核心洞察，并结合社区最新实践经验，旨在为 Claude Code 使用者提供一份兼具理论深度和实操价值的指南。
核心立场：模型是不稳定的，但围绕它的系统可以是可靠的。 你对 Claude Code 的掌控程度，取决于你对 Harness 的理解深度。
第一部分：理解 Claude Code 的设计哲学
1.1 为什么需要”Harness Engineering”
当模型只能输出文字时，出错的代价是”回答不好”。但当模型能执行命令、写文件、操作 Git 时，出错的代价变成了”执行造成真实损害” — 目录被改、进程被杀、Git 历史变得难以审计。
Claude Code 的设计从一开始就承认一个事实：模型不值得无条件信任。它不是一个套了壳的聊天机器人，而是一个有完整控制结构的工程系统。这个控制结构就是 Harness。
Harness 包含五层：
- Prompt 控制平面 — 不是人设装饰，而是行为协议
- 查询循环（Query Loop） — 持续的、有状态的执行循环，是系统的心跳
- 工具调度与权限 — 工具不是能力的延伸，而是需要被管理的执行接口
- 上下文治理 — 内存、CLAUDE.md、compact 构成预算管理体系
- 错误恢复 — 失败路径是主路径，不是异常处理
理解这五层，你就理解了为什么 Claude Code 有时候”不听话” — 它不是在对抗你，而是在执行它的控制协议。
1.2 两种 Harness 哲学：运行时纪律 vs 制度设计
通过对比 Claude Code 和 Codex（OpenAI），可以看到 AI 编码系统的两条路线：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
这不是谁更好的问题。关键是：你准备在哪一层关住不确定性？ 笼子的位置决定了系统未来会长成什么样。
对 Claude Code 使用者来说，理解”运行时纪律”这个核心理念，能帮你更好地配合系统工作，而不是和它对抗。
第二部分：CLAUDE.md — 你最重要的配置文件
CLAUDE.md 是每次会话的系统 prompt，是你和 Claude Code 之间的”宪法”。写好它，等于给每次对话设定了正确的起点。
2.1 三层架构
Claude Code 的 CLAUDE.md 按层级累积加载（不是覆盖）：
~/.claude/CLAUDE.md ←全局层：个人跨项目习惯./CLAUDE.md ←项目层：团队架构、标准、命令（提交到 git）./CLAUDE.local.md ←本地层：个人项目偏好（不提交）.claude/rules/*.md ← 规则目录：按需加载的细分规则
2.2 写什么、不写什么
必须写的（Claude 无法从代码推断的信息）：
- 项目一句话描述 + 技术栈
- 构建/测试/部署命令（
pnpm dev、npm run build等） - 与默认不同的代码风格偏好（附反例）
- 非显而易见的架构决策和设计约束
- 你踩过的坑（有机增长，遇到一个加一个）
不要写的：
- Claude 能从代码自行推断的”常识”
- 模糊的指令（”写干净的代码”）
- 假设性的规则 — 只写你实际遇到过的问题
- 可以用 hooks 机械执行的规则（格式化、lint 等）
2.3 长度控制
这是很多人忽略的关键点：
- 最佳长度：100-200 行（约 800-1600 tokens）
- 上限：300 行。超过后每条低价值规则都会等比稀释高价值规则的遵守率
- 超长怎么办：拆分到
.claude/rules/目录，按需加载
“LLM 可靠遵循指令的上限大约是 150-200 条。超过这个阈值，退化是均匀的 — 你加的每一条低价值规则，都在等比削弱所有高价值规则的执行力。” — How to Write a CLAUDE.md That Actually Works
2.4 实用模板
# CLAUDE.md## 项目概述[一句话描述]+[技术栈]## 常用命令-开发:`pnpm dev`-构建:`pnpm build`-测试:`pnpm test`-Lint:`pnpm lint`## 代码规范-[你最重要的2-3条规范，附反例]-例：使用具名导出，不用默认导出✗`export default`✓`export const`## 架构约束-[非显而易见的设计决策]-例：API 路由不直接访问数据库，必须通过 service 层## 禁止事项-不要修改`config/production.ts`-不要在没有测试的情况下修改认证逻辑-不要使用`any`类型
2.5 团队协作
把 CLAUDE.md 当基础设施对待，不是个人偏好：
- 项目级 CLAUDE.md 提交到 git，团队共同维护
- 用 PR review 的标准审查 CLAUDE.md 的变更
- monorepo 中，根目录放通用规范，子目录放领域规则
- 定期清理过时的规则，防止规则膨胀
第三部分：上下文管理 — 最被低估的核心技能
上下文窗口不是被动存储，而是主动工作内存。管理不好，Claude Code 就像一个记忆力越来越差的同事。
3.1 核心认知
- Claude Code 的上下文窗口约 200K tokens（Opus 4.6 为 1M）
- 上下文不是越多越好 — 信号被噪音稀释后，模型看到更多东西，但不一定更清楚下一步该做什么
- Compact 不是紧急措施，而是常规操作 — 它是系统的”呼吸”
3.2 Token 节约实战
读文件：
- 用
--lines读特定范围，不要读整个文件 - 用 grep 搜索（约 200 tokens）代替全文件读取（约 3000 tokens）
- 不要重复读已经在上下文中的文件
写 prompt：
- 精炼的 20 词 prompt 比 150 词的段落效果更好
- 把相关修改合并成一个请求，避免多轮交互累积 token
- 把冗长的命令输出重定向到文件，只读相关部分
Plan 模式：
- 用
Shift+Tab激活，把思考和执行分开 - 涉及 3+ 文件的复杂重构，Plan 模式可节省约 40% token
- 让 Claude 先研究代码库，你批准方案后再动手
3.3 Compact 策略
- 上下文填充到 60% 时开始关注，80% 时触发 compact
- 手动 compact（
/compact）比自动 compact 更可控 - compact 前添加总结消息，帮助保留关键上下文
- 用 PreCompact hooks 导出会话状态到外部日志
长会话结构：
30分钟工作冲刺→/compact →30分钟工作冲刺→/compact →...
这种节奏可以维持 4+ 小时的高效会话。每次 compact 前，把当前进度和下一步计划写入会话，确保 compact 后能无缝继续。
3.4 多会话扩展
- 每个功能域一个会话（后端、前端、测试）
- 通过
.claude/shared-context.md共享决策 - 用 Git worktree 隔离并行会话的分支
- 会话结束前导出状态到
.claude/session-handoff.md
3.5 上下文治理的三条路（来自书中的洞察）
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
避免第三条路。”信息更丰富”不等于”工作更有效”。
第四部分：工具、权限与安全 — 能力越大，约束越细
4.1 理解工具的本质
在 Claude Code 的世界里，工具不是”能力的延伸”，而是”需要被管理的执行接口”。一旦模型能碰 shell、文件系统、Git 和网络，问题就从”它说得对不对”变成”它做的事有没有后果”。
Claude Code 对工具的治理逻辑：
- 执行前有权限检查
- 执行中有监控和中断能力
- 执行后有结果修正和失败补偿
- 并行执行时，上下文修改按原始顺序回放，保证因果一致性
4.2 Bash — 最危险的工具
Claude Code 对 Bash 有近乎偏执的约束，这不是过度谨慎，而是事故经验的结晶：
|
|
|
|---|---|
git add.
git add-A |
|
--no-verify
|
|
--amend |
|
|
|
|
|
|
|
git reset--hard |
|
rm-rf
|
|
实用建议：对高风险操作保持”确认优先”的习惯。暂停确认的成本很低，误操作的成本可能很高。
4.3 权限配置
在 settings.json 中配置权限策略：
- 严格模式（生产环境）：所有写操作需要确认
- 宽松模式（原型开发）：信任常见操作，只拦截高风险
- 自定义：通过
allowedTools精细控制
{"permissions":{"allow":["Read","Glob","Grep","Write","Edit"],"deny":["Bash(rm -rf *)"]}}
不要使用 dangerously-skip-permissions。如果你觉得权限检查太烦，说明你应该配置 allowedTools，而不是关掉安全网。
第五部分：Hooks — 把规则变成自动执行的纪律
5.1 什么是 Hooks
Hooks 是在特定时机自动执行的 shell 命令。和 prompt 指令不同，hooks 是机械执行的 — 不依赖模型的”理解”和”遵守”。
三种时机：
- PreToolUse：工具执行前（验证、拦截）
- PostToolUse：工具执行后（格式化、lint、类型检查）
- Stop：会话结束时（最终验证）
5.2 推荐的 Hook 配置
编辑后自动格式化 + lint：
{"hooks":{"PostToolUse":[{"matcher":"Write|Edit","command":"pnpm prettier --write \"$FILE_PATH\"","description":"Format edited files"},{"matcher":"Write|Edit","command":"pnpm eslint --fix \"$FILE_PATH\"","description":"Lint edited files"}]}}
文件大小守卫（防止生成过大的文件）：
{"hooks":{"PreToolUse":[{"matcher":"Write","command":"检查文件行数，超过 800 行则阻止写入","description":"Block oversized writes"}]}}
5.3 Hook 使用原则
- Hooks 应该在基线治理稳定后再引入，不要一开始就堆
- 推荐顺序：格式化 → lint → 类型检查 → 构建验证
- 机械规则放 hooks，需要判断力的规则放 CLAUDE.md
- hooks 的输出打印到 STDOUT，不要打印到
/dev/tty
第六部分：Skills — 把经验变成可复用的工作流
6.1 Skills 是什么
Skills 是存储在 .claude/skills/ 中的 markdown 文件，封装了特定领域的专业知识和工作流程。它们在上下文匹配时自动加载，避免每次会话重复说明。
6.2 何时创建 Skill
- 你发现自己在不同会话中重复给出相同的指令
- 某个工作流有固定的步骤和检查清单
- 团队需要统一某类任务的执行标准
6.3 Skill 编写原则
---name:my-skilldescription:一句话描述，用于判断何时加载---## 何时使用[触发条件]## 步骤1.[具体步骤]2.[具体步骤]## 检查清单-[][验证项]
- 每个 skill 聚焦一个职责
- 描述要具体，让系统能准确判断何时加载
- 包含明确的完成定义（Definition of Done）
- 通过
npx skills find[关键词]搜索社区 skill，避免重复造轮子
6.4 推荐安装的社区 Skills
|
|
|
|
|---|---|---|
anthropics/skills@pdf |
|
npx skills add anthropics/skills@pdf-g-y |
anthropics/skills@frontend-design |
|
npx skills add anthropics/skills@frontend-design-g-y |
更多 skill 可在 skills.sh 浏览。
第七部分：多 Agent 与子 Agent — 分而治之
7.1 为什么需要多 Agent
单 Agent 在简单任务上够用，但当任务变大时，研究、实现、验证被挤在同一个上下文链里，竞争预算和注意力。多 Agent 的价值不是”更多人手”，而是分割不确定性。
Anthropic 的研究表明：Opus 4 作为主导 + Sonnet 4 子 Agent 的多 Agent 系统，在复杂研究任务上比单个 Opus 4 高出 90.2%。
7.2 子 Agent 使用原则
何时用子 Agent：
- 独立的研究任务（搜索代码、读文档）
- 可并行的实现任务（不同模块、不同文件）
- 需要独立视角的验证任务
何时不用：
- 任务之间有强依赖
- 需要共享可变状态
- 简单到一个 Agent 就能搞定
7.3 子 Agent Prompt 编写
像给一个刚进门的聪明同事做 briefing：
- 解释你要完成什么、为什么
- 描述你已经了解或排除了什么
- 给足周围问题的上下文，让它能做判断而不是机械执行
- 如果需要简短回复，明确说
错误：基于你的发现，修复这个 bug正确：在 src/auth/login.ts:45处，JWT 验证在 token 过期时抛出未捕获异常。请添加try-catch并返回401状态码。
7.4 并行执行模式
主Agent├──子Agent1:安全分析 auth 模块├──子Agent2:性能审查 cache 系统└──子Agent3:工具类型检查
- 只对不相交的工作并行 — 不同模块、不同文件
- 用 Git worktree 隔离并行 Agent 的工作空间
- 父级中止时子级也要中止（防止孤儿任务）
7.5 验证必须独立
这是书中反复强调的核心原则：
实现者天然过度信任自己的改动，模型更是如此。同一个 Agent 写代码又验证代码，等于自己批改自己的作业。
实践方法：
- 写代码的 Agent 和跑测试的 Agent 分开
- 用 code-reviewer Agent 做独立审查
- 验证阶段不要只问”通过了吗”，要问”为什么通过了”
第八部分：错误恢复 — 失败是常态，不是意外
8.1 认知转变
大多数系统把失败当异常处理。Claude Code 把失败当主路径设计。在长会话中，以下情况是”日常天气”：
prompt-too-long：上下文超限max-output-tokens：输出被截断- 工具被中断
- Hook 创建死循环
- Compact 自身失败
8.2 系统如何恢复（了解这些帮你配合系统）
prompt-too-long：
- 先尝试低成本恢复 — 清理已知积压（context collapse）
- 不够再做完整 compact（reactive compact）
- 已经尝试过 compact 的同类失败不会盲目重试
- 实在不行，直接报错并跳过 stop hooks（防止死循环）
max-output-tokens：
- 先提高 token 上限重试
- 不行就追加”从截断处继续”的指令 — 不道歉、不回顾、不写客套话
- 每次截断回顾都在烧预算和增加语义漂移
compact 失败：
- 有熔断机制（circuit breaker），连续失败超过阈值就停止重试
- compact 请求本身也可能触发 prompt-too-long — 系统会从头部截断历史重试
8.3 你能做什么
- 看到上下文快满时，主动
/compact而不是等系统被迫处理 - 输出被截断时，说”继续”而不是”重新开始”
- 遇到反复失败时，开新会话比死磕更高效
- 会话行为漂移时，果断重启 — 这不是浪费，是止损
第九部分：团队落地 — 从个人技巧到组织能力
9.1 核心原则
专家可以凭经验驯服 Agent，但团队不能依赖这个。个人技巧必须制度化，Agent 系统才能成为组织能力而非个人手艺。
9.2 落地顺序
- 先定边界再推广 — 定义可接受的使用范围
- 先统一验证定义再增加 skill 数量 — 验证标准比工具数量重要
- 用 review、CI 和少量稳定的指令文件打底 — 再加 hooks 和编排
- 审批按风险分级 — 不要粗暴地按工具名称分类
- 每条自动化路径都要可解释 — 但不要从第一天就要求完整审计
- hooks 在后期引入 — 基线治理稳定后再加
9.3 团队配置清单
必须有的：
-
项目级 CLAUDE.md，提交到 git
统一的构建/测试/lint 命令
共享的 skills 库（
.claude/skills/）PostToolUse hooks 做格式化和 lint
CI/CD 中集成 Claude Code 做 PR review
进阶的：
-
分层 CLAUDE.md（根目录 + 子目录）
自定义 slash commands 标准化常见操作
PreCompact hooks 导出会话状态
多 Agent 编排模式（orchestrator + specialists）
会话记录和回放机制
9.4 采用策略
- 从结对编程会话开始，让团队成员观察 Claude Code 的行为
- 建立 Claude Code 输出的 code review 规范
- 创建 onboarding checklist
- 度量使用模式，迭代改进配置
第十部分：十大原则速查
从两本书和社区实践中提炼的核心原则，贴在显示器旁边：
- 模型是不稳定组件，不是队友 — 越早承认，系统越早长出安全网
- Prompt 是控制平面 — 写约束，不写人设
- 查询循环是心跳 — 理解它，才能配合它
- 工具是受管理的接口 — 越危险的工具，越需要细粒度约束
- 上下文是工作内存 — 管理它，不要塞满它
- 错误路径是主路径 — 为失败设计，不是为失败道歉
- 恢复优先保证继续 — 截断后继续，不要回顾
- 多 Agent 分割不确定性 — 不是更多人手，是更清晰的责任
- 验证必须独立 — 自己批改自己的作业不算验证
- 团队制度 > 个人技巧 — 制度化才能规模化
第十一部分：日常工作流速查表
开始新任务
1.确认 CLAUDE.md 是最新的2.用Plan模式让Claude先研究代码库3.审批方案后再动手4.复杂任务拆分为子Agent并行执行
长会话管理
1.每30分钟/compact 一次2.上下文60%时开始关注3. compact 前写一句当前进度总结4.行为漂移时果断开新会话
提交前检查
1.运行测试，不要只问Claude"测试通过了吗"2.用独立的 code-reviewer Agent审查3. git diff 确认改动范围符合预期4.不要 git add .—逐文件添加
遇到问题时
1.先诊断，再换策略—不要盲目重试2.读错误信息，检查假设3.反复失败→开新会话4.不要用破坏性操作走捷径（--no-verify, reset --hard）
参考资源
书籍：
- Harness Engineering: A Design Guide to Claude Code
https://harness-books.agentway.dev/book1-claude-code - The Harness Design Philosophies of Claude Code and Codex
https://harness-books.agentway.dev/book2-comparing
社区指南：
- 25 Things I Learned Using Claude Code Every Day
https://g.money/blog/25-things-claude-code/
- CLAUDE.md Complete Guide (2026)
https://www.shareuhack.com/en/posts/claude-code-claude-md-setup-guide-2026
- Context Management Tips
https://institute.sfeir.com/en/claude-code/claude-code-context-management/tips/
- Context Management Optimization
https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/
- Claude Code for Teams Setup Guide
https://www.ayautomate.com/blog/claude-code-for-teams
- Claude Code Automations Complete Guide
https://www.theneuron.ai/explainer-articles/claude-code-automations-complete-guide/
- Best Practices for Claude Code Subagents
https://pubnub.com/blog/best-practices-for-claude-code-sub-agents
- How to Write a CLAUDE.md That Actually Works
https://www.turbodocx.com/blog/how-to-write-claude-md-best-practices
- Claude Code Advanced Patterns (Anthropic Webinar)
https://www.anthropic.com/webinars/claude-code-advanced-patterns
- Skills 生态
https://skills.sh/
订阅智宅客
AI / 技术 / 数字生活方式，新文章第一时间送到邮箱。
