Back to Details

builder-review-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Builder Review Loop

构建者评审循环

Use a two-agent workflow:
  • The builder agent implements the requested slice.
  • The reviewer agent reads the real files, not just the summary, and helps the user decide whether to fix, defer, revert, or proceed.
  • The human owns scope and final decisions.
采用双Agent工作流：
  • 构建者Agent实现需求的指定模块。
  • 评审者Agent读取实际文件（而非仅依赖总结），协助用户决定是修复、延期、回退还是继续推进。
  • 由人类掌控范围与最终决策。

Core Rules

核心规则

  • Treat the builder summary as a claim, not proof. Read the touched files.
  • Findings come first. Prioritize bugs, regressions, scope drift, and contract breaks over style.
  • Separate 
    must fix now
    from 
    can defer
    .
  • Keep prompts narrow: one bug fix or one feature slice at a time.
  • Do not silently reopen product or architecture decisions that the user already made.
  • Prefer a fresh conversation when context is bloated and the next agent can reconstruct state from the code.
  • 将构建者的总结视为声明而非证据，务必查看被修改的文件。
  • 先列出发现的问题。优先处理漏洞、回归问题、范围偏离与合约破坏，而非代码风格问题。
  • 区分「必须立即修复」和「可延期处理」的问题。
  • 保持prompt范围狭窄：一次仅处理一个漏洞修复或一个功能模块。
  • 不要擅自重新开启用户已经确定的产品或架构决策。
  • 当上下文过于臃肿，且下一个Agent可从代码中重构状态时，建议开启新的对话。

Review Workflow

评审工作流

  1. Read the builder summary and exact files changed.
  2. Read the touched files plus the nearest neighboring files needed to verify the claims.
  3. Classify findings: 
    • High
      : wrong behavior, data loss, broken contract, serious regression.
    • Medium
      : incomplete slice, UX mismatch, race condition, unsafe assumption.
    • Low
      : cleanup, naming, minor debt, acceptable temporary duplication.
  4. Answer the user’s direct questions plainly:
    • Is the change good enough to keep?
    • Fix now or move on?
    • Is something missing?
    • Was something included that should not be here?
    • Fresh conversation or existing one?
  5. If there are no blocking findings, say so explicitly and name the next slice.
  1. 阅读构建者的总结以及被修改的具体文件。
  2. 阅读被修改的文件，以及验证声明所需的相邻文件。
  3. 对发现的问题进行分类： 
    • 高优先级
      ：行为错误、数据丢失、合约破坏、严重回归问题。
    • 中优先级
      ：模块未完成、UX不匹配、竞态条件、不安全假设。
    • 低优先级
      ：代码清理、命名问题、轻微技术债务、可接受的临时重复代码。
  4. 直接明了地回答用户的问题：
    • 该变更是否足够好，可以保留？
    • 立即修复还是继续推进？
    • 是否有遗漏的内容？
    • 是否包含了不应存在的内容？
    • 开启新对话还是沿用现有对话？
  5. 如果没有阻塞性问题，需明确说明，并指明下一个要处理的模块。

Review Rubric

评审准则

Check these in order:
  • Does the code actually do what the summary claims?
  • Did the builder stay within the requested scope?
  • Does it match the locked contracts, master plan, and latest user decisions?
  • Is there hidden hardcoding or architecture drift?
  • Are UI truth and runtime truth reading from the same source of truth?
  • Can the change lose, overwrite, or fabricate user state?
  • Is the remaining debt acceptable for the current phase?
按以下顺序检查：
  • 代码是否真正实现了总结中声称的功能？
  • 构建者是否在需求指定的范围内工作？
  • 代码是否符合已锁定的合约、总体规划以及用户最新的决策？
  • 是否存在隐藏的硬编码或架构偏离？
  • UI数据与运行时数据是否来自同一可信数据源？
  • 该变更是否可能导致用户状态丢失、覆盖或伪造？
  • 当前阶段剩余的技术债务是否可接受？

Decision Rules

决策规则

  • Fix now
    if the issue causes incorrect behavior, lost state, misleading UX, invalid persistence, or contract breakage.
  • Defer
    if the issue is real but isolated, understood, and does not poison the next slice.
  • Revert
    only if the direction is wrong, scope exploded, or the change makes the architecture harder to recover.
  • Proceed
    when the slice is coherent and only minor follow-up debt remains.
  • 立即修复
    ：若问题导致行为错误、状态丢失、UX误导、持久化无效或合约破坏。
  • 延期处理
    ：若问题真实存在但影响范围孤立、已被理解且不会影响下一个模块。
  • 回退
    ：仅当方向错误、范围失控或变更导致架构难以恢复时才执行。
  • 继续推进
    ：当模块逻辑连贯，仅剩余轻微后续技术债务时。

Prompt Writing Rules

prompt撰写规则

Every next-step prompt should include:
  • The current goal in one sentence
  • The context about the feature or bugfix
  • Exact files to read first
  • The specific bug or missing behavior
  • Clear constraints on what not to touch
  • Acceptance criteria
  • Required verification
  • Expected final response shape
Do not write vague prompts like:
  • "make it cleaner"
  • "make it more dynamic"
  • "improve the architecture"
每个下一步的prompt应包含：
  • 一句话概括当前目标
  • 关于功能或漏洞修复的上下文
  • 需优先阅读的具体文件
  • 具体的漏洞或缺失的行为
  • 明确的禁止修改约束
  • 验收标准
  • 必要的验证步骤
  • 预期的最终响应格式
避免撰写模糊的prompt，例如：
  • "make it cleaner"
  • "make it more dynamic"
  • "improve the architecture"

Handoff Rule

上下文传递规则

Use a fresh conversation when:
  • The context window is crowded
  • A new feature slice is starting
  • Several review rounds have already happened
  • The next agent can recover truth from the code and current files
Reuse the same conversation when:
  • The follow-up is tiny and local
  • The same bug is being fixed
  • The recent reasoning still matters more than the code state
在以下情况开启新对话：
  • 上下文窗口过于拥挤
  • 新功能模块即将启动
  • 已进行多轮评审
  • 下一个Agent可从代码与当前文件中恢复真实状态
在以下情况沿用现有对话：
  • 后续任务极小且局部化
  • 正在修复同一个漏洞
  • 近期的推理逻辑比代码状态更重要

Default Response Shape

默认响应格式

Use this structure:
  1. Findings
  2. Answer
  3. Next step
  4. Prompt
  5. Fresh vs existing conversation
采用以下结构：
  1. 发现的问题
  2. 回答
  3. 下一步计划
  4. prompt
  5. 开启新对话还是沿用现有对话

Prompt Template

prompt模板

text
We are continuing a phased implementation. This task is intentionally narrow.

Read these files first:
- ...
- ...

Current issue:
- ...

What to change:
- ...

Constraints:
- Do not ...
- Keep ...
- Stay within ...

Acceptance criteria:
- ...
- ...

Verification:
- Run ...
- Report exact files changed
- Explain the root cause and why the fix works
text
We are continuing a phased implementation. This task is intentionally narrow.

Read these files first:
- ...
- ...

Current issue:
- ...

What to change:
- ...

Constraints:
- Do not ...
- Keep ...
- Stay within ...

Acceptance criteria:
- ...
- ...

Verification:
- Run ...
- Report exact files changed
- Explain the root cause and why the fix works