AI 编程工具的 Prompt Engineering——CLAUDE.md、AGENTS.md 和上下文管理实战

---

前九篇文章里反复出现两个文件：CLAUDE.md 和 AGENTS.md。每次提到它们都是"这样配置一下就好"，但没有展开讲过到底该写什么、怎么写、写错了会怎样。

这一篇补上。

不是通用的 Prompt Engineering 教程——专门讲 AI 编程工具的配置和上下文管理。每一个知识点背后都有一个翻过车的真实场景。

---

为什么"描述清楚需求"还不够

如果你只告诉 Claude Code"加一个导出 PDF 的功能"，它能写。但写出来的代码大概率跟你项目的风格格格不入——它用双引号你的项目用单引号，它写 class 你的项目用函数，它引了 lodash 你的项目全是原生写法。

AI 编程工具跟 ChatGPT 的区别在于——它会读你的项目。但你得让它知道"读完项目后该按什么规则写"。

这就是 CLAUDE.md 和 AGENTS.md 的作用——不是告诉 AI 做什么，是告诉它怎么做。

---

CLAUDE.md：给 Claude Code 的项目说明书

CLAUDE.md 放在项目根目录。Claude Code 启动时自动读取，注入到每次对话的上下文里。

一个空 CLAUDE.md 的惨案：

我的 Node.js 项目，没写 CLAUDE.md。让 Claude Code 加一个中间件。它写了这样的代码：

// Claude Code 生成的——没用项目约定
const rateLimit = require("express-rate-limit");
app.use(rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100
}));

问题在哪？我项目里用 import 不是 require，用 kebab-case 命名文件不是 snake_case，中间件统一放在 middlewares/ 目录下而不是直接塞 app.js。

Claude Code 不知道这些约定。它按最通用的方式写，不是你项目的方式。

加了 CLAUDE.md 之后：

# CLAUDE.md

## 项目技术栈
- Node.js 22 + Express 4.x
- 数据库：PostgreSQL，通过 Prisma ORM 访问
- 测试：Vitest

## 代码风格
- 使用 ES Module（import/export），不用 CommonJS
- 字符串用单引号，除非字符串内包含单引号
- 文件命名用 kebab-case
- 异步操作用 async/await，不用回调

## 项目结构
- 路由定义在 src/routes/ 下
- 中间件放在 src/middlewares/ 下
- 业务逻辑在 src/services/ 下
- 数据库模型定义在 prisma/schema.prisma

## 约束
- 不能引入超过 10KB 的新依赖（bundle size 敏感）
- 所有 API 响应统一用 { success, data, error } 格式
- 日志用 pino，不要 console.log

同样的需求，这次生成的代码：

// Claude Code 生成的——匹配了项目风格
import rateLimit from 'express-rate-limit';
import { createRateLimiter } from '../middlewares/rate-limiter.js';

app.use(createRateLimiter({ windowMs: 15 * 60 * 1000, max: 100 }));

它自动把中间件放到了 src/middlewares/rate-limiter.js，用了 import 语法，而且看懂了我的项目里有统一的中间件工厂模式。

CLAUDE.md 里到底该写什么：

该写	不该写	为什么
项目技术栈和版本号	“用最好的实践”	AI 不知道你的"最好"是什么
具体的命名约定	“保持代码整洁”	太模糊，等于没说
文件结构和分层规则	大段粘贴代码	占 token，不如让 AI 自己读
硬性约束（禁止/必须）	个人偏好吐槽	浪费上下文窗口
项目特有的设计模式	通用知识（怎么用 Express）	AI 本来就知道

一个小技巧：用到什么写什么。

不要一上来就写个 500 行的 CLAUDE.md。每次 Claude Code 生成代码不符合预期，把那条规则补进去。一个月后，CLAUDE.md 就是你们项目的精准说明书。

---

AGENTS.md：Codex 的版本，有区别

Codex 用 AGENTS.md，不是 CLAUDE.md。格式类似，但有三个关键区别：

1. 层级加载。 Codex 从 git 根目录一路读到当前目录，合并所有 AGENTS.md。如果你在 monorepo/services/payment/ 下工作，Codex 会读到：

~/monorepo/AGENTS.md          ← 根级，团队通用规则
~/monorepo/services/AGENTS.md ← 服务级，所有服务共享的规则
~/monorepo/services/payment/AGENTS.md ← 项目级，本服务特有规则

2. 有 AGENTS.override.md。 文件名里带 override 的会取代同目录下的 AGENTS.md，不会影响父目录的配置。适合某个子项目规则完全独立时用。

