CLAUDE.md 是 Claude Code 的"系统提示词"——写得好，Agent 像你的10x工程师搭档；写得差，它就是个乱改代码的实习生。本文给你5个可复制的生产级模板，覆盖全栈项目、微服务、数据分析、开源贡献和一人创业项目。

你的Claude Code是不是也这样？

明明说了要用 TypeScript，它偏给你写 JavaScript
让它重构代码，结果把测试全删了
每次新开会话都要重新解释项目架构，烦得要死
生成的代码风格和你项目里现有的完全不一致

这不是 Claude Code 不够聪明——是你的 CLAUDE.md 没写对。

CLAUDE.md 本质上是一个持久化的系统提示词，Claude Code 在每次对话开始时自动加载它。它告诉 Agent：你是谁、项目是什么、规则是什么、偏好是什么。

但 90% 的开发者要么不写 CLAUDE.md，要么只写了一行"这是个 React 项目"。今天我们把它彻底讲透。

CLAUDE.md 为什么是 Claude Code 的第一性配置

在 Claude Code 的配置体系中，有三个层级的"记忆"：

层级	配置方式	生效范围	典型用途
全局	`~/.claude/settings.json`	所有项目	API密钥、全局Hook
项目	`CLAUDE.md`（项目根目录）	当前项目	项目架构、编码规范
会话	对话中的指令	当前会话	临时需求、一次性约束

其中 CLAUDE.md 是投入产出比最高的一项：

写一次，每次对话自动生效
不消耗 context window 中的对话轮次
可以提交到 Git，团队共享

实测数据：一个 200 行的 CLAUDE.md 约消耗 ~500 tokens 的系统提示预算，但它能省掉每轮对话中「解释项目结构」的 200-500 tokens。一天 50 轮对话下来，净省 10,000+ tokens。

CLAUDE.md 的黄金结构

经过大量实战验证，一个高效的 CLAUDE.md 应该包含以下 5 个模块：

# 项目名称（1行）

## 1. 项目概述（3-5句）
- 这个项目做什么
- 技术栈一句话
- 目标用户/使用场景

## 2. 技术架构（10-20行）
- 目录结构概览
- 关键模块和职责
- 数据流/请求流

## 3. 编码规范（10-20行）
- 语言/框架具体约束
- 命名规范
- 文件组织规则
- 禁止事项（非常重要！）

## 4. 常用命令（5-10行）
- 安装/构建/测试/部署
- Lint/格式化命令

## 5. 特殊约定（5-10行）
- Git 工作流
- PR/Review 流程
- 环境变量/密钥管理

下面我们逐一拆解，每个模块都有可直接复制的模板。

模板一：全栈项目（React + Node.js）

这是最常见的 AI 创业项目形态——前端 React/Next.js，后端 Node.js/Express，数据库 PostgreSQL。

# MySaaS - AI 内容创作平台

## 项目概述
全栈 SaaS 应用，帮助内容创作者用 AI 生成和排期社媒内容。
- 前端: Next.js 14 (App Router) + TypeScript + Tailwind CSS
- 后端: Node.js + Express + Prisma ORM
- 数据库: PostgreSQL (Supabase)
- AI: OpenAI API (GPT-4o) + Anthropic API (Claude 3.5 Sonnet)
- 部署: Vercel (前端) + Railway (后端)

## 目录结构

/
├── frontend/ # Next.js 前端
│ ├── app/ # App Router 页面
│ ├── components/ # 可复用组件
│ │ ├── ui/ # 基础 UI (shadcn/ui)
│ │ └── features/ # 业务组件
│ ├── lib/ # 工具函数、API 客户端
│ └── hooks/ # 自定义 Hooks
├── backend/ # Express 后端
│ ├── routes/ # API 路由
│ ├── services/ # 业务逻辑层
│ ├── middleware/ # 认证、日志等中间件
│ └── prisma/ # 数据库 Schema + 迁移
└── shared/ # 前后端共享类型定义

