一个智能体不是一堆提示词的集合，而是一套有层次、有分工、有约束的工程体系。
一、为什么架构设计是第一件事？
很多人搭建AI辅助开发体系的第一步，是打开编辑器写一段System Prompt：
你是一个嵌入式开发专家，擅长C语言、FreeRTOS、ESP32...然后发现：AI时而靠谱时而翻车，审查全靠心情，流程全靠手动提醒。问题出在哪？
因为你只定义了"身份"，没有定义"能力"。
一个能真正落地的嵌入式智能体，必须回答四个问题：
- 它会什么？ ------ 有哪些专项能力，覆盖哪些领域
- 它按什么流程做事？ ------ 从需求到提交，每一步做什么、谁来把关
- 它用什么工具？ ------ 平台命令行、代码分析、效率工具
- 它遵守什么规则？ ------ 哪些是红线，哪些是最佳实践，产出物放哪
这四个问题，对应智能体的四大模块。架构设计就是把这四个模块的边界、分工、协作关系定义清楚。
二、整体架构：四层能力模型
嵌入式专家采用四层能力模型，从下到上依次是：
#mermaid-svg-I72oV2P0ukolFD6p{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-I72oV2P0ukolFD6p .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-I72oV2P0ukolFD6p .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-I72oV2P0ukolFD6p .error-icon{fill:#552222;}#mermaid-svg-I72oV2P0ukolFD6p .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-I72oV2P0ukolFD6p .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-I72oV2P0ukolFD6p .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-I72oV2P0ukolFD6p .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-I72oV2P0ukolFD6p .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-I72oV2P0ukolFD6p .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-I72oV2P0ukolFD6p .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-I72oV2P0ukolFD6p .marker{fill:#333333;stroke:#333333;}#mermaid-svg-I72oV2P0ukolFD6p .marker.cross{stroke:#333333;}#mermaid-svg-I72oV2P0ukolFD6p svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-I72oV2P0ukolFD6p p{margin:0;}#mermaid-svg-I72oV2P0ukolFD6p .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-I72oV2P0ukolFD6p .cluster-label text{fill:#333;}#mermaid-svg-I72oV2P0ukolFD6p .cluster-label span{color:#333;}#mermaid-svg-I72oV2P0ukolFD6p .cluster-label span p{background-color:transparent;}#mermaid-svg-I72oV2P0ukolFD6p .label text,#mermaid-svg-I72oV2P0ukolFD6p span{fill:#333;color:#333;}#mermaid-svg-I72oV2P0ukolFD6p .node rect,#mermaid-svg-I72oV2P0ukolFD6p .node circle,#mermaid-svg-I72oV2P0ukolFD6p .node ellipse,#mermaid-svg-I72oV2P0ukolFD6p .node polygon,#mermaid-svg-I72oV2P0ukolFD6p .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-I72oV2P0ukolFD6p .rough-node .label text,#mermaid-svg-I72oV2P0ukolFD6p .node .label text,#mermaid-svg-I72oV2P0ukolFD6p .image-shape .label,#mermaid-svg-I72oV2P0ukolFD6p .icon-shape .label{text-anchor:middle;}#mermaid-svg-I72oV2P0ukolFD6p .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-I72oV2P0ukolFD6p .rough-node .label,#mermaid-svg-I72oV2P0ukolFD6p .node .label,#mermaid-svg-I72oV2P0ukolFD6p .image-shape .label,#mermaid-svg-I72oV2P0ukolFD6p .icon-shape .label{text-align:center;}#mermaid-svg-I72oV2P0ukolFD6p .node.clickable{cursor:pointer;}#mermaid-svg-I72oV2P0ukolFD6p .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-I72oV2P0ukolFD6p .arrowheadPath{fill:#333333;}#mermaid-svg-I72oV2P0ukolFD6p .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-I72oV2P0ukolFD6p .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-I72oV2P0ukolFD6p .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-I72oV2P0ukolFD6p .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-I72oV2P0ukolFD6p .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-I72oV2P0ukolFD6p .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-I72oV2P0ukolFD6p .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-I72oV2P0ukolFD6p .cluster text{fill:#333;}#mermaid-svg-I72oV2P0ukolFD6p .cluster span{color:#333;}#mermaid-svg-I72oV2P0ukolFD6p div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-I72oV2P0ukolFD6p .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-I72oV2P0ukolFD6p rect.text{fill:none;stroke-width:0;}#mermaid-svg-I72oV2P0ukolFD6p .icon-shape,#mermaid-svg-I72oV2P0ukolFD6p .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-I72oV2P0ukolFD6p .icon-shape p,#mermaid-svg-I72oV2P0ukolFD6p .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-I72oV2P0ukolFD6p .icon-shape .label rect,#mermaid-svg-I72oV2P0ukolFD6p .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-I72oV2P0ukolFD6p .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-I72oV2P0ukolFD6p .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-I72oV2P0ukolFD6p :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 第一层：质量保障（14个）
专项审查
150+检查项
风险分级
自动触发
第二层：开发工作流（14个）
PIV双循环
3道门禁
端到端自动化
第三层：辅助工具（5个）
平台命令行
代码库分析
三侧Token压缩
第四层：社区技能（4个）
项目策略
arXiv查证
代码图谱
波形图
为什么是这个顺序？因为质量是地基，流程是骨架，工具是肌肉，社区是外延。
- 没有质量保障层，工作流再顺也是在生产垃圾代码
- 没有工作流层，审查技能再强也是零散的，无法嵌入开发过程
- 没有工具层，每次操作都要手动敲命令，效率上不去
- 没有社区层，所有能力都要自己造轮子，重复劳动
四层之间是单向依赖：上层可以调用下层，下层不依赖上层。审查技能不知道工作流的存在，工作流可以调用审查技能；工具被各层使用，但不反过来依赖它们。
三、第一层：质量保障模块（14个审查技能）
这是整个智能体的核心竞争力。通用AI和嵌入式专家的差距，90%体现在这一层。
3.1 分类组织
14个审查技能按领域分为五组：
| 分组 | 技能 | 检查项数 | 核心关注点 |
|---|---|---|---|
| 内存安全（4个） | buffer_overflow_check | 10项 | 缓冲区溢出、TOCTOU、整数溢出、格式化字符串 |
| memory_leak_check | 12项 | Double Free、堆碎片、野指针、泄漏路径 | |
| stack_overflow_check | 10项 | 栈消耗估算、递归深度、RTOS任务栈 | |
| struct_best_practice_check | 18项 | 对齐、位域、内存优化、寄存器映射 | |
| 硬件相关（3个） | interrupt_check | 10项 | FromISR接口、volatile、标志清除、原子操作 |
| dma_cache_check | 7项 | Cache一致性、对齐、栈内存做DMA | |
| peripheral_conflict_check | 10项 | GPIO复用、时钟冲突、寄存器访问 | |
| 系统管理（3个） | rtos_task_check | 10项 | 死锁、优先级反转、信号量泄漏、栈大小 |
| watchdog_timer_check | 12项 | 超时配置、多任务喂狗、定时器溢出 | |
| power_management_check | 11项 | GPIO漏电、功耗量化、睡眠模式、唤醒源 | |
| 通信存储（2个） | communication_protocol_check | 9项 | 超时、CRC、粘包、字节序、重传 |
| flash_storage_check | 13项 | 擦写寿命、OTA回滚、掉电保护、分区表 | |
| 质量保障（2个） | error_handling_check | 9项 | 返回值检查、资源泄漏、恢复策略 |
| firmware_code_style | 15类 | 命名、分层、注释、安全规范 |
总计：150+检查项，每一项都包含四个要素：错误示例、正确示例、原理分析、后果说明。
3.2 为什么要拆成14个而不是一个"全能审查"？
这是设计中最关键的决策。拆成14个专项技能的好处：
1. 触发精准：写UART代码时只调用通信协议+DMA+错误处理三个技能，不需要跑全部150项检查，节省Token、提高效率。
2. 深度足够 ：每个技能只关注一个领域，可以把这个领域的检查项做到专家级。比如dma_cache_check只有7项，但每一项都是嵌入式DMA最容易踩的坑，有完整的原理和示例。
3. 可独立维护：新增一个检查领域（比如安全加密审查），只需要加一个技能文件夹，不影响其他技能。
4. 可组合调用 ：piv-review-changes工作流会根据改动的代码领域，自动组合调用相关技能，实现"全面审查"的效果。
3.3 自动触发映射
技能不是放那就完事了，必须定义什么时候调用哪个技能 。这个映射关系写在global-rule.md里：
| 改动领域 | 强制调用技能 | 检查重点 |
|---|---|---|
| DMA/内存搬运/cache | dma_cache_check | cache刷新、对齐、栈内存做DMA |
| 中断/ISR/NVIC | interrupt_check | 标志清除、FromISR接口、共享变量 |
| 缓冲区/字符串/memcpy | buffer_overflow_check | 边界检查、危险函数 |
| 通信协议（UART/SPI/I2C） | communication_protocol_check | 超时、校验、重传 |
| RTOS任务/信号量 | rtos_task_check | 优先级、死锁、栈大小 |
| ... | ... | ... |
AI生成或修改代码后，自动按领域匹配并调用对应技能。这就是质量门禁的底层机制。
四、第二层：开发工作流模块（14个PIV技能）
质量保障层解决了"代码写得对不对"的问题，工作流层解决"开发过程顺不顺"的问题。
4.1 PIV双循环架构
工作流采用PIV双循环设计，参考coleam00/skills的PIV框架，结合嵌入式项目定制：
#mermaid-svg-BGrku7N6GTZAHnEA{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-BGrku7N6GTZAHnEA .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-BGrku7N6GTZAHnEA .error-icon{fill:#552222;}#mermaid-svg-BGrku7N6GTZAHnEA .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-BGrku7N6GTZAHnEA .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-BGrku7N6GTZAHnEA .marker{fill:#333333;stroke:#333333;}#mermaid-svg-BGrku7N6GTZAHnEA .marker.cross{stroke:#333333;}#mermaid-svg-BGrku7N6GTZAHnEA svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-BGrku7N6GTZAHnEA p{margin:0;}#mermaid-svg-BGrku7N6GTZAHnEA .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-BGrku7N6GTZAHnEA .cluster-label text{fill:#333;}#mermaid-svg-BGrku7N6GTZAHnEA .cluster-label span{color:#333;}#mermaid-svg-BGrku7N6GTZAHnEA .cluster-label span p{background-color:transparent;}#mermaid-svg-BGrku7N6GTZAHnEA .label text,#mermaid-svg-BGrku7N6GTZAHnEA span{fill:#333;color:#333;}#mermaid-svg-BGrku7N6GTZAHnEA .node rect,#mermaid-svg-BGrku7N6GTZAHnEA .node circle,#mermaid-svg-BGrku7N6GTZAHnEA .node ellipse,#mermaid-svg-BGrku7N6GTZAHnEA .node polygon,#mermaid-svg-BGrku7N6GTZAHnEA .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-BGrku7N6GTZAHnEA .rough-node .label text,#mermaid-svg-BGrku7N6GTZAHnEA .node .label text,#mermaid-svg-BGrku7N6GTZAHnEA .image-shape .label,#mermaid-svg-BGrku7N6GTZAHnEA .icon-shape .label{text-anchor:middle;}#mermaid-svg-BGrku7N6GTZAHnEA .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-BGrku7N6GTZAHnEA .rough-node .label,#mermaid-svg-BGrku7N6GTZAHnEA .node .label,#mermaid-svg-BGrku7N6GTZAHnEA .image-shape .label,#mermaid-svg-BGrku7N6GTZAHnEA .icon-shape .label{text-align:center;}#mermaid-svg-BGrku7N6GTZAHnEA .node.clickable{cursor:pointer;}#mermaid-svg-BGrku7N6GTZAHnEA .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-BGrku7N6GTZAHnEA .arrowheadPath{fill:#333333;}#mermaid-svg-BGrku7N6GTZAHnEA .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-BGrku7N6GTZAHnEA .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-BGrku7N6GTZAHnEA .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BGrku7N6GTZAHnEA .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-BGrku7N6GTZAHnEA .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BGrku7N6GTZAHnEA .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-BGrku7N6GTZAHnEA .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-BGrku7N6GTZAHnEA .cluster text{fill:#333;}#mermaid-svg-BGrku7N6GTZAHnEA .cluster span{color:#333;}#mermaid-svg-BGrku7N6GTZAHnEA div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-BGrku7N6GTZAHnEA .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-BGrku7N6GTZAHnEA rect.text{fill:none;stroke-width:0;}#mermaid-svg-BGrku7N6GTZAHnEA .icon-shape,#mermaid-svg-BGrku7N6GTZAHnEA .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BGrku7N6GTZAHnEA .icon-shape p,#mermaid-svg-BGrku7N6GTZAHnEA .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-BGrku7N6GTZAHnEA .icon-shape .label rect,#mermaid-svg-BGrku7N6GTZAHnEA .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BGrku7N6GTZAHnEA .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-BGrku7N6GTZAHnEA .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-BGrku7N6GTZAHnEA :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 外层循环（低频，大需求时走）
每个切片进入内层循环
内层循环（高频，每次开发必走）
prime-codebase
加载上下文
piv-plan-implementation
Validation-First计划
piv-implement
按计划实现
piv-validate
编译+行为验证
piv-review-changes
审查（调14技能）
piv-commit → PR
原子提交 → 创建PR
plan-create-prd
需求澄清→PRD
plan-architecture
架构设计→SDD
piv-slice-epic
拆解为可交付切片
外层循环处理"大需求"：一个功能涉及多个模块、多种硬件、协议不明确时，先走外层做需求澄清、架构设计、任务拆解。
内层循环处理"每次开发"：不管需求大小，只要写代码，就必须走prime→plan→implement→validate→review→commit这六步。
4.2 三道强制门禁
内层循环中有三道质量门禁，不通过不能进入下一步：
| 门禁 | 所在环节 | 通过条件 | 不通过怎么办 |
|---|---|---|---|
| 计划门禁 | piv-plan-implementation | 必须有Validation-First的验证方法 | 回到计划阶段补充 |
| 验证门禁 | piv-validate | 编译无新增错误/警告 + 行为验证通过 + 边界覆盖 | 回到implement修复 |
| 审查门禁 | piv-review-changes | 无critical/high问题 + 审查报告已产出 | 回到implement/validate |
这三道门禁是整个工作流的质量底线。没有门禁的工作流只是"流程表演"，有门禁的工作流才是真正的质量保障。
4.3 核心方法论
PIV工作流不是简单的步骤排列，背后有几个关键设计理念：
1. Context is King（上下文至上）
动手写代码前，必须先通过prime-codebase加载代码库上下文------项目结构、技术栈、编码约定、相关模块。AI不了解项目就写代码，等于闭着眼开车。
2. Validation-First（验证优先）
写代码之前先想清楚"怎么证明它工作"。计划里必须包含验证方法：编译通过？单元测试？串口回环？异常注入？先定义验证标准，再写实现代码。
3. 对终点具体，对手段放权
PRD和SDD里精确规定"做什么、验收标准是什么"，但实现路径留给开发者（或AI）自由选择。不规定"用哪个函数、怎么命名"，只规定"必须满足这些验收条件"。
4. Inherit don't re-decide（继承不重议）
PRD里定了的需求，SDD里定了的架构，实现阶段直接继承，不重新讨论。避免每一步都从头开始决策，导致需求漂移。
五、第三层：辅助工具模块（5个）
前两层解决了"质量"和"流程"，工具层解决"效率"。
| 工具 | 功能 | 设计定位 |
|---|---|---|
| esp-idf-helper | ESP-IDF命令行工作流（配置/编译/烧录/监控/排错） | 平台专属，本地化Windows+Git Bash多子项目 |
| analyzing-projects | 陌生代码库系统性分析（结构/技术栈/数据流/约定） | 接手新项目时快速建立认知 |
| caveman | 输出侧压缩：少说（删填充词、客套话） | 默认常驻，省输出Token |
| tokenzero | 输入侧压缩：少喂（本地npm CLI，无损压缩输入） | 手动触发，省输入Token |
| ponytail | 生成侧压缩：少写（决策梯子/YAGNI，能不写就不写） | 默认常驻，嵌入式禁ultra档 |
这里有一个很有意思的设计：三侧Token压缩。
- 输入侧（tokenzero）：喂给AI的代码和文档太多？用tokenzero压缩，去掉注释、空行、重复结构，无损保留语义。
- 输出侧（caveman）：AI回复太啰嗦？caveman自动删掉冠词、填充词、客套话，只保留关键信息。
- 生成侧（ponytail）：AI写代码太多？ponytail走"决策梯子"------需要存在吗？已有吗？标准库有吗？一行能搞定吗？能不写就不写。
三侧同时压缩，Token消耗可以降到原来的30%-50%。对于嵌入式项目来说，这意味着同样的上下文窗口能装下更多代码，AI能看到更完整的项目结构。
六、第四层：社区技能模块（4个）
最后一层是外部能力引入。不需要所有能力都自己造，社区已经有成熟的技能，直接引入即可。
| 技能 | 功能 | 依赖 |
|---|---|---|
| advise-project-approach | 项目策略咨询：动手前/中/后研究最佳路径 | 无本地依赖 |
| neuroarxiv | 新架构前查arXiv先例，避免重复造轮子 | 需联网 |
| using-codegraph | tree-sitter代码知识图谱，SQLite亚毫秒查询 | 需Python + codegraph CLI |
| wavedrom-gen | 时序描述→WaveJSON→SVG/PNG/HTML波形图 | 需Node 20+ + npm ci |
引入社区技能的原则：保留上游原结构，不做破坏性修改。这样上游更新时可以直接diff合并，不需要重新适配。
这一层的意义在于：智能体的能力边界不应该由你一个人定义。社区有好的工具，直接拿来用，把精力放在自己的核心领域（嵌入式审查+工作流）上。
七、目录结构设计：.codebuddy的组织方式
讲完四大模块，来看它们在文件系统上怎么组织。整个智能体就是项目根目录下的一个.codebuddy文件夹：
c
项目根目录/
├── .codebuddy/
│ ├── README.md # 配置指南（人读的文档）
│ ├── settings.json # 全局配置（机器读的参数）
│ ├── global-rule.md # 全局强制规则（AI必须遵守）
│ ├── plans/ # 实现计划产出目录
│ │ ├── uart_dma_rx.md # 人类可读的计划
│ │ └── uart_dma_rx.json # 结构化验证用
│ ├── code-reviews/ # 审查报告产出目录
│ │ └── 2026-08-30-uart_dma.md
│ ├── schemas/ # JSON Schema（产出物验证规范）
│ │ ├── implementation-plan.schema.json
│ │ └── review-report.schema.json
│ └── skills/ # 37个技能
│ ├── buffer_overflow_check/
│ │ └── SKILL.md
│ ├── dma_cache_check/
│ │ └── SKILL.md
│ ├── piv-plan-implementation/
│ │ └── SKILL.md
│ └── ...（共37个文件夹）
├── docs/ # PRD/SDD等正式文档
│ ├── PRD_uart_485_slave.md
│ └── SDD_uart_485_slave.md
└── src/ # 你的源代码7.1 设计原则
1. 配置与产出分离
skills/、schemas/、global-rule.md、settings.json是配置，纳入git版本控制，团队共享plans/、code-reviews/是产出，可选纳入git（计划建议纳入，审查报告建议.gitignore）
2. 一个技能一个文件夹
每个技能是独立的文件夹，里面至少有一个SKILL.md。需要额外资源（脚本、模板、参考文档）也放在这个文件夹里。技能之间不互相引用文件，保持独立可迁移。
3. 双格式产出
关键产出物（实现计划、审查报告）同时生成Markdown和JSON：
- Markdown给人看，git diff友好，适合评审
- JSON给机器验证，按Schema检查字段完整性，适合CI/CD集成
4. 正式文档与工作产物分离
PRD、SDD放在项目的docs/目录（正式文档，长期保留），实现计划和审查报告放在.codebuddy/下（工作产物，随开发迭代）。
八、配置体系：三件套撑起整个智能体
四大模块是"能力"，配置体系是"约束"。能力再强，没有约束也会跑偏。
8.1 settings.json ------ 全局参数
这是机器读的配置文件，控制智能体的行为模式：
json
{
"autoInvokeSkill": true, // 自动触发审查技能
"strictMode": true, // 严格模式：必须修复所有问题
"codeLanguage": "C", // 项目主语言
"scopes": ["embedded", "esp32", "rtos", "firmware"],
"maxContextFileNum": 10, // 最大上下文文件数
"enableCodeReviewAutoScan": true, // 启用自动扫描
"disableUnreasonableRefactor": true, // 禁止不合理重构
"preferChineseReply": true, // 中文回复
"excludePaths": ["build/", "output/", "keil/", "*.hex", "*.bin"],
"enableSmartContextFilter": true, // 智能上下文过滤
"autoCompressConversation": true, // 自动压缩对话
"enforceSkillOnCodeGen": true, // 代码生成时强制检查
"autoReviewAfterEdit": true // 编辑后自动审查
}关键参数解读：
- strictMode：严格模式开关。开启后，致命和高危问题必须修复才能提交。这是质量底线的总开关。
- autoInvokeSkill：自动触发审查。关闭后AI不会自动调用审查技能，需要手动指定。
- scopes：项目领域标签。帮助AI理解项目类型，在通用场景下也能保持领域意识。
- disableUnreasonableRefactor：禁止不合理重构。AI有时候会"好心办坏事"，把能跑的代码重构出bug，这个参数防止过度重构。
8.2 global-rule.md ------ 全局强制规则
这是AI必须遵守的"宪法"，定义了所有代码生成、修改、审查的硬性规则：
markdown
## 1. 硬件相关硬性规则
- 禁止自动优化硬件初始化代码
- 禁止随意修改寄存器、时钟、GPIO、DMA、NVIC配置
- 所有硬件改动必须给出风险提示、原因、替代方案
## 2. 安全规范
- 所有数组、缓冲区必须做边界判断
- 禁止裸指针直接运算
- 中断函数必须极简，禁止延时、禁止循环阻塞
## 3. RTOS规范
- FreeRTOS禁止在中断中调用非FromISR接口
- 栈分配禁止大数组，大缓冲区必须全局/静态
## 4. 评审优先级
安全风险 > 稳定性风险 > 性能 > 代码风格global-rule.md和skills的区别：
- global-rule是"所有场景都适用"的通用红线，比如"中断里不能阻塞"
- skills是"特定领域的深度检查"，比如dma_cache_check里的7项DMA专项检查
global-rule管"不能做什么 "，skills管"应该怎么检查"。
8.3 schemas/ ------ 产出物验证规范
这是最容易被忽略但非常工程化的一层。关键产出物（实现计划、审查报告）有对应的JSON Schema，用来验证产出的完整性：
c
implementation-plan.schema.json → 验证实现计划是否包含：
- 需求描述
- 验证方法（Validation-First）
- 实现步骤
- 风险评估
review-report.schema.json → 验证审查报告是否包含：
- 检查范围
- 问题列表（位置+等级+原理+修复）
- 结论有了Schema，AI生成产出后可以自动验证：字段齐不齐？类型对不对？必填项有没有？这就是结构化产出的质量保障。
下面是配置三件套与产出物验证的整体流程：
#mermaid-svg-Px9UAi5OtNbKi9wD{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Px9UAi5OtNbKi9wD .error-icon{fill:#552222;}#mermaid-svg-Px9UAi5OtNbKi9wD .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Px9UAi5OtNbKi9wD .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Px9UAi5OtNbKi9wD .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Px9UAi5OtNbKi9wD .marker.cross{stroke:#333333;}#mermaid-svg-Px9UAi5OtNbKi9wD svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Px9UAi5OtNbKi9wD p{margin:0;}#mermaid-svg-Px9UAi5OtNbKi9wD .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster-label text{fill:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster-label span{color:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster-label span p{background-color:transparent;}#mermaid-svg-Px9UAi5OtNbKi9wD .label text,#mermaid-svg-Px9UAi5OtNbKi9wD span{fill:#333;color:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD .node rect,#mermaid-svg-Px9UAi5OtNbKi9wD .node circle,#mermaid-svg-Px9UAi5OtNbKi9wD .node ellipse,#mermaid-svg-Px9UAi5OtNbKi9wD .node polygon,#mermaid-svg-Px9UAi5OtNbKi9wD .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Px9UAi5OtNbKi9wD .rough-node .label text,#mermaid-svg-Px9UAi5OtNbKi9wD .node .label text,#mermaid-svg-Px9UAi5OtNbKi9wD .image-shape .label,#mermaid-svg-Px9UAi5OtNbKi9wD .icon-shape .label{text-anchor:middle;}#mermaid-svg-Px9UAi5OtNbKi9wD .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Px9UAi5OtNbKi9wD .rough-node .label,#mermaid-svg-Px9UAi5OtNbKi9wD .node .label,#mermaid-svg-Px9UAi5OtNbKi9wD .image-shape .label,#mermaid-svg-Px9UAi5OtNbKi9wD .icon-shape .label{text-align:center;}#mermaid-svg-Px9UAi5OtNbKi9wD .node.clickable{cursor:pointer;}#mermaid-svg-Px9UAi5OtNbKi9wD .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Px9UAi5OtNbKi9wD .arrowheadPath{fill:#333333;}#mermaid-svg-Px9UAi5OtNbKi9wD .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Px9UAi5OtNbKi9wD .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Px9UAi5OtNbKi9wD .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Px9UAi5OtNbKi9wD .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Px9UAi5OtNbKi9wD .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Px9UAi5OtNbKi9wD .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster text{fill:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD .cluster span{color:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Px9UAi5OtNbKi9wD .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Px9UAi5OtNbKi9wD rect.text{fill:none;stroke-width:0;}#mermaid-svg-Px9UAi5OtNbKi9wD .icon-shape,#mermaid-svg-Px9UAi5OtNbKi9wD .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Px9UAi5OtNbKi9wD .icon-shape p,#mermaid-svg-Px9UAi5OtNbKi9wD .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Px9UAi5OtNbKi9wD .icon-shape .label rect,#mermaid-svg-Px9UAi5OtNbKi9wD .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Px9UAi5OtNbKi9wD .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Px9UAi5OtNbKi9wD .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Px9UAi5OtNbKi9wD :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 按 Schema 校验
按 Schema 校验
字段/类型/必填项
字段/类型/必填项
约束
配置三件套
settings.json
全局参数
global-rule.md
强制规则
schemas/
验证规范
AI 生成产出物
实现计划
Markdown + JSON
审查报告
Markdown + JSON
implementation-plan.schema.json
review-report.schema.json
通过 → 进入下一步
九、设计原则总结
回顾整个架构设计，有几个核心原则贯穿始终：
| 原则 | 含义 | 体现 |
|---|---|---|
| 分层解耦 | 四层能力单向依赖，上层调用下层 | 审查技能不依赖工作流，工作流调用审查 |
| 单一职责 | 一个技能只做一件事，做到专家级 | 14个审查技能各管一个领域 |
| 配置驱动 | 行为由配置控制，不是硬编码 | settings.json控制严格模式、自动审查等 |
| 双格式产出 | 人类可读+机器可验证 | Markdown + JSON + Schema |
| 可迁移 | 复制文件夹即可用在新项目 | .codebuddy目录自包含，无外部依赖 |
| 可演进 | 新增能力不破坏现有结构 | 加技能文件夹即可，不需要改架构 |
十、小结
一个嵌入式智能体的整体架构，就是四层能力 + 三件套配置：
- 四层能力：质量保障（14个审查技能）→ 开发工作流（14个PIV技能）→ 辅助工具（5个）→ 社区技能（4个）
- 三件套配置：settings.json（参数）+ global-rule.md（规则）+ schemas/（验证规范）
- 目录组织 ：一个
.codebuddy文件夹，配置与产出分离，技能独立可迁移
架构搭好了，接下来就是往里面填内容。下一篇，我们深入最核心的设计单元------Skill技能的设计方法论，看看一个SKILL.md应该包含什么、怎么写触发条件、怎么控制粒度。
架构是骨架，技能是血肉。骨架正了，血肉才不会长歪。