20.8 Research 项目包装：简历、GitHub 与 One-Pager

项目包装不是美化结果，而是压缩证据。优秀的 Research 项目材料必须让面试官在 30 秒内看懂问题、在 3 分钟内判断研究可信度、在 30 分钟 Deep Dive 中复现你的关键决策。任何无法解释的数据、指标或代码，都不应出现在简历上。

概念详解

一页纸研究：高效传递研究价值

One-Pager 是一份决策摘要，不是缩短版论文。它要回答七个问题：

1. 研究问题是什么，为什么值得研究？
2. 数据在什么时间可得，样本范围是什么？
3. 核心方法和基准是什么？
4. 样本外结果如何，是否扣除成本？
5. 结果为什么可能成立？
6. 何时失效，容量和风险在哪里？
7. 下一步实验或上线门槛是什么？

建议正文控制在 600—1000 中文字，加 1—2 张高信息密度图表。面试附件可稍长，但超过一页就失去“一页纸”的筛选效率。

一页纸研究模板

互动式 One-Pager 自检模板

结论型标题数据时间轴基准对照样本外成本容量风险边界可复现

逐项勾选。七项不能同时回答，说明项目证据链还不完整。

可直接复制以下结构：

标题：一句话写出结论，不写“基于机器学习的量化研究”
研究问题：市场机制 + 可证伪假设
数据：资产池、频率、区间、Point-in-Time 处理
方法：基准 → 核心模型 → 组合构建 → 成本模型
结果：样本外指标、置信区间、基准增量
机制：为何存在，谁提供收益，为什么尚未消失
风险：失效状态、容量、拥挤、数据与执行风险
下一步：最有信息价值的三个实验
复现：commit hash、配置、命令、随机种子

信息密度排序

内容	必须保留	应删除或下沉附录	面试官判断
可证伪假设	是	空泛行业背景	你是否像研究员
数据时间轴	是	数据供应商宣传	是否存在前视偏差
样本外增量	是	只报样本内最优值	是否真正泛化
成本后结果	是	毛收益曲线堆叠	是否可交易
失败案例	是	只挑最好年份	是否诚实且理解边界
参数明细	关键参数即可	全部网格搜索结果	是否过拟合
代码截图	否	截图不可复现	工程可信度低
复现命令	是	安装过程流水账	是否可审计

简历研究项目：STAR 不是四段流水账

量化简历中的 STAR 应压缩成两到四条 bullet：

• S／T：一句交代市场问题、数据规模和目标。
• A：写你的关键决策，不罗列工具名。
• R：报告样本外、成本后、相对基准的量化结果。
• Boundary：必要时补容量、风险或上线状态，防止指标失真。

弱描述：

使用 Python 和 XGBoost 开发量化选股策略，取得较好收益。

强描述：

基于 2016—2024 年 Point-in-Time A 股财务与行情数据构建质量—预期差模型；采用行业／市值中性化和 purged walk-forward 验证，在锁定的 2023—2024 年样本上实现 Rank IC 0.034，扣除双边 20 bps 成本后多空组合 Sharpe 1.31；容量压力测试显示交易额约束超过 15% ADV 后收益显著衰减。

强描述的每个数字都必须能在 notebook、结果文件或 commit 中定位。

四类量化简历模板

方向	第一屏重点	项目 bullet 强调	不应喧宾夺主	典型证据
学术 Research	研究问题、论文、方法	假设、识别、稳健性	工具清单	论文、复现实验、样本外结果
工程 Quant Dev	系统、性能、可靠性	延迟、吞吐、故障与测试	泛泛策略收益	benchmark、测试、架构图
策略 Quant Trader	市场机制、盈亏与风险	报价、执行、容量、回撤	复杂模型名	成本后 PnL、风险归因
管理／Lead	业务影响、团队和决策	资源取舍、流程、交付	个人编码细节过量	上线规模、团队产出、治理指标

