Back to Details

embedded-cross-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Embedded Code Review Expert

嵌入式代码审查专家

Overview

概述

Perform structured review of embedded and firmware changes with emphasis on memory safety, interrupt correctness, RTOS usage, hardware interfaces, C/C++ pitfalls, and embedded security.
The preferred review strategy is cross-review by two independent subagents that inspect the same diff separately, then compare findings for consensus, gaps, and contradictions.
The purpose of running two subagents is to improve correctness, not speed. Cross-review exists to reduce false positives, reduce false negatives, and increase confidence that a reported issue is real before escalating it to the user.
The skill is intentionally host-agnostic:
  • Do not hardcode Claude Code, Codex, ACP, or any vendor-specific runtime.
  • Use the current environment's native parallel subagent mechanism when available.
  • If the environment supports model selection, use two different high-capability models for the two subagents.
  • If model selection is unavailable, still run two independent subagents with different review emphases.
  • If parallel subagents are unavailable, fall back to a single-agent review and state that cross-review could not be run in this environment.
Target environments: bare-metal MCU, RTOS (FreeRTOS/Zephyr/ThreadX), Linux embedded, mixed C/C++ firmware.
对嵌入式和固件变更进行结构化审查，重点关注内存安全、中断正确性、RTOS使用、硬件接口、C/C++常见陷阱及嵌入式安全性。
首选审查策略是由两个独立子代理进行交叉审查：分别独立检查同一代码差异，然后对比结果以达成共识、发现遗漏和矛盾点。
运行两个子代理的目的是提升审查准确性，而非速度。交叉审查旨在减少误报和漏报，在将问题上报给用户前，提升问题真实性的可信度。
本技能特意设计为与宿主环境无关：
  • 请勿硬编码Claude Code、Codex、ACP或任何供应商特定的运行时。
  • 若当前环境支持原生并行子代理机制，则使用该机制。
  • 若环境支持模型选择，为两个子代理选用不同的高性能模型。
  • 若无法选择模型，仍需运行两个独立子代理，且各自侧重不同的审查方向。
  • 若不支持并行子代理，则退化为单代理审查，并说明当前环境无法运行交叉审查。
目标环境：裸机MCU、RTOS（FreeRTOS/Zephyr/ThreadX）、嵌入式Linux、混合C/C++固件。

Trigger

触发条件

Activate when the user asks to review embedded or firmware code changes. Examples:
  • "review firmware-pro2 的改动"
  • "review the NFC changes"
  • /embedded-cross-review ~/Documents/dec/firmware-pro2
  • /embedded-cross-review ~/Documents/dec/firmware-pro2 HEAD~5..HEAD
  • /embedded-cross-review <github-pr-url>
当用户请求审查嵌入式或固件代码变更时激活。示例：
  • "review firmware-pro2 的改动"
  • "review the NFC changes"
  • /embedded-cross-review ~/Documents/dec/firmware-pro2
  • /embedded-cross-review ~/Documents/dec/firmware-pro2 HEAD~5..HEAD
  • /embedded-cross-review <github-pr-url>

Severity Levels

严重等级

LevelNameDescriptionAction
P0CriticalMemory corruption, interrupt safety violation, security vulnerability, brick riskMust block merge
P1HighRace condition, resource leak, undefined behavior, RTOS misuseShould fix before merge
P2MediumCode smell, portability issue, missing error handling, suboptimal patternFix or create follow-up
P3LowStyle, naming, documentation, minor suggestionOptional improvement
等级名称描述处理动作
P0致命内存损坏、中断安全违规、安全漏洞、设备变砖风险必须阻止合并
P1高竞态条件、资源泄漏、未定义行为、RTOS误用应在合并前修复
P2中代码异味、可移植性问题、缺少错误处理、次优实现模式修复或创建后续任务
P3低风格、命名、文档、次要建议可选优化

Workflow

工作流程

Mode Selection

模式选择

Single-agent mode:
  • Use for small diffs (default threshold: ≤100 lines)
  • Use when the user explicitly asks for a quick review
  • Use when the host environment does not support parallel subagents
Cross-review mode:
  • Default for diffs >100 lines
  • Prefer for new features, architecture changes, and critical paths (ISR, DMA, crypto, NFC, boot)
  • Implement as two independent subagents reviewing the same payload in parallel
  • Primary goal: better review correctness and confidence, not faster turnaround
  • If the host exposes model choice, use two different high-capability models
User can override: "用双代理 review" or "quick review 就行"
单代理模式：
  • 适用于小代码差异（默认阈值：≤100行）
  • 当用户明确要求快速审查时使用
  • 当前宿主环境不支持并行子代理时使用
