458 lines
12 KiB
Markdown
458 lines
12 KiB
Markdown
# ETF轮动项目文档创建规范
|
||
|
||
> 规范版本：v2.0
|
||
> 制定日期：2026-06-21
|
||
> 核心原则：**实证类文档必须记录Git版本，确保结果可复现**
|
||
|
||
---
|
||
|
||
## 1. 核心原则：Git可复现性
|
||
|
||
### 1.1 为什么必须记录Git版本？
|
||
|
||
量化策略研究的特点是**代码与结果紧密耦合**：
|
||
- 同一份代码，不同参数可能产生截然不同的结果
|
||
- 代码迭代后，历史实验结果可能无法复现
|
||
- 没有版本记录，文档的结论很快就会变成"孤证"
|
||
|
||
**核心要求**：凡涉及代码运行、数据分析、回测实验的文档，必须在生成时记录完整的Git版本信息。
|
||
|
||
### 1.2 什么是"实证类文档"？
|
||
|
||
| 类型 | 是否需要Git版本 | 说明 |
|
||
|------|----------------|------|
|
||
| 实验记录 | ✅ 必须 | 每次实验都是特定代码版本的输出 |
|
||
| 分析报告 | ✅ 必须 | 分析结果依赖特定配置和代码 |
|
||
| 阶段总结 | ✅ 必须 | 快照性质，必须锁定版本 |
|
||
| 调研报告 | ⚠️ 有回测则需要 | 纯文献综述无需，有验证实验则需要 |
|
||
| 核心逻辑 | ⚠️ 迭代版本需要 | 描述当前逻辑无需，对比版本则需要 |
|
||
| 技术架构 | ❌ 不需要 | 设计文档，与代码版本无关 |
|
||
| 接口说明 | ❌ 不需要 | API文档，与具体版本无关 |
|
||
|
||
### 1.3 必须记录的版本信息
|
||
|
||
实证类文档头部必须包含以下三项：
|
||
|
||
```markdown
|
||
> **Git Commit**：`abc1234`（完整的commit hash或短hash）
|
||
> **配置文件**：`rotation/config_simple.yaml`
|
||
> **运行命令**：`python rotation/simple_rotation.py`
|
||
```
|
||
|
||
**为什么这三项是必要的？**
|
||
1. **Git Commit**：锁定代码版本，任何人可通过 `git checkout` 回到该版本
|
||
2. **配置文件**：参数配置对结果影响极大，必须明确记录
|
||
3. **运行命令**：完整的执行路径，确保复现时不会遗漏步骤
|
||
|
||
---
|
||
|
||
## 2. 文件命名规范
|
||
|
||
### 2.1 基本格式
|
||
|
||
```
|
||
YYYYMMDD_中文名称.md
|
||
```
|
||
|
||
- **日期来源**：文档首次创建的git提交日期（可通过 `git log --diff-filter=A` 查询）
|
||
- **命名原则**：日期前缀 + 简洁中文描述
|
||
- **分隔符**：使用 `_` 分隔日期和名称，名称内部可用 `-` 连接
|
||
- **禁止字符**：空格（会导致命令行操作困难）
|
||
|
||
### 2.2 特殊场景命名规则
|
||
|
||
| 场景 | 格式 | 示例 |
|
||
|------|------|------|
|
||
| 实验记录 | `YYYYMMDD_编号_名称.md` | `20260617_010_起始年份敏感性分析.md` |
|
||
| 版本迭代 | `YYYYMMDD_名称_vN.md` | `20260519_轮动策略核心逻辑_v3.md` |
|
||
| 阶段总结 | `YYYYMMDD_名称_hash.md` | `20260606_策略快照_ca933e4.md` |
|
||
| 英文内容 | 可保留英文或翻译 | `20260621_greedy与rank对比分析.md` |
|
||
|
||
### 2.3 例外情况（无需日期前缀）
|
||
|
||
- 规范文档：`文档创建规范.md`
|
||
- 目录说明：`README.md`
|
||
- 从其他位置迁移的旧文档：可保留原名称，在元信息中注明迁移信息
|
||
|
||
---
|
||
|
||
## 3. 文档分类详解
|
||
|
||
### 3.1 实验记录类（docs/experiments/）
|
||
|
||
**定位**：A/B对比实验、参数优化、敏感性分析等需要严格复现的研究
|
||
|
||
**头部模板**：
|
||
|
||
```markdown
|
||
# 实验记录 XXX: [实验名称]
|
||
|
||
## 实验信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 实验编号 | XXX |
|
||
| 实验日期 | YYYY-MM-DD |
|
||
| 实验类型 | 参数优化 / 对比实验 / 敏感性分析 / 问题诊断 |
|
||
| 研究问题 | [一句话描述] |
|
||
| Git Commit | `[hash]` |
|
||
| 配置文件 | `[路径]` |
|
||
| 实验脚本 | `[路径]` |
|
||
|
||
## 实验背景
|
||
[问题来源、预期目标]
|
||
|
||
## 实验设计
|
||
[变量定义、对照组设置]
|
||
|
||
## 实验结果
|
||
[数据表格、核心发现]
|
||
|
||
## 结论与后续
|
||
[结论摘要、下一步建议]
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- 实验编号：三位数字，便于排序和引用
|
||
- Git Commit：**必须**
|
||
- 配置文件：**必须**
|
||
- 实验脚本：**必须**
|
||
|
||
**为什么实验记录格式最严格？**
|
||
实验记录是项目的核心资产，每一份都代表一个可复现的"科学实验"。未来可能需要：
|
||
- 回溯历史实验验证当前假设
|
||
- 对比不同时期的实验结果
|
||
- 复现某个关键发现
|
||
|
||
---
|
||
|
||
### 3.2 分析报告类（docs/）
|
||
|
||
**定位**：策略深度分析、回测报告、问题诊断等
|
||
|
||
**头部模板**：
|
||
|
||
```markdown
|
||
# [报告标题]
|
||
|
||
> 分析日期：YYYY-MM-DD
|
||
> Git Commit：`[hash]`（如有代码运行）
|
||
> 配置文件：`[路径]`（如有配置依赖）
|
||
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD
|
||
|
||
---
|
||
|
||
## 1. 分析背景
|
||
...
|
||
|
||
## 2. 分析方法
|
||
...
|
||
|
||
## 3. 核心发现
|
||
...
|
||
|
||
## 4. 结论与建议
|
||
...
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- 分析日期
|
||
- Git Commit：**如果分析依赖代码运行，必须记录**
|
||
- 回测区间：如果有回测数据
|
||
|
||
**分析报告的核心价值**：记录"为什么"和"怎么做"，不只是结论
|
||
|
||
---
|
||
|
||
### 3.3 调研报告类（docs/）
|
||
|
||
**定位**：技术调研、因子调研、文献综述、方法论研究
|
||
|
||
**头部模板**：
|
||
|
||
```markdown
|
||
# [调研标题]
|
||
|
||
> 调研日期：YYYY-MM-DD
|
||
> 调研来源：[文献/社区/实验验证]
|
||
> Git Commit：`[hash]`（如有验证实验）
|
||
> 当前结论：[核心发现摘要]
|
||
|
||
---
|
||
|
||
## 1. 调研背景
|
||
[为什么调研这个主题]
|
||
|
||
## 2. 调研内容
|
||
[方法/理论/实验]
|
||
|
||
## 3. 结论与建议
|
||
[对项目的指导意义]
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- 调研日期
|
||
- 调研来源：说明结论来自哪里（文献、实验、社区等）
|
||
|
||
**两种调研类型**：
|
||
1. **文献调研**：无需Git版本，但需注明文献来源
|
||
2. **验证调研**：如果包含回测验证，必须记录Git版本
|
||
|
||
---
|
||
|
||
### 3.4 阶段性总结类（docs/strategy_summaries/）
|
||
|
||
**定位**：策略阶段快照，锁定特定版本的状态
|
||
|
||
**头部模板**：
|
||
|
||
```markdown
|
||
# ETF轮动策略阶段总结
|
||
|
||
> **生成日期**：YYYY-MM-DD
|
||
> **Git Commit**：`[完整hash]`
|
||
> **复现方式**：
|
||
> ```bash
|
||
> git checkout [hash]
|
||
> python [脚本路径] --config [配置路径]
|
||
> ```
|
||
|
||
---
|
||
|
||
## 1. 策略概述
|
||
[资产池、因子、参数配置]
|
||
|
||
## 2. 当前表现
|
||
[收益、风险、换手率等]
|
||
|
||
## 3. 关键发现
|
||
[本阶段的主要认知]
|
||
|
||
## 4. 下一步计划
|
||
[待解决的问题、优化方向]
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- Git Commit：**必须**（这是快照类文档的本质）
|
||
- 复现方式：**必须**（完整的复现命令）
|
||
|
||
**为什么阶段性总结最强调复现？**
|
||
阶段性总结是项目的里程碑，代表某个时期的"完整状态"。未来可能需要：
|
||
- 对比不同阶段的策略表现
|
||
- 回溯某个阶段的认知
|
||
- 复现某个版本的具体结果
|
||
|
||
---
|
||
|
||
### 3.5 核心逻辑类（docs/）
|
||
|
||
**定位**：策略核心机制说明、版本迭代对比
|
||
|
||
**当前版本模板**（无需Git版本）：
|
||
|
||
```markdown
|
||
# [策略名称]核心逻辑
|
||
|
||
## 策略概览
|
||
[一句话定位]
|
||
|
||
## 核心机制
|
||
[信号生成、仓位分配、调仓逻辑]
|
||
|
||
## 参数说明
|
||
[关键参数及其含义]
|
||
|
||
## 典型场景
|
||
[持仓示例、调仓示例]
|
||
```
|
||
|
||
**版本迭代模板**（需要Git版本）：
|
||
|
||
```markdown
|
||
# [策略名称]核心逻辑 V3
|
||
|
||
> 更新日期：YYYY-MM-DD
|
||
> Git Commit：`[hash]`
|
||
|
||
## V2 vs V3 核心差异
|
||
| 维度 | V2 | V3 |
|
||
|------|----|----|
|
||
| [维度1] | ... | ... |
|
||
|
||
## V3 新增机制
|
||
[详细说明]
|
||
|
||
## 迁移指南
|
||
[从V2迁移到V3的注意事项]
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- 版本迭代类：必须记录Git Commit
|
||
- 当前描述类：无需，但建议注明"当前版本"
|
||
|
||
---
|
||
|
||
### 3.6 技术架构类（docs/）
|
||
|
||
**定位**：系统架构、模块设计、接口说明
|
||
|
||
**头部模板**：
|
||
|
||
```markdown
|
||
# [模块名称] - 架构设计
|
||
|
||
## 设计目标
|
||
[解决的问题、达到的效果]
|
||
|
||
## 整体架构
|
||
[架构图 + 说明]
|
||
|
||
## 核心组件
|
||
[各组件职责]
|
||
|
||
## 使用示例
|
||
[典型调用场景]
|
||
```
|
||
|
||
**特点**：技术架构类文档与具体代码版本无关，无需Git版本记录
|
||
|
||
---
|
||
|
||
## 4. 内容撰写建议
|
||
|
||
### 4.1 好文档的特征
|
||
|
||
| 特征 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **背景清晰** | 读者能快速理解"为什么" | "诊断发现IC=0.07，故调研新因子" |
|
||
| **方法明确** | 读者能理解"怎么做" | "使用slope×R²因子，回看25天" |
|
||
| **数据完整** | 关键数据用表格呈现 | 收益对比、参数列表 |
|
||
| **结论有力** | 结论基于数据，有行动建议 | "建议采用slope_r2作为默认因子" |
|
||
| **可复现** | 任何人可按指引复现结果 | Git版本 + 配置 + 命令 |
|
||
|
||
### 4.2 应避免的问题
|
||
|
||
| 问题 | 说明 | 改进方向 |
|
||
|------|------|----------|
|
||
| 无版本记录 | 实验结果无法复现 | 添加Git Commit + 复现命令 |
|
||
| 结论无数据 | "效果很好"但没有数据 | 添加收益表格、对比数据 |
|
||
| 背景缺失 | 直接讲结果，读者不知道为什么 | 添加"背景/问题来源"章节 |
|
||
| 过于冗长 | 全是文字，缺少结构 | 使用表格、列表、章节编号 |
|
||
| 缺少建议 | 只有结论，没有下一步 | 添加"后续建议"章节 |
|
||
|
||
### 4.3 章节编号建议
|
||
|
||
- 主章节：`## 1.`、`## 2.`、`## 3.`
|
||
- 子章节：`### 1.1`、`### 1.2`
|
||
- 更细：`#### 1.1.1`
|
||
|
||
**灵活使用**：短文档可以不编号，长文档建议编号便于引用
|
||
|
||
### 4.4 分隔线使用
|
||
|
||
- 元信息与正文之间：建议使用 `---`
|
||
- 不同主题之间：可选使用 `---`
|
||
- 同一主题内：不建议使用
|
||
|
||
---
|
||
|
||
## 5. 目录存放规则
|
||
|
||
### 5.1 目录结构
|
||
|
||
```
|
||
docs/
|
||
├── YYYYMMDD_文档名称.md # 分析报告、调研报告、核心逻辑
|
||
├── experiments/ # 实验记录（严格格式）
|
||
│ └── YYYYMMDD_XXX_实验名称.md
|
||
├── strategy_summaries/ # 阶段性总结（严格格式）
|
||
│ └── YYYYMMDD_策略快照_hash.md
|
||
└── 文档创建规范.md # 本规范（例外）
|
||
```
|
||
|
||
### 5.2 目录选择原则
|
||
|
||
| 文档类型 | 存放目录 | 原因 |
|
||
|----------|----------|------|
|
||
| 实验记录 | experiments/ | 需要编号排序，便于查找 |
|
||
| 阶段总结 | strategy_summaries/ | 快照性质，独立存放 |
|
||
| 其他文档 | docs/ | 通用位置 |
|
||
|
||
---
|
||
|
||
## 6. 文档创建检查清单
|
||
|
||
### 6.1 实证类文档必查项
|
||
|
||
创建实验记录、分析报告、阶段总结时：
|
||
|
||
- [ ] **Git Commit已记录**（这是最重要的！）
|
||
- [ ] 配置文件路径已记录
|
||
- [ ] 运行命令已记录
|
||
- [ ] 回测区间/数据范围已说明
|
||
- [ ] 文件名符合命名规范
|
||
|
||
### 6.2 所有文档通用检查项
|
||
|
||
- [ ] 文件名符合 `YYYYMMDD_中文名称.md` 格式（例外除外）
|
||
- [ ] 头部有必要的元信息（根据类型）
|
||
- [ ] 有明确的背景/问题描述
|
||
- [ ] 有数据支撑的结论
|
||
- [ ] 有后续建议或下一步
|
||
- [ ] 存放在正确的目录
|
||
|
||
### 6.3 复现测试（可选但推荐）
|
||
|
||
重要文档创建后，建议进行复现测试：
|
||
|
||
```bash
|
||
# 切换到文档记录的版本
|
||
git checkout [文档中的hash]
|
||
|
||
# 按文档中的命令运行
|
||
python [文档中的脚本] --config [文档中的配置]
|
||
|
||
# 验证结果是否与文档一致
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 快速参考
|
||
|
||
### 7.1 按文档类型选择模板
|
||
|
||
| 文档类型 | 模板章节 | Git版本要求 |
|
||
|----------|----------|------------|
|
||
| 实验记录 | 3.1 | **必须** |
|
||
| 分析报告 | 3.2 | 有代码运行则必须 |
|
||
| 调研报告 | 3.3 | 有验证实验则必须 |
|
||
| 阶段总结 | 3.4 | **必须** |
|
||
| 核心逻辑（迭代） | 3.5 | 对比版本时必须 |
|
||
| 技术架构 | 3.6 | 不需要 |
|
||
|
||
### 7.2 Git版本记录模板
|
||
|
||
复制以下内容到实证类文档头部：
|
||
|
||
```markdown
|
||
| Git Commit | `[hash]` |
|
||
| 配置文件 | `[路径]` |
|
||
| 实验脚本 | `[路径]` |
|
||
```
|
||
|
||
或使用引用块格式：
|
||
|
||
```markdown
|
||
> **Git Commit**：`[hash]`
|
||
> **配置文件**：`[路径]`
|
||
> **运行命令**：`[完整命令]`
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 版本历史
|
||
|
||
| 版本 | 日期 | 主要变更 |
|
||
|------|------|----------|
|
||
| v2.0 | 2026-06-21 | 强化Git可复现性要求，区分实证与非实证文档 |
|
||
| v1.0 | 2026-06-21 | 初版，定义命名规范与分类模板 | |