aszer/etf

Fork 0

Files

aszerW aa4a8b2b62 docs: 移除实验文档编号前缀，简化命名规则

2026-06-21 19:39:36 +08:00

12 KiB

Raw Blame History

ETF轮动项目文档创建规范

规范版本：v2.0 制定日期：2026-06-21 核心原则：实证类文档必须记录Git版本，确保结果可复现

1. 核心原则：Git可复现性

1.1 为什么必须记录Git版本？

量化策略研究的特点是代码与结果紧密耦合：

同一份代码，不同参数可能产生截然不同的结果
代码迭代后，历史实验结果可能无法复现
没有版本记录，文档的结论很快就会变成"孤证"

核心要求：凡涉及代码运行、数据分析、回测实验的文档，必须在生成时记录完整的Git版本信息。

1.2 什么是"实证类文档"？

类型	是否需要Git版本	说明
实验记录	✅ 必须	每次实验都是特定代码版本的输出
分析报告	✅ 必须	分析结果依赖特定配置和代码
阶段总结	✅ 必须	快照性质，必须锁定版本
调研报告	⚠️ 有回测则需要	纯文献综述无需，有验证实验则需要
核心逻辑	⚠️ 迭代版本需要	描述当前逻辑无需，对比版本则需要
技术架构	❌ 不需要	设计文档，与代码版本无关
接口说明	❌ 不需要	API文档，与具体版本无关

1.3 必须记录的版本信息

实证类文档头部必须包含以下三项：

> **Git Commit**：`abc1234`（完整的commit hash或短hash）
> **配置文件**：`rotation/config_simple.yaml`
> **运行命令**：`python rotation/simple_rotation.py`

为什么这三项是必要的？

Git Commit：锁定代码版本，任何人可通过 git checkout 回到该版本
配置文件：参数配置对结果影响极大，必须明确记录
运行命令：完整的执行路径，确保复现时不会遗漏步骤

2. 文件命名规范

2.1 基本格式

YYYYMMDD_中文名称.md

日期来源：文档首次创建的git提交日期（可通过 git log --diff-filter=A 查询）
命名原则：日期前缀 + 简洁中文描述
分隔符：使用 _ 分隔日期和名称，名称内部可用 - 连接
禁止字符：空格（会导致命令行操作困难）

2.2 特殊场景命名规则

