Zenn
🤖

プロンプトコーディングのススメ：AIとの対話に秩序をもたらし、開発を加速する新手法

に公開
生成 AI
tech

はじめに：生成AIとの対話における「絶望」と「希望」

近年、エージェント型生成AI、特にコーディング支援を行うAIエージェントの進化は目覚ましく、多くのエンジニアがその可能性に大きな期待を寄せています。単純なコード補完から、複雑な機能実装、テストコード生成、リファクタリングに至るまで、AIは開発プロセスを劇的に変える可能性を秘めているからです。

しかし、その一方で、AIエージェントを意のままに操ることの難しさに直面し、深い「絶望」を味わった経験を持つエンジニアも少なくないのではないでしょうか。

意気揚々とAIに作業を依頼したものの、生成されるのは大量の、意味があるのかわからない、そして何より動かないコードの山。あるいは、最初は順調に見えた対話が、いつの間にか迷走し、AIがこちらの意図を全く汲み取ってくれなくなる。「AIにはしごを外された」と感じるあの瞬間。暗中模索、五里霧中、孤立無援――。期待が大きかった分、その落差による徒労感や失望感は、決して好ましいものではありません。

私も、そんなAIとの対話に翻弄され、絶望感を味わったエンジニアの一人です。チャットインターフェースでの対話は、その場限りで揮発性が高く、うまくいったときの指示を再現するのも、失敗の原因を特定するのも困難でした。このままでは、AIの真の力を引き出すことはできないのではないか――。

そんな試行錯誤と苦い経験の中から生まれたのが、本稿で紹介する「プロンプトコーディング」という手法です。これは、AIとの対話をより構造化し、試行錯誤のプロセスを「記録」として残すことで、AIとの協働をより確実で、再現性の高いものにするためのアプローチです。プロンプトコーディングは、AIとの対話における混乱と絶望を減らし、エンジニアがAIの力を最大限に引き出し、開発プロセスを前進させるための「希望」となることを目指しています。

本稿では、プロンプトコーディングの具体的な手法とその背後にある考え方を解説し、エンジニアの皆さんがAIとのより建設的な関係を築くための一助となることを願っています。

プロンプトコーディングとは何か？

プロンプトコーディングとは、AIに依頼したい作業内容、手順、守るべきルール、そして作業の進捗状況を、特定のフォーマットに従ってファイルに記述し、そのファイルを介してAIエージェントと対話する手法です。

従来のチャット形式の対話では、プロンプト（指示）とその結果は時系列に流れていってしまい、後から見返すのが困難でした。特に複雑な作業を依頼する場合、何度も指示を修正したり、前提条件を再確認したりするうちに、対話の全体像を見失いがちです。うまくいったとしても、その成功体験を別の作業に活かすためには、記憶を頼りに過去の対話を遡るしかありませんでした。

プロンプトコーディングは、この問題を解決するために、AIとの対話の中心に「ファイル」を置きます。このファイル（後述するWORK_{作業内容}.md）は、単なる指示書ではなく、AIとの「契約書」であり、「作業指示書」であり、そして「進捗管理表」でもあるのです。

プロンプトコーディングの主な目的と利点:

  1. 再現性の向上: うまくいった指示や作業手順がファイルに明確に記録されるため、同様の作業を再度依頼する際に、そのファイルをテンプレートとして利用できます。これにより、毎回ゼロからプロンプトを考える手間が省け、成功体験を容易に再現できます。
  2. 試行錯誤の可視化とノウハウの蓄積: AIが指示通りに動かなかった場合、どの指示が悪かったのか、どのような制約を追加すべきかをファイル上で検討し、修正を加えることができます。この修正プロセス自体が、AIをうまく使うためのノウハウとしてファイルに蓄積されていきます。失敗経験もまた、貴重な学びとして記録されるのです。
  3. 作業の確実な前進: AIに一度に大きな作業を丸投げするのではなく、ファイルを介して作業を細かいステップに分割し、一つ一つのステップの完了を確認しながら進めることができます。これにより、AIが途中で迷走したり、タスク全体を完了できなかったりするリスクを低減し、着実に作業を前進させることが可能になります。
  4. AIへの指示の明確化: ファイルという形式で指示を構造化することで、曖昧さを減らし、AIが理解しやすい形で要求を伝えることができます。特に、「作業一覧表」を用いてタスクを具体的にリストアップすることで、AIの「見落とし」や「解釈違い」を防ぐ効果が期待できます。
  5. チーム内でのノウハウ共有: プロジェクト内でWORK_{作業内容}.mdファイルのフォーマットを統一し、.workingのような専用ディレクトリに蓄積していくことで、個人の試行錯誤の結果がチーム全体のAI活用ノウハウ資産となります。他のメンバーが類似のタスクを行う際に、過去のファイルを参考にすることで、効率的に作業を進めることができます。

