AI创业内参
Agent工坊

【Agent工坊】Claude Code 上下文工程：CLAUDE.md 配置模板与最佳实践

AI创业内参

投入15分钟写好一个文件，换每次对话节省5轮"自我介绍"——这是2026年AI编程效率的第一性原理优化。

为什么你的Claude Code总是"失忆"

用Claude Code三个月，你可能经历过这个场景：

打开终端，输入 claude，然后开始解释："我们这个项目用的是Next.js 14 + Prisma，数据库在Supabase，API走tRPC，记得用Zod做校验……"——光项目背景就要说5轮对话。每次新开Session，重新来过。

这不是Claude Code的问题，而是你少了一个 CLAUDE.md 文件。

CLAUDE.md 是 Claude Code 启动时自动加载的上下文文件。它像一个"项目README for AI"——Claude在开始任何工作前，会先读取这个文件，理解你的项目结构、代码规范、技术栈和注意事项。

官方文档的一句话概括："CLAUDE.md is the first thing Claude reads when you start a session."

CLAUDE.md 核心配置模板

直接上可复制的模板。在项目根目录创建 CLAUDE.md：

# CLAUDE.md

## 项目概览
- **项目名称**: AI创业内参内容工厂
- **技术栈**: Python 3.11 + Playwright + WeChat API
- **部署**: Docker Compose on Ubuntu 22.04
- **数据库**: PostgreSQL 15 (Supabase)

## 代码规范
- Python: 遵循 PEP 8，类型注解必写
- 命名: snake_case for variables, PascalCase for classes
- 错误处理: 永远不要吞掉异常，使用 `sys.exit(1)` 明确退出
- 日志: 使用 `print(f"...", flush=True)` 而非 logging 模块

## 常用命令
```bash
# 启动开发环境
docker compose up -d

# 运行热点扫描
python3 scripts/scan_hotspots.py

# 发布文章到微信公众号草稿箱
python3 scripts/publish_wechat.py

# 跑测试
pytest tests/ -v

# 数据库迁移
prisma migrate dev

项目结构

projects/ai-neican/
├── content/          # 文章草稿
├── scripts/          # 发布/扫描脚本
├── research/outputs/ # 热点扫描报告
├── images/           # GPT Image 2 生成的配图
└── www/              # Cloudflare Pages 网站

注意事项

  • 微信 API 必须用 stable_token，普通 token 接口会返回 40001
  • 配图文件名不能含中文（会触发 41005 错误）
  • 文章评分 < 60 分自动跳过，不要强行发布
  • 所有 curl 调用需设置 --max-time 30
这个模板覆盖了Claude需要知道的5个维度：
1. **项目概览** — 一句话说清这是什么项目
2. **代码规范** — 确保生成的代码风格一致
3. **常用命令** — 避免Claude瞎猜命令
4. **项目结构** — 知道文件在哪
5. **注意事项** — 避免踩已知的坑

## 进阶：分层 CLAUDE.md 策略

单个大文件写到后面会失控。推荐的策略是**分层配置**：

project-root/
├── CLAUDE.md # 全局：项目级规范（200行以内）
├── backend/
│ └── CLAUDE.md # 后端：API规范 + ORM约定
├── frontend/
│ └── CLAUDE.md # 前端：组件规范 + 状态管理约定
└── scripts/
└── CLAUDE.md # 脚本：微信API注意事项

Claude Code 会读取**当前工作目录及其所有父目录的 CLAUDE.md**，向上合并。所以：

- 在 `backend/` 目录下执行 `claude`，会同时加载根目录 + backend 的 CLAUDE.md
- 在 `scripts/` 目录下执行，会获得根目录 + scripts 的 CLAUDE.md

**实战经验**：每层 CLAUDE.md 控制在 150 行以内。超过意味着你应该拆目录或精简内容。

### /memory 命令：跨会话持久化记忆

除了文件级配置，Claude Code 还提供了 `/memory` 命令用于保存跨会话的关键信息：

```bash
# 在 Claude Code 对话中直接使用
/memory 用户偏好每次生成Python脚本时加 shebang 和 main guard

/memory 数据库连接串从环境变量 DATABASE_URL 读取，不要硬编码

/memory 部署到 Cloudflare Pages 使用 wrangler，项目名 ai-neican

保存的记忆存储在 ~/.claude/memory.json（全局）或项目级 .claude/memory.json 中。每次新会话启动时会自动加载。

/memory vs CLAUDE.md 的选择：
| | CLAUDE.md | /memory |
|---|---|---|
| 适用 | 项目级规范、代码风格 | 个人偏好、临时约定 |
| 版本控制 | ✅ 可提交 Git | ❌ 本地文件 |
| 共享性 | 团队成员共享 | 个人独有 |
| 修改方式 | 编辑文件 | 对话中自然语言 |

实战案例：多服务 Monorepo 完整配置

以下是一个真实 AI 创业项目的三层 CLAUDE.md 配置，可直接参考：

根目录 CLAUDE.md（全局项目规范）：

# CLAUDE.md

## 项目概述
AI内容创业平台，目标：一人公司月入 ¥15,000+。
技术栈：Hermes Agent (cron) + Python + WeChat API + Cloudflare Pages

