---
source: ../../../core/documentation-writing-standards.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-03-17
status: current
---

# 文件撰写规范

> [English](../../../core/documentation-writing-standards.md) | **繁体中文**

**版本**: 1.2.0
**最后更新**: 2026-03-17
**适用范围**: 所有软体专案（新建、重构、迁移、维护）

---

## 目的

本标准根据专案类型定义文件需求，并提供各类文件的详细撰写指南。

**与其他标准的关系**:
- 补充 [documentation-structure.md](documentation-structure.md) 所定义的档案组织
- 本标准聚焦于**内容需求**和**专案类型对照**

---

## 专案类型与文件对照

### 文件需求矩阵

| 文件 | 新建专案 | 重构 | 迁移 | 维护 | 说明 |
|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 专案入口 |
| **ARCHITECTURE.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 系统架构 |
| **API.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | API 规格 |
| **DATABASE.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 资料库架构 |
| **DEPLOYMENT.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 部署指南 |
| **MIGRATION.md** | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 | 迁移计划 |
| **ADR/** | ⚪ 建议 | ✅ 必要 | ✅ 必要 | ⚪ 如适用 | 架构决策 |
| **CHANGELOG.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 版本历史 |
| **CONTRIBUTING.md** | ⚪ 建议 | ⚪ 建议 | ⚪ 建议 | ⚪ 如适用 | 贡献指南 |

**图例**: ✅ 必要 | ⚪ 建议/如适用 | ❌ 不需要

---

### 专案类型说明

#### 🆕 新建专案

从零开始建立的软体专案。

**必要文件**:
- README.md - 专案概述、快速开始
- ARCHITECTURE.md - 设计架构（开发前规划）
- DEPLOYMENT.md - 部署流程
- CHANGELOG.md - 版本历史

**建议文件**:
- API.md - 如对外提供 API
- DATABASE.md - 如使用资料库
- ADR/ - 记录重要技术决策

---

#### 🔄 重构专案

改善既有系统的程序码结构、架构或技术栈，但不改变外部行为。

**必要文件**:
- README.md - 更新技术栈说明
- ARCHITECTURE.md - 新旧架构对比
- API.md - API 变更说明（如适用）
- DATABASE.md - Schema 变更说明（如适用）
- DEPLOYMENT.md - 新部署流程
- MIGRATION.md - 重构迁移计划
- ADR/ - 记录重构决策
- CHANGELOG.md - 详细变更记录

**重点**:
- MIGRATION.md 需包含回滚计划
- ADR/ 需记录「为何重构」及「为何选择此方案」

---

#### 🚚 迁移专案

将系统从一个环境/平台迁移到另一个（如云端迁移、版本升级）。

**必要文件**:
- README.md - 新环境说明
- ARCHITECTURE.md - 新架构图
- API.md - API 相容性说明
- DATABASE.md - 资料迁移说明
- DEPLOYMENT.md - 新环境部署
- MIGRATION.md - 迁移步骤与验证
- ADR/ - 迁移决策记录
- CHANGELOG.md - 迁移变更记录

**重点**:
- MIGRATION.md 是核心文件
- 需包含资料迁移验证、回滚计划、集成方通知

---

#### 🔧 维护专案

既有系统的日常维护、Bug 修复、小幅功能增强。

**必要文件**:
- README.md - 保持更新
- CHANGELOG.md - 记录每次变更

**建议文件**:
- 依变更范围更新其他文件

---

## 核心原则

> **文件是程序码的延伸，应与程序码同等重视。好的文件能减少沟通成本、加速新人上手、降低维护风险。**

### 文件金字塔

```
                    ┌─────────────┐
                    │   README    │  ← 入口点，快速概览
                    ├─────────────┤
                 ┌──┴─────────────┴──┐
                 │   ARCHITECTURE    │  ← 系统总览
                 ├───────────────────┤
              ┌──┴───────────────────┴──┐
              │  API / DATABASE / DEPLOY │  ← 技术细节
              ├─────────────────────────┤
           ┌──┴─────────────────────────┴──┐
           │    ADR / MIGRATION / CHANGELOG │  ← 变更历史
           └───────────────────────────────┘
```

---

## 文件分类与规范

### 1. 架构文件

#### ARCHITECTURE.md

**用途**: 描述系统整体架构、模组划分、技术选型

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| 系统概述 | 目的、范围、主要功能 | 必要 |
| 架构图 | 使用 Mermaid 或 ASCII Art | 必要 |
| 模组说明 | 职责、依赖关系 | 必要 |
| 技术栈 | 框架、语言、资料库版本 | 必要 |
| 资料流程 | 主要业务流程的资料流向 | 必要 |
| 部署架构 | 生产环境部署拓扑 | 建议 |
| 设计决策 | 关键决策的理由（或连结至 ADR） | 建议 |

**范本结构**:

```markdown
# 系统架构

## 1. 系统概述
[系统目的与范围]

## 2. 架构图
[Mermaid 或 ASCII 图]

## 3. 模组说明
### 3.1 表现层
### 3.2 业务逻辑层
### 3.3 资料存取层

## 4. 技术栈
| 类别 | 技术 | 版本 |
|----------|------------|---------|

## 5. 资料流程
[主要业务流程图]

## 6. 部署架构
[部署拓扑图]
```

---

### 2. API 文件

#### API.md

**用途**: 记录对外 API 界面

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| API 概述 | 版本、Base URL、认证方式 | 必要 |
| 认证方式 | Token 取得、过期时间 | 必要 |
| 端点列表 | 所有 API 端点 | 必要 |
| 端点规格 | 每个端点的请求/回应格式 | 必要 |
| 错误码参考 | 错误码与说明 | 必要 |
| 程序码范例 | 常见语言的范例 | 建议 |
| 速率限制 | API 呼叫频率限制 | 如适用 |

**端点规格格式**:

```markdown
### POST /api/v1/resource

描述此端点的功能。

**请求**

| 栏位 | 类型 | 必要 | 说明 |
|-------|------|----------|-------------|
| field1 | string | 是 | 说明 |
| field2 | integer | 否 | 说明 |

**请求范例**
```json
{
  "field1": "value",
  "field2": 123
}
```

**回应**

| 栏位 | 类型 | 说明 |
|-------|------|-------------|
| success | boolean | 是否成功 |
| data | object | 回应资料 |

**回应范例**
```json
{
  "success": true,
  "data": {}
}
```

**错误回应**
| 代码 | 说明 |
|------|-------------|
| 400 | 请求错误 |
| 401 | 未授权 |
```

---

### 3. 资料库文件

#### DATABASE.md

**用途**: 记录资料库结构、关联、索引策略

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| 资料库概述 | 类型、版本、连线资讯 | 必要 |
| ER 图 | 实体关联图 | 必要 |
| 资料表列表 | 所有资料表及用途 | 必要 |
| 资料表规格 | 每个资料表的栏位定义 | 必要 |
| 索引说明 | 索引策略与效能考量 | 必要 |
| 迁移脚本 | 脚本位置与执行顺序 | 必要 |
| 备份策略 | 备份频率、保留期限 | 建议 |

**资料表规格格式**:

```markdown
### 资料表名称

资料表用途说明。

**栏位定义**

| 栏位 | 资料类型 | 可空 | 预设值 | 说明 |
|--------|-----------|----------|---------|-------------|
| id | bigint | 否 | IDENTITY | 主键 |
| name | varchar(100) | 否 | - | 名称栏位 |
| status | tinyint | 否 | 0 | 状态旗标 |

**索引**

| 索引名称 | 栏位 | 类型 | 说明 |
|------------|---------|------|-------------|
| PK_TableName | id | CLUSTERED | 主键 |
| IX_Status | status, created_at | NONCLUSTERED | 查询最佳化 |

**关联**

| 关联资料表 | 连结栏位 | 关系 |
|---------------|--------------|--------------|
| OtherTable | id = other_id | 1:N |
```

---

### 4. 部署文件

#### DEPLOYMENT.md

**用途**: 记录部署步骤、环境配置、故障排除

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| 环境需求 | 硬体、软体、网路需求 | 必要 |
| 安装步骤 | 详细安装流程 | 必要 |
| 配置说明 | 配置档参数说明 | 必要 |
| 验证方式 | 如何确认部署成功 | 必要 |
| 故障排除 | 常见问题与解法 | 必要 |
| 监控设定 | 健康检查、日志位置 | 建议 |
| 扩展指南 | 如何水平/垂直扩展 | 如适用 |

**配置档说明格式**:

```markdown
### config.yaml 设定

| 参数 | 预设值 | 说明 | 范例 |
|-----------|---------|-------------|---------|
| db.host | localhost | 资料库主机 | `192.168.1.100` |
| db.port | 5432 | 资料库连接埠 | - |
| app.timeout | 300 | 请求逾时（秒） | - |
```

---

### 5. 迁移文件

#### MIGRATION.md

**用途**: 记录迁移计划、向后相容策略、回滚程序

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| 迁移概述 | 目标、范围、时程 | 必要 |
| 前置准备 | 迁移前需完成的准备 | 必要 |
| 迁移步骤 | 详细迁移流程 | 必要 |
| 验证清单 | 迁移后验证项目 | 必要 |
| 回滚计划 | 失败时的回滚步骤 | 必要 |
| 向后相容 | API/资料库相容性说明 | 必要 |
| 集成方通知 | 需通知的外部系统 | 如适用 |

---

### 6. 架构决策记录 (ADR)

#### docs/ADR/NNN-title.md

**用途**: 记录重要的架构决策及其理由

**档案命名**: `NNN-kebab-case-title.md`（例如：`001-use-postgresql.md`）

**必要章节**:

| 章节 | 说明 | 必要性 |
|---------|-------------|----------|
| 标题 | 决策名称 | 必要 |
| 状态 | proposed/accepted/deprecated/superseded | 必要 |
| 背景 | 为何需要此决策 | 必要 |
| 决策 | 具体决策内容 | 必要 |
| 后果 | 决策的影响（正面/负面） | 必要 |
| 替代方案 | 考虑过的其他选项 | 建议 |

**范本**:

```markdown
# ADR-001: [决策标题]

## 状态
已接受

## 背景
[为何需要此决策...]

## 决策
[具体决策...]

## 后果

### 正面影响
- 好处 1
- 好处 2

### 负面影响
- 缺点 1
- 缺点 2

## 替代方案
1. 方案 A - 因...而拒绝
2. 方案 B - 因...而拒绝
```

---

## 品质标准

### 格式要求

| 项目 | 标准 |
|------|----------|
| 语言 | 繁体中文 |
| 编码 | UTF-8 |
| 行长度 | 建议 ≤ 120 字元 |
| 图表 | 优先使用 Mermaid，次之 ASCII Art |
| 连结 | 内部连结使用相对路径 |

### 维护要求

| 项目 | 标准 |
|------|----------|
| 同步更新 | 程序码变更时同步更新文件 |
| 版本标记 | 文件顶部标记版本与更新日期 |
| 审查纳入 | 程序码审查需包含文件变更 |
| 定期检视 | 每季检视文件是否过时 |

### 审查清单

提交文件前：

- [ ] 必要章节完整
- [ ] 无过时或错误资讯
- [ ] 所有连结有效
- [ ] 范例可执行/正确
- [ ] 格式符合标准

---

## 文件位置规范

```
project-root/
├── README.md                    # 专案入口文件
├── CONTRIBUTING.md              # 贡献指南
├── CHANGELOG.md                 # 变更日志
├── .standards/ or .claude/      # 开发标准
│   ├── documentation-writing-standards.md
│   └── ...
└── docs/                        # 文件目录
    ├── INDEX.md                 # 文件索引
    ├── ARCHITECTURE.md          # 架构文件
    ├── API.md                   # API 文件
    ├── DATABASE.md              # 资料库文件
    ├── DEPLOYMENT.md            # 部署文件
    ├── MIGRATION.md             # 迁移文件
    ├── ADR/                     # 架构决策记录
    │   ├── 001-xxx.md
    │   └── ...
    └── DB/                      # 资料库脚本
```

---

## 工具建议

| 用途 | 工具 |
|---------|-------|
| Markdown 编辑 | VS Code + Markdown Preview Enhanced |
| 图表绘制 | Mermaid / draw.io / PlantUML |
| API 文档 | OpenAPI (Swagger) / Redoc |
| ER 图 | dbdiagram.io / DBeaver |

---

## AI 协作文档

### Token 感知设计

为 AI 助手优化文档结构：

**原则**:

| 原则 | 说明 |
|------|------|
| **前置重要信息** | 关键信息放在文档开头 |
| **结构化数据** | 使用表格、列表、代码块 |
| **明确标记** | 使用清晰的章节标题 |
| **避免冗余** | 减少重复内容 |

**AI 友好文档模式**:

```markdown
---
# YAML 前置元数据（AI 可解析）
title: API 端点文档
version: 2.0.0
last_updated: 2026-01-24
ai_summary: 用户认证 API，支持 OAuth2
---

<!-- AI-SECTION-START: quick-reference -->
## 快速参考
[最常用的信息放这里]
<!-- AI-SECTION-END: quick-reference -->

<!-- AI-SECTION-START: details -->
## 详细说明
[完整详情放这里]
<!-- AI-SECTION-END: details -->
```

### 为 AI 代码生成撰写

撰写 AI 可用于生成代码的文档：

**范例 - 好的 AI 提示友好文档**:

```markdown
## 创建用户 API

### 约束条件
- 用户名：3-20 字符，仅字母数字
- 邮箱：必须唯一
- 密码：最少 8 字符，需含数字

### 成功响应
返回 HTTP 201 和用户对象（不含密码）

### 错误情况
- 409: 邮箱已存在
- 400: 验证失败
```

**AI 提示友好特点**:

| 特点 | 好处 |
|------|------|
| 明确约束条件 | AI 可生成验证代码 |
| 列出错误情况 | AI 可生成错误处理 |
| 结构化格式 | AI 易于解析 |

---

## API 文档标准

### OpenAPI 3.1 规范

```yaml
openapi: 3.1.0
info:
  title: 示例 API
  version: 1.0.0
  description: |
    ## 概述
    此 API 提供用户管理功能。

    ## 认证
    使用 Bearer Token 认证。

paths:
  /users:
    post:
      summary: 创建用户
      operationId: createUser
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
```

### AsyncAPI 2.6 规范（异步 API）

```yaml
asyncapi: 2.6.0
info:
  title: 事件 API
  version: 1.0.0

channels:
  user/created:
    publish:
      summary: 用户创建事件
      message:
        payload:
          type: object
          properties:
            userId:
              type: string
            createdAt:
              type: string
              format: date-time
```

---

## 文档可及性

确保文档对所有用户都可访问，在适用的情况下遵循 WCAG 2.1 Level A 指南。

| 需求 | 描述 | 示例 |
|------|------|------|
| **浅显语言** | 使用清晰、简单的语言；目标为 8 年级阅读程度 | 避免：「utilize」→ 使用：「use」 |
| **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `![显示三层架构的架构图](arch.png)` |
| **标题层级** | 使用正确的标题层级（h1→h2→h3），不跳级 | 不要从 `#` 直接跳到 `###` |
| **链接文字** | 使用描述性链接文字，而非「点此」 | 避免：[点此] → 使用：[安装指南] |
| **代码区块** | 使用带语言标示的围栏式代码区块 | ` ```javascript ` 而非 ` ``` ` |
| **色彩独立性** | 不仅依赖色彩传达意义 | 搭配使用 ✅/❌ 图标与色彩 |

---

## 相关标准

- [Documentation Structure Standard](documentation-structure.md) - 文件结构标准
- [Changelog Standards](changelog-standards.md) - 变更日志标准

---

## 版本历史

| 版本 | 日期 | 变更内容 |
|---------|------|---------|
| 1.1.0 | 2026-01-24 | 新增：AI 协作文档章节、API 文档标准（OpenAPI 3.1、AsyncAPI 2.6） |
| 1.0.1 | 2025-12-24 | 新增：相关标准章节 |
| 1.0.0 | 2025-12-10 | 初版文档撰写标准 |

---

## 参考资料

- [OpenAPI 3.1 规范](https://spec.openapis.org/oas/v3.1.0) - RESTful API 描述标准
- [AsyncAPI 2.6 规范](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 异步 API 描述标准
- [JSON Schema](https://json-schema.org/) - 数据验证标准
- [Diátaxis 文档框架](https://diataxis.fr/) - 技术文档组织方法

---

## 授权

本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
