> ## 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.

# 自定义提示

> 为每个类别和建议的编写方式自定义 Kody 的审查提示以匹配团队的需求

自定义提示让您完全控制 Kody 如何分析代码和沟通发现。定制 AI 在每个审查类别中查找的内容,以及如何呈现建议以匹配团队的标准和沟通风格。

<Card title="访问自定义提示设置" icon="gear" href="https://app.kodus.io/settings/code-review/global/custom-prompts">
  为组织中的所有代码库配置自定义提示
</Card>

## 为什么使用自定义提示?

<CardGroup cols={2}>
  <Card title="团队特定标准" icon="users">
    使 Kody 的审查与团队独特的编码标准、架构模式和最佳实践保持一致
  </Card>

  <Card title="模型优化" icon="brain">
    在使用 BYOK 时,为特定 AI 模型的优势精心设计提示
  </Card>

  <Card title="焦点控制" icon="bullseye">
    将 Kody 的注意力引导到对项目最重要的问题上并减少噪音
  </Card>

  <Card title="沟通风格" icon="comments">
    自定义 Kody 如何呈现建议 - 对关键问题详细或对次要问题简洁
  </Card>
</CardGroup>

## 自定义提示如何工作

自定义提示在两个级别运行:

### 类别提示

定义 Kody 在每个审查类别中查找的内容:

<Tabs>
  <Tab title="错误">
    \*\*焦点:\*\*代码正确性和执行问题

    默认覆盖范围:

    * 执行中断(未处理的异常)
    * 错误结果(不正确的输出)
    * 资源泄漏(文件、连接、内存)
    * 状态损坏(无效的对象/数据状态)
    * 逻辑错误(不正确的控制流)
    * 竞态条件(并发访问问题)

    \*\*最大长度:\*\*2000 字符
  </Tab>

  <Tab title="安全性">
    \*\*焦点:\*\*安全漏洞和数据保护

    默认覆盖范围:

    * 注入漏洞(SQL/NoSQL/命令/LDAP)
    * 身份验证/授权缺陷(缺少检查、权限提升)
    * 数据暴露(日志/响应中的敏感数据)
    * 加密问题(弱算法、硬编码密钥)
    * 输入验证差距(缺少清理/边界检查)
    * 会话管理(可预测的令牌、缺少过期)

    \*\*最大长度:\*\*2000 字符
  </Tab>

  <Tab title="性能">
    \*\*焦点:\*\*速度、效率和资源优化

    默认覆盖范围:

    * 算法复杂性(当可能 O(n)时为 O(n²))
    * 冗余操作(重复计算、不必要的循环)
    * 内存浪费(大量分配、泄漏)
    * 阻塞操作(关键路径中的同步 I/O)
    * 数据库效率低下(N+1、缺少索引、全表扫描)
    * 缓存未命中(不利用可用缓存)

    \*\*最大长度:\*\*2000 字符
  </Tab>
</Tabs>

### 建议提示

控制 Kody 如何沟通每个单独的建议。这自定义了出现在 PR 评论中的消息格式和语气,例如:

```
新文件 'create-or-update-issues-parameter.dto.ts' 不遵循
公司的命名约定。根据 Kody 规则,所有新文件
必须使用驼峰命名法。请将文件重命名为 'createOrUpdateIssuesParameter.dto.ts'
以遵守标准。
```

您的自定义提示指示 Kody 如何编写建议消息。提示接收有关严重性级别、问题描述、建议代码以及是否为 Kody 规则违规的上下文。Kody 使用此上下文以及您的提示为每个建议生成适当的消息。

您可以根据团队的需求自定义语气、详细程度和沟通风格 - 从关键问题的详细解释到次要问题的简洁反馈。

## 外部引用

所有自定义提示——类别、建议和 PR 摘要——都支持引用 Kody 可以访问的代码库中的真实文件。当您保存更新时,Kody 会自动检测外部引用并为将来的审查解析它们。