交叉审查模式：
  • 代码差异>100行时默认使用
  • 优先用于新功能、架构变更和关键路径（ISR、DMA、加密、NFC、启动）
  • 实现方式：两个独立子代理并行审查同一审查上下文
  • 核心目标：提升审查准确性和可信度，而非更快的周转速度
  • 若宿主环境支持模型选择，选用两个不同的高性能模型
用户可手动覆盖："用双代理 review" 或 "quick review 就行"

Host Capability Rule

宿主环境能力适配规则

Choose the best available execution mode in this order:
  1. Two parallel subagents with explicit different high-capability models
  2. Two parallel subagents with the same model but different prompts and review focus
  3. One agent review with explicit note that cross-review was unavailable
Do not abort just because a specific vendor runtime is unavailable. Do not justify a weaker mode by claiming it is faster; the priority is review quality.
按以下优先级选择最佳执行模式：
  1. 两个并行子代理，分别使用不同的高性能模型
  2. 两个并行子代理，使用同一模型但不同提示词和审查重点
  3. 单代理审查，并明确说明无法进行交叉审查
请勿因特定供应商运行时不可用而终止审查。 请勿以“速度更快”为理由选择较弱的审查模式；审查质量为优先目标。

Phase 0: Preflight - Scope & Context

阶段0：预检 - 范围与上下文

  1. Run 
    scripts/prepare-diff.sh <repo_path> [diff_range]
    to extract:
    • Repository info (branch, last commit)
    • Target identification (MCU, RTOS, compiler)
    • Diff stat and full diff content
  2. Assess scope:
    • No changes: Inform user; offer to review staged changes or a commit range.
    • Small diff (≤100 lines): Default to single-agent review unless user requests cross-review.
    • Large diff (>500 lines): Summarize by file or subsystem first, then review in batches.
    • Critical path touched (ISR, DMA, crypto, NFC, boot): Strongly prefer cross-review.
  3. Build review context package:
text
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. Load reference files by trigger, not blindly:
    • Always load 
      references/c-pitfalls.md
      for C/C++ diffs unless the change is purely documentation or build metadata.
    • Load 
      references/memory-safety.md
      when the diff touches buffers, parsing, 
      memcpy
      /
      memset
      , string handling, stack allocation, heap use, DMA buffers, packed structs, pointer casts, or alignment-sensitive code.
    • Load 
      references/interrupt-safety.md
      when the diff touches ISRs, callbacks from interrupt context, shared state, 
      volatile
      , critical sections, atomics, RTOS tasks/queues/semaphores/mutexes, or any code that can run concurrently.
    • Load 
      references/hardware-interface.md
      when the diff touches peripheral init, clocking, GPIO mux, MMIO registers, DMA setup, watchdogs, reset/power sequencing, or protocol drivers such as I2C/SPI/UART/NFC.
    • Architecture/maintainability and embedded security do not have dedicated reference files in this skill; review those directly from the diff and target context.
    • If the diff spans multiple categories, load every matching reference file.
    • If the category is unclear, the diff is safety-critical, or a critical path is touched, load all four reference files.
  1. 运行
    scripts/prepare-diff.sh <repo_path> [diff_range]
    以提取：
    • 仓库信息（分支、最新提交）
    • 目标环境标识（MCU、RTOS、编译器）
    • 差异统计和完整差异内容
  2. 评估范围：
    • 无变更：告知用户；可提议审查暂存变更或指定提交范围。
    • 小差异（≤100行）：默认使用单代理审查，除非用户要求交叉审查。
    • 大差异（>500行）：先按文件或子系统汇总，再分批审查。
    • 触及关键路径（ISR、DMA、加密、NFC、启动）：强烈建议使用交叉审查。
  3. 构建审查上下文包：
text
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. 根据触发条件加载参考文件，而非盲目加载：
    • 对于C/C++代码差异，除非变更仅涉及文档或构建元数据，否则始终加载
      references/c-pitfalls.md
      。
    • 当代码差异涉及缓冲区、解析、
      memcpy
      /
      memset
      、字符串处理、栈分配、堆使用、DMA缓冲区、打包结构体、指针转换或对齐敏感代码时，加载
      references/memory-safety.md
      。
    • 当代码差异涉及ISR、中断上下文回调、共享状态、
      volatile
      、临界区、原子操作、RTOS任务/队列/信号量/互斥锁或任何可并发运行的代码时，加载
      references/interrupt-safety.md
      。
    • 当代码差异涉及外设初始化、时钟配置、GPIO复用、MMIO寄存器、DMA设置、看门狗、复位/电源时序或协议驱动（如I2C/SPI/UART/NFC）时，加载
      references/hardware-interface.md
      。
    • 架构/可维护性和嵌入式安全在本技能中暂无专门的参考文件；直接根据代码差异和目标上下文进行审查。
    • 若代码差异涉及多个类别，加载所有匹配的参考文件。
    • 若类别不明确、代码差异涉及安全关键或触及关键路径，加载全部四个参考文件。

