name: confluence-docs description: 用于 ADRs、运行手册和架构文档的文档模板。在创建架构决策记录、操作运行手册或技术文档时使用。
Confluence 文档技能
目的
提供用于创建技术文档的标准化模板。这些模板确保项目内一致、高质量的文档。
适用场景
- 创建架构决策记录 (ADRs)
- 编写操作运行手册
- 记录系统架构
- 创建技术规范
- 编写知识转移 (KT) 文档
现有 ADRs (参考)
| ADR | 位置 | 主题 |
|---|---|---|
| ADR-002 | docs/adr/ADR-002-constants-unification.md |
常量组织 |
| ADR-003 | docs/adr/ADR-003-dependency-upgrade-typescript-fixes.md |
依赖升级 |
| ADR-004 | docs/adr/ADR-004-server-component-data-access-pattern.md |
服务器组件模式 |
| ADR-005 | docs/adr/ADR-005-ci-infrastructure-services.md |
CI 基础设施 |
| ADR-006 | docs/adr/ADR-006-bonus-pdf-private-bucket-security.md |
安全模式 |
| ADR-007 | docs/adr/ADR-007-rendertrust-marketing-pages.md |
营销架构 |
ADR 模板 (架构决策记录)
# ADR-XXX: [标题]
## 状态
[提议 | 接受 | 弃用 | 被替代]
## 上下文
我们看到的驱动这个决策的问题是什么？
## 决策
我们提议和/或正在做的改变是什么？
## 后果
### 正面
- [好处 1]
- [好处 2]
### 负面
- [权衡 1]
- [权衡 2]
### 中性
- [观察]
## 实现说明
这个决策应该如何实现？
## 相关决策
- ADR-XXX: [相关决策]
## 参考
- [相关文档链接]
运行手册模板
# 运行手册: [操作名称]
## 概述
简要描述这个运行手册涵盖的内容。
## 先决条件
- [ ] 访问 [系统]
- [ ] 所需权限
- [ ] 安装的工具
## 过程
### 步骤 1: [操作名称]
\`\`\`bash
# 要执行的命令
\`\`\`
**预期输出**: 描述你应该看到的内容
**如果错误**: 如果出现问题该怎么做
### 步骤 2: [操作名称]
...
## 验证
如何验证操作是否成功。
## 回滚
如果需要撤销操作的步骤。
## 故障排除
### 问题: [常见问题]
**症状**: 你看到什么
**原因**: 为什么发生
**解决方案**: 如何修复
## 联系人
- 主要: [姓名/角色]
- 升级: [姓名/角色]
## 修订历史
| 日期 | 作者 | 更改 |
| ---------- | ------ | --------------- |
| YYYY-MM-DD | 姓名 | 初始版本 |
架构文档模板
# [系统/组件] 架构
## 概述
系统/组件的高级描述。
## 目标与非目标
### 目标
- [这个系统应该做什么]
### 非目标
- [这个系统不应该做什么]
## 架构图
\`\`\`
[ASCII 图或图链接]
\`\`\`
## 组件
### 组件 1: [名称]
- **目的**: 做什么
- **位置**: 在哪里
- **依赖**: 需要什么
### 组件 2: [名称]
...
## 数据流
数据如何在系统中移动。
## 安全考虑
- 认证
- 授权 (RLS)
- 数据保护
## 性能考虑
- 缓存策略
- 数据库优化
- API 响应时间
## 监控与可观测性
- 关键指标
- 告警阈值
- 日志位置
## 未来考虑
可能改变或改进的地方。
## 参考
- 相关 ADRs
- 外部文档
知识转移 (KT) 文档模板
# KT: [主题名称] - {{TICKET_PREFIX}}-XXX
## 摘要
做了什么以及为什么重要。
## 上下文
理解这项工作所需的背景信息。
## 关键决策
1. [决策 1]: [推理]
2. [决策 2]: [推理]
## 实现细节
### 改变了什么
- 文件: `path/to/file.ts`
- 更改描述
### 如何工作
实现的解释。
## 陷阱与经验教训
可能让未来开发者困惑的地方。
## 测试
如何验证一切正常工作。
## 相关工单
- {{TICKET_PREFIX}}-XXX: [相关工作]
## 未来工作
下一步应该做什么。
文档输出位置
| 文档类型 | 位置 | 命名 |
|---|---|---|
| ADRs | docs/adr/ |
ADR-XXX-{描述}.md |
| 运行手册 | docs/runbooks/ |
{操作}-runbook.md |
| 架构文档 | docs/architecture/ |
{系统}-architecture.md |
| KT 文档 | docs/ |
KT-{{TICKET_PREFIX}}-XXX-{主题}.md |
| 技术文档 | docs/agent-outputs/technical-docs/ |
{{TICKET_PREFIX}}-XXX-{描述}.md |
文档清单
在发布任何文档之前：
- [ ] 清晰、描述性的标题
- [ ] 正确的标题层次 (H1 > H2 > H3)
- [ ] 带语言标签的代码块
- [ ] 相关文档链接
- [ ] 包括作者和日期
- [ ] 无敏感数据 (秘密、密码)
- [ ] 拼写检查
- [ ] Markdown 语法检查通过