用于聊天构建应用的代理人角色：从 Planner 到 Reviewer 的工作流

当你通过聊天构建应用时，为什么可靠性会崩塌

聊天能让你快，但它不擅长把整个产品都牢记在脑中。大多数失败并不是“代码写得差”。而是你想要的、助手假定的、以及实际交付的之间出现了差距。

第一个裂缝是缺少需求。你要的是“一个简单的注册流程”，但没人写下像重置密码、邮箱已被使用，或用户在中间关闭标签页时会发生什么这样的边界情况。助手去填补这些空白，而这些猜测就变成了你的产品。

第二个裂缝是决策不一致。一次消息选了某个数据模型，下一次添加了捷径，第三次又改了命名或校验规则。每个选择单看都合理，但放在一起就会造出一个脆弱的应用，下一次增加功能时就会出问题。

第三个裂缝是缺乏证明。没有基本的测试和明确的验收检查，你往往要点击运行后才发现问题。那时“在我机子上能跑”就会变成熬夜、补丁和随机的回归。

一个简单的修复是使用可复用的人格分工：Planner（把工作具体化）、Architect（搭建结构）、Implementer（按小步骤实现）、Tester（尝试破坏它）和 Reviewer（抓住那最后10%会导致90%痛苦的部分）。这不是沉重的流程，而是一种可重复的方式来保持决策一致性。

这种方法适用于独立创始人、小团队和使用像 Koder.ai 这样的聊天工具的非技术构建者。你仍然可以快速行动，但不再完全依赖运气。

这些角色不会魔法般地保证质量。你仍需要清晰的输入（成功长什么样、约束、优先级），你也仍需要阅读输出。把角色看作护栏：它们减少可避免的错误，但你仍然是司机。

核心思想：分离职责，然后进行干净的交接

当一个聊天尝试一次性完成所有事：决定要构建什么、设计它、编写代码、测试并评判时，可靠性就会下降。把这些工作混在一起很容易漏掉边界情况、在构建中途改变需求，或者通过增加更多混乱来“修复”bug。

防止这种情况的实用方法是保持角色一致且职责狭窄。每个角色只负责一件事，并且不被允许在该职责外“帮忙”。这让决策可追溯，也让错误更容易被发现。

对几乎任何功能都可以使用以下顺序：

• Planner：定义目标、用户、验收检查以及哪些不在范围内
• Architect：提出可以支撑目标的最简单设计
• Implementer：按计划分小步实现
• Tester：尝试破坏并清楚地报告失败情况
• Reviewer：检查最后的细节（命名、安全基础、UX 漏洞、有风险的捷径）

干净的交接和角色同样重要。每次交接都应包含已决定的内容、所做的假设和“完成”意味着什么。如果你使用 Koder.ai，把每个角色作为独立的聊天回合或快照对待，这样当某项决策证明错误时可以回退。

按目的回环，而不是意外回环。如果测试失败，回到 Implementer 并附上最小化的 bug 报告。如果设计无法支持新需求，回到 Architect。如果需求不清或不断变化，暂停并回到 Planner。

在不同功能间保持相同的角色和顺序。几次执行后，你会形成肌肉记忆：你会在早期问出更好的问题，也会停止在后期重做工作。

人格 1：Planner（在任何人开始构建前把工作讲清楚）

Planner 的工作是把模糊的想法变成可构建且可验证的东西。这不是“写文档”。而是在第一张屏幕或接口出现之前就达成对“完成”的一致。

一个好的 Planner 输出要小而可测：清晰的问题陈述、几条用户故事、简单的验收标准和一小段边界情况清单。同时它还应说明当前不做什么，以免 Implementer 无意中构建超出预期的更大功能。

Planner 提示模板（小而有优先级的计划）

在你有功能想法并希望产生让后续角色可遵循的紧凑计划时使用。

You are the Planner. Turn the feature idea below into a buildable plan.

Feature idea:
<PASTE IDEA>

Context:
- App type:
- Target users:
- Current behavior (if any):
- Constraints (time, data, compliance, devices):

Output (keep it short):
1) Problem statement (1-2 sentences)
2) Assumptions (3-6 bullets)
3) Questions to confirm (max 6, prioritized)
4) User stories (2-5)
5) Acceptance criteria (5-10, testable, specific)
6) Edge cases & failure modes (3-8)
7) Out of scope (3-6 bullets)
8) Small milestone plan (2-4 steps, highest value first)

