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 跑偏的坑。

text 复制代码

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

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

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. 项目定位

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

md 复制代码

## 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 命令。明确写出来。

md 复制代码

## Core Commands

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

3. 工作流约束

md 复制代码

## 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 里最容易被忽略但最值钱的部分。

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. 交付标准

md 复制代码

## 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 在系统里的位置

text 复制代码

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

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

六、单仓库项目怎么写

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

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 一进来就加载了太多对当前任务无关的信息。这时最好的做法是分层写。

text 复制代码

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。

十、起步模板

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

md 复制代码

# 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 如何分层。