学术方向 bullet 模板

提出【可证伪假设】，基于【数据与识别方法】排除【主要混淆因素】；在【预注册／锁定留出集】上相对【基准】提升【指标】，并通过【稳健性检验】确认结论在【边界】内成立。

工程方向 bullet 模板

重构【系统路径】，通过【数据布局／并发模型／算法】将【P50／P99 延迟或吞吐】从【基线】改善至【结果】；使用【sanitizer／压力测试／回放】验证【正确性不变量】，上线后【稳定性结果】。

策略方向 bullet 模板

识别【市场机制】并设计【信号／报价／执行策略】；在【Point-in-Time 样本】上经【walk-forward】验证，扣除【手续费、滑点、冲击】后实现【指标】，容量约为【规模】，主要失效条件为【状态】。

管理方向 bullet 模板

负责【团队／平台／资金规模】，将【模糊目标】拆解为【研究与工程里程碑】；通过【评审、数据治理、风险门禁】使【交付周期／事故率／策略规模】改善【量化结果】。

GitHub 仓库建设

一个面试仓库的目标是“可读、可跑、可验证”，而不是展示文件数量。

quant-research-project/
├── README.md                 # 研究结论、结果、复现入口
├── pyproject.toml            # 锁定依赖与工具配置
├── configs/
│   ├── baseline.yaml         # 冻结基线
│   └── holdout.yaml          # 锁定样本外配置
├── src/
│   ├── data/                 # 数据接口与 PIT 对齐
│   ├── features/             # 特征，只依赖过去信息
│   ├── portfolio/            # 组合与约束
│   └── evaluation/           # 指标、成本、归因
├── tests/
│   ├── test_no_leakage.py    # 时间轴断言
│   ├── test_costs.py         # 成本与成交约束
│   └── test_invariants.py    # 权重、现金和持仓不变量
├── reports/                  # 冻结图表与 One-Pager
└── .github/workflows/ci.yml  # lint、test、最小复现实验

README 首屏应包含：一句话结论、关键结果表、最小复现命令、数据限制、项目状态。不要让面试官先读 40 行安装说明。

测试、文档与 CI

最低测试集：

1. 时间泄漏测试：特征时间戳不得晚于决策时间。
2. 数据不变量：价格非负、代码唯一、复权逻辑可解释。
3. 组合不变量：权重和、杠杆、行业暴露、换手计算正确。
4. 成本测试：零成交无成本，买卖方向和印花税规则正确。
5. 确定性测试：固定种子与配置可复现核心结果。
6. 烟雾实验：CI 用小样本完成数据—信号—组合—报告闭环。

CI 不应下载私有大数据。准备一个经过脱敏的小型 fixture；README 说明完整数据因许可证限制不公开。

面试展示：Project Deep Dive

建议准备三个时长版本：

版本	结构	使用场景
30 秒	问题—动作—结果—边界	自我介绍、快速筛选
3 分钟	加数据、基准、验证和机制	常规项目介绍
20 分钟	加失败实验、代码、归因和路线图	Research Deep Dive

20 分钟 Deep Dive 的顺序：

1. 先给结论和决策价值。
2. 画数据可得时间轴。
3. 解释最朴素基准。
4. 展示你的关键增量。
5. 主动展示失败实验。
6. 报告样本外、成本、容量和风险。
7. 打开代码定位一个核心模块和一个测试。
8. 用下一步实验结束，不用“未来可继续优化”。

Code Review 准备

面试官可能随机打开文件。提前为以下问题准备答案：

• 为什么这个类存在，它的不变量是什么？
• 为什么选择 DataFrame／NumPy／C++，边界在哪里？
• 哪个函数最可能慢，你如何证明？
• 哪个测试最有价值，它曾捕获什么错误？
• 如何避免配置漂移和结果不可复现？
• 如果数据规模扩大 100 倍，哪个环节先失效？
• 哪段代码你会重写，为什么当时没重写？

