投稿する
マガジン
著者：アソバース編集部公開：更新：約7分で読めます

既存のWebアプリにAIコーディングを入れる前に整える起動・テスト・規約のメモ

AIを使いこなす

Claudeで執筆し、GPTで自動校閲・修正しています。

Webアプリ導入前の準備項目をノートで確認する手元
記事の内容をもとに制作したAI生成イメージです。実際の製品画面や検証結果の写真ではありません。

既存のWebアプリにAIコーディングを入れる前に整えるのは、「起動できる」「テストで確かめられる」「守る規約が分かる」の3点です。この3つを、AIが自分でコマンドを打って確認できる形で書いておきます。 多くの現場では、これらの情報が誰かの頭の中や、古いREADMEの中に残っています。人は先輩に聞いて補えますが、AIは聞けないので、推測で進めて的外れな修正をします。この記事では、導入前に1時間ほどで済ませる手順と、READMEとAI向け指示に書く項目のチェックリストを示します。

この記事の目次
  1. 最初に整えるのは「コードから読み取れない情報」
  2. 手順：クリーンな環境で試し、詰まった所を書く
  3. 準備チェックリスト
  4. AI向け指示の雛形と置き場所
  5. 試運転：コードを変えずに手順だけ検証させる

最初に整えるのは「コードから読み取れない情報」

Claude Codeのベストプラクティスは、コードだけでは見えない知識（デプロイ手順、完了とみなす前に通すべきチェックなど）をAIに伝え、実行できる確認手段を渡すことを軸にしています。GitHub Copilotのリポジトリ指示のドキュメントも、bootstrap・build・test・run・lintの各手順と必要なツールのバージョンを書くよう勧めています。

つまり、迷いの原因は多くの場合「実行方法の不足」です。規約の文章を磨く前に、起動とテストの手順を実際に動くものにしてください。

手順：クリーンな環境で試し、詰まった所を書く

  1. 新しいクローンで、READMEだけを見て起動します。 自分の環境の「いつもの状態」には頼りません。詰まった箇所をすべてメモします。AIも同じ所で詰まります。
  2. テストを1コマンドで実行できるようにします。 あわせて、特定のファイルや1件だけを実行する方法も控えます。AIは修正のたびに全件を回さず、狭く確認できるほうが進めやすくなります。
  3. 落ちているテスト、遅いテスト、外部サービスが必要なテストを洗い出します。 「このテストは既知の失敗」と書いておかないと、AIが原因を探して無関係な箇所を直し始めることがあります。
  4. 規約は「レビューで繰り返し指摘すること」を3〜5個に絞ります。 スタイルガイド全文は不要です。CursorのRulesのドキュメントも、スタイルガイド全文や既存コードの複製を避け、ファイル参照を使い、同じ誤りが繰り返されたときに足す進め方を挙げています。
  5. AI向け指示にまとめます。 READMEと重複する内容は書き写さず、READMEへのリンクにします。
  6. 試運転します。 後述の依頼文で、コードを変えずに手順だけ検証させます。

準備チェックリスト

READMEに書く（人にもAIにも必要）

  • [ ] 必要なランタイムとバージョン（Node、Ruby、Python、DBなど）
  • [ ] 初回セットアップのコマンドを上から順に
  • [ ] 環境変数の一覧と、ダミー値で動くか（.env.exampleの有無）
  • [ ] 開発サーバーの起動コマンドと、起動後に開くURL
  • [ ] DBやキューなど依存サービスの立ち上げ方、初期データの入れ方
  • [ ] テスト、lint、型チェック、ビルドの各コマンド
  • [ ] 既知の失敗テストや、手元で再現しない警告

AI向け指示に書く（短く、具体的に）

  • [ ] 作業を終える前に必ず通すコマンド（例：lint→型チェック→関連テスト）
  • [ ] 1ファイルだけテストする方法
  • [ ] 規約3〜5個（命名、置き場所、使うライブラリと使わないもの）
  • [ ] ディレクトリの役割の要約（フロント、API、共通部品）
  • [ ] 触る前に相談する領域（認証、決済、マイグレーション、生成ファイル）
  • [ ] 本物の秘密情報は読ませない、貼らないという方針

AI向け指示の雛形と置き場所

次は説明用の例です。実際のプロジェクトで実行して確かめたものではないので、コマンドやパスは自分の環境に置き換えてください。

markdown
# プロジェクトの概要
社内向け予約管理Webアプリ（フロント: <フレームワーク>、API: <言語>）。
詳しい構成は README.md を参照。

# コマンド
- 初回セットアップ: <install コマンド>
- 開発サーバー: <dev コマンド>（http://localhost:<port>）
- 全テスト: <test コマンド>
- 単一ファイル: <test コマンド> <ファイルパス>
- 完了前に必ず通す: lint → 型チェック → 変更に関係するテスト

# 規約
- API呼び出しは src/api/ の関数経由。コンポーネントから直接 fetch しない
- 新しい依存パッケージは追加前に相談する
- 日付処理は <採用済みライブラリ> に統一

# 注意
- 既知の失敗テスト: <テスト名>（原因調査は不要）
- 次の領域は変更前に相談: 認証、決済、db/migrations/
- .env の実値は読まない。必要な変数名は .env.example を見る

置き場所はツールで違います。確認できた範囲を表にします。

  • Claude Code、主な指示ファイル：CLAUDE.md、確認した内容：既存のAGENTS.mdを代わりに読むことも可能。指示は強制設定ではなく文脈として扱われる
  • GitHub Copilot、主な指示ファイル：.github/copilot-instructions.md、AGENTS.mdなど、確認した内容：パス別の指示は.github/instructions/の*.instructions.md
  • Cursor、主な指示ファイル：.cursor/rules、プロジェクト直下のAGENTS.md、確認した内容：ルールは500行以下が目安

複数ツールを使うなら、AGENTS.mdに共通内容を置き、重複を避けるのが管理しやすいでしょう（これは編集上の提案です）。ツールごとの読み込み順や優先度は、導入前に各公式ドキュメントで確認してください。

Claudeのメモリのドキュメントによると、指示は具体的で簡潔なほど守られやすい一方、強制ではありません。「絶対にさせない」操作は、指示文ではなく権限設定やフックなど別の仕組みで止めます。

試運転：コードを変えずに手順だけ検証させる

整えたら、AIに次の依頼文を渡します。

text
コードは一切変更しないでください。
README.md と、AI向け指示ファイルだけを根拠に、次を順に実行してください。
1. セットアップと開発サーバーの起動
2. 全テストの実行
3. 1つのテストファイルだけの実行
実行したコマンドと結果を一覧にし、手順が足りない・曖昧・矛盾している箇所を
「どの文書の何行目付近か」付きで報告してください。推測で補った点は明記してください。

人が確認するのは次の4点です。

  • 報告された「詰まった箇所」を、READMEかAI向け指示に反映します。
  • AIが実行したコマンドが、本番DBや外部サービスに触れていないか確認します。
  • 全テストの結果が既知の失敗と一致しているか確認します。
  • 指示ファイルに社内URL、鍵、顧客データが入っていないか確認します。

手順が一度で通るようになってから、最初の小さな修正（文言変更やテスト追加など）を任せます。以降は、AIが同じ間違いを繰り返したときだけ規約を1行足します。

出典・参考資料

マガジン一覧に戻る