チャットで構築するアプリのエージェント役割：プランナーからレビュワーまでのワークフロー

信頼性が壊れる理由（チャットでアプリを作るとき）

チャットは素早く進められますが、製品全体を頭の中で保持するのは苦手です。多くの失敗は「悪いコード」ではありません。意図したこと、アシスタントの想定、実際にリリースされたものの間に生じたギャップが原因です。

最初の亀裂は要件の抜け落ちです。「シンプルなサインアップフローを作って」と頼んでも、パスワードリセット、既に使われているメールアドレス、ユーザーが途中でタブを閉じたときの扱いといったエッジケースが書かれないことが多いです。アシスタントが空白を埋め、その推測がそのまま製品になります。

二つ目の亀裂は決定の一貫性欠如です。あるメッセージでデータモデルを決め、次でショートカットが入り、さらに別のメッセージで命名やバリデーションルールが変わる。どれも単体では合理的でも、積み重なると次の機能追加で壊れやすい、もろいアプリになります。

三つ目の亀裂は検証不足です。基本的なテストや明確な受け入れチェックがないと、クリックしてみて初めて問題に気づきます。すると "自分の画面では動く" が深夜の修正やランダムなリグレッションにつながります。

簡単な対策は再利用可能なペルソナを使うことです：作業を明確にするプランナー、形を決めるアーキテクト、段階的に作る実装者、壊しにくるテスター、そして痛みの90%を引き起こす最後の10%を見つけるレビュワー。これは重いプロセスではなく、決定を一貫させるための繰り返し可能な仕組みです。

このアプローチは、ソロ創業者、小規模チーム、非技術的な人が chat ツール（例えば Koder.ai）を使う場合にも有効です。速く動けますが、運に頼らなくてもよくなります。

ただし、これらの役割が品質を完全に保証するわけではありません。成功の定義（何が成功か）、制約、優先順位といった明確な入力は引き続き必要ですし、出力を読む必要もあります。役割はガードレールだと考えてください：回避できるミスを減らしますが、最終的にはあなたが運転手です。

コアアイデア：責務を分け、きれいに引き継ぐ

信頼性が下がるのは、1つのチャットが「何を作るか決める」「設計する」「コードを書く」「テストする」「判断する」を同時にしようとするときです。これらを混ぜるとエッジケースを見落としたり、作成中に要件が変わったり、バグを "直す" と称してさらに混乱を招いたりします。

防ぐ現実的な方法は、役割を一貫して狭く保つことです。各役割は1つの仕事を持ち、その仕事の外で "手伝う" ことを許さない。こうすると決定が追跡可能になり、ミスが見つけやすくなります。

ほとんどの機能で次の順序を使ってください：

• プランナー：ゴール、ユーザー、受け入れチェック、除外事項を定義する
• アーキテクト：ゴールを支えられる最もシンプルな設計を提案する
• 実装者：計画どおりに小さなステップで実装する
• テスター：壊しにかかり、失敗を明確に報告する
• レビュワー：命名、セキュリティの基本、UXの欠陥、リスキーな近道など最後の細部を確認する

きれいな引き継ぎは役割と同じくらい重要です。各ハンドオフには決定されたこと、前提、そして「完了」の定義が含まれているべきです。Koder.ai を使うなら、各役割を別のチャットターンやスナップショットとして扱い、決定が間違っていたときにロールバックできるようにしましょう。

意図的にループバックすること。テストが失敗したら、最小限のバグ報告で実装者に戻す。設計が新しい要件を支えられないならアーキテクトに戻す。要件が不明確か頻繁に変わるなら、プランナーに戻して一時停止してください。

機能ごとに同じ役割と順序を保ちましょう。数回繰り返すと、早い段階でより良い質問ができるようになり、後で作業をやり直す回数が減ります。

ペルソナ1：プランナー（誰かが作る前に作業を明確にする）

プランナーの仕事は、ぼんやりしたアイデアを作って検証できる形にすることです。これは「ドキュメントを書く」ことではありません。最初の画面や API エンドポイントが存在する前に「完了」するとは何かを合意することです。

