code-production-process

代码生产流程

概述

这项技能实现了一个由六个阶段组成的质量门禁流水线，所有非简单代码实现任务在宣告完成之前都必须通过该流水线。设置这条流水线，是因为仓库所有者无法直观评估代码质量，因此，所有质量保证都必须由 Agent 流水线中的自动化门禁来执行，而不能依赖事后人工审查。每个阶段都会产出具体成果，并且必须通过指定门禁，才能开始下一阶段。标准流程中不得跳过任何阶段。Critic Agent 在完全隔离上下文的环境中工作，以防受到实现者自身表述方式的锚定偏差。刻意采用对抗式审查，可以发现协作式审查容易遗漏的问题。

触发条件

满足以下任一条件时，就会加载此技能：

显式触发（派发前）：

• PM 即将派发工程师 Agent 处理预计会产出超过 50 行源代码的任务
• PM 即将派发工程师 Agent 处理会涉及超过 1 个源文件的任务
• 任务描述包含实现类动词：“implement”“write”“build”“create”“refactor”“add feature”“fix bug in [module]”

派发后检测：

• 工程师 Agent 返回后，git diff --stat 显示源文件（包含逻辑的 .py、.ts、.js、.go、.rs、.java、.rb、.sh）发生变更，无论任务声明的范围如何
• 工程师 Agent 在 src/、lib/、app/、services/、api/ 目录下创建了新文件

明确排除——以下情况不要触发此流水线：

• 文档编辑（仅修改 .md、.rst、.txt、.html 内容）
• 提交说明、PR 描述、变更日志
• 仅配置变更（不含代码逻辑的 *.yaml、*.toml、*.json、*.env）
• 已确认范围少于 5 行的单行修复
• 未修改代码的依赖版本更新

**拿不准时：**倾向于触发此流水线。误报只会多派发一次 Critic。漏报则可能发布有缺陷或不安全的代码。

六阶段流水线

每个阶段都指定了 Agent、必需的输出成果和门禁条件。必须满足门禁条件才能继续。门禁未通过时，应退回当前阶段，而不是回到第 1 阶段；但如果失败表明对需求存在根本性误解，则应回到第 1 阶段。

阶段 1：调研

Agent： research

工具： mcp__vector-indexer-mcp__search_hybrid、mcp__knowledge__kb_search、mcp__knowledge__search_local

Agent 的工作：

• 搜索现有代码库，查找可复用或扩展的相似实现
• 确定实现必须遵循的现有抽象、模式和惯例
• 查找涵盖架构决策、数据模型、API 契约的相关知识库条目
• 列出外部依赖项及其在代码库中已确立的使用模式

必需的输出成果： 一份书面规范文档（Markdown），涵盖：

• 已有内容（注明文件路径和函数名称）
• 必须新建的内容
• 实现必须遵循的现有模式
• 新代码必须满足的输入／输出契约
• 现有用法中已知的边缘情况

门禁： 规范文档必须存在，并至少列出一项现有代码库参考。调研 Agent 不得产出实现代码。如果没有相关的现有代码，输出中必须明确写出“未找到先前实现”——这是有效的调研结果，不是失败。

参见： references/stage-research.md，了解提示词模板和搜索策略。

---

阶段 2：架构设计

Agent： python-engineer（处于设计模式——不编写实现代码）

已加载的技能： software-patterns

Agent 的工作：

• 阅读阶段 1 的规范文档
• 设计公共接口：类签名、函数签名、数据模型和类型注解
• 在需要多态的地方指定抽象基类（ABC）或 Protocol 类
• 记录每个公共方法的不变量和前置条件
• 说明将使用哪些外部依赖，以及如何使用

必需的输出产物： 一份接口规范文档，包含：

• 所有公共类／函数的完整类型注解签名
• ABC 或 Protocol 定义（不包含方法体——仅使用 ... 或 pass）
• 数据模型架构（Pydantic 模型、dataclass、TypedDict——不包含逻辑）
• 将引发的错误类型及其层级
• 一段说明实现不会做什么的文字

关卡： 接口文档已存在。实现代码为零（没有包含逻辑的函数体、算法步骤或 I/O 调用）。架构师负责制定契约；工程师负责填充实现。

重要提示： 可选地在此阶段调度 code-critic Agent，在开始实现前审查接口设计是否连贯。这是第 2 阶段的设计评审环节。如果进行调度，评审者仅接收接口文档作为输入——此时尚无代码。

参见： references/stage-architect.md，了解接口规范模板。

---

阶段 3：实现

Agent： python-engineer

已加载的技能： software-patterns、asyncio（需要异步代码时）、pytest

Agent 的工作：