* 使用 `@file:path/to/file.ts` 指向您正在编辑的代码库中的文件;Kody 将首先尝试在本地找到路径。
* 在引用另一个代码库中的文件或在全局级别编辑提示时包含 `@repo:org/project`。
* 首选精确的 blob 样式路径而不是占位符,以便模型可以可靠地找到正确的文件。
* 保存后,Kody 在后台处理引用。检查提示编辑器旁边的状态指示器以确认解析何时完成。

## 最佳实践

### 对上下文要具体

<CardGroup cols={2}>
  <Card title="做:上下文特定" icon="check">
    ```
    错误类别提示:
    专注于我们 Java 服务中的空指针异常、
    DAO 层中未关闭的数据库连接以及
    异步事件处理程序中的竞态条件。检查
    try-finally 块中的正确资源清理。
    ```
  </Card>

  <Card title="不要:太通用" icon="xmark">
    ```
    错误类别提示:
    在代码中查找错误。
    检查问题和问题。
    ```
  </Card>
</CardGroup>

### 避免提示之间的冗余

每个类别应该有不同的焦点。不要在不同的提示中重复相同的指令。

<Accordion title="示例:正确分离">
  **错误类别:**
  专注于执行正确性、Java 服务中的空指针异常和资源清理。

  **安全类别:**
  专注于 API 端点中的 SQL 注入、XSS 和 CSRF。验证输入清理和参数化查询。

  **性能类别:**
  专注于 N+1 查询、缺少数据库索引和数据处理中的低效循环。

  \*\*结果:\*\*每个提示都有清晰、不重叠的焦点。
</Accordion>

<Accordion title="反模式:冗余提示">
  **错误类别:**
  检查空指针、SQL 注入和慢查询。

  **安全类别:**
  查找 SQL 注入、空指针和性能问题。

  **性能类别:**
  查找慢查询、空指针和安全漏洞。

  \*\*问题:\*\*所有提示重叠,使模型混淆并降低审查质量。
</Accordion>

### 小心使用示例

<Tabs>
  <Tab title="好:模式描述">
    ```
    检测数据库查询中的 SQL 注入:
    - SQL 语句中的原始字符串连接
    - 查询字符串中的用户输入直接使用
    - 缺少参数化查询或 ORM
    - 动态查询构造没有清理
    ```

    这广泛描述了模式,捕获多个变体。
  </Tab>

  <Tab title="风险:特定示例">
    ```
    检测如下 SQL 注入:
    query = "SELECT * FROM users WHERE id = " + userId
    ```

    模型可能只标记此确切模式并错过:

    * 模板文字:`SELECT * FROM users WHERE id = ${userId}`
    * 字符串格式化:`f"SELECT * FROM users WHERE id = {userId}"`
    * 其他 SQL 注入向量
  </Tab>
</Tabs>

### 保持建议可扫描

对于建议提示,使消息易于扫描,因为开发人员一次审查许多:

<Tabs>
  <Tab title="好:清晰结构">
    ```
    编写具有清晰结构的建议。对于关键问题,
    以 🚨 表情符号开头,陈述问题,然后显示"修复:"
    后跟代码。对于其他严重性,保持简单 -
    只是问题和建议的代码。

    首先放置重要信息,以便开发人员可以快速
    了解需要做什么。
    ```

    清晰的层次结构,重要信息优先
  </Tab>

  <Tab title="差:文本墙">
    ```
    解释问题以及为什么它很重要,因为它可能
    在生产中引起问题,开发人员应该通过
    应用将解决问题的建议代码更改来修复它。
    ```

    难以扫描,掩埋操作
  </Tab>
</Tabs>

### 有意义地使用上下文

仅在有真正原因时区分建议格式:

<Tabs>
  <Tab title="好:有意义的区别">
    ```
    对于 Kody 规则违规,使用更严格的语气:
    "**团队标准**:[问题]。要求:[代码]"

    对于标准建议,使用更友好的语气:
    "[问题]。建议:[代码]"

    语言差异使要求级别清晰。
    ```

    清晰的区别:规则是要求,建议是建议
  </Tab>

  <Tab title="差:表面标签">
    ```
    对于 Kody 规则,在问题前添加"[规则]"前缀。
    对于建议,在问题前添加"[建议]"前缀。
    否则以相同的方式格式化它们。
    ```

    只添加标签不会增加价值
  </Tab>
