演讲者背景与核心目标

本次分享由 Qodo AI（原 CodeRabbit）的开发者关系负责人 Nnenna Ndukwe 主讲。Qodo AI 最初定位为 AI 代码审查平台，如今已扩展至覆盖软件开发生命周期（SDLC）的 代码质量与治理 领域。Nnenna 拥有全栈软件工程师背景，致力于探索 结构化的 AI 编码流程。她提供了一个可分叉的 GitHub 仓库（qodo-quality-workshop-signal-pay），建议观众通过让 AI 分析该仓库的结构来获取优化自身工作流的灵感。她强调，随着团队对 AI 编码工具的广泛采用（如 Claude Code、Codeex 等），代码质量可能在规划、设计、开发、审查及部署的任何环节出现断裂。因此，必须通过“过度引导”AI 代理来确保最终代码达到人类开发者敢于署名并推向生产环境的质量标准。

质量标准的定义与上下文操作化

构建高质量 AI 编码工作流的第一步是 明确代码质量的定义。如果是在团队环境中，这一标准必须被正式化并存储在特定位置（如本地仓库或上下文管理层），以便 AI 能够提取这些规则。Nnenna 提出 操作化上下文（Operationalize Context） 的概念，即通过仓库中的规则文件、技能库等资源，将质量标准分发到 CLI、IDE 和 CI/CD 工作流中。她指出：“我们需要尽早且频繁地验证质量，理想情况下，我们在每个阶段要求代理检查的标准应该是相同的。” 这种一致性确保了从规划到代码生成的全过程都遵循同一套质量基准，从而降低后期修复成本。

实战演示：Signal Pay API 的质量门禁流程

为了具体说明这一过程，Nnenna 使用了一个名为 signal-pay 的自包含 FastAPI 支付 API 项目作为演示案例。该流程分为几个关键阶段：首先，读取仓库规则以确定与当前编码变更相关的特定标准；其次，利用 TDD（测试驱动开发）和 BDD（行为驱动开发） 技能编写适当的测试用例；接着，指导编码代理实现代码变更。在本地阶段，运行 Linters 和静态分析 等确定性检查工具，结合 AI 能力进行初步筛选。随后，代码通过 Pull Request（PR）提交至 GitHub，由 Qodo AI 进行审查。最后，针对代理发现的任何问题，利用 Agent Skill（智能体技能） 自动解决修复。Nnenna 强调：“我们要利用规则、技能和各种资源来规划编码变更，并确保在 PR 审查阶段也能直接应用这些标准。”

自动化修复与闭环验证

在演示的最后阶段，重点在于 问题的自动解决机制。当 Qodo AI 在 GitHub PR 中识别出代码质量问题或潜在缺陷后，系统并非仅停留在报告层面，而是通过预定义的 Agent Skill 自动应用修复方案。这一环节体现了结构化工作流的核心价值：将人工审查与自动化代理能力相结合，形成从代码生成、本地静态检查到远程 PR 智能审查的完整闭环。通过这种方式，开发者可以将重复性的质量验证任务交给 AI，而专注于更高层级的架构设计和业务逻辑确认。Nnenna 总结道：“我们不需要手动处理所有这些步骤，而是通过工具链将上下文和操作自动化。” 这种模式不仅提高了开发效率，更确保了代码库在快速迭代中保持高质量和一致性。

仓库结构与本地环境初始化

在开始编码之前，必须首先理解并配置项目的基础仓库结构。该示例项目包含一个 agents.md 文件、隐藏的规划目录（hidden plan）、规则集（rules）、技能库（skills）以及文档。核心代码位于 API 部分，同时配备了测试套件和用于静态分析的 Serc Grep工具。此外，CI 工作流中的验证流程也是质量门禁体系的重要组成部分。为了启动应用，开发者需要克隆仓库并执行 make setup 指令进行本地环境搭建。一旦配置完成，通过运行 make run 即可启动应用。

"Okay, once we've done that, it should be make run... All right now it is running and locally it should available."

启动后，开发者将看到一个简单的支付 API 界面。虽然这并非演示的核心重点，但它证明了本地环境已成功运行。如果开发者希望进行动手实践或仅作为观察员，都可以基于此基础继续。关键在于确保本地仓库能够平滑运行任何所需的更改，必要时可请求 AI 助手协助调整配置。

