> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳实践

> 编写能在拉取请求中发现真实问题、其余时候保持安静的自定义智能体。

<Callout icon="alien" iconType="regular">自定义智能体目前处于 beta 阶段。行为和界面仍可能变化。</Callout>

## 每个关注点一个智能体

同时检查架构、安全和测试覆盖的智能体，指令会写得含糊，发现也会含糊。把它拆开：每个关注点一个智能体，各自有自己的文件、指南和标签。标签让团队知道是谁在说话，每个智能体的页面会显示它过去 30 天发布的评论，你能看出哪个智能体噪音最大。

## 编写聚焦的指令

把指令写成给一位熟悉代码库的审查者的简报，涵盖三件事：

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

智能体只报告其指令要求的内容，验证器会丢弃超出该关注范围的一切。指令没有要求的发现，您就不会看到。

<Tabs>
  <Tab title="含糊">
    ```text theme={null}
    Review the code for quality and best practices.
    ```
  </Tab>

  <Tab title="聚焦">
    ```text theme={null}
    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.
    ```
  </Tab>
</Tabs>

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

发现在发布前会被检查。给智能体一些它能证明的东西：

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

只存在于某人脑中的规则无法被引用，所以请把它写进指令或某个 doc 中。

## 让 glob 明确

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

## Skill 还是 doc？

| 在以下情况使用 **doc** | 在以下情况使用 **skill** |
| - | - |
| 指南很短，适用于智能体审查的每个变更。 | 规则很多，或规则只适用于部分变更。 |
| 您希望每次都完整读取。 | 您希望智能体只在变更需要时打开它，连同其参考文件。 |

Docs 计入每个智能体 20,000 token 的预算。冗长的手册更适合做成带参考文件的 skill。

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

新智能体默认关闭。开启之前：

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

`@kody -v <name>` 可以在真实的拉取请求上做同样的事并发布评论，即使智能体仍处于关闭状态。

## 阅读丢弃原因

被丢弃的发现会告诉您智能体该改什么：

| 原因 | 要改什么 |
| - | - |
| 找不到引文 | 目标分支上的指南中没有这段文字。关联正确的指南，或把规则写进指令。 |
| 超出智能体的关注范围 | 指令没有要求它。补充进去，或交给 Kody。 |
| 代码中没有依据 | 智能体在猜测。在指令中要求具体的证据。 |
| 低于最低严重程度，或超出评论上限 | 预期内的过滤。如果想看到更多，降低下限。 |

## 控制评论数量

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.