AIへ「顧客管理システムを作って」と頼むだけでも、画面が動くところまでは進められるようになりました。
しかし、一度にアプリ全体を作らせると、何が変更されたのか分からなくなりがちです。エラーが起きるたびに追加の修正を依頼し、別の場所が壊れ、最後には元へ戻せなくなることもあります。
この記事では、プログラミングを始めたばかりの人を対象に、コーディングエージェントを使って小規模なWebアプリや業務システムを開発する基本手順を説明します。
特定の製品の操作方法ではなく、どのエージェントでも応用できる進め方を中心にします。
AI開発ツールにはいくつかの形がある
AIを使った開発ツールは、使い方によって大きく次のように分けられます。
| 種類 | 主な使い方 |
|---|---|
| チャット型 | 設計相談、エラーの解説、コード例の作成 |
| エディタ統合型 | 開いているコードの補完、修正、質問 |
| エージェント型 | 複数ファイルの調査・編集、コマンド実行、テスト |
| クラウド型 | Issueなどを基に非同期で実装し、変更案やPRを作成 |
実際の製品は複数の特徴を持つため、この分類に完全に分かれるわけではありません。例えば、エディタに組み込まれた機能が、エージェントとして複数ファイルを変更することもあります。
この記事では、Claude CodeやCodexのように、プロジェクトを調査し、ファイルを編集し、テストまで実行できるエージェント型を前提にします。
エージェント型でも、人が決めることは残る
コーディングエージェントは、コードを書くことだけでなく、既存コードの調査、修正案の作成、テストの実行もできます。
一方、次の判断までAIへ任せきることはできません。
- 誰が何のために使うのか
- どの機能を最初に作るのか
- 誰にどのデータを見せてよいのか
- どの情報を保存してよいのか
- 予算や納期をどこまで使えるのか
- 本番へ反映してよい状態か
AIは曖昧な部分を推測して先へ進むことがあります。実装を始める前に、人が目的と制約を決めることが重要です。
開発全体の流れ
最初は、次の流れを繰り返せば十分です。
目的を決める
↓
機能を小さく分ける
↓
AIに調査と計画を依頼する
↓
一つだけ実装する
↓
差分とテスト結果を確認する
↓
Gitへコミットする
↓
次の機能へ進む
大切なのは、一度に完成させようとしないことです。いつでも直前の正常な状態へ戻せるように進めます。
1. 最初に作るものを一文で決める
最初に、利用者と目的を一文で書きます。
営業担当者が、顧客からの問い合わせと対応状況を共有するための社内Webアプリを作る。
「高機能なCRMを作る」だけでは、AIは必要な機能を決められません。対象を絞ると、不要な機能や技術が増えることを防げます。
次に、最初のバージョンで必要な機能だけを列挙します。
- ログインする
- 顧客を登録する
- 顧客を一覧表示する
- 問い合わせを記録する
- 対応状況を更新する
- 管理者が利用者を管理する
集計、通知、CSV出力などは、最初から必要でなければ後回しにします。
2. 実装の前に計画を作らせる
最初の依頼では、まだコードを書かせません。機能、画面、データ、権限、実装順序を整理させます。
営業担当者が、顧客からの問い合わせと対応状況を共有するための
社内Webアプリを作ります。
まだ実装は行わず、次の内容を整理してください。
- 想定する利用者
- 必要な機能
- 画面一覧
- データベースのテーブル案
- 認証と権限
- 実装する順番
- 判断が必要な点
技術スタックはREADMEに従ってください。
不明な要件を勝手に決めず、質問または未決定事項として示してください。
出てきた計画をそのまま採用する必要はありません。不要な機能を削り、不明点へ回答してから、READMEや設計資料へ残します。
3. Gitを最初から使う
Gitは、完成後にGitHubへアップロードするためだけの道具ではありません。AIが行った変更を確認し、問題が起きたときに戻すための安全装置です。
作業を始める前に、現在の状態をコミットします。
git status
git add <確認したファイル>
git commit -m "顧客登録機能の実装前"
AIが変更した後は、少なくとも次を確認します。
git status
git diff
.env、APIキー、DBパスワードなどが含まれていないことも確認します。内容が分からない変更を、とりあえず全部コミットする運用は避けます。
4. 一つの機能をさらに小さくする
「顧客管理機能を作る」では変更範囲が広すぎます。例えば、次の単位へ分けます。
- 顧客テーブルのスキーマを作る
- マイグレーションを生成する
- 顧客を登録するAPIを作る
- 入力値を検証する
- 登録画面を作る
- 正常系と異常系のテストを作る
一つの依頼で変更する目的が一つなら、間違いを見つけやすく、問題が起きても戻しやすくなります。
5. まず調査と実装計画を依頼する
既存プロジェクトへ機能を追加するときも、最初から編集させる必要はありません。
顧客登録機能を追加したいです。
まず既存のディレクトリ構成、DBスキーマ、認証方法、テスト方法を調査してください。
まだファイルは変更せず、変更が必要なファイルと実装手順を提示してください。
不明点や既存機能への影響も示してください。
計画を見ると、AIがプロジェクトを正しく理解しているかを実装前に確認できます。知らないライブラリを勝手に追加しようとしていないか、認証やDB変更を見落としていないかも確認します。
6. 実装時は完成条件まで伝える
「実装して」だけでは、画面が表示された時点で完了と判断されることがあります。何をもって完成とするかを一緒に伝えます。
提示した計画に沿って、顧客登録機能だけを実装してください。
- 名前は必須、メールアドレスは形式を検証する
- 入力値はサーバー側でも検証する
- 未認証の利用者は登録できない
- 正常系、入力エラー、未認証のテストを追加する
- DB変更はDrizzle Kitのマイグレーションとして作成する
- 関係のないファイルは変更しない
- 実装後に型チェック、Lint、テストを実行する
- 最後に変更ファイルと確認結果を報告する
制約と確認方法まで伝えることで、「動いて見えるだけ」の実装を減らせます。
7. AIの完了報告だけで判断しない
エージェントが「実装とテストが完了しました」と回答しても、人が結果を確認します。
変更されたファイル
意図していない設定ファイル、認証処理、既存機能が変更されていないかを確認します。
git status
git diff --stat
git diff
実際のテスト結果
テストを作っただけで、実行していない場合があります。どのコマンドを実行し、何件成功したのかを確認します。
ブラウザでの動作
最低限、正常な入力だけでなく、空欄、長すぎる文字、重複、権限不足なども試します。
エラー処理
DBや外部APIへ接続できないときに、秘密情報を含むエラーが画面へ表示されないかを確認します。
8. DBマイグレーションは特に慎重に扱う
DBの変更は、コードを元へ戻すだけでは取り消せない場合があります。列やテーブルを削除すると、保存されていたデータも失われます。
初心者でも、次の原則は守ります。
- DB変更はマイグレーションファイルとして残す
- 生成されたSQLを適用前に確認する
- 適用済みマイグレーションを後から書き換えない
- 修正は新しいマイグレーションとして追加する
- 本番適用前にバックアップと復旧方法を確認する
- 本番データでいきなり試さない
特に、テーブルや列の削除、型変更、NOT NULLの追加、大量データへのインデックス作成は、人が影響を確認してから実行します。
9. 認証と権限は別々に確認する
ログインできることと、権限が正しいことは別です。
- 未ログインでAPIを呼べないか
- 一般利用者が管理者画面を操作できないか
- URLのIDを書き換えて他人のデータを見られないか
- 画面でボタンを隠すだけでなく、サーバー側でも拒否しているか
「ログイン画面があるから安全」と判断せず、APIやサーバー処理ごとに認証と権限を確認します。
10. 秘密情報をAIへ渡さない
エラー調査を依頼するときに、ログや設定ファイルをそのまま貼り付けると、次の情報まで含まれることがあります。
- APIキー
- アクセストークン
- DB接続情報
- Cookieやセッション情報
- 顧客の氏名やメールアドレス
秘密部分を伏せ、必要なエラーメッセージだけを渡します。リポジトリ内でも、.envや認証情報がGitの管理対象になっていないか確認します。
11. エラーが起きたら修正を重ね続けない
エラーへ対して短い指示を繰り返すと、その場しのぎの変更が増えることがあります。
直して
まだ動かない
別の方法で直して
代わりに、現象と再現方法を整理して調査を依頼します。
顧客登録時に500エラーが発生します。
再現手順:
1. 一般利用者でログインする
2. 顧客名とメールアドレスを入力する
3. 登録ボタンを押す
期待する結果:
顧客が登録され、一覧画面へ移動する。
実際の結果:
500エラーになり、DBには登録されない。
まず原因を調査してください。まだ修正せず、根拠と修正案を提示してください。
原因が分からなくなったら、最後に正常だったコミットとの差分を確認します。修正が積み重なりすぎた場合は、正常な状態へ戻してやり直すほうが早いこともあります。
12. コミットしてから次へ進む
一つの機能が動き、差分とテストを確認したらコミットします。
git add <確認したファイル>
git commit -m "顧客登録機能を追加"
「画面作成、認証変更、DB変更、デプロイ設定」を一つの巨大なコミットへまとめないようにします。変更理由ごとに分かれていれば、不具合の原因を調べやすくなります。
AIへ渡すプロジェクトルール
毎回同じ注意を繰り返さなくて済むように、プロジェクトのルールを文書へ残します。ツールが読み込む指示ファイルを利用する場合も、READMEなど人が読める文書と矛盾させないようにします。
# 開発ルール
- 技術スタックはREADMEに記載したものを使用する
- 新しいライブラリの追加前に理由と代替案を示す
- 関係のないファイルを変更しない
- DB変更はマイグレーションとして作成する
- 認証と権限はサーバー側でも検証する
- 秘密情報をコード、ログ、テストデータへ含めない
- 変更後に型チェック、Lint、テストを実行する
- 破壊的な操作や本番反映は、実行前に確認を求める
ルールを増やしすぎると読まれにくくなるため、事故につながる項目と、プロジェクト固有の判断を優先します。
初心者が避けたい進め方
アプリ全体を一度に作らせる
変更量が多くなり、どこが正しいのか確認できません。一つの業務を完了できる小さな単位で進めます。
エラーのたびに別の技術へ変更する
認証ライブラリ、ORM、フレームワークを途中で次々に変更すると、古い実装が残ります。まず現在の問題の原因を調査します。
AIの提案したコマンドを読まずに実行する
ファイル削除、DB初期化、本番反映、課金リソース作成などが含まれる可能性があります。対象と影響が分からないコマンドは実行しません。
テストが通ったので完成と考える
テストが仕様を正しく表していなければ、間違った実装でも成功します。主要な操作は人も確認します。
チャット履歴だけを仕様書にする
新しい会話では過去の前提が伝わらないことがあります。決定事項はREADME、設計資料、Issueなどへ残します。
最小限のチェックリスト
一つの機能を終えるたびに、次を確認します。
- 今回作る機能と完成条件が明確になっている
- 実装前の状態をGitへ保存している
- AIが変更したファイルを確認した
- 不要なライブラリや設定が追加されていない
- 認証と権限をサーバー側でも確認している
- DB変更をマイグレーションとして管理している
- 秘密情報や個人情報が含まれていない
- 型チェック、Lint、テストを実行した
- 正常系と主な異常系を実際に操作した
- 確認した変更だけをコミットした
まとめ
エージェント型のAIを使うと、初心者でも調査、実装、テストを一つの流れとして進められます。しかし、アプリ全体を一度に任せると、人が確認できる範囲を簡単に超えてしまいます。
まず目的を決め、機能を小さく分け、実装前に計画を確認します。一つ実装するたびに差分とテスト結果を確認し、Gitへコミットしてから次へ進みます。
重要なのは、AIを信用するか疑うかではありません。AIが行った変更を確認でき、問題があれば戻せる開発手順を作ることです。
技術選定については、次の記事で初心者向けの構成例を紹介しています。
本番公開前の確認事項については、次の記事にまとめています。