这次我们来看一个不是模型、也不是工具链的“轻量工程文件”agent.md。它可以不改代码、不装依赖就能明显改善大语言模型在代码仓库里的表现。很多团队发现同一个 AI 编程助手在不同仓库里的代码质量差距很大重要原因不是模型不行而是模型没有拿到项目规则。agent.md解决的就是“把项目惯例告诉模型”这件事。它放在仓库根目录用 Markdown 写清楚项目结构、编码规范、构建命令、测试要求和常见坑AI 编程助手在进入仓库后会优先读取这份文件把它当作项目级提示词来生成代码、补全建议和代码审查意见。本文会说明agent.md的原理、适用场景、编写模板、验证方法、上下文占用和常见坑给出一套可以直接照做的落地流程。不需要额外安装服务只要你的 AI 编程工具支持项目级提示文件或者你愿意在本地调用大模型时手动注入上下文就能跑起来。1. 核心能力速览agent.md不是一个可执行程序而是一份结构性指令文件。它的核心价值是让大语言模型在“理解代码仓库”这件事上少走弯路。能力项说明文件类型项目根目录下的 Markdown 提示文件主要功能向大语言模型传递项目结构、代码规范、构建流程、测试要求、命名约定支持工具主流 AI 编程助手大多支持项目级指令文件本地调用大模型时也可自行注入与 README 的区别README 面向人类协作agent.md 面向模型生成与审查显存 / GPU 要求无属于提示工程层不消耗额外推理资源安装难度无安装创建文件即可生效方式对话开始或进入仓库时自动读取批量支持可配合批量代码审查、CI 提示注入使用上下文影响会占用模型上下文窗口因此内容需要精简从这张表可以看出来agent.md的门槛几乎为零。难点在于内容设计也就是怎么把项目里最关键的规则压缩成模型能理解、能执行的指令。衡量一个仓库是否需要agent.md可以看三个信号AI 生成的代码经常不符合项目命名规范AI 频繁使用仓库里根本不存在的依赖或工具函数同一个模型在不同仓库里的质量差异很大。如果命中两个以上项目级提示文件就值得加。2. 适用场景与使用边界agent.md最适合三类情况。第一类是中型以上代码仓库。当项目超过一定规模模型不可能靠几轮对话理解全部模块一份结构清晰的项目提示文件可以显著减少“猜上下文”的试错成本。第二类是团队协作频繁的仓库。多个成员用 AI 改代码时风格不一致是常见问题。把规范写进 agent.md相当于把团队约定“前置”到了模型上下文里。第三类是本地部署大语言模型的场景。很多本地模型上下文窗口有限在仓库根目录放一份精简的 agent.md配合脚本把文件内容注入到每次对话 prompt 中本地模型的补全和建议质量也能提升。后面第 6 节会给出一个通用的注入脚本思路。边界也要说清楚。agent.md不是万能提示词它解决不了模型本身能力不足的问题。如果模型对某种语言、框架本身就生成不出正确代码加提示文件只能减少跑偏不能提升能力上限。合规方面需要特别注意。如果仓库代码属于商业项目或包含未公开逻辑不要直接把agent.md写得太细更不要通过云端工具上传敏感信息比如内部 API 地址、密钥命名、员工身份信息等。项目级提示文件会被工具自动读取本质上就是进入模型上下文的文本一旦发送给云端模型就从仓库本地信息变成了外部处理数据。建议只写通用规则敏感内容用占位符替代。3. 环境准备与前置条件使用agent.md不需要安装额外依赖。前置条件只有一个你的 AI 编程工具支持“项目级提示文件”或“仓库级规则文件”。目前多数主流 AI 编程助手已经支持类似机制即使工具没有原生的 agent.md 支持也可以使用工具自带的自定义规则文件或通过对话指令手动指定。操作系统的要求等同于你日常开发环境。Windows、macOS、Linux 都可以。文件放在 Git 仓库根目录后只要工具能识别仓库路径基本都能读到。需要特别注意文件编码。推荐使用 UTF-8 无 BOM 编码避免中文或特殊字符在部分工具中被解析成乱码。行尾格式不用纠结Git 仓库通常建议统一用 LF但这不是强制要求。文件命名方面虽然标准叫法是agent.md但不同工具可能有不同偏好比如AGENTS.md、CLAUDE.md或用户级规则文件。建议直接查阅你所用工具的文档确认优先级是根目录生效还是子目录也生效哪些文件名被保留。确认这些信息只需要几分钟但能避免后续“写了文件却不生效”的困惑。如果工具确实不支持项目级文件还有一个兜底方案写一个简短脚本在调用模型前把agent.md的内容拼进 system prompt。这部分会在第 6 节展开。4. 编写入门第一份 agent.md写agent.md不需要什么特殊格式但要避免一开始就堆砌大段文字。模型对冗长指令的遵守率会下降所以第一版应该短、具体、可验证。下面是一个通用模板适合大多数中大型仓库。实际使用时需要替换语言、框架、命令等具体内容。# AGENTS.md ## 项目简介 - 这是一个面向零售行业的数据可视化后台前端 Vue 3后端 Go。 - 项目目标快速展示订单趋势不做复杂权限控制。 ## 常用命令 - 安装依赖pnpm install - 启动前端pnpm dev - 启动后端go run ./cmd/server - 运行测试pnpm test go test ./... ## 代码规范 - 前端组件命名统一使用 PascalCase文件名使用 kebab-case。 - Go 后端需要遵循标准库错误处理错误必须包装上下文。 - API 路由必须使用 /api/v1/ 前缀。 - 禁止在业务代码中直接写 console.log改用项目封装的 logger。 ## 结构说明 - frontend/src页面组件按页面模块拆分。 - backend/internal业务逻辑按领域模块拆分。 - backend/pkg可复用的工具包。 ## 常见注意点 - 数据库变更必须走 migration不要手动改表结构。 - 图片上传统一走 OSS不要直接存服务器磁盘。 - 不需要考虑 IE 兼容性。这个模板的关键点在于把“模型最可能猜错的信息”写进去比如命令、前缀、目录职责、禁止事项。模型不需要知道全部背景只需要在生成代码时遵循这些硬约束。第一版不需要追求完整。先写 10 到 20 行跑几天看看效果再逐步补充。5. agent.md 的内容组织策略文件够不够好不取决于长度取决于信息密度。在启动任何 AI 编程工具之前模型都会把 agent.md 当作项目级系统指令内容越长上下文占用越大模型对关键规则的注意力也越容易分散。我从实践中比较推荐的结构是“五段式”项目简介、常用命令、代码规范、结构说明、常见注意点。每一段只写对该项目最重要的事实不是把团队 wiki 复制进来。第一段“项目简介”两到三行即可说明技术栈和核心业务方向。这里要避免空话比如“这是一个现代化高效平台”就没有价值模型无法据此做出任何不同决策。写技术栈、入口、主要模块就足够。第二段“常用命令”这个价值最高。模型如果不知道项目用什么包管理器、怎么跑测试、怎么起服务经常会在重构和补全时给出根本无法执行的命令。把命令写全模型生成的 CI 配置、安装步骤就会贴近仓库实际。第三段“代码规范”只写硬约束。命名规则、目录规则、错误处理方式、禁止使用的 API。不要写“注意代码整洁”这种无法验证的软性要求模型无法执行“整洁”这种模糊定义。第四段“结构说明”帮模型建立仓库地图。重点说明每个目录的职责边界这能减少模型“把后端逻辑塞进前端目录”这类问题。第五段“常见注意点”放容易踩坑的内容。包括数据库迁移、图片上传、依赖选择、环境变量等。写规则时有一个高效句式场景 动作 原因。比如“数据库变更必须走 migration不要手动改表结构”比“注意数据库变更流程”有效得多。如果仓库很大不要试图在一个文件里覆盖全部模块。更合理的做法是根目录放全局规则子目录再放局部规则。支持子目录提示文件的工具会按目录范围合并不支持的话就在根目录文件里写明“详细规则见各模块 README”并让模型去读对应文件。6. 让本地大模型也吃到 agent.md如果你的 AI 编程助手不支持 agent.md或者你使用的是本地部署的大语言模型那么可以用一个简单脚本来做“上下文注入”。思路是调用模型前从仓库读取 agent.md把它作为 system prompt 的一部分再拼接当前任务。下面是一个通用 Python 示例演示如何构造这种注入逻辑。它不是某个现成工具的命令而是一种可调整的实现思路。import os import sys from pathlib import Path def load_agents_file(repo_root: str) - str: 从仓库根目录读取 AGENTS.md 内容找不到就返回空字符串。 candidates [AGENTS.md, agent.md, CLAUDE.md] for name in candidates: path Path(repo_root) / name if path.exists(): return path.read_text(encodingutf-8) return def build_messages(repo_root: str, user_query: str) - list[dict]: 构造发给本地模型的 messages。 这里假设你有一个支持 OpenAI 风格 /chat/completions 的本地服务。 system_prompt load_agents_file(repo_root) if not system_prompt: system_prompt 你是一个代码助手请基于用户提供的仓库信息回答问题。 return [ {role: system, content: system_prompt}, {role: user, content: user_query}, ] if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else os.getcwd() query sys.argv[2] if len(sys.argv) 2 else 这个项目怎么运行测试 messages build_messages(root, query) print(messages)这段代码把 agent.md 文本作为 system prompt在每次请求时自动注入。你可以把它接到本地推理服务的调用函数中实现简易的项目级上下文。注入方式要注意两点。一是不要把 agent.md 塞进消息最后再问“请遵守上述规则”系统提示放在 system 位置更稳定。二是如果 agent.md 内容超过本地模型上下文窗口的四分之一就需要精简。本地模型窗口通常不大提示文件越短越好。批量场景下这个思路也适用。假设你有一批仓库需要做代码审查可以遍历仓库列表读取各自的 agent.md再按仓库分别构造请求避免把 A 项目的规则带到 B 项目。import json from pathlib import Path # 批量读取多个仓库的 AGENTS.md并输出为 JSON 便于检查 repo_list [ Path(./repo-a), Path(./repo-b), Path(./repo-c), ] batch_context_dir Path(./batch_context) batch_context_dir.mkdir(exist_okTrue) for repo in repo_list: agents_path repo / AGENTS.md if not agents_path.exists(): print(f[skip] {repo} 缺少 AGENTS.md) continue content agents_path.read_text(encodingutf-8) output_path batch_context_dir / f{repo.name}_prompt.json output_path.write_text( json.dumps({repo: str(repo), system_prompt: content}, ensure_asciiFalse, indent2), encodingutf-8, ) print(f[ok] {repo} 已生成提示文件长度 {len(content)} 字)这个脚本的本意不是直接调用模型而是把批量任务的上下文准备做成可审计的中间步骤方便在批量审查前确认每个仓库的规则是否正确加载。7. 功能测试与效果验证写完 agent.md 后不要急着写正式代码先做一轮验证。验证的核心是模型是否真正读到了文件内容并且按规则执行。最直接的测试是问一个“只有读过 agent.md 才能回答的问题”。比如模板里写了“API 路由必须使用/api/v1/前缀”你就直接问模型“项目里新增一个创建订单的接口路由路径应该怎么写”如果模型回答包含/api/v1/orders说明规则已经生效。如果模型给出一个泛泛的/orders说明文件可能没被加载或者规则写得不够明确。第二轮测试是代码生成测试。挑一个新增的小需求让模型直接生成代码检查三件事命名是否符合 agent.md 中规定的风格目录位置是否与项目结构匹配命令和依赖是否与仓库实际使用的一致。第三轮测试是审查测试。把你之前写的一小段代码贴给模型要求“按 AGENTS.md 规范做代码审查”。如果模型能指出违反规范的点比如错误处理没包装、路由没用前缀说明它已经把项目规则内化在了审查逻辑中。为了对比明显可以在同一会话中先用“忽略 agent.md”的方式测试一次再启用项目提示文件测试一次看生成结果差异。这个对比最能说明文件的价值。判断标准可以简化成一条模型生成的结果从“通用正确”变成了“符合这个仓库的正确”。如果只是通用正确说明文件没有起作用或写得太泛。如果文件不生效先检查工具的规则文件命名和放置路径再看是否需要重启会话才能重新加载。某些工具对规则文件有缓存改完文件后要重新打开 IDE 或重开会话。8. 与其他规则文件的优先级配合项目里可能同时存在多个规则来源用户级全局规则、项目根目录 agent.md、子目录提示文件、对话中的临时指令。它们之间怎么排优先级直接决定最终生成结果。我的建议是把全局规则留给人格化设定和工作流基础配置比如“你是资深后端工程师回答要简洁”。把项目级 agent.md 留给硬性规范和命令。把子目录文件留给特定模块的细节规则。用户级全局规则写太细会有问题。不同项目可能有相反的要求全局规则一旦写死模型在 A 项目中就难以遵循 B 项目的命名约定。因此项目级 agent.md 的优先级应当高于全局规则子目录规则又应当高于根目录规则。但要注意不是所有工具都按这个顺序处理。有些工具是“后写入优先”有些是“项目文件覆盖全局文件”还有些完全不支持子目录合并。最稳妥的做法是各工具都确认一遍不要默认。如果工具只支持单一规则文件优先级问题就不存在。你只需要在 agent.md 里把最重要的一条规则放在文件顶部因为模型对提示文件前部内容的遵守率通常高于后部。还有一个容易踩的坑别把个人偏好写进项目级文件。agent.md 是团队共享的提交进 Git 仓库后会影响所有人任何有争议的规则应该先在团队内部达成一致而不是你个人在 IDE 里临时加的。9. 上下文占用与性能观察agent.md 不消耗显存也不影响模型推理速度但它会占用上下文窗口。这个因素容易被忽略。上下文窗口是有限的模型能同时“看到”的内容总量有限。agent.md 作为 system prompt 常驻在上下文中它占用的 token 越多留给用户代码和对话历史的 token 就越少。在长上下文场景里这会造成早期对话被截断或模型对最新代码关注度下降。所以 agent.md 的内容应该控制在合理范围。一个经验判断是如果文件超过 300 行大概率需要拆分或精简。与其在一份文件里写所有细节不如只保留“模型不知道就无法做对”的信息。性能观察方面建议记录三类指标。第一类是效果指标记录加 agent.md 前后相同问题下模型首轮回答是否更准确。第二类是上下文指标查看工具的 token 统计确认文件名占了多少输入 token。第三类是延迟指标在大仓场景下如果工具每次读取整个文件再拼进上下文多器官的 token 也会增加首 token 延迟。优化方向有三个精简文件内容、拆分子目录文件、把不常用的细节移入其他文档并只让模型按需读取。最后一种做法尤其适合大型仓库根目录 agent.md 只写“仓库地图”模型生成具体模块代码时让它先读对应模块的 README 或设计文档不要把所有内容一次性硬塞进上下文。10. 常见问题与排查方法这一节把使用过程中最常见的现象列成表格方便对照排查。问题现象可能原因排查方式解决方案模型完全无视 agent.md 规则工具没启用项目级文件查看工具文档确认文件名和存放位置改用工具约定文件名如 AGENTS.md或放到规则配置目录修改后的 agent.md 不生效工具缓存了旧文件重启 IDE 或重新打开仓库重开会话查看工具日志确认加载状态生效了但对长文件遵守率低内容太长模型注意力分散检查 token 统计和文件行数精简内容核心约束前移细节拆到子目录跨仓库时规则串味全局规则写入了项目特有规范查看全局规则文件和项目文件把项目特有内容移入项目级 agent.md全局只保留通用人格帮助不明显写得过于抽象对比测试有/无文件时模型输出补充硬性命令、目录结构、禁止事项减少软性描述中文乱码文件编码不是 UTF-8用文本编辑器查看编码另存为 UTF-8 无 BOM批量任务 A 项目用了 B 项目规范批量脚本共享了同一份上下文检查批量脚本的 prompt 构建逻辑每个仓库独立读取自己的 agent.md如果排查后仍然不生效最直接的办法是打开一个新会话在对话框里加一句“请先阅读仓库根目录的 agent.md”手动引导模型去读文件。这一招虽然不如自动加载优雅但在临时场景下非常有效。11. 最佳实践与使用建议下面这些建议来自项目实战观察不依赖特定工具适用于大多数使用大语言模型辅助开发的场景。第一个建议是第一版 agent.md 一定要短。写 10 到 20 行只覆盖最关键的命名、命令、目录、禁止事项。跑一段时间后再补充。一次性写一份长篇文档维护成本高模型遵守率也差。第二个建议是把 agent.md 纳入版本管理随代码库一起 review。它本质上是一份工程文件应该跟随项目演进。新增模块、切换包管理器、命令变化时都要同步更新 agent.md。如果一个 AI 生成的代码使用了过时命令先别急着怪模型看看 agent.md 是否已经过期。第三个建议是设计便于模型执行的句式。写成“当……时需要……因为……”的结构比单独的形容词有效得多。比如“当新建前端组件时文件使用 kebab-case 命名因为项目统一使用该约定”模型更容易提取规则因子。第四个建议是批量任务与 CI 集成时把 agent.md 作为规则源。批量代码审查、批量重构、批量补文档都可以先读取 agent.md 作为公共上下文。如果审查脚本能自动识别仓库并加载对应提示文件批量任务的质量会更稳定。第五个建议是讲清授权边界。agent.md 会被模型读取也可能被发送到云端推理服务。项目里如果涉及未公开代码、用户敏感数据、内部密钥相关内容不要写进 agent.md。可以在文件里用指针替代比如“内网部署细节见内部文档不要发送给外部工具”。第六个建议是定期做一次“无 agent.md 对照测试”。每个月选一个新需求分别在有提示文件和没有提示文件的条件下生成一遍代码对比差异。这个测试能快速暴露提示文件是否已经失效或写偏。这套方法不需要额外硬件不需要安装服务核心投入是几十分钟的编写和持续维护。对大多数团队来说这是成本最低的 AI 辅助编码优化方案。# 快速检查仓库里是否已存在常见提示文件位置 find . -maxdepth 2 -iname agent.md -o -iname AGENTS.md -o -iname CLAUDE.md 2/dev/null如果这个命令没有任何输出说明仓库里还没有项目级提示文件。现在就可以考虑创建第一份。