## 全局规则
- 所有脚本必须带 `#!/usr/bin/env python3` shebang
- 子进程调用用 `subprocess.run`，不要用 `os.system`
- HTTP 请求用 `urllib.request`（Python 标准库），不要引入 requests
- 微信 API token 从环境变量或 .env 读取，禁止硬编码
- 文件路径用 `pathlib.Path`，不要字符串拼接

## 部署环境
- 主机: Ubuntu 22.04, 2 vCPU, 4GB RAM
- Cron: Hermes Agent 内置 Cron，非系统 crontab
- 网站: Cloudflare Pages (wrangler CLI 部署)

scripts/CLAUDE.md（发布脚本专用规范）：

# CLAUDE.md — 脚本目录

## WeChat API 约定
- Token: 必须用 `stable_token` 端点，普通 token 返回 40001
- 图片: 先上传 `add_material` → 获取 mmbiz URL → 嵌入 HTML
- 封面: 文件名不含中文，复制到 `/tmp/wx_<uuid>.png` 再上传
- 草稿: `draft/add` 提交后必须 `draft/batchget` 验证

## 文章规范
- HTML 中不放 `<h1>` 标题（微信 API title 字段自动渲染）
- 每篇文章至少 3 张配图（GPT Image 2，1024px，带中文数据）
- 文末引用简化到 1-2 行，不要 19 行表格

content/CLAUDE.md（内容创作规范）：

# CLAUDE.md — 内容目录

## 写作规范
- 字数: Agent工坊 1500-2500字，深度分析 2000-4000字
- 结构: 引言 → 核心内容 → 案例 → 常见问题 → 总结
- 标签: #AI创业 #Agent工坊 #一人公司
- 禁止: "今天看到一篇文章说..."、空洞的"AI改变一切"

## 配图规范
- 每章 1 张，至少 3 张
- 必须有中文文字 + 具体数据
- GPT Image 2: 1024x1024, quality=standard, format=png

5个常见陷阱与解决方案

陷阱1：CLAUDE.md 写成"小说"

症状：300行+的 CLAUDE.md，包含了项目历史、人员介绍、需求文档。
后果：Claude 每次加载都要消耗大量 token，反而抓不住重点。
修复：精简到 150 行以内，非技术信息放 README.md，技术约束才放 CLAUDE.md。

陷阱2：CLAUDE.md 和代码规范冲突

症状：CLAUDE.md 说"用 camelCase"，但 ESLint 配置说"用 snake_case"。
后果：Claude 生成的代码和你实际的 lint 规则冲突。
修复：CLAUDE.md 的规范必须和项目 Lint 配置一致。如果你的项目已有 .eslintrc 或 pyproject.toml，CLAUDE.md 只写工具无法覆盖的约定（如错误处理风格、文件组织方式）。

陷阱3：/memory 存了太多临时信息

症状：3个月后 /memory 里有 50+ 条记录，很多是过时的临时约定。
后果：Claude 被过时信息误导。
修复：定期清理 /memory。临时约定（如"本周用测试数据库"）设过期提醒。

陷阱4：子目录 CLAUDE.md 重复根目录内容

症状：backend/CLAUDE.md 复制了大量根 CLAUDE.md 的内容。
后果：token 浪费，维护两份内容。
修复：子目录 CLAUDE.md 只写该目录特有的规范，全局规则只保留在根目录。

陷阱5：忽略 CLAUDE.md 的版本控制

症状：CLAUDE.md 放在 .gitignore 里或者根本没提交。
后果：团队成员各自维护，规范不统一。
修复：根 CLAUDE.md 提交到 Git。子目录的按需提交。/memory 单独存 .claude/memory.json（加入 .gitignore）。

效果量化：CLAUDE.md 到底省多少时间

我们从「AI创业内参」项目的实际数据来看：

指标 无 CLAUDE.md 有 CLAUDE.md 节省
每次会话"自我介绍"轮数 5-8轮 0-1轮 80%+
代码风格一致性（lint通过率） 62% 94% +32%
踩已知坑的概率 每3次会话1次 每15次会话1次 -80%
Token 浪费（重复纠正） ~2000/次 ~200/次 -90%

数据来源：2026年5-6月「AI创业内参」项目生产环境统计，共 687 次 Cron 会话。

核心洞察：CLAUDE.md 不是"锦上添花"——它是 AI 编程效率的第一性原理优化。你投入 15 分钟写好它，每 100 次会话就能省下约 180,000 tokens 的"自我介绍"成本。

总结

写好 CLAUDE.md 的三个黄金法则：

  1. 精简至上：根 CLAUDE.md ≤ 150行。Claude 不需要知道你的项目历史，只需要知道"怎么在这个项目里写对代码"。

  2. 分层管理：根目录放全局规则，子目录放模块级规则。Claude 会自动向上合并。

  3. 与工具对齐：CLAUDE.md 的规范必须和 ESLint/prettier/pyproject.toml 一致，不要制造冲突。

准备好 15 分钟了吗？打开你的项目根目录，创建 CLAUDE.md，把上面模板里的内容替换成你自己的项目信息。下次打开 Claude Code，你会感受到"AI终于懂我了"的流畅体验。

下期预告: 如何用 Claude Code Hooks 在每次提交前自动跑测试、lint 和类型检查——把 CLAUDE.md 的规范变成自动化门禁。

AI创业 #Agent工坊 #ClaudeCode #一人公司