先说明一个判断大语言模型辅助编码真正提升代码质量的关键不一定在于模型本身有多强而在于你通过什么方式把项目的“隐性规则”告诉它。普通提问是一次性的模型只能靠临时对话里的少量上下文做猜测项目级提示文件则把项目的构建方式、代码风格、目录边界、常见坑位写下来让每一次 AI 交互都站在同一个信息基线上。agent.md 就是这样一个项目级提示文件。它放在项目根目录专门给支持读取项目上下文的 AI 编程助手读。适合下面这些人经常让 AI 生成代码、改 bug、补测试但发现结果时好时坏的人团队里多个成员共用 AI 助手但每个人写出的代码风格不一致的人项目大了以后模型总是“记不住”项目约定反复给出通用答案的人。这篇文章会把 agent.md 拆开来讲它解决什么问题怎么写才有效怎么验证它真的提升了代码质量以及落坑时怎么排查。下面直接按实操顺序过一遍。1. 先确认 agent.md 解决的是“上下文缺失”和“规则失忆”问题1.1 大语言模型辅助编码时最常见的问题不是“不会写”而是“不知道你的项目怎么写的”单独让 AI 写一个 Python 模块或者让 AI 生成一段前端组件它往往能写得很像样。但你把它放到真实项目里问题就来了它不知道你的项目用不用类型注解不知道变量命名是 snake_case 还是 camelCase不知道测试命令是 pytest 还是 unittest不知道错误处理是抛出异常还是返回结果对象。这些信息没有传递进去AI 就只能按“大多数项目”的经验来写。我在日常写代码时有一个明显感受同一个模型同一个对话上下文如果你在提问前先给它看项目里的关键文件它输出的代码质量会完全不一样。但如果每个问题都手动粘贴文件成本太高而且粘贴的内容还可能过时。agent.md 就是为了解决这个“每次都要重新描述项目规则”的问题。1.2 agent.md 并非常规 README它更像一份“给 AI 的项目操作手册”很多人会把 agent.md 误解成 README 的替代品。实际上它们服务对象不同README 给人类开发者看主要介绍项目是什么、如何安装、如何使用。agent.md 给 AI 编程助手看主要说明项目如何构建、如何测试、有哪些约束、有哪些坑。README 可以写得很详细包含背景故事和使用截图agent.md 应该尽量简洁、指令化、可直接执行。你可以把 agent.md 理解成“操作手册”或者“部署 checklist”。它不解释“为什么”只说明“在这里应该怎么做”。1.3 为什么项目级提示文件比单次 Prompt 更可靠单次 Prompt 像是临时找了一个熟悉项目的顾问但他只能靠你此刻递过去的那几句话判断。项目级提示文件则像给这个顾问发了一本工作手册每次进项目先把手册读一遍。可靠性主要体现在三方面稳定性无论谁发起对话无论什么时候发起项目级提示文件都能提供一致的背景信息。可维护性项目规范变化时只改 agent.md 一处后续所有 AI 交互都能用上新规则。可追溯性如果 AI 输出不符合预期你可以检查 agent.md 是否写清楚而不是反复调整一次性的提问模板。所以项目级提示文件不是“多一个配置文件”而是把团队的知识沉淀和 AI 使用方式绑定在一起的工作机制。2. agent.md 的核心内容给 AI 搭好“项目上下文操作规则”两套信息2.1 项目上下文里必须包含哪些基础信息一份可用的 agent.md 至少应该覆盖下面几个部分信息类型要写什么示例项目简介一句话说明项目目标用户管理系统负责注册、登录、权限管理技术栈语言、框架、关键依赖Python 3.11 FastAPI PostgreSQL目录结构告诉 AI 哪些目录放什么src/放业务代码tests/放测试构建/运行命令如何启动项目python -m app.api测试命令如何执行测试pytest tests/ -v代码规范命名、格式、类型注解使用类型注解变量使用 snake_case异常处理如何处理错误服务层抛出领域异常控制器捕获转 HTTP 错误约定和限制项目特有约束不直接操作数据库必须通过 repository 层这些内容不一定要全部写完但前三项建议必须写。如果项目还很小写个简单的三行也能用技术栈、启动命令、测试命令。2.2 操作规则明确 AI 在生成代码时的“行为边界”除了基本信息agent.md 还需要规定 AI 在生成、修改代码时应该怎么做。这类“行为规则”对代码质量影响很大。例如## 代码生成规则 - 所有新增模块必须在 src/ 下创建不新建顶层目录。 - 函数和变量使用 snake_case类名使用 PascalCase。 - 所有外部依赖用于生产环境时需要添加到 pyproject.toml并在 PR 描述里说明。 - 不要修改数据库迁移文件除非任务明确要求。 - 错误处理统一使用自定义异常不要随意抛 RuntimeError。 - 新增公共函数需要补充 docstring 和类型注解。 - 生成测试时优先使用 pytest fixture不使用复杂类继承。行为规则越具体AI 的输出越容易符合预期。如果你只写“请写出高质量代码”模型仍然不知道什么是高质量。2.3 实用提示不是把 agent.md 写成百科全书而是写成“决策辅助信息”很多初写 agent.md 的人容易犯一个错把项目所有细节都塞进去。结果文件超过几千行AI 读取时要么截断要么被大量不相关内容分散注意力。我的建议是agent.md 只写“影响代码生成决策”的信息。哪些信息会影响决策AI 需要知道入口文件和函数在哪里。AI 需要知道测试框架和运行方式。AI 需要知道项目禁止什么写法。AI 不需要知道你的数据库密码不需要知道某个历史版本为什么失败。一句话写“规则”和“命令”不写“故事”和“流程”。3. 从零搭建 agent.md先写出最小可用版本再逐步迭代3.1 用 15 分钟写出第一版不要追求完整第一次写 agent.md 时不需要考虑太多。找到项目根目录新建agent.md先按模板写一个最简版本# Agent 使用手册 ## 项目概述 这是一个基于 FastAPI 的图书管理 API。 功能包括图书录入、查询、借还、用户管理。 ## 技术栈 - Python 3.11 - FastAPI - SQLAlchemy 2.0 - PostgreSQL - Pytest ## 常用命令 - 安装依赖pip install -e .[dev] - 启动服务uvicorn app.main:app --reload - 运行测试pytest tests/ -v - 生成迁移alembic revision --autogenerate -m message - 执行迁移alembic upgrade head ## 目录结构 - app/应用主目录 - app/models/SQLAlchemy 模型 - app/schemas/Pydantic 请求/响应模型 - app/api/路由和接口 - app/services/业务逻辑 - app/repositories/数据访问 - tests/测试代码 ## 代码规范 - 所有业务逻辑写在 services 层不要在 api 层写复杂判断。 - 数据库操作必须通过 repositories 层不直接使用 Session。 - 模型统一使用 SQLAlchemy 2.0 的 Mapped 和 mapped_column 写法。 - 函数必须加类型注解。 - 错误处理使用自定义异常在全局异常处理器中转换 HTTP 响应。 ## 任务注意事项 - 新增 API 时需要同时添加 Pydantic schema、repository 方法、service 方法和测试。 - 修改模型字段时需要生成迁移文件。 - 不要删除旧迁移文件。 - 测试使用 pytest不使用 unittest。这个版本已经很可用了。它给 AI 提供了足够的约束信息。3.2 实际使用时在 Agent 对话里主动提到 agent.md有些 AI 编程工具或模型不一定会自动加载项目根目录的 agent.md。这时候你可以在一次对话开始时先输入一条指令例如请先阅读项目根目录下的 agent.md并严格遵循其中的项目规则。之后的所有回答都需要基于该文件。如果工具支持 rules 或 context 配置也可以把 agent.md 配置到自动加载列表中。不同工具的名称不同但原理一致让模型在开始任务前拿到这份文件。3.3 根据实际反馈迭代第二版、第三版第一版 agent.md 通常只能覆盖最常见规则。真正有价值的版本来自迭代。我在实际过程中会记录这些情况AI 生成的代码不符合项目结构比如在错误目录里建文件。AI 把测试写成了单元测试风格而项目期望集成测试风格。AI 使用了不存在的依赖或者没有把新依赖写入配置。AI 在修改接口时遗漏了参数校验。每遇到一次我就把对应的规则补充进 agent.md。比如“新增接口必须包含请求参数校验”“测试文件统一放在 tests/integration 下不使用 unittest”。这样每迭代一次AI 的“失误率”都会下降一点。4. 怎样验证 agent.md 真的提升了代码质量4.1 别凭感觉判断先建立“质量信号”很多人搞完 agent.md 后凭感觉说“效果好了”。但代码质量提升需要可观测的信号。推荐几种简单可操作的验证方式修改返工率同一个需求AI 第一次生成后需要人工修改才能合并的比例是否下降。规范符合度生成的代码是否严格遵循了 agent.md 中的规则比如类型注解、目录结构、异常处理。测试通过率让 AI 写测试观察测试通过率以及测试是否覆盖关键路径。上下文重复率每次提问时你是否还需要反复解释项目背景。如果不需要了说明 agent.md 起了作用。4.2 用一组小任务做 A/B 对照最直观的验证方式是对照实验。拿两个类似的小需求一个在不使用 agent.md 的情况下完成另一个在使用 agent.md 的情况下完成然后对比生成代码是否符合项目规范。代码风格是否与现有代码一致。构建/测试命令是否能直接跑通。需要人工纠正的次数。不需要统计得像严谨论文只要记录几次就能看出差异。我经常遇到的对比是没有 agent.md 时模型可能生成一个独立的脚本文件而不会融入项目分层有 agent.md 时它会主动引用现有目录并按照项目已有模式写代码。4.3 判断标准要落到“能不能合并到主干”对实际项目来说代码质量的最终标准是能否合并主干。agent.md 的价值在于减少“为修复问题而产生的额外沟通成本”。可以记录修复一轮问题所需的对话轮次没有 agent.mdAI 生成了代码你指出目录不对它重新生成你又指出缺少测试它再补再指出命名风格不对再改。有 agent.mdAI 一次生成的代码已经考虑了目录、测试和风格你只需要做少量调整。这个对比是最实用的判断指标。如果你的团队已经有代码评审可以重点关注 agent.md 引入前后“评审意见中关于规范和结构类问题”的数量。5. 更进一步的玩法把 agent.md 融入团队和批量工作流5.1 每个项目维护一个 agent.md在代码评审时也把它纳入审查当项目有多个开发者时agent.md 本身也应该像代码一样被评审和维护。建议把 agent.md 的变更放在 Pull Request 里一起提交至少要有一次 review。因为一旦 agent.md 写错所有 AI 生成的代码都会跟着错。评审 agent.md 时可以关注命令是否准确可以直接执行。目录结构是否和实际一致。规则是否过于严苛导致 AI 无法完成常规任务。是否有相互矛盾的规则。5.2 多个项目统一管理用模板 差异覆盖对于同时维护多个项目的人来说每个项目都从零写 agent.md 很繁琐。可以建立一个项目模板初始内容包含通用的工程规范然后每个项目再补充自己的技术栈和规则。例如通用模板可以包含## 代码生成通用规则 - 新增文件前先检查是否已有同类型文件。 - 不要删除现有文件。 - 使用已有依赖不额外引入新依赖除非任务要求。 - 生成代码需要附带单元测试。 - 所有公开函数需要 docstring。项目特定部分则写## 项目订单系统 - 使用 Django。 - 数据库访问通过 ORM不写原生 SQL。 - 新增订单状态变更必须记录审计日志。这种“通用模板 项目差异”的结构维护成本低又保留了项目的特异性。5.3 子目录级 agent.md模块内提示文件如果某个项目特别大根目录的 agent.md 可能覆盖不了所有模块细节。可以考虑在子目录里再放一个局部的提示文件例如src/payment/agent.md说明这个模块的隐藏约束比如“支付金额使用分存储不使用浮点数”“回调接口必须做签名验证”。AI 工具是否支持读取多个层级的提示文件取决于具体实现。即使不支持你仍然可以在根目录 agent.md 中引用子目录文件让模型在相关任务发生时主动去查找。不过要注意过多的子文件会增大检索成本建议只在核心复杂模块中使用。5.4 与 CI 或代码检查工具配合agent.md 本身是一个文本文件CI 不会自动运行它。但你可以写一个简单的检查脚本确保 agent.md 中的命令有效、路径存在、文件引用正确。比如用 Python 写一个小脚本扫描 agent.md 中出现的命令并在当前项目里做静态检查。不需要多复杂关键是防止 agent.md 随着项目演进而过时。更实际的做法是在代码评审中要求涉及命令变更或目录结构调整时同步更新 agent.md。我在团队里见过最典型的问题就是 agent.md 写完就没人管半年后命令全变了AI 照着旧命令跑反而降低了效率。所以把 agent.md 当成“活文档”而不是“一次性交付物”这一点非常重要。6. 避坑清单为什么有些项目用了 agent.md 还是没效果6.1 模型根本没读到 agent.md先检查上下文注入方式最容易被忽略的问题是你写了 agent.md模型却不一定会自动读取。很多 AI 编程助手只在特定模式或设置下才会加载项目规则文件。你需要确认你的工具是否支持自动加载项目根目录文件。如果不支持是否需要在对话里手动指定。如果支持内容是否被截断了。排查顺序先看 agent.md 文件是否真的在项目根目录。再确认文件名是否有拼写错误。然后在一次对话中让模型复述 agent.md 里的规则比如问“我的测试命令是什么”看它能否回答。如果回答不出来说明没有加载需要调整工具配置或手动指定。6.2 agent.md 写得过于冗长或过于抽象导致模型“读过但用不上”文件太长模型可能注意不到关键规则文件太短模型缺少足够约束。有一些常见信号AI 生成的代码总是偏离规范但规则明明写在 agent.md 里。这时要检查规则是不是写得不够直接。比如“保持高质量代码”太抽象“所有接口必须使用 Pydantic 校验”更具体。规则里存在大量与当前任务无关的内容AI 容易被噪音干扰。建议按任务类型分区例如“新增接口时要看这里”“修改数据库时看这里”让模型在遇到相关任务时可以定位。6.3 把 agent.md 当成万能钥匙忽略了模型本身的能力边界agent.md 能大幅改善上下文一致性和规范遵循度但不能让模型突然学会一个完全不熟悉的框架也不能完全避免逻辑错误。对复杂业务逻辑、需要全局推理的改动仍然需要人工设计架构、人工做逻辑判断。此外agent.md 不适合写这些内容认证信息、密钥、服务器地址。临时性的操作流程如某个一次性迁移的注意事项。纯粹的历史背景、团队八卦、决策讨论记录。与代码生成无关的团队流程。agent.md 的目标是提升代码质量不是替代知识库。需要沉淀更多项目文档时放 docs 或 README不要在 agent.md 里堆。6.4 频繁改动 agent.md导致模型输出不稳定如果每次对话前 agent.md 都被修改AI 在不同时间点给出的代码风格可能会有差异。建议对 agent.md 的变更采用“周期性更新”策略比如一批重构完成后集中更新避免一天改三次。尤其在一个功能迭代中不要中途频繁调整规则否则会让 AI 前后判断不一致也会让人类开发者困惑。6.5 不要完全依赖 agent.md保留代码评审机制agent.md 是辅助工具不是保险。即便 AI 严格遵循 agent.md 的项目规范仍然可能产生逻辑问题、边界条件遗漏、性能隐患。代码评审、单元测试、持续集成都不能取消。agent.md 的真正作用是把“AI 生成代码的质量基线”提高让代码评审关注“真正有挑战的设计问题”而不是浪费在“目录结构不对、缺少 docstring、测试风格不统一”这些重复问题上。7. 最后的实操建议先把单个场景跑稳再扩大使用范围如果你刚接触 agent.md不要立刻把它推广到所有项目。我建议先选一个中等规模、规则明确的项目按下面顺序试一周写一个不超过 100 行的最小版 agent.md。在一个具体任务里让 AI 先读 agent.md再做改动。试完记录一次前后对比找出不符合预期的点补充进 agent.md。觉得有效后再把它复制到其他项目并逐步加入更细的业务规则。这看起来只是多了一个文件但实际改变的是一种工作方式让 AI 从“临场猜规则”变成“按项目手册执行”。长期坚持下来你会在代码质量、团队协作、上下文维护效率上都感受到区别。到那时你会发现AI 编程助手的能力上限并不是模型的参数规模而是你用什么样的信息把项目变成它可理解、可遵守的对象。