良いプランナーの出力は小さく検証可能です：明確な問題定義、いくつかのユーザーストーリー、シンプルな受け入れ基準、短いエッジケースのリスト。また、「今はやらないこと」を明示して、実装者が勝手にスコープを広げないようにします。

プランナー用プロンプトテンプレート（小さく優先度をつけた計画）

機能アイデアがあり、残りの役割が従える厳密な計画が欲しいときに使ってください。

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>

プランナーで唯一やるべきことがあるとすれば、受け入れ基準を測定可能にすることです。例えば「ユーザーがパスワードをリセットすると 60 秒以内にメールが届く」 は「パスワードリセットが動作する」より優れています。

ペルソナ2：アーキテクト（アプリが実際に支えられる形を選ぶ）

アーキテクトは良い計画を実装可能な形に変えます。役割は凝ったパターンを考案することではなく、本番でユーザーが操作し、データが増え、エラーが起きたときにも動く最もシンプルな構造を選ぶことです。

ここで信頼性が現実味を帯びます：明確な境界、明確なデータ、明確な失敗パス。

実用的なアーキテクトの出力は通常、次をカバーします：

• 画面（React や Flutter）または API エンドポイント（Go）
• 小さなデータモデル（PostgreSQL テーブルと重要なフィールド）
• 1〜2 個のコアフロー（ハッピーパスと起こり得る失敗）
• 現時点で重要な非機能（認証、プライバシー、パフォーマンス、ログ）
• トレードオフ（今は作らないもの）

具体的に保ってください。たとえば "通知システム" と言う代わりに、"POST /api/alerts、table alerts(user_id, type, status)、ヘッダーに未読数を表示" と記述する。"セキュア" と言うだけではなく、"JWT セッション、管理者エンドポイントでのロールチェック、PII フィールドの保護" と書きましょう。

プロンプトテンプレート：アーキテクトのハンドオフ（トレードオフを強制する）

プランナーがアーキテクトに仕事を渡すとき、または機能が混乱していると感じたときにリセットしたいときに使ってください。

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 で作るなら、この種のハンドオフは実装が速くなります。実装者は形を推測する代わりに明確なマップに従えます。

ペルソナ3：実装者（小さなステップで作り、スコープを厳守する）

実装者は明確な計画を動くコードに変えます。計画を変えないことが第一です。ここで信頼性は勝ち取られるか失われます。目標は簡単明瞭：合意した通りに、元に戻せる小さなステップで作ることです。

すべての変更はロールバックされる可能性があると考えましょう。薄いスライスで作業し、受け入れ基準を満たしたら止める。何か不明点があれば質問してください。推測は小さな機能が予期しない大幅な書き換えになる原因です。

良い実装者は短い証跡を残します：ビルド順、何が変わったか、変わらなかったこと（潜在的なスコープ膨張を避けるため）、検証方法。

以下は実装者に渡すときに貼れるプロンプトテンプレートです。

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.

例：プランナーが "パスワードリセットのメールフローを追加" と頼んだなら、実装者はログイン画面を再設計してはいけません。メールリクエスト用エンドポイント、トークン処理、UI の順に実装し、各ステップ後に簡単な検証メモを残します。ツールがスナップショットやロールバックをサポートしていれば（Koder.ai など）、小さなステップはより安全になります。

ペルソナ4：テスター（動作を証明し、壊し方を示す）

テスターの仕事はユーザーの前に機能を壊すことです。ハッピーパスを信用せず、不明瞭な状態、欠けたバリデーション、初日から現れるエッジケースを探します。

良いテスターの出力は他の人が使えるものです：受け入れ基準に結びついたテストマトリクス、短い手動スクリプト、再現可能な手順付きのバグレポート。

何をテストするか（UI、API、データ）

量よりカバレッジを重視してください。失敗したときのコストが高い箇所に集中します：バリデーション、権限、エラーステート。

