コードのAI可読性を分析し、生成AIがバグ修正や変更を行う際に苦戦する原因となる問題を特定するスキル。 以下の場合に使用する： (1) 「AIが修正しやすいコードか分析して」「AI可読性を診断して」と依頼された時 (2) バグ修正や変更作業が難航している原因を調査したい時 (3) コードベースのAIフレンドリー度を評価したい時 (4) リファクタリング優先度を決めたい時 分析観点：コンテキストウィンドウ問題、命名・表現問題、構造・設計問題、テスト・検証問題、ドキュメント問題、LLM特有の苦手パターン
Analyzes code for AI readability issues that cause bugs and difficult changes. Use when asked to diagnose AI-friendliness or when troubleshooting stalled refactoring tasks.
/plugin marketplace add CAPHTECH/claude-marketplace/plugin install caphtech-plugin@caphtech-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
生成AIがコードを理解・修正する際に障壁となる問題を特定し、改善提案を行う。
1. 対象特定 → 2. 6観点分析 → 3. 重大度評価 → 4. 改善提案
ユーザーが指定した箇所、または作業中に問題が発生した箇所を特定する。
各観点について問題を検出し、具体的な箇所を特定する。
LLMのコンテキストウィンドウ制限に関連する問題。
| チェック項目 | 検出パターン |
|---|---|
| 暗黙的依存関係 | import文が分散、型定義が遠い、暗黙のグローバル参照 |
| 循環依存 | A→B→C→A のような依存ループ |
| グローバル状態 | グローバル変数、シングルトンの多用、隠れた副作用 |
| ファイルサイズ | 300行超のファイル、1000行超のモジュール |
コードの意図が読み取りにくい命名・表現。
| チェック項目 | 検出パターン |
|---|---|
| 一貫性のない命名 | 同概念に複数名（user/member/account）、命名規則の混在 |
| 略語・省略 | calcTtlPrc、idx、tmp等の意味不明な略語 |
| マジックナンバー | if (status === 3)、timeout: 86400000 |
| 曖昧な名前 | data、info、result、handle等の汎用名 |
コードの構造や設計に起因する問題。
| チェック項目 | 検出パターン |
|---|---|
| 責務の混在 | 1関数が複数処理、God Object、Fat Controller |
| 過度な抽象化 | 5層超の継承、過剰なDI、追跡困難なメタプログラミング |
| 不十分な抽象化 | コピペコード、似た処理の散在、DRY違反 |
| 深いネスト | 4段超のif/else、コールバック地獄 |
| 長い関数 | 50行超の関数、引数5個超 |
修正の正しさを検証できない問題。
| チェック項目 | 検出パターン |
|---|---|
| テスト不足 | テストなし、カバレッジ低い、エッジケース未検証 |
| テストと実装の乖離 | テストが古い、モックが実装と不一致 |
| 環境依存 | 外部サービス必須、特定環境でのみ動作 |
| 実行困難 | セットアップ複雑、シークレット必須 |
コードの意図や仕様が不明な問題。
| チェック項目 | 検出パターン |
|---|---|
| コメントと実装の乖離 | 古いコメント、誤解を招くコメント |
| 型情報の欠如 | anyの多用、動的型付け、型ヒントなし |
| ADR/設計文書不在 | 設計理由不明、歴史的経緯不明 |
| 仕様の暗黙知 | ドキュメント化されていないビジネスルール |
LLMが特に苦手とするコードパターン。
| チェック項目 | 検出パターン |
|---|---|
| 生成コード混在 | minified JS、自動生成コード、バンドル済みファイル |
| 非標準パターン | 社内DSL、フレームワーク独自拡張、マクロ多用 |
| 時間・状態依存 | 競合状態、タイミング依存バグ、非決定的動作 |
| 外部システム依存 | API仕様の暗黙知、DBスキーマ、インフラ設定 |
| バイナリ/非テキスト | 画像埋め込み、バイナリプロトコル |
検出した問題に重大度を付与する。
| 重大度 | 基準 | 対応優先度 |
|---|---|---|
| 🔴 Critical | AI修正がほぼ不可能、重大なリスク | 即時対応 |
| 🟠 High | AI修正が困難、ミスしやすい | 優先対応 |
| 🟡 Medium | AI修正可能だが効率低下 | 計画的対応 |
| 🟢 Low | 軽微な改善余地 | 余裕時対応 |
以下の形式で分析結果を出力する。
## 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 | 危険（重大なリファクタリング必要） |