作者在2025年首次尝试用LLM辅助编程，代码质量差且无法编译。2026年初虽能解决复杂问题，但代码仍混乱。通过使用agentic IDE反复提示“不要用魔法数字”“加注释”等，最终大幅提升代码质量，接近手写水平。

好的，这是根据您的要求，对原文进行中文重述和精简后的版本：

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

作者最初在2025年中尝试用LLM写代码，效果不佳，生成的代码甚至无法编译。到2026年1月再次尝试时，情况有所好转，LLM能写出复杂的数据结构并定位到晦涩的bug。然而，代码质量依然堪忧，结构混乱且缺乏注释，清理代码所耗费的时间抵消了效率提升。

2026年3月，作者开始使用支持“迭代”的智能IDE，并发现自己像在指导一位耐心但经验不足的初级程序员，不断重复“不要用魔法数字”、“加个注释”等建议。代码质量虽有提升，但过程繁琐。

Agent.md 的解决方案

作者发现，在编码会话启动时，工具会加载一个名为 agent.md 的文件并将其注入提示词中。这成为了一个完美的“微调”代码风格偏好的地方。作者将自己反复提出的建议都写入了这个文件。

作者分享了他的 agent.md 文件作为起点，其中包含以下核心规则：

• 简洁沟通：为人类阅读的内容（注释、提交信息等）使用最少的词语，直击要点。
• 避免空泛赞美：直接给出客观事实。
• 消除魔法值：将重复或有意义的值提取为常量或枚举。
• 减少缩进：避免“箭头反模式”，善用提前返回。
• 函数名简短：不超过30个字符。
• 用枚举替代布尔参数。
• 代码块间留空行，增加可读性。
• 添加简洁注释，说明代码块“做什么”和“为什么”，必要时可用ASCII图。
• 谨慎修改成员可见性：默认保持私有，修改需用户明确批准。
• 分层抽象：底层细节封装在驱动层，对外暴露高层API。
• 不修改无关代码：最小化变更行数。
• 严格遵循分层边界：各层只能与直接相邻的下层通信。
• 始终使用花括号，即使是一行if语句。
• 遵循7条提交信息规范（如主题行50字内、使用祈使语气等）。
• 修复bug前先写测试：先写测试并观察其失败，再写修复代码并观察测试通过。

作者强调，这个“技巧”虽然显著提升了代码质量，但并非万能药。LLM仍会“幻觉”，他仍需花精力在架构和设计上，而非代码风格。

应对“注意力稀释”

LLM存在“上下文稀释”问题，即随着上下文增长，模型会忽略中间部分的指令。作者发现两种缓解方法：

1. 保持上下文简短，每个功能开启新会话。
2. 当代码质量下降时，明确要求工具重新加载 agent.md。

自动更新 agent.md

作者无需手动编辑文件，而是直接让智能体（agent）自己更新 agent.md 文件。

根据评论内容，主要观点及论据总结如下：

观点一：应通过代码检查工具强制执行编码规范
- 评论1（评分：无，作者：OptionOfT）指出，许多规范应通过linting工具强制执行，例如“始终使用花括号，即使是一行if语句”和“函数名不超过30个字符”。
- 关键引用：
- "A bunch of these should be enforce with linting, that way people who still hand-craft code get the same kind of feedback"
- "Always use {}, even on a one-line 'if' statement. & Keep function names short. Less than 30 characters."

观点二：注释应简洁说明“做什么”和“为什么”，而非重复代码
- 评论1（评分：无，作者：OptionOfT）强调，注释应解释代码块的功能和原因，并举例或使用ASCII图说明系统，因为“代码本身已说明‘是什么’”。
- 关键引用：
- "Add a small, to the point, comment to explain what the block does and why. Use examples when possible."
- "The what is the code."

观点三：使用简化技术英语可减少冗长和浮夸
- 评论2（评分：无，作者：oumua_don17）推荐在AGENTS.md中使用ASD-STE100简化技术英语，认为这能有效减少或消除冗长和浮夸。
- 关键引用：
- "Just this one line in AGENTS.md has given better results to reduce if not eliminate verbosity and grandeur."
- "Always use ASD-STE100 Simplified Technical English"

平衡性说明：评论1侧重工具强制与注释原则，评论2侧重语言规范，两者均强调简洁性，但切入角度不同。无评分差异，观点间无直接冲突。