Phase 1: Single-Agent Review

阶段1：单代理审查

For small diffs or when cross-review is not requested or not available:
Before reviewing, use the Phase 0 trigger rules to decide which reference files to load. Do not assume all four references are required for every small diff, but do load all applicable ones. Architecture/maintainability and embedded security are always reviewed even though this skill currently has no dedicated reference files for them.
  1. Memory safety scan
    • Load 
      references/memory-safety.md
      when the diff matches the memory-safety triggers from Phase 0
    • Stack overflow, buffer overrun, alignment, DMA cache coherence, heap fragmentation
    • Flag 
      sprintf
      , 
      strcpy
      , 
      gets
      , 
      strcat
      ; suggest bounded alternatives
  2. Interrupt and concurrency correctness
    • Load 
      references/interrupt-safety.md
      when the diff matches the interrupt/concurrency triggers from Phase 0
    • Shared variable access, critical sections, ISR best practices, RTOS pitfalls
    • Priority inversion, reentrancy, nested interrupt handling
  3. Hardware interface review
    • Load 
      references/hardware-interface.md
      when the diff matches the hardware-interface triggers from Phase 0
    • Peripheral init ordering, register access, timing violations, pin conflicts
    • I2C/SPI/UART/NFC buffer management and timeout handling
  4. C/C++ language pitfalls
    • Load 
      references/c-pitfalls.md
      for any non-trivial C/C++ code review
    • Undefined behavior, integer issues, compiler assumptions, linker issues
    • Preprocessor hazards, portability, type safety
  5. Architecture and maintainability
    • No dedicated reference file today; review this directly from the diff and surrounding design
    • HAL/BSP layering, abstraction, coupling, testability
    • Dead code, magic numbers, configuration management
    • Check whether newly added code is over-coupled, overly procedural, or mixing responsibilities that could be better expressed with common design patterns
    • Review whether SOLID-style refactoring or a simpler pattern such as strategy, state, adapter, factory, or dependency inversion would make the design clearer, safer, or easier to extend
  6. Embedded security scan
    • No dedicated reference file today; review this directly from the diff and threat surface
    • Secret storage, debug interfaces, firmware update integrity
    • Side channels, fault injection, input validation, stack canaries
Then skip to Phase 3: Output.
适用于小代码差异场景，或交叉审查未被请求/不可用的场景：
审查前，使用阶段0的触发规则决定加载哪些参考文件。请勿假设所有小代码差异都需要加载四个参考文件，但需加载所有适用的参考文件。即使本技能暂无专门的参考文件，架构/可维护性和嵌入式安全始终是审查重点。
  1. 内存安全扫描
    • 当代码差异匹配阶段0中内存安全触发条件时，加载
      references/memory-safety.md
    • 检查栈溢出、缓冲区溢出对齐问题、DMA缓存一致性、堆碎片化
    • 标记
      sprintf
      、
      strcpy
      、
      gets
      、
      strcat
      ；建议使用有界替代函数
  2. 中断与并发正确性审查
    • 当代码差异匹配阶段0中中断/并发触发条件时，加载
      references/interrupt-safety.md
    • 检查共享变量访问、临界区、ISR最佳实践、RTOS常见陷阱
    • 检查优先级反转、可重入性、嵌套中断处理
  3. 硬件接口审查
    • 当代码差异匹配阶段0中硬件接口触发条件时，加载
      references/hardware-interface.md
    • 检查外设初始化顺序、寄存器访问、时序违规、引脚冲突
    • 检查I2C/SPI/UART/NFC缓冲区管理和超时处理
  4. C/C++语言陷阱审查
    • 对于任何非 trivial 的C/C++代码审查，加载
      references/c-pitfalls.md
    • 检查未定义行为、整数问题、编译器假设、链接器问题
    • 检查预处理器风险、可移植性、类型安全
  5. 架构与可维护性审查
    • 暂无专门参考文件；直接根据代码差异和周边设计进行审查
    • 检查HAL/BSP分层、抽象、耦合性、可测试性
    • 检查死代码、魔术数字、配置管理
    • 检查新增代码是否过度耦合、过于过程化，或混合了职责，是否可通过通用设计模式更好地表达
    • 检查是否可通过SOLID风格重构或更简单的模式（如策略、状态、适配器、工厂、依赖倒置）使设计更清晰、安全或易于扩展
  6. 嵌入式安全扫描
    • 暂无专门参考文件；直接根据代码差异和威胁面进行审查
    • 检查密钥存储、调试接口、固件更新完整性
    • 检查侧信道攻击、故障注入、输入验证、栈保护
