#07 AIに実装させるときの「完了メッセージフォーマット」設計で学習効率が上がった話

はじめに

Claude Codeに実装を依頼すると、完了後にこんなメッセージが返ってきます。

Step 4 完了です。
実施内容まとめ
body_parts.py は実装済みでした。
テスト実行で以下の不具合を発見・修正しました。
完了条件チェック
✅ pytest tests/test_body_parts.py -v — 5/5 passed

「何を実装したか」は分かります。でも 「なぜその実装方法なのか」「実装後にどう動作するのか」が分からない。

テストが通ったことは確認できますが、コードの中身を理解できていない——これが問題でした。

これは多くのClaude Code活用者が直面する問題だと思います。AIが書いたコードは動きますが、「動く」と「理解している」は別物です。

この記事では、完了メッセージを「学習に使えるフォーマット」に変えることで、この問題を解決した方法を紹介します。

デフォルトの完了メッセージの問題点

初学者の立場で完了メッセージに欲しい情報は何かを考えると、こうなります。

1. 今回実装した内容（概要）
2. なぜその実装方法なのか（設計の意図）
3. 変更・作成したファイルと役割
4. 実装後にどう動作するのか（ユーザー視点）
5. 発生した問題と解決策
6. 初学者向け補足（用語解説）
7. 次のステップ

デフォルトは「1」と「5」しかカバーしていません。

AGENTS.mdに完了メッセージフォーマットを追加する

AGENTS.mdに以下のセクションを追加しました。

## 完了メッセージのフォーマット

各Stepの実装が完了したら、**必ず以下のフォーマットで報告**してください。
**7項目すべてを埋めること。項目の省略禁止。**

**1. 今回実装した内容**
（専門用語には括弧で補足を付ける）

**2. なぜこの実装方法なのか**
（設計の意図・選択理由を初学者向けに説明する）

**3. 変更・作成したファイルと役割**
| ファイル | 役割 |
|---|---|

**4. 実装後にどう動作するのか**
（ユーザー視点で番号付きで説明する）

**5. 発生した問題と解決策**（エラーがあった場合のみ）

**6. 初学者向け補足**
- 【用語名】説明

**7. 次のステップ**

フォーマットを守らせるための工夫

最初はAGENTS.mdにフォーマットを書くだけでは守られませんでした。

実際に起きた失敗を正直に書きます。Step 5の実装が終わったとき、Claude Codeは旧フォーマット（「何を実装したか」だけ）のまま返してきました。AGENTS.mdはちゃんと更新していたのに、です。

原因は指示文に明示がなかったことでした。AGENTS.mdを更新しても、指示文の中に「7項目すべてを埋めること。省略禁止」という一文がなければ、Claude Codeはフォーマットを無視して以前の形式で返してくることがあります。

解決策は 指示文にも明示的に書くこと です。

実装完了後はAGENTS.mdの【完了メッセージのフォーマット】セクションを参照し、
7項目すべてを埋めて報告してください。項目を省略しないでください。

ポイントは3つです。

• 必ず をつけて強調する
• 【完了メッセージのフォーマット】 とセクション名を明示する
• 7項目すべて 省略しないで と具体的に指定する

AIは指示された通りにしか動きません。曖昧な指示は曖昧な出力につながります。 これはソフトウェアテストでいう「テスト仕様の明確化」と同じ考え方です。仕様書に書いてあっても、担当者への周知が曖昧なら漏れが起きる——それと全く同じです。

フォーマット変更後の完了メッセージ（抜粋）

## ✅ Step 4 完了レポート

### 1. 今回実装した内容
- 部位マスタのCRUD APIを実装した
  → CRUD = Create（作成）/Read（取得）/Update（更新）/Delete（削除）の略

### 2. なぜこの実装方法なのか
- 削除時に紐づくメニューを確認してから削除する設計にした
  → 理由：部位を削除するとメニュー（ベンチプレス等）が孤立してしまうため
  → 紐づきがある場合は 400 PART_HAS_MENUS を返して削除を拒否する

### 3. 変更・作成したファイルと役割
| ファイル | 役割 |
|---|---|
| backend/routers/body_parts.py | 部位マスタのAPIエンドポイント定義 |
| backend/schemas/body_part.py | リクエスト/レスポンスの型定義 |

### 4. 実装後にどう動作するのか
1. ユーザーがマスタ管理画面で「胸」を入力して追加ボタンを押す
2. POST /api/body-parts にリクエストが送られる
3. 同名の部位が存在するか確認する（重複なら409エラー）
4. 問題なければDBに保存して201で返す

### 6. 初学者向け補足
- 【409 Conflict】「競合」を意味するHTTPステータスコード。
  今回は「同じ部位名がすでに登録されている」ときに返す。

この変更の効果

「なぜ」が分かるようになった

「削除時に紐づきチェックをする理由」を説明してもらうことで、ただ動くだけでなく
「なぜそういう設計なのか」 が理解できるようになりました。

用語が自然に身につく

「CRUD」「409 Conflict」「CASCADE削除」——毎回の補足説明で、コードを読む中で自然に用語が身についていきました。

問題の切り分けが上手くなった

「発生した問題と解決策」を毎回記録することで、「このエラーはどのレイヤーで起きたのか」を考えるクセがつきました。「routers/の問題か、services/の問題か」を分けて考える習慣は、テスト設計でいう「バグの影響範囲を整理する」感覚と同じです。テスター経験がここでも活きました。

まとめ

• デフォルトの完了メッセージは「何をしたか」しかカバーしない
• 7項目フォーマットに変えることで「なぜ・どう動くか・用語説明」まで得られる
• フォーマットはAGENTS.mdに定義するだけでなく、指示文にも毎回明示する
• AGENTS.mdを更新しても指示文に書かなければ守られないことがある
• 「AIは指示された通りにしか動かない」——これはテスト仕様の明確化と同じ考え方

次回（#08）は、AIが書いたコードを「自分のもの」にするための具体的な方法——コメントルールとExcel解説書の活用——を書きます。

このシリーズの一覧は#0 総論記事からご覧ください。