| name | readability-review |
| description | 「リーダブルコード」とミラーの法則（7±2の認知限界）に基づくコード可読性レビュー。 トリガーキーワード: "可読性", "readability", "読みやすさ", "理解しやすい", "understandable", "わかりやすい", "clear", "明確", "命名", "naming", "variable name", "変数名", "関数名", "function name", "ネスト", "nesting", "深いネスト", "deep nesting", "関数設計", "function design", "コメント", "comments", "複雑", "complex", "complexity", "難しい", "難読", "confusing", "Miller's Law", "ミラーの法則", "cognitive load", "認知負荷", "AI-generated", "premature", "over-engineering", "過剰設計", "unnecessary abstraction", "不要な抽象化"。 認知科学の原則と実践的パターンに基づいて、コードレビュー中に自動的にアクティブ化され、 可読性の問題を検出し改善を提案。命名/構造、制御フロー最適化、コメント戦略、 AIコードアンチパターン検出のセクションを含む。 |
| allowed-tools | Read, Grep, Glob, Task |
Readability Review - コード明確性と認知負荷分析
🎯 核心哲学
「コードは、他の誰かがそれを理解するのにかかる時間を最小化するように書かれるべき」
- その「他の誰か」は、6ヶ月後のあなた自身かもしれません
- 理解時間 > 記述時間
- 目標: 新しいチームメンバーが1分以内にコードを理解できる
🧠 科学的基盤: ミラーの法則
人間の認知能力は7±2項目に制限されています
コードがこれらの限界を超えると：
- 理解時間が指数関数的に増加
- エラー率が倍増
- 精神的疲労が加速
私たちの脳は、あまりにも多くの複雑さを一度に処理することができません。
推奨制限:
| コンテキスト | 理想 | 最大 |
|---|---|---|
| 関数の引数 | 3 | 5 |
| クラスのメソッド | 5 | 7 |
| 条件分岐 | 3 | 5 |
| 関数の長さ | 5-10行 | 15行 |
| ネストの深さ | 2 | 3 |
📚 セクションベースのコンテンツ
このスキルは、効率的なコンテキスト使用のために4つの専門セクションに分かれています：
📝 セクション1: 命名と構造の基礎
ファイル: `references/naming-structure.md` トークン: ~500 焦点: 変数/関数の命名、具体的 vs 抽象的、検索可能性
トリガー: naming, 命名, variable name, 変数名, function name, 関数名, concrete, abstract
カバー範囲:
- 誤解されない命名
- 具体的な命名より抽象的
- 検索可能で発音可能な名前
- 具体的 vs 汎用的な命名
🔀 セクション2: 制御フローと複雑性
ファイル: `references/control-flow.md` トークン: ~600 焦点: 制御フロー最適化、ネスト削減、ミラーの法則の適用
トリガー: nesting, ネスト, control flow, Miller's Law, complexity, guard clause, early return
カバー範囲:
- ネストの深さを最小化
- ガード節と早期リターン
- 複雑な条件の抽出
- ミラーの法則の適用（7±2制限）
- 関数の長さと複雑性のガイドライン
💬 セクション3: コメントと明確性
ファイル: `references/comments-clarity.md` トークン: ~400 焦点: コメント戦略、意図の伝達、コードの自己文書化
トリガー: comments, コメント, documentation, intent, 意図, obvious, clarity
カバー範囲:
- Whatではなく、Whyのコメント
- コード優先、コメント二の次
- 古いコメントの更新または削除
- コードを意図のように見せる
🤖 セクション4: AIコードアンチパターン
ファイル: `references/ai-antipatterns.md` トークン: ~500 焦点: AI生成コードにおける過剰設計パターンの検出
トリガー: AI, AI-generated, premature, over-engineering, unnecessary abstraction
カバー範囲:
- 時期尚早な抽象化の検出
- 単純なタスクに対する不必要なクラス
- 想像上の拡張性
- 検出と改善戦略
💡 実践的適用
自動トリガー例
ユーザー: "この関数は理解するのが難しい"
Readability Review Skillがトリガー →
「可読性の観点から改善しましょう：
1. 関数名の明確性
2. ネスト削減（現在4レベル）
3. 複雑な条件の抽出
4. ミラーの法則の適用（最大5パラメータ）
具体的な改善を提案します...」
一般的なシナリオ
関数のレビュー
- パラメータ数をチェック（≤5）
- 関数の長さを確認（5-15行）
- ネストの深さを評価（≤3レベル）
変数の命名
- 抽象的より具体的を確保
- 検索可能性をチェック
- 発音可能性を確認
コード構造
- ガード節を適用
- サブ問題を抽出
- 関数ごとに1つのタスク
AIコードレビュー
- 時期尚早な抽象化を検出
- 不必要なクラスにフラグ
- 過剰設計を特定
✨ 重要なポイント
- 明確性は巧妙さに勝る - シンプルなコードが勝つ
- 認知限界を尊重 - ミラーの法則（7±2）
- 名前が重要 - 具体的、検索可能、発音可能
- 制御フロー - ネストを最小化、ガード節を使用
- 賢くコメント - なぜを説明、何をではなく
最終テスト: 「新しいチームメンバーはこれを1分以内に理解できますか？」