AI 编程上下文工程 SOP：为编程 agent 结构化上下文的五步流程

Q: CLAUDE.md 和 AGENTS.md 有什么区别？该用哪个？

同一套约定的两个文件名。Claude Code 读 `CLAUDE.md`，OpenCode/Codex 读 `AGENTS.md`。如果你只用 Claude Code，写 `CLAUDE.md` 就行；如果团队里有人用 OpenCode 或 Codex，两个文件都写、内容保持一致。本站自己的做法就是在 CLAUDE.md 顶部加一行提醒「修改其一需同步另一份」。

同一个 Claude Code，有人用它两周重构完遗留系统，有人用它改个函数改出一堆报错。差距不在模型，在上下文。你喂给 agent 的项目结构、编码约定、红线规则、相关代码片段，统称上下文（context）。上下文工程（Context Engineering）就是把这些信息结构化、分层、按需投喂的套路--不是写更长的 prompt，而是让 agent 在每一步推理时看到该看的、不看不该看的。

这篇 SOP 给你一套可复制流程：梳理项目上下文 -> 写规则文件 -> 管上下文窗口 -> 记忆持久化 -> 验证迭代，五步。规则文件以 CLAUDE.md / AGENTS.md 为例（Claude Code 读 CLAUDE.md，OpenCode/Codex 读 AGENTS.md，这是真实约定，非杜撰），上下文管理以 Claude Code 的 @-引用 / /compact / 子代理机制为主。截至 2026-08-11，具体行为以各工具官方文档为准。与同批的 ZCode 3.0 升级热点（Goals 模式靠上下文拆解目标）、AI 编程套餐横评（选完套餐怎么用）、crush 开源编程 Agent 资源（model-agnostic 靠你配好上下文）成对互链，建议对照读。

一、上下文工程不是提示词工程

先划清三个容易混的概念。同站的工具调用 SOP 讲的是模型怎么决定调哪个 API；Computer Use SOP 讲的是模型怎么看屏幕操控 GUI。上下文工程不在这两层--它解决的是「在模型推理之前，你往它的上下文窗口里塞什么」。

维度	提示词工程	上下文工程
关注点	单条指令怎么写	整个信息生态怎么搭
范围	一次对话	跨会话、跨文件、跨工具
核心动作	改措辞、加示例	管理规则文件、代码引用、记忆层
持久性	用完即弃	持久化到文件，下次自动加载

一句话：提示词工程教 AI 怎么说话，上下文工程教 AI 看什么。对编程 agent 来说，后者比前者重要十倍--模型再聪明，看不到你的项目约定就会按默认习惯写，写出来的代码风格不对、架构不对、踩了你早就踩过的坑。

二、SOP 五步流程

Step 1：梳理项目上下文

动手写规则文件之前，先搞清楚你的项目有哪些上下文值得结构化。四类必梳理：

技术栈与版本：语言、框架、运行时、包管理器、数据库。别让 agent 猜你用的是 Python 3.11 还是 3.13，写死。目录结构：核心模块在哪、入口在哪、测试在哪、配置在哪。给 agent 一张「地图」比让它自己 ls 强。编码约定：命名风格、错误处理模式、日志规范、测试框架。这些是模型训练数据里学不到的「团队方言」。红线与禁区：不能碰的文件、不能引入的依赖、不能跳过的检查步骤。

实操：在项目根目录跑 tree -L 2 -I "node_modules|.git|dist" 看结构，跑 rg "TODO|FIXME|HACK" 看技术债，翻 package.json / pyproject.toml 看依赖。把这些整理成几行文字，就是规则文件的骨架。

Step 2：写规则文件（CLAUDE.md / AGENTS.md）

