通过 agent.md 提升 LLM 辅助代码质量

使用 agent.md 文件允许开发者将持久的风格偏好和架构约束直接注入 LLM 的提示中，从而将人类的角色从纠正基础代码风格转变为专注于高层次设计。这种方法减少了在 AI 辅助编码会话中反复进行手动反馈的繁琐重复工作。

agent.md 框架

agent.md 文件是一个项目根目录下的配置文件，由代理型 IDE 和编码环境自动加载，用于微调 LLM 的行为。开发者无需在每次新会话中重复相同的风格修正，而是可以将这些要求编码为单一的权威来源。

核心编码规范

为确保生产级别的代码质量，建议在 agent.md 文件中包含以下规则：

  • 简洁性： 在注释、提交消息和提示回复中尽可能使用最少的词语。避免使用最高级形容词和赞美性语言。
  • 整洁代码实践：
    • 将重复或有意义的值提取为描述性常量或枚举，以避免“魔法数字”。
    • 通过使用提前返回和 continue 语句减少缩进，避免“箭头反模式”。
    • 可见性： 默认将所有字段和函数设为私有；在更改访问修饰符为内部或公共之前，必须明确批准。
  • 架构与抽象：
    • 将底层机制（例如原始硬件 I/O、套接字流）封装在专用驱动层中。
    • 遵循严格的分层边界层次结构，每一层仅与下方的直接相邻层通信。
  • 文档： 添加简短注释，解释代码块的 作用 和 原因，对复杂系统可使用示例或 ASCII 图形说明。
  • 测试： 修复 bug 时，LLM 必须首先编写一个失败的测试，观察失败情况，再编写修复代码并验证其通过。

提交消息规范

为保持干净的 Git 历史记录，agent.md 文件可强制执行 7 条提交消息规则：

  1. 用空行将主题行与正文分隔开。
  2. 限制主题行长度为 50 个字符（硬性上限为 72）。
  3. 主题行首字母大写。
  4. 不以句号结尾主题行。
  5. 使用祈使语气（例如“修复 bug”而非“已修复 bug”）。
  6. 手动在 72 个字符处换行正文文本。
  7. 使用正文解释 做什么 和 为什么做，而非 怎么做。

管理上下文与稀释问题

随着上下文窗口增大，LLM 会遭遇“上下文稀释”（或“注意力稀释”）现象，即模型对提示中间位置的指令关注度降低。这一现象在《Lost in the Middle》研究论文中有详细记录。

为缓解此问题，开发者应：

  1. 限制会话时长： 为每个独立功能启动新会话，以保持上下文简短。
  2. 强制重载： 当代码质量开始下降时，明确命令代理执行“Reload agent.md”。
  3. 自动化更新： 在会话中发现新规则时，让 AI 代理自身更新 agent.md 文件。

社区观点与批评

尽管 agent.md 方法对部分开发者有效，但开发社区也提出了若干关于其实施的反面观点：

"这些规则中的很多应该通过 linting 强制执行……真正重要的是代码本身。"

批评者认为，许多规则——如为单行 if 语句使用大括号或限制函数名长度——更适合由自动化 linter 处理，而非通过提示指令实现。其他开发者指出，过于臃肿的 agent.md 文件实际上会增加上下文消耗并降低性能。

社区还提出了以下建议：

  • 关注点分离： 将编码规范移至 CODING_STANDARDS.md 文件，而将 agent.md 保留用于交互偏好设置。
  • 收敛规则： 一些开发者实施“收敛规则”，要求每个任务必须以三种状态之一结束：成功、有意义的进展，或诚实的停止，以防止 AI 生成无穷无尽且脆弱的补丁。
  • 简化技术英语： 使用指令遵循 "ASD-STE100 简化技术英语"，进一步减少 AI 的冗余表达。

Sources

相关