# 五層品質モデル > 汎用ガイド | 全プロジェクト共通 --- ## 概要 五層品質モデルは、AI生成物（コード、ドキュメント、設定等）の品質を段階的に評価するフレームワークである。下層から順に検証することで、効率的な品質保証を実現する。 ``` ┌─────────────────────────────────────────────────┐ │ L4: 品質性 (Quality) │ │ 「高品質か？」 │ ├─────────────────────────────────────────────────┤ │ L3: 機能性 (Functionality) │ │ 「正しく動作するか？」 │ ├─────────────────────────────────────────────────┤ │ L2: 実行性 (Executability) │ │ 「実行できるか？」 │ ├─────────────────────────────────────────────────┤ │ L1: 正当性 (Validity) │ │ 「形式的に正しいか？」 │ ├─────────────────────────────────────────────────┤ │ L0: 存在性 (Existence) │ │ 「存在するか？」 │ └─────────────────────────────────────────────────┘ ``` --- ## 1. 各層の詳細 ### L0: 存在性 (Existence) **問い**: プロジェクトが存在し、基本構造があるか？ | チェック項目 | 配点 | 説明 | | ------------------------ | ---- | --------------------------------- | | プロジェクトディレクトリ | 30 | ディレクトリが存在する | | package.json | 25 | Node.jsプロジェクトとして認識可能 | | Git管理 | 20 | .gitディレクトリが存在 | | CLAUDE.md | 15 | Agent設定が存在 | | srcディレクトリ | 10 | ソースコードの配置場所 | **合格基準**: 50点以上 **失敗時の対応**: ```bash # プロジェクト初期化 mkdir my-project && cd my-project npm init -y git init touch CLAUDE.md mkdir src ``` --- ### L1: 正当性 (Validity) **問い**: コードが形式的に正しいか？ | チェック項目 | 配点 | 説明 | | -------------- | ---- | ------------------- | | TypeScript設定 | 50 | tsconfig.jsonが存在 | | 依存関係 | 30 | node_modulesが存在 | | Lintエラー | 20 | ESLintエラーがない | **合格基準**: 60点以上 **失敗時の対応**: ```bash # 依存関係のインストール npm install # TypeScriptエラーの確認 npx tsc --noEmit # Lintエラーの確認 npm run lint ``` --- ### L2: 実行性 (Executability) **問い**: ビルドが成功し、起動できるか？ | チェック項目 | 配点 | 説明 | | ---------------- | ---- | ------------------------- | | ビルドスクリプト | 30 | package.jsonにbuildが定義 | | ビルド成果物 | 40 | .next, dist, buildが存在 | | 起動スクリプト | 30 | dev/startが定義 | **合格基準**: 60点以上 **失敗時の対応**: ```bash # ビルド実行 npm run build # 開発サーバー起動 npm run dev ``` --- ### L3: 機能性 (Functionality) **問い**: テストが通過し、機能が動作するか？ | チェック項目 | 配点 | 説明 | | ------------------ | ---- | ---------------------------- | | テストディレクトリ | 30 | **tests**, tests, testが存在 | | テストスクリプト | 20 | package.jsonにtestが定義 | | テスト通過率 | 50 | テストが成功する | **合格基準**: 50点以上 **失敗時の対応**: ```bash # テスト実行 npm run test # テストファイル作成 mkdir __tests__ touch __tests__/example.test.ts ``` --- ### L4: 品質性 (Quality) **問い**: コードが高品質か？ | チェック項目 | 配点 | 説明 | | ---------------- | ---- | ---------------------- | | README.md | 15 | プロジェクト説明が存在 | | CLAUDE.md | 15 | Agent設定が充実 | | ESLint設定 | 10 | Lint設定ファイルが存在 | | Prettier設定 | 10 | フォーマット設定が存在 | | ドキュメント | 25 | docsディレクトリ等 | | コードカバレッジ | 25 | テストカバレッジ基準 | **合格基準**: 50点以上 --- ## 2. スコアリング ### 2.1 総合スコア計算 各層に重み付けを適用： | 層 | 重み | 理由 | | --- | ---- | ---------------------- | | L0 | 10% | 基本的な前提条件 | | L1 | 20% | 形式的正しさは重要 | | L2 | 30% | 実行できることが最重要 | | L3 | 25% | 機能の正しさ | | L4 | 15% | 品質は付加価値 | ``` 総合スコア = Σ(層スコア × 重み) ``` ### 2.2 品質レベル判定 | レベル | スコア範囲 | 状態 | | ---------- | ---------- | ------ | | Excellent | 90-100 | 優秀 | | Good | 80-89 | 良好 | | Acceptable | 60-79 | 許容 | | Warning | 40-59 | 要注意 | | Critical | 0-39 | 重大 | --- ## 3. ゲート方式 下層が未通過の場合、上層はスキップされる： ``` L0 未通過 → L1〜L4 すべてスキップ L1 未通過 → L2〜L4 スキップ L2 未通過 → L3〜L4 スキップ L3 未通過 → L4 スキップ ``` **理由**: - 存在しないものの品質は測定不能 - ビルドできないコードのテストは無意味 - 効率的な問題特定が可能 --- ## 4. 改善の優先順位 ### 4.1 Critical/Warning状態の場合 ``` 1. L0の問題を解決（存在性の確保） 2. L1の問題を解決（形式的正しさ） 3. L2の問題を解決（実行可能性） 4. L3/L4は後回し ``` ### 4.2 Acceptable状態の場合 ``` 1. L3のテスト充実 2. L4のドキュメント整備 3. コードカバレッジ向上 ``` --- ## 5. mirrorでの活用 ### 5.1 ダッシュボード確認 ``` http://localhost:3000/ # ホーム（概要） http://localhost:3000/quality # 詳細ダッシュボード http://localhost:3000/projects # Qualityタブ http://localhost:3000/evolution # 進化×品質相関 ``` ### 5.2 優先アクションの確認 mirrorは自動的に優先対応を提案： - Critical/Warningプロジェクトを特定 - 具体的な改善アクションを表示 --- ## 6. 原則 ### 6.1 鏡であれ、門番であるな 品質システムは： - 状態を映し出す（鏡） - 気づきを促す（問い） - 強制はしない（自律を尊重） ### 6.2 監視ではなくサポート 目的は： - 問題の早期発見 - 改善への道筋提示 - プロジェクト横断パターンの検出 --- ## 参照 - AI Agent運用規約 - Git・GitHub運用ガイド - 品質システム設計