「プロンプトを書くClaude」と「実装するClaude」を分けたら開発が回り始めた話

はじめに

ここ1か月ほど、業務の開発をほぼ Claude Code（デスクトップアプリ） で進めています。
この記事では、実際にどのように Claude を使っていたのかを振り返りながら、うまくいったやり方をまとめます。

この1か月で Claude と一緒にやったことは、ざっくりこんな感じです。

全体の流れ

まずは全体像です。1画面を実装するときは、だいたいこの流れで進めています。

ここからは、ステップごとに意識していることを書いていきます。

1. プロンプトを作るセッションと、実装するセッションを分ける

一番効果があったのがこれです。

画面を作るとき、手元にあるのは「画面イメージ（キャプチャ）」と「画面項目の一覧」、それに要件定義書です。

これをいきなり実装リポジトリに渡して「この画面を作って」と頼むと、仕様を読み解く作業と実装作業が1つのセッションに混ざります。その結果、コンテキストがすぐに埋まってしまいました。

家づくりに例えると、設計士が図面を描きながら、同時に大工としてトンカチも振っているような状態です。
そこで役割を分けました。

• セッション①（設計士）：要件定義書が置いてあるドキュメントリポジトリで、「実装の指示書（プロンプト）」を書く
• セッション②（大工）：実装リポジトリで、その指示書どおりに作る

セッション①には、まずこう頼みます。

項目、貼付した画面からエージェントに画面を実装するプロンプトを作成してください
mdファイルではなくコードブロックに記載お願いします。

Claude は要件定義書・画面一覧・画面遷移図・DB スキーマなどを読み、別のコーディングエージェントにそのまま渡せる実装プロンプトを書いてくれます。
それをコピーして、実装リポジトリの新しいセッションに貼り付ければ準備完了です。

分けて良かったのは、こんな点です。

• 実装セッションは仕様が整理された状態から始まるので、余計な調査をしない
• 実装の前に、プロンプトを人間がレビューできる（仕様の勘違いにここで気づける）
• プロンプトが手元に残るので、似た画面を作るときの参考資料になる（例：「延滞料金の計算式は『貸出台帳』の実装プロンプトを参照」）

2. 実装プロンプトはテンプレート化する

何画面か作るうちに、実装プロンプトの構成が固まってきました。だいたい毎回この形です。

# 実装プロンプト：〇〇（画面ID 画面名）

## 依頼
何をする画面か。どんな業務で使うか。

## 作業の進め方
1. 着手前に実装先リポジトリを調べ、技術スタック・ディレクトリ構成・
   共通コンポーネント・API の書き方を把握すること。
   新しいライブラリは、既存のもので実現できない場合に限って追加する。
2. 似た画面（例：他の検索ポップアップ）が既にあれば、その作りに合わせる。
   同じロジックがあれば共通化して使い、二重に実装しない。
3. テーブルや API が無い場合は、作る前に「どこに何を追加するか」を一覧にして報告する。
4. 「要確認事項」に当たる箇所は勝手に仕様を決めない。
   暫定で実装する場合は `TODO(要確認):` を残し、完了報告に一覧で載せる。
5. 計算ロジックや絞り込み条件には単体テストを付ける。

## 参照資料
- 要件定義/〇〇_機能要件.md：該当する章
- 要件定義/〇〇_画面遷移図.drawio：遷移元 → この画面
- database/〇〇.sql：使うテーブル

## 画面レイアウト
（罫線で描いた画面のラフ）

## 画面項目
| No | 項目名 | 種類 | 配置 | 動作 |

## 動作仕様 / 入力チェック / キーボード操作

## 要確認事項
仕様書からは決めきれないこと

## 受入条件

大事なのは 「作業の進め方」 です。ここに並んでいるのは、どれも一度失敗してから足したルールです。

• 既存の流儀に合わせる：何も言わないと、新しいライブラリや独自の書き方を持ち込まれがち
• 共通化する：たとえば「貸出台帳」と「延滞一覧」は延滞料金の計算元が同じなので、「貸出台帳の処理を流用し、ロジックを重複させない」と書いておく
• 追加するものは先に一覧で確認：API やテーブルを勝手に増やされるのを防ぐ

画面レイアウトは、画面イメージを見ながら罫線で描いたラフも入れています。画像だけで伝えるより、配置の指示がぶれにくくなりました。

┌ 利用者選択 ─────────────────────────────┐
│ [利用者検索            ] ← 黄色背景      [閉じる] │
│  コード [        ]  氏名 [                ]      │
│ ┌──────────────────────────────┐ │
│ │利用者コード│氏名            │区分          │ │
│ │ ...                                          │ │
│ └──────────────────────────────┘ │
│ [決定]                                           │
└──────────────────────────────────┘