Qodo AI 集成与上下文摄取

接下来，演示引入了 Qodo (Kodto) 作为核心工具。与仅在拉取请求（PR）中运行不同，这里强调在账户层面设置 Qodo，以便其能够摄取仓库中已有的技能和规则。这一过程至关重要，因为它允许 AI 在代码审查阶段以及规划阶段将上下文应用于编码代理。开发者需要访问 app.codto.ai，使用 GitHub 邮箱登录并连接 GitHub Cloud。

"What's great about Kodto here is that we're not just going to run this in a pull request. We want to set up our account with Kodto so it can actually ingest the skills that are in this repo already and to ingest the rules."

连接时，建议仅关联分叉的仓库而非所有仓库。随后，开发者需在 Qodo 门户生成 API Key，并将其保存至本地的 codto.config.json 文件中。虽然可以使用命令如 npx skills add-to-skills 添加技能，但仓库内已预置了相关资源。这种集成方式确保了上下文管理的一致性，即使不使用 Qodo，团队也应将规则和技能存储在独立于本地仓库的集中位置（如 Unblocked），以便随时调用。

质量门禁的具体层级与标准

演示详细阐述了五个关键的质量门禁（Quality Gates）。首先是规则门禁，仓库中包含针对支付 API 的特定规则。AI 代理的任务是判断在实现代码更改时，哪些规则适用并严格遵守它们。其次是规划与测试驱动开发（TDD）门禁。仓库提供了高层计划模板和执行聚焦的详细计划。研究表明，规划阶段越详细、结构化和一致，AI 代理在后续执行中 adherence（遵循度）越高，且能更好地自我纠正遗漏的关键点。该模板明确了预期行为和实施所需的技能。

第三个门禁是本地验证门禁。这里结合了确定性工具（如 Ruff、Pytest、Bandit、Pi Test 和 Conventional Commits）与 AI。开发者坚信将确定性工具与 AI 结合是最佳实践。第四个门禁涉及 PR 审查与修复闭环。当打开 PR 时，Qodo 的发现结果会被检查，修复方案和延期处理需记录在案。最后，开发者必须重新运行验证命令以完成代码审查循环，而不是仅仅满足于本地运行的通过。

前置条件与任务执行示例

为了顺利实施上述流程，系统需要一系列前置依赖环境。这包括 Git、GitHub 账户、GitHub CLI、Python（配合 UV）、Node.js/npm，以及首选的编码代理工具（如 CodeEx 或 Cloud Code）。此外，必须拥有 Qodo 账户以完成 API Key 的配置。这些技术栈确保了从代码生成到静态分析再到 CI/CD 验证的全链路畅通。

"I am a huge believer in combining deterministic tools with AI."

本次演示的具体任务是添加一个小型支付工作流安全流程。开发者可以选择实现退款工作或捕获重试处理逻辑。这是一个有意设计的微小更改（Intentionally small change），旨在展示在严格的质量门禁约束下，AI 如何精确地执行特定任务。通过这一案例，观众可以观察到从规则匹配、详细规划到本地验证及最终 PR 审查的完整闭环过程，从而理解如何在 Agentic Coding 中构建可靠的质量保障体系。

支付 API 场景下的代理配置与技能验证

在构建基于 AI 的编码工作流时，敏感业务逻辑（如支付 API）是验证代码质量门禁的理想场景。由于 AI 生成的退款或捕获重试处理逻辑往往看似合理却隐含风险，因此需要严谨的配置流程。演示者首先通过复制粘贴提示词来初始化项目环境，要求代理识别本地规则 ID 并加载相关上下文。这一过程的核心在于验证依赖健康度与技能安装状态。当代理检测到本地工作坊（workshop）的技能尚未完全安装时，它会主动触发 installer verify codto skills 命令。该命令仅复制已提交的本地技能文件夹到代理的技能目录中，确保所有本地规则被正确拉取并生效。这种自动化的环境自检机制避免了因配置缺失导致的执行错误，为后续的任务实施奠定了坚实基础。

"I'm just copy and pasting, getting my agent really ready to start working on this project, giving it that context that it needs."

