文档与 ADR
Archyl 提供强大的文档功能，让您可以在架构图旁边创建丰富的关联文档。保持您的架构知识有组织且相互关联。
创建文档
手动创建文档
手动创建文档：
- 前往项目中的 文档 选项卡
- 点击 新建文档
- 输入标题并用 Markdown 编写内容
- 添加标签以便组织
- 点击 保存
文档支持完整的 Markdown 语法，包括：
- 标题和格式
- 带语法高亮的代码块
- 表格和列表
- 图片和链接
从 Git 导入
您可以从 Git 仓库导入现有文档：
- 前往 项目设置 > 文档发现
- 配置仓库连接
- 点击 发现文档
- 审查并批准发现的文档
这非常适合导入现有的 README 文件、技术规范或 Wiki 内容。
关联到架构元素
文档与架构关联后变得更强大：
创建关联
- 打开文档页面
- 点击 关联到元素
- 搜索或浏览架构元素
- 选择要关联的元素
- 点击 完成
查看关联的文档
在图表中查看元素时，关联的文档会出现在详情面板中。这提供了即时上下文，无需离开图表视图。
关联的使用场景
- 将 API 文档关联到服务容器
- 将安装指南关联到基础设施组件
- 将设计规范关联到系统上下文
- 将代码注释关联到代码元素
架构决策记录（ADR）
ADR 记录重要的架构决策及其上下文和影响。
什么是 ADR？
架构决策记录包含：
| 字段 | 描述 |
|---|---|
| 标题 | 决策的内容 |
| 状态 | 提议、已接受、已弃用或已替代 |
| 上下文 | 为什么需要这个决策 |
| 决策 | 决定了什么 |
| 影响 | 决策的影响 |
创建 ADR
- 前往项目中的 决策 选项卡
- 点击 新建 ADR
- 填写 ADR 字段
- 关联到相关的架构元素
- 点击 保存
ADR 工作流
ADR 遵循生命周期：
- 提议：初稿，讨论中
- 已接受：决策已做出并获批准
- 已弃用：不再相关，但保留历史记录
- 已替代：被更新的决策替代
ADR 发现
与文档类似，ADR 可以从仓库中发现：
- 前往 项目设置 > ADR 发现
- 配置 ADR 的路径（如
docs/adr/） - 点击 发现 ADR
- 审查并批准发现的记录
最佳实践
保持文档更新
- 架构变更时更新文档
- 在冲刺回顾中审查文档
- 对重要决策使用 ADR
关联一切
- 每个系统都应有描述文档
- 将 ADR 关联到受影响的组件
- 交叉引用相关文档
有效使用标签
- 按领域标记（认证、支付等）
- 按类型标记（API、指南、规范）
- 按状态标记（草稿、审查、最终）
ADR 指南
- 为重要决策创建 ADR
- 包含考虑过的替代方案
- 记录权衡取舍
- 尽可能关联到实现的 PR
文档发现设置
配置文档发现方式：
路径模式
指定要扫描的路径：
docs/
wiki/
README.md
*.md
排除模式
跳过某些文件：
node_modules/
vendor/
CHANGELOG.md