“这是为了赶时间”可以是真实答案，但要补充当时约束、风险隔离和后续偿还计划。

数学原理

指标必须有分母和基准

“收益提高 20%”缺少基准。至少区分绝对变化和相对变化：

$$\Delta_{abs}=M_{new}-M_{base},\qquad \Delta_{rel}=\frac{M_{new}-M_{base}}{|M_{base}|}$$

若 Sharpe 从 1.0 提高到 1.2，可说绝对提高 0.2、相对提高 20%；但 Sharpe 的抽样误差可能很大，还需报告样本长度和置信度。

年化与有效样本量

日收益 Sharpe 常写为：

$$SR_{ann}=\sqrt{252}\frac{\bar r}{s_r}$$

当收益自相关时，简单乘 $\sqrt{252}$ 会高估有效样本量。项目材料至少说明频率、年化方式、是否重叠持有和是否扣除成本。

IC 的可信区间

若 IC 序列近似独立，均值标准误约为 $s_{IC}/\sqrt{T}$；存在自相关时应使用 HAC／Newey-West 标准误或 block bootstrap。只报告平均 IC 而不报告波动、覆盖期和换手，证据不完整。

容量不是单个 AUM 数字

冲击成本常用幂律近似：

$$Cost(Q)\approx \eta\sigma\left(\frac{Q}{ADV}\right)^\alpha,\quad 0<\alpha\le 1$$

One-Pager 应给“规模—成本后 Sharpe／收益”的曲线或情景表，而不是宣称一个精确容量上限。

Python实战

README 自动生成工具

PYTHON43 行 · 896 B

📄此处有展示代码43 行 · 896 B展开 ▼

from dataclasses import dataclass


@dataclass
class Project:
    name: str
    thesis: str
    results: list[str]
    stack: list[str]


FENCE = "`" * 3  # 避免在 Markdown 代码块里嵌套三反引号


def render_readme(project: Project) -> str:
    results = "\n".join(f"- {item}" for item in project.results)
    stack = " · ".join(f"`{item}`" for item in project.stack)
    return f"""# {project.name}

## Research Thesis
{project.thesis}

## Key Results
{results}

## Reproduce
{FENCE}bash
python -m pytest -q
python -m src.run_experiment --config configs/baseline.yaml
{FENCE}

## Tech Stack
{stack}
"""


project = Project(
    name="A-Share Factor Research",
    thesis="检验质量因子中性化后是否仍有截面预测能力。",
    results=["样本外 Rank IC：0.031", "成本后 Sharpe：1.24"],
    stack=["Python", "pandas", "pytest"],
)
print(render_readme(project))

▶ 点击展开可浏览运行结果

# A-Share Factor Research
    
    ## Research Thesis
    检验质量因子中性化后是否仍有截面预测能力。
    
    ## Key Results
    - 样本外 Rank IC：0.031
- 成本后 Sharpe：1.24
    
    ## Reproduce
    ```bash
    python -m pytest -q
    python -m src.run_experiment --config configs/baseline.yaml
    ```
    
    ## Tech Stack
    `Python` · `pandas` · `pytest`

生成器的价值不是替你写研究结论，而是强制每个仓库都包含同一证据骨架。脚本默认只打印，避免在 Pyodide 沙箱写文件；本地可用 Path.write_text() 输出。

简历 bullet 审计器

PYTHON30 行 · 1.0 KB

📄此处有展示代码30 行 · 1.0 KB展开 ▼

from __future__ import annotations

import re


WEAK_WORDS = {"参与", "负责相关", "取得较好", "熟悉", "了解"}
EVIDENCE_WORDS = {"样本外", "成本", "基准", "延迟", "吞吐", "容量", "置信区间"}