3. 「推測させない」をルールにする

業務システムで一番怖いのは、それっぽく推測で作られてしまうことです。
たとえば「延滞料金は1日いくら？」「休館日は延滞日数に含める？」といったルールを AI が勝手に決めると、見た目は動いていても中身が間違ったシステムになります。

そこで、どのプロンプトにも次の指示を入れています。

• 不明な業務ルールは推測しない
• 実装・要件定義書・テストが食い違っていたら、独自に正しい仕様を決めない
• わからないことは、成果物とは別に記録する
  • 実装なら → コードに TODO(要確認): を残し、完了報告に一覧で載せる
  • ドキュメントなら → 確認事項.md に参照元つきでまとめる

こうしておくと、Claude の完了報告がそのまま**「お客さんや有識者に確認することリスト」**になります。
人間は確認して答えをもらい、「Q2 の検索について、検索ボタンを付けてください」のように一言返すだけで済みます。

4. 「モックを起動して」で、すぐ画面を見る

実装が終わったら、毎回まずこう言います。

画面を確認したいので動かしてください

フロントエンドは Vite + MSW（Mock Service Worker） で作っているので、バックエンドが無くてもモック API で画面が動きます。
Claude Code デスクトップアプリでは、.claude/launch.json に起動設定を書いておくと、Claude が dev サーバーを起動してアプリ内のブラウザで画面を開いてくれます。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "mock-dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    }
  ]
}

画面を触って気になったところは、そのままチャットで伝えます。たとえばこんな感じです。

• 「貸出明細・貸出台帳・延滞一覧の画面で、閉じるや戻るを押したらメニュー画面に戻るようにしてください」
• 「目次が2つ表示されているので、2つ目を削除してください」
• 「ヘルプのリンクを押しても画面が切り替わりません」

コードを読むより先に画面で確かめる。このサイクルを短く回すことが、一番の時短になっています。

5. ドキュメント作りもテンプレートで横展開

画面の実装だけでなく、一般利用者向けのヘルプ（操作マニュアル） も Claude に作ってもらいました。
5つのリポジトリで同じことをする必要があったので、ここでもプロンプトをテンプレート化して使い回しています。

ヘルプは 2段階 に分けて作ります。

一度に全部やらせると、照合とスクショ撮影まで手が回らなくなるので分けました。

プロンプトには「読者」「書き方」「スクリーンショット」のルールを細かく書いています。一部を抜粋します。

システムに詳しくない一般利用者向けに、画面のヘルプ（操作マニュアル）をMarkdownで作成してください。

■ 読者と文章の方針
- このシステムを初めて使う人を想定してください。
- 専門用語や開発者向けの説明を避け、短く具体的な言葉で説明してください。
- ボタン名・画面名・入力項目名は、実際の画面の表示に合わせてください。
- 操作手順は番号付きで、1つの手順につき1つの操作を基本にしてください。

■ 記載内容
1. この画面でできること
2. 利用できる人・操作前に必要な準備
3. 画面の開き方
4. 基本的な操作手順
5. 入力項目の説明（必須・任意、入力例、入力上の制約）
6. 注意事項（保存、取消、削除の影響など）
7. 困ったときの対処方法

実装や資料で確認できない機能・制約・対処方法は追加しないでください。
未実装の機能を、利用できる機能として説明しないでください。

■ 作成先・変更範囲
- help フォルダ以外のファイルは変更しないでください。
- 画面へのヘルプボタン追加やルーティング変更は行わないでください。

■ 完了時の報告
作成したファイル、対象にした画面、参照できなかった資料、主な確認事項を簡潔に報告してください。

■ スクリーンショット
- 開発・テスト環境の実際の画面を撮影してください。画面画像を推測で生成しないでください。
- テスト用の架空データを使用し、個人情報・機密情報・認証情報を写さないでください。
- 操作箇所を強調する場合は、表示内容を変えず、枠や番号を重ねてください。
- 起動・ログイン・データ準備などの不足で撮影できない場合は、
  画像を捏造せず、必要な準備を報告してください。

特に効いたのは 「変更範囲」 と 「画像を捏造しない」 の2つです。
Claude はモックで画面を起動し、ブラウザを操作してスクリーンショットを撮り、赤枠や番号を重ねたうえで HTML に埋め込んでくれました。

6. レガシーコードの単体テストも任せる

Web だけでなく、.NET Framework 4.8 の WPF アプリの単体テストも Claude に書いてもらっています。

ここでも「プロンプトを作るセッション → 実行するセッション」の分け方が効きました。
まず、テスト対象のプロジェクト・共通の手順書（AGENTS.md）・社内のモックライブラリのドキュメントを渡して、テスト作成用のプロンプトを作ってもらいます。
できあがったプロンプトには、次のような内容が入っていました。

