为聊天构建的应用设定代理人角色:定义清晰的人设、交接提示和快速检查,让团队能从聊天更可靠地交付 Web 与移动应用。

聊天能让你快,但它不擅长把整个产品都牢记在脑中。大多数失败并不是“代码写得差”。而是你想要的、助手假定的、以及实际交付的之间出现了差距。
第一个裂缝是缺少需求。你要的是“一个简单的注册流程”,但没人写下像重置密码、邮箱已被使用,或用户在中间关闭标签页时会发生什么这样的边界情况。助手去填补这些空白,而这些猜测就变成了你的产品。
第二个裂缝是决策不一致。一次消息选了某个数据模型,下一次添加了捷径,第三次又改了命名或校验规则。每个选择单看都合理,但放在一起就会造出一个脆弱的应用,下一次增加功能时就会出问题。
第三个裂缝是缺乏证明。没有基本的测试和明确的验收检查,你往往要点击运行后才发现问题。那时“在我机子上能跑”就会变成熬夜、补丁和随机的回归。
一个简单的修复是使用可复用的人格分工:Planner(把工作具体化)、Architect(搭建结构)、Implementer(按小步骤实现)、Tester(尝试破坏它)和 Reviewer(抓住那最后10%会导致90%痛苦的部分)。这不是沉重的流程,而是一种可重复的方式来保持决策一致性。
这种方法适用于独立创始人、小团队和使用像 Koder.ai 这样的聊天工具的非技术构建者。你仍然可以快速行动,但不再完全依赖运气。
这些角色不会魔法般地保证质量。你仍需要清晰的输入(成功长什么样、约束、优先级),你也仍需要阅读输出。把角色看作护栏:它们减少可避免的错误,但你仍然是司机。
当一个聊天尝试一次性完成所有事:决定要构建什么、设计它、编写代码、测试并评判时,可靠性就会下降。把这些工作混在一起很容易漏掉边界情况、在构建中途改变需求,或者通过增加更多混乱来“修复”bug。
防止这种情况的实用方法是保持角色一致且职责狭窄。每个角色只负责一件事,并且不被允许在该职责外“帮忙”。这让决策可追溯,也让错误更容易被发现。
对几乎任何功能都可以使用以下顺序:
干净的交接和角色同样重要。每次交接都应包含已决定的内容、所做的假设和“完成”意味着什么。如果你使用 Koder.ai,把每个角色作为独立的聊天回合或快照对待,这样当某项决策证明错误时可以回退。
按目的回环,而不是意外回环。如果测试失败,回到 Implementer 并附上最小化的 bug 报告。如果设计无法支持新需求,回到 Architect。如果需求不清或不断变化,暂停并回到 Planner。
在不同功能间保持相同的角色和顺序。几次执行后,你会形成肌肉记忆:你会在早期问出更好的问题,也会停止在后期重做工作。
Planner 的工作是把模糊的想法变成可构建且可验证的东西。这不是“写文档”。而是在第一张屏幕或接口出现之前就达成对“完成”的一致。
一个好的 Planner 输出要小而可测:清晰的问题陈述、几条用户故事、简单的验收标准和一小段边界情况清单。同时它还应说明当前不做什么,以免 Implementer 无意中构建超出预期的更大功能。
在你有功能想法并希望产生让后续角色可遵循的紧凑计划时使用。
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 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 秒内收到邮件” 要比 “密码重置可用” 更好。
Architect 把好的计划变成可构建的结构。工作不是去发明花哨的模式,而是选择在真实用户点击、数据增长和错误发生时仍能工作的最简单结构。
这里是可靠性开始变得真实的地方:清晰的边界、明确的数据和明确的失败路径。
实用的 Architect 输出通常包括:
保持具体。不要写“通知系统”,要写“POST /api/alerts,表 alerts(user_id, type, status),在页眉显示未读计数”。不要只写“安全”,要写“JWT 会话,管理员端点的角色校验,保护 PII 字段”。
在 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 可以遵循清晰的地图而不是在构建中猜测结构。
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 支持),小步执行会更安全。
Tester 的工作是在用户之前弄坏功能。他们不信任正常路径,会寻找不清晰的状态、缺失的校验以及上线第一天就会出现的边界情况。
一个好的 Tester 输出应便于他人使用:与验收标准挂钩的测试矩阵、简短的手动脚本,以及带有精确步骤(期望 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.
Reviewer 是最后的质量把关。不是为了重写所有东西,而是发现那些会演变成长期 bug 的小问题:令人困惑的命名、缺失的边界情况、薄弱的错误信息以及让下次修改更困难的冒险捷径。
一个好的 Review 输出很明确:检查了什么、必须改的是什么、哪些是有风险但可接受的,以及已做出的决定(这样下周就不会再争论)。
把检查保持简短且可重复。关注那些最常破坏可靠性的点:
当 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 请求更改,应当小而具体。目标是减少生产环境的意外,而不是启动第二轮开发。
大多数返工发生是因为下一位开始时目标模糊、输入缺失或有隐藏约束。一个简单的交接模板可以让每次移交都变得可预测。
每次交接都使用一个共享的页眉,即使是小任务也要统一:
下面是一个 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,然后在实现前拍一个快照,这样如果范围发生变化,回滚会很容易。
当你把每个功能当作一次小发布,并在角色间做干净交接时,可靠性会提升。从一个用户故事开始,而不是一堆想法。用简单语言写出来,然后加入让某人可以验证的验收标准。
只设计支持该故事的最小形状。目标不是完美系统,而是一个在你加入下一个功能时不会塌掉的简单计划。
一个实用流程如下:
保持每一步的输出小而明确。通常每个角色一条交接消息就够:输入、已做决定、以及下一步需要什么。
最后写一段一段话的变更说明:添加了什么、移除了什么、下一次发布要注意什么。这段“记忆”能防止相同的争论和 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 在发布前验证了性能和抛光。
让聊天构建的软件失去信任的最快方式是让每个人什么都会做。清晰的角色和干净的交接让工作可预测,即使你动作很快。
一个有用的小习惯:Implementer 完成后,把验收标准再贴一次并逐条打勾。
在构建前、合并前和发布后都运行这份清单。
一个小例子:"添加按邮件邀请"。包括字段(email、role)、当 email 无效时会怎样,以及是否允许重复邀请。
如果你的平台支持(Koder.ai 支持),在有风险的编辑前拍一个快照。知道可以回滚会让你更容易小步发布且更安全。
选一个小功能并完整跑一次人格链。选一些真实但受限的任务,比如“添加密码重置”、“创建仅管理员页面”或“导出发票到 CSV”。目的是观察当你强制从 Planner 到 Reviewer 做干净交接时会发生什么变化。
如果你使用 Koder.ai (koder.ai),Planning Mode 是在构建前锁定范围和验收检查的实用位置。然后快照和回滚提供了安全出口,当某项决策证明错误时,不必把整个项目变成争论场。
要让工作流可重复,保存你的人格提示作为团队可复用的模板。保持简短,保持输出格式一致,你们就能花更少时间反复解释同样的上下文。