工程实践中给 AI Coding一本项目说明书

代码 Agent 进入一个陌生仓库时，常见失败点是项目理解错误。它可能跑错测试命令，改到生成文件，把业务约定当成普通代码，或者绕过团队已经写好的访问层。

AGENTS.md 正在成为这类问题的标准答案。它是一份写给 AI 编码代理阅读的项目说明书，放在仓库根目录，用结构化文字告诉代理：这个项目怎么构建，代码怎么写，测试怎么跑，哪些规则需要遵守。

它的价值落在上下文转译上：把“团队默认知道的规则”变成“机器每次开工前都能读取的约束”。随着 OpenAI、Google、Cursor、Sourcegraph 等工具支持这类项目指令文件，AGENTS.md 已经成为主流编码代理能够识别的通用标准。

AGENTS.md

Project
Next.js 15 App Router, TypeScript strict mode, pnpm, PostgreSQL.
Business logic lives in src/domain. Route handlers stay thin.

Commands
Install: pnpm install
Dev: pnpm dev
Test: pnpm test
Typecheck: pnpm typecheck
Build: pnpm build

Repository rules
src/app contains routes and server actions.
src/domain contains business rules.
src/db contains all database access.
src/generated is generated output and must not be edited directly.

Workflow
For bug fixes, reproduce first, add a regression test, then change code.
For new features, copy the nearest existing module pattern before adding files.
Before completion, run the narrow test first, then the relevant full check.

Do not
Do not bypass repository rules, architecture boundaries, verification, or secret handling policies.

一、AGENTS.md 先解决项目上下文缺口

README 通常写给人看，重点是项目介绍、安装说明和使用方式。AI 编码代理需要的是更直接的工作约束：改代码前读哪里，新增功能按什么路径走，哪些目录是生成产物，测试失败时优先查哪一层。

这类信息过去分散在团队经验、代码评审习惯、CI 配置、历史 PR 和口头约定里。人可以靠经验补齐，代理只能靠上下文读取。AGENTS.md 把这些隐性规则放到仓库根目录，让每次任务启动时都有一个稳定入口。

当前 AGENTS.md 已经被六万级开源仓库采用。对团队来说，它把规则来源收回到仓库本身：不同编码代理读取同一份项目说明，开发者不必为每个工具重复维护一套规则。

二、项目概述要让代理快速建立地图

AGENTS.md 的开头不需要写成产品介绍。它要快速交代技术事实：语言、框架、运行时、包管理器、数据库、架构模式、主要服务边界和部署方式。代理读完后，应当知道这个项目大致由哪些层组成。

这里的关键是准确和可执行。写“现代化前端项目”没有意义；写“Next.js 15 App Router、TypeScript strict mode、Prisma、PostgreSQL、pnpm monorepo”才有用。技术栈越具体，代理越容易选对命令和文件。

架构模式也要写清楚。项目是分层单体、前后端分离、模块化单仓、插件系统，还是事件驱动服务。这个判断会影响代理新增文件的位置、跨层调用方式和测试选择。

三、目录结构约定决定代理从哪里下手

目录结构部分负责解释每个关键目录的职责。代理需要知道：页面入口在哪里，领域代码在哪里，共享组件和一次性页面组件怎样区分，哪些文件由人维护，哪些文件由工具产出。

生成目录和外部同步目录要特别标注来源。许多代理会看到类型文件、客户端 SDK、迁移产物后直接修改，结果下一次生成就被覆盖。目录约定写清“改源头”，后续规则只需要引用这个边界。

当仓库很大时，可以在根目录放全局规则，再在子目录放局部 AGENTS.md。根目录说明全局架构和通用命令，模块目录说明局部领域规则。这样代理进入支付、认证、报表、插件等不同区域时，能读到更贴近当前任务的约束。

四、编码规范要写成可判断的约束

编码规范需要写成可以执行、可以检查、可以拒绝的约束，因为“保持代码整洁”对代理来说是无效指令。比如 TypeScript 开启 strict mode，禁止新增 any，组件文件超过 300 行要拆分，API 入参用 schema 校验。

