# Writing a Good CLAUDE.md

> 原文链接：https://www.humanlayer.dev/blog/writing-a-good-claude-md
> 作者/来源：Kyle / HumanLayer
> 阅读日期：2026-04-02

## 一句话总结
`CLAUDE.md` 是 agent harness 中杠杆率最高的配置点，因为它出现在每一个 agent 会话中；编写时应遵循"少即是多"原则，聚焦于 WHAT/WHY/HOW 三个维度，保持简洁并利用 progressive disclosure 管理复杂性。

## 核心论点

文章的核心前提是：LLM 是无状态的（stateless），`CLAUDE.md`（或开源工具中的 `AGENTS.md`）是每次会话中将 agent "onboard" 到你的代码库的唯一持久化通信渠道。因此，它是整个 harness 中杠杆效应最大的单一配置点。

Kyle 提出了三个基础性推论：agent 对你的代码库初始知识为零；关键信息必须在每次会话中被传达；`CLAUDE.md` 是指定的传达载体。基于此，文件内容应覆盖三个维度：**WHAT**（技术栈、项目结构、代码地图）、**WHY**（项目目的、各组件的功能）、**HOW**（工具细节如 bun vs node、验证方法、测试执行方式）。

文章揭示了一个关键问题：Claude 经常忽略 `CLAUDE.md` 中的指令。这是因为 Anthropic 在系统提示中注入了"此 context 可能与你的任务相关也可能不相关"的提示，导致 Claude 会降低非通用指令的优先级。作者指出，这很可能是因为太多用户把 `CLAUDE.md` 当成"热修复仓库"而非 onboarding 文档来使用。

## 关键概念
- **Harness 的最高杠杆点**：`CLAUDE.md` 因其在每次 agent 会话中的必然出现而成为影响 agent 行为最重要的配置文件
- **指令容量上限**：研究表明前沿 LLM 能可靠遵循大约 150-200 条指令，而 Claude Code 的系统提示已经占用了约 50 条，留给用户的空间有限
- **Progressive Disclosure（渐进式披露）**：不把所有信息塞入一个文件，而是创建 `agent_docs/` 目录下的专题文件（building、testing、conventions、architecture、schema），在 `CLAUDE.md` 中用 `file:line` 指针引用
- **确定性工具 vs LLM**：代码风格检查应交给 linter（如 Biome），而不是浪费 LLM 的 token 和推理能力

## 实践建议
1. **保持文件简短**：根文件控制在 300 行以内，HumanLayer 自己的根文件不到 60 行，只包含普遍适用的内容
2. **不要放代码风格指南**：使用 Biome 等 linter 的 auto-fix 功能，通过 Claude Code Stop hooks 或 Slash Commands 处理格式问题
3. **不要自动生成**：手动精心策划每一行内容，因为坏指令会在规划和实现阶段产生指数级的错误放大
4. **使用 progressive disclosure**：将详细文档放在 `agent_docs/` 子目录中，`CLAUDE.md` 只包含全局性的简要信息和指向详细文档的引用
5. **覆盖 WHY/WHAT/HOW**：不仅告诉 agent 代码结构（what），还要解释为什么这样设计（why），以及如何验证和测试（how）

## 独到观点
文章最独到的观点是关于 LLM 的"指令容量"概念——前沿模型能可靠遵循的指令数量是有限的（约 150-200 条），而系统提示已经占用了约三分之一。这意味着 `CLAUDE.md` 不是一个可以无限堆砌指令的地方，而是一个需要精心分配"指令预算"的稀缺资源。此外，关于 Claude 因系统提示注入而忽略用户配置的观察，为理解 agent 行为提供了重要的内部视角。

## 与其他文章的关联
- 与 **HumanLayer Backpressure**（#13）直接相关：backpressure wrapper 函数应该被配置在 `CLAUDE.md` 的 HOW 部分中
- 与 **Claude Code Best Practices**（#23）互补：官方最佳实践提供了 `CLAUDE.md` 的基础框架，而本文提供了更深入的策略性思考
- 与 **Anthropic Writing Tools for Agents**（#18）关联：工具的使用说明也需要在 `CLAUDE.md` 中以简洁的方式呈现
- 与 **OpenHands Context Condensation**（#14）理念一致：都在强调"context 是稀缺资源"这一核心原则
- 与 **Fowler Anchoring to Reference**（#21）相关：`CLAUDE.md` 中的 WHAT 部分可以作为 agent 理解代码结构的参考锚点