OpenSkillIndex← back to search
claude-code

Agent-almanac review-codebase

install
source · Clone the upstream repo
git clone https://github.com/pjt222/agent-almanac
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/review-codebase" ~/.claude/skills/pjt222-agent-almanac-review-codebase-2a5356 && rm -rf "$T"
manifest: i18n/ja/skills/review-codebase/SKILL.md
source content

Review Codebase

重大度評価された所見と修正順序の推奨事項を生成する多段階の深いコードベースレビュー。

review-pull-request
（差分に限定）や単一ドメインレビュー（
security-audit-codebase
、
review-software-architecture
）とは異なり、このスキルはプロジェクトまたはサブプロジェクト全体を1回のパスですべての品質次元をカバーする。

使用タイミング

  • プロジェクト全体またはサブプロジェクトのレビュー（PR限定ではない）
  • 新しいコードベースのオンボーディング — 何が存在し何に注意が必要かのメンタルモデルを構築する
  • 持続的な開発後の定期的な健全性チェック
  • アーキテクチャ、セキュリティ、コード品質、UXにわたるリリース前の品質ゲート
  • 出力をIssue作成やスプリント計画に直接フィードする場合

入力

  • 必須: 
    target_path
    — レビューするコードベースまたはサブプロジェクトのルートディレクトリ
  • 任意: 
    • scope
      — 実行するフェーズ：
      full
      （デフォルト）、
      security
      、
      architecture
      、
      quality
      、
      ux
    • output_format
      — 
      findings
      （テーブルのみ）、
      report
      （ナラティブ）、
      both
      （デフォルト）
    • severity_threshold
      — 含める最低重大度：
      LOW
      （デフォルト）、
      MEDIUM
      、
      HIGH
      、
      CRITICAL

手順

ステップ1: 棚卸し

範囲を確立しレビュー対象を特定するためにコードベースの目録を作成する。

  1. 言語/タイプ別にファイル数を数える：
    find target_path -type f | sort by extension
  2. 言語ごとの合計行数を計測する
  3. テストディレクトリを特定し、テストカバレッジを推定する（テストがあるファイルとないファイル）
  4. 依存関係の状態を確認する：ロックファイルの存在、古い依存関係、既知の脆弱性
  5. ビルドシステム、CI/CD設定、ドキュメントの状態を記録する
  6. 棚卸しをレポートの冒頭セクションとして記録する

期待結果： 事実に基づく目録 — ファイル数、言語、テストの存在、依存関係の健全性。まだ判断はしない。

失敗時： ターゲットパスが空またはアクセスできない場合は停止して報告する。特定のサブディレクトリがアクセスできない場合は記録して、利用可能なものでレビューを続行する。

ステップ2: アーキテクチャレビュー

構造的健全性を評価する：結合度、重複、データフロー、関心の分離。

  1. モジュール/ディレクトリ構造をマッピングし、主要なアーキテクチャパターンを特定する
  2. コードの重複を確認する — ファイル間での繰り返されるロジック、コピー&ペーストパターン
  3. 結合度を評価する — 単一の機能変更のために何ファイルを変更する必要があるか
  4. データフローを評価する — 層間（UI、ロジック、データ）に明確な境界があるか？
  5. デッドコード、未使用のエクスポート、孤立したファイルを特定する
  6. 一貫したパターンを確認する — コードベースは自身の規則に従っているか？
  7. 各所見を評価する：CRITICAL、HIGH、MEDIUM、またはLOW

期待結果： 重大度評価とファイル参照を含むアーキテクチャ上の所見リスト。一般的な所見：モード発信の重複、欠けている抽象化レイヤー、循環依存関係。

失敗時： コードベースが意味のあるアーキテクチャレビューに小さすぎる場合（5ファイル未満）は、これを記録してステップ3に進む。アーキテクチャレビューには構造を持つのに十分なコードが必要である。

ステップ3: セキュリティ監査

セキュリティの脆弱性と防御的コーディングのギャップを特定する。

  1. インジェクションベクタをスキャンする：HTMLインジェクション（
    innerHTML
    ）、SQLインジェクション、コマンドインジェクション
  2. 認証と認可のパターンを確認する（該当する場合）
  3. エラーハンドリングをレビューする — エラーが暗黙的に飲み込まれているか？エラーメッセージが内部情報を漏洩しているか？
  4. 依存関係のバージョンを既知のCVEに対して監査する
  5. ハードコードされたシークレット、APIキー、または認証情報を確認する
  6. Docker/コンテナのセキュリティを確認する：rootユーザー、公開されたポート、ビルドシークレット
  7. localStorage/sessionStorageの機密データストレージを確認する
  8. 各所見を評価する：CRITICAL、HIGH、MEDIUM、またはLOW

期待結果： 重大度、影響を受けるファイル、修正ガイダンスを含むセキュリティ所見リスト。CRITICAL所見にはインジェクションの脆弱性と露出したシークレットが含まれる。

失敗時： セキュリティ関連コードが存在しない場合（純粋なドキュメントプロジェクト）は、これを記録してステップ4に進む。

ステップ4: コード品質

保守性、可読性、防御的コーディングを評価する。

  1. 名前付き定数にすべきマジックナンバーとハードコードされた値を特定する
  2. コードベース全体で一貫した命名規則を確認する
  3. システム境界での欠けている入力バリデーションを見つける
  4. エラーハンドリングパターンを評価する — 一貫しているか？有用なメッセージを提供しているか？
  5. コメントアウトされたコード、TODO/FIXMEマーカー、不完全な実装を確認する
  6. テストの品質をレビューする — テストは動作をテストしているか、実装の詳細をテストしているか？
  7. 各所見を評価する：CRITICAL、HIGH、MEDIUM、またはLOW

