code-analyzer

code-analyzer

目的

プロジェクトの健全性について、何が壊れているのか、何にリスクがあるのか、何が整理されていないのか、何が不足しているのか、何を追加できるのかを、優先順位を付けて明確に伝えます。出力は構造化されたレポートであり、憶測の寄せ集めではありません。各指摘は実在するファイルを示し、懸念点をわかりやすく説明し、改善の方向性を提案します。

これは診断のスキルであり、リファクタリングのスキルではありません。監査の一環として、コードの編集、フォーマッターの実行、コミットは行わないでください。ユーザーがレポートを読み、修正する対象を明示的に選んだ場合にのみ、コードを変更します。

使用する状況

• ユーザーがプロジェクトのレビュー、監査、コード品質チェック、またはコードベース全般の問題点を尋ねた場合
• ユーザーがプロジェクト全体のセキュリティ問題、脆弱性、または強化策について尋ねた場合
• ユーザーが「何を改善できるか」または「次に何に取り組むべきか」を尋ねた場合
• 既存のプロジェクトに即した新機能のアイデアを求められた場合
• ハンガリー語での同等の表現：「nézd át」、「auditáld」、「találj hibákat」、「javasolj fejlesztéseket」

ユーザーが具体的なバグや機能を指定している場合（「このクラッシュを修正して」、「このエンドポイントを追加して」など）、このスキルの対象ではありません。そのまま対応してください。

前提条件

開始する前に、基本事項を確認します。

1. プロジェクトディレクトリ内にいること

git rev-parse --show-toplevel 2>/dev/null || pwd

Git リポジトリが望ましいですが（最近の履歴を参考情報として確認できるため）、必須ではありません。プロジェクトのルートを確認し、レポート内のすべてのパスの基点として使用してください。

2. 作業ツリーの状態

git status --porcelain 2>/dev/null

未コミットの変更があっても監査には問題ありません。何も変更しないためです。ユーザーがすでに作業中の可能性があることを念頭に置き、指摘に作業中のファイルが含まれる場合は、問題が今回の作業で生じたものか、以前から存在していたものかをユーザーが判断できるよう、明記してください。

ワークフロー

ステップ 1：監査の範囲を決める

プロジェクト全体の監査では、対象範囲に上限がありません。コードを読む前に、次の 3 つの観点から作業の内容を決めてください。

• 重点分野：すべての観点を対象にするか、1 つに絞るか（セキュリティ／品質／パフォーマンス／テスト／ドキュメント／アイデア）。
• 対象範囲：リポジトリ全体、サブディレクトリ、または変更されたファイルの一覧。非常に大規模なリポジトリ（ソースファイルが約 1000 個を超える）の場合は、範囲を明示してサンプリングしてください。実際の問題を見落とすような広く浅いレポートを作るのではなく、まず最も頻繁に編集されているモジュール、規模の大きいモジュール、または中核となるモジュールを選びます。
• 制約：除外すべきものがあるか（生成コード、ベンダー提供の依存関係、削除予定のレガシーモジュール、サードパーティ製 SDK など）。

対話型での使用（人間が参加している場合）：重点分野の引数が渡されていれば、それを使用します。渡されていない場合は、既定の計画を短いメッセージで伝え、ユーザーから異議がない限り続行します。長々とした聞き取りにしないでください。ユーザーが求めているのは指摘であり、開始前の打ち合わせではありません。

非対話型での使用（質問できる人間がいない場合。自動化、評価、パイプライン内で実行する場合など）：妥当な既定値（リポジトリ全体、すべての観点、標準の除外対象）を選び、質問する代わりに、その対象範囲の判断をレポートのエグゼクティブサマリーに記載してください。入力待ちで処理を止めてはいけません。

ステップ 2：プロジェクトを把握する

問題を評価する前に、監査対象の全体像を把握します。可能であれば、次の情報を並行して収集します。

