书籍 / Claude 完全指南：从 API 到 Agent 生产实战
第 41 章

斜杠命令完全参考：内置命令 + Bundled Skills 的全部用法

第四十一章：CLAUDE.md 工程化：项目规范、记忆系统与 Agent 指令设计

41.1 CLAUDE.md 的本质：不只是说明文档

每次你在终端输入 claude 启动 Claude Code，它做的第一件事不是等待你的输入，而是寻找并读取 CLAUDE.md 文件。这个文件决定了 Claude 在这个项目中的行为方式、技术偏好、禁止操作和工作风格。

CLAUDE.md 不是给人类读者准备的 README，而是专门为 AI Agent 设计的运行时指令文档。它的内容直接注入到每次会话的系统提示中，影响 Claude 的每一个决策。

这种设计产生了一个非常重要的结果：你可以把团队对代码质量、架构风格和工作流程的所有共识，编码进这个文件，让 Claude 的行为自动符合团队规范。

CLAUDE.md 的加载机制

Claude Code 按照以下优先级查找和加载 CLAUDE.md：

加载顺序（从高到低优先级）：

1. ~/.claude/CLAUDE.md          —— 用户全局配置（个人偏好）
2. <项目根目录>/CLAUDE.md        —— 项目根级配置（主要配置）
3. <当前子目录>/CLAUDE.md        —— 子目录局部配置（模块专属规则）

当你在 src/backend/ 目录下工作时，Claude 会同时读取根目录和 src/backend/ 下的 CLAUDE.md，并将两者合并。这让你可以在 monorepo 中为每个子包设置独立规则，同时保持全局规范。

全局配置 ~/.claude/CLAUDE.md 适合放个人工作偏好，例如代码风格倾向、常用工具链、个人 API 密钥规则。项目级 CLAUDE.md 适合放团队共享的项目规范，应该提交到版本控制。

文件大小与性能的权衡

CLAUDE.md 的内容被加载到上下文窗口中。过长的 CLAUDE.md 会占用宝贵的 token 空间，在长对话中可能导致重要信息被截断。

实践经验表明，项目级 CLAUDE.md 的合理长度是 200-500 行。超过这个范围，考虑使用 @import 机制将内容拆分到专项文件中（详见 41.3 节）。

41.2 CLAUDE.md 的结构化设计

一个高质量的 CLAUDE.md 不是随意堆砌的笔记，而是有清晰结构的工程文档。以下是一个经过实践验证的结构模板：

# 项目名称 —— Claude 工作指南

## 项目概述
[项目一句话描述、技术栈、架构风格]

## 快速上下文
[让 Claude 快速理解项目状态的关键信息]

## 技术规范
### 语言与框架
### 代码风格
### 测试要求

## 工作流程
### 开发流程
### 提交规范
### Review 标准

## 关键约束
### 禁止操作
### 安全规则

## 常用命令
[项目特定的 npm/make/cargo 命令]

## 架构指南
[核心模块说明、重要数据流]

下面用一个真实的 TypeScript 全栈项目展示完整填充后的效果：

# YiteAI Tools —— Claude 工作指南

## 项目概述
基于 Next.js 14 App Router 的 SaaS 工具集合平台。
技术栈：TypeScript + Next.js + Prisma + PostgreSQL + Tailwind CSS
架构：monorepo（pnpm workspaces），apps/web + packages/ui + packages/db

## 快速上下文
- 主要业务逻辑在 apps/web/src/app/（App Router）
- 数据库模型在 packages/db/schema.prisma
- 共享 UI 组件在 packages/ui/src/components/
- 环境变量模板在 .env.example，实际值在 .env.local（不提交）

## 技术规范

### 代码风格
- TypeScript strict mode，所有函数必须有明确返回类型
- 使用 Zod 做运行时类型验证，尤其是 API 输入
- Server Actions 优先于 API Routes（减少网络往返）
- 组件文件名用 PascalCase，工具函数文件名用 camelCase

### 错误处理
- 服务端使用 Result<T, E> 模式，不抛裸 Error
- 客户端使用 React Error Boundary + toast 通知用户
- 所有数据库操作必须在 try/catch 中，记录 structured log

### 测试要求
- 纯函数必须有单元测试（Vitest）
- API Routes 必须有集成测试
- 覆盖率目标：语句 80%，分支 70%

## 工作流程

### 提交规范
遵循 Conventional Commits：
- feat: 新功能
- fix: 修复 bug
- refactor: 重构（无功能变化）
- test: 测试相关
- docs: 文档
禁止 `git commit -m "update"` 等无意义提交信息

### 禁止操作
- 不得直接修改 packages/db/migrations/（只通过 prisma migrate dev）
- 不得在组件中直接调用 fetch，必须通过 Server Actions 或 hooks
- 不得在 .env.local 中硬编码生产密钥
- 不得使用 any 类型，除非有注释说明原因