def audit_bullet(text: str) -> dict[str, object]:
    numbers = re.findall(r"\d+(?:\.\d+)?%?|\d+(?:\.\d+)?\s*(?:ms|us|bps)", text)
    weak = sorted(word for word in WEAK_WORDS if word in text)
    evidence = sorted(word for word in EVIDENCE_WORDS if word in text)
    return {
        "length": len(text),
        "numbers": numbers,
        "weak_words": weak,
        "evidence_terms": evidence,
        "pass": 55 <= len(text) <= 180 and bool(numbers) and not weak and len(evidence) >= 2,
    }


bullet = "使用机器学习开发选股策略，取得较好收益。"
print(audit_bullet(bullet))

better = (
    "基于 Point-in-Time A 股数据构建质量因子；在锁定样本外 Rank IC 0.031，"
    "扣除双边 20 bps 成本后 Sharpe 1.24，并完成容量压力测试。"
)
print(audit_bullet(better))

▶ 点击展开可浏览运行结果

{'length': 20, 'numbers': [], 'weak_words': ['取得较好'], 'evidence_terms': [], 'pass': False}
{'length': 88, 'numbers': ['0.031', '20', '1.24'], 'weak_words': [], 'evidence_terms': ['容量', '成本', '样本外'], 'pass': True}

规则检查不能判断研究是否真实，但能捕获“无数字、无样本外、无成本、弱动词”四类常见问题。

常见误区

误区	风险	修正方式
把项目包装理解为夸大收益	Deep Dive 很快穿帮	只陈述可定位证据
标题写“基于 ML 的研究”	看不出结论和价值	用一句可证伪结论
只展示最好回测曲线	暴露选择性报告	展示基准、样本外和失败状态
简历塞满 Python／SQL 工具名	只有手段，没有判断	写关键决策和量化结果
结果不扣成本	策略不可交易	明确手续费、滑点、冲击与税
GitHub 只有 notebook	难测试、难复现	拆 src、tests、configs、reports
README 先写长安装说明	首屏没有研究价值	先结论、结果、复现入口
上传无权公开的数据	法务与职业风险	提供脱敏 fixture 和数据说明
CI 依赖私有环境	面试官无法验证	用小样本烟雾实验
bullet 写团队结果但不写个人动作	无法评估贡献	明确“我决定／实现／验证”
所有指标保留三位小数	制造虚假精确	与样本误差匹配精度
被问失败实验时说“没有”	暗示研究不充分	准备最有信息价值的失败案例

诚信底线

不要虚构公司、资金规模、收益、上线状态、论文或 GitHub commit。若项目使用模拟数据，应在标题附近明确标注。若受 NDA 限制，用结构化的范围描述替代敏感数字，不要暗示不存在的成绩。

小测验

题目 1

一页纸研究应该控制在多少字以内？
对于求职附件中的中文 One-Pager，最佳经验范围是什么？

• AA. 不超过 200 字，越短越专业
• BB. 约 600—1000 中文字，整体保持一页
• CC. 至少 3000 字，方法越完整越好
• DD. 完全没有限制，只看排版

💡查看答案与解析展开 ▼

正确答案：B

本章正文建议：中文 One-Pager 正文控制在 600—1000 字，配 1—2 张高信息密度图表，整体保持一页（英文约 400—700 词）。它要在研究问题、数据、方法、结果、机制、风险、复现七个维度上压缩证据，篇幅既要够交代样本外区间、成本与容量边界，又要保证面试官 30 秒能读完。A 错：200 字无法交代验证、风险和复现，显得证据不足。C 错：3000 字已是短报告，失去“一页纸”的筛选效率。D 错：一页与高信息密度是明确约束，不能只看排版。

英文 One-Pager 如何调整？

可控制在约 400—700 个英文词，仍以一页为硬约束。图表标题必须能独立表达结论，正文避免重复读图。

实战练习

案例 1｜截面质量—预期差因子 One-Pager

标题：质量—预期差组合在行业／市值中性化后仍保留稳定的 A 股截面预测能力

研究问题：盈利质量与分析师预期修正能否提供互补信息，还是只是小市值和行业暴露的替代变量？