• 言語と規模：言語ごとのファイル数とおおよその行数を確認します。git ls-files（または find）と wc -l を使えば十分です。
• パッケージ／ビルドマニフェスト：package.json、pyproject.toml、requirements*.txt、Cargo.toml、go.mod、pubspec.yaml、Gemfile、pom.xml、build.gradle*、composer.json などを確認します。これらから、フレームワーク、ランタイムのバージョン、依存関係がわかります。
• 既存のツール：リンター、型チェッカー、フォーマッター、セキュリティスキャナー、テストランナーを確認します。設定ファイル（.eslintrc*、ruff.toml、tsconfig.json、pytest.ini、.golangci.yml、analysis_options.yaml など）や CI ワークフロー（.github/workflows/、.gitlab-ci.yml、Makefile）を調べます。
• エントリーポイントと構成：main.*、index.*、トップレベルのディレクトリ（src/、lib/、app/、cmd/）を確認します。
• ドキュメント：README*、CONTRIBUTING*、docs/、CHANGELOG* を確認します。すべてを読み込まず、ざっと目を通します。
• 最近の変更：git log --since="3 months ago" --pretty=oneline | head -50 を使い、変更の多い箇所や意図を確認します。

すでに設定されているツールを把握することは重要です。たとえば、プロジェクトが CI で ruff と mypy をすでに実行しているなら、同じ内容のスタイルに関する細かな指摘を加えてもノイズになります。既存のパイプラインで検出できていない問題を優先して報告します。

ユーザーから別途指示がない限り、次のものは通常、対象から除外します：node_modules/、.git/、dist/、build/、target/、vendor/、.next/、__pycache__/、.venv/、生成コード、ロックファイル。これらは有用な情報を大量のノイズに埋もれさせます。

ステップ 3：既存のツールに面倒な作業を任せる

自分でコードを読む前に、プロジェクトですでに設定されているツールを実行し、出力を記録します。このほうが速く、信頼性が高く、誰もが納得できるシグナルが得られます。例（プロジェクトで実際に設定またはインストールされているものだけを実行します）：

• JS/TS：npm audit --json、npx eslint . --format json、npx tsc --noEmit
• Python：pip-audit、ruff check .、mypy .、bandit -r .
• Go：go vet ./...、staticcheck ./...、govulncheck ./...
• Rust：cargo clippy -- -D warnings、cargo audit
• Dart/Flutter：flutter analyze、dart pub outdated
• 汎用：gitleaks detect、trufflehog filesystem .（シークレット）、git grep -nE "TODO|FIXME|HACK|XXX"

ツールがインストールされていない場合は、「<tool> を実行すれば、ここでさらに問題が見つかる可能性があります」と報告に記載し、先へ進みます（「重要な制約 — 自動インストールしない」を参照）。

プロジェクトの主要言語向けの標準ツールがひとつもインストールまたは設定されていない場合、その不在自体が、ツール／開発者体験に関する指摘として報告する価値があります。チームの他のメンバーが備わっていると思っている正確性の確認手段が、実際には存在しないということです。

時間のかかるスキャンでは、JSON 出力を優先し、生ログをそのままユーザーに提示するのではなく、要約を解析して報告にまとめます。

ステップ 4：意図を持ってコードを読む

次に、手作業／LLM 主導で確認します。コードベースが複雑な場合は、領域ごとに Agent（Explore）サブエージェントを並行して起動します。セキュリティ、品質、パフォーマンスなど、各サブエージェントがほかの作業に気を取られず、深く調査できるようにします。小規模なコードベースなら、焦点を絞った確認を 1 回行えば十分です。

以下の各観点について、具体的で場所を特定できる指摘を探します。曖昧な印象で済ませてはいけません。すべての指摘には実際の場所を示す必要があります。通常はファイル名（可能であれば行の範囲も）を記載しますが、プロジェクトレベルで存在しないもの（.gitignore がない、LICENSE がない、テストディレクトリがない、CI 設定がないなど）については、Where: project root（または、たとえば Where: tests/ (missing) のように存在しないパス）で問題ありません。「曖昧な指摘をしない」ことがルールであり、「必ず 1 行だけを示す」ことではありません。

正確性とバグ

• 未処理のエラーパス（拒否された Promise、握りつぶされた例外、戻り値の無視）
• Null／undefined／欠落しているオプション値への対処
• オフバイワン、誤ったループ境界、古い参照
• 競合状態と非同期処理の順序に関するバグ
• デッドコード、到達不能な分岐、矛盾した条件
• 型の取り違え（特に動的言語）

セキュリティ

• インジェクション：SQL、NoSQL、OS コマンド、パストラバーサル、テンプレート、LDAP
• クロスサイトスクリプティング（HTML／DOM への未エスケープ出力）
• ハードコードされたシークレット、API キー、トークン、秘密鍵（リポジトリが十分小さい場合はコミット履歴も検索）
• 弱い暗号：セキュリティ目的での MD5／SHA1、独自の暗号、トークン用の弱い乱数
• 安全でないデフォルト設定：過度に許可的な CORS、認証チェックの欠如、本番コードパス内のデバッグルート
• 安全でないデシリアライズ、SSRF、オープンリダイレクト
• ツールによる確認ですでに指摘されていない依存関係の CVE
• 機密データのログ出力
• 信頼境界での入力検証の欠如

