ln-610-code-comments-auditor

パス： ファイルパス（shared/、references/、../ln-*）はスキルリポジトリのルートを基準とします。CWD に見つからない場合は、この SKILL.md ディレクトリを探し、1 つ上の階層をリポジトリのルートとしてください。

コードコメント監査

コードコメントと docstring の品質を監査します。あらゆる技術スタックに対応します。

目的

• コメントが明白な WHAT ではなく WHY を説明していることを確認します
• コメント密度（15～20% の比率）を確認します
• 禁止コンテンツ（日付、著者名、過去の記録）を検出します
• docstring が関数シグネチャと一致していることを検証します
• コメントが現在のコードの状態と一致していることを確認します
• レガシーコメントとコメントアウトされたコードを特定します

呼び出し

• 直接： ユーザーがコードコメントの品質レビューを依頼します
• パイプライン： ln-100-documents-pipeline から呼び出されます（Phase 5、auditComments=true の場合）

ワークフロー

1. スキャン： すべてのソースファイルを検索します（技術スタックを自動検出）
2. 抽出： インラインコメントと docstring／JSDoc を解析します
3. 監査： 6 つのカテゴリのチェックを実行します（以下の「監査カテゴリ」を参照）
4. 採点： カテゴリごとに X/10 を算出します
5. コンテキスト検証： 検出結果を後処理でフィルタリングします（以下を参照）
6. レポート： 検出結果と推奨アクションを出力します

監査カテゴリ

#	カテゴリ	確認内容
1	WHY（理由）であり WHAT（内容）ではない	コメントが明白なコードの動作を繰り返すのではなく、その根拠を説明していること
2	密度（15～20%）	コメントとコードの比率が範囲内であり、コメントが多すぎたり少なすぎたりしないこと
3	禁止コンテンツなし	日付や著者名、過去の記録、コメント内のコード例がないこと
4	docstring の品質	関数シグネチャと一致していること、パラメーターが文書化されていること、戻り値の型が正確であること
5	現状との一致	コメントがコードの動作と一致し、古い参照がなく、例が実行可能であること
6	レガシーのクリーンアップ	文脈のない TODO、コメントアウトされたコード、非推奨に関する注記がないこと

コンテキスト検証（後処理フィルター）

必ず読むこと： shared/references/context_validation.md を読み込みます

ルール 1 とコメント固有のインラインフィルターを適用します：

FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
  # Rule 1: ADR/Planned Override
  IF finding matches ADR → advisory "[Planned: ADR-XXX]"

  # Comment-specific: Per-category density targets
  IF Cat 2 (Density) finding:
    Classify file by path:
    - test/ or tests/           → target density 2-10%
    - infra/ or config/ or ci/  → target density 5-15%
    - business/domain/services  → target density 15-25%
    Recalculate with per-category target instead of fixed 15-20%.
    If >50% comments are docstrings → calculate inline density separately.

  # Comment-specific: Complexity context for WHY-not-WHAT
  IF Cat 1 (WHY not WHAT) finding:
    - If file McCabe complexity > 15 → WHAT comments acceptable (complex logic)
    - If file in domain/ or business/ → explanatory comments OK (domain knowledge)

Downgraded findings → separate "Advisory" note in report.

出力形式

## Code Comments Audit Report - [DATE]

### Compliance Score

| Category | Score | Issues |
|----------|-------|--------|
| WHY not WHAT | X/10 | N obvious comments |
| Density (15-20%) | X/10 | X% actual (target: 15-20%) |
| No Forbidden Content | X/10 | N forbidden items |
| Docstrings Quality | X/10 | N mismatches |
| Actuality | X/10 | N stale comments |
| Legacy Cleanup | X/10 | N legacy items |
| **Overall** | **X/10** | |

### Critical Findings

- [ ] **[Category]** `path/file:line` - Issue description. **Action:** Fix suggestion.

### Recommended Actions

| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | Remove author name | src/X:45 | Forbidden |
| Medium | Update stale docstring | lib/Y:120 | Actuality |

採点アルゴリズム

必ず読むこと： 統一された採点式について、shared/references/audit_scoring.md を読み込みます。

重大度の対応付け：

問題の種類	重大度
コメント内の著者名、日付	CRITICAL
コメントアウトされたコードブロック	HIGH
古いコメント	HIGH
明白な WHAT を説明するコメント	MEDIUM
密度の逸脱が 5% 超	MEDIUM
軽微な密度の逸脱	LOW

参照ファイル

• コメントのルールとパターン：references/comments_rules.md

完了の定義

• すべてのソースファイルをスキャンしている（技術スタックを自動検出）
• インラインコメントと docstring／JSDoc を抽出し、解析している
• 6 つすべてのカテゴリ（WHY と WHAT の区別、密度、禁止コンテンツ、docstring、現状との一致、レガシー）をそれぞれ X/10 で採点している
• コメントとコードの密度比を算出し、15～20% の目標と比較している
• 重大な検出事項に、ファイル名：行番号、カテゴリ、修正案を記載している
• 優先度、アクション、場所、カテゴリを含む推奨アクションの表を作成している

重要な注意事項

• ルールではなくコードを修正する： 違反を通すためにルールファイル（_rules.md、_standards.md）を変更してはなりません。必ずコードを修正してください。
• コードが正： コメントがコードと矛盾している場合は、コメントの更新を指摘してください
• WHY ＞ WHAT： 明白な動作を説明するコメントは削除してください
• タスク ID は可： コメント内のタスク／ストーリー ID は、コードの追跡に役立ちます
• 汎用： あらゆる言語で動作し、コメント構文を自動的に検出します
• 基づくもの： Claude Code の comment-analyzer エージェントのパターン

---

バージョン： 3.0.0 最終更新日： 2025-12-23