# Architecture Brief

## 1. 系统概览

- 系统边界: 用 2-4 句话说明当前项目负责什么、不负责什么。
- 核心能力: 列出用户可见功能、核心服务、后台任务、集成系统或关键模块。
- 主要数据流: 用 `入口 -> 处理 -> 存储/下游 -> 验证/回写` 的形式写出主链路。

## 2. 分层职责

| 层 | 职责 | 主要目录 |
| --- | --- | --- |
| Interface 层 | 页面、API、CLI、Webhook、消息入口 | `待补` |
| Application 层 | 编排流程、用例、状态推进 | `待补` |
| Domain 层 | 核心业务规则、不变量、领域对象 | `待补` |
| Infrastructure 层 | 数据库、缓存、队列、外部服务、SDK | `待补` |
| Governance 层 | 规则、验证、trace、回归、知识沉淀 | `docs/harness/`, `docs/testing/`, `traces/` |

按项目实际技术栈改名即可；不需要强行保留这五层。

## 2.1 领域模型入口

- 核心实体入口: `docs/context/domain-model.md` 或等价文件
- 状态流转入口: `docs/product/state-matrix.yaml` 或等价文件
- 业务规则入口: `docs/product/`、`docs/spec/` 或等价 truth source
- 不变量入口: 验收标准、测试策略、契约或 schema
- 领域逻辑定位入口: `docs/ai/repo-map.md`、主模块入口、服务目录索引

## 3. 真相源

- 产品真相源: `待补`
- 设计真相源: `待补`
- Contract 真相源: `待补`
- 类型 / Schema 真相源: `待补`
- 测试真相源: `docs/testing/*`
- 领域模型真相源: `待补`

要求:

- 没有明确真相源的项目事实，不要写成已确认结论。
- 如果某项真相源缺失但当前任务依赖它，先在 `CURRENT_TASK.md` 或 task 分析里标成缺口。

## 4. 关键模块

| 模块 | 责任 | 上游 | 下游 | 风险 |
| --- | --- | --- | --- | --- |
| `待补模块-1` | 说明职责 | 谁触发它 | 它调用谁 | 最主要风险 |
| `待补模块-2` | 说明职责 | 谁触发它 | 它调用谁 | 最主要风险 |

至少覆盖本项目当前最重要的 3-7 个模块。

## 5. 关键约束

- 写当前项目必须遵守的架构边界、共享契约、数据边界、依赖约束和部署约束。
- 这里只保留项目事实，不复制通用编码常识。
- 如果约束已经在 `docs/architecture/constraints.md`、schema 或 lint 中明确，可直接引用，不必重写。

## 6. 高风险区域

- 先列当前任务最容易出错的状态流转、数据修改、权限、外部系统、异步流程或公共契约。
- 每条风险尽量对应一个可验证入口，例如测试、日志、review gate 或回滚方式。

## 7. 建议阅读顺序

1. `AGENTS.md`
2. `docs/ai/repo-map.md`
3. 当前任务相关模块入口
4. `docs/harness/architecture.md`
5. `docs/harness/rule-governance.md`
6. `docs/testing/*`

## 8. 裁剪要求

- 初始化后，把所有 `待补`、示例字段和不适用层级替换成当前项目事实。
- 如果项目很小，可以把本文件控制在 30-80 行；重点是帮助新会话快速建立正确边界，而不是写成长报告。