コード品質

• 大きなファイル、長い関数、深いネスト、複雑な条件式
• 抽出して整理できる重複（ただし、抽出によって明らかに改善する場合に限ります。抽象化が不適切であれば、重複を残すほうがよい場合もあります）
• 誤解を招く命名：実際の動作と名前が一致しない変数、関数、モジュール
• コードと矛盾するコメント
• プロジェクト内ですでに採用されているスタイルが、モジュール間で一貫していない

アーキテクチャ

• 独立しているべきレイヤー間の密結合
• モジュール間の循環依存
• UI／ルートハンドラー／マイグレーションへのビジネスロジックの混在
• 抽象化の欠如、または時期尚早な抽象化

パフォーマンス

• N+1 クエリパターン
• 頻繁に実行される処理での同期 I/O
• 上限のないループ、ページネーションの欠如
• タイトなループ内での大きなメモリ確保、正規表現の繰り返しコンパイル、ループ内での文字列連結
• クエリの形状から必要性がわかるインデックスの欠如（スキーマを確認できる場合）

テスト

• 重要な処理にテストがない（認証、決済、金銭やデータ損失に関わる処理など）
• 意味のある検証をしていない、または恒真なアサーションを使うテスト
• 不安定なテストを生むパターン（実時間、実ネットワーク、共有グローバル状態）
• パーサー、バリデーター、境界条件に関するエッジケースの不足

ドキュメントと開発者体験

• README のセクション（セットアップ、実行、テスト、デプロイ）の欠落や古さ
• ドキュメント文字列や型ヒントがない公開 API
• ドキュメント化されていない環境変数／設定
• CHANGELOG がない、またはリリースプロセスが不明確
• ビルドが遅い、エラーメッセージが不明確、プレコミットフックがない

機能と改善のアイデア この観点は、最も推測を含みます。コードに実際の兆候がある場合に限って機能を提案してください。たとえば、TODO、実装途中のフロー、明らかな不足（「API には list/get/create があるが delete がない」など）、自動化が望ましい手作業のワークフローが該当します。問題ではなくアイデアであることを明記してください。リストを長くするために機能を作り出してはいけません。

Step 5: スコア付けと優先順位付け

各指摘に2つの属性を割り当てます。これにより、ユーザーは絞り込みを行い、対応する内容を判断できます。

• 重大度：critical（データ消失、セキュリティ侵害、コアフローの破損）、high（実際のバグ、よくあるケースでの失敗、現実的な条件下で悪用可能）、medium（回避策のある正確性または品質の問題）、low（スタイル、軽微な問題）、info（アイデア、所見）
• 確信度：high（問題のある正確な行を示し、何が問題かを説明できます）、medium（パターンに疑いがあり、間違っている可能性が高いものの、確認にはコードの実行が必要です）、low（意図的なものかもしれません。メンテナーに確認してもらうための指摘です）

low confidence / low severityの項目をたくさん書いていることに気づいたら、そこで止めてください。そうした項目はレポートを読みにくくし、重要な内容を見えにくくします。ユーザーの今週の計画を変えない項目はすべて削除してください。

Step 6: レポートを作成する

レポートをプロジェクトのルートにCODE_AUDIT_<YYYY-MM-DD>_<HHMM>_<auditor>.mdとして保存します。たとえば、CODE_AUDIT_2026-06-29_1430_claude-opus-4-8.mdです。タイムスタンプは監査の実行時刻を記録し、<auditor>は実行者を記録するため、監査を繰り返しても前回のレポートがひそかに上書きされず、並べて保存されます。ローカルの時計と実行者の識別情報を使って名前を作成してください。

date +%Y-%m-%d_%H%M        # the date + time component, e.g. 2026-06-29_1430

<auditor>には、エージェントが監査を実行する場合はモデルID（例：claude-opus-4-8）を、人間が実行する場合はgitのuser.name（スラッグ化し、小文字にして、スペースは-に置き換える）を使います。（または、ユーザーが希望する場合はインラインで出力します。）ユーザーがすばやく確認できるよう、次の構成を正確に使用してください。

# Code audit — <project name> — <YYYY-MM-DD HH:MM>

