AIタスクパケット:よりよい指示と受け入れ基準

Table of Contents
よい指示は、作業内容と評価方法を説明します。 文章を増やしても、範囲の不足は解消しません。このレッスンでは、曖昧な依頼を講座の演習用タスクパケットに変えます。
学習目標: 情報源、対象ファイル、確認項目、停止条件を定めたタスクパケットを書きます。
要点
- 成果 は、求める成果物や動作を示します。
- 範囲 は、変更を許可するファイルと除外する操作を示します。
- 情報源 は、承認済みの要件を特定します。
- 受け入れ基準 は、成功を観察可能にします。
- 停止条件 は、推測や未承認の追加作業を防ぎます。
始める前に
前提条件: 展開済みの演習資料、その中の docs/requirements.md、
リポジトリコンテキストのレッスン
です。30分を確保してください。難易度は初級です。この演習では、書面のパケットを作成します。まだコードを編集する必要はありません。
2つの依頼を比べる
曖昧な依頼:「タスクスクリプトを改善してください。」エージェントは出力を書き換えたり、依存関係を追加したり、サンプルデータを編集したり、テストを省略したりするかもしれません。依頼では、どの選択も決まっていません。
範囲を定めた依頼:「task_report.py に任意指定の状態フィルターを追加してください。docs/requirements.md の改訂1に従います。既定の出力を維持してください。テストを追加してください。サンプルデータは変更しないでください。コミット前に停止してください。」実装の詳細はエージェントが選びますが、タスクによって成功の条件は定まります。
| パケットの項目 | 演習例 | 確認方法 |
|---|---|---|
| 成果 | レポートに --status を追加 | 許可された2つの値が動作する |
| 情報源 | docs/requirements.md、改訂1 | コードが承認済みの値に一致する |
| 範囲 | プログラムとテストのみ | diff に他のファイルが含まれない |
| 制約 | 既定の出力とサンプルデータを維持 | 基準出力が Total tasks: 4 のまま |
| 証拠 | テストコマンドと手動実行 | 出力が期待する件数に一致する |
| 停止 | コミットもプッシュもしない | Git履歴とリモートに変更がない |
再利用できるテンプレートを使う
小規模なコーディングや調査タスクには、このテンプレートをコピーしてください。 曖昧な文章で埋めるのではなく、関係のない項目を削除します。
Outcome:
Authoritative source and revision:
Relevant files or records:
Allowed changes:
Excluded changes and actions:
Examples of desired behavior:
Completion checks:
Stop or ask when:
Report back with:
演習用の完成例:
Outcome: Add an optional --status filter to task_report.py.
Source: docs/requirements.md, revision 1.
Relevant files: task_report.py, tasks.json, tests/.
Allowed changes: task_report.py and focused tests.
Excluded: tasks.json, new dependencies, commits, pushes.
Examples: no filter prints Total tasks: 4. Open and done each print 2.
Checks: run unit tests and four manual commands: no filter, open, done, and invalid.
The invalid value must exit nonzero with a clear error.
Stop or ask: source conflict, missing file, unrelated failing baseline.
Report: changed files, commands, observed outputs, unresolved issues.
**Windowsでは、**環境でPythonランチャーを使う場合、パケット内のコマンドには py -3 を使います。
パケットは、すべてのコード行を指示しません。 結果を検証できる状態に保ちつつ、エージェントに小規模な実装を選ばせます。
例を慎重に加える
正確な例は曖昧さを減らします。 open と done の例は、提示された4件のタスクを含むファイルでの出力を示します。どのファイルにも当てはまる一般規則ではありません。別のファイルでは、件数はそのレコードに左右されます。
期待値と観察結果を分けます。 プログラムの実行前は、各状態の期待値が Total tasks: 2 です。実行後のターミナル出力は観察結果です。値が異なる場合は、成功を報告する前にデータと実装を調べます。
停止条件を決める
要件ファイルが見つからない場合を考えます。 パケットでは、そのファイルを承認済みの情報源に指定しています。古いチャットやサンプルの課題から許可値を推測せず、作業を止めて要件を確認します。
編集前に基準テストが失敗する場合を考えます。 失敗を記録し、まず初期状態を直すべきか確認します。後の実行が成功しても、差異の原因がフィルターなのか初期状態なのかは特定できません。
エージェントがコミットしようとする場合を考えます。 パケットではコミットを除外しています。diff とテストの後で停止するよう伝えます。その後のコミットがプロジェクトの手順に合うかどうかは、あなたが決めます。
パケットを確認する
各項目に1点を付けます。 成果は具体的ですか。根拠となる情報源を記載していますか。対象ファイルは明確ですか。観察可能な確認項目が2つ以上ありますか。停止条件がありますか。5点未満なら、エージェントに渡す前にパケットを見直してください。
成果物: 最終タスクパケットと、停止条件を説明する一文を保存します。次の実践レッスンでコーディングエージェントに渡すか、学習ルートで期待結果を手動で回答します。
理解度を確認する
- 質問: タスクパケットを検証可能にする要素は何ですか。回答: 情報源、許可ファイル、観察可能な確認項目、停止条件です。
- 質問: 情報源に必要な詳細がない場合、エージェントはどうするべきですか。回答: 作り上げずに停止し、不足する詳細を報告します。
トラブルシューティング
- エージェントが変更しすぎる: パケットに対象ファイルと除外する操作を記載します。
- エージェントが何度も質問する: 不足している情報源または具体例を提示します。
- エージェントが早く成功を宣言する: コマンドの実際の出力を求め、ファイルを確認します。
- パケットが長くなりすぎる: コピーした情報源の文章をパスと改訂番号に置き換えます。
次のステップ
初めてのコーディングエージェントタスク に進みましょう。 パケットを使い、演習で小さな編集を行います。
講座ナビゲーション: 前へ:リポジトリコンテキスト 、 講座の概要 。


