embedded-review

組み込みコードレビューエキスパート

重大度レベル

レベル	名前	説明	対応
P0	致命的	メモリ破損、割り込み安全性違反、セキュリティ脆弱性、ブリック化のリスク	マージを必ずブロック
P1	高	競合状態、リソースリーク、未定義動作、RTOS の誤用	マージ前に修正すべき
P2	中	コードの問題点、移植性の問題、エラー処理の不足、最適でないパターン	修正するか、フォローアップを作成
P3	低	スタイル、命名、ドキュメント、軽微な提案	任意の改善

---

ワークフロー

モードの選択

単一モデルモード（小規模な差分 ≤100 行のデフォルト）：

• 現在のセッションのモデルを使って、1 回レビューします
• 高速で、低コストです
• 軽微な変更、設定の微調整、ドキュメントに適しています

デュアルモデルのクロスレビュー（差分が >100 行の場合、または明示的に要求された場合のデフォルト）：

• Claude Code と Codex が ACP を介して独立してレビューします
• 指摘事項を相互比較します
• 品質が高く、多様な見落としを発見できます
• 次の用途に使用します：新機能、アーキテクチャの変更、クリティカルパス（ISR、暗号、NFC、DMA）

ユーザーは「用双模型 review」または「quick review 就行」と指定して変更できます。

---

フェーズ 0：事前確認 — スコープとコンテキスト

1. scripts/prepare-diff.sh <repo_path> [diff_range] を実行します。次の情報が出力されます：

   • リポジトリ情報（ブランチ、最新のコミット）
   • 対象の特定（ビルドファイルから MCU、RTOS、コンパイラーを特定）
   • 差分の統計、行数、規模の評価（SMALL/MEDIUM/LARGE）
   • クリティカルパスの検出（ISR/DMA、暗号、NFC、ブート/OTA）
   • 差分の全内容

2. スクリプトの出力を使ってレビューのモードを決定します：

   • 変更なし：ユーザーに知らせ、ステージ済みの変更またはコミット範囲のレビューを提案します。
   • SMALL（≤100 行）：デフォルトで単一モデルレビューを行います。
   • LARGE（>500 行）：まずファイル/モジュールごとに要約し、その後サブシステムごとに分けてレビューします。
   • クリティカルパスが検出された場合：常にデュアルモデルを推奨します。

3. レビューコンテキストパッケージを作成します：

   REVIEW_CONTEXT = {
     repo_info: (branch, MCU, RTOS, compiler),
     diff: (full git diff text),
     references: (relevant checklist sections from references/),
     focus_areas: (user-specified or auto-detected critical paths)
   }
   

---

フェーズ 1：単一モデルレビュー

小規模な差分の場合、またはデュアルモデルが要求されていない場合：

1）メモリ安全性のスキャン

• 詳細なチェックリストは references/memory-safety.md を読み込みます。
• スタックオーバーフロー、バッファーオーバーラン、アラインメント、DMA キャッシュコヒーレンシー、ヒープの断片化
• sprintf、strcpy、gets、strcat を検出し、境界チェック付きの代替手段を提案します

2）割り込みと並行処理の正当性

• 詳細なチェックリストは references/interrupt-safety.md を読み込みます。
• 共有変数へのアクセス、クリティカルセクション、ISR のベストプラクティス、RTOS の落とし穴
• 優先度逆転、再入可能性、ネストされた割り込みの処理

3）ハードウェアインターフェイスのレビュー

• 詳細なチェックリストは references/hardware-interface.md を読み込みます。
• 周辺機器の初期化順序、レジスターアクセス、タイミング違反、ピンの競合
• 通信プロトコル：I2C/SPI/UART/NFC のバッファー管理、タイムアウト処理

4）C/C++ 言語の落とし穴

• 詳細なチェックリストは references/c-pitfalls.md を読み込みます。
• 未定義動作、整数の問題、コンパイラーの前提、リンカーの問題
• プリプロセッサーの危険性、移植性、型安全性

5）アーキテクチャと保守性

• HAL/BSP のレイヤリング、抽象化、結合度、テスト容易性
• デッドコード、マジックナンバー、設定管理

6）セキュリティスキャン（組み込み向け）

• シークレットの保存、デバッグインターフェイス、ファームウェア更新の完全性
• サイドチャネル、フォールトインジェクション、入力検証、スタックカナリア

→ 単一モデルの結果については、フェーズ 3：出力に進みます。

---

フェーズ 2：デュアルモデルのクロスレビュー（ACP）

デュアルモデルレビューが開始された場合：

ステップ 1：レビュー用ペイロードを準備