• 最初に読む資料（共通手順書、モックライブラリの README、使い方の実例）
• 参考にする既存のテストプロジェクト（ただし真似してはいけない点も明記）
• テスト対象のクラス一覧と、確認済みの事実
• coverlet でカバレッジを測り、HTML レポートを出すこと

テストができたら、あとはカバレッジを見ながら関数単位で指示します（関数名は例です）。

今の全体のカバレッジが63%なのでもう少しカバレッジをあげてください

UpdateLoanList() のカバレッジ率が25.97%なので、ここのカバレッジをあげてください

SaveCategory() / MoveUp() / MoveDown() のカバレッジ率をあげてください。
その後 coverage.cobertura.xml と index.html を今のカバレッジで出力して

「全体を上げて」と頼むより、レポートを見てカバレッジの低い関数を名指しするほうが、狙いどおりに上がりました。

7. Git 操作は「小さく push、まとめて PR」

Git 操作もほぼ Claude にお願いしています。よく使う言い方はこの2つです。

コミットしてpushしてください。PRはまだ出さなくていいです。

mainブランチにPRを出してください
日本語でissue-XXの作業内容を記載してください

区切りのいいところで「コミットして push。PR はまだ」を何度も繰り返し、まとまったら Issue 番号を伝えて PR を出してもらいます。
コミットメッセージや PR の説明を日本語で書いてもらうのは、チームのメンバーが読みやすいようにするためです。

8. CLAUDE.md と AGENTS.md の使い分け

各リポジトリには CLAUDE.md と AGENTS.md を置いています。

• AGENTS.md：プロジェクトのルール本体（技術スタック、ディレクトリ構成、「指示なく新規ライブラリを追加しない」など）
• CLAUDE.md：Claude 向けの入口。@AGENTS.md でルール本体を読み込ませたうえで、アプリの種類によって読ませるドキュメントを切り替えています

# 共通設定

最初に `APPLICATION.md` のアプリ種別を確認する。

- `with-login`：ログイン画面を持つアプリ用のドキュメントを適用する
- `no-login`：ログイン画面を持たないアプリ用のドキュメントを適用する
- 種別が未記載・不正な場合は、認証まわりの実装を始めない

@AGENTS.md
@APPLICATION.md

AGENTS.md の先頭には「このファイルは指示なく修正しないこと。改善案は提示してよい」と書いてあります。
ルールファイルそのものを勝手に書き換えられないようにするための一文です。

うまくいかなかったこと・学び

いいことばかりではなかったので、失敗談も残しておきます。

大きすぎるタスクは、コンテキストが溢れる

26画面分のヘルプを1つのセッションでまとめて作らせたときは、会話の自動要約（コンパクション）が何度も起きました。並列のサブエージェントも使ってくれましたが、途中で何をしていたのか追いにくくなりました。
→ 「Markdown 作成」と「HTML 化」を分ける、画面のまとまりごとにセッションを分けるようにしました。

変更範囲を書かないと、関係ないファイルまで直される

一度、4つのファイルに数千行の変更が入ってしまい、取り消してもらったことがあります。
→ それ以来、プロンプトには必ず「〇〇以外のファイルは変更しないでください」と書いています。

テンプレートを使い回すと、書き換え漏れが起きる

テンプレートは便利ですが、別のリポジトリにコピーしたときに参照資料のパスや作成先を書き換え忘れることがありました。
Claude は書かれたとおりに動くので、ここは人間がチェックするしかありません。
→ 変わる部分（リポジトリ名・作成先・参照資料）を、テンプレートの先頭にまとめておくと安全です。

dev サーバーが起動しないときは、まずエラーを渡す

vite が見つからない、ヘルプに遷移しない、通信エラーになる、といったことはよく起きます。
エラーメッセージや画面の状態をそのまま貼って「直して」と言えば、たいてい解決してくれます。

まとめ

この1か月で効いたことを、もう一度並べます。

1. プロンプトを作るセッションと、実装するセッションを分ける
2. 実装プロンプトをテンプレート化する（既存に合わせる／共通化する／追加は先に確認）
3. 推測させない。不明点は TODO(要確認): や 確認事項.md に残させる
4. 「モックを起動して」 ですぐ画面を見て、チャットで直す
5. 小さく push、まとめて PR

AI に任せる範囲が広がった分、人間の仕事は 「何を作るかを正しく伝えること」 と 「できたものを確かめること」 に寄ってきたと感じます。
プロンプトを丁寧に書くことは仕様を整理し直すことでもあるので、結果的に自分の設計への理解も深まりました。

同じように Claude Code を業務で使っている方の参考になればうれしいです。
最後まで読んでいただき、ありがとうございました！