计划模式下的约束分析与任务拆解

进入规划模式（Plan Mode）后，代理不再直接编写代码，而是利用本地工作坊的规划技能将 README 中的任务转化为高层实施计划和构建会话执行计划。这一阶段的关键在于确定约束条件与技能路由。代理需要阅读 agents.mmd 和规则文件，识别出适用于当前支付工作流的特定本地规则。例如，在演示退款工作流程时，代理会明确指出将使用哪些技能来指导实施，并定义后续的测试驱动开发（TDD）提示词链。这种模式强制代理在动手前进行深度思考，仅读取和检查文件而不写入任何代码或计划文件。通过这种方式，开发者可以确保代理对业务逻辑、现有约束以及预期行为有清晰的理解，从而避免盲目编码带来的技术债务。

"It is taking a while to do this... All of the local skills are now pulled down. And here are the selected repo local rules for this payment workflow task."

结构化模板：从行为变更到质量门禁的完整映射

为了实现可维护且高质量的 AI 编码输出，结构化模板（Structured Templates）至关重要。演示者展示了规划模板的核心要素：它必须回答行为变更内容、适用规则、指导技能、验证测试以及通过审查前的质量门禁（Quality Gates）。模板通常包含摘要、问题陈述、约束条件、技能路由、范围与行为场景验证，以及失败恢复规则。这种结构化的规划方式使得代理能够像传统团队开发一样组织代码、使用约定式提交（conventional commits）并生成有序的 Pull Request。技能路由功能尤其关键，它允许代理在实施阶段自动按顺序调用不同技能或循环执行目标任务，无需人工干预。通过这种高度结构化的规划与实施分离机制，AI 编码工作流得以在保持灵活性的同时，建立起类似传统软件工程的质量保障体系。

"I truly believe that this is a really important artifact to be able to take with you... A plan should answer what behavior are we changing, which rules apply... and what kind of quality gates should pass before we review."

建立标准化的执行模板与上下文文档

在构建 Agentic Coding（智能体编码）工作流时，建立标准化的执行模板是确保一致性的基石。演讲者指出，最有帮助的做法是为智能体提供一份详尽的“起始状态”文档。这份文档必须明确当前所在的代码分支、现有的本地验证流程，以及用于判定代码通过或失败的具体命令。此外，还需包含对 Linter（代码检查工具）的期望以及具体的实现技能交接和执行步骤。

"I want the agent knows every single step in this process of making the code change and I want it to determine what the test plan is as well."

这种结构化的方法要求智能体不仅知道每一步操作，还要自主确定测试计划。文档中还需包含“完成定义”（Definition of Done）和备注，确保所有命令已运行、变更点已被识别且任何中途的决策调整都有据可查。例如，在一个退款工作流的实施计划中，包含了摘要、关联的仓库规则、高层级实施方案以及构建会话执行计划和假设条件。这种全链路的上下文管理让智能体能够在清晰的框架内自主行动，减少歧义。

利用特定技能库提升代码质量

为了实现跨 SDLC（软件开发生命周期）的一致性，演讲者强调运营化上下文、规划、代码生成和代码审查的重要性。她使用了一套组合的“智能体技能”（Agent Skills），这些技能可根据仓库、编程语言和框架进行调整。在 Python 生态中，她使用了如 Pydantic、Pyright（用于类型检查）以及 Python typing contracts 等技能。

特别值得一提的是来自开发者 Aaron Francis 的审计类技能，包括边界审计、漂移检测、名称规范、抽象层检查、死代码识别以及错误处理。这些技能在实施阶段被证明能极大地简化和提升代码质量。虽然部分技能可能未公开，但鼓励团队自行构建或利用现有资源。核心逻辑在于尽早并频繁地执行质量检查。通过从上下文管理层拉取规则，智能体可以确定哪些规则与当前任务相关，从而在代码提交给其他开发者之前解决细微问题。这种前置的质量控制策略能有效缓解后期出现问题的风险。

本地与 CI/CD 中的自动化代码审查实践

在实施层面，演讲者主张无论使用何种工具（如 CodeGeeX、Cloud Code 或 Qodo），始终运行本地代码审查。这是因为许多小改动可以在早期被修正，避免让其他开发者看到不完美的代码。随后，在 CI（持续集成）或 Git 提供商中运行自动化代码审查是默认且必要的步骤。为了验证这一工作流的有效性，演讲者对一个开源工具进行了大规模测试。

