Back to notes

Writing a good CLAUDE.md

AI summary · Qwen Summary in Chinese Indexed
Original source

文章建议把 CLAUDE.md 写成简短、通用且高杠杆的项目入门说明，并用渐进披露和确定性工具减少上下文负担。

核心定位

  • 文章认为 LLM 在推理时基本是无状态的，不会随时间学习代码库。
  • CLAUDE.md 或 AGENTS.md 是默认进入每次会话的文件，用于向 Claude 介绍项目。
  • 它应帮助 Claude 了解代码库结构、项目目的和工作方式。

内容框架

  • WHAT：说明技术栈、项目结构、应用和共享包的位置。
  • WHY：说明项目目的以及各部分的作用。
  • HOW：说明如何构建、测试、类型检查、编译或验证改动。

被忽略风险

  • Claude Code 会在用户消息中加入 system-reminder，提示上下文可能不相关。
  • 如果 CLAUDE.md 包含大量不通用指令，Claude 可能判断其不相关而忽略。
  • 文件内容越不普遍适用，被忽略的可能性越高。

少即是多

  • 文章引用研究称前沿思考型 LLM 可较稳定地遵循约 150 到 200 条指令。
  • 指令数量增加时，模型对指令的遵循质量会整体下降。
  • Claude Code 的系统提示约含 50 条指令，因此 CLAUDE.md 应尽量减少指令数量。

长度与适用性

  • 上下文窗口中聚焦且相关的内容通常比大量无关内容更有效。
  • CLAUDE.md 应尽可能通用，避免放入只在特定任务中相关的说明。
  • 文章提到一般共识是少于 300 行较好，HumanLayer 的根文件少于 60 行。

渐进披露

  • 任务或项目特定说明可放在独立 markdown 文件中。
  • CLAUDE.md 可列出这些文件并简述用途，让 Claude 在需要时读取。
  • 优先使用 file:line 指针，而不是容易过时的代码片段。

工具分工

  • 文章反对把 LLM 当作昂贵的 linter 或 formatter。
  • 代码风格应优先交给确定性工具处理。
  • 可用 hooks、slash commands 等方式把实现与格式检查分开。

避免自动生成

  • CLAUDE.md 影响工作流的每个阶段，是高杠杆文件。
  • 文章建议不要依赖 /init 或自动生成功能。
  • 应仔细手工编写每一行，以减少错误被放大。