ai-readability-analysis
コードのAI可読性を分析し、生成AIがバグ修正や変更を行う際に苦戦する原因となる問題を特定するスキル。以下の場合に使用する：(1) 「AIが修正しやすいコードか分析して」「AI可読性を診断して」と依頼された時(2) バグ修正や変更作業が難航している原因を調査したい時(3) コードベースのAIフレンドリー度を評価したい時(4) リファクタリング優先度を決めたい時分析観点：コンテキストウィンドウ問題、命名・表現問題、構造・設計問題、テスト・検証問題、ドキュメント問題、LLM特有の苦手パターン
When & Why to Use This Skill
This Claude skill specializes in evaluating 'AI Readability'—the degree to which a codebase is optimized for Large Language Models to understand, debug, and modify. By analyzing six critical dimensions including context window constraints, structural design, and LLM-specific weaknesses, it identifies why AI agents may struggle with certain files and provides a prioritized roadmap for refactoring code to be more AI-friendly.
Use Cases
- Diagnosing AI failures: Identify specific structural or naming issues that cause AI coding assistants to fail when attempting to fix bugs or implement changes.
- AI-Readability Audit: Evaluate a legacy codebase to determine its 'AI-friendliness' before starting a major AI-assisted migration or refactoring project.
- Refactoring Prioritization: Use the severity-based scoring system to decide which modules require immediate structural improvement to maximize developer productivity with AI tools.
- Context Optimization: Detect implicit dependencies and global states that exceed LLM context windows, ensuring the AI has the necessary information to perform tasks accurately.
| name | ai-readability-analysis |
|---|---|
| description | | |
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から順に対応、一度に全部やらない