• UI: 空の状態、エラーメッセージ、読み込み状態、無効化ボタン、キーボードのみの操作
• API: 欠落フィールド、型の不一致、認証失敗、レートやタイムアウトの挙動
• データ検証: 重複、最大長、無効形式、サーバーサイドチェック（UI に依存しない）
• 権限: 通常ユーザーと管理者の差
• リグレッション: 1〜2 個の「既存挙動を壊していないか」チェック

例："請求書作成" を追加したら、負の金額、1 万文字のメモ、顧客がない状態、ダブルサブミットを試してください。

プロンプトテンプレート：受け入れ基準からテストマトリクスを生成する

実装者からテスターへ渡すときに使ってください。受け入れ基準と関連 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：レビュワー（痛みの90%を引き起こす最後の10%を見つける）

レビュワーは最終的な品質チェックを行います。すべてを書き直すためではなく、後で長期的なバグにつながる小さな問題：分かりにくい名前、抜けたエッジケース、弱いエラーメッセージ、次の変更を困難にするリスキーな近道を見つけます。

良いレビューは明確な出力を出します：何をチェックしたか、何を修正すべきか、リスクだが受け入れ可能な点、そして何が決定されたか（次週に再議論しないように記録）。

レビュワーが見るポイント

パスを短く繰り返し可能に保ってください。信頼性を最も損なう項目に集中します：

• 一貫性：命名、パターン、フォルダ構成、UI の挙動が既存アプリと一致しているか
• セキュリティの基本：入力検証、認可チェック、ログに機密データが含まれていないか
• エラー：ユーザー向けメッセージは明確か、サーバーエラーは対処しやすいか、サイレント失敗はないか
• 保守性：関数が小さいか、意図が明らかか、理由のない重複ロジックがないか
• 将来の変更：後で変更が難しくなる箇所と、それを減らす方法

構造化されたレビューのプロンプト（承認か差し戻しか）

実装者が機能を完了したと言ったときにこのハンドオフを使ってください。

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

レビュワーが変更を要求する場合、それは小さく具体的であるべきです。目的は本番での驚きを減らすことで、二度目の大きな開発サイクルを作ることではありません。

再作業を防ぐハンドオフテンプレート

多くの再作業は次の人があいまいなゴール、不足した入力、隠れた制約で始めるために起きます。単純なハンドオフテンプレートは、すべての受け渡しを予測可能にします。

毎回使う共通ヘッダーを用意しましょう（小さなタスクでも）：

• Context + Goal：何を、なぜ作るのかを1段落で。
• 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つのユーザーストーリーから始め、平易な言葉で書き、誰でも検査できる受け入れ基準を加えます。

そのストーリーを支える最小限の設計だけ行ってください。目的は完璧なシステムではなく、次の機能を追加しても崩れないシンプルな計画です。

実用的なフローはこうなります：

1. プランナー：ユーザーストーリー、エッジケース、受け入れ基準（成功、失敗、ユーザーが X をしたらどうなるか）を確定する。
2. アーキテクト：最小限のデータモデルと API 面（テーブル/フィールド、エンドポイント、認可ルール）を提案し、作らないものを短く示す。
3. 実装者：受け入れ基準を満たす薄いスライス（UI→API→DB）を一通り作る。UI は簡素でもよい。
4. テスター：再現可能なテストスクリプトを実行し、再現手順付きで失敗をログに残し、不明瞭な挙動を記録する。
5. レビュワー：セキュリティの基本とプロダクトの仕上げを最終チェックし、決定を記録する。

各ステップの出力は小さく明確に保つこと。一つのハンドオフメッセージ（入力、決定、次に必要なこと）で十分なことが多いです。

最後に 1 パラグラフの変更ノートを書いて終わりましょう：何を追加し、何を削除し、次のリリースで何に注意するか。これが記憶となり、同じ議論やバグの再発を防ぎます。

現実的な例：アイデアからレビュー済みリリースまでの一つの機能

