codebase-audit-pre-push

プッシュ前のコードベース監査

シニアエンジニアとして、このコードを GitHub にプッシュする前に最終レビューを行います。すべてを注意深く確認し、問題が見つかったらその場で修正してください。

このスキルを使うタイミング

• ユーザーが「コードベースを監査して」または「プッシュ前にレビューして」と依頼した場合
• GitHub への初回プッシュ前
• リポジトリを公開する前
• 本番環境へのデプロイ前のレビュー
• ユーザーが「コードを整理して」または「すべてを最適化して」と依頼した場合

作業内容

コードベース全体をファイルごとにレビューします。コードを注意深く読み、問題はすぐに修正してください。問題を指摘するだけでなく、必要な変更を加えてください。

監査プロセス

1. 不要なファイルを整理する

まず、GitHub に含めるべきでないファイルを探します。

以下の候補を確認し、許可された範囲内で、不要であることが確認できたファイルのみ削除してください。

• OS ファイル：.DS_Store、Thumbs.db、desktop.ini
• ログ：*.log、npm-debug.log*、yarn-error.log*
• 一時ファイル：*.tmp、*.temp、*.cache、*.swp
• ビルド出力：dist/、build/、.next/、out/、.cache/
• 依存関係：node_modules/、vendor/、__pycache__/、*.pyc
• IDE ファイル：.idea/、.vscode/（先にユーザーに確認）、*.iml、.project
• バックアップファイル：*.bak、*_old.*、*_backup.*、*_copy.*
• テスト生成物：coverage/、.nyc_output/、test-results/
• 個人的な不要ファイル：TODO.txt、NOTES.txt、scratch.*、test123.*

重要 — シークレットを確認する：

• .env ファイル（コミットしてはいけません）
• 次の文字列を含むファイル：password、api_key、token、secret、private_key
• *.pem、*.key、*.cert、credentials.json、serviceAccountKey.json

コード内にシークレットが見つかった場合は、重大なブロッカーとして報告してください。

2. .gitignore を修正する

.gitignore ファイルが存在するか、十分な内容になっているか確認します。存在しない場合や不十分な場合は、上記の不要ファイルのパターンをすべて含めるよう更新してください。キーはあるものの値が設定されていない .env.example が存在することも確認してください。

3. すべてのソースファイルを監査する

各コードファイルを確認し、以下をチェックします。

不要なコードの可能性（削除前に利用箇所、ビルド規約、実行時の規約を確認すること）：

• コメントアウトされたコードブロック
• 未使用のインポート／require
• 未使用の変数（宣言されているが使用されていない）
• 未使用の関数（定義されているが呼び出されていない）
• 到達不能なコード（return の後や if (false) 内）
• 重複したロジック（複数箇所に同じコードがある場合は統合する）

コード品質（作業を進めながら問題を修正する）：

• 曖昧な名前：data、info、temp、thing → 内容が分かる名前に変更する
• マジックナンバー：if (status === 3) → 名前付き定数にする
• デバッグ用の記述：console.log、print()、debugger を削除する
• TODO/FIXME コメント：未解決の要件は残し、根拠と対象範囲が明確な場合のみ解決する
• TypeScript の any：適切な型を追加するか、any を使う理由を説明する
• JavaScript では == ではなく === を使う
• 50 行を超える関数：分割を検討する
• ネストが 3 階層を超えるコード：早期リターンを使ってリファクタリングする

ロジックの問題（重大）：

• null／undefined のチェック漏れ
• 空の可能性がある配列に対する操作
• await されていない非同期関数
• .catch() や try/catch のない Promise
• 無限ループになる可能性
• switch 文の default の欠落

4. セキュリティチェック (ゼロトレランス)

シークレット: ハードコードされたパスワード、API キー、トークンを検索します。これらは環境変数に格納されている必要があります。

インジェクション脆弱性:

• SQL: クエリ内で文字列連結を行わないこと—パラメータ化クエリのみを使用する
• コマンドインジェクション: ユーザー提供の入力を使用した exec() は禁止
• パストラバーサル: 検証なしにユーザー入力からファイルパスを生成しない
• XSS: ユーザーデータを innerHTML や dangerouslySetInnerHTML に渡さない

認証/認可:

• パスワードは bcrypt/argon2 でハッシュ化する (MD5 や平文は絶対に不可)
• 保護されたルートは認証をチェックする
• 認可チェックは UI 上だけでなく、サーバーサイドで行う
• IDOR の禁止: ユーザーがアクセスするリソースを所有していることを検証する

データ漏えい:

• API レスポンスは不要な情報を漏らさない
• エラーメッセージはスタックトレースやデータベースの詳細を露出しない
• リストエンドポイントにはページネーションが存在する

依存関係:

• npm audit または同等のツールを実行する
• 重大に古い、または脆弱なパッケージをフラグする

5. スケーラビリティチェック

データベース:

