Claude Code Harness 04：写好 CLAUDE.mdCLAUDE.md 是 Claude Code 进

Claude Code Harness 04：写好 CLAUDE.md

CLAUDE.md 是 Claude Code 进入项目后读到的第一份工作说明。写得好，它会更快进入正确工作模式、更少做无关探索、更少在构建和测试命令上来回猜、更少在基本边界上跑偏。写得差，它会变成另一种系统负担——越写越长、越长越像什么都重要、最后 Claude 读了但没被约束住。

核心问题不是"里面要写哪些内容"，而是：什么样的 CLAUDE.md 能让 Claude Code 在项目里稳定工作。

一、角色定位：项目级工作说明，不是知识库

如果把 CLAUDE.md 当知识库写，最后会变成一本项目百科——架构背景、历史沿革、团队习惯、业务规则、API 说明、部署流程、未来规划全塞进去。看起来很认真，实际很危险。

对 Claude Code 来说，CLAUDE.md 是一进项目就要读、并且会持续影响行为的高优先级上下文。它最适合承担的职责是：这个项目是什么、重要目录和入口在哪、build/test/lint/typecheck 怎么跑、复杂任务默认怎么开始、哪些边界不能碰、当前项目里最容易让 Claude 跑偏的坑。

CLAUDE.md ≠ 项目百科 ≠ 所有知识的总和
CLAUDE.md = 项目级工作说明 = 高优先级运行规则 = 进入项目后的第一张工作卡片

二、反例：一份坏掉的 CLAUDE.md

# Project Guide

This is a next-generation full-stack platform for managing users, billing,
notifications, content workflows, analytics pipelines, AI research, data sync,
growth experiments, and internal tooling.

## Coding Style

Always write clean code.
Prefer maintainability.
Avoid unnecessary duplication.
Use good naming.
Keep things modular.
Think carefully.
Be professional.

## Important

Never break anything.
Always test thoroughly.
Check for edge cases.
Make sure the user is happy.

问题在三个地方。

全是正确的废话。 "write clean code"、"think carefully"、"never break anything"——Claude 本来就默认知道这些泛原则，重复一遍只占上下文，不带来额外约束。

没有项目级高价值信息。 Claude 最需要的——项目入口在哪、常用命令是什么、哪些目录是主路径哪些是遗留路径、哪些文件不能乱改——全没写。它只能靠猜，探索成本和跑偏概率同时上升。

没有优先级。 所有内容平铺，Claude 看完不清楚哪条是硬约束、哪条只是背景介绍。信息很多，行动很弱。

三、好 CLAUDE.md 的判断标准

判断一份 CLAUDE.md 写得好不好，看三个标准。

能让 Claude 更快进入正确上下文。 一进项目就知道这是什么项目、入口在哪、基本命令怎么跑。

能减少无效探索。 不用反复找测试命令、不用猜主要模块在哪、不用推断代码风格底线。

能压住最常见的偏航。 哪些事情不要做、什么情况必须先 plan、哪些改动不能顺手扩大、什么算完成。

一份有用的 CLAUDE.md 核心能力不是"解释世界"，而是让 Claude Code 更少猜、更少漂、更少做无关动作。

四、推荐的内容结构

第一版 CLAUDE.md 用五个模块。

1. 项目定位

一句话说明项目是什么、技术栈、主要入口。

## Project Overview

This is a Next.js + TypeScript web application.
The main app lives under `apps/web`.
Shared domain logic lives under `packages/core`.

2. 常用命令

Claude Code 最常反复猜的就是启动、测试、lint、typecheck 命令。明确写出来。

## Core Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Build: `pnpm build`

3. 工作流约束

## Workflow Rules

- For multi-file or ambiguous tasks, start with a plan before editing code.
- For bug fixes and new features, prefer test-first changes.
- Do not widen scope without explicit confirmation.
- Do not claim completion before running verification.

4. 项目特有的坑

CLAUDE.md 里最容易被忽略但最值钱的部分。

## Project-Specific Gotchas

- `packages/generated/` contains generated files. Do not edit manually.
- `legacy-auth/` is still in production use. Avoid refactoring unless explicitly required.
- Full E2E suite is slow; use targeted tests first, then run full suite before merge.

5. 交付标准

## Definition of Done

- Relevant tests pass
- Typecheck passes
- No new lint issues introduced
- Changes stay within confirmed scope
- Summary includes what changed, what was verified, and what remains risky

五块加起来并不长，但对 Claude Code 的帮助远大于一堆"请写优雅代码"的空话。

五、CLAUDE.md 在系统里的位置

Claude Code Work System
│
├── CLAUDE.md ← 项目级总说明
│
├── rules/    ← 长期约束
├── commands/ ← 高频入口
├── skills/   ← 按需方法论
├── hooks/    ← 自动化治理
└── session summaries / memory ← 长会话延续

CLAUDE.md 是总说明，但不是一切。它适合放"高优先级、项目级、启动即需要知道"的东西。如果发现自己正在把某个复杂 workflow 全塞进 CLAUDE.md，很大概率已经放错地方了。