期待結果： 保守性に焦点を当てた品質所見リスト。一般的な所見：マジックナンバー、一貫性のないパターン、欠けているガード。

失敗時： コードベースが生成またはminifyされている場合は、これを記録して期待を調整する。生成されたコードは手書きのコードとは異なる品質基準を持つ。

ステップ5: UXとアクセシビリティ（フロントエンドが存在する場合）

ユーザーエクスペリエンスとアクセシビリティ準拠を評価する。

  1. インタラクティブ要素のARIAロール、ラベル、ランドマークを確認する
  2. キーボードナビゲーションを確認する — Tabキーですべてのインタラクティブ要素に到達できるか？
  3. フォーカス管理をテストする — パネルが開閉した際にフォーカスが論理的に移動するか？
  4. レスポンシブデザインを確認する — 一般的なブレークポイントでテストする（320px、768px、1024px）
  5. カラーコントラスト比がWCAG 2.1 AA標準を満たしているか確認する
  6. スクリーンリーダーとの互換性を確認する — 動的なコンテンツの変更が通知されるか？
  7. 各所見を評価する：CRITICAL、HIGH、MEDIUM、またはLOW

期待結果： 該当する場合はWCAG参照を含むUX/a11y所見リスト。フロントエンドが存在しない場合、このステップは「N/A — フロントエンドコードが検出されませんでした」を生成する。

失敗時： フロントエンドコードが存在するがレンダリングできない場合（ビルドステップが欠けている）は、ソースコードを静的に監査し、実行時テストが不可能であったことを記録する。

ステップ6: 所見の統合

すべての所見を優先順位付けされたサマリーにまとめる。

  1. すべてのフェーズからの所見を1つのテーブルにマージする
  2. 重大度でソートする（CRITICALを最初に、次にHIGH、MEDIUM、LOW）
  3. 各重大度レベル内でテーマ別にグループ化する（セキュリティ、アーキテクチャ、品質、UX）
  4. 各所見について含める：重大度、フェーズ、ファイル、1行の説明、提案された修正
  5. 修正間の依存関係を考慮した推奨修正順序を生成する
  6. サマリー：重大度別の合計所見数、上位3つの優先事項、推定作業量レベル

期待結果： 列を持つ所見テーブル：

#
、
Severity
、
Phase
、
File(s)
、
Finding
、
Fix
。依存関係を考慮した修正順序の推奨事項（例：「テストを追加する前にアーキテクチャをリファクタリングする」）。

失敗時： 所見が生成されなかった場合は、これ自体が所見である — コードベースが例外的にクリーンか、またはレビューが浅すぎた。少なくとも1つのフェーズをより深く再検査する。

バリデーション

  • 要求されたすべてのフェーズが完了している（または正当化とともに明示的にスキップされている）
  • すべての所見に重大度評価がある（CRITICAL/HIGH/MEDIUM/LOW）
  • すべての所見が少なくとも1つのファイルまたはディレクトリを参照している
  • 所見テーブルが重大度でソートされている
  • 修正順序の推奨事項が所見間の依存関係を考慮している
  • サマリーに重大度別の合計数が含まれている
  • output_format
    に 
    report
    が含まれる場合、ナラティブセクションがテーブルに付随している

休憩によるスケーリング

レビューフェーズの間、特にフェーズ2〜5の間（異なる分析的観点が必要）には、チェックポイントとして 

/rest
を使用する。チェックポイント休憩（短く、移行的）は、あるフェーズの勢いが次のフェーズにバイアスをかけるのを防ぐ。ガイダンスはチェックポイント対フル休憩の 
rest
スキルの「Scaling Rest」セクションを参照する。

よくある落とし穴

  • 海を沸騰させる: 大きなコードベースのすべての行をレビューするとノイズが生じる。高インパクトな領域に焦点を当てる：エントリーポイント、セキュリティ境界、アーキテクチャの継ぎ目
  • 重大度のインフレ: すべての所見がCRITICALではない。悪用可能な脆弱性とデータ損失のリスクのためにCRITICALを予約する。ほとんどのアーキテクチャの問題はMEDIUMである
  • 細部に迷って全体像を見失う: 個々のコード品質の問題は体系的なパターンよりも重要度が低い。マジックナンバーが20ファイルに現れる場合、それは1つのアーキテクチャ上の所見であり、20の品質所見ではない
  • 棚卸しをスキップする: 棚卸し（ステップ1）は官僚的に見えるが、存在しないコードをレビューしたり、ディレクトリ全体を見逃したりすることを防ぐ
  • フェーズの混在: アーキテクチャレビュー中のセキュリティ所見、またはセキュリティ監査中の品質所見。懸念事項を混在させるのではなく、正しいフェーズのために記録する — より整理された所見テーブルを生成する

関連スキル

  • security-audit-codebase
    — review-codebaseのセキュリティフェーズが複雑な脆弱性を明らかにした際の深いセキュリティ監査
  • review-software-architecture
    — 特定のサブシステムの詳細なアーキテクチャレビュー
  • review-ux-ui
    — フェーズ5がカバーする範囲を超えた包括的なUX/アクセシビリティ監査
  • review-pull-request
    — 個々の変更の差分スコープレビュー
  • clean-codebase
    — このレビューで特定されたコード品質の修正を実装する
  • create-github-issues
    — 所見テーブルを追跡されたGitHub Issueに変換する