## 编码规范

### TypeScript
- 严格模式 (`strict: true`)，禁止 `any`
- 接口用 `interface`，类型别名用 `type`
- 所有函数必须有返回类型注解
- 异步函数返回 `Promise<T>`

### React
- 组件用函数式 + Hooks，禁止 Class 组件
- 一个文件只导出一个组件
- Props 用 interface 定义，放在文件顶部
- 用 `'use client'` 明确标记客户端组件

### 命名
- 文件名: kebab-case (`user-profile.tsx`)
- 组件名: PascalCase (`UserProfile`)
- 函数/变量: camelCase (`getUserData`)
- 常量: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)

### 禁止事项
- ❌ 不要使用 `var`
- ❌ 不要直接操作 DOM（用 React 声明式写法）
- ❌ 不要在组件中直接调用 API（用 hooks 封装）
- ❌ 不要硬编码 API 密钥或 URL（用环境变量）
- ❌ 不要删除已有的测试文件
- ❌ **绝对不要修改 `prisma/schema.prisma` 除非我明确要求**

## 常用命令
```bash
# 开发
cd frontend && npm run dev      # 前端开发服务器 :3000
cd backend && npm run dev       # 后端开发服务器 :4000

# 测试
npm test                        # 运行所有测试
npm test -- --coverage          # 含覆盖率报告

# 数据库
cd backend && npx prisma migrate dev   # 执行迁移
cd backend && npx prisma studio        # 可视化数据库

# 部署
git push main                  # 自动触发 Vercel + Railway 部署

Git 约定

分支: feature/xxx, fix/xxx, refactor/xxx
Commit: Conventional Commits (feat:, fix:, refactor:)
PR 前必须通过 lint + test

---

## 模板二：CLI 工具 / NPM 包

AI 创业者经常要写 CLI 工具或发布 npm 包。这个模板适用于单仓库、注重 API 设计的项目。

```markdown
# agent-utils - AI Agent 工具集

## 项目概述
一组用于构建 AI Agent 的 TypeScript 工具库。发布到 npm，目标用户是 Node.js 开发者。

## 架构

/
├── src/
│ ├── core/ # 核心抽象 (Agent, Tool, Memory 接口)
│ ├── tools/ # 内置工具 (FileSystem, WebSearch, CodeExec)
│ ├── memory/ # 记忆系统实现
│ └── utils/ # 内部工具函数
├── tests/ # Vitest 测试
├── examples/ # 使用示例
└── docs/ # TypeDoc 生成的 API 文档

## 编码规范

### 核心原则
- 库代码必须是无副作用的纯函数（除 tools/ 目录）
- 所有公共 API 必须有 JSDoc 注释
- 导出用 named exports，禁止 default export
- 错误用自定义 Error 子类，不要 throw 字符串

### API 设计规则
- 构造器参数用对象解构（options pattern）
- 异步操作用 AbortSignal 支持取消
- 返回类型始终明确，不依赖类型推断

### 禁止事项
- ❌ 不要在库代码中使用 `console.log`（用 debug 库）
- ❌ 不要引入超过 50KB 的依赖
- ❌ 不要修改 `package.json` 的版本号
- ❌ 不要在未讨论的情况下添加新依赖

## 测试规范
- 测试文件: `src/xxx.test.ts`（与源文件同目录）
- 每个公共 API 至少有一个测试
- 用 `describe`/`it` 模式，描述用英文
- Mock 外部依赖，不请求真实网络

## 常用命令
```bash
npm run build       # tsc 编译
npm test           # vitest --run
npm run lint       # eslint + prettier
npm run docs       # 生成 API 文档
npm version patch  # 发布新版本（自动 build + test + publish）

---

## 模板三：Python 数据/AI 项目

Python 是 AI Agent 开发的主力语言。这个模板适用于 Jupyter-heavy 的数据分析或 AI 模型项目。

```markdown
# ai-analytics - AI 使用数据仪表板