3. 默认 32KB 限制。 所有 AGENTS.md 合并后的总大小默认不超过 32KB，超出部分会被截断（而且是静默截断，不会有警告）。精简比堆内容重要。

生成初始 AGENTS.md：

在 Codex 的 session 里运行 /init，它会扫描项目生成一个脚手架：

/init
→ Generating AGENTS.md scaffold...
  - Detected: Python project, FastAPI framework
  - Detected: pytest test framework
  - Detected: SQLAlchemy ORM
  - AGENTS.md created with project summary

然后手动补充项目特有的规则——技术栈它能自动识别，但命名约定和设计模式需要你写。

---

上下文管理：喂对东西比喂多东西重要

AI 编程工具的上下文窗口有限。不是把所有文件怼进去效果就好。

少即是多。

我有一个 80 个文件的 Python 项目。没配 .claudeignore 的时候，Claude Code 启动要扫一分钟，而且经常引用错误的工具函数——因为 utils/ 下有三个废弃版本的 helpers_v2.py、helpers_v3_legacy.py，它分不清哪个是当前用的。

加了 .claudeignore 排除废弃文件后，启动快了一倍，代码引用准确率明显提升：

# .claudeignore
*deprecated*
*legacy*
*v2*
migrations/
migration_backups/

即时附加上下文比提前塞满更有效。

不要在需求描述里贴 200 行代码。让 AI 自己决定读什么——它的 Grep 和 Read 工具能比你更精准地找到相关代码。你只需要告诉它"从哪个模块开始看"。

应该这样：

参照 src/routes/orders.js 的路由写法，加一个 /invoices 的路由。业务逻辑放 src/services/invoice-service.js。

而不是贴整段 orders.js 的源码。

---

settings.json：权限控制不只是安全

.claude/settings.json 不只是防 AI 删文件。合理配置能消除大量"确认疲劳"。

默认最让人烦的场景： 每次 AI 要跑 npm test 都弹确认框。一个下午点了几十次"允许"。慢慢开始看都不看直接按 Y——权限控制形同虚设。

精准放行常用操作：

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run *)",
      "Bash(python -m pytest *)",
      "Bash(git diff *)",
      "Bash(git status)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push *)",
      "Bash(sudo *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

测试、lint、git 状态这类高频无害操作全部放行。删除、推送、sudo、网络请求需要确认。这样每次弹确认框你都会认真看——因为你知道只有危险操作才会弹。

---

三个翻车案例

翻车 1：把 CLAUDE.md 写成小作文

第一次写 CLAUDE.md，我写了 800 行。技术栈、编码规范、业务术语表、团队分工、会议纪要全塞进去了。结果 Claude Code 每次启动花 15 秒读 CLAUDE.md，而且指令密度被无关信息稀释——它记住了"每周五上线"但忘了"用单引号"。

教训：CLAUDE.md 是代码规范说明书，不是项目 wiki。wiki 单独放，AI 不读。

翻车 2：规则互相矛盾

我在 CLAUDE.md 里写了"尽量用函数式风格"，又写了"遵循项目中已有的代码风格"。但项目里有大量 class-based 的代码，Claude Code 左右为难——一会写函数一会写 class。

教训：规则要具体，避免"尽量"“可能"这种词。与其写"风格偏好”，不如写"参照 src/services/order-service.js 的写法"。

翻车 3：用 Codex 但没写 AGENTS.md

Codex 是懒加载，不像 Claude Code 会自动扫描项目。没写 AGENTS.md 时，Codex 完全不知道项目中有什么。让它加一个功能，它从零写了一个新的服务类，而项目里明明有一个完全能复用的基类。

教训：Codex 依赖 AGENTS.md 告诉它项目里有什么。至少写清楚技术栈、项目结构和关键模块的路径。

---

一个可以直接用的 CLAUDE.md 模板

# CLAUDE.md

## 技术栈
- {语言 + 版本}
- {框架 + 版本}
- {数据库/ORM}
- {测试框架}

## 代码风格
- {缩进、引号、分号}
- {命名约定：文件、变量、函数}
- {模块化方式：import/export 风格}

## 项目结构
- {目录划分和职责}
- {分层规则}

## 约束
- {禁止做的事}
- {必须遵守的格式}
- {包大小限制、性能要求等}

## 参考风格
- 如果不确定怎么写，参照 {某个文件} 的写法

填完大概 50-80 行。够用。

---

下一篇

十个交互技巧——不是配置而是使用习惯。比如怎么中断 AI 的"跑偏"、怎么让它先给方案再动手、怎么在生成过程中修正方向。