プロンプトコーディングは、揮発性の高い口頭での指示やチャットでの対話を、永続的で再利用可能な「コード（ここでは手順やルールを記述したファイル）」として扱うことから、その名が付けられました。AIとの対話を「コーディング」のように捉え、体系化・構造化していくアプローチなのです。

プロンプトコーディングの実践：WORK_{作業内容}.md の設計

プロンプトコーディングの中核をなすのが、WORK_{作業内容}.md というMarkdownファイルです。このファイルは、AIへの指示、作業の進捗管理、そして試行錯誤の記録という複数の役割を担います。

ファイル命名規則と配置場所

AIとの作業記録を一元管理し、後から参照しやすくするために、ファイル名と配置場所には一定のルールを設けることを推奨します。

  • 配置場所: プロジェクトのルートディレクトリなどに .working というディレクトリを作成し、その中に WORK_*.md ファイルを格納します。これにより、プロジェクトのソースコードとは区別しつつ、関連する作業記録として管理できます。
  • ファイル名: WORK_{作業内容}.md という形式を基本とします。{作業内容} の部分には、そのファイルが何の作業に関するものかを具体的に記述します。さらに、一意性や検索性を高めるために、日付や関連するチケット番号（Issue ID）などをアンダーバー区切りで含めるのが効果的です。
    • 例: WORK_20250429_ISSUE-123_Refactor_User_Authentication_Module.md
    • 例: WORK_20250501_Add_Unit_Tests_for_Payment_Service.md

プロジェクト内でこの命名規則を統一することで、.working ディレクトリが自然とプロジェクトにおけるAI活用のノウハウデータベースとして機能するようになります。

WORK_{作業内容}.md の構成要素

WORK_{作業内容}.md ファイルは、主に以下の4つのセクションで構成されます。セクションは「依頼作業」「作業後の確認事項」「注意事項」「作業一覧表」です。

# WORK_{作業内容}.md

## 依頼作業

ここにAIに実行してほしい作業の全体的な指示を記述します。
特に重要なのは、以下の定型文を含めることです。

**「作業一覧を一行つづ上から作業を行う。一行の作業が完了したら、作業一覧の「作業完了」「完了ステータス」「コメント」に追記を行う。追記が完了したらもう一度このファイルを読み直し、次の作業を行う。」**

この指示により、AIは作業一覧表に基づいてステップバイステップでタスクを実行し、進捗を自己記録するようになります。

## 作業後の確認事項

AIによる作業が完了した後、人間が確認すべき点をリストアップします。
これにより、作業の品質を担保し、意図しない変更がないかを確認できます。

例:
- [ ] 生成されたコードがコーディング規約に準拠しているか
- [ ] ユニットテストが全てパスするか
- [ ] 意図した機能が正しく実装されているか（手動テストなど）
- [ ] 作業一覧表のステータスとコメントが適切に記載されているか

## 注意事項

AIが作業を行う上で、絶対に守るべきルールや制約事項を記述します。
作業の安全性や一貫性を保つために重要です。

例:
- 特定のファイルを変更しないこと。
- 機密情報を含むコードを生成しないこと。
- 既存のテストコードを削除しないこと。

**（※後述の通り、ファイル作成後に以下の重要な注意文を追記します）**
**「このファイルは作業一覧表の「作業完了」「完了ステータス」「コメント」以外は絶対に変更しないでください。」**

## 作業一覧表

| 対象 | 作業完了 | 完了ステータス | コメント |
|---|---|---|---|
| (ここに具体的な作業対象をリストアップ) | (AIが追記) | (AIが追記) | (AIが追記) |
| ... | ... | ... | ... |

