上下文工程实战：写好 AGENTS.md / CLAUDE.md，让编程 Agent 一次就懂你的项目

一个重要反直觉事实：往上下文里塞得越多，Agent 表现越差。多项研究（Chroma 的 context rot、苏黎世联邦理工的 AGENTS.md 评估）都验证过——把整段对话历史塞进去，准确率能掉 30%；自动生成的上下文文件甚至比「没有文件」还差 3%。原因很简单：模型的注意力是有限的，废话越多，关键指令的信号越被稀释。所以我们要的不是「多写」，而是「在最对的时间，给最少的、最高信号的信息」。这正是「上下文工程（Context Engineering）」的核心。

2026 年形成了一套事实标准，三个文件，三种作用域，按需加载：

关键思路是渐进式披露：常驻文件只放高频规则，把「数据库迁移怎么写」「部署流程」这种偶发知识拆到 SKILL.md，等 Agent 真碰到迁移任务时才加载。这样每一次对话的上下文都精简，但信息一个不少。

把下面这份贴到项目根目录的 AGENTS.md，按你的项目填空。每条都遵循「命令先于解释、显式约束、给反例、附命令速查」的原则：

# AGENTS.md（项目通用约定，所有 AI 编程 Agent 都读）

## 技术栈与命令
- 包管理：pnpm（禁 npm/yarn）
- 启动：pnpm dev ｜ 构建：pnpm build ｜ 测试：pnpm test -- --tb=short
- 代码风格：Prettier + ESLint，提交前必跑 pnpm lint

## 必须遵守的约定（Do）
- 业务逻辑放 internal/，可复用组件放 pkg/
- 数据库只用参数化查询，禁止字符串拼 SQL
- 错误处理：捕获具体异常，禁止裸 except/ catch (Exception)

## 禁止做的事（Don't）
- 禁止直接改 generate/ 下的生成文件
- 禁止为一次性逻辑抽公共函数（用一次不算复用）
- 禁止把密钥写进源码，统一走环境变量

## 常见任务怎么下手
| 任务 | 动作 |
|------|------|
| 加 API 端点 | 写 handler → 校验入参 → 写单测 → 更新 OpenAPI |
| 加数据库表 | 写迁移 → 改 repository → 加集成测试 |

## 细节文档（按需取，别全塞进来）
- 架构图与决策记录 → docs/ARCHITECTURE.md
- 接口契约 → specs/README.md

AGENTS.md 是开放标准，Codex、Cursor、Copilot、Claude Code 都会自动读。唯一例外是 Claude Code 默认读 CLAUDE.md——解决办法就一行，让它在 CLAUDE.md 里引用 AGENTS.md，避免维护两份：

# CLAUDE.md（Claude 专属，放根目录）
@AGENTS.md

## Claude 专属补充说明
-  destructive 命令（rm -rf / git push --force）执行前必须先问我
-  偏好用 rg 搜索而非 grep

如果你在多台机器开发，还可以放一份全局 ~/.claude/CLAUDE.md，写「跨所有仓库都成立的个人偏好」（比如默认编辑器、提交信息风格）。层级是：全局 → 项目 → 子目录/per-area，越具体越优先，Agent 会自动向上合并。

「数据库迁移规范」「部署到预发环境的 12 步」这种低频但高价值的操作，不该常驻在每次对话里。把它们写成 .claude/skills/数据库迁移/SKILL.md 这类技能文件，Agent 只有在真的碰到相关任务时才会加载。好处是双重的：常驻上下文更干净，且每条技能可以写得很细（200 行都不嫌多），反正不占日常额度。

# .claude/skills/数据库迁移/SKILL.md（按需加载，不占日常上下文）
触发：涉及 migration / schema 变更时
步骤：
1. 读当前 schema，确认命名规范
2. 只加不减，向后兼容
3. 生成迁移文件 → 跑 pnpm test
4. 在 PR 描述里写明回滚方案

不需要复杂指标，盯住一个最直观的：每个任务你需要返工/纠正几次。如果你还在说「我明明告诉过你别用 print」「你该写个测试」，说明这条规则该进文件。典型收益对比：

最后给两条维护纪律：① 5% 规则——常驻上下文（AGENTS+CLAUDE）别超过有效窗口的 5%（200K 窗口下约 1 万 token / 500 行是红线）；② 定期审计——每个 sprint 或每月过一遍，把 Agent 反复犯的错提进规则、把过时的删掉。上下文文件是「活文档」，不是一次性产物。