基于Codex创建嵌入式专用代码审查Skill

接上篇：嵌入式专用的 AI 代码审查 Checklist

在 Codex 里，Skill 本质上就是一个标准化的文件夹。把之前的审查要点做成 Skill，就是把“一堆规则文本”升级为“一个可被 Codex 自动识别和调用的工作流模块”。

核心提示：截至 2026 年 5 月，Cursor、Codex、Claude Code 都已支持围绕 SKILL.md 组织能力。这意味着按本指南制作的 Skill，天然具备跨平台兼容性，换工具也不用重写。

1. Codex Skill 是什么？

Codex Skill 是一个封装了可复用工作流的文件夹。它把“任务指令 + 脚本 + 参考资料”打包成标准化模块，让 AI 稳定执行特定开发任务。

它的核心价值在于：

打个比方：传统 Prompt 像给 AI 一本 200 页的全科手册让它从头读到尾，Skill 像只递一本《嵌入式代码审查专项手册》，用到时才翻开。

2. Skill 的标准目录结构

一个标准的 Codex Skill 长这样：

embedded-code-review/           # 技能文件夹（名称即技能 ID）
├── SKILL.md                    # 核心入口文件（必需）
├── scripts/                    # 可选：辅助脚本（Python/Shell）
│   └── check_embedded_smells.py
├── references/                 # 可选：参考资料、详细规范
│   └── review-checklist.md
└── assets/                     # 可选：配置文件、模板
    └── report_template.md

SKILL.md 是唯一必需的文件，其他都是锦上添花。

3. 制作 Skill 的完整流程

3.1 方法一：对话固化（最推荐，最快）

这是最直观的方式——先让 Codex 跑通一次审查流程，然后把流程固化成 Skill。

Step 1：在 Codex 中启动一个新对话，手动执行一次完整的代码审查：

请审查当前 Git diff。重点看嵌入式风险：
1. 中断和主循环共享变量是否需要 volatile
2. DMA 缓冲区生命周期是否安全
3. 是否有阻塞式延时影响实时性
4. 是否修改了 CubeMX 生成区域
5. CMake 是否漏加源文件
只输出问题、风险和建议，不要改代码。

这个提示词模板参考了 Codex 做嵌入式代码审查的官方推荐写法。

Step 2：等 Codex 完成审查、输出结果后，直接说：

把刚才的流程固化成一个 Skill，命名为 embedded-code-review，按标准格式生成 SKILL.md 和文件夹结构。

Step 3：Codex 会自动生成完整的 Skill 文件夹和 SKILL.md 文件。你只需要检查内容是否正确，然后保存到 Codex 的 skills 目录即可。

3.2 方法二：手动创建（完全掌控）

如果你想从头手写，可以按以下步骤操作：

Step 1：在 Codex 的 skills 目录下创建文件夹：

# macOS / Linux
mkdir -p ~/.codex/skills/embedded-code-review

# Windows
mkdir C:Users你的用户名.codexskillsembedded-code-review

Codex Skills 支持多个层级：系统级（内置）、全局级（所有项目生效）、仓库级（仅当前项目）。上面创建的是全局级 Skill。

Step 2：在文件夹中创建 SKILL.md 文件：

---
name: embedded-code-review
description: 嵌入式 C/C++ 代码审查。用于审查嵌入式Linux、MCU、RTOS、驱动、BSP 相关代码，重点发现内存安全、并发竞态、中断上下文误用、DMA/cache 一致性、实时性风险等问题。
---

# 嵌入式 C/C++ 代码审查 Skill

## 触发条件
当用户要求审查嵌入式 C/C++ 代码、驱动代码、RTOS 相关代码、BSP 代码时自动启用。

## 核心原则
**先看会不会死机、丢数据、破坏硬件状态、影响实时性。风格建议往后放。**

## 审查流程
1. **首先**：扫描第一优先级——正确性缺陷（内存安全、并发竞态、整数边界、错误处理）
2. **其次**：检查嵌入式专属风险（DMA/cache 一致性、动态内存、硬件超时、中断上下文）
3. **然后**：评估实时性风险（优先级反转、ISR 长度、阻塞调用）
4. **最后**：给出风格建议（优先级最低）

## 嵌入式专项检查要点

