From 7cc882daded3f3af6b209b055e181d53954214d8 Mon Sep 17 00:00:00 2001 From: aszerW Date: Sun, 21 Jun 2026 19:31:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BC=BA=E5=8C=96Git=E5=8F=AF=E5=A4=8D?= =?UTF-8?q?=E7=8E=B0=E6=80=A7=E8=A7=84=E8=8C=83=EF=BC=8C=E5=8C=BA=E5=88=86?= =?UTF-8?q?=E5=AE=9E=E8=AF=81=E4=B8=8E=E9=9D=9E=E5=AE=9E=E8=AF=81=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=B1=BB=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/文档创建规范.md | 598 ++++++++++++++++++++++++++----------------- 1 file changed, 367 insertions(+), 231 deletions(-) diff --git a/docs/文档创建规范.md b/docs/文档创建规范.md index 3b8aaa1..527a09d 100644 --- a/docs/文档创建规范.md +++ b/docs/文档创建规范.md @@ -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` 格式（例外除外） +- [ ] 头部有必要的元信息（根据类型） +- [ ] 有明确的背景/问题描述 +- [ ] 有数据支撑的结论 +- [ ] 有后续建议或下一步 - [ ] 存放在正确的目录 -- [ ] 章节编号规范 -- [ ] 代码块指定语言类型 -- [ ] 分隔线使用恰当 \ No newline at end of file + +### 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 | 初版，定义命名规范与分类模板 | \ No newline at end of file