"The proof was in the amount of lines that I changed... Only one bug was uncovered in over 900 lines of code using Qodo for that like automated code review and it was one reliability bug."

在一个包含超过 900 行代码的大型 Pull Request（PR）中，通过 Qodo 的自动化审查仅发现了一个可靠性 bug。这一结果证明了该工作流的价值：它并非为了制造障碍，而是为了确保在大规模变更中保持极高的代码稳定性。这种基于数据的验证表明，将质量门禁嵌入到智能体工作流中是可行且高效的。

规则引擎的分类、分级与仓库级作用域

在 Qodo Portal（门户）中，规则被系统化地管理。这些规则通过上下文推断、摄入并保存，分为可访问性（Accessibility）、正确性（Correctness）、可维护性（Maintainability）、架构（Architecture）和安全性（Security）等类别。更重要的是，规则按严重程度分级。并非所有规则都同等重要：有些强到足以阻止合并（Block Merge），而另一些仅是最佳实践，即使通过也不会造成严重危害。

"There are some rules that are strong enough to where you want to block a merge. There are others that it's good practice, but this isn't something detrimental if were to get through."

规则的作用域可以细化到组织级别或仓库级别。演讲者指出，虽然目前主要通过仪表板进行过滤，但将规则限定在特定仓库内是可行的设计方向。这种粒度控制允许团队根据具体用例决定哪些通用技能或规则最相关。例如，针对 Python 仓库的规则集可以独立于其他语言仓库进行配置。这种分层且可作用域化的规则体系，使得质量门禁既能保持通用标准，又能适应不同项目的特定需求。

基于代码库分析自动生成质量规则

在构建 Agentic Coding（智能体编码）工作流时，Qodo AI 能够自动分析现有代码库以发现潜在的质量规则。当用户将内容导入 Portal（门户）时，系统并非凭空捏造规范，而是通过深入阅读和分析实际代码库来提取惯例。这些规则往往不是开发者显式写入的，而是 Qodo 在分析整个代码库后观察到的既定惯例。系统不会自动创建并强制执行这些规则，而是将其作为建议呈现给用户进行审查。生成的内容包含良好代码示例与不良代码示例的对比，旨在向 AI 智能体清晰界定什么是“好”与“坏”。用户可以编辑这些示例，定义规则的类别（Category）和警告级别（Warning Levels），在确认无误后接受并激活该规则，使其自动应用于后续的开发流程中。

智能体 RAG 机制与规则筛选逻辑

Qodo Get Rule Skill（获取规则技能）的工作方式类似于一个智能的 RAG（检索增强生成）过程。它通过连接 Qodo 平台的后端，从本地仓库规则中拉取数据。由于并非所有关联到不同工作流路径的规则都适用于当前场景，系统会自动过滤掉无关规则。这种机制确保了智能体在处理特定任务时，只关注最相关的上下文和规范。正如演讲者所述：“It's sort of like this agentic uh rag process of determining um what which ones are actually irrelevant and it filters it down”。这种动态筛选能力解决了规则过载的问题，使得质量门禁（Quality Gates）能够精准地作用于当前的代码变更，而非盲目应用所有组织级规范。

实施质量门禁后的 PR 审查流程演示

在实施了“添加退款工作流并加入质量门禁”的计划后，Qodo 自动生成了 Pull Request（PR）摘要。演示者将草稿 PR 转为正式状态，目的是让 Qodo 在不合并的情况下对代码进行审查。如果 Qodo 已连接到仓库，系统会自动弹出分析界面。经过几分钟的分析，Qodo 会列出潜在问题，并触发智能体技能（Agent Skill）自动解决这些问题。此外，虽然 Qodo 已根据仓库设置自动执行了验证提示（Verification Prompt）以确保变更通过，但最佳实践仍建议在进行本地审查后运行独立的验证步骤。生成的 PR 摘要包含了详细的描述和变更图，清晰展示了 API、内存存储及支付退款端点等组件的变化。

代码审查中的规则冲突与阻塞机制