从 Planner 到 Architect 的交接（结构化且简短）

把下面这条消息按原样（填充好）发送，以减少来回沟通。

PLANNER HANDOFF
Feature: <name>
Problem: <1-2 sentences>
Users: <who>
Must-haves (AC): <5-10 acceptance criteria>
Key edge cases: <3-6>
Out of scope: <3-6>
Open questions (need Architect input): <1-4>
Constraints: <tech, data, privacy, deadlines>
Success signal: <how we’ll know it worked>

如果 Planner 只做一件事，那就是让验收标准可度量。例如：“用户可以重置密码并在 60 秒内收到邮件” 要比 “密码重置可用” 更好。

人格 2：Architect（选择应用能真正支撑的形状）

Architect 把好的计划变成可构建的结构。工作不是去发明花哨的模式，而是选择在真实用户点击、数据增长和错误发生时仍能工作的最简单结构。

这里是可靠性开始变得真实的地方：清晰的边界、明确的数据和明确的失败路径。

实用的 Architect 输出通常包括：

• 屏幕（React 或 Flutter）或 API 端点（Go）
• 一个小的数据模型（PostgreSQL 表和关键字段）
• 一到两个核心流程（正常路径以及可能出错的情况）
• 现阶段重要的非功能需求（认证、隐私、性能、日志）
• 权衡（暂不构建的内容）

保持具体。不要写“通知系统”，要写“POST /api/alerts，表 alerts(user_id, type, status)，在页眉显示未读计数”。不要只写“安全”，要写“JWT 会话，管理员端点的角色校验，保护 PII 字段”。

提示模板：Architect 交接（强制做出取舍）

在 Planner 把工作交给 Architect 时使用，或当你想重置感觉混乱的功能时使用。

You are the Architect.
Goal: design the simplest buildable structure for this feature.
Context:
- App type: [web/mobile/both]
- Stack: React UI, Go API, PostgreSQL DB (Flutter screens if mobile)
- Existing constraints: [auth method, existing tables, deadlines]

Input (from Planner):
- User story:
- Acceptance criteria:
- Out of scope:

Deliverables (keep it short and specific):
1) UI map: list screens/components with 1-line purpose each.
2) API map: list endpoints with method, path, request/response fields.
3) Data model: tables + key columns + relationships.
4) Key flows: happy path + 2 failure cases and how UI should respond.
5) Non-functional needs: security, performance, audit/logging (only what matters now).
6) Tradeoffs: 3 decisions you made (and what you avoided) to prevent over-design.

Rules:
- Prefer the smallest option that meets acceptance criteria.
- If something is unclear, ask up to 3 questions, otherwise make a reasonable assumption and write it down.

如果你在 Koder.ai 中构建，这种交接会让实现更快，因为 Implementer 可以遵循清晰的地图而不是在构建中猜测结构。

人格 3：Implementer（分小步实现，严格遵守范围）

Implementer 把清晰的计划变成可运行的代码，但不改变计划。这里是可靠性最终成败的关键。目标很直接：按约定小步实现，可回滚。

把每次变更都当作可能要回滚来处理。以薄片切入，满足验收标准就停止。如果有什么不清楚，问清楚。猜测是小功能变成意外重写的原因。

一个好的 Implementer 会留下简短的证据轨迹：构建顺序、改了什么、没改什么（避免隐藏范围蔓延），以及如何验证。

下面是当把工作交给 Implementer 时可粘贴的提示模板：

You are the Implementer.

Context:
- Feature: <name>
- Current behavior: <what happens today>
- Desired behavior: <what should happen>
- Acceptance criteria: <bullets>
- Constraints: <tech choices, performance, security, no schema change, etc.>

Before writing code:
1) Ask up to 5 questions if anything is unclear.
2) Propose a step-by-step build plan (max 6 steps). Each step must be reversible.
3) For each step, list the exact files/modules you expect to touch.

Then implement:
- Execute steps one by one.
- After each step, summarize what changed and how to verify.
- Do not add extras. If you notice a better idea, stop and ask first.

