エージェントへの作業指示書を書く

レビューで評価できる変更を記述する

「顧客データのエクスポートを追加する」だけでは、複数の判断が未確定です。誰がレコードをエクスポートできますか？どのレコードとフィールドを含めますか？リクエストが失敗するとどうなりますか？エージェントは、それらをもっともらしい選択で補えます。しかし、その選択は業務に合っていない可能性があります。

まず利用者と問題を示します。次に必要な動作を記述します。結果が受入可能かどうかを示す証拠も含めてください。

作業指示書は、内部設計をすべて固定せずに、不確実性を減らすものです。必要なデータの範囲を指定します。変更する理由がなければ、リポジトリの既存パターンに沿って実装します。

具体例を使う

以下は、架空のサポート用アプリの作業指示書です。学習用の例であり、完全な本番用仕様ではありません。

成果: サポート部門のマネージャーが顧客リストをダウンロードできる。
実行者: 現在の組織のマネージャー。
データ: その組織の有効な顧客のみ。
フィールド: 顧客ID、会社名、アカウントの状態。
形式: ヘッダー行付きのUTF-8 CSV。
拒否されたリクエスト: 既存の認可エラーを返す。
結果が空の場合: ヘッダーだけを含む有効なCSVを返す。
対象範囲: 既存のエクスポートルートと監査パターンを使う。
対象外: 新しいロール、依存関係、デプロイは追加しない。
証拠: 許可、拒否、空の結果、組織をまたぐリクエストのテスト。

この指示書は、有用な動作と制限を示しています。同時に、追加の疑問も明らかにします。エクスポート量に上限を設けますか？フィールドに表計算の数式が入る可能性はありますか？監査記録には誰がアクセスできますか？影響の大きい疑問は実装前に解決してください。この例を万能のチェックリストとして扱わないでください。

要件と仮定を分ける

要件は、変更が満たすべき動作を示します。仮定は、まだ検証していない事実です。分けて扱ってください。

例えば「既存の監査パターンを使う」は、適切なパターンが存在すると仮定しています。エージェントに探すよう依頼します。リポジトリに存在しない場合は、新しい監査システムを作り始める前に、不足している依存要素を報告させます。

制約と成果が矛盾する場合もあります。既存のルートは、設計上すべての組織を返すかもしれません。エージェントは矛盾を示し、限定的な修正を提案すべきです。黙ってデータの範囲制限を取り除いたり、タスクをアーキテクチャ全体の書き直しに広げたりしてはいけません。

証拠を完了条件に含める

最終的な動作、範囲の変更、実施した確認を説明する作業結果の要約を求めます。重要な箇所では、正確なコマンドと結果を要求してください。合格した確認と、実行できなかった確認を区別します。

pull requestには、変更の理由を残します。後の保守担当者は、元の会話を知らずにコードを見るかもしれません。特定のフィールドをエクスポート対象から外す理由と、アクセス制御の実施方法が分かるだけの背景を含めます。

Googleの変更説明ガイドは、この記録の参考になります。何を変えるのかと、その目的を説明してください。レビューで変更した後も、記録を最終実装に合わせます。

タスクに合った詳しさにする

小さな文言の修正なら、短い作業指示書で十分です。データのエクスポートは、失敗すると情報が漏れるため、詳しい説明が必要です。新しい支払フローには、さらに分析とレビューが必要です。

長さで作業指示書の質を測らないでください。適切な知識を持つレビュー担当者が、正しい結果と誤った結果を区別できるかを考えます。妥当な二つの実装でも、影響の大きい動作が異なるなら、まずその動作を明確にしてください。