観察可能な成果から始める
コーディングエージェントは、画面が何をすべきか決める前に説得力のある見た目を作れてしまいます。まず小さなユーザー成果から始めましょう：ログインしたユーザーがプロフィールを編集し、保存し、リロード後に保存された名前を見る。これが実装とレビューに具体的な目標を与えます。
ブリーフには現在の振る舞い、期待される振る舞い、重要な失敗ケースを含めます。作業を所有している既存モジュールを名指しします。プロフィール編集の追加依頼は、エージェントに二番目のユーザーストアを発明させるのではなく、認証層を指し示すべきです。認証情報はプロンプトやスクリーンショットに入れないでください — 貼り付けられた apps/web/.env.local やセッション Cookie は会話記録の一部になります。
実用的なブリーフはこんな風に書けます：「アカウント画面で、ログイン中のユーザーが表示名を編集し、リロード後にそれを確認できるようにする。ユーザーレコードは認証モジュールが所有するので、テーブルは追加しない。空の名前、または他のユーザーのレコードを指すリクエストは拒否しなければならない。pnpm test と狭い幅での 1 回の手動保存で証明する。」5 文で、推測の余地はほぼ消えます。
- ユーザーに見える成果を、動作中のアプリで確認できる表現で書くこと。
- 今日その振る舞いを所有しているファイルやモジュール — そして手つかずに保つべき領域。
- 少なくとも 1 つの失敗ケース：未認証の試行、無効な入力、または繰り返されたリクエスト。
- それを証明するチェック — テストコマンド、フィクスチャ、または明示的な手動ウォークスルー。
リポジトリに自己説明させる
アプリの実行方法、どのチェックが決定的か、所有権がどこで強制されるかを文書化します。supastack では AGENTS.md がワークスペース境界を記録し、.ai/ がファイル単位の決定を記録します。これらのノートは、どのファイルが変わったかだけでなく、実装がなぜ存在するかを次の貢献者 — 人間でもエージェントでも — に伝えるときに最も有用です。エージェントセットアップガイドはキットがその情報をどう公開するかを示し、ローカルセットアップガイドがエージェントが実際に従うウォークスルーです。
変更前に関連コードを読むようエージェントに依頼します。狭い変更には通常、インターフェース、そのサーバー境界、その境界周辺のテストが必要です。リポジトリ全体を読み込むより、新しい振る舞いが正しいかを決める数か所 — 所有権チェック、スキーマ、権限 — を理解する方が有用です。
機能が設定に触れるときは、内容を書き写すのではなくファイル名を指定します — 「apps/web/.env.local にキーを追加する」なら秘密情報はディスクに残ります。同じ規律はプロバイダーのダッシュボードにも当てはまります：宛先を説明し、認証情報を貼り付けないことです。
小さくレビュー可能な変更で進める
エージェントは、変更に 1 人のオーナーと 1 つの確認可能な成果があるときに最も信頼できます。「プロフィール編集を追加する」はレビュー可能ですが、「アカウント周辺を改善する」は誰も頼んでいないリファクターを招きます。機能がスキーマ変更・サーバー境界・画面に分解できるなら、それぞれビルドをグリーンに保つ別々のブリーフとして実行します。
エージェントを実行する前にコミットまたはチェックポイントを取ります。クリーンなベースラインがあれば、悪い出力は考古学の作業ではなく削除すればよい差分になり、レビューにも安定した前後比較を与えます。
一度に一つの完全な変更をレビューする
振る舞いを変える前に受け入れチェックを書きます。プロフィール編集なら、有効な更新と未認可の試行をカバーします。それらのケースを満たす最小の実装を作り、実際のテキストと狭いビューポートで実際の操作を検査します。
結果と同じくらい差分をレビューします。重複したビジネスロジック、過度に広い例外処理、既存スタックが既にカバーする問題を解決する新しい依存を探します。プロジェクトのチェックを実行し、それらが確立することを記録します。ブラウザフィクスチャはフォーム操作を検証できますが、本番データベースや外部プロバイダーが正しく設定されていることは確立できません。
各コマンドは異なる質問に答えます。pnpm test は決定的な fake とローカルアダプターに対して振る舞いを実行し、pnpm check は lint・型チェック・フォーマットをカバーし、pnpm build はバンドル時にしか現れない統合エラーを表面化させます。合わせてレビューの最低ラインになります — ローンチチェックリストは実環境でまだ証明すべきことをカバーしています。
pnpm test
pnpm check
pnpm buildエージェントが間違えたとき
結果が間違っていたら、悪い差分の上に追加のプロンプトを積み重ねるのは我慢しましょう。チェックポイントに戻り、誤解された箇所 — たいていは明記されていない制約か欠けたオーナー — を中心にブリーフを締め直して再実行します。再試行のたびに、新しい緊急性ではなく新しい情報を載せるべきです。
失敗が続く場合、ブリーフがリポジトリに存在しないコンテキストを前提にしていることが多いです。エージェントがユーザーを保存する二番目の場所を発明し続けるなら、直すべきなのは口調ではなく、アイデンティティがどこに住んでいるかについての AGENTS.md の一文です。ドキュメントを更新してからタスクを再試行してください — このワークフローはキットのエージェントガイドにあります。
エージェントワークフローについてよくある質問
創業者が実際の製品作業をコーディングエージェントに任せ始めるとき、いつもいくつかの質問が出てきます。
- コーディングエージェントは SaaS 全体を一人で構築できますか？ — 見える部分はすぐ組み立てられますが、残る部分 — 認可、課金ライフサイクル、データ分離 — には依然としてブリーフとチェックとレビューが必要です。そのループのない速さはやり直しになります。
- コーディングエージェントへのタスクはどのくらいの大きさがよいですか？ — 数分以内に動作中のアプリで結果を確認できる程度です：ユーザーに見える成果 1 つ、所有モジュール 1 つ、受け入れチェック 1 つ。
- プロンプトに入れてはいけないものは？ — プロバイダーの秘密情報、セッション Cookie、
.env.localの中身、顧客データです。値をチャットログにコピーするのではなく、ファイル名を指定してツールにローカルで読ませます。 - エージェントが書いたコードでレビューの仕方は変わりますか？ — レビューは書くことから読むことへ移ります：差分を見て、重複したロジック、広すぎる例外処理、スタックがすでに処理している問題を解き直す依存を探します。
- エージェントの出力に最も重要なテストは？ — 所有権と失敗時の振る舞いを固定するものです：未認可リクエスト、無効な入力、繰り返し送信。デモが見せるハッピーパスだけではありません。