## 常用命令
\`\`\`bash
pnpm dev              # 启动开发服务器
pnpm build            # 生产构建
pnpm test             # 运行测试
pnpm db:push          # 推送 schema 变更（开发环境）
pnpm db:migrate       # 生成迁移文件
pnpm lint             # ESLint + Prettier 检查
\`\`\`

## 架构注意事项
- 认证使用 NextAuth v5，session 在 middleware 中验证
- 文件上传使用 UploadThing，大文件分片
- 邮件发送使用 Resend，模板在 packages/emails/
- 支付走 Stripe Webhooks，事件处理在 app/api/webhooks/stripe/

这个示例展示了 CLAUDE.md 的几个关键要素：它告诉 Claude 在哪里找东西、用什么模式做事、什么是被禁止的。有了这些信息，Claude 在修改代码时能主动遵守规范，而不需要你每次都重复说明。

41.3 @import 语法：模块化管理记忆

当项目复杂度增加，单一 CLAUDE.md 文件会变得难以维护。Claude Code 提供了 @import 语法，允许你将不同主题的内容拆分到独立文件中：

# 主 CLAUDE.md

## 核心规范
@import docs/claude/tech-stack.md
@import docs/claude/code-style.md

## 工作流程
@import docs/claude/workflow.md

## 架构文档
@import docs/claude/architecture.md

@import 的路径是相对于当前 CLAUDE.md 文件的位置。被导入的文件内容会在加载时展开，对 Claude 来说和直接写在 CLAUDE.md 里效果相同。

@import 的设计哲学

@import 的核心价值不只是拆分文件，而是按需加载。你可以这样设计：

项目根目录/
├── CLAUDE.md                    # 主入口，只导入核心内容
└── docs/
    └── claude/
        ├── tech-stack.md        # 技术栈详解（始终导入）
        ├── api-design.md        # API 设计规范（API 工作时导入）
        ├── db-patterns.md       # 数据库模式（数据库工作时导入）
        ├── frontend-rules.md    # 前端规范（前端工作时导入）
        └── security.md          # 安全规则（始终导入）

主 CLAUDE.md 始终导入核心必要内容，子目录的 CLAUDE.md 导入模块专属内容：

# src/api/CLAUDE.md
（此目录的 API 开发规范）

@import ../../docs/claude/api-design.md
@import ../../docs/claude/security.md

## 本目录专属规则
- 所有端点必须在 openapi.yaml 中记录
- 响应格式统一使用 { data, error, meta } 结构

动态上下文注入

@import 最强大的用法之一是导入自动生成的文件。例如，你可以在 CI 中生成一个列出当前 API 端点的文档，然后在 CLAUDE.md 中导入它：

## 当前 API 状态
@import .claude/generated/api-endpoints.md

配合一个小脚本，每次构建后自动更新这个文件，就实现了"Claude 始终了解当前 API 全貌"的效果。

41.4 记忆系统的三种类型

在使用 Claude Code 的过程中，"记忆"这个概念有三个完全不同的含义，混淆它们会导致很多困惑：

类型一：上下文记忆（Context Memory）

这是 Claude 在单次会话中能看到的所有内容：CLAUDE.md 的内容、当前对话历史、你读入的文件内容。这种记忆随会话结束而消失。

上下文记忆的容量是有限的（Claude 3.5 Sonnet 的上下文窗口约 200K tokens），但在窗口内它是完全可靠的——Claude 能精确引用任何位置的内容。

工程含义：CLAUDE.md 是把持久知识注入上下文记忆的主要机制。

类型二：文件记忆（File Memory）

当你让 Claude 把某个决策或发现写入文件时，这个信息就持久化了。下次会话中，你或 Claude 可以重新读取这个文件，把信息带回上下文。

Claude Code 的 Read, Write, Edit 工具赋予了 Claude 直接操作文件系统的能力，使得"写入文件 = 创建持久记忆"成为可能。

工程实践：在项目中创建 .claude/memory/ 目录，专门存放 Claude 生成的记忆文件：

.claude/
├── memory/
│   ├── architecture-decisions.md   # 架构决策记录
│   ├── known-issues.md             # 已知问题和临时解决方案
│   ├── session-notes.md            # 跨会话的工作笔记
│   └── investigation-log.md        # 调查过的问题记录
└── settings.json                   # Claude Code 配置

在 CLAUDE.md 中导入这些记忆文件，确保每次会话都能读取历史信息：

## 项目记忆
@import .claude/memory/architecture-decisions.md
@import .claude/memory/known-issues.md

类型三：训练记忆（Training Memory）

这是 Claude 模型在预训练阶段获得的知识——关于编程语言、框架、算法、最佳实践的通用知识。这种记忆不受 CLAUDE.md 影响，是恒定的背景知识。

工程含义：不需要在 CLAUDE.md 中解释 Python 的语法或 React 的工作原理，Claude 已经知道了。CLAUDE.md 应该专注于项目特有的信息，训练记忆中没有的内容。

三种记忆的协同

训练记忆（模型权重）
    ↓ 提供通用技术知识
上下文记忆（CLAUDE.md + 对话）
    ↓ 提供项目规范和当前任务
文件记忆（.claude/memory/）
    ↓ 提供历史决策和积累知识
─────────────────────────────
Claude 的实际行为 = 三层记忆的综合

41.5 Agent 指令设计原则

CLAUDE.md 的核心是"Agent 指令"——你希望 Claude 遵循的行为规范。写好这些指令需要理解 AI Agent 的工作方式。

原则一：具体优于抽象

差的指令：

写高质量的代码。

好的指令：

每个函数不超过 40 行；提取超过 3 次的重复代码为工具函数；
复杂逻辑必须有行内注释说明 "为什么"（不是 "是什么"）。

抽象指令对 Claude 来说信息量接近零。Claude 对"高质量"的理解可能和你完全不同。具体指令消除了歧义，直接约束了行为。

原则二：禁止操作比允许操作更重要

Claude 会尽力完成任务，有时它认为合理的做法恰好是你不想要的。明确列出禁止操作，可以防止 Claude 在不理解业务背景的情况下做出错误决策：

## 禁止操作（Claude 不得执行以下行为）

- 不得删除或重命名现有数据库列（只能添加新列）
- 不得修改 packages/contracts/ 中的接口定义（这是外部 API 契约）
- 不得在未运行测试的情况下提交代码
- 不得使用 console.log 做生产日志（必须用 logger 模块）
- 不得向外部 URL 发送用户数据，包括日志服务

原则三：提供判断标准，而非仅列规则

规则无法覆盖所有情况。更好的方式是给 Claude 提供做判断的框架：

## 变更影响评估

在做任何代码变更前，评估以下维度：
1. 是否影响数据库 Schema？如果是，需要迁移文件
2. 是否影响外部 API 接口？如果是，需要版本协商
3. 是否影响认证流程？如果是，需要安全审查
4. 是否影响性能关键路径？如果是，需要性能测试

如果对以上任何一点不确定，先询问，不要假设。

原则四：写明 Claude 应该主动做什么

CLAUDE.md 不只是约束，也可以是赋能——告诉 Claude 它有权主动执行哪些操作：

## Claude 的主动权限

Claude 可以在以下情况下主动执行，无需询问：
- 修复 ESLint/TypeScript 报错
- 添加 JSDoc 注释到缺少文档的导出函数
- 将重复代码提取为工具函数（如果被使用超过 3 次）
- 更新快照测试（运行 `pnpm test --updateSnapshot`）

Claude 必须在以下情况下先询问，不得主动执行：
- 修改数据库 Schema
- 更改 API 端点路径或请求格式
- 升级主要依赖版本
- 删除文件或大段代码

这种区分让 Claude 能够高效自主地处理低风险操作，同时在高风险操作上保持谨慎。

41.6 多 CLAUDE.md 的 Monorepo 策略

在包含多个子项目的 Monorepo 中，CLAUDE.md 的层级设计尤为重要：

monorepo/
├── CLAUDE.md                    # 全局规范：git 工作流、提交规范、全局禁止操作
├── apps/
│   ├── web/
│   │   └── CLAUDE.md           # Next.js 前端规范：组件风格、状态管理
│   └── api/
│       └── CLAUDE.md           # FastAPI 后端规范：端点设计、错误处理
└── packages/
    ├── ui/
    │   └── CLAUDE.md           # 组件库规范：设计系统、无障碍要求
    └── shared/
        └── CLAUDE.md           # 共享工具库规范：纯函数要求、无副作用

全局 CLAUDE.md 应包含：

子目录 CLAUDE.md 应包含：

41.7 CLAUDE.md 的版本控制最佳实践

CLAUDE.md 应该像代码一样被认真对待：

提交规范

# 使用专门的 commit 类型标识 CLAUDE.md 变更
git commit -m "claude: add API versioning guidelines to CLAUDE.md"
git commit -m "claude: update forbidden operations list"
git commit -m "claude: import new architecture decision record"

Code Review

CLAUDE.md 的变更应该经过团队 Review，因为它直接影响所有成员使用 Claude Code 的体验。特别注意：

迭代改进

CLAUDE.md 不是一次写完的，而是在使用中持续迭代的：

发现问题 → 分析根因（是 Claude 不知道规则，还是规则本身不够清晰）
    ↓
更新 CLAUDE.md → 在下次会话中验证效果
    ↓
观察 Claude 是否自动遵守 → 如果没有，继续细化规则

保持一个 CLAUDE.md.changelog 或在文件头部记录变更历史，有助于理解规则演变：

<!-- CHANGELOG
2024-03-15: 添加 Zod 验证要求（因为 Claude 生成了未验证的 API 输入处理代码）
2024-03-22: 细化禁止操作列表（增加数据库迁移规则）
2024-04-01: 导入架构决策文档
-->

小结

CLAUDE.md 是 Claude Code 工程化使用的核心杠杆点。一个精心设计的 CLAUDE.md 能将 Claude 从一个"聪明的通用助手"变成"深度了解你项目的专业队友"。

关键要点：

本章评分
4.9  / 5  (3 评分)

💬 留言讨论