---
**完了ステータスの凡例:**
- ✅: 作業および確認完了
- 🟡: 注意事項あり。 (コメント欄に詳細記載)
- ❌: 作業未達 (コメント欄に理由記載)
---

「作業一覧表」の重要性：タスク分割と具体性

プロンプトコーディングの成否を大きく左右するのが、「作業一覧表」の設計です。ここでのポイントは、タスクの分割単位と対象の具体性です。

  • 分割単位: AIに依頼する作業を、人間が「完了した」と客観的に確認できる、意味のある最小単位に分割します。一度に大きなタスクを依頼するのではなく、細かなステップに分けることで、AIが処理しやすくなり、途中で失敗するリスクを減らせます。

    • 分割例:
      • ファイルごと (src/service/UserService.ts のリファクタリング)
      • 関数ごと (calculateTotalPrice 関数のドキュメントコメント追加)
      • クラスごと (OrderRepository クラスへのメソッド追加)
      • 機能分割ごと (ユーザーCRUD機能のうち、Create処理の実装)
      • テストケースごと (test_user_creation_success テストケースの作成)
    • 繰り返し単位での分割: 同じような作業の繰り返しになる単位（例: 特定ディレクトリ以下の全ファイルに関数ヘッダーを追加する、特定の命名規則を持つ全テストケースにアサーションを追加する）で分割できると、AIが作業パターンを学習しやすく、成功率が高まることが期待できます。

  • 対象の具体性: 作業対象となる要素を具体的にリストアップします。これにより、AIが作業範囲を正確に認識し、「見落とし」を防ぐことができます。

    • 例: 特定ディレクトリ以下の全ファイルを対象とする場合、「src/controllers ディレクトリ以下の全ての .js ファイル」と記述するだけでなく、ls src/controllers/*.js の結果などを貼り付けて、ファイル名を具体的に列挙させます。
    • 同様に、関数名、クラス名、テストスイート名なども、可能な限り具体的にリストアップします。

この「作業一覧表」をAI自身が更新していくことで、タスクの進捗状況がリアルタイムに可視化され、どこまで作業が進み、どこで問題が発生したのかが一目瞭然となります。

ファイル作成後の追記

WORK_{作業内容}.md の初期バージョン（たたき台）はAIに作成してもらいましょう。プロンプトにお願いするのはめんどくさいこともあるので、特に重要な部分は自分で記載するのがいいと思います。

記載するのは2点。

  • 「作業依頼」セクションに、
    「作業一覧を一行つづ上から作業を行う。一行の作業が完了したら、作業一覧の「作業完了」「完了ステータス」「コメント」に追記を行う。追記が完了したらもう一度このファイルを読み直し、次の作業を行う。」
    この記述があることで、進捗状況がリアルタイムで確認できる、途中で失敗しても再開できるなどの利点が得られます。

  • 「注意事項」セクションに以下の非常に重要な一文を必ず追記します。
    「このファイルは作業一覧表の「作業完了」「完了ステータス」「コメント」以外は絶対に変更しないでください。」
    これは、AIが作業を進める中で、勝手に「依頼作業」の内容や「注意事項」自体を変更してしまうことを防ぐための制約です。AIには作業一覧表のステータス更新のみを許可し、それ以外の部分は人間が管理する、という役割分担を明確にします。

AIエージェントへの指示と実行プロセス

WORK_{作業内容}.md の準備ができたら、いよいよAIエージェントに作業を依頼します。

最初のWORK_{作業内容}.md作成依頼

多くの場合、WORK_{作業内容}.md の雛形作成自体もAIに依頼できます。

依頼例:
「以下の作業を行うための WORK_{作業内容}.md ファイルを作成してください。
作業内容: src/utils ディレクトリ以下の全ての .ts ファイルに JSDoc コメントを追加する。
ファイル名は WORK_20250429_Add_JSDoc_to_Utils.md としてください。
作業対象となるファイルリストを調べて 作業一覧表 に含めてください。」

AIが生成したファイルをレビューし、必要に応じて修正を加えます。

AIへの実行依頼プロンプト

WORK_{作業内容}.md が完成したら、AIにそのファイルに基づいて作業を実行するよう指示します。この際のプロンプトは、可能な限り最小限にし、WORK_{作業内容}.md ファイル自体に詳細な指示を集約させるのがプロンプトコーディングの基本です。

しかし、以下の点は毎回明示的に指示に含めることが重要です。

依頼プロンプト例:
「.working/WORK_20250429_Add_JSDoc_to_Utils.md を注意深く熟読し、内容を確認してください。そして、依頼作業 に書かれていることを実行してください。
重要: WORK_20250429_Add_JSDoc_to_Utils.md ファイルの 作業一覧表 の「作業完了」「完了ステータス」「コメント」カラム以外は、絶対に、いかなる理由があっても変更しないでください。」

このように、対象となるファイルを明確に指定し、「熟読して指示に従うこと」と、「ファイルの一部以外は変更しないこと」を念押しします。これにより、AIがファイルの内容を尊重し、指定された手順と制約の中で作業を進めることを期待します。

実行プロセスと人間による確認

AIは指示を受けると、WORK_{作業内容}.md を読み込み、「作業一覧表」の最初の未完了行の「対象」に対して作業を実行します。そして、その結果を「作業完了」「完了ステータス」「コメント」に追記します。その後、再度ファイルを読み込み、次の未完了行の作業に移ります。このプロセスを繰り返し、一覧表の最後まで到達するか、途中で問題が発生するまで続けます。途中で問題が発生しなくても、作業をやめてしまうことがありますが、途中で終わった場合には、依頼プロンプトに「前回の作業が途中で終了しているので、作業一覧表をみて、作業の続きを行ってください。」と依頼することで作業の再開が容易になります。

人間は、AIの作業がある程度進んだ段階や、AIが停止した段階で、以下の点を確認します。

  • WORK_{作業内容}.md の作業一覧表の進捗状況
  • 実際に生成・変更されたコードの内容
  • AIがコメント欄に記述した内容（エラーメッセージ、注意点など）

期待通りに作業が進んでいれば、そのままAIに続きを任せます。もし問題があれば、次のセクションで説明する改善プロセスに入ります。

試行錯誤、改善、そしてノウハウの深化

AIが常に完璧に指示通り動くとは限りません。プロンプトコーディングは、むしろ、うまくいかなかった場合に、その原因を特定し、改善策をWORK_{作業内容}.mdに反映させていくプロセスそのものに価値を置いています。

うまくいかなかった場合の対応

AIの作業結果が期待通りでなかったり、途中で停止してしまったりした場合、まずはWORK_{作業内容}.mdの内容を見直します。

  • 指示の曖昧さ: 「依頼作業」の指示が曖昧で、AIが解釈を誤った可能性はないか？ より具体的に、明確に記述し直します。
  • 作業単位の粒度: タスクの分割単位が大きすぎたのではないか？ より細かいステップに分割し直します。
  • 考慮漏れ: AIが見落としがちな点や、守るべき暗黙のルールが「注意事項」に記載されていなかったのではないか？ 新たな注意点を追加します。
  • 前提条件: 作業に必要な前提条件（特定のライブラリのバージョン、環境設定など）が不足していなかったか？ 「依頼作業」や「注意事項」に追記します。

WORK_{作業内容}.md を修正したら、再度AIに同じ依頼プロンプトで作業を指示します。この 「実行 → 確認 → 修正 → 再実行」 のサイクルを繰り返すことで、徐々にAIとの連携精度を高めていきます。

時には、根本的にアプローチを変える必要があるかもしれません。その場合は、現在のWORK_{作業内容}.md を参考に、新しい方針で WORK_{新しい作業内容}.md を作成し直します。

作業が途中までうまくいっている場合は、そこまでの成果物（コードや WORK_{作業内容}.md の進捗）をバージョン管理システム（Gitなど）にコミットしておくと、後戻りや別アプローチの試行が容易になります。

失敗からの学習とノウハウ化

重要なのは、うまくいかなかった経験もまた、貴重なノウハウとして WORK_{作業内容}.md に落とし込むことです。

例えば、AIがある特定の種類のバグを頻繁に作り込むことがわかった場合、「注意事項」に「XXのようなバグを避けるため、YYの点に注意してコーディングすること」といった具体的な指示を追加します。あるいは、「作業一覧表」の分割方法を工夫することで、その種のバグが発生しにくい手順を設計します。

人間による手作業介入とそのフィードバック

どうしてもAIだけではタスクを完了できない場合や、特定のステップだけ人間が介入した方が効率的な場合があります。その場合、人間が手作業でタスクの一部または全体を完了させることがあります。

この手作業の内容も、将来のAIの成功率を高めるための重要な情報となり得ます。現在検証中のアプローチですが、手作業で行った内容や、その際に気づいた注意点を WORK_{作業内容}.md の「注意事項」に追記しておくことが有効である可能性があります。

フィードバック例:
「（人間が手作業で対応）〇〇の設定ファイルにXXの記述を追加する必要があった。AIはこの作業を忘れることがあるので、次回以降、関連する作業を行う際は、設定ファイルXXの更新を忘れずに行うこと。」

このように具体的なフィードバックを「注意事項」として残しておくことで、次回、類似のタスクをAIに依頼した際に、AIがその注意点を考慮に入れ、より正確に作業を実行してくれるようになることを期待しています。

プロンプトコーディングによるノウハウの再利用とチーム開発への展開

プロンプトコーディングの真価は、一度作成した WORK_{作業内容}.md が、将来の作業のための貴重なテンプレートとなる点にあります。

成功したWORK_{作業内容}.mdの再利用

あるタスクで非常にうまくいった WORK_{作業内容}.md ができたら、それはあなたの（そしてプロジェクトの）「AI操縦ノウハウ」が詰まった資産です。次に類似のタスクが発生した場合、ゼロから指示を考える必要はありません。

AIへの再利用指示例:
「新しい作業として、src/components ディレクトリ内の全Reactコンポーネントに propTypes を追加したい。以前成功した .working/WORK_20250420_Add_JSDoc_to_Services.md のやり方が非常に良かった。あのファイルの構成や指示の仕方を参考に、今回の作業内容に合わせて完璧なやり方を熟慮し、新しい WORK_20250502_Add_PropTypes_to_Components.md を作成してください。作業対象のコンポーネントリストも忘れずに含めてください。」

このように、過去の成功事例ファイルを「お手本」としてAIに提示することで、AIは過去のノウハウを踏襲した上で、新しいタスクに適した WORK_{作業内容}.md を生成してくれることが期待できます。

.working ディレクトリ：チームのAI活用ノウハウリポジトリ

プロジェクトの .working ディレクトリに、様々なタスクに対応する WORK_*.md ファイルが蓄積されていくと、それは単なる個人の作業記録を超え、チーム全体のAI活用ノウハウのリポジトリとなります。

新しいメンバーがプロジェクトに参加した際や、他のメンバーが類似のタスクに取り組む際に、過去の WORK_*.md ファイルを参照することで、効果的なAIの活用方法を迅速に学び、実践することができます。これにより、チーム全体の開発効率とAIリテラシーの向上が期待できます。

おわりに：AIと共に進化する開発プロセスへ

プロンプトコーディングは、混沌としがちなAIとの対話に「秩序」と「再現性」をもたらすための実践的な手法です。AIとの試行錯誤を構造化されたファイルに残し、それを改善し、再利用していくプロセスを通じて、私たちはAIをより効果的に、そして予測可能に活用する方法を学ぶことができます。

AIにはしごを外される絶望感から、AIと共に着実にタスクを前進させる手応えへ。プロンプトコーディングが、エンジニアの皆さんとAIとの関係をより建設的で生産的なものへと変え、皆さんが本来集中すべき創造的な作業により多くの時間を使えるようになるための一助となれば幸いです。

さあ、あなたも .working/WORK_My_First_Task.md を作成し、AIとの新たな対話を始めてみませんか？

// 以上、生成AIで作成に加筆、修正。プロンプトは以下。

プロンプトコーディングのススメ、という文章10000文字の技術文章を作成してください。
内容は以下。
・エージェント型生成AIの使い方の紹介
・エンジニアが使い方を試したいとおもい、希望が持てるような文章にしてください。
・プロンプトコーディングはAIとの対話の苦労を減らす。コーディング生成AIエージェントを使っている人なら、誰しもが生成AIとの対話の末、大量の、意味があるかわからない、動かない、正しくいうと動いているかどうかもわからない、大量のコードの山が出来上がり絶望した経験があると思う。AIにはしごを外されたときのあの感覚、暗中模索、五里霧中、孤立無援。あの感覚をどう表現すればよいかわからないが、生成AIへの期待の高さからの落差もあって、あまり好ましいものではない。私もその感覚を味わった一人で、その経験から生まれたのがプロンプトコーディングという手法である。この手法は一定のルールを持ったプロンプトをファイルに記載しAIとの対話の中での試行錯誤をファイルという残るものに残すことで、ある作業をAIに依頼する際のAIとの付き合い方のノウハウを蓄積、作業を前進させるものである。
・WORK_{作業内容}.mdというファイルを.workingディレクトリ内に、生成AIに作成してもらう。作業内容には日付、チケット番号|issueIDなどがアンダーバー区切りで含まれていても良い。プロジェクト内でフォーマットが統一されているのが好ましい。WORK_.mdファイルがプロジェクトに蓄積されていくのが、プロジェクト内のプロンプト作成ノウハウ集積につながる。
・WORK_{作業内容}.md内容は、「依頼作業」「作業後の確認事項」「注意事項」「作業一覧表」である。作業一覧表には、「対象」「作業完了」「完了ステータス」「コメント」カラムがある。
・依頼作業に”作業一覧を一行つづ上から作業を行う。一行の作業が完了したら、作業一覧の「作業完了」「完了ステータス」「コメント」に追記を行う。追記が完了したらもう一度このファイルを読み直し、次の作業を行う。”を含める。
・作業一覧の一行は人間が「完了した」と確認できる、意味のある最小単位とします。分割単位の例としては、ファイルごと、関数ごと、クラスごと、機能分割ごと（CRUD単位）、テストケースごとなどです。作業が特定の範囲の全要素（例: 特定ディレクトリ以下の全ファイル、特定の命名規則を持つ全テストケース）を対象とする場合、その全要素をリストアップさせます。これにより、AIの「見落とし」を防ぎます。ファイル名、関数名、クラス名、テストスイート名などを具体的に列挙させます。同じような作業の繰り返しになる単位で分割できると、作業がパターンになりやすく、成功率が高まることが期待できます。
・作業一覧表には完了ステータスの凡例を記載します。
- ✅: 作業および確認完了 - 🟡: 注意事項あり。 - ❌: 作業未達
・作成完了後、「注意事項」には　”このファイルは作業一覧表の「作業完了」「完了ステータス」「コメント」以外は絶対に変更しないでください。”と追記する。
・依頼時のプロンプトは最小限とする。ただし、先の注意事項を再び含める。”WORK_{作業内容}.mdを注意深く熟読、内容を確認して、作業依頼に書かれていることを実行してください。WORK_{作業内容}.md作業一覧表の「作業完了」「完了ステータス」「コメント」以外は絶対に変更しないでください。”
・実施後、作業がいい感じにできていることを確認します。だめなようならWORK_{作業内容}.mdを修正します。あとは生成AIに任せる。だめなら修正を繰り返す。方向性を変えてもう一度やりなす。途中までいい感じにできているようであれば、そこまでをコミットし、そこからやり直してもいい。うまくいかなかったときも、そこまでの生成AIとのやり取りの経験を次に繋げるためにWORK_{作業内容}.mdの内容に落とし込んでいきます。
・どうしてもAIが最後までできなかった場合、人間が手を動かしてタスクを完成させることがあります。検証中ですが、手作業でやったことを注意事項欄に「XXを忘れることがあるので、作業中にXXを忘れずに実行すること。」などを記載すると、次回からの成功率が上がることを期待敷いています。
・いい感じのWORK_{作業内容}.mdができたら、次から「XXをしてほしいのだけれど、完璧なやり方を熟慮して、WORK_{作業内容}.mdを参考にWORK_{作業内容2}.mdを作成して。」などしてAIに再利用してもらいます。

どうですかね？似たものにMemory Bankがありますが、それよりも私にとってはお手軽で実践的な手法の紹介でした。

Discussion