规则文件是上下文工程的「宪法」--持久化在项目里，每次 agent 启动自动加载。Claude Code 读 CLAUDE.md，OpenCode/Codex 读 AGENTS.md，Cursor 用 .cursor/rules/*.mdc（旧版 .cursorrules），Crush 这类 model-agnostic agent 同样靠你配好指令文件。文件放项目根目录，内容分四块：

角色定位：一两句话告诉 agent 这个项目是什么、它的角色是什么。红线规则：Never / Ask first / Always 三档，用祈使句写死。常用命令：构建、测试、部署的精确命令，agent 直接抄就能跑。风格约定：命名、格式、错误处理的几条硬规矩。

写法纪律：每条规则一行，用粗体关键词开头（Never / Always / Ask first），别写成长段落--模型对短句的遵从度远高于散文。总长控制在 50-80 行以内，太长模型会忽略后半段（见第四节坑 1）。真实示例见第三节。

Step 3：管理上下文窗口（@-引用 / 精简 / 分层）

规则文件管的是「持久上下文」，但每次任务还有「即时上下文」--当前要改的文件、相关接口定义、报错日志。管理即时上下文三招：

@-引用：Claude Code 支持 @filepath 语法，在对话里写 @src/auth/login.ts 就把该文件内容注入上下文。比手动复制粘贴干净，且 agent 能感知文件路径。引用要精准--@src/ 引用整个目录可能灌入无关文件，@src/auth/login.ts 只引用一个文件才高效。分层加载：先给项目结构（让 agent 看全貌），再给任务相关文件（让它聚焦），最后给报错日志（让它修正）。别一上来把 20 个文件全塞进去。及时清理：长对话用 /compact 压缩历史（把早期对话摘要化），用 /clear 彻底清空开新任务。一个会话别堆三个不相关的任务，上下文污染比上下文缺失更致命。

Step 4：记忆与持久化（memory / 会话状态）

规则文件是「你写的」记忆，还有一类是「agent 自己攒的」记忆。Claude Code 的记忆分三层：

项目级 CLAUDE.md：放项目根目录，团队共享，进 Git。用户级 ~/.claude/CLAUDE.md：放你的 home 目录，跨项目生效，写你的个人偏好（如「始终用中文回复」）。子目录 CLAUDE.md：放在子目录里，agent 进入该目录工作时才加载--适合给某个模块写专属约定。

子代理（Subagents）是另一层隔离。Claude Code 的 .claude/agents/*.md 定义子代理，每个子代理有独立上下文窗口，主 agent 把子任务委派给它，结果回来时不污染主上下文。ZCode 3.0 的 Subagents 功能、Crush 的多 provider 设计也是同理：复杂任务拆域并行，每个 agent 上下文更干净。长程任务跨会话断档的问题，靠的就是这层持久化--闲时任务、Remote Control 能跨天跑，前提是状态和上下文都存住了。

Step 5：验证与迭代

规则文件不是写一次就行的。每跑完一个任务，检查三件事：

规则有没有被遵守：看 agent 的输出是否违反了你写的 Never/Always。如果违反了，要么规则写得不够明确，要么规则太长被忽略了。规则有没有过时：项目技术栈换了、目录结构改了、命令变了，规则文件得跟着改。过时规则比没规则更危险--agent 照着旧规则跑，报错还查不出原因。有没有新坑该写进去：踩了一个新坑（比如某依赖版本不兼容），马上补一条规则防止下次重蹈。本站自己的 CLAUDE.md 就有「操作留痕」机制：每完成一步操作就追加一条记录，这就是迭代。

建议每周花 10 分钟过一遍规则文件，删过时的、补新踩的、精简啰嗦的。规则文件像花园，不除草就长荒。

三、真实规则文件示例

下面是一个 Web 项目的 CLAUDE.md 示例（AGENTS.md 内容保持一致，改个文件名即可）。可直接拿去改用。

markdown

# MyShop 电商后台

Next.js 15 (App Router) + TypeScript + Prisma + PostgreSQL 的电商后台。
前端组件用 shadcn/ui，样式用 Tailwind CSS v4。

## 红线

- **Never**：使用 `any` 类型；跳过 `npm run lint` 和 `npm test`；在组件里直接写 SQL
- **Ask first**：引入新 npm 依赖；修改 prisma/schema.prisma；删除任何已有 API 路由
- **Always**：改完代码跑 `npm run lint && npm test`；新 API 路由加 Zod 入参校验；
  数据库变更先写 Prisma migration 再跑 `npx prisma migrate dev`

## 常用命令

- 开发：`npm run dev`（端口 3000）
- 构建：`npm run build`
- 测试：`npm test`（Vitest）
- Lint：`npm run lint`
- 数据库迁移：`npx prisma migrate dev --name <描述>`

## 风格约定

- 组件文件用 PascalCase（如 `ProductCard.tsx`），工具函数用 camelCase
- API 路由统一在 `app/api/` 下，返回 `{ data, error }` 结构
- 错误处理：业务错误抛 `AppError`，系统错误 try/catch 后返回 500
- 所有时间存 UTC，展示时在前端转时区

对应的上下文引用示例（Claude Code 对话中）：

text

# 精准引用：只给当前任务需要的文件
请重构 @src/api/orders/route.ts 的错误处理。
相关类型定义在 @src/types/order.ts，
AppError 的实现在 @src/lib/errors.ts。
参考 @src/api/products/route.ts 的错误处理写法保持一致。
跑 @npm run test 验证没有破坏现有测试。

要点：@filepath 引用精确到文件而非目录；相关文件一次给齐（类型定义 + 依赖实现 + 参考范例）；最后让 agent 自己跑测试验证。这比「帮我改一下订单接口」然后手动粘贴五个文件的效率高得多。

四、五个踩坑

坑 1：规则文件太长，模型忽略后半段 把所有约定、所有命令、所有历史决策全塞进 CLAUDE.md，写到 300 行。模型注意力有限，长文本后半段的遵从率明显下降。修法：总长控制在 50-80 行，只写「每次都要遵守」的规则。偶尔才用的约定放进子目录的 CLAUDE.md，按需加载。删掉「显而易见」的规则（如「写干净的代码」--模型本来就会）。

坑 2：上下文超窗口，agent「失忆」 长对话里堆了十几个文件引用、几十轮来回，超出上下文窗口后早期信息被截断。agent 忘了你的项目用 TypeScript，开始写 JavaScript。修法：用 /compact 定期压缩历史；不相关的任务开新会话用 /clear；大文件用子代理处理，结果以摘要形式回主会话。Crush 这类 model-agnostic agent 尤其要注意--不同模型的上下文窗口差异大，换模型可能直接超限。

坑 3：规则冲突，多层 memory 打架 项目级 CLAUDE.md 写「用 pnpm」，用户级 ~/.claude/CLAUDE.md 写「用 npm」，两个规则冲突，模型随机选一个。修法：用户级只写个人偏好（语言、回复风格），项目级写项目约定（技术栈、命令）。冲突时项目级优先。定期检查两层规则有没有矛盾。

坑 4：memory 失效，旧规则污染新任务 项目上个月从 REST 迁到 GraphQL，但 CLAUDE.md 里还写着「新 API 路由放 app/api/ 下」。agent 照旧规则生成 REST 路由，和你现在的架构完全脱节。修法：技术栈变更后第一时间更新规则文件；在规则文件顶部写明「最后更新日期」提醒自己；用 Step 5 的验证机制定期检查规则是否和代码现状一致。

坑 5：写完规则不迭代，规则变成废弃文档 规则文件写了一次就再没动过，三个月后项目大改，规则文件成了废纸。agent 不读废纸--它读的是文件内容，不管过不过时。修法：把规则文件当活文档，每周过一遍；每次踩坑后立刻补一条规则；在 DEV.md 或项目文档里加「操作留痕」表，规则文件每次改动也记一条。

五、常见问题

Q1：CLAUDE.md 和 AGENTS.md 有什么区别？该用哪个？ 同一套约定的两个文件名。Claude Code 读 CLAUDE.md，OpenCode/Codex 读 AGENTS.md。如果你只用 Claude Code，写 CLAUDE.md 就行；如果团队里有人用 OpenCode 或 Codex，两个文件都写、内容保持一致。本站自己的做法就是在 CLAUDE.md 顶部加一行提醒「修改其一需同步另一份」。

Q2：规则文件该写多长？有没有上限？ 没有硬性上限，但建议 50-80 行。经验法则：如果一条规则不是「每次任务都要遵守」的，它不该放在根 CLAUDE.md 里--放进子目录的 CLAUDE.md 或注释里。长规则文件的后半段遵从率会下降，不如精简。实在写不下，拆成多个文件放子目录，按需加载。

Q3：@-引用和直接粘贴代码有什么区别？ @-引用让 agent 知道文件的真实路径，后续修改时它能直接定位文件；粘贴代码 agent 只看到文本，不知道来自哪个文件，改完还得你手动同步回去。另外 @-引用在 Claude Code 里会被标记为「文件上下文」，和对话文本区分开，模型对文件内容的权重处理更高。所以凡是项目内的已有文件，优先用 @-引用。

Q4：换了模型（比如从 Claude 换到 GLM），规则文件要重写吗？ 不用重写，但要调措辞。CLAUDE.md / AGENTS.md 是通用 Markdown，任何能读指令文件的 agent 都能用。差异在于不同模型对规则的遵从度不同：Claude 对结构化规则（Never/Always 分档）的遵从度高；GLM 系列对中文规则的理解好但有时需要更明确的措辞；Crush 是 model-agnostic，换模型只换 provider 配置，规则文件不动。建议规则用短句 + 粗体关键词，所有模型都吃这套。

Q5：上下文工程和 RAG（检索增强生成）是什么关系？ 互补。RAG 是「按需检索外部知识」--你的代码库不在模型训练数据里，agent 通过语义搜索找到相关代码片段注入上下文。上下文工程是更大的框架：规则文件是「常驻上下文」，@-引用是「手动注入上下文」，RAG 是「自动检索上下文」。一个成熟的编程 agent 三者都用：启动时加载 CLAUDE.md（常驻），对话中 @-引用相关文件（手动），后台用代码库索引做语义搜索（RAG）。ZCode 3.0 的「全上下文感知」就是把 RAG 这层做进了 agent 内核。

参考来源

Anthropic Claude Code 官方文档（CLAUDE.md memory、@-引用、/compact、子代理）：https://docs.anthropic.com/en/docs/claude-code/memory
Anthropic Claude Code Memory 文档（项目级/用户级/子目录 CLAUDE.md 层级）：https://docs.anthropic.com/en/docs/claude-code/memory
Cursor Rules 官方文档（.cursor/rules/*.mdc 规则文件格式）：https://docs.cursor.com/context/rules
OpenCode 官方文档（AGENTS.md 约定）：https://opencode.ai/docs/
charmbracelet/crush 官方仓库（model-agnostic 终端编程 agent）：https://github.com/charmbracelet/crush
本站《ZCode 3.0 升级 GLM Coding Plan 额度回满热点》：https://aiwebcool.com/zh/zcode-upgrade-glm-coding-plan-quota-hotspot
本站《AI 编程套餐横评》：https://aiwebcool.com/zh/ai-coding-plan-comparison-review
本站《crush 开源编程 Agent 资源》：https://aiwebcool.com/zh/crush-coding-agent-resource
本站《AI Agent 工具调用 SOP》：https://aiwebcool.com/zh/ai-agent-tool-calling-sop
本站《Computer Use Agent 搭建 SOP》：https://aiwebcool.com/zh/computer-use-agent-build-sop