## 项目概述
分析 AI API 调用日志，生成成本和使用趋势报告。内部工具，非公开发布。

## 技术栈
- Python 3.12+
- 数据处理: Pandas, Polars (优先 Polars，性能更好)
- 可视化: Plotly (非 Matplotlib)
- 配置: Pydantic Settings
- 环境管理: uv (非 pip)

## 目录结构

/
├── src/
│ ├── ingest/ # 数据摄入 (API logs → Parquet)
│ ├── transform/ # 数据清洗和聚合
│ ├── visualize/ # 图表生成
│ └── report/ # 报告生成 (Markdown + HTML)
├── notebooks/ # 探索性分析（不要放生产代码）
├── tests/
└── data/ # 本地数据（gitignored）

## 编码规范

### Python 风格
- 类型注解: 所有函数签名必须有完整类型注解
- 字符串: 单引号 `'...'`（除非字符串内含单引号）
- Docstring: Google 风格
- 行宽: 100 字符

### 数据处理规范
- 优先用 Polars，仅在与 Plotly 集成时用 Pandas
- 大文件用 Parquet 格式，不要用 CSV
- 链式操作，避免中间变量

### 禁止事项
- ❌ 不要使用 `print()` 调试（用 `logging` 模块）
- ❌ 不要在 notebooks/ 中写生产代码
- ❌ 不要硬编码文件路径（用 `src/config.py`）
- ❌ 不要在循环中逐行构建 DataFrame

## 常用命令
```bash
uv run pytest                    # 运行测试
uv run ruff check .              # Linting
uv run mypy src/                 # 类型检查
uv run python -m src.main        # 运行主流程

---

## 模板四：开源贡献者（多仓库协作）

如果你用 Claude Code 给开源项目提 PR，这个模板告诉 Agent 如何与陌生代码库交互。

```markdown
# Open Source Contributor Mode

## 核心原则
这是一个开源贡献会话。我在为 [项目名] 提交 PR。

## 交互规则
1. **先读后改**: 修改任何文件前，先阅读相关文件和测试
2. **最小变更**: 只改实现目标所需的最小代码
3. **保持风格**: 严格遵循已有代码风格，不做格式化
4. **测试先行**: 修改前理解现有测试，修改后确保测试通过
5. **Commit 规范**: 遵循项目的 CONTRIBUTING.md 中的约定

## 代码探索策略
- 先看 `README.md` 和 `CONTRIBUTING.md`
- 再看相关源码文件的 import 和类型定义
- 最后看测试了解预期行为

## 禁止事项
- ❌ 不要在未理解的情况下删除代码
- ❌ 不要重新格式化已有代码
- ❌ 不要引入项目未使用的依赖
- ❌ 不要修改与 PR 目标无关的文件
- ❌ 不要擅自重构

## 工作流
1. 创建分支: `git checkout -b fix/description`
2. 修改 + 测试
3. 运行项目的 lint/test 命令
4. 生成 PR description

模板五：一人创业项目（全栈 + 运营）

这是给"一个人干全栈 + 内容 + 运营"的 AI 创业者准备的模板。

# AI创业内参 - 全栈一人项目

## 项目概述
AI 行业日报 + 工具教程的自动化内容生产系统。包含：
- 热点监控（cron + Hermes Agent）
- 内容生产（多 Agent 协作流水线）
- 微信公众号发布
- 网站同步（Cloudflare Pages）
- 数据分析（n8n 待搭建）

## 核心约束（非常重要！）

### 发布安全
- **绝对不要**在未人工确认的情况下发布文章
- 所有草稿必须先保存到 `content/draft-*.md`
- 发布前必须通过三审：rate_article(≥60) → rate_layout(≥80) → rate_images(≥70)

### Token 成本控制
- 单篇文章的 Agent 调用成本控制在 $0.50 以内
- 搜索优先用 HN Algolia API（免费），避免 web_search（付费）
- 长文章用 deepseek-v4（便宜），短指令用 claude-sonnet（精准）