举例：如果 Planner 要求“添加密码重置邮件流程”，Implementer 不应该顺便重设计登录屏。先实现邮件请求端点，再实现 token 处理，然后实现 UI，并在每一步后提供简短的验证说明。如果你的工具支持快照和回滚（Koder.ai 支持），小步执行会更安全。

人格 4：Tester（在用户之前先把它弄坏）

Tester 的工作是在用户之前弄坏功能。他们不信任正常路径，会寻找不清晰的状态、缺失的校验以及上线第一天就会出现的边界情况。

一个好的 Tester 输出应便于他人使用：与验收标准挂钩的测试矩阵、简短的手动脚本，以及带有精确步骤（期望 vs 实际）的缺陷报告。

要测试的内容（UI、API 和数据）

以覆盖重要点为目标，而不是追求数量。重点在于失败代价高的地方：校验、权限和错误状态。

• UI：空状态、错误信息、加载状态、禁用按钮、仅键盘可用流程
• API：缺失字段、错误类型、认证失败、限流/超时行为
• 数据校验：重复、最大长度、非法格式、服务端校验（而非仅靠 UI）
• 权限：普通用户能做什么 vs 管理员能做什么
• 回归：一到两个“我们有没有破坏现有行为？”检查

举例：如果你添加了“创建发票”，尝试负金额、10000 字符备注、缺失客户和重复提交点击。

提示模板：从验收标准生成测试矩阵

在 Implementer 交给 Tester 时使用。粘贴验收标准和相关的 UI/API 说明。

ROLE: Tester
GOAL: Produce a test matrix tied to acceptance criteria, including negative tests.
CONTEXT:
- Feature: <name>
- Acceptance criteria:
  1) <AC1>
  2) <AC2>
- Surfaces: UI screens: <list>; API endpoints: <list>; DB changes: <notes>
OUTPUT FORMAT:
1) Test matrix table with columns: AC, Test case, Steps, Expected result, Notes
2) Negative tests (at least 5) that try to break validation and permissions
3) Manual test script (10 minutes max) for a non-technical person
4) Bug ticket template entries for any failures you predict (Title, Steps, Expected, Actual, Severity)
CONSTRAINTS:
- Keep steps precise and reproducible.
- Include at least one test for loading/error states.

人格 5：Reviewer（抓住那最后 10% 导致 90% 痛点的细节）

Reviewer 是最后的质量把关。不是为了重写所有东西，而是发现那些会演变成长期 bug 的小问题：令人困惑的命名、缺失的边界情况、薄弱的错误信息以及让下次修改更困难的冒险捷径。

一个好的 Review 输出很明确：检查了什么、必须改的是什么、哪些是有风险但可接受的，以及已做出的决定（这样下周就不会再争论）。

Reviewer 会关注的点

把检查保持简短且可重复。关注那些最常破坏可靠性的点：

• 一致性：命名、模式、文件夹结构和 UI 行为是否与现有应用匹配
• 安全基础：输入校验、认证检查、日志中无敏感数据
• 错误：面向用户的消息清楚；服务端错误可操作；无静默失败
• 可维护性：函数小巧、意图明显、无无理由的重复逻辑
• 未来更改：将来哪些改动会很难做，如何在现在降低成本

结构化审查提示（通过或需改进）

当 Implementer 说功能完成时使用：

You are the Reviewer. Do a final review for correctness, clarity, and maintainability.

Context
- Feature goal:
- User flows:
- Key files changed:
- Data model/migrations:

Review checklist
1) Correctness: does it meet the goal and handle edge cases?
2) Security basics: auth, validation, safe logging.
3) Errors: clear messages, consistent status codes.
4) Consistency: naming, patterns, UI text.
5) Maintainability: complexity, duplication, TODOs.

Output format
- Findings (bulleted): include file/function references and severity (high/medium/low)
- Requested changes (must-fix before merge)
- Risk notes (acceptable with reason)
- Decision log updates (what we decided and why)

Finish with exactly one:
APPROVE
CHANGES REQUESTED

如果 Reviewer 请求更改，应当小而具体。目标是减少生产环境的意外，而不是启动第二轮开发。

可防止返工的交接模板

大多数返工发生是因为下一位开始时目标模糊、输入缺失或有隐藏约束。一个简单的交接模板可以让每次移交都变得可预测。

