软件架构文档

使用根目录下的ARCHITECTURE.md和docs/*.md文件记录软件架构，包含Mermaid图表。当项目根目录存在ARCHITECTURE.md时主动使用，或调用以创建初始架构文档。涵盖系统设计、数据流、组件关系和代码组织，并引用关键入口点和抽象。

结构

project/
├── ARCHITECTURE.md      # 高级系统概览
└── docs/
    ├── <组件>.md   # 详细的组件文档
    └── ...

主动使用

当项目根目录存在ARCHITECTURE.md时：

在重大更改前：阅读ARCHITECTURE.md以理解系统结构
结构更改后：更新图表和入口点
添加组件时：创建新的docs/*.md文件，并在ARCHITECTURE.md中链接
重构期间：更新受影响的图表和文件引用

创建架构文档

初始设置工作流

分析代码库结构
- 确定入口点（main, CLI, API处理器）
- 映射主要组件及其职责
- 追踪关键数据流
创建ARCHITECTURE.md
- 编写系统概述（1-2段落）
- 添加C4上下文图表显示系统边界
- 文档入口点表格
- 列出关键抽象
- 添加测试概述
- 链接到详细文档（即使最初为空，也创建docs/部分）
为主要组件创建详细文档
- 每个逻辑组件一个文件在docs/
- 文件名与组件名称匹配（灵活的约定）
- 包含组件级图表

查看references/document-templates.md以获取完整模板。

ARCHITECTURE.md节

必需节

节	内容
概览	关于系统目的的1-2段落
系统图表	C4上下文或容器图表
入口点	带有描述的主要文件表格
关键抽象	重要类/接口/函数的表格
测试	测试策略和关键测试位置的概述
详细文档	链接到`docs/*.md`文件

可选节

节	包含时
数据流	复杂的管道或转换
代码组织	非显而易见的目录结构
配置	重要的配置或环境设置

详细文档（`docs/*.md`）

当组件：

有3+关键文件或抽象
包含复杂的内部逻辑
与多个其他组件交互
需要序列图来解释流程

命名约定

灵活的。与组件的身份匹配：

docs/auth.md用于认证组件
docs/data-pipeline.md用于数据管道
docs/cli.md用于CLI处理

必需内容

节	内容
目的	这个组件做什么
关键文件	重要文件的表格
关键抽象	类、接口、函数

可选内容

节	包含时
架构图表	多个内部子组件
序列图	多步骤交互
依赖	非显而易见的依赖
测试	组件特定的测试模式
配置	组件特定的配置

图表选择

图表类型	用途
C4上下文	`ARCHITECTURE.md` - 系统边界和外部参与者
C4容器	`ARCHITECTURE.md` - 可部署单元（服务、数据库）
C4组件	`docs/*.md` - 组件的内部结构
流程图	控制流、管道、决策逻辑
序列	请求流、API交互、多步骤流程
ER图表	数据模型、实体关系
类图表	对象层次结构、接口实现

从最小（3-5个节点）开始。只有在提高清晰度时才添加细节。

查看references/mermaid-patterns.md以获取图表模板。

入口点和抽象

入口点表格

记录作为理解代码库起点的文件：

| 文件 | 描述 |
|------|-------------|
| `src/main.py` | 应用程序入口点 |
| `src/core/engine.py` | 核心处理引擎 |
| `tests/conftest.py` | 测试装置和设置 |

包括：

应用程序入口点（main, CLI, 处理器）
核心领域逻辑位置
配置文件
测试设置和装置

关键抽象表格

记录重要的类、接口和函数：

| 抽象 | 位置 | 目的 |
|-------------|----------|---------|
| `Engine` | `src/core/engine.py` | 协调处理 |
| `Handler` | `src/api/base.py` | 请求处理接口 |

关注：

基类和接口
核心领域对象
公共API表面
扩展点

维护文档

更新时机

触发器	动作
新增组件	创建`docs/<组件>.md`，添加链接到`ARCHITECTURE.md`
入口点更改	更新入口点表格
重大重构	更新受影响的图表和文件引用
新外部依赖	更新C4上下文图表
组件移除	移除或归档相应的详细文档

更新清单

结构更改后：

验证入口点表格是否准确
检查图表节点是否与实际组件匹配
确认表格中的文件路径是否有效
更新任何受影响的详细文档