# 架构文档

本文件是系统的顶层地图。保持简洁，需要时指向更深入的文档。

## 系统形状

- 产品：{{项目名称}}
- 主要用户工作流：{{主要工作流描述}}
- 运行时表面：{{cli / web / api / desktop}}
- 产品行为的真实来源：本文件 + `feature_list.json`

## 模块地图

| 模块 | 职责 | 主要入口 | 关联规格 |
|------|------|----------|----------|
| `src/{{模块a}}/` | {{职责描述}} | {{入口文件}} | {{规格路径}} |
| `src/{{模块b}}/` | {{职责描述}} | {{入口文件}} | {{规格路径}} |

## 层级模型

使用固定的方向性模型，防止 agent 发明临时架构：

```
types → config → repo → service → api → cli/ui
```

低层不得依赖高层。跨层关注点应通过显式的 provider 或 adapter 边界进入。

## 硬依赖规则

- 低层模块不得导入高层模块。
- CLI/UI 不得绕过 service 层的契约。
- 数据访问必须通过 repository 或等效适配器。
- 共享工具必须保持通用，不得积累领域逻辑。
- 新依赖应在相关计划或设计文档中说明理由。

## 热点区域

- {{最难安全修改的区域}}
- {{边界薄弱或测试脆弱的区域}}

## 变更检查清单

当你触及架构相关代码时：

1. 如果模块地图或允许的边界发生变化，更新本文件。
2. 如果推理发生变化，更新相关设计文档。
3. 如果规则应该被机械地执行，添加或更新可执行检查。