ai-readability-analysis

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: 命名・表現問題

コードの意図が読み取りにくい命名・表現。

チェック項目	検出パターン
一貫性のない命名	同概念に複数名（user/member/account）、命名規則の混在
略語・省略	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件
- **総合スコア**: NN/100

### 検出された問題

#### 🔴 Critical

1. **[観点名] 問題タイトル** (`file:line`)
   - 問題: 具体的な問題の説明
   - 影響: AIがどう困るか
   - 改善案: 具体的な改善方法

#### 🟠 High
...

### 推奨アクション

1. [最優先] 〜を修正
2. [優先] 〜をリファクタリング
3. ...

スコアリング基準

総合スコアは以下の計算式で算出：

スコア = 100 - (Critical × 20 + High × 10 + Medium × 5 + Low × 2)
最小値 = 0

スコア	評価
80-100	優良（AIフレンドリー）
60-79	良好（軽微な改善推奨）
40-59	要改善（修正推奨）
0-39	危険（重大なリファクタリング必要）

分析のヒント

• 作業難航時: 現在困っている具体的な箇所から分析開始
• 予防的分析: 変更前に対象範囲を分析し、リスク把握
• 段階的改善: Criticalから順に対応、一度に全部やらない