从 2025 年中期在 Rust 语言的 mDNS 库中连编译都无法通过，到 2026 年初能够独立定位 Windows IOCP（输入输出完成端口）底层轮询机制的隐蔽缺陷，大语言模型的代码编写能力经历了一次跨越。表面上看，AI 辅助编程难以交付生产级项目是模型推理能力的欠缺，本质上则是无状态交互机制引发的高频沟通损耗：开发者在每个新会话中都在重复输入相同的代码风格、架构分层与测试规范。
知名游戏引擎黑书《Game Engine Black Book》作者 Fabien Sanglard 近期公开了他的实战解法。通过在代码仓库根目录建立名为 agent.md 的规范文件，并借助现代编码环境（Coding Harness）的自动注入机制，成功将 AI 生成代码的质量拉升至符合严苛工程标准的水平。
| 阶段 | 核心问题 | 留下的硬伤 |
|---|---|---|
| 2025 年中期（初代尝试） | 模型无法理解跨模块上下文与语言严格类型系统 | 代码甚至无法通过编译器静态检查 |
| 2026 年初（能力跃升） | 能写复杂二叉堆与系统底层代码，但缺乏工程自律 | 面条式逻辑、缺少注释与结构，人工重构成本抵消提速红利 |
| 2026 年 3 月至今（Agentic IDE） | 支持分阶段审核代码，但每个新会话都要反复强调规范 | 提示词输入重复琐碎，极易诱发开发者沟通疲劳 |
从重复摩擦到规则固化：agent.md 的工作机制
现代 Agentic IDE（如 Claude Code 插件、Antigravity 等开发套件）在启动编码会话时，会自动扫描并加载项目根目录下的约定文件作为系统上下文。这是低成本、高收益的开发干预点。
Sanglard 将每一次对 AI 编码助手的风格纠偏和规则指令，统一沉淀进项目根目录的 agent.md。为了适配不同厂商工具的命名偏好，开发者只需将 claude.md 或 gemini.md 以软链接形式指向 agent.md，即可在不同模型与编辑器间实现统一的工程约束。
更关键的改变在于维护方式的转向。开发者不再需要反复手动修改规范文件，而在会话中发现模型违背原则时，直接指令 AI “把刚才修正的规范同步写入 agent.md”。让 Agent 自行沉淀规范资产，将提示词维护从被动的文本编辑转为主动的工程演进。
# 在项目根目录建立统一的规则链
ln -s agent.md claude.md
ln -s agent.md gemini.md
15 条工程法则：兼顾微观表达与宏观架构
Sanglard 总结的规则清单摒弃了模糊的抽象要求，全部采用具备确定性动作的约束准则：
- 精炼人类阅读文本：注释、提交信息（Git Commit Message）以及模型生成的解释文本遵循极简原则，去除一切冗余修饰。
- 剔除虚假赞美：明确禁止模型使用“你说得完全正确”等奉承语料，要求模型直接给出冷酷的技术实情与潜在风险。
- 消除魔法值：严禁在逻辑中内联硬编码数字或字符串，所有数值均需提取为常量或枚举。源自开放标准的值（例如 HTTP 200 状态码）必须调用标准库或常量定义。
- 扁平化控制流：严格禁止深层嵌套的箭头反模式（Arrow Anti-Pattern），广泛使用提前返回（Early Return）和
continue减少缩进。 - 严控函数命名长度：函数名称字符数强制限制在 30 字符以内，迫使逻辑拆分粒度更加精准。
- 参数强类型化：杜绝使用无状态意义的布尔值作为函数入参，统一改用具备语义的枚举类型。
- 逻辑分块呼吸感：在不同职责的代码逻辑块之间强制插入空行，提升视觉可读性。
- 精准注释与架构图解：注释仅解释“做了什么”和“为何这么做”，复杂系统设计必须在注释中附带 ASCII 架构流转图。
- 可见性变更安全审查：成员可见性修改被定义为破坏性设计。所有成员默认保持私有，模型在将成员由
private变更为internal或public之前，必须获得开发者的显式批准。 - 抽象层次强隔离：底层系统机制（如硬件 I/O、裸套接字网络通信、扇区解析）必须完全封装在驱动层或底层抽象中，上层只暴露纯净的高级 API。
- 最小化代码扰动：严禁触碰与当前需求无关的代码行，禁止顺手重构无关模块，严格最小化变更行数。
- 严格单向分层边界：代码架构严格按层通信，控制器与 UI 层绝对禁止越级直连裸数据库查询或底层驱动。
- 括号作用域强制约束：即便是单行条件分支（
if），也强制使用花括号{}包裹。 - 标准化七条提交规范：提交信息必须满足主题行不超过 50 字符、首字母大写、结尾无句号、使用祈使语气、主题与正文空行分隔、正文单行不超过 72 字符，且正文仅阐述原因而非实现细节。
- 测试驱动修障（TDD）：修复缺陷时，强制执行“编写可复现的失败测试、提交修复补丁、验证测试通过”的三步顺序。
破解注意力稀释：上下文控制与主动重载
大语言模型存在已知的“迷失在中间（Lost in the Middle）”现象，随着会话长度增加和 Token 消耗攀升，模型对早前注入的提示词关注度会迅速衰减，这种现象被称为上下文稀释（Context Dilution）。
面对上下文稀释导致的质量退化，开发者应当采取两项应对手段：
- 微型会话管理：放弃单个长会话完成全部模块的做法，坚持“一个功能特性开设一个新会话”的原则，将上下文长度始终控制在高效区间。
- 显式上下文重载：在较长交互中一旦观察到代码缩进变深、单行分支不加括号等违背规则的苗头，立即向环境输入“Reload agent.md”，强制模型在最新注意力窗口中重新对齐工程基准。
综合判断与现实边界
agent.md 不是让 AI 具备自主架构设计能力的魔法，而是用来消除低级工程噪音的防护栏。
这项实践的价值在于：它并非替代人工的代码审查，而是把开发者的注意力从挑剔代码格式、缩进层级和魔法数字，解放并聚焦到底层系统设计与架构合理性上。 把模型视为一个极其勤奋但缺少工程记忆的高级初级工程师，将一切隐性规则显性化，是实现高质量 Vibe Coding 的可靠途径。
一个未解决的问题
当开发项目引入多个具备不同职责的自主 Agent（如分别负责测试生成、安全审计、性能调优的专属智能体）协同作业时，单一的 agent.md 文件难以区分不同角色的权限与规则冲突。如何在维持单一真实数据源（Single Source of Truth）的前提下，构建模块化、具备继承关系的规则拓扑，仍是当前编码框架尚未标准化的挑战。
引用来源
- Fabien Sanglard. My agent.md to improve LLM-assisted code quality. 2026-08-21. https://fabiensanglard.net/agent.md/index.html
- Hacker News. Discussion on the AGENTS.md context-file standard. 2026-08-19. https://github.com/anthropics/claude-code/issues/6235
- Anthropic Documentation. Claude Code: Managing Context and Memory with Project Rules. 2026-08-10. https://docs.anthropic.com/en/docs/claude-code/context-management
- AGENTS.md. A simple, open format for guiding coding agents (used by over 60k open-source projects). 2026-08-05. https://agents.md/
- GNU Emacs devel. Emacs project adds official AGENTS.md. 2026-08-06. https://lists.gnu.org/archive/html/emacs-devel/2026-08/msg00077.html
