Skill: leon-2050/embedded-code-skill (version 0.0.2)

--- name: embedded-code-skill description: "Generate, rewrite, or review embedded C code. Use when creating/rewriting/reviewing embedded C for microcontrollers, drivers, firmware. Triggers automatically when user mentions: generate, create, write code, implement driver, rewrite, refactor, review, check, audit." user-invocable: true --- # Embedded C 代码生成规范 ## 概述 本规范用于生成生产级嵌入式 C 代码，适用于 STM32、PowerPC、RISC-V 等平台。 **核心原则**: 像嵌入式软件架构师一样思考，生成可演进、可测试、可移植的代码。 --- ## 思维方式 生成代码时必须以**嵌入式软件架构师**的思维进行: | 维度 | 要求 | |------|------| | **系统视角** | 设计可演进的系统，考虑模块边界、接口契约、依赖关系 | | **资源意识** | 内存精确计算缓冲区，CPU 减少中断嵌套，优化关键路径 | | **实时性** | ISR 应尽可能短，考虑 WCET，防范优先级反转/死锁/队列溢出 | | **可靠性** | 看门狗策略、异常恢复、关键数据冗余存储 | | **硬件无关** | 寄存器抽象为结构体，驱动与业务逻辑分离 | | **可测试** | 公共接口易 mock，状态机可单步测试，边界条件覆盖 | --- ## 编码规范 ### 1. 类型规范 | 类型 | 用途 | 禁止 | |------|------|------| | `uint8_t` | 单字节、GPIO | `char`, `signed char` | | `uint16_t` | 16位寄存器 | `short`, `unsigned short` | | `uint32_t` | 32位寄存器、时间戳 | `int`, `long`, `unsigned int` | | `int32_t` | 有符号值 | - | | `uint64_t` | 64位数据 | - | | `bool` | 布尔标志 | - | **必须包含的头文件:** ```c #include <stdint.h> #include <stdbool.h> #include <stddef.h> ``` ### 2. 命名规范 | 元素 | 格式 | 示例 | |------|------|------| | 变量 | `snake_case` | `sensor_value`, `data_count` | | 全局变量 | `g_snake_case` | `g_system_ticks` | | 常量/宏 | `SCREAMING_SNAKE` | `MAX_BUFFER_SIZE`, `SPI_CR_EN` | | 函数 | `camelCase` | `initUart()`, `getSensorData()` | | 结构体类型 | `snake_case_t` | `uart_config_t` | | 枚举类型 | `snake_case_t` | `gpio_state_t` | | 枚举值 | `PREFIXED_SNAKE` | `GPIO_STATE_LOW` | | 指针 | `p_snake_case` | `p_rx_buffer` | | 寄存器结构体 | `module_name_reg_t` | `spi_reg_t` | | 寄存器头文件 | `module_reg.h` | `spi_reg.h` | ### 3. 错误处理 所有 public 函数必须: 1. 返回 `embedded_code_status_t` 枚举类型 2. 验证所有输入指针（NULL 检查） 3. 返回具体错误码 ```c typedef enum { EmbedCode_Ok = 0, EmbedCode_ErrNullPtr = -1, EmbedCode_ErrInvalidArg = -2, EmbedCode_ErrTimeout = -3, EmbedCode_ErrBusy = -4, EmbedCode_ErrNotInit = -5 } embedded_code_status_t; #define VALIDATE_NOT_NULL(ptr) \ do { if ((ptr) == NULL) return EmbedCode_ErrNullPtr; } while(0) ``` ### 4. 注释规范 **注释语言: 优先使用中文** | 原则 | 说明 | |------|------| | **中文优先** | 便于团队阅读和维护 | | **解释 WHY** | 注释应说明原因和意图，而非描述代码在做什么 | | **代码自说明** | 如果代码本身已清楚表达含义，无需注释 | **Doxygen 文件头格式:** ```c /** * @file spi_reg.h * @brief SPI 寄存器结构体定义 * @author Claude Code * @date 2026-04-10 */ ``` **行内注释示例:** ```c config |= SPI_CR_EN_MASK; /* 启用 SPI，低电平有效 */ ``` ### 5. 寄存器结构体定义 **每个外设模块必须有独立的 reg.h 文件:** | 必需元素 | 说明 | |----------|------| | `XXX_BASE_ADDR` | 基地址定义，格式：`XXX_BASE_ADDR` | | `xxx_reg_t` | 寄存器结构体，使用 `volatile uint32_t` | | `XXX_XXX_MASK/SHIFT` | 位字段宏定义 | | `XXX_REG` | 结构体指针访问宏 | **reg.h 模板:** ```c /** * @file spi_reg.h * @brief SPI 外设寄存器定义 */ #ifndef SPI_REG_H #define SPI_REG_H #include <stdint.h> /* 基地址 */ #define SPI_BASE_ADDR (0xA0010000U) /* 寄存器结构体 */ typedef struct { volatile uint32_t CTRL; /* 0x00: 控制寄存器 */ volatile uint32_t STATUS; /* 0x04: 状态寄存器 */ volatile uint32_t DATA; /* 0x08: 数据寄存器 */ } spi_reg_t; /* 位字段定义 */ #define SPI_CTRL_EN_MASK (1U << 0) #define SPI_CTRL_MODE_MASK (3U << 2) /* 寄存器访问 */ #define SPI_REG ((spi_reg_t *) SPI_BASE_ADDR) #endif /* SPI_REG_H */ ``` ### 6. 寄存器赋值规范 **禁止直接赋字面值，必须使用已定义的宏:** ```c // ❌ 错误 SPI_REG->CTRL = 0x47U; SPI_REG->BAUD = 250U; // ✅ 正确 SPI_REG->CTRL = SPI_CTRL_INIT_VAL; SPI_REG->BAUD = SPI_BAUD_DIV; ``` ### 7. 安全编码 | 禁止 | 必须 | |------|------| | `malloc`, `free`, `calloc`, `realloc` | 固定大小缓冲区 | | `new`, `delete` | 环形缓冲区用于数据流 | | VLA (变长数组) | 精确计算的缓冲区大小 | ```c #define BUFFER_SIZE 256U uint8_t buffer[BUFFER_SIZE]; ``` ### 8. 数据结构 | 场景 | 方式 | |------|------| | 相关配置数据 | `struct` | | 相关常量集合 | `enum` | | 相关状态数据 | `struct` | ```c /* 配置结构体 */ typedef struct { uint32_t base_address; uint16_t interrupt_priority; bool enable_dma; } peripheral_config_t; /* 句柄结构体 */ typedef struct { bool initialized; peripheral_config_t config; } peripheral_handle_t; ``` --- ## 工作模式 ### GENERATE 模式 直接应用本规范生成代码，无需保留任何旧代码。 ### REWRITE 模式 **核心原则: 功能流程优先** > ⚠️ 用户提供的源代码代表着原有的功能实现流程。即使代码有错误，在修改前必须先完整理解其功能流程，再进行符合规范的改写。不得为符合规范而破坏原有的功能流程。 **执行步骤:** | 步骤 | 内容 | |------|------| | **Step 1: 理解原代码** | 梳理数据流、识别状态机/算法、标注寄存器操作 | | **Step 2: 识别重写部分** | 确定需重构的函数/模块 | | **Step 3: 按规范重写** | 类型/命名/结构体符合规范，功能逻辑保持一致 | | **Step 4: 回查验证** | 验证功能流程未改变，所有规范已满足 | **关于原代码中的 bug：** - 原代码的 bug 属于"功能流程"的一部分 - 如果 bug 是用户期望保留的行为（如已知的工作around），保持原样 - 如果原代码有语法错误无法编译，标注问题但不擅自修复 - 除非用户明确要求，否则不修改原代码的功能逻辑 ### REVIEW 模式 检查现有代码是否符合嵌入式 C 规范。 **执行步骤:** | 步骤 | 内容 | |------|------| | **Step 1: 对照检查** | 按回查清单逐项检查 | | **Step 2: 标注问题** | 列出不符合规范的地方 | | **Step 3: 提出建议** | 提供具体的修改建议 | --- ## 项目文件结构 ``` project/ ├── inc/ │ ├── module_reg.h # 寄存器结构体定义（每个外设必须有） │ ├── module_config.h # 配置参数 │ └── module.h # 公共接口 └── src/ └── module.c # 实现 ``` --- ## PDCA 工作流 ``` ┌─────────────────────────────────────────────────────────┐ │ P (Plan) - 分析需求，检查完备性 │ │ • 确定模式: GENERATE / REWRITE / REVIEW │ │ • 检测领域/架构/外设关键词 │ │ • 检查关键信息是否完备（基地址等） │ │ ⚡ REWRITE模式: 优先理解原代码功能流程 │ ├─────────────────────────────────────────────────────────┤ │ D (Do) - 生成/重写代码 │ │ • GENERATE: 直接应用本规范 │ │ • REWRITE: 保持原功能流程，应用本规范 │ │ • 创建或更新 reg.h 寄存器结构体定义 │ │ • 生成符合规范的代码 │ ├─────────────────────────────────────────────────────────┤ │ C (Check) - 回查验证 │ │ • 对照回查清单逐项检查 │ │ • 验证寄存器结构体定义是否正确 │ │ ⚡ REWRITE模式: 验证功能流程是否保持一致 │ ├─────────────────────────────────────────────────────────┤ │ A (Act) - 修正输出 │ │ • 修正所有发现的问题 │ │ • 重新回查确认 │ │ • 输出合格代码 │ └─────────────────────────────────────────────────────────┘ ``` --- ## 回查清单 生成后必须逐项检查: | # | 检查项 | 不合格则修正 | |---|--------|------------| | 1 | 是否有对应的 reg.h 文件? | 创建 reg.h | | 2 | 寄存器是否用 `volatile uint32_t` 结构体定义? | 重构为结构体 | | 3 | 位字段是否有宏定义 (MASK/SHIFT)? | 添加位字段宏 | | 4 | 类型是否仅用 stdint.h? | 替换所有非标准类型 | | 5 | 命名是否符合规范表? | 修正所有命名 | | 6 | 所有 public 函数有错误处理? | 添加状态返回 | | 7 | 无任何 malloc/free/VLA? | 替换为固定缓冲区 | | 8 | 注释是否使用中文? | 重写注释 | | 9 | 文件头是否完整 (Doxygen)? | 添加 Doxygen | | 10 | 生成的代码是否符合规范? | 修正生成代码 | | ⚡ 11 | REWRITE 模式: 原代码的功能流程是否保持一致? | 确保数据流/状态机/算法逻辑不变 | | ⚡ 12 | 寄存器赋值是否都使用宏? | 添加宏定义，禁止字面值赋值 | --- ## 常见错误 ### 错误 1: 寄存器定义散落各处 ```c // ❌ 错误 #define SPI_CTRL_ADDR (*(volatile uint32_t *)0xA0010000) void spiInit(void) { SPI_CTRL_ADDR = 0x47; } // ✅ 正确 - 独立的 reg.h，统一的命名风格 #include "spi_reg.h" void spiInit(void) { SPI_REG->CTRL = SPI_CTRL_INIT_VAL; } ``` ### 错误 2: 魔法数字 ```c // ❌ 错误 - 含义不清 if (SPI_REG->STATUS & 0x04) { } SPI_REG->CTRL |= (1U << 7); // ✅ 正确 - 命名位字段宏 if (SPI_REG->STATUS & SPI_STATUS_TF_EMPT_MASK) { } /* TX FIFO empty */ SPI_REG->CTRL |= SPI_CTRL_SCPOL_MASK; /* 时钟极性 */ ``` ### 错误 3: 使用 `__I`/`__IO` 前缀 ```c // ❌ 错误 - ARM CMSIS 特有，不具可移植性 typedef struct { __I uint32_t DATA; __IO uint32_t CTRL; } spi_reg_t; // ✅ 正确 - 标准 volatile typedef struct { volatile uint32_t DATA; volatile uint32_t CTRL; } spi_reg_t; ``` ### 错误 4: 直接赋字面值 ```c // ❌ 错误 - 魔法数字 SPI_REG->BAUD = 250U; SPI_REG->CTRL = 0x08U; // ✅ 正确 - 使用宏定义 SPI_REG->BAUD = SPI_BAUD_DIV; SPI_REG->CTRL = SPI_CTRL_INIT_VAL; ``` --- ## 输出格式 GENERATE 模式输出每个外设模块: ``` module/ ├── module_reg.h # 寄存器结构体定义 ├── module.h # 公共接口 └── module.c # 实现 ```