• N+1 クエリ: ループ内でデータベース呼び出しを行う → JOIN またはバッチクエリを使用する
• WHERE/ORDER BY カラムにインデックスが欠けている
• 無制限のクエリ: LIMIT またはページネーションを追加する
• SELECT * を避ける: カラムを明示する

API 設計:

• 重い処理 (メール、レポート、ファイル処理など) → バックグラウンドキューに移動する
• パブリックエンドポイントにレート制限を設ける
• 頻繁に読み取られるデータをキャッシュする
• 外部呼び出しにタイムアウトを設定する

コード:

• グローバルな可変状態を持たない
• イベントリスナーをクリーンアップする (メモリリークを避けるため)
• 大きなファイルはメモリに読み込まず、ストリーミングする

6. アーキテクチャチェック

構成:

• 明確なフォルダー構造
• ファイルが論理的な場所に配置されている
• 「misc」や「stuff」といったフォルダーがない

関心の分離:

• UI レイヤー: レンダリングのみを担当する
• ビジネスロジック: 純粋関数
• データレイヤー: データベースクエリを分離する
• 500 行を超える「god ファイル」がない

再利用性:

• 重複コード → 共有ユーティリティに抽出する
• 定数は一度だけ定義し、インポートする
• 型/インターフェースは再定義せず、再利用する

7. パフォーマンス

バックエンド:

• コストの高い処理がリクエストをブロックしない
• 可能な場合はデータベース呼び出しをバッチ化する
• キャッシュヘッダーを正しく設定する

フロントエンド (該当する場合):

• コード分割を実装する
• 画像を最適化する
• 小さなユーティリティのために巨大な依存関係を避ける
• 重いコンポーネントには遅延読み込みを使用する

8. ドキュメント

README.md に含めるべき内容:

• プロジェクトが何を行うかの説明
• インストールと実行の手順
• 必要な環境変数
• テストの実行に関するガイダンス

コードコメント:

• WHAT ではなく WHY を説明する
• 複雑なロジックには説明を付ける
• コードを単に繰り返すだけのコメントは避ける

9. テスト

• クリティカルパスにはテストを用意する (認証、決済、コア機能)
• test.only や fdescribe をコードに残さない
• 説明なしに test.skip を使用しない
• テストは実装の詳細ではなく、振る舞いを検証する

10. 最終検証

すべての変更を加えた後、アプリを実行します。何も壊れていないことを確認します。次をチェックします:

• アプリがエラーなく起動する
• 主要な機能が動作する
• テストがパスする (存在する場合)
• リグレッションが導入されていない

出力形式

監査後、レポートを提供します:

CODEBASE AUDIT COMPLETE  

FILES REMOVED:  
- node_modules/ (build artifact)  
- .env (contained secrets)  
- old_backup.js (unused duplicate)  

CODE CHANGES:  
[src/api/users.js]  
  ✂ Removed unused import: lodash  
  ✂ Removed dead function: formatOldWay()  
  🔧 Renamed 'data' → 'userData' for clarity  
  🛡 Added try/catch around API call (line 47)  

[src/db/queries.js]  
  ⚡ Fixed N+1 query: now uses JOIN instead of loop  

SECURITY ISSUES:  
🚨 CRITICAL: Hardcoded API key in config.js (line 12) → moved to .env  
⚠️ HIGH: SQL injection risk in search.js (line 34) → fixed with parameterized query  

SCALABILITY:  
⚡ Added pagination to /api/users endpoint  
⚡ Added index on users.email column  

FINAL STATUS:  
Status: report passed checks, unresolved findings and untested environments; no universal production-readiness certification

Scores:  
Security: list concrete findings and evidence
Code quality: list scoped findings
Scalability: state measured evidence or untested
Overall: state remaining blockers

基本原則

• コードを隅々まで読み、流し読みしない
• 問題は文書化するだけでなく、すぐに修正する
• 何かを削除することに確信が持てない場合は、ユーザーに尋ねる
• 変更後にテストする
• 徹底的に、しかし実用的に—実際の問題に焦点を当てる
• セキュリティ問題はブロッカーである—重大な脆弱性を抱えたまま出荷すべきではない

関連スキル

• @security-auditor - より深いセキュリティレビュー
• @systematic-debugging - 特定の問題を調査する
• @git-pushing - 監査後にコードをプッシュする

制限事項

• タスクが上記の範囲に明確に当てはまる場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

追跡対象のビルド成果物、ベンダー提供の依存関係、フィクスチャ、バックアップ、メモが、意図的にプロジェクトのソースとして含まれている場合があります。削除する前に、リポジトリの規約と所有者を確認してください。プッシュの準備だけを目的に、ローカルの .env を削除しないでください。認証情報が漏えいした場合は、報告書からその情報を伏せ、ローテーションまたは失効を行い、履歴や成果物も評価してください。認証情報を環境変数に移しても、漏えいがなかったことにはなりません。実際に読み取った正確なファイルと、実際に実行したチェックを報告してください。サンプル監査をコードベース全体の監査完了と称してはいけません。