AgentSkillsCN

ai-readability-analysis

分析代码的AI可读性，识别那些可能导致生成式AI在进行缺陷修复或代码变更时举步维艰的问题。 以下场景中可使用此技能： (1) 当用户请求“分析代码是否易于AI修改”或“诊断AI可读性”时； (2) 当您希望查明导致缺陷修复或代码变更困难的原因时； (3) 当您需要评估代码库的AI友好程度时； (4) 当您需要确定重构工作的优先级时。 分析视角：上下文窗口问题、命名与表述问题、结构与设计问题、测试与验证问题、文档问题，以及LLM特有的常见弱点。

SKILL.md
--- frontmatter
name: ai-readability-analysis
context: fork
description: |
  コードのAI可読性を分析し、生成AIがバグ修正や変更を行う際に苦戦する原因となる問題を特定するスキル。
  以下の場合に使用する：
  (1) 「AIが修正しやすいコードか分析して」「AI可読性を診断して」と依頼された時
  (2) バグ修正や変更作業が難航している原因を調査したい時
  (3) コードベースのAIフレンドリー度を評価したい時
  (4) リファクタリング優先度を決めたい時
  分析観点：コンテキストウィンドウ問題、命名・表現問題、構造・設計問題、テスト・検証問題、ドキュメント問題、LLM特有の苦手パターン

AI可読性分析（AI Readability Analysis）

生成AIがコードを理解・修正する際に障壁となる問題を特定し、改善提案を行う。

分析ワークフロー

code
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: 重大度評価

検出した問題に重大度を付与する。

重大度基準対応優先度
🔴 CriticalAI修正がほぼ不可能、重大なリスク即時対応
🟠 HighAI修正が困難、ミスしやすい優先対応
🟡 MediumAI修正可能だが効率低下計画的対応
🟢 Low軽微な改善余地余裕時対応

Step 4: 改善提案の出力

以下の形式で分析結果を出力する。

markdown
## 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. ...

スコアリング基準

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

code
スコア = 100 - (Critical × 20 + High × 10 + Medium × 5 + Low × 2)
最小値 = 0
スコア評価
80-100優良（AIフレンドリー）
60-79良好（軽微な改善推奨）
40-59要改善（修正推奨）
0-39危険（重大なリファクタリング必要）

分析のヒント

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