path: README.md
content: # embedded-code-skill

> 嵌入式 C 代码生成规范 — 统一团队代码风格，生成生产级驱动代码

<!-- Language Switcher -->
[简体中文](README.md) · [English](README_EN.md) · [日本語](README_JP.md)

---

[![Platform: Claude Code | VS Code | Cursor | OpenClaw | Hermes Agent](https://img.shields.io/badge/Platform-Claude%20Code%20%7C%20VS%20Code%20%7C%20Cursor%20%7C%20OpenClaw%20%7C%20Hermes%20Agent-blue)]()
[![Standard: MISRA-C Compliant](https://img.shields.io/badge/Standard-MISRA--C%20Compliant-green)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)]()

---

## 特性

- **三种工作模式** — GENERATE（生成）、REWRITE（重写）、REVIEW（审查）
- **生产级代码** — 像嵌入式软件架构师一样思考，生成可演进、可测试的代码
- **多平台支持** — STM32 (Cortex-M)、PowerPC、RISC-V、ARM Cortex-A
- **团队统一** — 代码风格一致，review 有据可依
- **自我进化** — 内置达尔文式优化系统，持续改进规范质量

---

## 快速开始

```bash
/embedded-code-skill 生成一个STM32 UART驱动，基地址 0x4000C000
/embedded-code-skill 重写这段代码为符合规范的版本
/embedded-code-skill 审查这段代码是否符合规范
```

---

## 三种工作模式

### GENERATE 模式

直接应用规范生成代码，无需保留任何旧代码。

### REWRITE 模式

**核心原则: 功能流程优先**

- 用户提供的源代码代表着原有的功能实现流程
- 即使代码有错误，也必须先完整理解其功能流程再改写
- 不得为符合规范而破坏原有的功能逻辑
- 原代码的 bug 属于"功能流程"的一部分，默认保持原样

### REVIEW 模式

检查现有代码是否符合嵌入式 C 规范，按回查清单逐项检查并提出修改建议。

---

## 核心要求

| 要求 | 规范 |
|------|------|
| **可读性** | `snake_case` / `SCREAMING_SNAKE` / `camelCase` 命名，Doxygen 注释，中文优先 |
| **可移植性** | `stdint.h` 类型，`volatile` 寄存器宏，无 `int`/`char`/`long` |
| **数据结构** | `struct`/`enum` 组织数据，无散落全局变量 |
| **错误处理** | public 函数返回 `embedded_code_status_t`，NULL 检查 |
| **安全编码** | 禁止 `malloc`/`free`/VLA，固定大小缓冲区 |

---

## 生成代码前请提供

| 信息 | 必要性 | 示例 |
|------|--------|------|
| 外设寄存器基地址 | **必需** | `UART_BASE_ADDR = 0x4000C000U` |
| 芯片/架构类型 | 可推断 | `STM32`, `Cortex-M4`, `RISC-V` |

> **注意**: 基地址必须提供，禁止 AI 编造寄存器地址。

---

## 文件结构

```
embedded-code-skill/
├── SKILL.md                     # 斜杠命令入口
├── README.md                    # 本文档
│
├── .evolution/                  # 自我进化系统
│   ├── SKILL.md                # 进化系统主文件
│   ├── test-prompts.json       # 测试用例集
│   ├── results.tsv             # 优化历史记录
│   └── README.md               # 进化系统说明
│
├── embedded-code-skill-standards/        # 编码标准详情
│   └── SKILL.md
│
├── embedded-code-skill-arch/             # 架构模式
│   └── SKILL.md                # Cortex-M/A, PowerPC, RISC-V
│
├── embedded-code-skill-drivers/          # 驱动模板
│   └── SKILL.md                # UART, SPI, I2C, DMA, CAN
│
└── embedded-code-skill-domains/          # 领域规范
    └── SKILL.md                # 航天/军工/工业/汽车
```

---

## 输出格式

GENERATE 模式输出每个外设模块：

```
module/
├── module_reg.h    # 寄存器结构体定义
├── module.h        # 公共接口
└── module.c       # 实现
```

**uart_reg.h 示例:**

```c
/**
 * @file uart_reg.h
 * @brief UART 外设寄存器定义
 */
#ifndef UART_REG_H
#define UART_REG_H

#include <stdint.h>

/* 基地址 */
#define UART_BASE_ADDR  (0x4000C000U)

/* 寄存器结构体 */
typedef struct {
    volatile uint32_t DR;       /* 0x00: Data register */
    volatile uint32_t RSR;      /* 0x04: Receive status register */
    volatile uint32_t Reserved;
    volatile uint32_t FR;       /* 0x18: Flag register */
    volatile uint32_t IBRD;     /* 0x24: Integer baud rate divisor */
    volatile uint32_t FBRD;     /* 0x28: Fractional baud rate divisor */
    volatile uint32_t LCRH;     /* 0x2C: Line control register */
    volatile uint32_t CR;       /* 0x30: Control register */
} uart_reg_t;

/* 寄存器访问 */
#define UART_REG  ((uart_reg_t *) UART_BASE_ADDR)

#endif /* UART_REG_H */
```

---

## 自我进化系统

内置自我优化系统：

- **8维度评估** — 结构质量（60分）+ 实际效果（40分）
- **棘轮机制** — 只保留改进，自动回滚退步
- **子 agent 验证** — 效果维度必须用子 agent 执行
- **人在回路** — 每轮优化后暂停等待用户确认

### 触发进化

```
用户："优化 embedded-code-skill"      → 完整优化流程
用户："评估 embedded-code-skill 质量"  → 仅评估不优化
用户："运行 embedded-code-skill 自我进化" → 自动优化直到确认
```

---

## 贡献

欢迎提交 Issue 和 Pull Request！

---

## 许可

MIT License


path: README_EN.md
content: # embedded-code-skill

> Embedded C Code Generation Specification — Unified team code style, generate production-grade driver code

<!-- Language Switcher -->
[简体中文](README.md) · [English](README_EN.md) · [日本語](README_JP.md)

---

[![Platform: Claude Code | VS Code | Cursor | OpenClaw | Hermes Agent](https://img.shields.io/badge/Platform-Claude%20Code%20%7C%20VS%20Code%20%7C%20Cursor%20%7C%20OpenClaw%20%7C%20Hermes%20Agent-blue)]()
[![Standard: MISRA-C Compliant](https://img.shields.io/badge/Standard-MISRA--C%20Compliant-green)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)]()

---

## Features

- **Three Work Modes** — GENERATE, REWRITE, REVIEW
- **Production-Grade Code** — Think like an embedded software architect, generate evolvable and testable code
- **Multi-Platform** — STM32 (Cortex-M), PowerPC, RISC-V, ARM Cortex-A
- **Team Uniformity** — Consistent code style, review with evidence
- **Self-Evolution** — Built-in Darwin-style optimization system, continuous improvement

---

## Quick Start

```bash
/embedded-code-skill Generate an STM32 UART driver, base address 0x4000C000
/embedded-code-skill Rewrite this code to conform to the specification
/embedded-code-skill Review if this code conforms to the specification
```

---

## Three Work Modes

### GENERATE Mode

Generate code directly using the specification, no need to preserve old code.

### REWRITE Mode

**Core Principle: Function Flow First**

- User-provided source code represents the original functional implementation flow
- Even if code has errors, you must fully understand its functional flow before rewriting
- Never破坏 the original functional logic to conform to the specification
- Bugs in the original code are part of the "functional flow" and are kept by default

### REVIEW Mode

Check if existing code conforms to the Embedded C specification, check item by item against the review checklist and provide modification suggestions.

---

## Core Requirements

| Requirement | Specification |
|------------|----------------|
| **Readability** | `snake_case` / `SCREAMING_SNAKE` / `camelCase` naming, Doxygen comments |
| **Portability** | `stdint.h` types, `volatile` register macros, no `int`/`char`/`long` |
| **Data Structure** | `struct`/`enum` for data organization, no scattered global variables |
| **Error Handling** | Public functions return `embedded_code_status_t`, NULL checks |
| **Safe Coding** | No `malloc`/`free`/VLA, fixed-size buffers |

---

## Required Information Before Code Generation

| Information | Necessity | Example |
|-------------|----------|---------|
| Peripheral register base address | **Required** | `UART_BASE_ADDR = 0x4000C000U` |
| Chip/Architecture type | Inferable | `STM32`, `Cortex-M4`, `RISC-V` |

> **Note**: Base address must be provided, AI must not fabricate register addresses.

---

## File Structure

```
embedded-code-skill/
├── SKILL.md                     # Slash command entry
├── README.md                    # This file (Chinese)
├── README_EN.md                 # English version
├── README_JP.md                 # Japanese version
│
├── .evolution/                  # Self-evolution system
│   ├── SKILL.md                # Evolution system main file
│   ├── test-prompts.json       # Test case set
│   ├── results.tsv            # Optimization history
│   └── README.md               # Evolution system docs
│
├── embedded-code-skill-standards/
│   └── SKILL.md
│
├── embedded-code-skill-arch/
│   └── SKILL.md                # Cortex-M/A, PowerPC, RISC-V
│
├── embedded-code-skill-drivers/
│   └── SKILL.md                # UART, SPI, I2C, DMA, CAN
│
└── embedded-code-skill-domains/
    └── SKILL.md                # Aerospace/Military/Industrial/Automotive
```

---

## Output Format

GENERATE mode outputs each peripheral module:

```
module/
├── module_reg.h    # Register structure definition
├── module.h        # Public interface
└── module.c       # Implementation
```

**uart_reg.h Example:**

```c
/**
 * @file uart_reg.h
 * @brief UART peripheral register definition
 */
#ifndef UART_REG_H
#define UART_REG_H

#include <stdint.h>

/* Base address */
#define UART_BASE_ADDR  (0x4000C000U)

/* Register structure */
typedef struct {
    volatile uint32_t DR;       /* 0x00: Data register */
    volatile uint32_t RSR;      /* 0x04: Receive status register */
    volatile uint32_t Reserved;
    volatile uint32_t FR;       /* 0x18: Flag register */
    volatile uint32_t IBRD;     /* 0x24: Integer baud rate divisor */
    volatile uint32_t FBRD;     /* 0x28: Fractional baud rate divisor */
    volatile uint32_t LCRH;     /* 0x2C: Line control register */
    volatile uint32_t CR;       /* 0x30: Control register */
} uart_reg_t;

/* Register access */
#define UART_REG  ((uart_reg_t *) UART_BASE_ADDR)

#endif /* UART_REG_H */
```

---

## Self-Evolution System

Built-in self-optimization system based on Darwin.skill:

- **8-Dimension Evaluation** — Structural quality (60pts) + Actual effect (40pts)
- **Ratchet Mechanism** — Only keep improvements, auto-rollback on regression
- **Sub-agent Verification** — Effect dimensions must use sub-agents
- **Human-in-the-Loop** — Pause after each optimization round for user confirmation

### Trigger Evolution

```
User: "Optimize embedded-code-skill"           → Full optimization flow
User: "Evaluate embedded-code-skill quality"  → Evaluation only
User: "Run embedded-code-skill self-evolution" → Auto-optimize until confirmed
```

---

## Contributing

Issues and Pull Requests are welcome!

---

## License

MIT License


path: README_JP.md
content: # embedded-code-skill

> Embedded C コード生成仕様 — チームコードスタイルの統一、プロダクショングレードのドライバコード生成

<!-- Language Switcher -->
[简体中文](README.md) · [English](README_EN.md) · [日本語](README_JP.md)

---

[![Platform: Claude Code | VS Code | Cursor | OpenClaw | Hermes Agent](https://img.shields.io/badge/Platform-Claude%20Code%20%7C%20VS%20Code%20%7C%20Cursor%20%7C%20OpenClaw%20%7C%20Hermes%20Agent-blue)]()
[![Standard: MISRA-C Compliant](https://img.shields.io/badge/Standard-MISRA--C%20Compliant-green)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)]()

---

## 機能

- **3つの動作モード** — GENERATE（生成）、REWRITE（書き換え）、REVIEW（レビュー）
- **プロダクショングレードのコード** — 組込みソフトウェアアーキテクトのように考え、進化可能でテスト可能なコードを生成
- **マルチプラットフォーム** — STM32 (Cortex-M)、PowerPC、RISC-V、ARM Cortex-A
- **チーム統一** — 一貫したコードスタイル、レビューエビデンス
- **自己進化** — 組込みのダーウィン式最適化システム、継続的な改善

---

## クイックスタート

```bash
/embedded-code-skill STM32 UARTドライバを生成、ベースアドレス 0x4000C000
/embedded-code-skill このコードを仕様に合わせて書き換える
/embedded-code-skill このコードが仕様是否符合をレビュー
```

---

## 3つの動作モード

### GENERATE モード

仕様を直接適用してコードを生成。古いコードの保持は不要。

### REWRITE モード

**核心原則：機能フローファースト**

- ユーザーが提供したソースコードは元の機能実装フローを表す
- コードにエラーがあっても、書き換える前に機能フローを完全に理解する必要がある
- 仕様に合わせるために元の機能ロジックを壊してはならない
- 元コードのバグは「機能フロー」の一部であり、デフォルトで維持

### REVIEW モード

既存のコードが Embedded C 仕様に是否符合かをチェックし、レビューリストに従って項目ごとにチェックし、変更提案を提供。

---

## コア要件

| 要件 | 仕様 |
|------|------|
| **可読性** | `snake_case` / `SCREAMING_SNAKE` / `camelCase` 命名、Doxygenコメント |
| **移植性** | `stdint.h` タイプ、`volatile` レジスタマクロ、`int`/`char`/`long` 禁止 |
| **データ構造** | `struct`/`enum` でデータ組織、散らばったグローバル変数禁止 |
| **エラー処理** | public関数は `embedded_code_status_t` を返す、NULL チェック |
| **安全なコーディング** | `malloc`/`free`/VLA 禁止、固定サイズバッファ |

---

## コード生成前に提供する情報

| 情報 | 必要性 | 例 |
|------|--------|-----|
| 外周レジスタベースアドレス | **必須** | `UART_BASE_ADDR = 0x4000C000U` |
| チップ/アーキテクチャタイプ | 推論可能 | `STM32`, `Cortex-M4`, `RISC-V` |

> **注意**: ベースアドレスは必須。AIはレジスタアドレスを捏造してはならない。

---

## ファイル構造

```
embedded-code-skill/
├── SKILL.md                     # スラッシュコマンドエントリ
├── README.md                    # このファイル（中国語）
├── README_EN.md                 # 英語版
├── README_JP.md                # 日本語版
│
├── .evolution/                  # 自己進化システム
│   ├── SKILL.md                # 進化システムメインファイル
│   ├── test-prompts.json       # テストケースセット
│   ├── results.tsv            # 最適化履歴
│   └── README.md              # 進化システム文書
│
├── embedded-code-skill-standards/
│   └── SKILL.md
│
├── embedded-code-skill-arch/
│   └── SKILL.md                # Cortex-M/A, PowerPC, RISC-V
│
├── embedded-code-skill-drivers/
│   └── SKILL.md                # UART, SPI, I2C, DMA, CAN
│
└── embedded-code-skill-domains/
    └── SKILL.md                # 航空/軍事/産業/自動車
```

---

## 出力形式

GENERATE モードは各外周モジュールを出力：

```
module/
├── module_reg.h    # レジスタ構造体定義
├── module.h        # 公開インターフェース
└── module.c       # 実装
```

**uart_reg.h 例:**

```c
/**
 * @file uart_reg.h
 * @brief UART 外周レジスタ定義
 */
#ifndef UART_REG_H
#define UART_REG_H

#include <stdint.h>

/* ベースアドレス */
#define UART_BASE_ADDR  (0x4000C000U)

/* レジスタ構造体 */
typedef struct {
    volatile uint32_t DR;       /* 0x00: Data register */
    volatile uint32_t RSR;      /* 0x04: Receive status register */
    volatile uint32_t Reserved;
    volatile uint32_t FR;       /* 0x18: Flag register */
    volatile uint32_t IBRD;     /* 0x24: Integer baud rate divisor */
    volatile uint32_t FBRD;     /* 0x28: Fractional baud rate divisor */
    volatile uint32_t LCRH;     /* 0x2C: Line control register */
    volatile uint32_t CR;       /* 0x30: Control register */
} uart_reg_t;

/* レジスタアクセス */
#define UART_REG  ((uart_reg_t *) UART_BASE_ADDR)

#endif /* UART_REG_H */
```

---

## 自己進化システム

ダーウィン.skillに基づく組込み自己最適化システム：

- **8次元評価** — 構造品質（60点）+ 実際効果（40点）
- **ラチェット機構** — 改善のみ保持、自動的にロールバック
- **サブエージェント検証** — 効果次元はサブエージェントを使用する必要がある
- **人在ループ** — 各最適化ラウンド後に一時停止、ユーザーの確認待ち

### 進化をトリガー

```
ユーザー：「embedded-code-skillを最適化」           → 完全な最適化フロー
ユーザー：「embedded-code-skillの品質を評価」      → 評価のみ
ユーザー：「embedded-code-skillの自己進化を実行」  → 確認まで自動最適化
```

---

## 貢献

Issue と Pull Request を歓迎！

---

## ライセンス

MIT License


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)