AIで開発していて、こんな経験ありませんか？
「昨日はsrc/ディレクトリ構成で生成してくれたのに、今日はapp/直下に作ってしまった」「バリデーションにZodを使ってほしいのに、毎回as stringキャストで誤魔化されている」「Server Actionsで書いてほしいのに、なぜかfetch()でPOSTするコードが出てきた」
自分自身、Next.jsプロジェクトでClaude Codeを使って開発していたとき、まさにこの問題に悩まされていました。同じプロンプトを投げても結果がバラバラで、「AIコーディングって、結局レビューコストが高くなるだけでは？」と感じはじめていたんです。
そこで試したのが、CLAUDE.md（AIへの指示書ファイル）にガイドラインを読み込ませる方法です。やってみると、導入は5〜10分、コード品質のスコアは5.6点 → 8.0点（+43%）まで改善しました。
この記事では、その具体的な手順をBefore/Afterのコード差分付きで紹介します。
この記事でわかること
- CLAUDE.mdにガイドラインを組み込む最小構成の手順（Step 1〜3）
- 導入前後のコード品質スコアの変化（5.6点 → 8.0点、+43%）
- どの観点で改善・悪化したかの具体的な数値（Zodバリデーション: 0% → 100% など）
検証データの概要（3種類のプロンプト × 5回 × 3条件で計測）：
| テスト項目 | Before | After（CLAUDE.md導入） |
|---|---|---|
| 認証ミドルウェア | 5.4/10 | 7.8/10 |
| CRUD API | 5.8/10 | 8.2/10 |
| UIコンポーネント | 5.6/10 | 8.0/10 |
| 全体平均 | 5.6/10 | 8.0/10 (+43%) |
なお、CLAUDE.mdやAIコーディングのガイドライン整備については、以前の記事（AIが書くコード、毎回バラバラ問題を解決するOSSを作った）でも触れています。今回はその実際の導入手順にフォーカスした内容です。
前提と環境
この記事は以下の環境を前提としています。
- AIコーディングツール: Claude Code（同様の仕組みはCursorやKiroでも応用できます）
- フレームワーク: Next.js 15 App Router
- Gitリポジトリ: 既に初期化済みであること
-
所要時間の目安:
- 記事の通読: 約15分
- 導入作業（Step 1〜3）: 約5〜10分
- Before/After 動作確認: 約5分
- 合計: 約30分以内
「CLAUDE.md」は、Claude Codeがプロジェクトを開いたときに自動で読み込む指示書ファイルです（初耳の方は「AIへの設計書」というイメージで大丈夫です）。このファイルにガイドラインへのパスを書いておくことで、AIが毎回そのルールを参照しながらコードを生成するようになります。
Before：ガイドラインなしの状態
まず「何も指示しない状態」でどんなコードが生成されるか見てみましょう。
たとえば「タスク作成フォームを作って」と指示した場合、次のようなコードが生成されることがよくあります。
// app/dashboard/tasks/TaskForm.tsx ← ❌ PascalCaseのファイル名、src/なし
"use client";
import { useState } from "react";
export default function TaskForm() {
const [title, setTitle] = useState("");
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
// ❌ Zod未使用、バリデーションなし
// ❌ try-catchなし、エラーハンドリング未実装
// ❌ Server Actionsではなくfetch()でPOST → CSRF対策なし
await fetch("/api/tasks", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title }),
});
}
return (
<form onSubmit={handleSubmit}>
<input
value={title}
onChange={(e) => setTitle(e.target.value)}
name="title"
placeholder="タスク名"
/>
<button type="submit">作成</button>
</form>
);
}
問題点をまとめると：
| 問題 | 詳細 |
|---|---|
| Zodバリデーション未使用 |
as stringキャストで型安全性がゼロ |
| ファイル配置がバラバラ |
src/ディレクトリなし、命名規則もPascalCase |
| エラーハンドリングなし | try-catchがなくエラーが握り潰される |
| Server Actions未使用 | fetch()でPOSTするためCSRF対策がない |
この状態が「Before スコア: 5.6/10」です。
AI Dev OSとは（解決策の説明）
問題の根本原因は、「AIがプロジェクトのルールを知らない」ことです。人間のエンジニアなら「このプロジェクトはこういう規約で」と説明すれば理解してもらえますが、AIは毎回ゼロから判断します。
その解決策として自分が作ったのが AI-Dev-OS というOSSです。Next.jsプロジェクト向けのコーディングガイドライン集で、命名規則・バリデーション・エラーハンドリング・Server Actionsのパターンなどを体系的にまとめています。
詳しい背景は前回の記事に書いていますが、ここでは「git submoduleとして追加して、CLAUDE.mdで参照させる」という使い方に絞って説明します。
導入の流れはシンプルです。
1. ai-dev-os をsubmoduleとして追加（git submodule add）
2. CLAUDE.md を最小構成で作成（参照するガイドラインのパスを書くだけ）
3. （任意）プロジェクト固有のルールを docs/guidelines/ に配置
それでは実際にやってみましょう。
Step 1: ルールリポジトリをsubmoduleとして追加
プロジェクトのルートで以下のコマンドを実行します。TypeScript / Next.js 向けのルールリポジトリを追加します。
git submodule add https://github.com/yunbow/ai-dev-os-rules-typescript.git docs/ai-dev-os
git submodule update --init
これで docs/ai-dev-os/ 配下にガイドライン群が追加されます。所要時間は1〜2分です。
git submoduleとは？
外部のGitリポジトリを自分のリポジトリの中に「参照として組み込む」仕組みです。ライブラリのように自分のコードと混在せず、AI Dev OS側の更新も git submodule update --remote で取り込めます。
クローン済みリポジトリを他のメンバーが使う場合は、以下も実行してもらいます。
git submodule update --init --recursive
（オプション）Claude Code プラグインを追加
後述する /ai-dev-os-check スラッシュコマンドを使いたい場合は、あわせて Claude Code 用プラグインも追加します。
git submodule add https://github.com/yunbow/ai-dev-os-plugin-claude-code.git .claude/plugins/ai-dev-os
CLAUDE.mdだけを参照させてコード生成の品質を上げたい、という場合はこのステップは不要です。
Step 2: CLAUDE.mdを最小構成で作成
プロジェクトルートに CLAUDE.md を作成します。最小構成は次の通りです。
# プロジェクト開発ガイドライン
## フレームワーク固有ガイドライン
- docs/ai-dev-os/03_guidelines/frameworks/nextjs/overview.md
- docs/ai-dev-os/03_guidelines/frameworks/nextjs/project-structure.md
- docs/ai-dev-os/03_guidelines/frameworks/nextjs/api.md
- docs/ai-dev-os/03_guidelines/frameworks/nextjs/server-actions.md
## 共通ガイドライン
- docs/ai-dev-os/03_guidelines/common/naming.md
- docs/ai-dev-os/03_guidelines/common/validation.md
- docs/ai-dev-os/03_guidelines/common/error-handling.md
これだけです。 ファイルを置くだけでClaude Codeが次回起動時から自動で読み込みます。
CLAUDE.mdを長く書きすぎるのは逆効果です。以前「CLAUDE.md を200行書いたら品質が79点に下がった話」でも紹介しましたが、詳細を詰め込むよりも「参照先ファイルへのパスを書く」方がスコアが上がりました。まずは最小構成から始めることをおすすめします。
Step 3: docs/guidelines/にプロジェクト固有ルールを配置（任意）
Step 2だけでも十分効果がありますが、プロジェクト固有のルール（独自のビジネスロジックや外部サービスの接続方法など）がある場合は、以下のディレクトリに追加します。
mkdir -p docs/guidelines/project-specific
たとえばこんなファイル構成です。
docs/
└── guidelines/
└── project-specific/
├── external/
│ ├── google-api.md # Google API の使い方
│ └── payment.md # 決済処理のルール
└── business-logic/
├── credit-system.md # クレジットシステム仕様
└── job-queue.md # 非同期処理のパターン
作成したファイルは、CLAUDE.mdに追記するだけで参照されます。
## プロジェクト固有ガイドライン
- docs/guidelines/project-specific/external/google-api.md
- docs/guidelines/project-specific/business-logic/credit-system.md
Step 3はあくまで任意なので、まずはStep 1〜2だけで試してみてください。
After: ガイドライン導入後、何が変わったか
実際に3種類のプロンプト（認証ミドルウェア・CRUD API・UIコンポーネント）それぞれ5回ずつ、計15回生成を回してスコアを比べました。
全体スコア（10点満点）
| 条件 | スコア | Before比 |
|---|---|---|
| Before（ガイドラインなし） | 5.6点 | — |
| After（CLAUDE.md導入） | 8.0点 | +2.4点（+43%） |
| After+Check（+ai-dev-os-check） | 8.1点 | +2.5点（+45%） ※後述 |
5〜10分の作業で 平均+43% のスコア改善。数字で見るとなかなか手応えがありますね。
何が一番改善されたか
項目別に見ると、改善の落差が特に大きかったのが C3（Zodバリデーション） です。
| 評価項目 | Before | After | After+Check ※後述 |
|---|---|---|---|
| C3 Zodバリデーション | 0% | 100% | 100% |
| C8 ディレクトリ構成 | 26% | 93% | 93% |
| C5 エラー分類(try-catch) | 7% | 60% | 60% |
| C7 型安全性（asキャスト） | 47% | 33% | 40% |
| C9 レスポンス統一 | 33% | 53% | 67% |
Zodバリデーションは、ガイドラインなしだと15回中1回も通らなかったのに、導入後は全件パスしました。AIはZodを「知っている」けれど、明示的に指示しないと書かない、という典型例です。
ディレクトリ構成（C8）も 26% → 93% と大きく改善。ここはガイドラインが効きやすい領域です。
Before/After diff: CRUD APIの例
ガイドライン導入前後でコードがどう変わるか、具体的に見てみましょう。
Before（ガイドラインなし）
// src/app/api/tasks/route.ts
export async function POST(request: Request) {
const body = await request.json();
const task = await db.task.create({
data: {
title: body.title, // ❌ バリデーションなし
description: body.description,
},
});
return Response.json(task); // ❌ レスポンス形式が独自
}
バリデーションなし、エラーハンドリングなし、レスポンス形式も独自。
After（CLAUDE.md導入後）
// src/app/api/tasks/route.ts
import { z } from "zod";
const createTaskSchema = z.object({
title: z.string().min(1).max(100),
description: z.string().optional(),
});
export async function POST(request: Request): Promise<Response> {
try {
const body = await request.json();
const parsed = createTaskSchema.safeParse(body);
if (!parsed.success) {
return Response.json(
{ error: { code: "VALIDATION_ERROR", message: parsed.error.message } },
{ status: 400 }
);
}
const task = await db.task.create({ data: parsed.data });
return Response.json({ data: task }, { status: 201 });
} catch (error) {
return Response.json(
{ error: { code: "INTERNAL_ERROR", message: "Internal server error" } },
{ status: 500 }
);
}
}
- ✅ Zodスキーマでバリデーション
- ✅ try-catchによるエラーハンドリング
- ✅
{ error: { code, message } }形式の統一レスポンス - ✅ 適切なHTTPステータスコード
ガイドラインに書いてあることがそのまま反映されています。「当たり前でしょ」と思うかもしれませんが、これが毎回・指示なしに揃うようになるのが大事なんです。
さらに上を目指す方へ: /ai-dev-os-check の紹介
CLAUDE.md導入で8.0点まで上がりましたが、細かい漏れはまだ残ります。今回の検証でも、revalidatePath の抜け、JWT_SECRET 未例外化、Cookie の Secure 属性漏れといった「動作確認では気づきにくいミス」が複数見つかりました。
これを自動検出・修正するのが /ai-dev-os-check です。Claude Code のカスタムスラッシュコマンドで、AIが生成したコードをAI自身がガイドラインに照らしてレビューします。CLAUDE.md導入後にこのコマンドを通すと 8.1点（+45%） まで改善できます。
仕組みの詳細・Compliance Reportの読み方・Hooksとの連携（コミット前の自動チェック設定）まで知りたい方は、次の記事で全部解説します。
→ [/ai-dev-os-check 実践ガイド — 動的チェックでAIコードを自動レビューする方法]
よくある失敗と対処法
導入してみて「あれ、うまくいかない」と感じたときのチェックポイントです。
1. CLAUDE.md を肥大化させてしまう
失敗: すべてのガイドラインをCLAUDE.mdに直接書き込み、200行を超えたあたりから品質が下がった。
なぜ起きるか: LLMはコンテキストが長くなるほど、前半の内容を薄く読む傾向があります。
対処: CLAUDE.md 本体は短く保ち、参照形式で別ファイルに分割する。今回の構成のように「docs/ai-dev-os/ 以下のファイルを参照してください」と書くだけで、AIは必要なときに読みに行きます。参照ファイルは3〜7本に絞るのがちょうどいいです。
（参考: CLAUDE.mdを200行書いたら品質が79点に下がった話）
2. ガイドラインのパスが間違っている
失敗: CLAUDE.md に書いたパスが実際のファイル構成と合っておらず、AIがガイドラインを読めていない。
対処: docs/ai-dev-os/ のパスは正確に記載する。迷ったら ls docs/ai-dev-os/ で実際の構造を確認してからCLAUDE.mdに書く。
3. サブモジュールの更新を忘れる
失敗: ai-dev-os をサブモジュールとして追加したのに、ガイドラインが古いまま。
対処: 定期的に git submodule update --remote を実行する。チームで使う場合は、git pull 後に git submodule update をセットで実行する習慣をつけておくと安心です。
この手法の限界
正直に書いておきます。「これで全部解決するわけではありません」。
改善が限定的だった項目
| 項目 | Before | After | After+Check |
|---|---|---|---|
| C7 型安全性（asキャスト） | 47% | 33% | 40% |
| C5 エラー分類（try-catch） | 7% | 60% | 60% |
| C9 レスポンス統一 | 33% | 53% | 67% |
C7（型安全性）はAfterで悪化しました。ガイドラインで推奨している ActionResult パターンが、逆に as キャストを誘発するケースがあったためです。ガイドライン自体が完璧ではないということです。
C5（エラー分類）は全条件で改善が限定的で、最終的に60%止まり。「適切なエラー分類をする」という指示は、AIにとって解釈の幅が広く、ガイドラインだけでは揃えにくい領域です。
C9（レスポンス統一）も After+Check でも67%。すべてのエンドポイントで統一するのはなかなか難しい。
根本的な限界
- ガイドラインは「確率を上げる」ものであり、毎回100%の再現性は保証されません
- プロンプトの内容・長さ・コンテキストによって同じガイドラインでも結果はブレます
- AIのモデルバージョンが変わると、同じCLAUDE.mdでもスコアが変動する可能性があります
「ガイドラインを入れたから大丈夫」ではなく、最終的な確認は人間が行う前提は変わりません。
まとめ
- 3プロンプト × 5回 × 3条件 = 45試行で検証した結果、CLAUDE.md導入で**平均5.6→8.0点（+43%）**の改善
- 最大の効果はZodバリデーション 0% → 100%。「知っているけど書かない」問題はガイドラインで解決できる
- 導入時間は実測5〜10分。サブモジュール追加＋CLAUDE.md作成だけで効果が出る
- さらに
/ai-dev-os-checkを組み合わせると、revalidatePath漏れやCookieのSecure属性など細かい漏れを自動検出・修正できる - ただし、型安全性（C7）はAfterで悪化するケースもあり、「確率を上げる」手法であることは忘れずに
皆さんはどうやってAI生成コードの品質を担保していますか？
コードレビュープロセス、プロンプトのテンプレート、チームでの運用ルールなど、ぜひコメントで教えてください！
GitHub リポジトリ: AI Dev OS（MIT License）
関連記事