• 严格按照阶段 2 定义的接口进行实现（不得擅自扩大范围——如需修改接口，应通知 PM）
• 使用 pytest 编写单元测试，覆盖：
  • 每个公共函数的正常路径
  • 每个有文档说明的错误条件
  • 每个函数至少一个边界情况
• 对新代码运行 mypy --strict，并在宣布完成前解决所有类型错误
• 在返回前本地运行 pytest 并确认所有测试均通过

必需的输出产物：

• 实现阶段 2 接口的源文件
• 包含 pytest 测试的测试文件
• 显示零错误的 mypy --strict 输出
• 显示所有测试均通过的 pytest 输出

关卡： 返回 PM 前，工程师必须提供无错误／失败的 mypy 和 pytest 输出。如果工程师无法提供这些输出，就表示尚未完成——PM 必须重新调度，而不能继续进入阶段 3.5。

参见： references/stage-implement.md，了解实现标准和自检清单。

---

阶段 3.5：测试必须通过关卡

Agent： PM（不调度 Agent——PM 直接评估阶段 3 的输出）

PM 的工作：

• 检查阶段 3 的 pytest 输出产物
• 如果 pytest 出现任何失败：立即退回阶段 3 的工程师。不得调度 code-critic。不得尝试推进流程。测试失败意味着实现尚未完成。
• 如果 pytest 全部通过（失败数为零）：继续进入阶段 4

此关卡不可协商。 对测试失败的代码调度 code-critic，只会浪费令牌来查找可能由损坏状态造成的问题。评审者审查的是可正常工作的代码，而不是正在修复中的代码。

退回给工程师的失败消息（模板）：

Tests failed. Return to Stage 3. Fix the following failures before requesting critic review:

[paste pytest output here]

When tests pass green, provide updated implementation + passing pytest output.

参见： references/stage-tests.md，了解测试质量要求和覆盖率标准。

---

阶段 4：评审员审查

Agent： code-critic

已加载技能： code-review-standards、code-production-process

必须隔离上下文。 完整要求请参阅下方的“评审员隔离规则”部分。未能隔离评审员上下文属于流程违规。

评审员 Agent 的职责：

• 根据阶段 2 的接口规范审查实现
• 应用带严重性标签的 code-review-standards 检查清单（CRITICAL/HIGH/MEDIUM/LOW）
• 生成结构化问题表格，并为每项问题标注文件和行号
• 返回顶层判定：APPROVE、WARN 或 BLOCK

必需的输出产物：

• 在回复顶部注明判定结果（APPROVE / WARN / BLOCK）
• 问题表格（APPROVE 时可以为空），列包括：Severity | File | Line | Issue | Fix
• 解释判定结果的摘要段落

关卡： 评审员返回判定结果。PM 根据下方的判定协议采取行动。

参见： references/stage-critic.md，了解调度模板和隔离检查清单。

---

阶段 5：安全性

Agent： security

范围： OWASP Top 10、机密信息/凭据泄露、注入漏洞（SQL、shell、模板）、身份验证和授权绕过、任意代码执行路径、不安全反序列化、密码学弱点。

该 Agent 的职责：

• 审查阶段 3 的实现，检查上述范围内的安全漏洞
• 不会重新审查代码风格或结构问题（这属于评审员的职责范围）
• 生成问题列表，列出严重性（CRITICAL / HIGH / MEDIUM / LOW）和修复措施

关卡： 严重性为 CRITICAL 或 HIGH 的安全问题必须为零。MEDIUM 问题会记录并归档。LOW 问题会注明。如果存在 CRITICAL 或 HIGH 安全问题，PM 会暂停并告知用户——处理方式与评审员给出 BLOCK 相同。

参见： references/stage-security.md，了解安全审查范围和 OWASP 对应关系。

---

评审员隔离规则

评审员 Agent 判定的独立性取决于其接收的上下文。锚定偏差——即审查者无意识地接受代码作者对代码功能的描述——是多 Agent 系统中代码审查的主要失效模式。

PM 构造评审员调度提示词时，必须只包含：

1. 阶段 1 规范文档（提出的需求）
2. 阶段 2 接口规范（设计的内容）
3. 阶段 3 实现文件（构建的内容）
4. 阶段 3 pytest 输出（测试结果）

PM 构造评审员调度提示词时，不得包含：

• 工程师的提交说明
• 工程师在实现回复中陈述的理由或设计说明
• PM 对工程师工作内容撰写的任何摘要
• “工程师解释说……”或“根据实现者的说法……”之类的表述

如果工程师的实现回复中将内联说明文字与代码混在一起，PM 必须为评审员调度提取代码和测试输出，并删除实现者的叙述。

制定此规则是因为，工程师写下“我选择这种方案，是因为另一种方案会造成性能问题”时，会微妙地提前反驳评审员提出性能问题的可能性。评审员必须在不了解背景的情况下直接审查代码。

