大規模な開発で、AIに渡す規約・制約・テスト方針をどう作ったのか

AIにコードを書かせたいが、規模が大きくなると書き方がぶれないか不安な開発の責任者の方に向けた記事です。規約・設計上の制約・テスト方針を、実装の前にリポジトリの中の文書にしておけば、AIが書く量が増えてもコードの形はそろいます。この記事では全国1,000店舗強で使われるモバイルオーダーをClaude Codeで作り直したときに、何をどこに書き、どう確かめたのかを説明します。
案件の全体像は「大規模なNext.js / FlutterアプリをClaude Codeでフルスクラッチ、どんな方針で取り組んだのか」にまとめています。
規約・制約・テスト方針は、どこに置いたのか
CLAUDE.mdと、docsフォルダの文書に置きました。どちらもリポジトリの中にあります。
CLAUDE.mdは、Claude Codeが作業を始めるときに読むファイルです。docsフォルダには規約や設計の文書を置きました。コードと同じリポジトリにあるので、AIが毎回読めます。文書を直すときも、コードと同じくプルリクエストで変更を管理できます。
人の頭の中にあるルールは、AIには守れません。口頭で伝えていた決まりごとも、文書にしました。
何を文書にしたのか
AIが毎回同じ基準で書けるように、次のものを文書にしました。
| 文書 | 書いたこと |
|---|---|
| コーディング規約 | コードの書き方の決まり |
| アーキテクチャとサンプルコード | 画面・部品・データ取得をどう分けるかと、その見本 |
| 守らなければならない制約 | 外部システムとの取り決めなど、業務やお客様に固有のルール |
| テストの方針 | 何を、どのテストで確かめるか |
外部システムとの連携は、どう進めたのか
公開・提供されている技術仕様やドキュメントをClaudeに読み込ませ、動作確認用のサンプルコードと確認事項をまとめてから、仕様をつかみました。
このサービスは、外部システムとの連携が非常に多い構成です。連携先ごとに仕様の書き方も粒度も違うので、いきなり本番のコードに組み込むと、仕様の読み違いがそのまま不具合になります。そこで、まずClaudeに技術仕様とドキュメントを読ませ、次の2つを作らせました。
- 動作確認用のサンプルコード:仕様どおりに呼び出したとき、実際にどう動くかを小さく確かめる
- 確認事項の一覧:仕様から読み取れないこと、連携先に確かめるべきことを洗い出す
サンプルコードで動きを確かめ、確認事項を解消してから、連携の取り決めを制約として文書に書きました。AIに推測で連携のコードを書かせないためです。
サーバーとのやり取りは、どう決めたのか
Next.jsのサーバーとのやり取りは、1つの型に決めました。Aurora Scharffさんの「Component Architecture for React Server Components」の考え方を主に採用しています。
- ページは部品を組み合わせるだけで、自分ではデータを取りに行かない
- データは、それを使う部品が自分で取得する
- 読み込み中の表示(Suspense)の区切り方は、ページの側で設計する
- ブラウザで動く部品(Client Components)は、部品の木の末端に置く
型を1つに決めると、AIが書くコードの形もそろいます。どこでデータを取り、どこで画面を描いているかが予想どおりになるので、コードを読まずに確かめられる範囲が広がりました。
振る舞いは、どのテストで確かめたのか
単体テスト、Storybookのテスト、E2Eテストの3つで確かめました。
| テスト | 確かめること |
|---|---|
| 単体テスト | 関数やロジックが、条件どおりの結果を返すか |
| Storybookのテスト | 画面の部品が、状態ごとに正しく表示され、操作に正しく反応するか |
| E2Eテスト | 利用者が画面を操作して、注文などの流れを最後まで終えられるか |
クーポンのように条件の組み合わせが多いところは、テストケースも相当な数になります。人がコードを1行ずつ読んで確かめるのではなく、テストで確かめる形にしました。
入力のバリデーションとエラーのメッセージ
利用者の入力は、zodのスキーマでバリデーションしてからサーバーに送ります。
サーバーから返るエラーは、OpenAPIで書かれたAPIスキーマに合わせて、エラーハンドリングのメッセージを自動で出すようにしました。画面ごとにAIにエラーの処理を書かせると、同じエラーでも画面によってメッセージや出し方が変わります。APIスキーマをもとに出せば、どの画面でも同じ扱いになります。
コードレビューは、どうしたか
画面の部品はStorybookで確認できるので、人が見るのは振る舞いだけです。そのため、コードレビューはほとんど行っていません。
まとめ
- 規約・制約・テスト方針はCLAUDE.mdとdocsフォルダに置き、リポジトリの中で管理した
- 外部システムとの連携は、技術仕様をClaudeに読ませてサンプルコードと確認事項をまとめ、仕様をつかんでから文書にした
- サーバーとのやり取りは1つの型に決め、AIが書くコードの形をそろえた
- 単体テスト、Storybookのテスト、E2Eテストで振る舞いを確かめ、エラーのメッセージはAPIスキーマに合わせて自動で出した
- そのため、コードレビューはほとんど要らなかった
開発チームにAI前提の進め方を入れる手順は、「開発チームにAIを入れる手順」にまとめています。
よくある質問
規約や制約は、どこに置けばよいですか?
リポジトリの中に置きます。この案件では、CLAUDE.mdと、docsフォルダの文書に書きました。コードと同じ場所にあれば、AIが毎回読めて、変更も同じ流れで管理できます。
エラーのメッセージは、画面ごとにAIに書かせましたか?
画面ごとには書かせていません。OpenAPIのAPIスキーマに合わせて、エラーハンドリングのメッセージが自動で出るようにしました。入力のバリデーションはzodで行っています。
テストは、何を使い分けましたか?
単体テスト、Storybookのテスト、E2Eテストの3つです。ロジックは単体テスト、画面の部品の振る舞いはStorybook、利用者の操作の流れはE2Eテストで確かめています。