如果你最近在用大模型辅助写代码大概率会遇到一种“分裂感”上一个对话里AI 还老老实实用项目里已有的工具函数换一个新对话之后它却大摇大摆地新造了一个重复实现你明明在需求里说过“错误不要吞掉”它还是写出一堆裸except: pass更折磨人的是每次新开会话你都得把项目背景、技术栈、代码风格重新讲一遍仿佛在给一个记忆力只有几小时的实习生反复做入职培训。这个问题不是“prompt 写得不够长”能解决的。对话级提示是临时的、局部的、一次性的项目级提示才是持久的、全局的、可复用的。而这正是agent.md这类文件出现的原因它把团队对项目的工程约束、代码风格、架构红线、测试要求写进项目根目录下一个普通 Markdown 文件里让 AI 编码工具在真正动手改代码之前先读到一份“项目说明书”。这篇文章会从“为什么 AI 生成的代码质量不可控”讲起解释agent.md到底是什么、和README/AGENTS.md/CLAUDE.md有何关系然后给出一份可直接套用的 FastAPI 项目示例再聊聊怎么验证它真的提升了代码质量、有哪些坑、如何在团队里长期维护。文章偏实战适合已经在大模型辅助编程上投入时间、却对输出质量不稳定的开发者和技术负责人。1. 为什么 AI 写代码越多代码质量越难控制先把问题摆清楚。大模型编码工具现在已经不是简单的“问答式补全”而是能够读仓库、改多文件、执行命令、运行测试的“编码代理”。能力变强之后新的矛盾也出现了它能改动的地方越多越容易破坏项目里原本约定好的东西。代码质量不稳定通常不是模型能力问题而是上下文问题。大语言模型本身没有记忆每次新建会话都相当于一次“失忆后的重新入职”。如果你没有把项目约定写进它的可见上下文它会凭训练数据里的“大众风格”写代码而不是针对你当前项目的“团队风格”写代码。这种大众风格往往看起来规范实际却和项目现有代码处处冲突。更麻烦的是项目里的多数约定是隐性的。命名前缀、异常处理方式、数据库访问封装、接口返回结构、测试命名风格这些东西可能只存在于组长脑子里或者散落在几十次 Code Review 评论里又或者写在一份没人更新的团队 Wiki 里。AI 再聪明也没有办法从这种信息环境里推断出约定。这时就会出现一种很普遍的对比。维度临时对话 prompt项目级提示文件 agent.md作用范围当前对话有效项目根部对所有会话生效记忆性新对话即失效文件常驻仓库持久可复用内容来源依赖开发者临时口述团队沉淀的工程规范一致性每个会话风格飘移每次任务读到同一份约束维护成本每次重复输入一次编写持续演进可评审性不可 diff、不可 Review像代码一样走版本管理到这里可以下第一个判断想让 AI 辅助编程从“能写代码”进化到“稳定产出符合项目规范的代码”关键动作不是写一个更复杂的 prompt而是把项目从“隐性约定”变成“显式文件”。2. agent.md 是什么一份给 AI 写的“项目使用说明”agent.md的命名直觉上很直接agentAI 编码代理 mdMarkdown。它放在项目根目录内容不是给人看的 API 文档而是给 AI 编码代理看的一份“项目使用说明”。我们可以把它理解成给入职实习生的那份《团队开发手册》里面有项目是做什么的、技术栈是什么、目录结构怎么理解、哪些代码是绝对不能碰的、加新功能的时候应该优先复用哪些模块、写完代码之后要跑什么测试。只不过这份手册的读者是 AI不是人。它和传统README.md的区别值得单独说明。README.md的读者是人类开发者和使用者通常是项目简介、安装方式、使用示例agent.md的读者是负责改代码的 AI它关心的是“以什么风格改、遵守什么约束、如何验证改动”。两者可以共存不需要合并。README 不一定需要写“错误码统一用AppError包装”但 agent.md 必须写因为 AI 改代码时会真正用到这条约束。这里需要避免一个误解agent.md不是某个工具官方规定的唯一文件名而是“项目级提示文件”这一类方案的通俗称呼。不同工具各有自己的约定常见的有工具/生态文件名示例读取方式OpenAI CodexAGENTS.md启动时会自动查找并加载Claude CodeCLAUDE.md会话开始时自动读取Cursor 等 IDE 扩展.cursor/rules/*.md按规则目录导入社区通用约定agent.md手动引用或工具自动读取文件名可能有差异但解决问题的思路是一致的在项目内部维护一份 AI 可读取、人类可 Review 的指令文件把以前靠开发者反复口述的约束沉淀下来。写法和原理完全可以迁移。从本质上说agent.md提供的是“项目级上下文”。对话级上下文是临时的会消失项目级上下文是持久的每次任务都自动进入 AI 的视野。它还为团队提供了一个新的协作接口以前约束 AI 是个人行为谁会用 prompt 谁就能得到更好的结果现在约束 AI 是工程行为文件写在哪里、写什么、怎么写整个团队可以一起 Review、一起改进。3. 编写 agent.md 的五个核心板块agent.md不是越长越好但内容结构可以做标准化。参考实际项目中的使用反馈一份能真正约束 AI 的 agent.md 通常包含五个板块。3.1 项目概览与技术栈AI 打开仓库时并非天然知道这个项目是干什么的。让它先理解项目目标再开始改代码可以显著减少南辕北辙式的改动。这个板块要写清楚项目一句话定位。核心业务对象。技术栈清单包括语言、框架、数据库、消息队列等。关键的目录结构以及每个目录的职责边界。目录结构尤其重要。AI 在寻找“应该改哪里”的时候如果目录职责写得不清楚它倾向于在根目录附近新建文件而不是进入现有模块。很多项目里出现“根目录下散落一堆单文件模块”的脏乱局面根源就在这里。3.2 核心架构与不可破坏的约束这是 agent.md 里优先级最高的部分也是最能体现“工程判断力”的部分。要明确告诉 AI哪些设计是不可改变的哪些代码是改动风险极高的哪些层之间不允许出现依赖倒挂。举例来说如果项目规定了三层架构API 路由层只做参数解析和响应封装。Service 层承载业务逻辑。Repository 层负责数据库访问。那么 agent.md 里就应该用“禁止”句式写清楚禁止在路由层直接操作数据库禁止在 Repository 层抛出业务异常等等。AI 编码代理的默认行为是“低阻力通过”只要当前测试能过它就倾向选择改动最小的路径。架构约束写清楚之后它会意识到“这样写虽然能过测试但是违反项目约定”从而主动调整方案。3.3 代码风格与实现约定代码风格部分不要只写“遵循 PEP8”这种所有项目都通用的泛泛之词要写那些“这个项目独有的、外面没有统一标准、但团队已经形成习惯”的规则。典型内容包括命名规则比如数据库表名、接口路径、DTO 后缀。返回结构统一的数据响应格式是什么。异常处理哪些异常需要捕获、哪些需要向上抛、是否统一包装。日志规范使用哪个 logger日志级别怎么用。禁止硬编码配置项必须走配置中心或环境变量。项目独有约定才是 agent.md 的增量价值。通用规范模型自己就懂所有项目都会遵守 PEP8 的 AI 反而是少数真正需要约束的是那些“只有你们团队才会这么写”的规则。3.4 测试与质量门槛没有测试门槛的 agent.md 是不完整的。AI 生成代码后必须知道如何验证自己写的代码是否合格。这个板块至少要包含新增功能时必须配套哪些测试。当前项目已有的测试命令。测试文件放在哪里命名规则是什么。覆盖率或关键路径的验收要求。哪些回归测试不允许跳过。建议把测试命令写得像可执行脚本一样清楚。比如 “运行make test-auth验证认证模块”这种写法比“请确保测试通过”有效得多因为它给 AI 提供了一条可执行路径。3.5 常用命令与工作流最后一个板块是“工具索引”。AI 编码代理在执行任务时经常需要运行命令来验证结果如果它不知道项目用poetry还是pip、用make还是pytest就会产生大量无效尝试。写明以下内容依赖安装命令。本地开发启动命令。测试命令。Lint / 格式化命令。数据库迁移命令。构建与打包命令。这一部分的价值是减少 AI 的“自由发挥”也减少 AI 在终端里反复试错的时间。4. 完整示例一个 FastAPI 项目的 agent.md下面给出一份可直接参考的agent.md示例。假设项目是一个基于 FastAPI SQLAlchemy PostgreSQL 的任务管理服务目录结构大致如下task-service/ ├── app/ │ ├── api/ │ ├── core/ │ ├── models/ │ ├── repositories/ │ ├── schemas/ │ ├── services/ │ └── main.py ├── tests/ │ ├── api/ │ ├── services/ │ └── repositories/ ├── pyproject.toml └── agent.md文件路径task-service/agent.md# agent.md ## 项目概览 这是一个任务管理服务。核心业务对象是 Task任务和 Project项目。 技术栈Python 3.11 FastAPI SQLAlchemy 2.0 PostgreSQL Alembic。 ## 目录职责 - app/apiHTTP 路由层只做参数解析、调用 service、封装响应。 - app/services业务逻辑层承载所有核心业务规则。 - app/repositories数据访问层封装 SQLAlchemy 会话与查询。 - app/modelsSQLAlchemy ORM 模型禁止写业务逻辑。 - app/schemasPydantic 模型用于请求校验与响应序列化。 - app/core配置、安全、公共依赖。 ## 架构红线 - 禁止在 app/api 层直接操作数据库或访问 app/models。 - 禁止在 app/repositories 层抛出业务异常业务异常统一在 service 层抛出。 - 禁止在 app/models 中引入 Pydantic 或 HTTP 相关类型。 - 新增表必须同时提供 Alembic 迁移脚本。 ## 代码风格 - 用户输入校验统一使用 Pydantic schema不允许在路由函数里手写 if 校验。 - 响应统一使用 app/core/response.py 中的 ApiResponse 包装格式为 {code, message, data}。 - 业务异常统一抛出 app/core/exceptions.py 中定义的 AppError并携带错误码。 - 时间字段统一使用 UTC 时间不允许使用本地时间直接入库。 - 日志必须使用 app/core/logger.py 中创建的 logger不允许随意 print。 ## 测试要求 - 新增 API 路由必须配套 tests/api 下的接口测试。 - 新增 Service 方法必须配套 tests/services 下的单元测试。 - 数据库改动必须保证 tests/repositories 中的现有测试不失败。 - 运行测试命令poetry run pytest - 运行 lint 命令poetry run ruff check app tests - 运行格式化检查poetry run ruff format --check app tests ## 常用命令 - 安装依赖poetry install - 启动开发服务poetry run uvicorn app.main:app --reload - 执行测试poetry run pytest - 执行迁移poetry run alembic upgrade head写这份文件时有一个原则每一条规则都应该是“AI 在写代码时能直接判断是否违反”的而不是一种感受性描述。例如“请写出优雅的代码”这种话没有任何约束力但“禁止在路由层操作数据库”就是一条可判断的规则。AI 拿到这条规则后如果发现自己想写的代码需要访问 ORM 模型它会主动回到 service 层去实现。另外一个容易被忽略的点是文件里的规则要互相独立。不要出现“统一使用 ApiResponse但某些接口例外”这种模糊条款AI 会因此进入摇摆。如果确实有例外应该把例外也写成精确条件。5. 从“写文件”到“任务闭环”agent.md 如何实际改变 AI 输出有了 agent.md 之后一次标准的 AI 辅助开发任务流程会变成AI 编码代理启动读取项目根目录下的agent.md。用户提出任务例如“新增一个创建任务的 API”。AI 根据 agent.md 中的目录职责确定应该修改app/api、app/services、app/repositories等文件。AI 按照代码风格要求使用统一响应结构抛出自定义业务异常。AI 运行测试命令验证改动符合测试要求。没有 agent.md 时AI 的默认路径往往是“找最近一个能塞下功能的文件”然后按训练样本里最常见的写法输出。这两者之间的差异在代码里体现得非常明显。设想一个需求在创建任务时如果项目不存在则返回 404。没有 agent.md 时AI 可能直接在路由函数里写一段临时的查询逻辑# 文件路径app/api/tasks.py (低质量示意) from fastapi import APIRouter, HTTPException from app.database import SessionLocal from app.models import Project router APIRouter() router.post(/tasks) def create_task(project_id: int, title: str): db SessionLocal() project db.query(Project).filter(Project.id project_id).first() if project is None: raise HTTPException(status_code404, detailproject not found) # ... 后续逻辑 ...这段代码能跑但它违反了 agent.md 里的三条红线路由层直接创建 Session 访问数据库、返回体没有使用 ApiResponse、没有经过 service 层。在真实项目里这样的代码进入 Code Review 后大概率被打回。有了 agent.md 的约束AI 更可能生成这样的结构# 文件路径app/services/task_service.py from app.core.exceptions import AppError from app.repositories.project_repository import ProjectRepository class TaskService: def __init__(self, project_repo: ProjectRepository): self._project_repo project_repo def create_task(self, project_id: int, title: str): project self._project_repo.get_by_id(project_id) if project is None: raise AppError(codePROJECT_NOT_FOUND, message项目不存在) # 业务逻辑...# 文件路径app/api/tasks.py from fastapi import APIRouter, Depends from app.core.response import ApiResponse from app.schemas.task import CreateTaskRequest from app.services.task_service import TaskService router APIRouter() router.post(/tasks) def create_task(req: CreateTaskRequest, service: TaskService Depends()): result service.create_task(project_idreq.project_id, titlereq.title) return ApiResponse.success(result)对比两个示例可以发现agent.md 的意义不只是“让代码更规范”而是让 AI 的结构决策从“怎么快怎么来”切换到“按项目设计来”。它其实是在替技术负责人完成一部分“架构引导”工作不需要每次把设计文档丢给 AI只需要让它遵守已经沉淀好的规则文件。6. 如何验证 agent.md 是否真的提升了代码质量如果只是把 agent.md 放进仓库就宣称“代码质量提升了”这不具备说服力。项目里引入任何工程手段都应该有验证方法。一个相对可行的做法是设计一组固定任务做对比验证。具体步骤如下。第一步准备 5 到 8 个有代表性的开发任务覆盖新增接口、修改业务逻辑、数据模型变更、修复缺陷等类型。把这些任务写成需求描述不要太详细模拟真实业务中用户给出的信息量。第二步用同一个 AI 编码代理在不加载 agent.md 的情况下执行一遍任务记录输出代码再以同样任务、加载 agent.md 的环境执行一遍记录输出代码。第三步从四个维度做对比评估维度没有 agent.md 时的常见表现有 agent.md 后的预期变化架构一致性逻辑出现在错误分层路由、服务、仓库分层稳定风格一致性错误处理方式多次变化统一使用项目既有模式代码可维护性为快速通过而硬编码遵循既有抽象与工具函数验证完整性依赖人工检查漏测主动运行项目测试命令这里需要注意的是评估时要看“是否违反项目约定”而不是看“代码能不能跑”。能跑但不符合项目约定的代码才是 AI 辅助开发里最大的隐性成本。除了人工对比还可以把部分约束自动化。比如在 CI 里增加一个简单的检查脚本校验新增代码是否出现了 agent.md 禁止的模式。下面是一个最小示例用来检查app/api目录下是否直接出现了数据库 Session 的调用。# 文件路径scripts/check_agent_rules.py import pathlib API_DIR pathlib.Path(app/api) DISALLOWED_PATTERNS [ SessionLocal(), db.query(, db.execute(, ] def main(): errors [] for path in API_DIR.rglob(*.py): text path.read_text(encodingutf-8) for line_no, line in enumerate(text.splitlines(), start1): for pattern in DISALLOWED_PATTERNS: if pattern in line: errors.append(f{path}:{line_no}: 禁止在路由层出现 {pattern}) if errors: print(\n.join(errors)) raise SystemExit(1) print(agent.md 架构约束检查通过) if __name__ __main__: main()python scripts/check_agent_rules.py这种脚本虽然简单但也说明了一个理念agent.md 里的规则能沉淀成检查命令的就尽量沉淀不要只停留在自然语言层面。可执行的约束比纯文本约束更可靠因为 AI 会验证、CI 也会验证人和机器都能从这条规则里获益。7. 常见问题与排查思路在实践中agent.md 不是一放进去就立竿见影很多团队会踩到类似问题。问题现象可能原因排查方式解决方案AI 好像没有读取 agent.md文件名与工具约定不一致或文件不在根目录确认工具支持的文件名查看工具日志或加载配置改用工具支持的文件名或将文件放到项目根目录文件太长AI 读完反而更容易偏离规则堆砌没有优先级关键信息淹没在泛泛描述里统计 agent.md 行数检查核心红线是否集中在开头压缩到尽量精简把高优先级规则放在文件前部规则之间互相冲突多条规则表述不一致AI 无法同时满足逐条对照检查模拟改代码场景删掉冗余规则用“必须/禁止”句式重写冲突条目定义的规则太泛AI 无法判断只有“请保持高质量”等感受性描述列出 AI 写代码时可以检查的模式每条规则补充正例和反例敏感信息写入 agent.md有人把密钥、内网地址直接贴在文件里检查 git 历史扫描敏感字段立即从文件中移除替换为环境变量引用并轮换已泄露的凭据团队没人维护文件很快失效agent.md 没有纳入代码评审流程查看文件最近修改时间与提交记录把 agent.md 纳入版本管理与 Review 范围这里最容易出问题的其实是第一条。不同 AI 工具对项目级提示文件的自动加载行为并不完全一致有的自动读取根目录约定文件名有的需要手动引用有的只读取特定命名。使用前应该先在自己用的工具上确认加载机制而不是想当然地以为“只要文件在AI 就一定会读到”。如果工具不支持自动读取也可以把 agent.md 的内容附在系统提示词或初次对话里。虽然这样会退化为“对话级提示”但至少内容是可复用、可版本化的比每次重新写 prompt 好很多。8. agent.md 的最佳实践与工程建议写 agent.md 不是写作文它更接近“为 AI 定义接口契约”。结合几次迭代经验这里有几条值得长期坚持的建议。第一长度控制在“能读完”的范围。agent.md 太长会让 AI 注意力被稀释甚至出现“读到后面忘了前面”的情况。从效果看一个中小型项目的 agent.md 控制在 200 到 400 行以内比较合适。如果项目确实复杂可以把详细规范拆到docs/architecture等文档里在 agent.md 中只保留索引和“必须遵守的裁决性规则”。第二强指令比弱建议有效。写“请尽量避免在路由层直接使用数据库”是弱建议AI 可能不把它当硬约束写“禁止使用 SessionLocal 于 app/api 目录”是强指令。有条件时附上反例AI 会更容易理解边界。第三把规则设计成“可检查的”。每写完一条规则问自己一个问题我能不能写一个脚本检查这条规则如果答案是可以那么这条规则是有效的如果不能它很可能太抽象。例如“代码质量要高”不可检查“所有新增接口必须提供 pytest 测试”就可以检查。能写进 CI 的规则会让 agent.md 的效果从“概率性遵守”变成“强制性验证”。第四把 agent.md 当作代码维护。修改 agent.md 要经历评审更新要写清楚原因历史变更要可追溯。它不应该是一个“写一次就不动”的文档而是要随着项目架构演进持续更新。当项目引入新框架、重构目录、修改错误码规范时都需要同步修改 agent.md。第五注意安全边界。agent.md 会进入 AI 的上下文甚至可能被复制到外部模型服务因此绝对不能包含密码、Access Key、内网地址、用户隐私数据。涉及敏感信息时只写“从环境变量读取”不写真实值。这不仅是安全规范也是让 agent.md 可以安全进入代码仓库、被所有协作者看到的必要条件。第六子目录规则按需拆分。如果项目规模很大根目录级 agent.md 不可能覆盖所有子模块的细节。此时可以按工具能力拆分子规则例如前端目录放一份前端相关约定后端目录放一份后端相关约定。子规则不要和根规则冲突根规则负责全局红线子规则负责局部细节。9. 从 agent.md 到更工程化的 AI 辅助开发把 agent.md 放回更大的趋势里看它其实是“AI 辅助开发从个人技巧走向团队工程实践”的一个缩影。过去能不能让 AI 写出好代码很大程度上取决于个人写 prompt 的水平这是一种不可复制的隐性能力现在项目级提示文件把这种能力拆解成了结构、文本和规则团队可以共同维护、共同迭代。它不是银弹但它是让 AI 编码质量可预期、可控制、可复现的一块重要基石。如果读完这篇文章只记住一件事我的建议是不要追求 agent.md 的格式多么完美先在一个真实项目里把“目录职责、架构红线、测试命令”这三类内容写进去然后观察 AI 的下一轮改动。你会发现它比上一次更懂这个项目了一点而这一点恰恰是团队协作和代码质量里最珍贵的东西。下一步你可以在项目里尝试三个动作一是为当前项目写一份精简的 agent.md二是用一组固定任务做一次带文件和不带文件的对比验证三是把其中一两条约束做成 CI 检查脚本。做完这三步你对“AI 辅助开发质量可控”应该会有更具体的体感。