القائمة
C 项目注释生成与审查节点。在 ddev-c-pro 编码规范审查通过后，对 .c/.h 文件逐项检查注释完整性并补齐缺失注释。由 ddev-gate 调度，作为 c-pro 之后的独立审查步骤。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/docevilOck/agent-skills-hook --skill ddev-comment-genيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | ddev-comment-gen |
| description | C 项目注释生成与审查节点。在 ddev-c-pro 编码规范审查通过后，对 .c/.h 文件逐项检查注释完整性并补齐缺失注释。由 ddev-gate 调度，作为 c-pro 之后的独立审查步骤。 |
在 ddev-c-pro 编码规范审查通过后，由 ddev-gate 拉起独立 subagent 加载本 skill，对代码注释做系统性审查和补全。
pass 后，ddev-gate 拉起.c / .h）pass（注释齐全）或 blocked（附缺失项清单 + 补全建议）审查 agent 必须逐文件、逐函数、逐结构体/枚举核验，不得仅凭印象判断。
.h 和 .c 文件必须包含 @file + @brief 头注释@brief 须说明本文件的主要职责，不能仅重复文件名@brief 只写当前职责，禁止迁移背景、阶段/演进标注（"阶段 N""已迁移""已释放""占位/恢复"）、方案/验证过程等说明，一律进 commit message/**
* @file module.h
* @brief 模块公开 API 定义，提供初始化和数据处理接口
*/
每个在 .h 中声明的公开函数必须包含完整 Doxygen 注释：
@brief：一句话说明函数做什么@param：每个参数一个，说明含义、约束（是否可为 NULL、取值范围）@return：返回值含义（无返回值写"无"或"void"）@note / @warning / @see：按需添加/**
* @brief 模块初始化，分配并配置硬件资源。
* @param cfg 配置参数，不可为 NULL，baud 须 > 0。
* @return MODULE_OK (0) 成功，其他为错误码。
* @note 重复调用前须先 module_deinit。
*/
module_status_t module_init(const module_cfg_t *cfg);
struct / union 定义必须有 @brief 说明用途/**< 说明 */ 行内注释enum 必须有 @brief 说明枚举用途/**< 说明 */ 行内注释/** @brief 模块运行时上下文 */
typedef struct {
uint32_t baud; /**< 当前波特率 */
volatile bool running; /**< ISR 与主循环共享，仅原子读写 */
uint8_t rx_buf[256]; /**< 接收环形缓冲区 */
} module_t;
/** @brief 模块操作状态码 */
typedef enum {
MODULE_OK = 0, /**< 成功 */
MODULE_ERR_INVALID_ARG, /**< 参数非法 */
MODULE_ERR_TIMEOUT, /**< 操作超时 */
} module_status_t;
static 函数不强制 Doxygen 格式，但复杂逻辑必须说明意图static 函数建议添加简要块注释说明职责@brief / @param / @return 等）保持英文标签本身，描述内容用中文/**< */ 内容用中文注释补充代码不可见的信息（为什么 / 约束 / 并发语义），不是复述代码本身。缺失注释与注释过密同为缺陷，双向核验：
/* */ 逻辑注释最多 2 行（What + 必要一句 Why）；方案背景、验证过程、替代方案、历史原因等说明写 commit message，不进代码注释；超过 2 行即冗余static 辅助函数不强制 @brief/@param/@return；仅复杂逻辑加 2~3 行块注释说明意图[P1_XXX] 等打点日志标签、迭代追溯标签不得进入注释正文（仓库统一约定除外）@brief、常量移除处、字段/成员注释、逻辑块注释。反例：文件头 @brief 只写当前职责，不写迁移史；常量移除处不写背景说明（直接删除即可，必要时只写"见 commit XXXX"）blocked，1~2 处列为建议项/** */ 或 ///）@brief / @param / @return / @note / @warning / @see / @todo / @retval.h 文件，逐一检查文件头、公开函数、结构体、枚举的注释完整性.c 文件，逐一检查文件头、私有函数的注释完整性@brief/常量移除处/字段成员处的迁移背景与阶段/演进标注（"阶段 N""已迁移""已释放""占位/恢复"）和方案/验证过程说明等pass；任一缺失，或冗余项累计 ≥ 3 → blocked + 附清单ddev-comment-gen 审查结论：[pass | blocked]
若 blocked，清单：
- module.h:42 — [缺失] module_init 缺少 @param cfg 注释
- module.c:10 — [缺失] 缺少 @file 头注释
- module.h:25 — [缺失] module_cfg_t 结构体缺少 @brief，成员 baud 缺少行内注释
- module.c:88 — [缺失] ISR 回调缺少说明注释
- module.c:60 — [冗余] 字段注释 3 行复述锁逻辑，字段名已自释，压到 ≤1 行
- module.c:120 — [冗余] static 辅助函数贴完整 Doxygen，应降为 2~3 行块注释
- module.c:88 — [冗余] 逻辑块注释 5 行含方案背景与验证过程，压到 ≤2 行，背景进 commit message
- prt_z5_cfg.h:432 — [冗余] 常量移除处写"补光灯控制权已迁移小核"迁移背景，应删除该注释，背景进 commit message
- prt_light.c:1 — [冗余] 文件头 @brief 含"阶段 2：torch 恢复真实下发""控制权已迁移"演进标注，@brief 只保留当前职责，迁移史进 commit message
当本 skill 被 ddev-gate 作为注释审查子代理加载时，必须使用 reviewer-prompt.md 作为任务模板执行审查。该模板定义了审查输入、审查维度优先级、CodeGraph 辅助查询方法和输出格式。
审查完成后将结果写入项目根目录的 progress.md：