数据：2016—2024 年 A 股日行情、财务公告和分析师一致预期；按公告时间构建 Point-in-Time 快照，排除上市不足 120 日、ST、长期停牌和交易日不可成交标的。2016—2022 年研究，2023—2024 年锁定留出。

方法：质量因子由应计、现金流和盈利稳定性组成；预期差由一致预期的 20 日修正构成。截面 winsorize、标准化后做行业与对数市值中性化，以单因子、等权复合和线性正则模型为基准。

结果：锁定样本 Rank IC 为 0.034，ICIR 为 0.71；月频十分组多空组合扣除双边 20 bps 后年化 Sharpe 为 1.31。相比纯质量基准，复合模型 Sharpe 增量为 0.27。

机制：质量过滤降低“预期上修但兑现能力弱”的假阳性，预期差为慢频财务信息提供更新。收益主要来自中等流动性股票，而非最小市值组。

风险与容量：财报季换手和拥挤度上升；当组合参与率超过 15% ADV 时冲击明显。2024 年下半年在高波动小盘反弹阶段相对弱。

下一步：加入公告文本意外度；对预期修正做分析师覆盖偏差校正；用逐笔模拟重估财报季成交成本。

复现：commit 8f3c2d1，configs/holdout.yaml，固定随机种子 42。

简历 STAR 描述：

针对 A 股财务因子暴露漂移问题，构建 Point-in-Time 质量—预期差模型并实施行业／市值中性化；在锁定的 2023—2024 年样本上实现 Rank IC 0.034，扣除双边 20 bps 后多空 Sharpe 1.31，容量测试识别出 15% ADV 后的显著冲击拐点。

案例 2｜日内订单簿失衡 One-Pager

标题：多档订单簿失衡仅在短时高撤单环境中具有可交易预测力

研究问题：五档 Order Flow Imbalance 对未来 1—10 秒中间价变化的预测，是否在延迟和手续费后仍可交易？

数据：三个月逐笔委托与成交，纳秒时间戳统一到交易所序列；剔除开收盘集合竞价、熔断和数据断档。按交易日 walk-forward，禁止随机切分相邻 tick。

方法：构造一至五档 OFI、队列不平衡、撤单强度和短期波动；以中间价随机游走、单档失衡和逻辑回归为基准。标签为未来 1、3、5、10 秒 mid-price move，特征计算截止决策时刻。

结果：五档模型在 3 秒标签上的样本外 AUC 为 0.557，高于单档基准 0.019；加入 80 微秒决策延迟和完整费用后，仅最高置信度 5% 信号具有正期望，日均机会约 140 次。

机制：预测力集中于一侧撤单加速且对侧队列稳定的状态，单纯静态深度失衡容易被快速补单反转。

风险与容量：排队位置估计误差是最大不确定性；新闻时段预测准确率上升但成交质量恶化。策略容量受最优档可成交量限制。

下一步：建立 queue-reactive 成交模型；按消息类型做消融；评估跨场所领先—滞后。

复现：公开仓库只含合成盘口 fixture，真实数据受许可证限制；核心测试覆盖消息回放确定性与时间泄漏。

简历 STAR 描述：

基于逐笔委托重建五档订单簿并研究 1—10 秒价格响应；通过按交易日 walk-forward 与 80 微秒延迟回放，将五档 OFI 在 3 秒标签上的样本外 AUC 提升至 0.557，并识别出仅最高置信度 5% 信号在完整费用后保持正期望。

案例 3｜可复现研究平台 One-Pager

标题：配置驱动与时间轴测试把因子复现周期从两天缩短到 40 分钟

问题：团队 notebook 分散、数据版本不一致，同一因子由不同研究员复现时结果偏差可达 15%。

目标：建立最小研究平台，使数据快照、特征、组合、成本与报告可由单一配置复现，并自动阻断时间泄漏。

