ios-code-audit

iOS コード監査スキル

運用ルール

• 読み取り専用の調査で、成果物は1つです。 コードは変更しません。出力はリポジトリのルートに置く CODE_AUDIT.md です。
• 指摘事項にはすべて path/to/file.swift:LINE（または行範囲）を記載します。 Critical または High の項目で「コードベース全体にわたって」という表現は決して使用できません。
• 重大度は慎重に割り当てます。 Critical はクラッシュ／データ損失／メモリ破損／セキュリティ露出を意味します。重大度を誇張しないでください。以下の重大度ガイドを参照してください。
• Critical の主張は、共有する前に必ず検証します。 エージェントが重大度を誇張することがあります。引用されたファイルを開き、バグが実在することを確認してください。該当行を読んでも主張を再現できない場合は、重大度を下げるか、指摘を削除してください。
• 発生箇所ではなく、根本原因ごとにまとめます。 @MainActor の注釈が1つ欠けていることで警告が7件発生するなら、7件に分けず、7箇所を列挙した1件の指摘にします。
• Dead/（または明示的にアーカイブされたディレクトリ）は対象外です。 エージェントを起動する前に、編集禁止のディレクトリがないか CLAUDE.md／プロジェクトの README を確認してください。

ワークフロー

Step 1 — コードベースの範囲を把握する

エージェントに共有するため、簡単な測定を行います。

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -not -path "*/Pods/*" -not -path "*/.build/*" | xargs wc -l 2>/dev/null | tail -1
find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" 2>/dev/null | wc -l
find . -name "*.metal" 2>/dev/null | wc -l

また、ホットスポットのファイル（行数が多いファイル、中心的な状態を管理するファイル）も特定します。

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -exec wc -l {} \; | sort -rn | head -10

CLAUDE.md が存在する場合は読みます。通常、中心的な状態ファイル（例：AppState.swift、CaptureState.swift）、レンダリングパイプライン、意図的に対象外とするディレクトリが記載されています。

Step 2 — コンパイラの確定情報を取得する

ビルドを実行し、すべての警告を抽出します。これを並行処理／非推奨 API の監査における標準入力にします。並行処理の警告が存在するかどうかを 推測 する必要はありません。

推奨（接続されている場合は Xcode MCP）：

mcp__xcode__XcodeListNavigatorIssues(tabIdentifier, severity: "warning")

これにより、path、line、message、severity を含む構造化リストが返されます。重複を排除し（複数ターゲットのコンパイルでは重複が発生します）、根本原因ごとに分類します。

代替手段（CLI から xcodebuild を実行）：

xcodebuild -project <Project>.xcodeproj -scheme "<Dev scheme>" -configuration Debug build 2>&1 \
  | grep -E "warning:" | sort -u

ビルドがインクリメンタルで、2秒未満で完了した場合は、ほとんどのファイルがスキップされている可能性があります。警告をすべて取得するには、各ターゲット内の Swift ファイルに変更を加えるか、clean build を実行してください。

Step 3 — Explore エージェントを3つ並行して起動する

1つのメッセージで、ツールを3回呼び出します。 各エージェントには references/agent-prompts.md の焦点を絞った指示を渡します。

• エージェント A — 並行処理と API の最新化。 Step 2 で取得した警告を渡します。
• エージェント B — デッドコード、重複、リファクタリング候補。 ホットスポットの一覧と、CLAUDE.md で判明している古いファイルを渡します。
• エージェント C — バグ、ロジックエラー、セキュリティ、パフォーマンス。 ホットスポットの一覧と、ユーザーが指定したサブシステム（カメラパイプライン、IAP、API クライアントなど）を渡します。

各指示には、指摘ごとのテンプレート（以下を参照）が含まれます。エージェントに要約を返させず、具体的なファイルと行番号を含む指摘を求めてください。

Step 4 — SwiftUI の専門家による確認（SwiftUI を使用している場合）

プロジェクトに SwiftUI のビューがある場合は、エージェントの結果が返ってきた後に、swiftui-expert-skill を個別に呼び出します。対象範囲は Views/（または SwiftUI の画面が置かれているディレクトリ）と、共有 UI ヘルパーです。特に次の点を確認するよう依頼してください。

