CAPHTECH AI可読性分析（AI Readability Analysis）
生成AIがコードを理解・修正する際に障壁となる問題を特定し、改善提案を行う。
分析ワークフロー
1. 対象特定 → 2. 6観点分析 → 3. 重大度評価 → 4. 改善提案
Step 1: 分析対象の特定
ユーザーが指定した箇所、または作業中に問題が発生した箇所を特定する。
- 特定のファイル/関数が指定された場合：そこを重点分析
- 「このバグ修正がうまくいかない」等の場合：関連ファイル群を分析
- 指定なしの場合：現在の作業対象を分析
Step 2: 6観点からの分析
各観点について問題を検出し、具体的な箇所を特定する。
観点1: コンテキストウィンドウ問題
LLMのコンテキストウィンドウ制限に関連する問題。
- 暗黙的依存関係（import文が分散、型定義が遠い、暗黙のグローバル参照）
- 循環依存（A→B→C→Aのような依存ループ）
- グローバル状態（グローバル変数、シングルトンの多用、隠れた副作用）
- ファイルサイズ超過（300行超のファイル、1000行超のモジュール）
観点2: 命名・表現問題
コードの意図が読み取りにくい命名・表現。
- 一貫性のない命名（同概念に複数名、命名規則の混在）
- 意味不明な略語・省略（
calcTtlPrc、idx、tmp等） - マジックナンバー（
if (status === 3)、timeout: 86400000等） - 曖昧な汎用名（
data、info、result、handle等）
観点3: 構造・設計問題
コードの構造や設計に起因する問題。
- 責務の混在（1関数が複数処理、God Object、Fat Controller）
- 過度な抽象化（5層超の継承、過剰なDI、追跡困難なメタプログラミング）
- 不十分な抽象化（コピペコード、似た処理の散在、DRY違反）
- 深いネスト（4段超のif/else、コールバック地獄）
- 長い関数（50行超の関数、引数5個超）
観点4: テスト・検証問題
修正の正しさを検証できない問題。
- テスト不足（テストなし、カバレッジ低い、エッジケース未検証）
- テストと実装の乖離（テストが古い、モックが実装と不一致）
- 環境依存（外部サービス必須、特定環境でのみ動作）
- 実行困難（セットアップ複雑、シークレット必須）
観点5: ドキュメント問題
コードの意図や仕様が不明な問題。
- コメントと実装の乖離（古いコメント、誤解を招くコメント）
- 型情報の欠如（
anyの多用、動的型付け、型ヒントなし） - ADR/設計文書不在（設計理由不明、歴史的経緯不明）
- 仕様の暗黙知（ドキュメント化されていないビジネスルール）
観点6: LLM特有の苦手パターン
LLMが特に苦手とするコードパターン。
| チェック項目 | 検出パターン |
|---|---|
| 生成コード混在 | minified JS、自動生成コード、バンドル済みファイル |
| 非標準パターン | 社内DSL、フレームワーク独自拡張、マクロ多用 |
| 時間・状態依存 | 競合状態、タイミング依存バグ、非決定的動作 |
| 外部システム依存 | API仕様の暗黙知、DBスキーマ、インフラ設定 |
| バイナリ/非テキスト | 画像埋め込み、バイナリプロトコル |
Step 3: 重大度評価
検出した問題に重大度を付与する。
| 重大度 | 基準 | 対応優先度 |
|---|---|---|
| 🔴 Critical | AI修正がほぼ不可能、重大なリスク | 即時対応 |
| 🟠 High | AI修正が困難、ミスしやすい | 優先対応 |
| 🟡 Medium | AI修正可能だが効率低下 | 計画的対応 |
| 🟢 Low | 軽微な改善余地 | 余裕時対応 |
Step 4: 改善提案の出力
以下の形式で分析結果を出力する。総合評価は個々の重大度スケールに基づき、検出された問題のうち最も重大な重大度をそのまま採用する（数値スコアの算出は行わない）。
## AI可読性分析レポート
### 対象
- ファイル: `path/to/file.ts`
- 関連ファイル数: N個
### サマリー
- 🔴 Critical: X件
- 🟠 High: Y件
- 🟡 Medium: Z件
- 🟢 Low: W件
- **総合評価**: 🔴/🟠/🟡/🟢（検出された問題のうち最も重大な重大度）
### 検出された問題
#### 🔴 Critical
1. **[観点名] 問題タイトル** (`file:line`)
- 問題: 具体的な問題の説明
- 影響: AIがどう困るか
- 改善案: 具体的な改善方法
#### 🟠 High
...
### 推奨アクション
1. [最優先] 〜を修正
2. [優先] 〜をリファクタリング
3. ...
分析のヒント
- 作業難航時: 現在困っている具体的な箇所から分析開始
- 予防的分析: 変更前に対象範囲を分析し、リスク把握
- 段階的改善: Criticalから順に対応、一度に全部やらない