六、单仓库项目怎么写

单应用仓库（一个前端项目、一个 API 服务、一个常规全栈项目）的 CLAUDE.md 应该非常克制。直接参考这个模板：

# CLAUDE.md

## Project Overview

This is a TypeScript service for payment reconciliation.
Main application code lives under `src/`.
Integration tests live under `tests/integration/`.

## Core Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Build: `pnpm build`

## Workflow Rules

- Start with a plan for multi-file or ambiguous tasks.
- Prefer test-first changes for new features and bug fixes.
- Do not widen scope without explicit confirmation.
- Do not weaken configs to make checks pass.
- Do not claim completion before verification.

## Project-Specific Gotchas

- `src/generated/` is generated code. Do not edit it manually.
- `src/reconciliation/legacy.ts` is still production-critical. Avoid refactoring unless explicitly required.
- Some integration tests require local fixtures under `tests/fixtures/`.

## Definition of Done

- Relevant tests pass
- Typecheck passes
- No new lint issues introduced
- Changes stay within confirmed scope

单仓库项目最重要的是让 Claude 快速进入工作状态，不是读一堆背景历史。

七、Monorepo 怎么写

Monorepo 或多模块仓库里最大的风险不是信息不够，而是 Claude 一进来就加载了太多对当前任务无关的信息。这时最好的做法是分层写。

repo/
├── CLAUDE.md                 # 根目录共享规则和总说明
├── apps/
│   ├── web/
│   │   └── CLAUDE.md         # Web 专属说明
│   └── api/
│       └── CLAUDE.md         # API 专属说明
└── packages/
    └── core/
        └── CLAUDE.md         # Core 包专属说明

根目录放项目总体结构、全局命令、通用规则、各目录职责。子目录放各自的框架特性、测试方式、常见坑、局部工作流。

好处是：Claude 在不同目录工作时能获得更相关的上下文，不会把整个仓库的说明一次性塞进当前任务。根层负责共识，子层负责局部精度。

八、什么时候不该再往 CLAUDE.md 里加内容

下面这些内容不适合继续往 CLAUDE.md 里塞：

某类任务的详细步骤（完整 TDD 教程、code review checklist 全文、大型 refactor 流程）——更适合 skills 或 commands。

很少触发的领域知识（某个三方 SDK 的完整说明、历史迁移方案的长文档）——更适合单独 docs 或 skills。

高频机械动作（编辑后检查 console.log、compact 前保存状态、长命令提醒后台化）——更适合 hooks。

会不断变化的清单型信息（当前任务列表、本周目标、临时 bug 调查状态）——更适合 session summary 或 task system。

如果老想把这些放进 CLAUDE.md，通常说明不是文档不够，而是系统里其他层还没搭出来。

九、放置判断速查

内容	该放哪
"复杂任务先 plan，再实现，再 verify"	CLAUDE.md 作为总规则 + `/plan`、`/verify` 作为具体入口
"TypeScript 文件改完后自动跑 typecheck"	hooks
"`src/generated/` 是生成代码，不要手改"	CLAUDE.md
"怎么做代码审查"	skills + `/review`
"这次任务当前做到哪了"	session summary

核心原则：CLAUDE.md 只放项目级、启动即需要知道、长期稳定有效的信息。超出这个范围，就考虑 rules、skills、commands、hooks 或 session summary。

十、起步模板

可以直接拿去改的起步版：

# CLAUDE.md

## Project Overview

This is a [tech stack] project.
Main code lives under `[main-directory]`.
Tests live under `[test-directory]`.

## Core Commands

- Install: `[install-command]`
- Dev: `[dev-command]`
- Test: `[test-command]`
- Lint: `[lint-command]`
- Typecheck: `[typecheck-command]`
- Build: `[build-command]`

## Workflow Rules

- Start with a plan for multi-file or ambiguous tasks.
- Prefer test-first changes for new features and bug fixes.
- Do not widen scope without explicit confirmation.
- Do not weaken configs to make checks pass.
- Do not claim completion before verification.

## Project-Specific Gotchas

- `[important-path-1]` should not be edited manually.
- `[legacy-area]` should not be refactored unless explicitly required.
- `[slow-test-or-special-setup]`

## Definition of Done

- Relevant tests pass
- Typecheck passes
- No new lint issues introduced
- Changes stay within confirmed scope
- Final summary includes what changed and what was verified

不需要一次写完所有细节。先把项目定位、常用命令、默认流程、项目特有坑、完成标准这五块写出来，就够用了。

十一、小结

CLAUDE.md 不是项目百科，是项目级工作说明。好的 CLAUDE.md 重点不在"更全"，而在"更能驱动正确行动"。一旦想把很多动态、低频、机械或步骤型内容塞进去，通常该去搭别的层了。

下一章继续把分层拆开：Rules、Skills、Commands、Hooks、MCP 如何分层。