场景	格式	示例
实验记录	`YYYYMMDD_名称.md`	`20260617_起始年份敏感性分析.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对比实验、参数优化、敏感性分析等需要严格复现的研究

头部模板：

# 实验记录 XXX: [实验名称]

## 实验信息

| 项目 | 内容 |
|------|------|
| 实验编号 | （可选） |
| 实验日期 | YYYY-MM-DD |
| 实验类型 | 参数优化 / 对比实验 / 敏感性分析 / 问题诊断 |
| 研究问题 | [一句话描述] |
| Git Commit | `[hash]` |
| 配置文件 | `[路径]` |
| 实验脚本 | `[路径]` |

## 实验背景
[问题来源、预期目标]

## 实验设计
[变量定义、对照组设置]

## 实验结果
[数据表格、核心发现]

## 结论与后续
[结论摘要、下一步建议]

必须记录的信息：

实验编号：可选，三位数字便于排序和引用
Git Commit：必须
配置文件：必须
实验脚本：必须

为什么实验记录格式最严格？ 实验记录是项目的核心资产，每一份都代表一个可复现的"科学实验"。未来可能需要：

回溯历史实验验证当前假设
对比不同时期的实验结果
复现某个关键发现

3.2 分析报告类（docs/）

定位：策略深度分析、回测报告、问题诊断等

头部模板：

# [报告标题]

> 分析日期：YYYY-MM-DD
> Git Commit：`[hash]`（如有代码运行）
> 配置文件：`[路径]`（如有配置依赖）
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD

---

## 1. 分析背景
...

## 2. 分析方法
...

## 3. 核心发现
...

## 4. 结论与建议
...

必须记录的信息：

分析日期
Git Commit：如果分析依赖代码运行，必须记录
回测区间：如果有回测数据

分析报告的核心价值：记录"为什么"和"怎么做"，不只是结论

3.3 调研报告类（docs/）

定位：技术调研、因子调研、文献综述、方法论研究

头部模板：

# [调研标题]

> 调研日期：YYYY-MM-DD
> 调研来源：[文献/社区/实验验证]
> Git Commit：`[hash]`（如有验证实验）
> 当前结论：[核心发现摘要]

---

## 1. 调研背景
[为什么调研这个主题]

## 2. 调研内容
[方法/理论/实验]

## 3. 结论与建议
[对项目的指导意义]

必须记录的信息：

调研日期
调研来源：说明结论来自哪里（文献、实验、社区等）

两种调研类型：

文献调研：无需Git版本，但需注明文献来源
验证调研：如果包含回测验证，必须记录Git版本

3.4 阶段性总结类（docs/strategy_summaries/）

定位：策略阶段快照，锁定特定版本的状态

头部模板：

# ETF轮动策略阶段总结

> **生成日期**：YYYY-MM-DD
> **Git Commit**：`[完整hash]`
> **复现方式**：
> ```bash
> git checkout [hash]
> python [脚本路径] --config [配置路径]
> ```

---

## 1. 策略概述
[资产池、因子、参数配置]

## 2. 当前表现
[收益、风险、换手率等]

## 3. 关键发现
[本阶段的主要认知]

## 4. 下一步计划
[待解决的问题、优化方向]

必须记录的信息：

Git Commit：必须（这是快照类文档的本质）
复现方式：必须（完整的复现命令）

为什么阶段性总结最强调复现？ 阶段性总结是项目的里程碑，代表某个时期的"完整状态"。未来可能需要：

对比不同阶段的策略表现
回溯某个阶段的认知
复现某个版本的具体结果

3.5 核心逻辑类（docs/）

定位：策略核心机制说明、版本迭代对比

当前版本模板（无需Git版本）：

# [策略名称]核心逻辑

## 策略概览
[一句话定位]

## 核心机制
[信号生成、仓位分配、调仓逻辑]

## 参数说明
[关键参数及其含义]

## 典型场景
[持仓示例、调仓示例]

版本迭代模板（需要Git版本）：

# [策略名称]核心逻辑 V3

> 更新日期：YYYY-MM-DD
> Git Commit：`[hash]`

## V2 vs V3 核心差异
| 维度 | V2 | V3 |
|------|----|----|
| [维度1] | ... | ... |

## V3 新增机制
[详细说明]

## 迁移指南
[从V2迁移到V3的注意事项]

必须记录的信息：

版本迭代类：必须记录Git Commit
当前描述类：无需，但建议注明"当前版本"

3.6 技术架构类（docs/）

定位：系统架构、模块设计、接口说明

头部模板：

# [模块名称] - 架构设计

## 设计目标
[解决的问题、达到的效果]

## 整体架构
[架构图 + 说明]

## 核心组件
[各组件职责]

## 使用示例
[典型调用场景]

特点：技术架构类文档与具体代码版本无关，无需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_实验名称.md
├── strategy_summaries/          # 阶段性总结（严格格式）
│   └── YYYYMMDD_策略快照_hash.md
└── 文档创建规范.md              # 本规范（例外）

5.2 目录选择原则

文档类型	存放目录	原因
实验记录	experiments/	需要编号排序，便于查找
阶段总结	strategy_summaries/	快照性质，独立存放
其他文档	docs/	通用位置

6. 文档创建检查清单

6.1 实证类文档必查项

创建实验记录、分析报告、阶段总结时：

Git Commit已记录（这是最重要的！）
配置文件路径已记录
运行命令已记录
回测区间/数据范围已说明
文件名符合命名规范

6.2 所有文档通用检查项

文件名符合 YYYYMMDD_中文名称.md 格式（例外除外）
头部有必要的元信息（根据类型）
有明确的背景/问题描述
有数据支撑的结论
有后续建议或下一步
存放在正确的目录

6.3 复现测试（可选但推荐）

重要文档创建后，建议进行复现测试：

# 切换到文档记录的版本
git checkout [文档中的hash]

# 按文档中的命令运行
python [文档中的脚本] --config [文档中的配置]

# 验证结果是否与文档一致

7. 快速参考

7.1 按文档类型选择模板

文档类型	模板章节	Git版本要求
实验记录	3.1	必须
分析报告	3.2	有代码运行则必须
调研报告	3.3	有验证实验则必须
阶段总结	3.4	必须
核心逻辑（迭代）	3.5	对比版本时必须
技术架构	3.6	不需要

7.2 Git版本记录模板

复制以下内容到实证类文档头部：

| Git Commit | `[hash]` |
| 配置文件 | `[路径]` |
| 实验脚本 | `[路径]` |

或使用引用块格式：

> **Git Commit**：`[hash]`
> **配置文件**：`[路径]`
> **运行命令**：`[完整命令]`

8. 版本历史

版本	日期	主要变更
v2.0	2026-06-21	强化Git可复现性要求，区分实证与非实证文档
v1.0	2026-06-21	初版，定义命名规范与分类模板

12 KiB Raw Blame History Unescape Escape

ETF轮动项目文档创建规范

1. 核心原则：Git可复现性

1.1 为什么必须记录Git版本？

1.2 什么是"实证类文档"？

1.3 必须记录的版本信息

2. 文件命名规范

2.1 基本格式

2.2 特殊场景命名规则

2.3 例外情况（无需日期前缀）

3. 文档分类详解

3.1 实验记录类（docs/experiments/）

3.2 分析报告类（docs/）

3.3 调研报告类（docs/）

3.4 阶段性总结类（docs/strategy_summaries/）

3.5 核心逻辑类（docs/）

3.6 技术架构类（docs/）

4. 内容撰写建议

4.1 好文档的特征

4.2 应避免的问题

4.3 章节编号建议

4.4 分隔线使用

5. 目录存放规则

5.1 目录结构

5.2 目录选择原则

6. 文档创建检查清单

6.1 实证类文档必查项

6.2 所有文档通用检查项

6.3 复现测试（可选但推荐）

7. 快速参考

7.1 按文档类型选择模板

7.2 Git版本记录模板

8. 版本历史

12 KiB

Raw Blame History