• @State／@Bindable／@Observable の誤用
• モディファイアの順序に関するバグ
• ビューの本体から外に出すべき処理（フォーマッタ、デコーダー、ソート）
• アクセシビリティ／Dynamic Type／ダークモードの不足
• 頻繁に使用される末端のビューに Equatable が不足していないか
• Liquid Glass／iOS 26 の採用機会（依頼された場合のみ）

スキルが特定したパターンを確認するため、自分でいくつかのビューのファイルを読む必要がある場合があります。

Step 5 — Critical の指摘を検証する

レポートを作成する前に、Critical のフラグが付いた指摘はすべて、引用された行を開いて次の点を確認します。

• コードがエージェントの説明と一致していること。
• 影響に関する主張が妥当であること（例：エージェントが「メモリ破損」と主張している場合、バッファが実際に不足しているか。計算を追跡してください）。
• 推奨される修正が妥当であること。

過去の実行では、この手順によって重大度に関する誤った主張が見つかっています。妥当でない項目は、重大度を下げるか削除してください。自分で検証していない Critical を決して共有しないでください。

ステップ 6 — CODE_AUDIT.md を作成する

references/report-template.md のひな形を使用してください。

必須：レンダリングされたレポートのすべての見出しにセクション番号を含めてください。 これは見た目だけの問題ではありません。レポートを利用するうえで最も重要なインターフェースです。ユーザーは「§5.4 を修正して」「§3.1 は完了した？」のように課題を報告しますが、見出しに番号がなければ、それができません。番号のないレポートを生成するのは、スタイル上の選択ではなく不具合です。 番号のないレポートは却下されます。

番号付けのルール：

• トップレベルのセクションには、以下の順序どおり、## 1. から ## 12. までの番号を付けてください。 指摘事項がないセクションも省略せず、その見出しの下に「No findings.」と記載してください。
• 各指摘事項は、### N.M <短いタイトル> の形式で番号付きサブセクションにしてください。 N は親セクションの番号、M は1から始まる連番です。例：### 5.1 Force-unwrap on Bundle.main.url、### 5.2 Missing .limited Photos auth handling。指摘事項を ### <短いタイトル> のように、N.M の接頭辞なしで出力してはいけません。
• 番号は編集後も変えないでください。 改訂中に指摘事項を削除する場合は、番号を残して本文に _REMOVED: <理由>_ と記載してください。残りの指摘事項の番号を振り直してはいけません。そうすると「§5.4」への外部参照がすべて無効になります。
• エグゼクティブサマリーの項目（§1）は、該当する番号付き指摘事項への参照を含む番号付きリスト 1., 2., … にしてください（例：「[Critical] Force-unwrap on Bundle.main.url — §5.1 — path:line」）。
• 検証項目（§12）では、サブセクション番号を使って指摘事項を参照してください。例：- **§5.1** — \path` の42～47行目を確認してください。テンプレートの<N.M>` プレースホルダーをそのまま残さず、実際の番号を記入してください。

トップレベルのセクションと順序：

1. エグゼクティブサマリー — 影響の大きい指摘事項を5～10件選び、各項目を重要度タグと§N.Mの相互参照付きで1行にまとめます。
2. すぐにできる改善 — 30分以内にできる修正（古いファイルの削除、デバッグ用の print の削除、未使用の let に関する警告の修正、アクセシビリティラベルの追加など）。
3. 並行処理
4. APIの最新化 — 非推奨API、iOS 17以降の代替手段
5. バグ／ロジックエラー
6. セキュリティ
7. パフォーマンス
8. SwiftUI／UI
9. デッドコード／重複／リファクタリング
10. 横断的な推奨事項 — リポジトリ全体に適用する価値のあるパターン
11. 監査対象外の項目 — 明示的な対象範囲外リスト
12. 検証 — Critical／Highの各指摘について、その主張を裏付ける正確な行

指摘事項ごとのテンプレート（先頭に N.M を付ける）：