命名约定也要具体。数据库表、接口路由、React 组件、hooks、测试文件、迁移文件，各自使用什么命名规则。代理遇到新文件时，会根据这些规则保持项目一致性。

文件长度限制提供的是重构信号。长文件往往意味着职责混在一起。AGENTS.md 可以写明：新增逻辑优先放到已有领域函数或服务里；当文件超过阈值时，先寻找项目内已有拆分模式，再抽取小函数或模块。

AGENTS.md 片段示例

Coding rules
TypeScript runs in strict mode.
Do not introduce any unless a local type boundary makes it unavoidable.
Prefer existing helpers in src/lib before adding new utilities.
Keep files under 300 lines when practical. Split by responsibility, not by random utility buckets.

Naming
React components use PascalCase.
Hooks start with use.
Test files follow feature-name.test.ts.
Database access functions end with Repository or Store.

五、架构规则要守住跨层边界

架构边界是 AGENTS.md 中特别关键的部分。AI 代理擅长局部补代码，也容易为了让当前测试通过而穿透分层。比如在页面里直接写 SQL，在 API 路由里堆满业务规则，绕过状态管理约定，或者把临时数据放进全局状态。

目录约定回答“代码放在哪里”，架构规则回答“代码怎样互相调用”。高风险边界通常集中在 API 路由、数据库访问和状态管理。API 路由决定输入输出和权限校验，数据库访问决定一致性和审计能力，状态管理决定前端复杂度和可调试性。

规则要给出正向路径。比如在一个使用 Prisma ORM 的项目中，只写“不要乱写 SQL”不够；还要写“所有数据库访问通过 Prisma repository 层，事务逻辑放在 service 层，迁移通过 prisma migrate 生成”。代理看到替代路径，才更容易做对。

六、常用模式让新功能有固定路径

新增一个 API、增加一个页面、修一个权限 bug、加一个数据库字段、补一条测试，这些高频动作在项目里通常都有固定路径。把路径写进 AGENTS.md，代理就不用从零推断“该先改 schema 还是先改页面”，也不用通过大量搜索猜测试文件放在哪里。

错误处理模式也值得单独写。项目使用抛异常、Result 类型、结构化错误码，还是 HTTP problem details。代理如果不知道错误语义，就会在不同层写出不一致的失败返回。

七、禁止事项要给出明确替代路径

禁止事项是一组风险边界，写法要克制。目录职责、编码规范和架构边界已经建立后，Do not 清单只负责把高风险动作、风险原因和正确替代路径放在一起。

高价值的禁止事项通常来自事故和代码评审经验。它们不只是“不要做什么”，还要告诉代理改走哪条路径：扩展访问层、修改 schema、使用现有工具、修复真实实现、替换敏感样本。

这类规则的作用是提前拦截“看起来省事”的错误路径。代理会寻找最短路径完成任务，AGENTS.md 需要让它知道哪些最短路径会破坏项目结构。

八、把 AGENTS.md 当作可维护的工程资产

AGENTS.md 写完后也会过期。框架升级、目录调整、测试命令变更、数据库访问层重构，都会让旧规则变成噪声。项目应当把它纳入代码评审：当 PR 改变开发入口或架构边界时，同步更新 AGENTS.md。

一种常见实践是把规则分成三层。根目录写长期稳定规则，模块目录写局部规则，任务文档写一次性上下文。不要把临时任务状态塞进根目录，也不要把全局架构规则藏在某个子模块里。

评估一份 AGENTS.md 是否有效，可以看代理行为有没有变化：它是否跑对命令，是否少改错目录，是否按项目模式加测试，是否在完成前给出验证证据。规则只有影响行动，才算写进了系统。

AGENTS.md 推荐骨架

Project overview
Tech stack, runtime, package manager, database, architecture pattern.

Repository structure
Directory responsibilities, generated files, module boundaries.

Commands
Install, dev, test, lint, typecheck, build, migration.

Coding rules
Type mode, naming, file size, dependency policy, formatting.

Architecture rules
API routes, database access, state management, background jobs.

Common workflows
New feature, bug fix, schema change, error handling, verification.

Do not
Forbidden actions, risk reason, correct replacement path.

Definition of done
Required checks before claiming the task is complete.