给 AI 编码助手补上项目上下文

前面三篇讲的是「把环境约定写进仓库」。这些约定其实还有一个常被忽略的读者:AI 编码助手。它没有团队记忆,也不会主动去翻你的 wiki——它只能读仓库里有的东西。上下文给对了,AI 生成的代码会自然贴合项目;给错或没给,它只能按训练数据里的通用习惯猜。

本文是「协作机制」板块的第一篇:给 AI 编码助手补上项目上下文,讲清楚上下文该放在哪、写什么、不该写什么,以及怎么把「上下文(建议)」和「强制约束」分开——强制约束由下一篇把检查左移到提交前承接。完整导航见文末。

一、AI 助手缺的不是能力,是上下文

大模型有通用知识,但缺项目私有信息:构建命令、目录约定、技术栈、命名习惯、架构决策、安全红线。缺了这些,它的表现会很稳定地"跑偏":

  • 生成代码风格漂移,和仓库既有风格对不上;
  • 重复问你已经回答过的问题;
  • 引入项目并不使用的库,或绕开既有的 lint / 构建 / 测试流程;
  • 把代码放进"通用位置",而不是项目约定的位置。

AI 的上下文来源主要有三类:对话(一次性、不可复用)、工具(让 AI 能查能跑)、仓库文件(最稳定、可共享、可版本化)。其中仓库文件是唯一能"一次写好、长期复用、团队共享"的来源——这正是前面几篇把约定写进仓库的意义:那些配置文件同时就是 AI 的上下文。

二、上下文放在哪:三种主流约定

工具上下文文件作用域加载方式
通用(跨 agent)AGENTS.md项目 / 子目录多数 agent 直接读取
Claude CodeCLAUDE.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 是比"把信息抄进规则文件"更合适的方案——前者是能力,后者是知识。

五、落地清单

  1. 建一个 AGENTS.md(或主用 agent 的记忆文件),先写构建 / 测试命令与目录约定——这两类收益最大。
  2. 之后每遇到"第二次解释同一件事",就补一条,让它保持"活文档"。
  3. 代码风格交给 linter / formatter,规则文件只写工具表达不了的项目约定。
  4. 需要"强制"的(安全红线、不可修改的目录)放 hooks,不要只写进规则文件。
  5. 大仓库用嵌套 AGENTS.md / 路径作用域规则,避免一个巨型文件。
  6. 定期清理冲突与过期指令,把规则当代码一样 review。
  7. 需要 AI 访问内部工具或数据时,评估接入 MCP。

参考链接

系列文章


给 AI 编码助手补上项目上下文
https://bubao.github.io/posts/2a6f9c4b.html
作者
一念
发布于
2026年11月21日
许可协议