aszer/etf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 强化Git可复现性规范，区分实证与非实证文档类型

Browse Source
This commit is contained in:
aszerW
2026-06-21 19:31:30 +08:00
parent 1cb854f2d8
commit 7cc882dade
1 changed files with 367 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

598
docs/文档创建规范.md
View File

@@ -1,100 +1,88 @@
# ETF轮动项目文档创建规范
> 规范版本：v1.0
> 规范版本：v2.0
> 制定日期：2026-06-21
> 核心原则：**实证类文档必须记录Git版本，确保结果可复现**
---
## 1. 文件命名规范
## 1. 核心原则：Git可复现性
### 1.1 基本格式
### 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提交日期（可通过 `git log --diff-filter=A` 查询）
- **命名原则**：日期前缀 + 简洁中文描述
- **禁止字符**：空格、特殊符号（除 `_` 和 `-`）
- **分隔符**：使用 `_` 分隔日期和名称，名称内部可用 `-` 连接
- **禁止字符**：空格（会导致命令行操作困难）
### 1.2 命名示例
### 2.2 特殊场景命名规则
| 类型 | 示例 |
|------|------|
| 分析报告 | `20260607_select_num_1深度分析.md` |
| 调研报告 | `20260606_动量因子对比调研.md` |
| 实验记录 | `20260617_010_起始年份敏感性分析.md` |
| 架构设计 | `20260507_通用数据源架构.md` |
| 核心逻辑 | `20260430_轮动策略核心逻辑.md` |
| 版本迭代 | `20260519_轮动策略核心逻辑_v3.md` |
| 场景 | 格式 | 示例 |
|------|------|------|
| 实验记录 | `YYYYMMDD_编号_名称.md` | `20260617_010_起始年份敏感性分析.md` |
| 版本迭代 | `YYYYMMDD_名称_vN.md` | `20260519_轮动策略核心逻辑_v3.md` |
| 阶段总结 | `YYYYMMDD_名称_hash.md` | `20260606_策略快照_ca933e4.md` |
| 英文内容 | 可保留英文或翻译 | `20260621_greedy与rank对比分析.md` |
### 1.3 特殊场景
### 2.3 例外情况（无需日期前缀）
- **实验编号**：experiments目录下保留编号前缀，格式 `YYYYMMDD_编号_名称.md`
- **版本号**：迭代版本在末尾加 `_vN`，如 `_v2`、`_v3`
- **Git标识**：阶段性总结可带commit hash，如 `_ca933e4`
- 规范文档：`文档创建规范.md`
- 目录说明：`README.md`
- 从其他位置迁移的旧文档：可保留原名称，在元信息中注明迁移信息
---
## 2. 文档分类与头部格式
## 3. 文档分类详解
### 2.1 分析报告类
### 3.1 实验记录类（docs/experiments/）
**适用场景**：策略分析、回测分析、深度分析
**定位**：A/B对比实验、参数优化、敏感性分析等需要严格复现的研究
**头部格式**：
```markdown
# [报告标题]
> 分析日期：YYYY-MM-DD
> 策略版本：[配置文件/代码版本说明]
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（约 N 个交易日）
## 1. [章节标题]
...
```
**必填字段**：
- 分析日期：文档创建日期
- 策略版本：基于的配置文件或代码版本
- 回测区间：数据时间范围
---
### 2.2 调研报告类
**适用场景**：技术调研、因子调研、文献综述
**头部格式**：
```markdown
# [调研标题]
> 调研日期：YYYY-MM-DD
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（可选）
> 当前结论：[核心发现摘要]
---
## 1. [章节标题]
...
```
**必填字段**：
- 调研日期：文档创建日期
**可选字段**：
- 回测区间：如有回测实验
- 当前结论：调研核心发现
---
### 2.3 实验记录类（experiments目录）
**适用场景**：对比实验、参数优化、敏感性分析
**头部格式**：
**头部模板**：
```markdown
# 实验记录 XXX: [实验名称]
@@ -105,218 +93,366 @@ YYYYMMDD_中文名称.md
|------|------|
| 实验编号 | XXX |
| 实验日期 | YYYY-MM-DD |
| 实验类型 | [类型分类] |
| 研究问题 | [问题描述] |
| 配置文件 | `[配置路径]` |
| 实验脚本 | `[脚本路径]` |
| 实验类型 | 参数优化 / 对比实验 / 敏感性分析 / 问题诊断 |
| 研究问题 | [一句话描述] |
| Git Commit | `[hash]` |
| 配置文件 | `[路径]` |
| 实验脚本 | `[路径]` |
## 实验背景
[问题来源、预期目标]
## 实验设计
[变量定义、对照组设置]
## 实验结果
[数据表格、核心发现]
## 结论与后续
[结论摘要、下一步建议]
```
**必须记录的信息**：
- 实验编号：三位数字，便于排序和引用
- Git Commit：**必须**
- 配置文件：**必须**
- 实验脚本：**必须**
**为什么实验记录格式最严格？**
实验记录是项目的核心资产，每一份都代表一个可复现的"科学实验"。未来可能需要：
- 回溯历史实验验证当前假设
- 对比不同时期的实验结果
- 复现某个关键发现
---
## 1. 实验背景
### 3.2 分析报告类（docs/）
**定位**：策略深度分析、回测报告、问题诊断等
**头部模板**：
```markdown
# [报告标题]
> 分析日期：YYYY-MM-DD
> Git Commit：`[hash]`（如有代码运行）
> 配置文件：`[路径]`（如有配置依赖）
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD
---
## 1. 分析背景
...
## 2. 分析方法
...
## 3. 核心发现
...
## 4. 结论与建议
...
```
**必填字段**：
- 实验编号：三位数字，如 001、010
- 实验日期：文档创建日期
- 实验类型：如"参数优化"、"对比实验"、"敏感性分析"
- 研究问题：一句话描述研究目标
- 配置文件：使用的配置文件路径
- 实验脚本：运行的脚本路径
**必须记录的信息**：
- 分析日期
- Git Commit：**如果分析依赖代码运行，必须记录**
- 回测区间：如果有回测数据
**分析报告的核心价值**：记录"为什么"和"怎么做"，不只是结论
---
### 2.4 技术架构类
### 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版本记录
---
### 2.5 核心逻辑类
## 4. 内容撰写建议
**适用场景**：策略核心逻辑、算法说明、版本迭代
### 4.1 好文档的特征
**头部格式**：
| 特征 | 说明 | 示例 |
|------|------|------|
| **背景清晰** | 读者能快速理解"为什么" | "诊断发现IC=0.07，故调研新因子" |
| **方法明确** | 读者能理解"怎么做" | "使用slope×R²因子，回看25天" |
| **数据完整** | 关键数据用表格呈现 | 收益对比、参数列表 |
| **结论有力** | 结论基于数据，有行动建议 | "建议采用slope_r2作为默认因子" |
| **可复现** | 任何人可按指引复现结果 | Git版本 + 配置 + 命令 |
```markdown
# [策略名称]核心逻辑 [版本号]
### 4.2 应避免的问题
## 📊 策略概览
| 问题 | 说明 | 改进方向 |
|------|------|----------|
| 无版本记录 | 实验结果无法复现 | 添加Git Commit + 复现命令 |
| 结论无数据 | "效果很好"但没有数据 | 添加收益表格、对比数据 |
| 背景缺失 | 直接讲结果，读者不知道为什么 | 添加"背景/问题来源"章节 |
| 过于冗长 | 全是文字，缺少结构 | 使用表格、列表、章节编号 |
| 缺少建议 | 只有结论，没有下一步 | 添加"后续建议"章节 |
[策略概述]
---
## [章节标题]
...
```
**说明**：
- 使用emoji增强章节可读性
- 版本迭代文档需包含版本对比章节
---
### 2.6 阶段性总结类（strategy_summaries目录）
**适用场景**：策略阶段总结、版本快照
**头部格式**：
```markdown
# [策略名称]阶段总结
> **生成日期**：YYYY-MM-DD
> **Git Commit**：`commit_hash`
> **复现方式**：`git checkout xxx` 后运行 `[脚本路径]`
---
## 1. 策略概述
...
```
**必填字段**：
- 生成日期：快照生成日期
- Git Commit：代码版本hash
- 复现方式：如何复现该版本的完整命令
---
## 3. Git可复现性规范
### 3.1 核心原则
> **所有实验、分析结果必须可通过Git历史精确复现**
### 3.2 必须记录的信息
| 信息类型 | 记录位置 | 示例 |
|----------|----------|------|
| 配置文件 | 元信息块 | `config_simple.yaml` |
| 代码版本 | 元信息块或正文 | `ca933e4` |
| 实验脚本 | 实验信息表 | `rotation/simple_rotation.py` |
| 数据范围 | 元信息块 | `2020-01-10 ~ 2026-06-05` |
### 3.3 复现命令示例
```bash
# 切换到指定版本
git checkout ca933e4
# 运行实验脚本
python rotation/simple_rotation.py --config rotation/config_simple.yaml
```
---
## 4. 内容结构规范
### 4.1 章节编号
### 4.3 章节编号建议
- 主章节：`## 1.`、`## 2.`、`## 3.`
- 子章节：`### 1.1`、`### 1.2`
- 段落要点：使用有序或无序列表
- 更细：`#### 1.1.1`
### 4.2 分隔线使用
**灵活使用**：短文档可以不编号，长文档建议编号便于引用
- 元信息块与正文之间：使用 `---` 分隔
- 不同主题章节之间：可选使用 `---` 分隔
### 4.4 分隔线使用
### 4.3 表格格式
```markdown
| 列名1 | 列名2 | 列名3 |
|------|------|------|
| 内容1 | 内容2 | 内容3 |
```
- 表头使用粗体或自然加粗
- 内容左对齐，数值列可右对齐
### 4.4 代码块格式
```markdown
```python
# 代码示例
def example():
pass
\```
```
- 指定语言类型
- 关键代码需有注释说明
- 元信息与正文之间：建议使用 `---`
- 不同主题之间：可选使用 `---`
- 同一主题内：不建议使用
---
## 5. 文档存放目录
## 5. 目录存放规则
### 5.1 目录结构
```
docs/
├── YYYYMMDD_文档名称.md # 通用文档
├── experiments/ # 实验记录
├── YYYYMMDD_文档名称.md # 分析报告、调研报告、核心逻辑
├── experiments/ # 实验记录（严格格式）
│ └── YYYYMMDD_XXX_实验名称.md
├── strategy_summaries/ # 阶段性总结
├── strategy_summaries/ # 阶段性总结（严格格式）
│ └── YYYYMMDD_策略快照_hash.md
└── 文档创建规范.md # 本规范文档（例外：无日期前缀）
└── 文档创建规范.md # 本规范（例外）
```
### 5.2 目录选择原则
| 文档类型 | 存放目录 |
|----------|----------|
| 策略分析、调研报告 | docs/ |
| 实验记录、对比测试 | docs/experiments/ |
| 策略阶段总结、版本快照 | docs/strategy_summaries/ |
| 文档类型 | 存放目录 | 原因 |
|----------|----------|------|
| 实验记录 | experiments/ | 需要编号排序，便于查找 |
| 阶段总结 | strategy_summaries/ | 快照性质，独立存放 |
| 其他文档 | docs/ | 通用位置 |
---
## 6. 例外情况
## 6. 文档创建检查清单
### 6.1 规范文档本身
### 6.1 实证类文档必查项
- 规范文档不使用日期前缀
- 文件名：`文档创建规范.md`
创建实验记录、分析报告、阶段总结时：
### 6.2 README文件
- [ ] **Git Commit已记录**（这是最重要的！）
- [ ] 配置文件路径已记录
- [ ] 运行命令已记录
- [ ] 回测区间/数据范围已说明
- [ ] 文件名符合命名规范
- 目录说明文件命名为 `README.md`
- 无需日期前缀
### 6.2 所有文档通用检查项
### 6.3 从其他位置迁移的文档
- 如无法确定原始创建日期，使用迁移日期
- 在元信息中注明"迁移自[原位置]"
---
## 7. 检查清单
创建新文档时，确认以下事项：
- [ ] 文件名符合 `YYYYMMDD_中文名称.md` 格式
- [ ] 头部元信息完整（根据文档类型）
- [ ] Git可复现信息已记录（commit hash、配置文件、脚本路径）
- [ ] 文件名符合 `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 | 初版，定义命名规范与分类模板 |