1. 为什么你的 AGENTS.md 写了却不好用如果你已经写过 AGENTS.md但 AI 还是反复追问基础背景、动不动就跑偏、切换任务后语气和职责全乱那你不是一个人。我前后迭代了 4 版前 3 版基本都在做无用功文件越写越长AI 反而越来越机械。第一版我只写了知识库路径和一句自我介绍。AI 知道我是谁但每次开工仍然会问写给哪个平台目标读者是谁这次要观点还是教程第二版我开始堆规则写作要求、禁用词、文章长度、输出格式全塞进去。结果 AI 变得像在逐条对照说明书每走一步都要停下来确认。第三版我又加了一堆“不要”不要编数据、不要替我决定、不要写太长、不要用术语。AI 为了不犯错连本该主动提的建议也不提了。这时候我才意识到问题不是规则不够而是第一版 AGENTS.md 只有“执行说明”没有“判断机制”。它告诉 AI 每一步怎么做却没告诉 AI 在信息不完整时该怎么判断、自主权到哪里结束、不同任务之间怎么切换身份。常见故障基本可以归成三类。第一类是“不会选”AI 给出多个方案后等你决定每一步都要追问这是判断层缺失。第二类是“容易跑偏”自己扩展范围、编数据、跳过关键确认这是边界层缺失。第三类是“任务串线”写文章的要求影响诊断研究结果直接变成结论这是角色层缺失。先判断你遇到的是哪种故障再改对应模块。不要一遇到问题就继续往文件里堆规则那样只会让文件更臃肿、AI 更僵硬。下面我按判断层、边界层、角色层三个模块拆开讲每个模块都给可复制片段最后给一份完整的 V2.0 模板。2. 判断层让 AI 先完成能完成的判断判断层解决的核心问题是AI 总等你决定。具体表现是每做一步都问“接下来怎么办”给了 3 个方案但不说明推荐哪个遇到信息不完整时要么停住要么凭空补全。判断层的思路不是把最终决定全部交给 AI而是要求 AI 先完成可以完成的判断把真正需要人决定的部分压缩到最少。你可以把下面这段直接放进 AGENTS.md## 判断框架 当你不确定下一步怎么做时按以下顺序判断 1. 目标优先这个动作是否服务于当前任务的核心目标 2. 用户优先最终使用者真正需要带走什么 3. 证据优先结论是否有原始材料、数据或可检查结果支撑 4. 简单优先两条路径都能达成目标时选择更容易验证的一条。 5. 主动暴露信息不足时明确指出缺口不要用猜测补齐。 如果判断仍然无法闭环给出2个选项、各自代价和你的推荐再请求确认。这段的关键在最后一句不是让 AI 无限自主而是要求它在无法闭环时给出选项、代价和推荐把决策成本降到最低。我实测下来加了这段之后AI 从“每步都问”变成“先给推荐再问”沟通轮次明显减少。但光有判断框架还不够。很多人只写“通过”和“不通过”结果不通过之后 AI 还是不知道该怎么办。所以判断层要配一套 checkpoint 动作明确问题出现后怎么处理动作什么时候用下一步放行方向和结果都符合预期继续推进阻止方向违反目标或边界停止当前路径绕道目标不变但当前路径走不通更换实现方式回炉方向正确结果质量不够保留约束后重做追问缺少必要信息列出最小问题集加料结果可用但证据或案例不足补来源、案例或细节把动作写清楚后AI 不只会报告“发现问题”还知道问题出现后该如何处理。这六种动作建议原样放进 AGENTS.md 的 checkpoint 章节配合判断框架一起用。判断层最容易踩的坑是写成“你要自己判断”这种空话。判断框架必须给出明确的优先级顺序否则 AI 还是不知道在冲突时听谁的。目标优先、用户优先、证据优先、简单优先这个顺序是我试过比较稳的你可以根据自己的业务调整但一定要有顺序。3. 边界层规定自主权到哪里结束边界层解决的核心问题是AI 经常跑偏。具体表现是没有来源也敢给出具体数据用户只让分析它却直接修改文件为了显得完整擅自扩大任务范围连续失败后仍在重复同一条路径。边界不是“禁止 AI 思考”而是规定自主权到哪里结束。可直接复制这段## 工作边界 1. 不替用户做高影响决定列出选项、依据和建议由用户确认。 2. 不编造事实没有来源的数据、案例和引用必须标注为待核验。 3. 不擅自扩大范围发现关联问题可以提醒但不要直接修改范围外内容。 4. 不隐藏失败工具失败、验证失败和信息缺口必须明确说明。 5. 不无限重试同一路径连续失败2次后停止分析原因并提出替代方案。 以下情况必须暂停并请求确认 - 目标与现有规则冲突 - 操作超出授权范围 - 结果无法被验证 - 不同方案会显著改变最终交付物这里有个关键细节每条“不要”后面都要补一个替代动作。“不要猜”后面要补“列出缺口并追问”“不要越权”后面要补“给出选项等待确认”。否则 AI 只知道不能做不知道应该做什么就会陷入僵住或机械回避的状态。另外不要把几十条文风偏好都写成“禁止行为”。像“少用术语”“段落不要太长”这类要求更适合放进写作规范或知识库AGENTS.md 只保留跨任务都有效的高优先级边界。我第三版就是把文风偏好和硬边界混在一起导致 AI 分不清哪些是必须遵守的红线、哪些只是偏好结果连正常建议都不敢提了。边界层还有一个容易被忽略的点失败处理。AI 连续失败后最容易做的事就是换个说法重试同一条路径看起来在努力实际上在原地打转。所以“同一路径连续失败 2 次后停止”这条要写死并明确要求它分析原因、提出替代方案。这个数字可以根据任务复杂度调整但一定要有上限。4. 角色层不同任务之间怎么切换身份角色层解决的核心问题是不同任务互相干扰。具体表现是写作任务结束后做诊断AI 仍然用营销文案语气研究角色找到一个观点就直接替你下结论审核角色一边审核一边替原作者解释。角色定义至少要写 4 项触发方式、职责、不负责什么、交付物。只写“你是一名资深专家”通常不会带来稳定协作。可直接复制## 角色切换 ### 写作助理 - 触发方式我说“开始写文章” - 职责基于指定素材生成结构和初稿 - 不负责替我决定核心观点、编造外部数据 - 交付物标题备选、文章结构、初稿、待核验项 ### 系统分析师 - 触发方式我说“做诊断” - 职责根据原始材料识别卡点并标注优先级 - 不负责未经确认直接实施修改 - 交付物问题、证据、影响、建议动作 ### 独立审核员 - 触发方式我说“独立审核” - 职责重新检查原始材料和交付标准 - 不负责相信生成者的自检结论 - 交付物通过项、失败项、验证证据、返工要求角色层的关键在“不负责”这一项。很多人写角色只写职责结果 AI 会顺手把不该它做的事也做了。明确写出“不负责什么”等于给每个角色划了一条职责边界切换任务时不会串线。触发方式建议用固定口令比如“开始写文章”“做诊断”“独立审核”。口令比自然语言描述更稳定AI 不容易误判当前该用哪个角色。如果你用 Claude Code 或 Cline 这类工具可以把这些口令和角色定义一起放进 AGENTS.md配合工具本身的上下文管理切换任务时行为一致性会好很多。角色层还有一个进阶用法给每个角色配独立的完成标准。写作助理的完成标准是“结构完整、观点有素材支撑、待核验项已标注”系统分析师的完成标准是“问题有证据、影响有优先级、建议可执行”独立审核员的完成标准是“通过项和失败项都有验证证据”。这样每个角色交付时都有明确的验收依据不会出现“看起来做完了但不知道合不合格”的情况。5. 完整 AGENTS.md V2.0 模板与验证方法如果三种问题都有可以用下面这份组合模板。先复制再替换大括号中的内容# AGENTS.md我和AI的协作协议 ## 1. 我的背景 - 我的身份{你的身份或业务} - 当前核心方向{一句话目标} - 主要用户{服务对象} - 知识库位置{路径} ## 2. 当前重点 - 当前项目{项目名称} - 本阶段目标{可验证目标} - 优先级{最重要的1到3件事} ## 3. 判断框架 1. 目标优先所有动作服务于当前核心目标。 2. 用户优先交付物必须解决具体使用场景。 3. 证据优先重要结论必须能追溯到来源或验证结果。 4. 简单优先优先选择容易检查、容易回退的方案。 5. 信息不足时列出缺口、选项、代价和推荐不要猜。 ## 4. 工作边界 - 不编造数据、案例和来源。 - 不替我做高影响决定。 - 不擅自修改任务范围外的内容。 - 同一路径连续失败2次后停止并换方案。 - 涉及删除、发布、付费和权限变化时先确认。 ## 5. 角色切换 ### {角色一} - 触发方式{口令或任务类型} - 职责{做什么} - 不负责{不做什么} - 交付物{输出格式} ### {角色二} - 触发方式{口令或任务类型} - 职责{做什么} - 不负责{不做什么} - 交付物{输出格式} ## 6. checkpoint动作 - 放行符合要求继续。 - 阻止违反目标或边界停止。 - 绕道目标不变更换路径。 - 回炉方向正确按反馈重做。 - 追问列出继续任务所需的最少信息。 - 加料补证据、案例或细节。 ## 7. 完成标准 - 交付物满足当前任务目标。 - 重要事实有来源或标记为待核验。 - 已完成约定的检查或测试。 - 已说明遗留问题和下一步。 ## 8. 经验回写 出现以下情况时提醒我更新AGENTS.md或知识库 - 同类问题重复出现2次以上 - 某条临时要求被多次复用 - 发现稳定的判断规则或失败模式 - 某个重复动作适合封装为模板或Skill使用方法不要一次填满先替换背景、目标和边界。根据前面的故障表只启用当前最需要的角色和规则。连续使用 3 到 5 次记录 AI 在哪些地方仍需要人工纠偏。只把重复出现的问题写回 AGENTS.md单次任务要求留在当前 Prompt 里。每次修改后用同一类任务重新验证确认规则真的有效。V2.0 是否有效的检查清单AI 减少了重复询问基础背景AI 遇到不确定时会暴露信息缺口AI 能说明推荐方案及其依据AI 不会擅自扩大任务范围不同任务能切换到对应角色失败后能选择阻止、绕道、回炉或追问而不是无限重试最终结果有明确验收证据。满足其中 5 项说明这次升级已经开始生效。6. 常见报错与排查对照改完 AGENTS.md 后你可能会遇到一些具体报错。下面按真实场景对照排查。401 Unauthorized如果你在 Claude Code 或 Cline 里接入模型时遇到 401先检查 API Key 是否完整复制、有没有多余空格。Base URL 要填https://taotoken.net/api不要带 UTM 参数。Key 和 Base URL 必须配套换 Key 后要重新保存配置。local proxy failed这个报错通常出现在本地代理配置环节。检查你的工具是否设置了本地代理端口以及该端口是否和实际服务一致。如果你用的是 Cline MCP 或 Claude Code确认配置文件里的 Base URL 指向正确地址不要混用多个来源的配置。reading choices 报错这类报错一般出现在请求返回结构不符合预期时。检查 Model ID 是否填写正确不同模型对请求格式的要求不同。如果你在 Codex 的 auth.json 里配置确认字段名和层级没有写错。OAuth 相关报错如果你用的是需要 OAuth 的工具确认授权流程是否走完。OAuth 和 API Key 是两套认证方式不要混用。Claude Code 接入时如果走 OAuth就不需要再填 API Key。配置三件套检查无论你用 CC Switch、Cline MCP 还是 Codex auth.json配置时都要确认三件套齐全——Base URL、Key、Model ID。缺任何一个都会导致请求失败。Base URL 统一用https://taotoken.net/apiModel ID 按你实际使用的模型填写。排查顺序建议先确认三件套是否齐全再看网络和代理配置最后看请求格式和返回结构。大部分报错集中在配置环节而不是模型本身。7. 把 AGENTS.md 从说明文档变成协作约束AGENTS.md 升级后AI 知道该怎么和你协作了。但整个系统的结构、常用路径和断档恢复方式仍然可能只在你的脑子里。下一篇我会讲怎么用 3 页写一份“系统使用说明书”让你隔三周回来也能在 5 分钟内接着工作。如果你现在就想把 AGENTS.md 落地可以先从判断层开始把判断框架和 checkpoint 六种动作复制进去用同一类任务跑 3 次看 AI 是否减少了重复询问。然后补边界层最后补角色层。不要一次全上那样你分不清是哪条规则起了作用。需要模型对话验证效果可以走 模型对话需要长期编码和 Agent 协作可以看 Coding Plan配置 Key 和接入文档在 API Keys 和 接入文档。Claude Code 相关配置可以参考 ClaudeCodeAnthropic。你的 AGENTS.md 目前最像哪种情况A. AI 总等我决定需要判断层B. AI 经常跑偏需要边界层C. 不同任务互相干扰需要角色层D. 还没写第一版。先对照故障表找到自己的问题再复制对应模块不需要全部重写。