Skip to main content

​
为什么本指南很重要

每个工程团队都有一个”最佳实践”文档。问题是 IDE 建议不读它,审查者忘记细微差别,文档慢慢失去权威性。本指南展示如何将您的手册转变为主动护栏,以便 Kody 自动执行这些规则,并在代码偏离时引用相关部分。 我们将重点关注两个构建块:
  • Kody 规则 – 将每个策略要点编码为确定性的文件级或 PR 级检查。
  • 自定义插件 – 当真相源存在于 Git 之外时,从远程 MCP 服务器获取标准。
遵循流程,任何代码库都可以从”手册 PDF”演变为”活策略包”。

​
飞行前检查清单

  • 您有权编辑代码审查设置 → Kody 规则。
  • 策略包位于代码库中(例如 docs/engineering-standards.md)。如果您的位于另一个路径,请相应调整。如果它位于 Notion、Confluence 或 Google Docs 中,计划通过远程 MCP 端点公开它。
  • 您知道哪些主题应该在文件级(控制器、配置)还是 PR 级(功能标志、推出叙述、架构)进行评估。
将手册保持在版本控制下。每次编辑都应通过有所有者签署的 PR。这种纪律使规则扎根于现实。

​
第 1 阶段 – 塑造规则友好的策略包

  1. 创建或重用 markdown 文件,例如 docs/engineering-standards.md。唯一的要求:Kody 必须能够通过 @file:... 引用它。
  2. 将内容组织成简短、可检查的要点:
  1. 添加元数据,如 [所有者:后端平台] 或 [风险:高] 以帮助路由违规。
如果真相源停留在 Git 之外,采用相同的结构,但通过远程 MCP 服务器发布它,以便规则可以调用 @MCP:policy_pack.getSection(...)。
使每个要点都是原子的。当规则触发时,应该没有关于需要更改什么的争论。

​
第 2 阶段 – 将每个规则指向真实文档

规则可以读取文件和远程 MCP 负载。引用实际手册,而不是在每个指令中粘贴片段。
  • 为特定领域的包交换其他文件路径(例如 @file:docs/mobile.md)。
  • 只需要文件的一部分?附加行锚点——@file:docs/engineering-standards.md#L40-L72——以便规则仅使用该部分。
  • 当策略来自 Notion/Confluence/等时,用 @MCP:policy_pack.getSection({"id":"security"}) 替换文件引用。
  • 当规则需要静态模板加上动态数据时,结合两者(例如,@file 用于日志格式 + @MCP:piiRegistry.list() 用于当前敏感字段)。
一个引用使一切保持同步。更新手册一次,每个规则都会执行最新版本。

​
第 3 阶段 – 将部分转换为 Kody 规则

打开代码审查设置 → Kody 规则并将每个策略部分映射到适当的范围。

​
文件级示例

​
PR 级示例

需要新鲜数据来评估规则?在指令中调用 MCP:
规则已经理解变量(fileDiff、pr_files_diff 等)、文件引用和 MCP 调用。请参阅 Kody 规则指南中的完整矩阵。

​
第 4 阶段 – 通过 MCP 镜像外部标准(可选)

有时手册(或其部分)必须保留在 Notion、Confluence、Google Docs 或其他系统中。您仍然可以将其输入 Kody:
  1. 构建或采用公开 listSections() 和 getSection(id) 的远程 MCP 端点。
  2. 通过添加自定义插件安装它。按照自定义插件指南获取确切流程。
  3. 用 @MCP:policy_pack.getSection({"id":"architecture"}) 替换 @file 引用。
  4. 在 MCP 服务器上缓存响应,以便多个规则在每次审查时共享负载。
现在 Kody 执行相同的标准,无论文档位于何处。

​
第 5 阶段 – 测试、观察并保持活力

创建一个违反每个部分的一次性 PR。提及 @kody 并确保内联 + PR 级评论引用正确的要点。
在推出期间,观察每个规则触发的频率。收紧文件 glob,添加排除项,或调整严重性,直到信号满足期望。
每当手册更改时,在同一个 PR 中更新 markdown(或 MCP 负载)和相关规则,以便审查者可以验证整个管道。

​
快速检查清单

  • docs/engineering-standards.md(或 MCP 等效项)存在,带有可扫描的标记要点。
  • 每个规则通过 @file 或 @MCP 引用策略包,确保它读取最新文本。
  • 文件级和 PR 级 Kody 规则涵盖您的关键部分。
  • 可选的 MCP 插件在需要时镜像非代码库标准。
  • 干运行 PR 在广泛推出之前确认了内联评论和 PR 摘要。