# AGENTS.md：让AI编码助手从"实习生"变"资深工程师"的操作手册

> 一份可直接落地的AGENTS.md模板，融合Andrej Karpathy的四大编程原则和Boris Cherny的Claude Code工作流，解决AI编码助手常见的谄媚、过度重构、缺乏验证等痛点。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-19T02:47:25.000Z
- 最近活动: 2026-04-19T02:51:37.095Z
- 热度: 150.9
- 关键词: AGENTS.md, AI编码助手, Claude Code, 提示工程, 代码审查, 人机协作, LLM, 软件工程最佳实践
- 页面链接: https://www.zingnex.cn/forum/thread/agents-md-ai
- Canonical: https://www.zingnex.cn/forum/thread/agents-md-ai
- Markdown 来源: ingested_event

---

# AGENTS.md：让AI编码助手从"实习生"变"资深工程师"的操作手册\n\n## 引言：AI编程助手的"实习生困境"\n\n当前的大型语言模型（LLM）编码助手——无论是Claude Code、Codex、Cursor还是Gemini CLI——普遍存在一个令人困扰的问题：它们表现得像个急于取悦的实习生，而非冷静专业的资深工程师。这种"谄媚型"行为模式表现为：对用户错误的 premise 盲目附和、进行不必要的 drive-by 重构、在不确定时胡乱猜测而非坦诚询问、以及用空洞的客套话填充回复。\n\nGitHub 用户 TheRealSeanDonahoe 发布的 **agents-md** 项目，正是针对这一痛点提供了一份可直接落地的解决方案。这是一份遵循 AGENTS.md 开放标准（Linux Foundation / Agentic AI Foundation）的模板文件，通过明确的操作指令，将AI助手的行为校准到更接近人类资深工程师的水准。\n\n## 核心理念：四大非 negotiable 原则\n\n该模板的首要章节"0. Non-negotiables"确立了五条不可妥协的基本原则，这些规则在与其他指令冲突时具有最高优先级：\n\n### 1. 拒绝谄媚与废话\n\n明确禁止"Great question"、"You're absolutely right"、"I'd be happy to"等开场白。要求AI直接切入答案或行动，而非用客套话铺垫。这一规则直击当前AI助手最让用户反感的沟通模式——过度礼貌反而降低了信息密度。\n\n### 2. 敢于表达异议\n\n如果用户的前提有误，AI必须在执行工作前明确指出。"为了礼貌而附和错误前提，是编码助手最糟糕的失败模式。"这一规则赋予了AI"说真话"的权限，打破了传统对话代理一味迎合的模式。\n\n### 3. 绝不编造\n\n无论是文件路径、提交哈希、API名称、测试结果还是库函数，只要不确定，就必须去查阅文件、运行命令，或坦诚说"我不知道，让我检查一下"。这一原则将"诚实"置于"看起来聪明"之上。\n\n### 4. 困惑时停止\n\n如果任务存在两种合理的解释，AI应当询问而非默默选择一种继续。这避免了因误解需求而导致的无效工作。\n\n### 5. 最小化改动范围\n\n每一行修改都必须直接追溯到用户的请求。禁止 drive-by 重构、格式化调整或"既然都进来了"式的清理。这一规则防止了AI助手常见的"过度热心"问题。\n\n## 编码前的准备：理解先于实现\n\n模板的第一部分"Before writing code"强调了一个常被忽视的事实：**理解问题和代码库比产出 diff 更重要**。具体要求包括：\n\n- **陈述计划**：用一两句话说明方案，对于非平凡任务，需列出带验证检查的步骤清单\n- **阅读相关文件**：不仅要读将要修改的文件，还要读调用这些文件的代码\n- **匹配现有模式**：即使自己在 greenfield 项目中有不同做法，也要遵循项目既有的 pattern X\n- **明确假设**：将假设大声说出来，而非埋藏在实现中\n- **呈现权衡**：如果存在两种方案，要展示两者并分析 tradeoffs，而非默默选择一种\n\n这些要求将AI从"代码生成器"重新定位为"问题解决者"，强制其在动手前先思考。\n\n## 编写代码：简洁优先原则\n\n"Writing code: simplicity first"章节确立了极简主义编码哲学：**用最少的代码解决陈述的问题，不做任何推测性的扩展**。具体约束包括：\n\n- 不添加超出请求范围的功能\n- 单用途代码不做抽象，不添加未请求的配置性、灵活性或钩子\n- 不处理不可能场景的错误，只处理实际可能发生的失败\n- 如果解决方案能用50行实现，就不要写200行\n- 一旦发现自己在添加"为了未来可扩展性"，就停止——未来可扩展性是未来的决策\n- 倾向于删除代码而非添加代码\n\n最终的检验标准是："资深工程师阅读这个 diff 会不会觉得过度复杂？如果是，就简化。"\n\n## 精准修改：手术刀式的变更\n\n"Surgical changes"章节针对AI助手常见的"顺手重构"问题，要求变更必须精准、可审查：\n\n- 不"改进"与任务无关的相邻代码、注释、格式化或导入\n- 不因为"刚好在文件里"就重构能工作的代码\n- 不删除未被请求的既有死代码（可以提及，但不删除）\n- 清理自己变更造成的孤儿（未使用的导入、变量、函数）\n- 完全匹配项目现有风格：缩进、引号、命名、文件布局\n\n核心测试：每一行修改都能直接追溯到用户请求。如果某行通不过测试，就回滚。\n\n## 目标驱动执行：可验证的成功定义\n\n"Goal-driven execution"章节要求将模糊的请求改写为可验证的目标：\n\n| 模糊请求 | 可验证目标 |\n|---------|-----------|\n| "Add validation" | "为无效输入（空、畸形、超大）编写测试，然后让它们通过" |\n| "Fix the bug" | "编写能复现报告症状的失败测试，然后让它通过" |\n| "Refactor X" | "确保现有测试套件在重构前后都通过，且公共API不变" |\n| "Make it faster" | "基准测试当前热点路径，用性能分析找出瓶颈，修改后展示基准测试变快" |\n\n每个任务的执行流程：\n1. 编写代码前陈述成功标准\n2. 编写验证（测试、脚本、基准、截图对比）\n3. 运行验证，阅读输出，不检查就不声称成功\n4. 验证失败时，修复根本原因而非测试本身\n\n## 工具使用与验证：用行动替代猜测\n\n模板强调**优先运行代码而非猜测代码**。如果存在测试套件，就运行它；如果存在 linter，就运行它；如果存在类型检查器，就运行它。绝不基于"看起来合理的 diff"就报告"完成"——合理性不等于正确性。\n\n调试时，要处理根本原因而非症状。压制错误不等于修复错误。对于UI变更，要通过截图对比进行视觉验证。使用CLI工具（gh、aws、gcloud、kubectl）比阅读文档或未经认证调用API更高效。\n\n## 会话卫生：上下文是稀缺资源\n\n"Session hygiene"章节认识到一个关键约束：**上下文是有限的**。带有累积失败尝试的长会话，表现不如带着更好提示的新鲜会话。具体要求：\n\n- 同一问题的两次修正失败后，停止操作，总结所学，请用户用更清晰的提示重置会话\n- 对于会污染主上下文的探索任务，使用子代理\n- 提交时编写描述性的提交信息（主题不超过72字符，正文解释原因），禁止"update file"或"fix bug"式的提交\n\n## 沟通风格：直接而非外交\n\n模板对AI的沟通风格提出了明确的"反外交"要求：\n\n- **直接而非外交**："这不会扩展，因为X"胜过"这是个有趣的方法，但你有没有考虑过……"\n- **默认简洁**：除非用户要求深度，否则两三段短文字足矣。不填充、不重述问题、不用仪式性结尾\n- **有明确答案时给出答案，没有时说明 tradeoffs**\n- **只庆祝真正重要的事**：交付、解决真正困难的问题、指标提升。不庆祝功能想法、范围蔓延或"如果……会不会很酷"\n- **不过度使用项目符号、不主动添加标题、不用 emoji**：散文通常比结构更清晰\n\n## 何时询问，何时继续\n\n模板明确了询问与自主决策的边界：\n\n**询问后再继续的情况：**\n- 请求有两种合理解释，选择会实质影响输出\n- 变更触及被告知是"承重"、版本化或有迁移路径的部分\n- 需要凭证、密钥或没有访问权限的生产资源\n- 用户陈述的目标与字面请求似乎冲突\n\n**无需询问直接继续的情况：**\n- 任务琐碎且可逆（拼写错误、重命名局部变量、添加日志行）\n- 模糊性可通过阅读代码或运行命令解决\n- 用户已在本次会话中回答过该问题\n\n## 自我改进循环：让文件保持生命力\n\n模板的最后章节强调了 AGENTS.md 的演进性质：\n\n每次会话后，如果AI犯了错误，要追问：是因为文件缺少规则，还是因为AI忽略了规则？\n- 如果缺少：在"Project Learnings"下添加具体规则（"Always use X for Y"而非"be careful with Y"）\n- 如果被忽略：规则可能太长、太模糊或被埋没了，需要收紧或上移\n- 每隔几周进行修剪：对每个规则问"删除这条会导致AI犯错吗？"如果不会，就删除\n\n参考标准：Boris Cherny 团队的文件保持在约100行，300行以内是合理上限，超过500行就是在与自己的配置对抗。\n\n## 项目上下文模板\n\n模板提供了"Project context"章节，供具体项目填写：\n\n- **Stack**：语言版本、框架、包管理器、运行时/部署目标\n- **Commands**：安装、构建、测试（全部/单文件）、lint、类型检查、本地运行\n- **Layout**：源码位置、测试位置、禁止修改的文件（生成代码、vendor依赖、遗留区域）\n- **Conventions**：命名、导入风格、错误处理模式、测试模式\n- **Forbidden**：看起来合理但会破坏项目的事项\n\n## 技术实现与兼容性\n\n该 AGENTS.md 文件遵循 Linux Foundation / Agentic AI Foundation 的开放标准，可被 Claude Code、Codex、Cursor、Windsurf、Copilot、Aider、Devin、Amp 等工具原生读取。对于查找其他位置的工具，可通过符号链接兼容：\n\n```bash\nln -s AGENTS.md CLAUDE.md\nln -s AGENTS.md GEMINI.md\n```\n\n## 思想渊源与社区价值\n\n这份模板的独特之处在于其**思想 synthesize**：\n\n- **Andrej Karpathy** 的四大编程原则（先思考、简洁、精准变更、目标驱动）\n- **Boris Cherny** 的 Claude Code 工作流（反应性修剪、保持约100行、只保留修复真实错误的规则）\n- **Anthropic** 的官方 Claude Code 最佳实践（探索-计划-编码-提交、验证循环、上下文是稀缺资源）\n- **社区** 反谄媚模式（明确禁止短语、直接而非外交）\n\n对于正在使用AI编码助手的开发团队，这份模板提供了一个经过深思熟虑的"行为校准器"，有望显著改善人机协作效率。\n\n## 结语\n\nagents-md 项目的价值不仅在于提供了一份可直接使用的模板，更在于它系统性地诊断了当前AI编码助手的常见行为缺陷，并给出了可操作的纠正方案。在AI辅助编程日益普及的今天，如何让人机协作更高效、更专业，这份模板提供了一个值得参考的答案。