最佳实践

​

每个关注点一个智能体

​

编写聚焦的指令

1. 要查找什么，要具体：“从 src/domain 导入到 src/http”，而不是”架构问题”。
2. 要忽略什么：风格、命名、其他智能体或 Kody 已经覆盖的内容。
3. 一条发现需要什么证据：“指出体现现有模式的文件”、“展示从来源到使用点的路径”、“引用 docs/ledger.md 中的规则”。

Review the code for quality and best practices.

Flag code in src/http/** that imports from src/infra/** directly.
Handlers reach infrastructure only through the ports in src/domain/ports.
Ignore tests, generated code and naming.
For each finding, name the port the handler should use, or say that
none exists yet.

​

说明一条发现需要什么证据

• 指南中的规则：关联 doc 或 skill，并要求智能体引用规则。引文会对照目标分支上的指南进行检查。
• CLI 结果：CLI 输出中提到该文件的行会作为证据写进评论。
• ast-grep 规则：匹配本身即为证据，无需模型检查。

​

让 glob 明确

• 把 Files 设为智能体关心的代码：写 src/payments/**，不要留空。没有 glob 的智能体会在每个拉取请求上运行。
• 用 Except 排除测试、fixture 和生成的代码。
• 当文件位于忽略路径中、而智能体仍必须读取它们时，显式点名这些文件：package.json、infra/**/*.tf。像 **/*.ts 这样宽泛的 glob，或 src/** 这样的文件夹，不会覆盖被忽略的文件。
• 在目录级别，glob 仍然从代码库根目录开始。

​

Skill 还是 doc？

​

开启前先在真实拉取请求上测试

1. 选择一个最近修改过智能体相关文件的拉取请求，最好是您知道好的审查者会说什么的那种。
2. 运行 Try it。阅读工具调用、它打开的 skills 以及每条发现。
3. 调整指令、glob 或最低严重程度，然后再次运行。
4. 当将要发布的评论正是您希望在拉取请求上看到的内容时，再开启它。

​

阅读丢弃原因

​

控制评论数量

• 对可能产生大量发现的智能体（例如重复代码智能体）设置 Max comments per pull request。保留最严重的那些。
• 对于发现放在一起更好读的智能体（例如覆盖率报告），使用 One PR comment。
• 当修复只能靠猜（例如架构调整）时，使用 Suggested fix: Never。