embedded-review

嵌入式代码审查专家

严重级别

级别	名称	描述	操作
P0	严重	内存损坏、中断安全违规、安全漏洞、设备变砖风险	必须阻止合并
P1	高	竞争条件、资源泄漏、未定义行为、RTOS 误用	应在合并前修复
P2	中	代码异味、可移植性问题、缺少错误处理、模式欠佳	修复或创建后续任务
P3	低	风格、命名、文档、次要建议	可选改进

---

工作流

模式选择

单模型模式（小型差异 ≤100 行时的默认模式）：

• 使用当前会话的模型进行一轮审查
• 更快，成本更低
• 适用于简单更改、配置调整、文档

双模型交叉审查（差异 >100 行时的默认模式，或用户明确要求时）：

• 通过 ACP 由 Claude Code 和 Codex 独立审查
• 交叉比较审查结果
• 质量更高，可发现不同模型各自的盲点
• 适用于：新功能、架构更改、关键路径（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 构建两个独立的审查任务：

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 并构建审查上下文