给 AI 编码助手补上项目上下文
前面三篇讲的是「把环境约定写进仓库」。这些约定其实还有一个常被忽略的读者:AI 编码助手。它没有团队记忆,也不会主动去翻你的 wiki——它只能读仓库里有的东西。上下文给对了,AI 生成的代码会自然贴合项目;给错或没给,它只能按训练数据里的通用习惯猜。
本文是「协作机制」板块的第一篇:给 AI 编码助手补上项目上下文,讲清楚上下文该放在哪、写什么、不该写什么,以及怎么把「上下文(建议)」和「强制约束」分开——强制约束由下一篇把检查左移到提交前承接。完整导航见文末。
一、AI 助手缺的不是能力,是上下文
大模型有通用知识,但缺项目私有信息:构建命令、目录约定、技术栈、命名习惯、架构决策、安全红线。缺了这些,它的表现会很稳定地"跑偏":
- 生成代码风格漂移,和仓库既有风格对不上;
- 重复问你已经回答过的问题;
- 引入项目并不使用的库,或绕开既有的 lint / 构建 / 测试流程;
- 把代码放进"通用位置",而不是项目约定的位置。
AI 的上下文来源主要有三类:对话(一次性、不可复用)、工具(让 AI 能查能跑)、仓库文件(最稳定、可共享、可版本化)。其中仓库文件是唯一能"一次写好、长期复用、团队共享"的来源——这正是前面几篇把约定写进仓库的意义:那些配置文件同时就是 AI 的上下文。
二、上下文放在哪:三种主流约定
| 工具 | 上下文文件 | 作用域 | 加载方式 |
|---|---|---|---|
| 通用(跨 agent) | AGENTS.md | 项目 / 子目录 | 多数 agent 直接读取 |
| Claude Code | CLAUDE.md、.claude/rules/*.md | 组织 / 用户 / 项目 / 路径 | 启动时加载,可按路径按需 |
| Cursor | .cursor/rules/*.mdc | 项目 / 团队 / 用户 | 按规则类型与 globs 决定 |
1. AGENTS.md:跨 agent 的开放格式
AGENTS.md 是一个开放的 Markdown 约定(现由 Linux Foundation 下的 Agentic AI Foundation 托管),目标是"一个文件、多个 agent 通用"。它的定位很清晰:README 给人看,AGENTS.md 给 agent 看——README 负责快速上手与项目描述,AGENTS.md 负责构建步骤、测试方式、代码约定等"放进来会让 README 变杂"的内容。
两个实用特性:
- 嵌套:可以在子目录放各自的
AGENTS.md,agent 读最近的那个,子目录指令优先; - 无强制格式:就是普通 Markdown,标题随意,agent 解析文本。
2. Claude Code:CLAUDE.md 与路径作用域规则
Claude Code 用 CLAUDE.md 承载持久指令,分四个作用域:组织级(托管策略)、用户级(~/.claude/CLAUDE.md)、项目级(./CLAUDE.md 或 ./.claude/CLAUDE.md,随仓库共享)、本地级(CLAUDE.local.md,个人用、不进版本库)。它也会读取仓库里的 AGENTS.md 作为项目指令,所以两者可以共存。
更细的粒度可以用 .claude/rules/:每个规则一个 Markdown 文件,用 paths 限定生效的文件类型,只有操作匹配文件时才加载,省上下文。Claude Code 还有一个 auto memory 机制,会让模型根据你的纠正自动记笔记,与手写规则互补。
3. Cursor:.cursor/rules
Cursor 的项目规则放在 .cursor/rules/*.mdc,带 frontmatter,分四种应用方式:始终生效、按描述智能生效、按 globs 匹配文件、手动 @ 引用。Cursor 同样支持 AGENTS.md(项目根与子目录)。
选型建议:如果团队里不止一种 agent,用
AGENTS.md做兜底——它已被 Codex、Jules、Cursor、Claude Code、VS Code 等广泛支持;主用的 agent 再叠加它自己的规则文件(如.claude/rules)做更细的控制。
三、写什么、不写什么
规则文件的效果取决于写法。官方文档给出的原则高度一致:指令要具体到可验证。
该写的:
- 构建 / 测试 / 运行的准确命令(如
pnpm test、go test -race ./...); - 目录与命名约定(如"API handler 放
src/api/handlers/"); - 架构决策与"始终 / 绝不"规则(如"不直接改
dist/"); - 安全红线、容易踩的坑。
Claude Code 文档里有一组对照,很说明问题:
- 写"用 2 空格缩进",而不是"代码格式良好";
- 写"提交前运行
npm test",而不是"测试你的改动"; - 写"API handler 放在
src/api/handlers/“,而不是"保持文件有序”。
不该写的:
- 整个代码风格指南——Cursor 文档明确建议:风格交给 linter,AI 本来就知道通用风格(“Copying entire style guides: Use a linter instead”);
- 通用工具知识(AI 知道 npm、git 怎么用);
- 罕见的边缘情况——规则越多,越容易过期;
- 大段代码复制——改为在规则里引用文件(如
@service-template.ts),让 AI 需要时去读,避免规则与代码脱节。
其它几条经验:
- 控制长度:CLAUDE.md 建议单个文件控制在 200 行以内,Cursor 规则建议 500 行以内;太长会稀释上下文、降低遵循度。
- 保持一致性:两条指令冲突时,模型可能随意选一条;定期清理过期/冲突内容(Claude Code 提供
/doctor prompt-audit做这类审计)。 - 从"重复的解释"开始:当你发现自己在对话里第二次解释同一件事,就该把它写进规则文件。
四、上下文 ≠ 强制:把「建议」和「约束」分开
这是最容易误解的一点:规则文件是上下文,不是强制配置。Claude Code 文档说得很直白——这些文件是"context, not enforced configuration",模型可能不遵循;要真正阻止某个动作,得用 hooks(如 PreToolUse)。
所以上下文与约束要分工:
- 上下文(AGENTS.md / CLAUDE.md / rules):让 AI"知道"项目约定,影响它生成与判断的方向;
- 强制约束(linter / formatter / Git hooks / CI):保证"做到",不管是谁(人还是 AI)写的代码,规则一视同仁。
举个例子:在 AGENTS.md 里写"提交前请跑 lint"是建议;把 lint 挂到 lefthook / husky 或 CI 才是卡口。建议负责效率,卡口负责底线。
此外,AI 光有文本上下文还不够,它还需要能查、能跑、能访问内部系统。这就是 MCP(Model Context Protocol) 的定位:一个开放标准,把数据源、工具、工作流接入 AI 应用,可以理解为"AI 的 USB-C"。当 AI 需要读构建日志、查数据库、调内部 API 时,MCP 是比"把信息抄进规则文件"更合适的方案——前者是能力,后者是知识。
五、落地清单
- 建一个
AGENTS.md(或主用 agent 的记忆文件),先写构建 / 测试命令与目录约定——这两类收益最大。 - 之后每遇到"第二次解释同一件事",就补一条,让它保持"活文档"。
- 代码风格交给 linter / formatter,规则文件只写工具表达不了的项目约定。
- 需要"强制"的(安全红线、不可修改的目录)放 hooks,不要只写进规则文件。
- 大仓库用嵌套
AGENTS.md/ 路径作用域规则,避免一个巨型文件。 - 定期清理冲突与过期指令,把规则当代码一样 review。
- 需要 AI 访问内部工具或数据时,评估接入 MCP。
参考链接
- AGENTS.md(跨 agent 开放格式)
- Claude Code:How Claude remembers your project
- Cursor:Rules
- Model Context Protocol(MCP)
系列文章
- 总述:代码规范工具到底在解决什么问题
- 环境配置:Node.js · Go · C/C++
- 协作机制:给 AI 编码助手补上项目上下文 · 把检查左移到提交前 · 依赖治理 · 命令收口
- 一致性与评审:本地开发与 CI 的一致性 · AI 生成代码的评审清单
