当前位置：首页 > news >正文

2026 开发者效率新范式：上下文工程实战，用 AGENTS.md/CLAUDE.md 让 AI 编程智能体一次做对

news 2026/8/13 1:15:59

2026 开发者效率新范式：上下文工程实战，用 AGENTS.md/CLAUDE.md 让 AI 编程智能体一次做对

![封面图](https://picsum.photos/seed/1786537499322/800/400)

2026 年是 AI 编程的"效率分水岭"：Cursor 开发者报告显示，开发者单次 PR 的代码量 p75 同比暴涨 2.5 倍，千行级"超级 PR"占比从 7% 一路涨到 13.8%。但很多团队一边享受 AI 的产出速度，一边痛苦于"AI 总是犯同样的错"——用了错误的包管理器、在禁止 `any` 的代码库引入 `any`、改掉不该动的生成文件。问题不在模型，而在**上下文**。本文用实战代码讲透 2026 年最热的效率杠杆：上下文工程（Context Engineering），让 AI 编程智能体第一次就做对。

一、为什么你的 AI 记不住昨天的事？

先认清一个事实：每个 AI 编程会话都是冷启动。Claude Code、Cursor、Codex 不会记得你昨天纠正过它什么。它不知道你的项目用 `pnpm` 而不是 `npm`，不知道 `src/generated/` 目录神圣不可侵犯，不知道提交前必须跑 `eslint --fix`。

于是循环开始了：你纠正它 → 它改对 → 明天新会话 → 又犯同样的错 → 你再纠正。有团队统计过，这种"反复纠错"消耗的时间，比 AI 节省的时间还多。

2026 年的解法不是更好的 Prompt，而是一个配置层（Configuration Layer）：在仓库里放一份机器可读的规则文件，让每个新会话开始前自动"入职"。这就是 AGENTS.md / CLAUDE.md。

二、AGENTS.md 与 CLAUDE.md：2026 年的"AI 入职文档"

两者的关系很简单：

• **AGENTS.md**：开放标准，被 Claude Code、Cursor、Codex、Windsurf、Gemini CLI 等主流工具共同支持，可跨工具移植；

• **CLAUDE.md**：Anthropic 系工具的专属规则文件，优先级高于 AGENTS.md，支持 `@path` 引用子文件；

• 其他工具各有变体：Copilot 读 `.github/copilot-instructions.md`，Cursor 读 `.cursor/rules/`。

它们不是给人类看的文档，而是给智能体看的工程简报。写得好，AI 产出的代码从"能用"变成"符合团队规范"；写不好，就是摆设。

三、实战一：从零写一份高质量 AGENTS.md

直接给一份可抄的模板，覆盖六大核心领域：

# AGENTS.md — 项目 AI 协作规则 ## 1. 项目概述 - 技术栈：FastAPI 3 + SQLAlchemy 2 + PostgreSQL 16 - 包管理：一律使用 pnpm（禁止 npm/yarn） - 运行环境：Python 3.12，依赖锁定在 pyproject.toml ## 2. 常用命令 - 安装依赖：`pnpm install` - 启动开发服务：`pnpm dev` - 运行测试：`pnpm test`（提交前必须全量通过） - 代码检查：`pnpm lint`（规则见 .eslintrc，禁止绕过） ## 3. 架构约定 - 分层：routes/ → services/ → repositories/，禁止跨层调用 - 数据库迁移：任何 schema 变更必须新增迁移文件，禁止改历史迁移 - 错误处理：统一抛 AppError，禁止裸 raise ## 4. 代码规范（优先级从高到低） 1. 测试必须通过（最高优先级） 2. 禁止在业务代码使用 `any` 类型 3. 所有对外 API 必须写 OpenAPI docstring 4. 命名：函数用 snake_case，组件用 PascalCase ## 5. 禁区（绝不修改） - `src/generated/`：自动生成代码，改了一律还原 - `*.lock` 文件：由锁文件工具管理 - `migrations/versions/`：已发布的迁移文件 ## 6. 工作流 - 修改前先读相关模块的 README - 实现功能必须补单元测试，覆盖率不低于 80% - 完成后执行：lint → test → build，三项全绿才算完成

把这份文件放进仓库根目录，AI 的"犯错率"会肉眼可见地下降——因为它终于知道：这里用 pnpm、这里不许碰、这里要先测。

四、实战二：分层上下文，别把规则写成"小说"

新手常犯的错误：把 AGENTS.md 写成 8000 字巨著。要知道，规则文件是整体加载进上下文的，写太长会稀释注意力、烧 token、降低推理质量。正确做法是三级分层：

repo/ ├── AGENTS.md # 第一级：核心规则，控制在 1500-2000 字以内 ├── docs/ # 第二级：按需加载的详细文档 │ ├── architecture.md │ └── api-conventions.md ├── .cursor/rules/ # 第三级：路径级规则 │ ├── frontend.mdc # 仅作用于 src/frontend/ 下的任务 │ └── db.mdc # 仅作用于 migrations/ 下的任务 └── src/generated/ # 禁区

规则文件里用 `@path` 引用子文档，让 AI渐进式加载：核心规则始终在上下文中，细节文档只在需要时读取。就像操作系统按需换页，而不是一次性把整个磁盘塞进内存。

五、实战三：用 Hooks 把规则变成"强制校验"

规则文件是软约束，AI 可能"看了但没执行"。2026 年更硬核的做法是Hooks（钩子）：在 AI 执行工具前后自动触发校验脚本，不满足条件就拦截。以 Claude Code 为例：

{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "scripts/guard.sh $CLAUDE_FILE_PATHS", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Bash(pnpm test|pnpm lint)", "hooks": [ { "type": "command", "command": "scripts/notify.sh" } ] } ] } }

再配一个简单的守卫脚本 `guard.sh`：

#!/usr/bin/env bash # 禁止修改生成目录：命中直接拦截，让 AI 换个思路 for f in "$@"; do case "$f" in *src/generated/*|*lock*) echo "🚫 禁止修改 $f（生成文件/锁文件），请改源文件后重新生成" exit 1 ;; esac done exit 0

配合 `.claude/settings.json` 里的权限配置（如 `disableModelInvocation` 限制危险命令），团队可以把"禁区"从口头约定变成代码强制——AI 想越界都越不了。

六、实战四：上下文工程 × MCP，补齐"能力"短板

AGENTS.md 解决"知道规矩"，MCP（Model Context Protocol）解决"有手有脚"。把两者结合，AI 才是完整的开发助手：规则文件约束行为，MCP Server 提供工具（查库、发 PR、读文档）。

在 Cursor / Claude Code 的 MCP 配置里加一段：

{ "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:***@localhost:5432/db"] } } }

Context7 让 AI 拉取最新框架文档（解决"训练数据过期"），Postgres MCP 让 AI 先读真实表结构再写 SQL（解决"凭空捏造字段"）。上下文工程管"内"，MCP 管"外"，双管齐下才是完整的效率底座。