本シリーズ（全3回）: ① OSS導入編（本記事）→ ② [Two-Tier Context Strategy 編] → ③ [チーム展開・運用編]
半年ほどAIコーディングを使い込んできて、ずっと引っかかっていたことがあります。
「ユーザー一覧を取得する関数を書いて」——同じ指示なのに、昨日は getUsers()、今日は fetchUserList()、明日は loadAllUsers()。関数名すら毎回バラバラ。
最初は「まあAIだし」と流していました。でもプロジェクトが大きくなるにつれ、命名規則もエラー処理もセキュリティ対策も全部ガチャ状態。手直しのコストがバカにならなくなってきました。
「AIの性能が上がれば解決するだろう」——そう思っていた時期もありました。でも、モデルが新しくなっても状況は変わりませんでした。
原因はAIの性能ではなく、「AIに渡している情報」の設計でした。
チームが当たり前だと思っている規約や設計判断、いわゆる「暗黙知」。これをAIに構造的に渡せていないから、毎回「惜しいけど違う」コードが出てきます。
この問題を解決するために、OSSを7リポジトリ公開しました。Claude Code / Cursor / Kiro の3ツールに対応しています。
本記事は Next.js を主な例に使っていますが、AI Dev OS の中心部分（セキュリティ・命名規則・エラーハンドリング等）はフレームワークに依存しません。Python（FastAPI / CLI）向けのルールセットもあり、他言語にも拡張できる設計です。
自分がやったこと — AI Dev OS を作った
じゃあどうすればいいか。自分がたどり着いた答えは、「ルールをAIに渡す仕組み」自体を設計する ことです。
普段の開発では、チームメンバーに「うちはこういうルールでやってるよ」と口頭やドキュメントで伝えますよね。AI Dev OS は、それと同じことをAIに対して構造的にやるための仕組み（フレームワーク）になります。
どんな仕組み？ — 4層モデル
ルールには「長く変わらないもの」と「すぐ古くなるもの」があります。AI Dev OS はルールを寿命ごとに4つの層に分けて整理しています。
┌─────────────────────────────────────────────┐
│ L1: 設計哲学（2〜5年変わらない） │
│ → 「正確性・観測可能性・実用性」を重視する等 │
│ │
│ L2: 技術判断の基準（1〜3年） │
│ → どのライブラリを使うか、設計の方針等 │
│ │
│ L3: 具体的なルール（6〜12ヶ月） │
│ → コーディング規約・セキュリティ・テストの書き方│
│ │
│ L4: ツール固有の設定（2〜4ヶ月） │
│ → Claude Code / Cursor / Kiro 用の設定 │
└─────────────────────────────────────────────┘
なぜ分けるの？ → 寿命が違うルールを1つのファイルに混ぜると、ツールの設定を更新するときに設計哲学まで巻き添えで壊してしまうリスクがあるからです。
7リポジトリの全体像
この4層を、役割ごとに7つのリポジトリで構成しました。
「全部入れなきゃダメ？」→ いいえ。 自分が使うツールと言語に合わせて、必要なものだけ組み合わせます。
| # | リポジトリ名 | ひとこと説明 |
|---|---|---|
| 1 | ai-dev-os | 全体の仕様・理論・入門ガイド（まずはここから） |
| 2 | ai-dev-os-rules-typescript | TypeScript / Next.js 向けのルール集 |
| 3 | ai-dev-os-rules-python | Python / FastAPI 向けのルール集 |
| 4 | ai-dev-os-plugin-claude-code | Claude Code 用の設定 |
| 5 | ai-dev-os-plugin-kiro | Kiro 用の設定 |
| 6 | ai-dev-os-plugin-cursor | Cursor 用の設定 |
| 7 | ai-dev-os-cli | セットアップを自動化するコマンドラインツール |
組み合わせ例:
- TypeScript × Claude Code →
ai-dev-os+rules-typescript+plugin-claude-code - Python × Cursor →
ai-dev-os+rules-python+plugin-cursor - 複数ツール併用 → 共通部分は1回だけ、Plugin だけツール分追加
3ツール比較 + 導入手順
どのツールでもルールの中身（L1〜L3）は共通です。違うのはツール固有の設定（L4）だけなので、ツールを乗り換えても、ルールを書き直す必要がありません。
| Claude Code | Cursor | Kiro | |
|---|---|---|---|
| 統合方法 | Git Submodule（別リポジトリを自分のプロジェクト内に組み込む仕組み） で .claude/plugins/ に配置 |
.cursor/rules/ にルールファイル配置 |
.kiro/ に Steering Rules（Kiroのルール設定機能） 配置 |
| コンポーネント | 9 Skills（Claude Codeに追加できるカスタムコマンド） + 3 Sub-agents（メインのAIが呼び出す補助AI） + 4 Hooks（特定のタイミングで自動実行されるスクリプト） | 16 Cursor Rules（.mdc形式（Cursor独自のルールファイル形式）） | 16 Steering Rules + Hooks |
| 設定ファイル |
CLAUDE.md（Claude Codeの設定ファイル） |
.cursorrules / .cursor/rules/
|
Kiro Steering Rules |
| 詳細手順 | ステップ2へ | ステップ3へ | ステップ4へ |
自分が使うツールのセクションだけ読めばOKです。 ステップ1（共通セットアップ）の後、ステップ2〜4はお使いのツールだけお読みください。
【ステップ1】インストール — 3ツール共通
前提条件
- Git がインストール済みであること
- 対象プロジェクトが Git リポジトリであること
CLI を使った自動セットアップ（推奨・約5分）
最も簡単な方法です。コマンド1つで必要なものが揃います。
# CLI のインストール
npm install -g ai-dev-os-cli
# プロジェクトのルートで実行
ai-dev-os init
ai-dev-os init を実行すると、対話形式で聞かれます。
- 言語/フレームワーク — TypeScript (Next.js) / Python (FastAPI) / etc.
- AIツール — Claude Code / Cursor / Kiro（複数選択可）
- ガイドラインレベル — Minimal（最小限）/ Standard（標準）/ Full（フル）
選択に応じて、必要なリポジトリが自動で追加されます。
手動セットアップ（CLIを使わない場合）
# Core リポジトリを追加
git submodule add https://github.com/yunbow/ai-dev-os.git docs/ai-dev-os
# 言語別ルールセットを追加（TypeScript の例）
git submodule add https://github.com/yunbow/ai-dev-os-rules-typescript.git docs/ai-dev-os-rules
【ステップ2】Claude Code 導入手順
Claude Code では、CLAUDE.md（設定ファイル）+ docs/（ルール本体）の2層構造で設定します。
CLAUDE.md とは？ Claude Code がプロジェクトのルールを読み取るための設定ファイルです。プロジェクトのルートに置きます。
2-1. プラグインを追加
git submodule add https://github.com/yunbow/ai-dev-os-plugin-claude-code.git .claude/plugins/ai-dev-os
2-2. CLAUDE.md を作成する — ここが一番ハマったポイント
自分が一番失敗したのがここです。最初はCLAUDE.md にルールを全部書き込んでいました。でも書けば書くほど品質が下がりました。
実際にベンチマーク（品質テスト）を取ってみた結果がこちらになります。
| CLAUDE.md の書き方 | 品質スコア |
|---|---|
| ルールなし（何も書かない） | 84点 |
| ルールを全部書く（約30ファイル分） | 79点（悪化！） |
| 厳選した10ファイルを参照 | 85点 |
| 3ファイルだけ参照 + 動的チェック | 96.9点 |
スコアはセキュリティ・エラーハンドリング・バリデーション（入力値が正しいかチェックすること）等の9項目100点満点で評価。詳細は ベンチマーク設計書 を参照。
自分も最初は信じられませんでした。 ルールを増やせば品質が上がると思い込んでいました。でも実際には、情報が多すぎてAIが「どれが重要かわからない」状態になり、何も守れなくなっていたんです。
最高スコアを出したのは、たった3ファイルだけ参照する構成です。
# {Project Name} - Claude Code Guidelines
Write code for this project following AI DEV OS.
When there are conflicts, higher sections take priority.
## Development Guidelines
### 1. Security（最重要）
- ai-dev-os/03_guidelines/common/security.md
### 2. Validation
- ai-dev-os/03_guidelines/common/validation.md
### 3. Project Structure
- ai-dev-os/03_guidelines/frameworks/nextjs/project-structure.md
さらに、この3ファイル構成に 動的チェック（/ai-dev-os-check） を組み合わせます。動的チェックとは、AIがコードを書いた後にルール違反がないか自動で確認する仕組みのことです。
「少ないルール + 書いた後のチェック」 この組み合わせが最強でした（詳しくは次回記事で解説）。
プロジェクトに合わせてカスタマイズ: 上の3ファイルはベンチマークで最も高スコアだった組み合わせです。ご自身のプロジェクトに合わせて入れ替えてOK。ポイントは「3〜5ファイルに絞る」ことです。
パス調整: ファイルの配置場所によってパスが変わります。docs/ai-dev-os/ に配置した場合は docs/ai-dev-os/03_guidelines/... のようになります。
テンプレートには 優先順位ルール も含まれています。ルールが矛盾したときに「どちらを優先するか」をAIに教えるためのものです。
## Priority Resolution Rules (CSS Specificity Style)
1. [Highest] frameworks/{stack}/* ← 最も具体的なルール
2. [High] common/* ← 共通だが具体的
3. [Medium] project-specific/* ← プロジェクト固有
4. [Low] 02_principles/* ← 抽象的な原則
5. [Lowest] 01_philosophy/* ← 最も抽象的
2-3. ルール本体の場所を確認する
CLAUDE.md から参照されるルールの本体は、docs/ai-dev-os/03_guidelines/ に入っています。
docs/ai-dev-os/03_guidelines/
├── common/ # どの言語でも使える共通ルール
│ ├── code.md # コーディング規約
│ ├── naming.md # 命名規則
│ ├── validation.md # 入力チェック
│ ├── error-handling.md # エラー処理
│ ├── security.md # セキュリティ
│ ├── testing.md # テストの書き方
│ └── ...
│
└── frameworks/
└── nextjs/ # Next.js 固有のルール
├── overview.md # 技術スタック
├── routing.md # ルーティング
├── api.md # API設計
└── ...
AIは必要なときに必要なファイルだけを読みます。全部を一度に読まないので、トークン（AIが処理するテキストの単位。日本語1文字≒1〜2トークン）を圧迫しません。
2-4. Skills と Hooks の確認
Claude Code プラグインに含まれる主要 Skills（クリックで展開）
| Skill | できること |
|---|---|
/ai-dev-os-init |
プロジェクトへの初期セットアップ |
/ai-dev-os-check |
コードがルールに従っているか自動チェック |
/ai-dev-os-extract |
コードレビューからルールを自動抽出 |
/ai-dev-os-audit |
ルール全体の整合性チェック |
/ai-dev-os-evolve |
ルールの更新提案 |
/ai-dev-os-plan |
実装計画の作成 |
/ai-dev-os-why |
「なぜこのルールがあるの？」に回答 |
/ai-dev-os-ticket |
タスクチケットの作成 |
/ai-dev-os-report |
ルール準拠レポートの出力 |
【ステップ3】Cursor 導入手順
3-1. プラグインを配置
git submodule add https://github.com/yunbow/ai-dev-os-plugin-cursor.git .cursor/rules/ai-dev-os
3-2. .cursorrules を作成
# AI Dev OS Guidelines
@import .cursor/rules/ai-dev-os/
## Project-Specific Rules
- Follow the guidelines in docs/ai-dev-os/03_guidelines/
- Framework-specific rules take precedence over common rules
3-3. ルールファイルの確認
.cursor/rules/ai-dev-os/ に 16 個の .mdc 形式のルールファイルが配置されます。Cursor はこれらを自動的に読み込み、コード生成時に参照します。
【ステップ4】Kiro 導入手順
4-1. プラグインを配置
git submodule add https://github.com/yunbow/ai-dev-os-plugin-kiro.git .kiro/ai-dev-os
4-2. Steering Rules の設定
.kiro/
├── steering/
│ └── ai-dev-os/ # ← 追加されたルール
│ ├── coding.md
│ ├── security.md
│ ├── naming.md
│ └── ...
└── specs/ # Kiro の Spec 機能と連携可能
4-3. Spec との連携
Kiro の Spec 機能（要件定義→タスク分解）を使う場合、AI Dev OS を設定しておくと、要件定義の段階からルールが効くようになります。上流工程から品質を担保できるのが Kiro × AI Dev OS の強みです。
導入後の確認 — 自分が最初にやった5つのチェック
導入直後、「本当に効いてるのか？」が一番不安でした。以下は自分が実際に試した確認方法です。
チェック1: 命名が一貫しているか
やること: 「ユーザー一覧を取得する関数を書いて」と3回指示する。
| Before | After | |
|---|---|---|
| 関数名 | 毎回バラバラ（getUsers / fetchUserList / loadAllUsers） |
毎回同じ命名ルールに従う |
| 戻り値の型 |
any や型なし |
明示的な型定義 |
チェック2: エラー処理がちゃんとしているか
やること: 「APIエンドポイントを実装して」と指示する。
-
Before:
catchの中でconsole.log(error)だけ - After: エラーコード分類・適切なHTTPステータスコード付き
チェック3: セキュリティが考慮されているか
やること: 「フォームの入力を処理する関数を書いて」と指示する。
- Before: ユーザーの入力をそのまま使う（危険！）
- After: 入力チェック（バリデーション）が自動的に含まれる
チェック4: ファイルの置き場所が正しいか
やること: 「新しいAPIルートを追加して」と指示する。
- Before: AIが勝手にファイルを配置
- After: プロジェクトのディレクトリ規約に沿った配置
チェック5: 何度やっても同じ品質か
やること: 同じ指示を3回繰り返す。
- Before: 毎回違うコード
- After: 3回とも同じルールに準拠した構造
目安: 5項目中4項目以上で改善が見られれば成功です。改善がなければ、次の「よくある失敗パターン」をチェック。
よくある失敗パターンと直し方
失敗1: CLAUDE.md にルールを全部書いてしまった
こうなる: AIが後半のルールを無視する。
なぜ: 情報が多すぎて、AIが優先度を判断できなくなる。
直し方: CLAUDE.md を「目次」にする。ルール本体は別ファイルに移し、CLAUDE.md には参照パスだけ書く。50行以内が目安。
- ## セキュリティルール
- - SQLインジェクション対策として…
- - XSS対策として…
- - ... (50行のルール)
+ ## セキュリティ
+ - docs/ai-dev-os/03_guidelines/common/security.md
失敗2: ファイルパスが間違っている
こうなる: AIがルールの存在を認識しない。
直し方: ターミナルで実際のパスを確認する。
ls docs/ai-dev-os/03_guidelines/common/
ls docs/ai-dev-os/03_guidelines/frameworks/nextjs/
失敗3: Submodule の初期化を忘れている
こうなる: docs/ai-dev-os/ フォルダが空。
直し方:
git submodule update --init --recursive
失敗4: ルールの優先順位を書いていない
こうなる: ルールが矛盾したとき、AIがどちらに従うか毎回変わる。
直し方: CLAUDE.md に優先順位を明記する。
## ガイドライン優先順位（上が最優先）
1. frameworks/nextjs/* — フレームワーク固有ルール
2. common/* — 共通ルール
3. project-specific/* — プロジェクト固有ルール
正直、解決しないこともある
万能ツールではないので、正直に限界も書いておきます。
- ビジネスロジックの正しさは保証できない: AI Dev OS が担保するのは「コードの書き方」であって「何を作るか」ではありません。要件の誤解や仕様の抜けは、別途レビューが必要です
- 最初のルール設計にはコストがかかる: 自分のプロジェクトに合わせたルール調整に、最初は半日〜1日かかりました。ただし一度作れば、その後はメンテナンスコストはかなり低いです
- AIモデルのアップデートで効果が変わる可能性がある: 今のベンチマーク結果は Claude Sonnet 4.6 での測定です。モデルが変われば最適なファイル数も変わるかもしれません。たぶん半年後にはまた調整が必要になると思います
- チーム全員が使わないと効果が薄い: 自分だけ導入しても、他のメンバーがルールなしでAIを使っていると、コードベース全体の一貫性は保てません（これは次回「チーム展開編」で扱います）
まとめ + 次に読む記事
AI Dev OS を導入すると、こう変わります。
- 一貫性: 同じ指示に対して、毎回同じ構造・命名のコードが生成される
- セキュリティ: 入力チェックや認証処理がルールに基づいて自動的に含まれる
- チーム展開: ルールを共有すれば、メンバー全員のAIが同じ品質でコードを書く
- ツール非依存: Claude Code / Cursor / Kiro のどれでも、ルールの中身は共通
導入にかかる時間
| 方法 | 所要時間 |
|---|---|
| CLI 自動セットアップ | 約5分 |
| 手動セットアップ | 約15分 |
| CLAUDE.md のカスタマイズ含む | 約30分 |
次回記事
この記事では「入れ方」を書きました。でも一番面白い（そして自分が一番ハマった）のは、「CLAUDE.md をどう設計するか」です。200行書いて品質79点だった失敗談から、96.9点に至るまでの過程を次回で共有します。
質問・フィードバックは GitHub Issues またはコメント欄でお待ちしています。
皆さんはAIが書くコードの品質、どう管理していますか？ 「自分はこうしてる」「こういう問題で困ってる」など、ぜひコメントで教えてください。自分も試行錯誤中なので、情報交換できると嬉しいです。
GitHub リポジトリ: AI Dev OS（MIT License）
関連記事