# AI 开发文档通用规范

本规范文档基于 FunRadiusP 项目的 AI 开发文档实践提炼而成，适用于各类软件开发项目的 AI 协作开发流程。

---

## 一、核心要素

### 1.1 文档结构体系

AI 开发文档应采用分层结构，包含以下核心组成部分：

- **索引文档**：项目概述、文档目录、重要路径、读取建议
- **核心文档**：项目概述、架构设计、快速开始（高优先级）
- **更新日志**：变更历史记录（最高优先级）
- **模块文档**：各功能模块的详细说明（中优先级）
- **配置文档**：各类配置的说明（低优先级）
- **最佳实践**：开发、部署、性能等方面的实践指南（参考级）

### 1.2 优先级机制

文档应设置明确的优先级体系，帮助 AI 快速定位关键信息：

- 优先级 0：更新日志（最新变更记录）
- 优先级 1-3：核心文档（项目基础信息）
- 优先级 4-12：模块文档（功能模块详情）
- 优先级 13-16：配置文档（配置说明）
- 优先级 17-20：最佳实践（参考指南）

### 1.3 项目约束规范

文档开头应明确项目的核心约束条件，确保 AI 遵循：

- 项目类型和技术栈限制
- 禁止的技术或架构模式
- 必须遵守的原则和规范
- 任务完成后的清理和文档更新要求

---

## 二、标准格式

### 2.1 索引文档格式

```markdown
# [项目名] AI 上下文文档索引

## 重要说明

[项目核心约束和原则]

### 必须遵守的原则

1. [原则 1]
   - [详细说明]
2. [原则 2]
   - [详细说明]

---

## 项目类型

[项目类型描述]

## 文档结构

[文档分类和优先级说明]

### [文档分类 1]

| 文档路径 | 优先级 | 内容描述 |
| -------- | ------ | -------- |
| [路径]   | [数字] | [描述]   |

### [文档分类 2]

...

## 读取建议

1. [建议 1]
2. [建议 2]

## 文档更新

- [更新规则 1]
- [更新规则 2]

## 项目根目录

[根目录信息]

## 重要文件路径

| 文件路径 | 功能描述 |
| -------- | -------- |
| [路径]   | [描述]   |
```

### 2.2 更新日志格式

```markdown
# 更新日志

本文件记录 [项目名] 项目的所有重要变更。

---

## [YYYY-MM-DD]

### 主要变更

- [变更标题]
  - [详细说明 1]
  - [详细说明 2]

### 新增文件

[文件类型]：[文件路径]

### 修改文件

[文件类型]：[文件路径]

---

## 变更类型说明

- [类型 1]：[说明]
- [类型 2]：[说明]
```

### 2.3 Markdown 规范

- 使用标准 Markdown 语法
- 表格用于结构化数据展示
- 代码块用于代码展示
- 层级标题（#、##、###）用于文档结构
- 列表（-、1.）用于项目列举
- 分隔线（---）用于内容分隔

---

## 三、关键规范要点

### 3.1 文档管理规范

1. **每次任务完成后必须更新变更日志**
2. **项目结构变更时更新索引文档和核心文档**
3. **功能模块变更时更新对应模块文档**
4. **配置变更时更新配置文档**
5. **定期检查文档的完整性和准确性**

### 3.2 内容编写规范

1. **简洁明了**：避免冗余描述，突出关键信息，不得使用emoji
2. **结构清晰**：使用层级标题组织内容
3. **重点突出**：使用表格、列表等形式展示关键数据
4. **保持一致**：统一使用相同的术语和格式
5. **及时更新**：确保文档与代码同步变更

### 3.3 变更记录规范

1. **按日期排序**：最新变更在前
2. **合并同日变更**：同一日期的变更合并记录
3. **分类记录**：区分主要变更、新增文件、修改文件
4. **详细描述**：变更说明应包含做了什么、为什么做、如何做的
5. **避免重复**：不要记录琐碎或无意义的变更

### 3.4 协作开发规范

1. **先读文档再开发**：AI 应先阅读索引文档和更新日志
2. **遵循优先级**：按优先级顺序读取相关文档
3. **遵守项目约束**：严格遵循文档中规定的原则和限制
4. **完成任务后清理**：检查并删除冗余文件、模块、包体、目录
5. **及时更新文档**：完成开发后更新相应的文档

---

## 四、实施建议

### 4.1 文档初始化

1. 创建文档目录结构
2. 编写索引文档
3. 编写核心文档（项目概述、架构设计、快速开始）
4. 创建更新日志文件
5. 根据项目规模逐步补充模块文档和配置文档

### 4.2 日常维护

1. 每次开发任务完成后更新变更日志
2. 定期审查文档的完整性
3. 根据项目演进更新相关文档
4. 保持文档格式的一致性

### 4.3 优化改进

1. 收集 AI 协作中的问题和反馈
2. 持续优化文档结构和内容
3. 补充最佳实践和经验教训
4. 定期评估文档的有效性

---

## 五、总结

本通用规范提供了 AI 开发文档的完整框架和标准，包括：

- **核心要素**：文档结构、优先级机制、约束规范
- **标准格式**：索引文档、更新日志、Markdown 规范
- **关键要点**：文档管理、内容编写、变更记录、协作开发

通过遵循本规范，可以建立高效、规范的 AI 协作开发文档体系，提高开发效率和项目质量。