## Executive summary
<3–6 lines: scope of audit, headline counts (critical/high/medium/low), the single biggest concern, and the single highest-leverage improvement>

## Findings

### Critical
<one entry per finding, in the format below — or "None" if nothing critical>

### High
...

### Medium
...

### Low
...

### Ideas (feature & enhancement opportunities)
...

## What was NOT analyzed
<honest list: paths skipped, tools not run, areas you only sampled>

## Suggested next steps
<3–5 bullets: which findings to act on first and why; how the user could attack the list>

指摘項目の形式：

#### [<id>] <short title>
- **Where**: `path/to/file.ext:LINE` (or `path/to/file.ext` if it's file-level)
- **Category**: bug | security | quality | performance | tests | docs | architecture | idea
- **Severity / Confidence**: high / high
- **What**: <one or two sentences describing the issue>
- **Why it matters**: <impact in plain terms>
- **Suggested fix**: <concrete direction; code sketch only if it really helps>

ユーザーが後から参照できるよう、SEC-01、BUG-01、Q-01、IDEA-01のような一貫したIDを使用してください。

文章は簡潔にしてください。ユーザーはこのリストをトリアージするため、段落が増えるほど時間がかかります。

Step 7: 引き継ぎと次の手順の提示

対話形式での利用：レポートを提示した後、ユーザーにわかりやすい選択肢を示してください。依頼されていない修正を始めてはいけません。

Audit complete. Report at CODE_AUDIT_<YYYY-MM-DD>_<HHMM>_<auditor>.md.

Want me to:
  1. Fix specific findings — name the ids, e.g. "fix SEC-01, BUG-02, Q-03"
  2. Open GitHub issues for the high/critical items (uses `gh issue create`)
  3. Drill into one finding in more depth
  4. Re-run the audit with different scope or focus

指示を待ってください。ユーザーが修正を選んだ場合は、各指摘を独立した小さなタスクとして扱います。該当するコードを読み、最小限の変更を加え、次に進む前に確認してください。関係のない修正を1つの大きなコミットにまとめてはいけません。

非対話形式での利用：選択肢のメニューは省略します。レポートの絶対パスを伝えて終了してください。呼び出し元のシステムがレポートを読み取り、次の対応を判断します。

出力の原則

次の原則は、上記のどのルールよりもレポートの品質を左右します。

• 巧みさより、場所の特定しやすさ。 ファイル名と行番号が明記された平凡な指摘の方が、洗練されていても抽象的な批評10件より価値があります。
• 網羅性より、確信度。 ユーザーが信頼できる、短く要点を絞ったレポートは、ユーザーが内容を弁護しなければならない長いレポートより価値があります。
• ユーザーの既存の好みを尊重する。 プロジェクトが明確に選択している慣例が自分なら別のものを選ぶ内容であっても、それは指摘事項ではなく、ユーザーが決めることです。指摘するのは、好みではなく、実際のコスト（正確性、セキュリティ、保守性）に関わるものです。
• アイデアと欠陥を区別する。 機能の提案をバグに混ぜてはいけません。ユーザーが、修正すべきものと検討すべきものを判断できるようにします。
• 省略した内容について正直に伝える。 「分析しなかった内容」は脚注ではなく、実際のセクションです。残っている死角をユーザーに伝えます。

重大な制約事項

• 読み取り専用の監査です。監査中にフォーマッターを実行したり、ファイルを編集したり、コミットやプッシュを行ったりしないでください。
• パッケージのインストール、依存関係の更新、または node_modules／.venv／ロックファイルを変更する操作を実行しないでください。ツールがインストールされていない場合は、その旨を記載し、無断でインストールしないでください。
• すべての指摘箇所は特定できるようにしてください。実在するファイル（可能な場合は行範囲を含む）、または project root や tests/ (missing) のようなプロジェクト内の場所を明記してください。具体的な場所を示せない指摘は、レポートに含めないでください。
• レポートを水増ししないでください。該当する指摘がないカテゴリには「None」と記載してください。それも有用な情報です。
• 悪用方法とその影響を説明できない限り、脆弱性だと断定しないでください。悪用の経路が曖昧な場合は、重大度を下げてください。
• 非常に大規模なプロジェクトでは、対象を明示してサンプリングしてください。コードベースの半分を黙って調査対象から外さないでください。
• レポートの後に修正を依頼された場合は、各指摘を個別の小さなタスクとして扱ってください。同じ編集に無関係な変更を紛れ込ませないでください。