機能：ユーザーが連絡先を追加し、"Lead" や "Vendor" のようなタグを付け、名前やタグで検索できる簡単な CRM 画面。制約：90 分で完了、既存の contacts テーブルを再利用（破壊的なマイグレーションは不可）。モバイルは1ページ内に収まる "Add Contact" 画面が必要。

以下は、このペルソナチェーンを使ったときのハンドオフ例です。各役割が次の人が信頼できる小さなアーティファクトを作ります。

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: プランナーの Scope、Assumptions、Acceptance Criteria がない限りコードを書かない。欠けている場合は最大 3 つまで質問をすること。"
• 完了の定義がないため作業が終わらない。修正：各ハンドオフに Done 行を必須にする。例："Done means: acceptance criteria met, no new TODOs, and changes documented in 5 bullets." を追加する。
• テスターがハッピーパスしかチェックしない。修正：必ず無効な入力ケースとエッジケースを1つずつ含める。テンプレート修正："Tester: provide (1) happy path, (2) one invalid input case, (3) one edge case. If you can’t run it, describe exact steps and expected output."
• レビュワーがスタイルを議論してプロダクトリスクを無視する。修正：レビュワーにまずリスクに集中させる。テンプレート修正："Reviewer: list the top 3 risks (security, data loss, broken UX, performance). Mention style only if it blocks readability or causes bugs."
• ハンドオフに文脈が足りず次の役割が推測する。修正：毎回短い Handoff Block を必須にする："Goal, What changed, How to verify, Known gaps." を 8 行以内に保つ。

役立つ小さな習慣：実装者が終わったら受け入れ基準をもう一度貼り、1つずつチェックを入れていくこと。

チャットで作る信頼できるリリースのためのクイックチェックリスト

ビルド前、マージ前、そしてリリース直後にこのチェックリストを回してください。

ビルド前（誰かがコードを書く前）

• ゴールを一文で書き、2-3 の受け入れチェック（何が "完了" か）を列挙する。
• スコープ外を明記する（実装者が推測しないように）。
• 正確なデータフィールドとルールを列挙する（型、必須/任意、デフォルト）。
• 主なエラーケースを記録する（不正入力、権限不足、空状態、タイムアウト）。
• 迅速に検証する方法を決める（画面、API レスポンス、ログ行）。

小さな例："メールで招待を送る"。フィールド（email, role）、メールが無効な場合の扱い、再招待を許可するかどうかを含めてください。

プレマージとポストリリース（変更への恐れを減らす）

• プレマージ：テストが実行された（または短い手動スクリプトが実行された）ことを確認し、何をチェックしたかを記録する。
• プレマージ：2〜3 のエッジケースを明示的にカバーする（"動くはず" ではなく）。
• プレマージ：ロールバック計画と、どの変更がトリガーになるかを記録する。
• ポストリリース：最初の1時間〜1日で 1〜2 のシグナル（エラー、遅いページ、失敗したジョブ）を監視する。
• ポストリリース：ユーザーフィードバックを取り、サポートが推測しないよう既知の制限を書き留める。

プラットフォームがサポートしていれば（Koder.ai など）、リスクのある編集前にスナップショットを取ると良いです。ロールバックできると小さく安全に出荷しやすくなります。

次の一歩：これをデフォルトワークフローにする

一つの小さな機能を選んで、ペルソナチェーンを一度だけ実行してみてください。実際的で範囲が限定されたもの（"パスワードリセットを追加"、"管理者専用ページを作る"、"請求書を CSV にエクスポート"）を選びます。プランナーからレビュワーまでクリーンにハンドオフすると何が変わるかを観察するのが目的です。

Koder.ai を使っているなら、Planning Mode はスコープと受け入れチェックを実装前に固定するのに便利です。そして、スナップショットとロールバックが決定が誤っていたときの安全弁となり、プロジェクト全体を議論で止めずに済みます。

ワークフローを繰り返し可能にするには、ペルソナプロンプトをテンプレートとして保存しましょう。短く、出力形式を一貫させておくと、毎回同じ文脈を説明する手間が減ります。