然后跳至阶段3：输出。

Phase 2: Cross-Review With Two Subagents

阶段2：双代理交叉审查

When cross-review mode is triggered, create two review tasks from the same 
REVIEW_CONTEXT
.
当触发交叉审查模式时，基于同一
REVIEW_CONTEXT
创建两个审查任务。

Step 1: Define distinct review roles

步骤1：定义不同的审查角色

Use prompts that force complementary perspectives.
Subagent A: Embedded systems safety reviewer
text
You are a senior embedded systems engineer reviewing firmware code changes.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Apply these review areas when relevant:
- Memory safety
- Interrupt and concurrency correctness
- Hardware interfaces and timing
- RTOS correctness
- Embedded security
- Architecture and maintainability, including whether new code should be replaced or reshaped using simpler abstractions, common design patterns, or SOLID principles

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

Flag uncertain findings with [?].
Subagent B: Independent adversarial reviewer
text
You are an independent reviewer for embedded and firmware code.
Your job is to challenge assumptions and find correctness problems the first reviewer might miss.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Focus on:
1. Logic errors and edge cases
2. C/C++ undefined behavior and integer hazards
3. Race conditions and state machine bugs
4. Hardware interface misuse, timeout paths, and recovery paths
5. Security and fault handling weaknesses
6. Whether the newly added structure is doing too much in one place and would be better modeled with a common pattern or cleaner responsibility split

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

Do not suppress low-severity issues. Report everything relevant.
If the host supports explicit model choice, assign different high-capability models to A and B. This is the preferred mode because model diversity helps validate whether a finding is genuinely problematic rather than a single-model hallucination or blind spot. If not, keep the roles different anyway.
使用提示词强制形成互补的审查视角。
子代理A：嵌入式系统安全审查员
text
You are a senior embedded systems engineer reviewing firmware code changes.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Apply these review areas when relevant:
- Memory safety
- Interrupt and concurrency correctness
- Hardware interfaces and timing
- RTOS correctness
- Embedded security
- Architecture and maintainability, including whether new code should be replaced or reshaped using simpler abstractions, common design patterns, or SOLID principles

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

Flag uncertain findings with [?].
子代理B：独立对抗式审查员
text
You are an independent reviewer for embedded and firmware code.
Your job is to challenge assumptions and find correctness problems the first reviewer might miss.

[REVIEW_CONTEXT: repo info, diff, focus areas]

Focus on:
1. Logic errors and edge cases
2. C/C++ undefined behavior and integer hazards
3. Race conditions and state machine bugs
4. Hardware interface misuse, timeout paths, and recovery paths
5. Security and fault handling weaknesses
6. Whether the newly added structure is doing too much in one place and would be better modeled with a common pattern or cleaner responsibility split

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

Do not suppress low-severity issues. Report everything relevant.
若宿主环境支持明确的模型选择，为代理A和代理B分配不同的高性能模型。这是首选模式，因为模型多样性有助于验证问题是否真的存在，而非单一模型的幻觉或盲区。若不支持模型选择，仍需保持角色差异。

Step 2: Spawn in parallel

步骤2：并行执行

Use the host's native subagent facility to run both tasks concurrently.
Requirements:
  • Same 
    REVIEW_CONTEXT
    for both subagents
  • Independent execution
  • No visibility into each other's findings before they finish
  • Prefer parallel execution over sequential execution
Rationale:
  • Parallelism is an implementation detail, not the objective.
  • Independence matters because cross-contamination weakens validation value.
  • Different strong models are preferred because the point is agreement quality, not throughput.
If the host only supports one worker model, still keep the prompts distinct.
使用宿主环境的原生子代理机制并发运行两个任务。
要求：
  • 两个子代理使用相同的
    REVIEW_CONTEXT
  • 独立执行
  • 在完成前，无法查看对方的审查结果
  • 优先并行执行，而非串行执行
原理：
  • 并行性是实现细节，而非目标。
  • 独立性至关重要，因为交叉干扰会降低验证价值。
  • 首选不同的高性能模型，因为核心目标是结果的一致性质量，而非吞吐量。