### N.M <short title>
- **Location:** `path/to/file.swift:LINE-LINE`
- **What:** <observed problem in one sentence>
- **Why:** <impact / why it matters>
- **Action:** <recommended fix; no code, reference patterns>
- **Severity:** Critical | High | Medium | Low

全体の長さは網羅的でありながら、ざっと読みやすいものにしてください。50～100件を目安とします。同じカテゴリの項目が多数ある場合は、類似する事例を1つの見出しにまとめてください（具体例を上位5～10件挙げ、残りの件数も記載します）。

重要度の基準

• Critical — クラッシュ、データ損失、メモリ破損、セキュリティ上の露出、または本番環境への誤ったサーバーURLのリリースにつながる可能性が高いもの。割り当てる前に、引用した行を自分で確認してください。
• High — ユーザーが実際に遭遇するバグ、将来のSwiftモードでエラーになるコンパイラ警告、実際に削除が進められている非推奨API、またはアーキテクチャ上の並行処理の問題。
• Medium — パフォーマンス／品質上の問題、リファクタリング候補、機能的なバグを伴わない最新化の不足。
• Low — 命名、見た目、コードスタイル、単発の整理。

品質基準（提出前の最終確認）

• 最上位のセクションにはすべて ## 1. から ## 12. までの番号が付いており、すべての指摘事項は番号付きのサブセクション ### N.M <title> になっています。 レンダリングされたレポートに目を通し、番号のない見出しがあれば、提出前に修正してください。番号のないレポートは不備として却下されます。
• エグゼクティブサマリーの各項目は §N.M で指摘事項を参照し、検証項目も同様に参照しています。 テンプレートの文字列 <N.M> が残っていないことを確認してください。
• すべての Critical および High の指摘事項に、正確な行範囲が記載されています。「コードベース全体」といった記載は避けてください。
• 並行処理に関する指摘事項は、Step-2 の警告一覧を相互参照しています。
• Critical の指摘事項を少なくとも 3～5 件、該当ファイルを開いて抜き取り検証しています。
• 指摘事項は根本原因ごとにグループ化されています（1 つの注釈から多数の警告が生じている場合は、1 件の指摘事項として扱います）。
• 「監査対象外」のセクションで対象外の範囲を明示し、ユーザーが未確認の領域を把握できるようにしています。
• レポートの個別の指摘事項は約 80 件以下です。これを超えると、実行可能性が損なわれます。
• レポート自体にコードを含めていません。推奨事項では実装ではなくパターンを説明しています。
• ユーザーが、追加の背景説明なしで個々の指摘事項を独立したタスクとして切り出せます。

スキルの出力

必ずリポジトリのルート（ユーザーのプロジェクト作業ディレクトリ）に CODE_AUDIT.md を作成してください。既存のファイルがある場合は上書きしてください。このスキルが生成するのは追記ログではなくスナップショットです。履歴を残したい場合は、実行前に以前のバージョンを git mv で移動できます。

このスキルの対象外

• Metal カーネルやドメイン固有コードのアルゴリズム的な正確性。 明白な問題だけを指摘してください。詳細なアルゴリズムレビューは対象外です。
• ビルド設定、スキーム設定、Xcode プロジェクトの構造。 共有スキームから確認できる範囲を除きます。
• サードパーティ製依存関係の内部実装。 SPM / CocoaPods のパッケージはブラックボックスとして扱います。
• テストカバレッジの評価。 テストターゲットの簡単な確認は構いませんが、詳細なテストレビューは別のスキルで行います。
• ローカライズの正確性。 未翻訳の文字列は指摘できますが、表現の適切さは評価しません。
• パフォーマンスのプロファイリング。 このスキルでは、潜在的なホットパス（フレームごとのアロケーション、広範な状態管理など）を特定しますが、Instruments のトレースは実行しません。その場合は、swiftui-expert-skill とそのトレースツールを別途実行してください。

参考資料

• references/agent-prompts.md — 3 つの Explore エージェント向け概要（コピーしてすぐに使える形式で、プロジェクトのコンテキストを記入します）。
• references/report-template.md — CODE_AUDIT.md の完全なひな形。