每次交接都使用一个共享的页眉，即使是小任务也要统一：

• Context + Goal：一句话说明你在做什么以及为什么做
• Inputs：屏幕、API 注释、字段示例、相关代码区域
• Constraints：技术选择、截止日期、性能、安全、必须保留的行为
• Definition of Done：可衡量的检查项（必须通过什么，必须存在什么）
• Assumptions / Open questions / Decisions made：你做了哪些假设，哪些未知，哪些已经锁定

下面是一个 Architect -> Implementer 的交接示例：

ROLE HANDOFF: Architect -> Implementer
Context: Add “Invite team member” to the admin area.
Goal: Admin can send an invite email; invited user can accept and set a password.
Inputs: Existing Users table; auth uses JWT; email provider already configured.
Constraints: Go backend + PostgreSQL; React UI; audit log required; no breaking auth changes.
Definition of Done:
- UI: invite modal + success state
- API: POST /invites, POST /invites/accept
- DB: invites table with expiry; audit event on create/accept
- Tests: happy path + expired invite + reused token
Assumptions: Email templates can reuse “reset password” styling.
Open questions: Should invites be single-use per email?
Decisions made: 72h expiry; tokens stored hashed.

如果你想让这个流程持久化，把模板存到每个人都能复制的地方。如果你在 Koder.ai 中构建，可以把这些提示保存在 Planning Mode，然后在实现前拍一个快照，这样如果范围发生变化，回滚会很容易。

每个功能都可遵循的分步工作流

当你把每个功能当作一次小发布，并在角色间做干净交接时，可靠性会提升。从一个用户故事开始，而不是一堆想法。用简单语言写出来，然后加入让某人可以验证的验收标准。

只设计支持该故事的最小形状。目标不是完美系统，而是一个在你加入下一个功能时不会塌掉的简单计划。

一个实用流程如下：

1. Planner：确认用户故事、边界情况和验收标准（成功、失败以及“如果用户做 X 会怎样”）。
2. Architect：提出最小的数据模型和 API 面（表/字段、端点、认证规则），并简要说明不做什么。
3. Implementer：实现一条薄片端到端（UI 到 API 到 DB），满足验收标准，即使 UI 很朴素。
4. Tester：运行可重复的测试脚本，记录可复现的失败步骤，并说明任何不清楚的行为。
5. Reviewer：做最终的安全基础和产品抛光检查，然后记录决策。

保持每一步的输出小而明确。通常每个角色一条交接消息就够：输入、已做决定、以及下一步需要什么。

最后写一段一段话的变更说明：添加了什么、移除了什么、下一次发布要注意什么。这段“记忆”能防止相同的争论和 bug 以后又回头出现。

现实示例：从想法到审查发布的一个功能

功能：一个简单的 CRM 界面，用户可以添加联系人、应用标签（如 “Lead” 或 “Vendor”），并按名字或标签搜索。约束：你有 90 分钟，且必须重用现有的 contacts 表（不能破坏迁移）。移动端需要一个在一页内完成的“添加联系人”界面。

下面是当你使用这条人格链时的交接样例。每个角色会产出一个下一个人可以信赖的小产物。

Planner output (definition + acceptance)
- Goal: Add contacts with tags and fast search.
- Must: Create, edit, list contacts; add/remove tags.
- Search: matches name OR any tag; results update in under 300ms.
- Constraint: keep existing contacts table; tags can be new table.
- Done when: 5 test cases pass; mobile screen has no scroll on common devices.

Architect output (shape + data)
- Tables: contacts (existing), tags (id, name), contact_tags (contact_id, tag_id).
- API: POST /contacts, PATCH /contacts/:id, GET /contacts?query=.
- Search: SQL ILIKE on contact name + join on tags.
- UI: Contact list with search bar; contact form with tag picker.
- Risk: duplicate tags (“lead” vs “Lead”) - enforce lowercase unique.

Implementer output (small steps)
- Step 1: Add tags + join table migrations.
- Step 2: Update backend handlers and query.
- Step 3: Build React UI list + form; wire to API.
- Step 4: Add basic validation (name required, tag length).
- Step 5: Add loading/error states; keep UI responsive.