</Tabs>

## 用例

<AccordionGroup>
  <Accordion title="行业特定要求">
    \*\*场景:\*\*具有 HIPAA 合规要求的医疗保健应用程序

    **自定义安全提示:**

    ```
    专注于数据处理中的 HIPAA 合规性:
    - 日志或错误中的 PHI(受保护健康信息)暴露
    - PHI 静态和传输中缺少加密
    - 患者数据的访问控制不足
    - PHI 访问的审计日志差距
    - 数据保留违规
    - 缺少患者同意验证
    ```

    \*\*好处:\*\*Kody 捕获通用安全审查可能错过的特定合规问题。
  </Accordion>

  <Accordion title="技术栈优化">
    \*\*场景:\*\*具有特定模式的 React/Node.js 应用程序

    **自定义错误提示:**

    ```
    专注于 React 和 Node.js 常见陷阱:
    - useEffect/useMemo 中缺少依赖数组
    - 异步处理程序中未处理的 promise 拒绝
    - 来自事件监听器清理的内存泄漏
    - 状态更新中的竞态条件
    - 缺少错误边界
    - Express 中间件中未捕获的异常
    ```

    \*\*好处:\*\*审查专注于您的技术栈的特定陷阱。
  </Accordion>

  <Accordion title="模型特定调整">
    \*\*场景:\*\*通过 BYOK 使用 Gemini 2.5 Flash 进行成本优化

    **自定义性能提示:**

    ```
    分析算法效率和资源使用。
    以这种格式列出特定问题:
    1. 问题类型和位置
    2. 当前复杂性
    3. 优化建议
    4. 预期改进

    优先:数据库查询、循环、内存分配。
    ```

    \*\*好处:\*\*Gemini 处理得非常好的结构化输出格式,提高审查质量。
  </Accordion>

  <Accordion title="基于严重性的沟通">
    \*\*场景:\*\*想要对关键问题进行详细解释但对次要问题进行简洁反馈

    **自定义建议提示:**

    ```
    编写建议时,根据严重性调整详细程度:

    对于严重问题:以"🚨 严重:"开头,后跟问题。
    添加一行解释"这需要立即关注。"然后提供
    带有"修复:"前缀的修复。

    对于高严重性:使用"⚠️"表情符号,陈述问题,然后显示修复
    带有"修复:"前缀。

    对于中等和低:保持简短 - 只陈述问题并显示
    建议的代码直接没有额外的解释。
    ```

    \*\*好处:\*\*关键问题获得额外的上下文,而次要问题保持简短,提高审查效率。
  </Accordion>

  <Accordion title="直接简洁的反馈">
    \*\*场景:\*\*团队更喜欢最少、可操作的反馈

    **自定义建议提示:**

    ```
    直接简洁。用一句话陈述问题,然后立即
    用"修复:"前缀显示修复。没有额外的上下文或解释。
    ```

    \*\*好处:\*\*每个建议都简短到位,没有额外的上下文。
  </Accordion>

  <Accordion title="教育性建议">
    \*\*场景:\*\*初级开发人员从详细解释中受益

    **自定义建议提示:**

    ```
    将建议分为三个部分:

    1. **问题:**清楚地陈述问题
    2. **为什么这很重要:**根据严重性解释影响:
       - 严重:可能导致生产失败或安全漏洞
       - 高:可能导致错误或性能问题
       - 中等/低:改善代码质量和可维护性
    3. **修复:**显示推荐的代码更改

    使解释具有教育性并帮助开发人员了解为什么它很重要。
    ```

    \*\*好处:\*\*每个建议都包括有关重要性的教育背景。
  </Accordion>

  <Accordion title="规则与建议的不同语气">
    \*\*场景:\*\*Kody 规则是严格要求,建议是建议

    **自定义建议提示:**

    ```
    根据类型使用不同的语气:

    对于 Kody 规则违规:
    - 以粗体"**团队标准违规**"开头
    - 陈述问题
    - 添加"这违反了记录的团队标准。"
    - 显示"必需的修复:"后跟代码

    对于标准建议:
    - 直接陈述问题
    - 显示"建议的改进:"后跟代码
    - 使用友好、建议性的语气
    ```

    \*\*好处:\*\*强制规则和可选建议之间的明确区别。
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="审查太吵">
    \*\*症状:\*\*自定义后太多低价值建议

    **解决方案:**

    * 使提示更具体和集中
    * 为您想要忽略的模式添加排除项
    * 在[建议控制](/how_to_use/en/code_review/configs/suggestion_control)中提高最低严重性阈值
    * 检查类别提示之间的冗余
  </Accordion>

  <Accordion title="缺少预期问题">
    \*\*症状:\*\*Kody 没有捕获应该捕获的问题

    **解决方案:**

    * 审查您的提示是否太窄或示例特定
    * 检查问题是否属于您未自定义的类别
    * 尝试重置为默认以查看是否捕获问题
    * 考虑问题是否可能被分类在不同的严重性下
  </Accordion>

  <Accordion title="不一致的结果">
    \*\*症状:\*\*有时标记相同类型的问题,但并非总是如此

    **解决方案:**

    * 确保提示清晰明确
    * 删除不同提示之间的冲突指令
    * 检查您是否使用太具体的示例
    * 考虑主/后备中的不同模型是否具有不同的功能
  </Accordion>

  <Accordion title="不确定要自定义什么">
    \*\*症状:\*\*想要使用自定义提示但不确定从哪里开始

    **解决方案:**

    * 先运行默认审查一周
    * 注意误报或遗漏问题的模式
    * 仅自定义与这些模式相关的特定提示
    * 保持其他提示为默认,直到您看到明确的需求
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="自定义提示适用于所有代码库吗?">
    这取决于您在哪里设置它们:

    * \*\*全局设置:\*\*适用于组织中的所有代码库
    * \*\*每个代码库设置:\*\*覆盖该特定代码库的全局设置

    这使您可以拥有组织范围的标准,并在需要时进行特定于代码库的覆盖。
  </Accordion>

  <Accordion title="在自定义之前我可以看到默认提示吗?">
    可以。点击设置中的任何提示以查看默认内容。
  </Accordion>

  <Accordion title="当我更改提示时,现有 PR 会发生什么?">
    更改仅影响新审查。使用 `@kody start-review` 重新运行以将新提示应用于现有 PR。
  </Accordion>

  <Accordion title="我可以使用 kodus-config.yml 自定义提示吗?">
    不可以。自定义提示仅限网页以确保有意更改。其他设置(忽略的路径、分支)可以使用 `kodus-config.yml`。
  </Accordion>

  <Accordion title="我应该自定义所有提示还是只是一些?">
    仅自定义具有明确、特定需求的提示。保持其他提示为默认以受益于我们的改进。从 1-2 个提示开始。
  </Accordion>

  <Accordion title="自定义提示如何与 BYOK 配合使用?">
    无缝工作。根据模型的优势定制提示。主和后备都使用相同的自定义提示。
  </Accordion>

  <Accordion title="类别提示和建议提示之间有什么区别?">
    **类别提示**控制 Kody 在每个审查类别中分析什么。**建议提示**控制 Kody 如何向团队呈现发现。您可以独立自定义两者。
  </Accordion>

  <Accordion title="我可以在建议提示中使用 markdown 吗?">
    可以。建议提示支持标准 markdown 格式,包括粗体、斜体、代码块和链接。
  </Accordion>

  <Accordion title="如果我的建议模板有语法错误会怎样?">
    Kody 将回退到默认建议格式并在设置中通知您错误。
  </Accordion>

  <Accordion title="建议提示对 Kody 规则和标准建议都有效吗?">
    可以。使用 `isKodyRule` 变量在同一提示中为规则 vs. 建议创建不同的消息。
  </Accordion>
</AccordionGroup>