若宿主环境仅支持单工作模型，仍需保持提示词的差异性。

Step 3: Cross-compare findings

步骤3：交叉对比结果

After both complete, classify results:
  1. Consensus findings: both subagents flagged substantially the same issue. Treat as high confidence.
  2. A-only findings: validate and keep if technically sound.
  3. B-only findings: validate and keep if technically sound.
  4. Contradictions: one subagent says correct, the other says buggy. Surface this explicitly for human judgment.
Normalize all findings to unified severity levels 
P0
to 
P3
.
两个任务完成后，对结果进行分类：
  1. 共识结果：两个子代理标记了基本相同的问题。视为高可信度。
  2. 仅代理A发现的问题：若技术上合理，则保留。
  3. 仅代理B发现的问题：若技术上合理，则保留。
  4. 矛盾结果：一个子代理认为正确，另一个认为存在问题。需明确呈现该矛盾供人工判断。
将所有结果统一为
P0
至
P3
的严重等级。

Step 4: Environment note

步骤4：环境说明

State which cross-review path was used:
  • two subagents, different high-capability models
  • two subagents, same model with different prompts
  • single-agent fallback
This matters because confidence differs across modes, and the user should know whether the review outcome was cross-validated by distinct strong models or only approximated.
说明使用的交叉审查路径：
  • two subagents, different high-capability models
  • two subagents, same model with different prompts
  • single-agent fallback
这一点很重要，因为不同模式的可信度不同，用户应了解审查结果是否经过不同高性能模型的交叉验证，或仅为近似验证。

Phase 3: Output Format

阶段3：输出格式

markdown
undefined
markdown
undefined

Embedded Code Review Summary

Embedded Code Review Summary

Target: [MCU/Board] | [RTOS/Bare-metal] | [Compiler] Branch: [branch name] Files reviewed: X files, Y lines changed Review mode: [Single-agent / Cross-review] Execution path: [two subagents, different high-capability models / two subagents, same model with different prompts / single-agent fallback] Confidence basis: [consensus across distinct strong models / consensus across role-separated same-model agents / single-agent judgment] Overall assessment: [APPROVE / REQUEST_CHANGES / COMMENT]
Target: [MCU/Board] | [RTOS/Bare-metal] | [Compiler] Branch: [branch name] Files reviewed: X files, Y lines changed Review mode: [Single-agent / Cross-review] Execution path: [two subagents, different high-capability models / two subagents, same model with different prompts / single-agent fallback] Confidence basis: [consensus across distinct strong models / consensus across role-separated same-model agents / single-agent judgment] Overall assessment: [APPROVE / REQUEST_CHANGES / COMMENT]

Findings

Findings

P0 - Critical (must block)

P0 - Critical (must block)

(none or list)
(none or list)

P1 - High (fix before merge)

P1 - High (fix before merge)

  1. [file:line] Brief title [consensus / reviewer-A-only / reviewer-B-only]
    • Description of issue
    • Risk: what can go wrong
    • Suggested fix
  1. [file:line] Brief title [consensus / reviewer-A-only / reviewer-B-only]
    • Description of issue
    • Risk: what can go wrong
    • Suggested fix

P2 - Medium (fix or follow-up)

P2 - Medium (fix or follow-up)

...
...

P3 - Low (optional)

P3 - Low (optional)

...
...

Cross-Review Analysis

Cross-Review Analysis

MetricCount
ConsensusX
Reviewer-A-onlyY
Reviewer-B-onlyZ
ContradictionsW
MetricCount
ConsensusX
Reviewer-A-onlyY
Reviewer-B-onlyZ
ContradictionsW

Notable disagreements

Notable disagreements

(list contradictions with both perspectives)
(list contradictions with both perspectives)

Hardware/Timing Concerns

Hardware/Timing Concerns

(register access, peripheral init, timing-sensitive code)
(register access, peripheral init, timing-sensitive code)

Architecture Notes

Architecture Notes

(layering, testability, portability observations) (include whether a common design pattern, SOLID-style split, or simpler abstraction would better fit the new code)

Only include `Cross-Review Analysis` when two subagents were actually used.

---

**Important**: Do not implement changes until the user explicitly confirms.
(layering, testability, portability observations) (include whether a common design pattern, SOLID-style split, or simpler abstraction would better fit the new code)

仅当实际使用两个子代理时，才包含`Cross-Review Analysis`部分。

---

**重要提示**：在用户明确确认前，请勿实施任何代码变更。