参见： references/critic-isolation.md，了解提示词构造模板。

Verdict 协议

PM 的行为完全由 critic 的顶层 verdict 决定。PM MUST NOT 使用判断来覆盖或弱化 verdict 协议。

APPROVE（零条 CRITICAL 发现，零条 HIGH 发现）：

• 进入 Stage 5（Security）
• 工程师无需采取其他行动
• 发现表（如果非空，且仅包含 MEDIUM/LOW）作为“供日后参考的备注”传递给 Documentation Agent 的交接信息

WARN（零条 CRITICAL 发现，一条或多条 HIGH 发现）：

• 进入 Stage 5（Security）——不要停止流水线
• PM MUST 将完整的 critic 发现表附加到发送给 Documentation Agent 的交接信息中
• PM MUST 在备注（KB 条目或待办评论）中记录这些发现，以便跟踪
• PM MUST NOT 默默丢弃 HIGH 发现——必须在某处明确呈现这些发现

BLOCK（存在任何 CRITICAL 发现）：

• PM 立即停止流水线
• PM 将 critic 发现表原样呈现给用户
• PM 表示：“Critic 已阻止此实现。必须先解决以下 CRITICAL 问题，流水线才能继续。请确认您的处理方向。”
• PM 等待用户明确指示：修复并重试、提供理由后覆盖，或放弃
• PM MUST NOT 在没有用户输入的情况下自动重新委派给工程师
• 当用户指示修复并重试时：返回 Stage 3（Implement），并将 critic 发现表作为额外输入。Stage 2 的架构师接口仍具有权威性，除非 CRITICAL 发现揭示了根本性的接口设计缺陷；在这种情况下，PM 返回 Stage 2。

跳过规则（Hotfix 路径）

以下规则定义了何时可以跳过阶段。无论采用哪条路径，Stage 3 到 Stage 5 绝不可跳过。

**标准路径：**全部 6 个阶段。所有新功能、超过 100 行的重构、任何对身份验证／授权代码的更改，以及任何对数据模型的更改，都必须采用此路径。

**Hotfix 路径：**仅当以下条件全部满足时，才可跳过 Stage 1 和 Stage 2：

• 已确认待修复的错误存在于生产环境中（不是假设性问题或仅在本地出现的故障）
• 已验证修复范围不超过 2 个文件，且新增代码总量不超过 20 行
• 修复不涉及身份验证、授权、密码学或数据序列化
• PM 在会话日志中明确注明“hotfix 路径”

即使采用 hotfix 路径，Stage 3（Implement + Tests）、Stage 3.5（Tests-Must-Pass Gate）、Stage 4（Critic）和 Stage 5（Security）仍为必经阶段，不可跳过。

**仅文档路径：**如果确认所有更改都仅涉及文档、配置值或依赖项版本升级，且没有逻辑更改，则跳过全部 6 个阶段。PM 应通过 git diff --stat 确认未修改任何源文件。

参见：references/skip-rules.md，了解跳过规则的决策树和示例。

失败循环协议

当阶段门禁未通过时，会以结构化格式将发现返回给负责的 Agent。PM 不尝试解读或修补该发现，而是原样传递。

BLOCK 后返回给工程师的格式：

PIPELINE GATE FAILURE — Return to Stage [N]

Critic verdict: BLOCK
Findings (CRITICAL):

| Severity | File | Line | Issue | Required Fix |
|----------|------|------|-------|--------------|
[paste finding table verbatim]

Instructions:
- Fix ALL CRITICAL items above
- Re-run pytest (must pass green)
- Re-run mypy --strict (must pass)
- Return updated implementation with fresh test output

Do NOT return until all CRITICAL findings are resolved and tests pass.

WARN 后返回给工程师的格式（如果用户要求修复）：

PIPELINE GATE — WARN findings for review

Critic verdict: WARN
Pipeline proceeded, but the following HIGH findings were logged:

| Severity | File | Line | Issue | Recommended Fix |
|----------|------|------|-------|-----------------|
[paste finding table]

These were noted in the documentation handoff. If you choose to address them in this session,
re-run tests and confirm they still pass. No re-critic required for WARN resolutions.

Token 效率说明

Stage 1 和 Stage 2 按设计保持轻量。Research 和 Architect Agent 主要处理文本文档（规范、KB 条目、接口文件），而不是大型代码库。大部分 token 消耗发生在 Stage 3 至 Stage 5，这些阶段中的实现、测试、critic 审查和安全审查都会处理完整的代码库上下文。先派遣 Research 和 Architect，可确保 Stage 3（Implement）收到清晰的规范，无需反复澄清，从而减少重新派遣工程师的次数——这是无结构实现工作流中 token 浪费的主要来源。