7.9 研究项目结构：如何组织代码与实验
课前导读
本章目标
学完能解决什么困惑：为什么量化研究不能把数据、代码、图表和结论随手放在一起，以及如何搭建最小研究文件夹。
适合谁学习：已经开始用 Python 读写数据，希望自己的 A 股研究一个月后还能复现的读者。
难度：beginner
预计用时：约 35 分钟
很多新手第一次做量化研究时，会把所有东西堆在桌面。
一个 CSV 文件叫 data.csv。
一个 Notebook 叫 新建文件.ipynb。
图表截图放在聊天软件里。
结论写在脑子里。
当时好像没问题。
两周后再打开，就会发现自己已经忘了数据从哪里来、代码跑的是哪一版、图表对应哪组参数。
研究项目结构要解决的，就是这种“研究失忆”。
你可以把项目文件夹想成一间厨房。
原材料、半成品、菜谱、成品菜、清洁记录，都应该有自己的位置。
量化研究也一样。
知识正文
1. 类比：厨房分区与研究分区
厨房里不会把生肉、熟菜、调料和账本混在一个盆里。
因为这样既不卫生，也不容易复查。
量化研究中的数据、代码、图表和日志，也需要分区。
data 像原材料区。
notebooks 像试菜台。
src 像正式菜谱。
reports 像端给别人看的成品。
logs 像后厨记录。
分区不是为了显得专业。
它是为了让研究过程可复现。
所谓可复现，就是别人或未来的你，能按相同材料和步骤得到相同或可解释的结果。
2. 最小研究文件夹长什么样
入门阶段不需要复杂工程。
一个最小研究文件夹可以这样组织。
ma20_ma60_research/
├── data/
│ ├── raw/
│ └── processed/
├── notebooks/
├── src/
├── reports/
└── logs/data/raw 保存原始数据。
原始数据尽量不要手工改动。
因为它是研究的起点证据。
data/processed 保存清洗后的数据。
例如补齐日期、统一字段名、剔除明显错误后的文件。
notebooks 用来探索。
你可以在这里试图表、看样本、验证想法。
src 用来放相对稳定的代码。
当某段 Notebook 代码反复使用，就可以整理到这里。
reports 用来放研究报告、图表输出和结论记录。
logs 用来放实验记录。
它记录你哪天改了什么参数，为什么改，结果如何。
3. A 股研究为什么尤其需要结构
A 股数据有很多口径问题。
比如前复权、后复权、未复权。
比如停牌日是否补齐。
比如成交额单位是元还是万元。
比如财务数据在公告日之后才可见。
如果文件随手放，口径很容易混乱。
你可能今天用前复权价格，明天误用未复权价格。
你可能这次筛选排除了 ST 股票，下次忘了这个条件。
你可能报告里写“样本 2020-2025”，但实际数据只到 2024 年底。
这些错误都不是策略思想问题。
它们是组织方式问题。
项目结构把容易混乱的地方提前分开。
这会显著降低研究复盘成本。
4. 文件命名：让未来的自己看懂
文件名不要只叫 result.csv。
一个好文件名应该包含主题、范围、日期或版本。
例如：000001_daily_2020_2025_raw.csv。
这表示某只股票的日线原始数据，覆盖 2020 到 2025。
例如：ma20_ma60_signals_v01.csv。
这表示 20 日均线和 60 日均线信号的第 1 版。
例如：research_report_2026-05-09.md。
这表示某天生成的研究报告。
命名的目的不是越长越好。
而是看到文件名时，你能大概知道它是什么。
如果文件名需要靠记忆解释，它就不够好。
5. 版本：研究不是一次完成的
研究会不断变化。
你会改数据范围。
你会改过滤条件。
你会改成本假设。
你会改图表说明。
如果每次覆盖旧文件，就很难知道结果为什么变了。
入门阶段可以用简单版本号。
v01 表示第一版。
v02 表示第二版。
也可以用日期。
例如 signals_2026-05-09.csv。
更专业的版本管理以后可以继续学习。
本节只要求你先做到：重要结果不要无痕覆盖。
6. 实验记录：写给未来的自己
实验记录不需要写成长论文。
它只需要回答五个问题。
今天研究什么问题。
使用哪份数据。
改了哪些规则或参数。
得到什么结果。
下一步要检查什么风险。
如果没有实验记录，研究很容易变成“凭印象改来改去”。
如果有记录，你就能追踪每次变化。
当某个结果突然变好或变差时，你能找到原因。
这就是从投资者直觉走向量化研究的关键一步。
7. 研究流程图
下面这个流程不涉及完整回测系统。
它只是最小研究文件夹内的数据流向。
flowchart TD
A[data/raw 原始数据] --> B[data/processed 清洗数据]
B --> C[notebooks 探索分析]
C --> D[src 稳定代码]
D --> E[reports 图表与报告]
C --> F[logs 实验记录]
D --> F注意，data/raw 不应该被随便覆盖。
你可以从原始数据加工出新文件。
但不要把加工结果再冒充原始数据。
这条边界对研究复现非常重要。
8. 一个短小的 Python 建夹示例
你也可以用 Python 创建最小文件夹。
这段代码不需要新增依赖。
from pathlib import Path
root = Path("ma20_ma60_research")
folders = [
"data/raw",
"data/processed",
"notebooks",
"src",
"reports",
"logs",
]
for folder in folders:
(root / folder).mkdir(parents=True, exist_ok=True)Path 用来表达文件路径。
mkdir() 用来创建文件夹。
parents=True 表示中间目录不存在时一起创建。
exist_ok=True 表示文件夹已经存在也不报错。
新手可以先手工创建文件夹。
等熟悉后，再用代码自动创建。
重点不是工具，而是分工清楚。
9. A 股案例：一个均线观察项目
假设你想研究“20 日均线高于 60 日均线时，某个股票池是否更容易保持强势”。
这个问题本身还不是完整策略。
它只是第 8 章因子和第 9 章回测之前的研究准备。
你可以把项目命名为 ma20_ma60_research。
把下载或手工导出的行情数据放入 data/raw。
把统一字段名、处理日期后的数据放入 data/processed。
把探索图表写在 notebooks。
把反复使用的均线计算函数放入 src。
把收益曲线、回撤曲线和文字结论放入 reports。
把每次调整股票池、时间范围、成本假设的记录放入 logs。
这样一个月后你再回来看，仍然知道当时做了什么。
10. 新手常见混乱点
混乱点一：原始数据和清洗数据混在一起。
解决方式：原始数据只读不改，清洗结果另存。
混乱点二：Notebook 越写越长，无法复查。
解决方式：探索可以乱一点，但最终结论要整理到报告。
混乱点三：图表没有对应的数据版本。
解决方式：图表文件名或报告里写清楚数据文件名。
混乱点四：参数只存在脑子里。
解决方式：把均线周期、成本假设、样本范围写入日志。
混乱点五：把研究文件夹当成交易系统。
解决方式：本章只做研究组织，不涉及实盘工程。
关键心得
研究结构不是程序员的洁癖，而是投资研究的证据链。
交互实验室
练习 1：搭建你的最小研究文件夹
请在本地创建一个文件夹，命名为 first_astock_research。
在里面创建五个子文件夹。
data/raw：放原始行情或样本表。
data/processed：放清洗后的表。
notebooks：放探索过程。
reports：放图表和报告。
logs：放实验记录。
如果你暂时不用 src，也可以先不建。
等某段代码需要反复使用时，再加入 src。
练习 2：写一条实验记录
在 logs 里新建一个文本记录。
写下今天的研究问题。
写下数据来源。
写下样本时间范围。
写下你准备计算的列。
写下你最担心的风险。
这五行就是最小实验日志。
练习 3：检查文件名
请检查你电脑里已有的研究文件。
如果出现 data.csv、结果.xlsx、最终版2.ipynb 这类名字，请给它们重新命名。
新名字至少包含研究主题和日期。
例如 ma20_signal_2026-05-09.csv。
你不需要追求完美。
只要未来的自己能看懂，就是进步。
核心复盘
知识清单：
- [ ] 我知道
data/raw、data/processed、notebooks、src、reports、logs的分工。 - [ ] 我理解原始数据应尽量保留，不应被清洗结果覆盖。
- [ ] 我能用文件名表达主题、范围、日期或版本。
- [ ] 我知道实验记录要写问题、数据、规则、结果和下一步。
- [ ] 我理解本章是在组织研究，不是在搭建完整回测或实盘系统。
金句总结
一个好项目结构，就是给未来的自己留下一条可追踪的研究证据链。