Tester output (proof + failure)
- Case: search “lea” returns contacts tagged “lead”. FAIL: returns none.
- Case: adding tag “Lead” then “lead” should not create two tags. PASS.
- Case: empty name rejected. PASS.
- Bug note: backend search only checks contact name, not tags.

Loop-back (Planner update)
- Update acceptance: search must match tags via join; include a test for it.
- Add edge case: searching by tag should return even if name doesn’t match.

Reviewer output (last 10%)
- Check: query uses indexes; add index on tags.name and contact_tags.tag_id.
- Check: error messages are clear; avoid raw SQL errors.
- Check: mobile form spacing and tap targets.
- Confirm: snapshots/rollback point created before release.

那个失败的测试强制做了一个干净的回环：计划变得更清晰，Implementer 改了一条查询，Reviewer 在发布前验证了性能和抛光。

常见陷阱（及简单修复）

让聊天构建的软件失去信任的最快方式是让每个人什么都会做。清晰的角色和干净的交接让工作可预测，即使你动作很快。

• 人格模糊（在需求稳定前就开始构建）。修复：在任何改动前把 Planner 输出锁定。模板修改："Implementer: 未看到 Planner 的 Scope、Assumptions 和 Acceptance Criteria 前不得写代码。若缺失，最多问 3 个问题。"
• 没有完成定义，工作永远做不完。修复：每次交接必须包含一个 Done 行。示例："Done 意味着：验收标准通过、没有新的 TODO、并在 5 条内记录改动。"
• Tester 只检查正常路径。修复：每次强制包含一个无效输入用例和一个边界用例。模板修改："Tester: 提供 (1) 正常路径，(2) 一个无效输入用例，(3) 一个边界用例。若无法运行，描述精确步骤和期望输出。"
• Reviewer 辩论风格而非产品风险。修复：强制 Reviewer 优先关注风险。模板修改："Reviewer: 列出前三个风险（安全、数据丢失、破坏性 UX、性能）。只有在样式阻碍可读或导致 bug 时才提样式问题。"
• 交接缺失上下文，导致下一位猜测。修复：要求每次交接都有简短的 Handoff Block："Goal, What changed, How to verify, Known gaps." 保持在 8 行以内。

一个有用的小习惯：Implementer 完成后，把验收标准再贴一次并逐条打勾。

可让聊天构建发布更可靠的快速清单

在构建前、合并前和发布后都运行这份清单。

构建前（在任何人写代码前）

• 用一句话写下目标并列出 2-3 条验收检查（什么是“完成”）。
• 写明什么不在范围内（避免 Implementer 猜测）。
• 列出精确的数据字段和规则（类型、必填/可选、默认值）。
• 注明主要错误情况（非法输入、缺失权限、空状态、超时）。
• 决定如何快速验证（一个屏幕、一个 API 响应、一行日志）。

一个小例子："添加按邮件邀请"。包括字段（email、role）、当 email 无效时会怎样，以及是否允许重复邀请。

合并前与发布后（减少变更恐惧）

• 合并前：确认测试已运行（或至少有短手动脚本）并记录检查内容。
• 合并前：明确覆盖 2-3 个边界用例，而不是“应该能工作”。
• 合并前：写下回滚计划以及触发回滚的变更条件。
• 发布后：观察 1-2 个信号（错误、慢页面、失败任务）在首小时/首日内。
• 发布后：收集用户反馈并写下已知限制，避免支持方去猜测。

如果你的平台支持（Koder.ai 支持），在有风险的编辑前拍一个快照。知道可以回滚会让你更容易小步发布且更安全。

下一步：把这套流程设为默认

选一个小功能并完整跑一次人格链。选一些真实但受限的任务，比如“添加密码重置”、“创建仅管理员页面”或“导出发票到 CSV”。目的是观察当你强制从 Planner 到 Reviewer 做干净交接时会发生什么变化。

如果你使用 Koder.ai (koder.ai)，Planning Mode 是在构建前锁定范围和验收检查的实用位置。然后快照和回滚提供了安全出口，当某项决策证明错误时，不必把整个项目变成争论场。

要让工作流可重复，保存你的人格提示作为团队可复用的模板。保持简短，保持输出格式一致，你们就能花更少时间反复解释同样的上下文。