###  第一优先级：正确性缺陷
- [ ] 是否存在 use-after-free、double-free？
- [ ] 错误路径上是否有资源泄漏（内存、文件描述符、锁）？
- [ ] 是否存在 NULL 指针解引用？
- [ ] 是否存在缓冲区溢出或数组越界？
- [ ] 是否存在未初始化变量在可达路径上被使用？
- [ ] 共享状态是否存在竞态条件？
- [ ] 中断上下文中是否调用了可能阻塞的函数？
- [ ] 长度字段是否先验证再使用？
- [ ] 整数运算是否存在溢出或截断？
- [ ] 可能失败的函数调用是否检查了返回值？

### 🟠 第二优先级：嵌入式专属风险
- [ ] 是否使用了动态内存分配（malloc/free）？如有，是否有严格规范？
- [ ] DMA buffer 是否处理了 cache 一致性？
- [ ] 等待硬件状态是否有超时机制？
- [ ] 任务间共享变量是否有保护措施？
- [ ] 是否存在忙等（busy-wait）而无合理退出条件？
- [ ] 寄存器操作和硬件交互逻辑是否正确？

### 🟡 第三优先级：实时性风险
- [ ] 是否存在优先级反转风险？
- [ ] 关键路径上是否有不可预测执行时间的操作？
- [ ] 中断服务程序（ISR）是否足够短？

### 🟢 第四优先级：编码规范
- [ ] 是否符合团队编码风格？
- [ ] 函数圈复杂度是否过高（建议 ≤ 10-15）？
- [ ] 是否存在硬编码的密码、密钥或魔数？
- [ ] 硬件相关注释是否准确？

## 输出格式
-  **严重问题**（必须修复）：正确性缺陷
- 🟠 **高风险**（强烈建议修复）：嵌入式专属风险
- 🟡 **中风险**（建议修复）：实时性问题
- 🟢 **低风险/建议**：风格和规范问题

## 审查原则
- 理解代码的硬件上下文（芯片型号、外设资源、编译配置）
- 建立“软件逻辑 ↔ 硬件约束”的双向映射
- 对可疑代码实施“双重校验”：静态分析 + 逻辑推理

Step 3：可选——添加 references/review-checklist.md 存放更详细的检查清单，添加 scripts/ 存放自动化检测脚本。Codex 会在需要时按需加载这些内容。

4. 如何安装和使用 Skill

安装方法

方法一：使用 Skill Installer（最省事）

在 Codex 终端中输入 $，选择 Skill Installer，然后输入技能名称或粘贴 GitHub 仓库 URL，Codex 会自动完成安装。安装完成后务必重启 Codex。

方法二：手动放置

把 embedded-code-review/ 文件夹直接放到 Codex 的 skills 目录下：

• • macOS：

  /Users/你的用户名/.codex/skills/

• • Windows：

  C:Users你的用户名.codexskills

放好后新开一个 Codex 对话，因为旧对话可能因缓存读不到新 Skill。

调用方式

方式一：自动触发当你说“帮我 review 这段嵌入式代码”时，Codex 会自动匹配 Skill 的 description 并调用。

方式二：显式调用输入 $embedded-code-review 或通过 /skills 菜单选择。

方式三：对话中引用直接说“用 embedded-code-review 技能审查当前文件”。

5. 进阶技巧

5.2 技巧一：配合 Git diff 做增量审查

在 Codex 中可以直接说：

用 embedded-code-review 技能审查当前 Git diff，只看本次变更引入的问题。

这对应了 Codex 做代码审查的典型场景。

5.3 技巧二：跨平台复用

由于 Cursor、Codex、Claude Code 都支持 SKILL.md 格式，你做的这个 Skill 可以直接复制到其他工具的 skills 目录下使用。

6. 总结

把嵌入式代码审查要点制作成 Codex Skill，只需要 3 步：

创建文件夹：~/.codex/skills/embedded-code-review/

写入 SKILL.md：复制上面的模板内容

重启 Codex：新开对话，直接使用

之后每次说“帮我 review 这段嵌入式代码”，Codex 就会自动按 Checklist 的标准执行审查——不用再复制粘贴长篇提示词，也不用担心 AI 漏掉关键检查项。

Skill 的本质，就是把团队反复踩过的坑、反复强调的规则，固化成 AI 默认遵守的工作流程。今天花几分钟做好，以后每次代码审查都能受益。