在具体的代码审查案例中，Qodo Portal 识别出与该次变更相关的特定规则。例如，组织规定所有 Python 函数必须包含 Docstring（文档字符串），Qodo 将此标记为“可维护性”问题。由于该规则被工程团队设定为高严重级别（High Severity），因此状态显示为“需要操作”（Action Required）。这种严重级别的设定是灵活的：规则不一定是阻塞性的，但必须由开发者处理。演讲者指出：“you can decide based on the level of severity of the rule this uh code this uh branch or PR will be will be blocked”。这意味着，当检测到高严重性问题时，合并操作会被阻止，直到问题修复并重新验证通过。尽管目前完全确定性的阻塞机制仍在推进中（特别是在受监管行业的需求推动下），但这一功能对于建立严格的质量门禁至关重要。

技能价值评估与第三方工具集成

针对工程师关于“如何证明特定智能体技能的实用性”的疑问，演讲者指出 Qodo 本身主要侧重于摄取技能而非评估其质量。为了量化技能的效用或检测潜在的安全风险，建议集成第三方工具 TeSSL (Tessle)。TeSSL 是一家专注于技能评估（Skills Eval）的公司，能够帮助团队确定某项技能是否如预期般有效，或是否存在安全隐患。这种外部评估机制填补了 Qodo 在技能价值度量方面的空白，使得团队能够基于数据而非直觉来优化智能体工作流中的技能配置。

自动化验证与持久化存储风险识别

在代码修复后的验证环节，最佳实践是始终运行验证步骤以确保持久性。演示中展示了Qodo AI识别出的具体问题：退款项的强度（potency）存储在内存字典中，而非持久化存储。这导致退款支付结果无法在系统重启后保留。AI不仅指出了代码片段，还提供了相关的规则证据和文件路径。关键洞察在于区分临时内存存储与持久化数据层，这是自动化代理需要重点监控的工程标准。通过这种方式，开发者可以明确知道哪些代码段存在潜在的数据丢失风险。

"Refund payment uses the process local uh dictionary to store and replay fund results, which is not durable persistent storage."

PR Resolver 的自动修复与审查流程

Qodo AI提供了两种处理模式：手动逐个审查或使用PR Resolver自动修复。在演示中，演讲者选择了“Autofix All”模式来处理6个已识别的问题（1个Bug，3条规则违规，2项技能洞察）。该工具会自动拉取从严重到高危的所有问题列表。自动修复过程包含验证步骤，如果提交结构不正确会自动阻止。完成后，代理会将更改摘要发布回PR，并标记已解决的问题。这种自动化不仅提高了效率，还确保了修复后的代码符合预定义的质量门控标准。

"I'm going to autofix all six codto issues... it'll take that next step further by actually posting back to the PR with a summary of all the changes that were fixed."

本地工作流与开源替代方案探讨

针对代码审查的本地化需求，Qodo AI即将推出COD Review Local Workflow，直接连接后端代理能力。其核心机制是克隆仓库以理解变更的更广泛上下文。对于寻求开源解决方案的团队，推荐关注Packmind，它提供了类似Qodo的规则治理层。此外，针对安全敏感行业（如银行、Nvidia团队），Qodo支持私有化部署和On-prem选项。演讲者建议开发者利用现有仓库作为模板，实践如何在本地工作流中嵌入验证步骤和工程标准。通过引入规则和技能存储层，团队可以跨仓库一致地治理AI代码生成。

"There are some uh open-source tools that have similar context management layers to what Kodto does... Packmind.com."

结论

本次演示证实，将规则、技能与确定性工具嵌入 Agentic Coding 工作流，能构建可靠的质量门禁体系。通过结构化规划与自动化修复闭环，Qodo AI 在超900行代码的PR中仅发现1个可靠性Bug，验证了该流程在大规模变更中的稳定性。其核心优势在于利用智能RAG机制精准筛选规则，并实现从本地静态检查到PR自动修复的全链路自动化。

然而，完全确定性的阻塞机制仍在推进中。团队需结合TeSSL等第三方工具评估技能价值，并针对敏感场景选择私有化部署。该方案适用于希望将AI编码纳入标准化治理、降低人工审查成本且具备一定工程配置能力的团队，通过前置质量控制有效缓解技术债务。