夜雨聆风本文是面向公众号读者的非官方中文自学整理，适合零基础或刚入门的朋友循序渐进学习。
开篇：为什么这一篇值得读
如果你已经看过前面的文章，可以把这一篇当成“把前面知识落到一个具体环节”的训练。很多人学习 AI 课程时，一上来就被英文术语、框架名和代码示例劝退。其实真正该先理解的是：AGENTS.md 模板到底解决什么问题，它在真实项目里处在什么位置，以及我们怎样判断它有没有做好。
基础差也可以读，因为我们会先用生活化比喻解释，再给工程化做法。你不用先成为算法专家，也不用先背一堆论文名。你只需要带着一个问题读：如果我要把 AI 用到一个真实任务里，今天这个概念能帮我少踩什么坑？
先用一句话讲清楚
AGENTS.md 模板可以先这样理解：AGENTS.md 是写给 coding agents 的项目说明，告诉它如何安装、运行、测试、修改和验收。
小白版比喻
如果把 AI 编程工具比作一个开发小队，模型像新人程序员，项目说明像团队规范，测试像验收标准，Git 像安全网，权限像门禁。AGENTS.md 模板 讨论的是怎样让这个小队在真实代码库里有秩序地工作，而不是到处乱改。
这个比喻很重要。因为 AI 相关知识最容易犯的错，就是把一个热词当成全部答案。真正能落地的学习方式，一定是把概念放回完整流程：它从哪里来，依赖什么，输出什么，如何验证，出了问题怎么定位。
放到工程图里看
本系列的基础工程图可以写成：
进入仓库 → 读取 AGENTS.md → 探索代码 → 制定计划 → 修改 → 测试 → diff → PR。 今天这篇关注的是其中的“AGENTS.md 模板”部分。它不是孤立知识点，而是和上下文、工具、数据、权限、测试、日志一起工作的。真实项目里，你只要忘掉其中一个环节，就可能出现“Demo 能跑，用户一用就坏”的问题。
核心知识一：先明确输入和输出
学习 AGENTS.md 模板 的第一步，不是问“应该用哪个框架”，而是写清楚输入和输出。输入是什么？可能是一句话、一个文件、一段日志、一个用户问题、一组表格数据。输出是什么？可能是一段回答、一个 JSON、一个待办清单、一个代码 diff、一个工单或者一个审批建议。
为什么要先写输入输出？因为 AI 最怕目标模糊。你让它“帮我处理一下”，它就会自由发挥；你让它“从这段会议记录中提取任务、负责人、截止时间，并输出 JSON”，它才有机会稳定完成。
新手可以记住一个公式：
稳定结果 = 清楚任务 + 足够上下文 + 明确格式 + 可验证标准 核心知识二：不要只追求“自动”，要追求“可控”
在这一主题里，你会经常遇到这些关键词或工具：Codex CLI、AGENTS.md、Subagents、MCP、Skills、Plugins、Git。
但只要 AI 开始调用工具、修改文件、访问数据库、发送消息，系统就进入了高风险区。本地 coding agent 能读写文件，因此目录、权限、测试和 Git 备份必须先做好。 公众号读者做项目时可以先遵守一个简单规则：凡是会影响真实用户、真实数据、真实金钱、真实账号的动作，都不要默认自动执行，先让人确认。
一个成熟做法通常有四个特征：第一，知道当前步骤的目标；第二，知道依赖哪些输入；第三，知道什么情况必须停下来检查；第四，做完之后能留下可复盘的证据。
核心知识三：上下文比“神奇提示词”更重要
很多人以为 AI 用不好，是因为提示词写得不够玄。其实大多数时候，问题是上下文不够。比如你让 AI 写接口，它不知道项目目录、数据库表、鉴权方式、测试命令和团队规范，就很容易写出“单独看没错，放进项目就错”的代码。
所以学习 AGENTS.md 模板 时，一定要养成上下文意识：给项目背景，给约束条件，给示例，给失败案例，给验收标准。真正的 AI 工程能力，不是会背 Prompt 模板，而是会把任务放进完整环境里描述。
核心知识四：必须能验证
不能验证的 AI 输出，只能算灵感，不能算工程结果。文章、总结、代码、数据分析、客服回复，都需要不同形式的验证。代码要跑测试，数据要抽样检查，回答要有来源，自动化流程要能回放，安全相关动作要有人类审批。
对于 AGENTS.md 模板，你可以设计三个检查问题：
结果是否符合我一开始写下的输出格式？
结果有没有引用错误、遗漏边界条件或越权操作？
如果结果错了，我能不能从日志中知道错在哪一步？
一个可以直接照抄的最小示例
# AGENTS.md ## 项目启动 - 安装依赖：pnpm install - 本地开发：pnpm dev - 运行测试：pnpm test ## 代码规范 - 修改 API 后必须更新 docs/api.md - 新增功能必须补单元测试 - 不要修改 .env、生产配置和迁移历史 ## 完成标准 - 测试通过 - lint 通过 - diff 中没有调试日志和密钥 这个示例不追求复杂，而是让你看到：好的工程实践会把规则写出来，把输入输出固定下来，把危险动作提前标出来。你可以先复制这个结构，再根据自己的项目替换命令、文件路径和验收标准。
新手实战任务
请用今天的概念做一个 30 分钟小练习：围绕“功能 PR：新增一个 API、补测试、更新 README，并用 Codex 自查 diff。”写一份任务说明。不要急着写代码，先写下面 6 行：
用户是谁；
用户输入什么；
AI 需要访问哪些资料或工具；
AI 输出什么格式；
哪些动作必须人工确认；
用什么方法判断结果是对的。
这 6 行写清楚以后，你已经比大多数只会“让 AI 帮我做个东西”的人更接近工程化思维。
常见误区
误区一：觉得 AGENTS.md 模板 越复杂越高级。其实初学者最应该追求简单、可解释、可测试。
误区二：把模型输出当成最终答案。正确做法是把模型输出当成候选结果，再经过规则、测试、人工确认或数据校验。
误区三：一开始就追求全自动。全自动不是第一步，先做半自动、可审批、可回滚，才是更稳的路线。
今天你需要记住的三句话
AGENTS.md 模板 的价值，在于让 AI 应用从“能回答”走向“能完成任务”。
任何 AI 工程能力都要同时考虑上下文、权限、验证和日志。
新手不要追求炫技，先做一个小而稳的流程。
下一篇预告
下一篇我们会继续讲：让 Codex 读项目：探索代码库的正确方式。你会看到这个知识点怎样和今天的内容连起来，逐步形成一个完整的 AI 工程学习路线。
如果你正在系统学习 AI 工程，可以收藏这一篇。下一篇我们继续往下拆，把概念变成能动手做的小项目。
