我的agent.md提升LLM辅助代码质量

我的 agent.md：提升 LLM 辅助编码的质量

2026 年 8 月 21 日

我的 agent.md：提升 LLM 辅助编码的质量

第一次尝试用 LLM 加快写代码的速度是在 2025 年年中。印象不怎么样。当时我在做 libadbmdns，一个 Rust 写的 mDNS 实现。它生成的代码连编译都过不了。

2026 年 1 月我又试了一次。这回好多了。它不仅写出了一个复杂的索引二叉堆类，还定位到了 polling crate 里一个因 Windows IOCP 实现而起的隐蔽 bug。

但代码质量惨不忍睹。一堆意大利面条式的代码，没有注释，没有结构。挺酷，可如果提速的收益全花在把代码清理到生产级标准上，那用 LLM 就不现实了。

反复迭代，反复重复自己

2026 年 3 月，我开始用 Antigravity 和 VS Code 的 Claude Code 插件这类 agentic IDE。这下可以对“暂存”的代码“迭代”了。我发现自己像是在给一个极有耐心的计算机专业低年级学生做 code review，提的意见无非是“别用魔法数字”“这里加一句短注释说明一下”“函数名短一点”。

代码质量大幅提升，已经很接近我“手写”出来的东西，但过程很烦。每开一个新会话，我都得把同样的话再说一遍。

agent.md 救场

编码会话启动时，编码 harness 会加载一个名为 agent.md 的文件并注入 prompt。这正是精细调整编码风格偏好的理想位置。每当我发现自己又在重复同一条改进建议，就把它写进去。

下面是我的 agent.md，需要的话可以拿它当起点。放在项目根目录就够了。或者把 gemini.md/claude.md 软链接到 agent.md，这样在任何地方都能生效。

# FAB's AGENT.MD

- When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.

- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.

- Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.

- Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.

- Keep function names short. Less than 30 characters.

- Use enums instead of booleans for function parameters.

- Let the reader of the code breathe. Add empty lines between logical blocks of code.

- Add a small, to the point, comment to explain *what* the block does and *why*. Use examples when possible. Propose ASCII drawings to explain complete systems.

- Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.

- Program to levels of abstraction. Lower-level mechanics (e.g., raw hardware I/O, sector parsing, direct socket streams) must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details.

- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature.

- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).

- Always use {}, even on a one-line "if" statement.

When you write a commit message, follow these 7 rules:
Rule 1: Separate the subject line from the body with a single blank line.
Rule 2: Limit the subject line to 50 characters (72 is the absolute hard limit).
Rule 3: Capitalize the first letter of the subject line.
Rule 4: Do not end the subject line with a period.
Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature," 
 not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied,
 this commit will [your subject line here]".
Rule 6: Wrap the body text manually at 72 characters to prevent Git formatting issues.
Rule 7: Use the body to explain what and why vs. how. Assume the code explains the how;
 the message must explain the context and reasoning. 

- 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. And observe the test passing. 

这个“技巧”确实让生成的代码好了不少，但它不是什么灵丹妙药，不能让我省掉读代码这一步。LLM 会不断产生幻觉，不可信。我仍然要大量验证和迭代，只不过现在关注的重点通常是架构和设计，而不是代码风格。

如何处理上下文稀释

LLM 有一个恼人的现象，叫“上下文稀释”或“注意力稀释”，Lost in the Middle 这篇论文对此做了描述。随着上下文变长，模型会逐渐减少对上下文中段指令的关注，转而更关注开头和结尾的内容。写到这里时，这种现象的成因还没有被很好地理解。我只找到两种减轻其影响的办法。

1. 保持上下文简短。也就是说，每个功能开一个新的会话。
2. 明确要求 harness 重新加载 agent.md。当我发现代码质量下降时，说一句“Reload agent.md”就够了。

自动更新 agent.md

不必每次想加一条新规则都打开编辑器。我现在做的是让 agent 去更新 agent.md。

---