Tutorial 4 Prompting and Reviewing ja

チュートリアル4 · プロンプトとレビュー

ゴール: メタスキルの習得。エージェントと機能を作れるようになった今、 それをなめらかに、繰り返しできるようにします。一発で意図が伝わるプロンプトの書き方、 効率のよい差分レビュー、うまくいかないときの立て直し、そしてセッションをまたいで 勢いを保つ方法を扱います。

← 前へ: チュートリアル3 はじめてのエージェントタスク · 次へ: チュートリアル5 多言語対応

---

検索窓ではなく、リードとして指示する

エージェントは、速くて、言葉どおりに受け取る、意欲的な若手エンジニアだと思って ください。優秀な若手を導くのと同じやり方が効きます。

• ゴールと制約を「両方」伝える。「endorse を追加して」は弱い指示です。 「connect のパターンに従って endorse を追加。乱数はシード付きのみ、テスト付き、 ゲートは緑のまま」は強い指示です。周囲になじむコードが出てくるかどうかは、 制約を書いたかどうかで決まります。
• お手本を指し示す。「renderConnect と同じパターンで」の一言は、長い説明文に 勝ります。既存のコードは最良の仕様書です。
• 自明でない作業では、編集の前に計画を出させる。 計画の軌道修正は安上がりですが、 10ファイル編集済みの状態を巻き戻すのは高くつきます。
• 1プロンプト1タスク。「endorseを追加、ついでに乱数まわりをリファクタ、 READMEも更新」とまとめて頼むと、レビュー困難な絡まった差分ができあがります。
• テストゲートを渡す。「npm test を実行し、緑になるまで完了と見なさないこと」 と言い添えるだけで、エージェントは自分の仕事を自分で検証するようになります。

差分は毎回レビューする

エージェントの価値は速さです。しかし読まれていない速さは、そのままバグの出荷に つながります。短くて一貫したレビューの型を持ちましょう。

1. 範囲: 変えるべきものだけを変えているか？ 無関係な行の移動は危険信号です。
2. パターン: 周囲のコードと揃っているか？ 依存の追加や、src/ 内でのI/Oは ないか？
3. このプロジェクトのルール: ここではシード付き乱数のみ（差分から Math.random を検索）、ユーザーに見える文字列は言語バンドルに置く （ハードコードしない）、カードの行はレイアウトの幅を超えないの3点です。
4. アクセシビリティ: 新しい出力は --accessible に耐えますか？ lockedin --accessible <your command> を実行し、きれいなプレーンテキストとして 読めるか——a11yFilter をすり抜けた装飾記号が紛れていないか——を確認します。
5. テスト: 新しいテストはあるか？ そしてその機能が壊れたとき、本当に落ちるか？ 「このテストを失敗させるには、どの行を変えればいいですか？」 と聞いてみましょう。
6. 実行する: npm test を回し、そのうえで実際にコマンドを実行して出力を見ます。

一文字残らず理解する必要はありませんが、すべての判断は理解している必要があります。 自分で説明できない変更があるなら、受け入れる前にエージェントに説明させてください。

緑にならないときの立て直し

ゲートが赤いのは、失敗ではなく普通の一工程です。効くのは、正確なフィードバックです。

「npm test が次のエラーで失敗します：[paste the exact error]。renderEndorse の 幅のテストは、カードの各行が表示幅60カラム以下であることを期待しています。 テストを弱めずに修正してください。」

実際のエラーテキストを貼るのが肝心です。「壊れています」だけではエージェントは 推測するしかありませんが、スタックトレースがあれば直せます。また、 新しい会話を始めるより同じ会話を続けるほうが有利です。エージェントは自分が たった今書いたものの文脈を持っているからです。2〜3回やり取りしても収束しないときは、 いったん引いて範囲を切り直しましょう。1つのプロンプトに対してタスクが大きすぎる サインです。

セッションをまたいで勢いを保つ

現実の作業は一度の作業時間では終わりません。エージェントを長期的に活かすには、 次の2つの習慣が効きます。

• メモリ / 規約ファイル。 永続メモリやプロジェクト指示ファイルに対応した エージェントなら、常に守ってほしいルールをそこに記録します（例: 「乱数はすべて pick/shuffle を使う」「完了を宣言する前に npm test を実行する」）。 毎回プロンプトに書く代わりに、一度書けば済みます。
• 引き継ぎメモ。 このリポジトリでは、機微な情報を除いた短い状況メモを docs/HANDOFF.md に置いています。何のプロジェクトで、どう作られ、どうテストされ、次に何をするのか。 作業に戻ってきたとき（あるいは同僚や別のエージェントに引き継ぐとき）、 このメモが数秒で文脈を復元してくれます。変更作業の一部として、 エージェントに最新化させるとよいでしょう。

守る価値のあるガードレール

• ゲートは交渉不可。 何かを出す前に、テストは緑。これがあるからこそ、 速く動きながら出力を信頼できます。
• 最終的なレビュー責任者はあなた。 書くのはエージェント、決めるのはあなたです。 差分を受け入れるとは、その内容を保証するということです。
• 小さく検証可能な一歩が、大きな一足飛びに勝ります。受け入れた変更のたびに、 アプリは動いている状態であるべきです。

---

✅ エージェントと試してみよう

1. mentor コマンド（「頼まれてもいない助言を授ける」）の仕様を、制約込みで 1段落書いてください。そのうえで、計画 → テスト → 実装 → ゲートの順に、 各ステップでレビューしながらテストファーストで作らせます。
2. docs/HANDOFF.md を更新させ、新しいコマンドについて追記させてください。
3. わざと何かを壊し（例: プールの要素を1つ削除）、npm test を実行して、 失敗内容を正確にエージェントへ伝えて直させる練習をしましょう。

---

次に進むなら

• src/lockedin.js の実物のコードを眺めてみてください。もう全体の形は頭に 入っているはずです。
• docs/HANDOFF.md で、プロジェクト自身の状況メモと設計メモを読んでみましょう。
• コマンドリファレンス のジョークも楽しんでください。

以上でチュートリアルは終わりです。あなたはもう、AIエージェントに指示して、 テストゲートの内側で本物のソフトウェアを作り、変更できます。 ——このうえなく自信過剰な題材を使って。同意する人は👇