方案：将 notebook 中稳定逻辑迁入 src/；用 YAML 冻结实验；结果记录数据版本、Git commit 和环境 hash；CI 在脱敏 fixture 上运行时间轴、权重、成本和确定性测试。

结果：选取 12 个历史因子回放，复现通过率从 58% 提升到 100%；标准实验从人工两天缩短到 40 分钟；时间轴断言在上线前发现 3 处公告日回填问题。

工程取舍：没有自研调度系统，复用现有 CI 和对象存储；大数据计算仍走内部集群，本地 fixture 只验证语义正确性。

风险：fixture 不能覆盖真实数据的全部长尾；配置过多可能造成实验矩阵失控，因此为正式结果设置冻结目录和 reviewer 门禁。

下一步：增加数据 schema 演进检查、benchmark regression 和自动 One-Pager 产出。

复现：公开 demo 包含合成数据、8 个核心测试和一条端到端 smoke workflow。

简历 STAR 描述：

针对量化研究结果不可复现问题，搭建配置驱动的因子研究流水线与 CI 时间轴测试；在 12 个历史因子上将复现通过率从 58% 提升至 100%，将标准实验周期由两天降至 40 分钟，并在上线前捕获 3 处财务公告回填泄漏。

Project Deep Dive 模拟题

1. 你的标签为什么这样定义？改变持有期后结论如何变化？
2. 哪个数据字段最容易泄漏？请打开对应测试。
3. 你的基准为什么公平？是否对复杂模型给予更多调参预算？
4. 报告的最好结果经历了多少次试验？如何控制多重检验？
5. 成本模型中最脆弱的参数是什么？翻倍后策略是否仍成立？
6. 哪个市场状态下失效最明显？这是否推翻原始机制？
7. 如果只能保留一张图，你保留哪张，为什么？
8. 哪一项结果由你个人完成，哪一项依赖团队？
9. 代码规模扩大十倍后，哪个模块先需要重构？
10. 如果明天上线，你拒绝上线的三个条件是什么？

发布前 15 分钟检查

项目	问题	通过标准
简历	每个数字能否定位	有结果文件、图表或 commit
One-Pager	首屏能否看懂结论	标题、结果、边界完整
GitHub	新环境能否运行	README 命令通过
数据	是否有发布权限	公开、合成或脱敏且有说明
代码	随机打开是否可讲	核心模块有不变量和测试
展示	30 秒／3 分钟是否演练	不超时且结论一致
诚信	是否暗示未发生的上线或业绩	措辞准确、边界明确

延伸阅读

1. William Zinsser，On Writing Well：压缩表达、删除空话和提高信息密度。
2. Chip Heath、Dan Heath，Made to Stick：让结论具体、可信且容易记住。
3. GitHub Docs，About READMEs 与 GitHub Actions：仓库入口和持续集成实践。
4. Google Engineering Practices，Code Review Developer Guide：代码评审的可读性与变更边界。
5. Marcos López de Prado，Advances in Financial Machine Learning：purged cross-validation、回测过拟合与研究验证。
6. Howard Marks，投资备忘录写作：从事实、判断、风险到决策的结构化表达。

本章要点

1. 项目包装的本质是压缩证据，不是夸大收益或堆砌工具名。
2. One-Pager 应在一页、约 600—1000 中文字内回答假设、数据、方法、结果、机制、风险与复现。
3. 简历 bullet 要用 STAR 压缩问题、个人动作和量化结果，并明确样本外、成本与容量边界。
4. GitHub 仓库至少应具备清晰 README、模块化源码、测试、冻结配置、结果报告和最小 CI。
5. 学术、工程、策略和管理方向应选择不同证据，不要用同一份项目描述覆盖所有岗位。
6. Deep Dive 应主动展示失败实验、代码测试和失效状态，以证明研究可信度。
7. 所有公司、数据、业绩、上线状态和个人贡献必须真实、可定位、可解释。