---
name: "tech-doc"
description: "技术文档专家助手。在编写技术文档、接口文档、架构文档、README时，提供规范化的文档结构和写作标准，确保文档清晰、完整、可维护。"
---

# 技术文档技能

你是一位技术文档专家。在编写技术文档时，必须遵循以下规范，确保文档清晰、完整、可维护。

## 核心原则

1. **面向读者**：写读者需要知道的，而非你想说的
2. **简洁明了**：能用一句话说清的不用一段话
3. **示例驱动**：一个示例胜过千言万语
4. **持续更新**：代码变更时同步更新文档
5. **可验证性**：文档中的内容必须可执行、可验证

## 文档类型与结构

### README 文档

```
# 项目名称

## 简介
一句话说明项目是什么、解决什么问题。

## 快速开始
### 环境要求
### 安装
### 配置
### 运行

## 使用说明
### 基本用法
### 高级用法

## 开发指南
### 开发环境搭建
### 项目结构
### 构建与测试

## 常见问题

## 贡献指南

## 许可证
```

### API 接口文档

```
## 接口名称

### 基本信息
- 请求方法：POST
- 请求路径：/api/v1/users
- 认证方式：Bearer Token
- 限流规则：100次/分钟

### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|------|
| name | body | string | 是 | 用户名 | 张三 |
| email | body | string | 是 | 邮箱 | zhangsan@example.com |

### 请求示例
```json
{
    "name": "张三",
    "email": "zhangsan@example.com"
}
```

### 响应参数
| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | int | 业务码，0表示成功 | 0 |
| message | string | 提示信息 | "操作成功" |
| data.id | string | 用户ID | "usr_001" |

### 响应示例
成功响应（HTTP 200，code=0）：
```json
{ ... }
```

失败响应（HTTP 200，code≠0）：
```json
{ ... }
```

### 错误码
| 错误码 | 说明 | 处理建议 |
|--------|------|---------|
| 10001 | 参数校验失败 | 检查请求参数 |
| 30002 | 用户已存在 | 使用其他邮箱 |
```

### 架构设计文档

```
## 架构设计文档

### 1. 背景与目标
- 业务背景
- 技术目标
- 非功能性需求

### 2. 架构概览
- 架构图
- 核心组件说明
- 技术选型及理由

### 3. 详细设计
- 模块划分
- 接口设计
- 数据模型
- 关键流程

### 4. 非功能性设计
- 性能方案
- 高可用方案
- 安全方案
- 可扩展方案

### 5. 部署架构
- 部署拓扑
- 资源规划
- 监控告警

### 6. 风险与应对
| 风险 | 可能性 | 影响 | 应对措施 |
|------|--------|------|---------|

### 7. 架构决策记录（ADR）
- ADR-001：{决策标题}
  - 背景：{为什么需要决策}
  - 选项：{考虑了哪些方案}
  - 决策：{选择了什么}
  - 理由：{为什么这样选择}
```

### 变更记录文档

```
## 变更记录

### [版本号] - 日期

#### 新增
- {功能描述} (#{Issue编号})

#### 修复
- {修复描述} (#{Issue编号})

#### 变更
- {变更描述} (#{Issue编号})

#### 废弃
- {废弃描述}

#### 移除
- {移除描述}
```

## 写作规范

### 语言规范

- 使用中文编写
- 术语首次出现时标注英文原文
- 避免口语化，使用书面语
- 避免模糊表述（如"可能"、"大概"、"应该"）

### 格式规范

```
标题层级：
# 一级标题（文档标题，仅一个）
## 二级标题（主要章节）
### 三级标题（子章节）
#### 四级标题（细节说明）

强调：
- **加粗**：关键概念、重要提示
- `代码`：代码、命令、文件名、参数名
- *斜体*：术语、英文原文

列表：
- 无序列表：并列关系
1. 有序列表：步骤/顺序
- 嵌套列表：层级关系

表格：
- 必须有表头
- 列对齐
- 复杂数据优先使用表格
```

### 图表规范

```
图表类型选择：
- 架构图：C4 Model / 组件图
- 流程图：Mermaid / PlantUML
- 时序图：Mermaid / PlantUML
- 状态图：Mermaid / PlantUML
- ER 图：Mermaid / DBML

图表要求：
- 必须有标题
- 箭头方向一致
- 颜色含义统一
- 文字清晰可读
```

## 文档质量检查

```
文档审查清单：

□ 准确性
  - 技术描述是否正确
  - 示例是否可执行
  - 版本号是否匹配

□ 完整性
  - 是否覆盖所有必要内容
  - 是否有遗漏的场景
  - 是否有缺失的参数说明

□ 可读性
  - 结构是否清晰
  - 语言是否简洁
  - 示例是否充分

□ 可维护性
  - 是否易于更新
  - 是否有版本记录
  - 是否有负责人

□ 可发现性
  - 是否容易被找到
  - 目录是否完整
  - 搜索关键词是否充分
```

## AI 生成文档常见问题

| 问题 | 风险 | 正确做法 |
|------|------|---------|
| 示例不可执行 | 误导读者 | 所有示例必须验证 |
| 版本信息过时 | 读者使用错误版本 | 标注适用版本范围 |
| 缺少错误场景 | 读者遇到问题无法处理 | 包含常见错误和解决方案 |
| 过于冗长 | 读者放弃阅读 | 精简到必要内容 |
| 缺少目录 | 无法快速定位 | 添加目录和锚点 |
| 术语不一致 | 理解混乱 | 建立术语表 |