代码 Agent 进入一个陌生仓库时常见失败点是项目理解错误。它可能跑错测试命令改到生成文件把业务约定当成普通代码或者绕过团队已经写好的访问层。AGENTS.md 正在成为这类问题的标准答案。它是一份写给 AI 编码代理阅读的项目说明书放在仓库根目录用结构化文字告诉代理这个项目怎么构建代码怎么写测试怎么跑哪些规则需要遵守。它的价值落在上下文转译上把“团队默认知道的规则”变成“机器每次开工前都能读取的约束”。随着 OpenAI、Google、Cursor、Sourcegraph 等工具支持这类项目指令文件AGENTS.md 已经成为主流编码代理能够识别的通用标准。AGENTS.md 应当像项目的操作手册它让代理知道从哪里下手、怎样验证、哪些边界不能碰并把团队的工程约定压缩成可执行的判断规则。30 秒读完的最小样例AGENTS.md 不需要一开始就很长。先把技术栈、命令、目录职责、架构边界、验证要求和禁止事项写清楚代理就能少犯一批低级项目错误。AGENTS.mdProjectNext.js 15 App Router, TypeScript strict mode, pnpm, PostgreSQL.Business logic lives in src/domain. Route handlers stay thin.CommandsInstall: pnpm installDev: pnpm devTest: pnpm testTypecheck: pnpm typecheckBuild: pnpm buildRepository rulessrc/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.WorkflowFor 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 notDo not bypass repository rules, architecture boundaries, verification, or secret handling policies.AGENTS.md Project Instruction Map把仓库知识转成代理可读取、可执行、可验证的工作边界AGENTS.mdmachine-readable project handbookProject Overview技术栈 / 架构模式Repository Rules目录职责 / 文件边界Coding Rules类型 / 命名 / 长度ArchitectureAPI / DB / 状态管理Workflow新功能 / 错误处理Do Not禁止事项 / 风险边界AGENTS.md 的结构应当服务一个目标让代理在行动前先获得项目边界在行动后知道怎样验证结果。描述越接近实际工作流代理越容易少走弯路。AGENTS.md 的六块核心内容项目概述技术栈、运行入口、架构模式。目录约定每个关键目录负责什么哪些目录不能直接改。编码规范类型、命名、文件长度、依赖策略。架构规则API、数据库、状态管理和后台任务的边界。常用模式新功能、bug 修复、数据库变更和错误处理的标准步骤。禁止事项高风险动作和对应替代路径。一、AGENTS.md 先解决项目上下文缺口README 通常写给人看重点是项目介绍、安装说明和使用方式。AI 编码代理需要的是更直接的工作约束改代码前读哪里新增功能按什么路径走哪些目录是生成产物测试失败时优先查哪一层。这类信息过去分散在团队经验、代码评审习惯、CI 配置、历史 PR 和口头约定里。人可以靠经验补齐代理只能靠上下文读取。AGENTS.md 把这些隐性规则放到仓库根目录让每次任务启动时都有一个稳定入口。当前 AGENTS.md 已经被六万级开源仓库采用。对团队来说它把规则来源收回到仓库本身不同编码代理读取同一份项目说明开发者不必为每个工具重复维护一套规则。AGENTS.md 应当回答的第一组问题这个项目是什么技术栈主要运行入口在哪里。代码目录怎样分层哪些目录由人维护哪些目录由工具生成。新功能、修复、测试、构建各自应该走什么标准路径。代理在任何情况下都不应该绕过哪些边界。二、项目概述要让代理快速建立地图AGENTS.md 的开头不需要写成产品介绍。它要快速交代技术事实语言、框架、运行时、包管理器、数据库、架构模式、主要服务边界和部署方式。代理读完后应当知道这个项目大致由哪些层组成。这里的关键是准确和可执行。写“现代化前端项目”没有意义写“Next.js 15 App Router、TypeScript strict mode、Prisma、PostgreSQL、pnpm monorepo”才有用。技术栈越具体代理越容易选对命令和文件。架构模式也要写清楚。项目是分层单体、前后端分离、模块化单仓、插件系统还是事件驱动服务。这个判断会影响代理新增文件的位置、跨层调用方式和测试选择。模块应该写什么写成什么会失效技术栈框架版本、语言模式、包管理器、数据库和测试框架。只写“前端项目”“后端项目”“AI 应用”。架构模式分层单体、模块化单仓、API 网关、插件架构等。只写“架构清晰”“代码解耦”。运行入口开发、构建、测试、类型检查、数据库迁移命令。只让代理自己去猜 package scripts。三、目录结构约定决定代理从哪里下手目录结构部分负责解释每个关键目录的职责。代理需要知道页面入口在哪里领域代码在哪里共享组件和一次性页面组件怎样区分哪些文件由人维护哪些文件由工具产出。生成目录和外部同步目录要特别标注来源。许多代理会看到类型文件、客户端 SDK、迁移产物后直接修改结果下一次生成就被覆盖。目录约定写清“改源头”后续规则只需要引用这个边界。当仓库很大时可以在根目录放全局规则再在子目录放局部 AGENTS.md。根目录说明全局架构和通用命令模块目录说明局部领域规则。这样代理进入支付、认证、报表、插件等不同区域时能读到更贴近当前任务的约束。目录约定的推荐写法src/app页面路由和服务端入口负责请求入口、页面组合和响应组织。src/domain领域逻辑和业务规则新增能力优先在这里建模。src/db数据访问相关代码包含 repository、迁移入口或数据库客户端封装。src/generated工具生成产物不直接手改需要改源 schema 或生成脚本。四、编码规范要写成可判断的约束编码规范需要写成可以执行、可以检查、可以拒绝的约束因为“保持代码整洁”对代理来说是无效指令。比如 TypeScript 开启 strict mode禁止新增 any组件文件超过 300 行要拆分API 入参用 schema 校验。命名约定也要具体。数据库表、接口路由、React 组件、hooks、测试文件、迁移文件各自使用什么命名规则。代理遇到新文件时会根据这些规则保持项目一致性。文件长度限制提供的是重构信号。长文件往往意味着职责混在一起。AGENTS.md 可以写明新增逻辑优先放到已有领域函数或服务里当文件超过阈值时先寻找项目内已有拆分模式再抽取小函数或模块。AGENTS.md 片段示例Coding rulesTypeScript 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.NamingReact 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 生成”。代理看到替代路径才更容易做对。架构规则的三条主线调用方向路由层只做认证、入参校验、服务调用和结构化错误返回复杂流程进入 domain 或 service。数据流向数据库读写统一经过访问层事务边界集中管理后台任务和工具脚本也走同一套入口。状态归属服务端状态用查询缓存本地交互状态放组件或轻量 store跨页面共享状态需要说明来源和失效策略。六、常用模式让新功能有固定路径新增一个 API、增加一个页面、修一个权限 bug、加一个数据库字段、补一条测试这些高频动作在项目里通常都有固定路径。把路径写进 AGENTS.md代理就不用从零推断“该先改 schema 还是先改页面”也不用通过大量搜索猜测试文件放在哪里。错误处理模式也值得单独写。项目使用抛异常、Result 类型、结构化错误码还是 HTTP problem details。代理如果不知道错误语义就会在不同层写出不一致的失败返回。任务推荐路径验证方式新增功能先读相邻模块再建领域函数最后接 API 或 UI。单元测试加集成测试必要时跑端到端路径。修复 bug先复现再定位根因再加回归用例再改实现。失败用例先红后绿保留原始复现路径。数据库变更改 schema生成迁移更新 repository 和测试。迁移可执行相关读写测试通过。错误处理按项目错误类型返回保留可行动错误信息。覆盖成功、失败、权限和边界输入。七、禁止事项要给出明确替代路径禁止事项是一组风险边界写法要克制。目录职责、编码规范和架构边界已经建立后Do not 清单只负责把高风险动作、风险原因和正确替代路径放在一起。高价值的禁止事项通常来自事故和代码评审经验。它们不只是“不要做什么”还要告诉代理改走哪条路径扩展访问层、修改 schema、使用现有工具、修复真实实现、替换敏感样本。这类规则的作用是提前拦截“看起来省事”的错误路径。代理会寻找最短路径完成任务AGENTS.md 需要让它知道哪些最短路径会破坏项目结构。Do not 清单示例新查询不要绕过访问层需要新能力时扩展 repository 或 store。生成产物不要直接手改需要调整输出时修改 schema 或生成脚本。简单格式化、日期比较、字符串转换不要先加依赖优先检查标准库和项目现有工具。测试失败不要降低断言强度先修复实现必要时补充明确的边界解释。secret、token、客户数据不要进入源码、日志、截图或测试夹具使用脱敏样本和环境变量。八、把 AGENTS.md 当作可维护的工程资产AGENTS.md 写完后也会过期。框架升级、目录调整、测试命令变更、数据库访问层重构都会让旧规则变成噪声。项目应当把它纳入代码评审当 PR 改变开发入口或架构边界时同步更新 AGENTS.md。一种常见实践是把规则分成三层。根目录写长期稳定规则模块目录写局部规则任务文档写一次性上下文。不要把临时任务状态塞进根目录也不要把全局架构规则藏在某个子模块里。评估一份 AGENTS.md 是否有效可以看代理行为有没有变化它是否跑对命令是否少改错目录是否按项目模式加测试是否在完成前给出验证证据。规则只有影响行动才算写进了系统。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】