# 架构决策记录 (ADR)

## ADR-001: 测试驱动 SDK 演进

- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 寄存器测试是 SDK 的第一用户，测试代码直接演进为 LL 层驱动
- 理由: bring-up 阶段的核心产出是验证寄存器功能，测试代码天然包含了对寄存器的精确操作逻辑，提炼为 LL 层零浪费
- 影响: Test/cases/ 的代码质量要求等同于 SDK 代码；每个功能单元的测试代码必须结构化，便于后续提炼

## ADR-002: HAL/LL 双层架构，参考 STM32CubeH7

- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 采用与 STM32CubeH7 一致的 HAL/LL 双层架构，包括句柄模式、弱回调、模块化编译
- 理由: STM32CubeH7 是经过大规模验证的工业级 SDK 架构，HAL/LL 双层兼顾了可移植性和性能，开发者社区熟悉度高
- 影响: 驱动代码必须遵循 HAL/LL 分层；HAL 用句柄+状态机+回调，LL 用内联函数直操寄存器；编译体积由 hal_conf.h 宏开关控制

## ADR-003: 33 个功能单元分 7 阶段 bring-up

- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 按 bring-up 逻辑将 33 个功能单元分为 P0-P6 七个阶段，P0-P1 串行，P2-P6 可按需并行
- 理由: 芯片 bring-up 有天然依赖——必须先能跑（P0），才能有调试输出（P1），然后才能测其他外设。但模拟、定时器、存储、高速接口之间没有强依赖，可以并行
- 影响: 任务编号用 D{阶段号}-{序号}，阶段切换需人类确认

## ADR-004: 1 人 + 2 AI 单仓库协作

- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 采用 1 人 + Arch AI + Worker AI 的协作模式，单仓库，不需要 review 仓库
- 理由: 嵌入式项目文件数少但精度高，Arch AI 和 Worker AI 在同一仓库操作更直接。测试包含在 Worker AI 职责内，不需要独立 QA AI
- 影响: 去掉 errlens 的 review/ 目录和 QA AI 角色；Worker AI 同时负责开发和测试

## ADR-005: Arch AI 角色可由任何 AI 担当

- 日期: 2026-05-27
- 状态: 已采纳
- 决策: Arch AI 和 Worker AI 不是绑定到某个特定 AI 平台的角色定义，而是职责定义。任何 AI（扣子、Claude Code、DeepSeek 等）读到 card.md 即可担当
- 理由: 实际使用中不同场景适合不同 AI——架构讨论用扣子对话，代码执行用 Claude Code 终端，快速查询用 DeepSeek CLI。强制绑定单一平台会降低效率
- 影响: card.md 必须自包含，不假设读它的 AI 有任何前置上下文；AGENTS.md 是通用上下文锚点