### 内容规范
- 文章 1500-2500 字
- 必须有可复制的代码/配置片段
- 必须有具体数据（不能是"据说""可能"）
- 必须标注数据来源 URL

## 常用命令
```bash
# 内容生产
python scripts/hotspot_scan.py      # 热点扫描
python scripts/generate_draft.py    # 生成草稿
python scripts/publish_wechat.py    # 发布公众号

# 网站
wrangler pages deploy www --project-name ai-neican --branch main

禁止事项

❌ 不要删除 content/ 中的历史草稿
❌ 不要在 .env 中硬编码 API 密钥（用环境变量）
❌ 不要在文章中写"据说""可能"等无法验证的内容
❌ 不要发布没有通过三审的文章

---

## CLAUDE.md 常见错误与修正

### 错误1：写成散文而非指令

❌ "这个项目用了很多现代技术，我们追求代码质量和最佳实践..."
✅ "TypeScript strict mode，禁止 any，文件名 kebab-case"

CLAUDE.md 是给 AI 看的，AI 需要**精确、可执行**的指令，不需要氛围描述。

### 错误2：只有禁止没有允许

❌ "不要写烂代码"
✅ "用函数式组件 + Hooks，一个文件一个组件，Props 用 interface 定义"

只说"不要什么"，AI 仍然不知道"要什么"。正向示例比禁止更有效。

### 错误3：放临时的任务描述

❌ "今天需要完成用户登录模块 # TODO"
✅ 临时任务放在对话中说，CLAUDE.md 只放持久化的项目规则

CLAUDE.md 会被 Git 追踪。临时的 TODO 会让 Agent 在每次对话中都以为要做这个任务。

### 错误4：过长或过短

❌ 10 行：只说"这是 React 项目"
❌ 500 行：连每个组件的作用都写了
✅ 80-200 行：架构概览 + 关键规则 + 禁止事项
```

AI 的注意力是有限的。太短没信息量，太长稀释重点。80-200 行是最佳区间。

错误5：忘记更新

代码库重构了，CLAUDE.md 还是旧的目录结构 → Agent 在错误的上下文中工作。每完成一个大功能就更新一次 CLAUDE.md。

效果评估：你怎么知道 CLAUDE.md 起作用了？

好的 CLAUDE.md 应该让你感受到这些变化：

新会话成本降低：不再需要每次解释项目结构
代码风格一致：Agent 生成的代码和已有代码看不出区别
减少"你错了"的纠正回合：Agent 第一次就按规则来
安全边界生效：Agent 不会擅自改不该改的文件

一个简单测试：新开一个对话，只给一句话任务（如"给用户表加个 avatar 字段"），看 Agent 是否：
- 知道了你的 ORM 是 Prisma 并修改了正确的 schema 文件
- 遵循了你的命名规范（avatar_url 而非 avatarUrl）
- 没有碰你不让碰的文件

全中 = CLAUDE.md 写对了 ✓

行动清单：现在就能做的事

今天就写：打开项目根目录，创建 CLAUDE.md，至少写 50 行
从模板开始：从上文 5 个模板中选择最接近你项目的，填充你的具体信息
先写禁止事项：如果时间紧，至少把"绝对不要做的事"写清楚——这是安全网
测试：新开一个 Claude Code 会话，给一个简单任务，观察 Agent 是否遵循规则
迭代：发现 Agent 犯了什么错误，就把规则加到 CLAUDE.md 里

一个 200 行的 CLAUDE.md，花 20 分钟写完，但未来 200 天，每天帮你省至少 10 分钟。这个投资回报率，你自己算。

本文是「Agent工坊」系列第 N 期。每周一个可复制的 AI Agent 配置模板，帮助 AI 创业者把 Agent 从"能用"提升到"好用"。

Agent工坊 #ClaudeCode #CLAUDE.md #AI编程 #一人公司 #效率工具