把代码风格写进 agent.md：Fabien Sanglard 用 15 条铁律驯服 Claude Code
把代码风格写进 agent.md：Fabien Sanglard 用 15 条铁律驯服 Claude Code
2026 年 8 月 23 日，Doom 源码注释版作者 Fabien Sanglard 在 HN 上贴出自己的 agent.md，7 小时拿下 147 分、75 条评论。他不是在分享一个花哨的 prompt 技巧，而是在说一件更朴素的事：LLM 写代码最大的问题不是不会写，而是写出来的东西不像你写的。
他的思路很直接：与其每次开会话都重复「别用魔法数字」「加个注释解释一下」，不如把这些话写进一个文件，让工具链自动注入。
从「代码不编译」到「代码不像人写的」
Sanglard 的时间线很诚实：2025 年中的第一次尝试，LLM 写的 Rust 代码「would not even compile」，直接被劝退。2026 年 1 月再试，模型能写出复杂的 indexed-binary heap、还能定位 Windows IOCP 下的 polling crate 老 bug——但代价是「spaghetti code with no comments and no structure」。
2026 年 3 月他换到 agentic IDE（Antigravity、VS Code 的 Claude Code 插件），终于能对「staged code」迭代了，但体验变成了给一个「infinitely patient junior CS major」做 code review：
I found myself reviewing the code of an infinitely patient junior CS major with suggestions like "don't use magic numbers", "add a short comment here to explain yourself", or "use short function names".
质量接近手写，但每次新会话都要把同样的建议再说一遍。烦了。
agent.md：把「你」注入到每次会话里
Sanglard 的解法一句话讲完：
When a coding session starts, the coding harness loads a file named agent.md and injects it into the prompt.
等于把你的代码风格偏好「超级微调」进每次会话。他公开了自己的完整 agent.md（链接见文末），规则分三类：
| 类别 | 规则示例 |
|---|---|
| 代码风格 | 少写废话注释、避免魔法数字、函数名 <30 字符、用枚举代替布尔参数 |
| 架构纪律 | 分层边界严格、私有成员默认、不碰无关代码块 |
| 工作流程 | 修 bug 先写测试看到它失败、commit message 遵守 7 条规则 |
其中有几条很值得抄：
- 「Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.」——专治 AI 的彩虹屁。
- 「Always use {}, even on a one-line 'if' statement.」——杜绝悬空 if 的经典坑。
- 「If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix.」——TDD 被写进了系统提示词。
别指望它替你读代码
Sanglard 对 agent.md 的定位很克制，原文原话：
While this "trick" has considerably improved the code generated, this is not a magic bullet that lets me avoid reading the code. LLMs constantly hallucinate and cannot be trusted.
丑话他自己先说了：这不是银弹，幻觉依旧，该 review 还得 review。省下来的精力，他从「清理代码风格」挪到了「架构和设计」上——这才是人该干的活。
他还提到一个实打实的坑：context dilution（出自 Lost in the Middle 论文）。随着上下文变长，模型对中间位置的指令注意力下降。他的两个对策：每个功能开新会话保持上下文短；看到代码质量下滑时直接说一句：
Reload agent.md is enough when I see code quality dropping.
你今天可以做的事
不用自己从头写规则。把他的 agent.md 拿过来当起点（文末链接），放进项目根目录即可。如果同时用 Gemini/Claude 的 CLI，可以用 symlink 让 gemini.md / claude.md 指向同一个 agent.md，一套规则到处生效。
然后按他的习惯跑一周：每次想对模型说「别用魔法数字」的时候，忍住，把这句话加进 agent.md。让模型自己改自己。
FAQ
agent.md 是什么？ 一个配置文件。编码工具链（Claude Code、Gemini CLI 等）会在会话启动时自动读取它并注入 prompt，用来固化你的代码风格和流程偏好。规范讨论见 agents.md 仓库 issue #135。
agent.md 放在哪里？ 项目根目录。Sanglard 说「Placing it in the root of a project should be enough」；多工具共用可以用 symlink 链到同一个文件。
agent.md 和 CLAUDE.md 冲突吗？ 不冲突。agent.md 是通用规范，各工具也有自己的专用文件（claude.md/gemini.md），Sanglard 的做法是用 symlink 让它们指向同一份规则，避免多份维护。
参考来源
- Fabien Sanglard, My agent.md to improve LLM-assisted code quality: https://fabiensanglard.net/agent.md/index.html
- agents.md 规范讨论 issue #135: https://github.com/agentsmd/agents.md/issues/135
- Lost in the Middle（context dilution 出处）: https://arxiv.org/abs/2307.03172
✨ 本文由 DeepSeek 生成初稿，Claude 审核润色。