同一の REVIEW_CONTEXT から、独立した 2 つのレビュータスクを作成します：

Claude Code タスク：

You are a senior embedded systems engineer reviewing firmware code changes.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Review checklist (apply all that are relevant):
- Memory safety (references/memory-safety.md)
- Interrupt & concurrency (references/interrupt-safety.md)
- Hardware interfaces (references/hardware-interface.md)
- C/C++ pitfalls (references/c-pitfalls.md)
- Architecture & security

Output format: For each finding, provide:
[P0/P1/P2/P3] [file:line] Title
- Description
- Risk
- Suggested fix

Be thorough. Flag everything you find, even if uncertain — mark uncertain items with [?].

Codex タスク：

You are an independent code reviewer for embedded/firmware projects.
Your job is to find bugs, security issues, and correctness problems.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Focus on:
1. Memory corruption risks (buffer overflow, use-after-free, stack overflow)
2. Concurrency bugs (race conditions, missing volatile, ISR safety)
3. Hardware interface errors (timing, register access, peripheral init)
4. Logic errors and edge cases
5. Security vulnerabilities

Output: List every issue found as:
[SEVERITY: critical/high/medium/low] [file:line] Issue title
- What's wrong
- What could happen
- How to fix

Do NOT skip low-severity items. Report everything.

ステップ 2：並列 ACP セッションを起動

sessions_spawn(runtime="acp", agentId="claude-code", task=claude_task)
sessions_spawn(runtime="acp", agentId="codex", task=codex_task)

両方を同時に実行します。両方が完了するまで待ちます。

ステップ 3：調査結果を相互比較する

両方のレビューが完了したら、結果を分析します。

1. 一致した調査結果（両方が同じ問題を指摘）：高い確信度 — これらは実際のバグです
2. Claude のみの調査結果：妥当性を確認します — 誤検出の可能性も、本当に見つかった問題の可能性もあります
3. Codex のみの調査結果：妥当性を確認します — 視点の違いにより、Claude が見落とした問題を見つけている可能性があります
4. 矛盾する調査結果：人間による判断が必要な項目として明示します — 一方は問題ないとし、もう一方はバグだとしています

統一された重要度レベル（P0～P3）に対応付けます。

---

フェーズ 3：出力形式

## Embedded Code Review Summary

**Target**: [MCU/Board] | [RTOS/Bare-metal] | [Compiler]
**Branch**: [branch name]
**Files reviewed**: X files, Y lines changed
**Review mode**: [Single-model / Dual-model (Claude Code + Codex)]
**Overall assessment**: [APPROVE / REQUEST_CHANGES / COMMENT]

---

## Findings

### 🔴 P0 - Critical (must block)
(none or list)

### 🟠 P1 - High (fix before merge)
1. **[file:line]** Brief title [🤝 consensus / 🔵 Claude-only / 🟢 Codex-only]
   - Description of issue
   - Risk: what can go wrong
   - Suggested fix

### 🟡 P2 - Medium (fix or follow-up)
...

### ⚪ P3 - Low (optional)
...

---

## Cross-Review Analysis (dual-model only)

| Metric | Count |
|--------|-------|
| 🤝 Consensus (both found) | X |
| 🔵 Claude-only | Y |
| 🟢 Codex-only | Z |
| ⚠️ Contradictions | W |

### Notable disagreements
(list any contradictions with both perspectives)

---

## Hardware/Timing Concerns
(register access, peripheral init, timing-sensitive code)

## Architecture Notes
(layering, testability, portability observations)

フェーズ 4：次のステップ

---
## Next Steps

Found X issues (P0: _, P1: _, P2: _, P3: _).

**How would you like to proceed?**
1. **Fix all** — implement all suggested fixes
2. **Fix P0/P1 only** — address critical and high priority
3. **Fix specific items** — tell me which issues to fix
4. **Re-review with dual-model** — run cross-review (if single-model was used)
5. **No changes** — review complete

重要：ユーザーが明示的に確認するまで、変更を実装しないでください。

---

リソース

references/

ファイル	目的
memory-safety.md	バッファー、スタック、ヒープ、DMA、アラインメントのチェックリスト
interrupt-safety.md	ISR、並行処理、RTOS、アトミック操作のチェックリスト
hardware-interface.md	周辺機器、レジスター、タイミング、プロトコルのチェックリスト
c-pitfalls.md	未定義動作、整数、コンパイラー、プリプロセッサー、移植性のチェックリスト

scripts/

ファイル	目的
prepare-diff.sh	git diff を抽出し、レビュー用のコンテキストを構築します