文档标准与规范

Claude Code项目的文档撰写标准、模板和格式规范。

文档原则

核心原则

1. 用户中心: 始终从用户需求出发撰写文档
2. 简洁明了: 用简洁的语言表达复杂的概念
3. 结构化: 使用一致的结构和格式
4. 可操作: 提供具体的使用示例和步骤
5. 持续更新: 保持文档与功能同步更新

质量标准

• 完整性: 涵盖所有主要功能和使用场景
• 准确性: 确保所有信息准确无误
• 一致性: 术语、格式、风格保持一致
• 可读性: 结构清晰，易于理解和导航
• 实用性: 提供实际可用的示例和指导

文档结构标准

通用文档结构

# 文档标题

简要描述文档内容和目标用户。

## 核心功能

- **功能1**: 简要说明
- **功能2**: 简要说明
- **功能3**: 简要说明

## 使用语法

```bash
基本命令语法示例
\```

### 主要选项
- `选项1` - 选项说明
- `选项2` - 选项说明

## 使用示例

### 场景1
```bash
示例命令
\```

### 场景2  
```bash
示例命令
\```

## 高级功能

详细的高级功能说明

## 最佳实践

### 1. 实践要点1
具体说明和示例

### 2. 实践要点2
具体说明和示例

---

*简短的总结语*

代理文档结构

# 代理名称

代理的简要介绍和定位。

## 核心能力

### 能力1
- 具体能力说明
- 应用场景

### 能力2
- 具体能力说明
- 应用场景

## 工作方法

1. **步骤1**: 详细说明
2. **步骤2**: 详细说明
3. **步骤3**: 详细说明

## 使用场景

### 场景名称
```bash
使用示例
\```

## 特色能力

- **特色1**: 说明
- **特色2**: 说明

---

*代理总结语*

命令文档结构

# 命令名称 (/command)

命令的功能描述和使用场景。

## 核心功能

- **功能1**: 功能说明
- **功能2**: 功能说明

## 使用语法

```bash
/command [参数] [选项]
\```

### 参数说明
- `参数1` - 参数说明
- `参数2` - 参数说明

### 主要选项
- `--option1` - 选项说明
- `--option2` - 选项说明

## 执行流程

1. **阶段1**: 流程说明
2. **阶段2**: 流程说明
3. **阶段3**: 流程说明

## 使用示例

### 基础使用
```bash
基础命令示例
\```

### 高级使用
```bash
高级命令示例
\```

## 高级特性

### 特性1
详细说明和示例

### 特性2
详细说明和示例

## 最佳实践

### 1. 实践建议1
具体说明

### 2. 实践建议2
具体说明

---

*命令总结语*

格式规范

标题规范

• 一级标题: # 标题 - 用于文档主标题
• 二级标题: ## 标题 - 用于主要章节，带emoji
• 三级标题: ### 标题 - 用于子章节
• 四级标题: #### 标题 - 用于详细分类

Emoji使用规范

用途	Emoji	说明
核心功能		表示主要功能和目标
使用方法		表示语法和快速使用
执行流程		表示工作流程和步骤
示例演示		表示使用示例和场景
高级功能		表示高级特性和配置
最佳实践		表示建议和规范
工具集成		表示工具和集成
性能指标		表示数据和统计
安全特性		表示安全和保护
特色能力		表示独特功能

代码块规范

```bash
# 命令行示例
command --option value
```

```javascript
// 代码示例
function example() {
  return "示例代码";
}
```

```yaml
# 配置示例
key: value
nested:
  key: value
```

表格规范

| 列标题1 | 列标题2 | 列标题3 |
|---------|---------|---------|
| 数据1   | 数据2   | 数据3   |
| 数据4   | 数据5   | 数据6   |

列表规范

### 无序列表
- **重点项目**: 说明内容
- **普通项目**: 说明内容
  - 子项目1
  - 子项目2

### 有序列表
1. **第一步**: 详细说明
2. **第二步**: 详细说明
3. **第三步**: 详细说明

引用和提示

>  **提示**: 重要的使用提示信息

>  **注意**: 需要特别注意的事项

>  **警告**: 可能导致问题的操作提醒

撰写指南

语言风格

• 简洁明了: 使用简短、清晰的句子
• 技术准确: 确保技术术语使用正确
• 用户友好: 避免过于专业的术语，或提供解释
• 一致性: 保持术语和表达方式的一致性

术语标准

中文术语	英文术语	使用场景
代理	Agent	AI代理系统
命令	Command	斜杠命令系统
工作流	Workflow	流程和步骤
任务编排	Task Orchestration	多任务协调
上下文	Context	项目环境信息
激活	Activation	代理和服务启动
集成	Integration	工具和服务连接

示例编写规范

• 完整性: 示例应该是完整可执行的
• 实用性: 使用真实的使用场景
• 多样性: 提供基础和高级的不同示例
• 注释: 为复杂示例添加必要的注释说明

质量检查清单

内容检查

• [ ] 标题结构完整且层次清晰
• [ ] 核心功能描述准确完整
• [ ] 使用示例真实可用
• [ ] 术语使用规范一致
• [ ] 链接引用正确有效

格式检查

• [ ] Emoji使用符合规范
• [ ] 代码块格式正确
• [ ] 表格对齐整齐
• [ ] 列表结构清晰
• [ ] 引用格式标准

用户体验检查

• [ ] 文档结构易于导航
• [ ] 内容组织逻辑合理
• [ ] 关键信息突出显示
• [ ] 提供足够的使用指导
• [ ] 包含必要的注意事项

文档维护

更新频率

• 功能更新: 随功能发布同步更新
• 修复更新: 发现问题立即修复
• 定期审查: 每月检查文档准确性
• 用户反馈: 根据反馈及时调整

版本管理

• 使用Git追踪文档变更
• 重要更新记录变更日志
• 保持文档与代码版本同步
• 标记过时内容并及时更新

协作规范

• 多人协作时保持风格一致
• 重大修改前进行团队讨论
• 使用Pull Request进行文档审查
• 建立文档责任人制度

---

文档标准与规范 - 确保文档质量和一致性