hunter-community CLAUDE.md

CLAUDE.md — hunter-community

本文件是 Claude Code 在本仓库工作时会自动读取的项目指令。

---

铁律:严禁 mock 兜底 · 空的比假的好

量化 / 指标 / 因子 / 回测 / 评分 类代码,任何用户会看到或送给 LLM 分析的数字都必须是真算出来的。算不出就显示 — 并注明原因。

严禁的模式

• Object.assign(mockDefault, realResult) — 真数据缺字段时假数据会露出
• realValue || 0 / realValue ?? 0.5 — 0.00 看起来像个结论
• 渲染层直接写常量或伪造公式(基准 = 1 + i*0.005、超额 = ann_ret - 0.062、相似度 = [87,62,54][i] 之类)
• API 转换层挂 _mock / metrics_mock 字段 — 修了展示层不算完,上游会继续注入
• 把不确定真假的指标送进 askHunter / LLM — 模型会认真点评根本不存在的业绩

Why

2026-08-18 事故:「全能蓝筹」3 年回测同屏出现「年化 −1.2%」与「信息比率 0.98 / 月度胜率 62%」—— 后两个是 backtest.html 里写死的常量,因为后端 _calc_metrics() 从来没算过 ir / win_rate,Object.assign 用 mock 补上了。全量排查后共发现 4 个页面 8 处假数据(20 个因子的 60 个指标、6 个官方策略 metrics、净值曲线、基准直线、因子归因公式…),其中最糟的是 askHunter 把假指标发给 LLM 分析。

相关提交(按顺序读):

05c8d3d fix(quant): 回测不再用假数字冒充真结果 (_17 步1-3)
fefcb6c fix(quant): 清掉全部写死的假数据 (_17 全量排查)
13a6f8f feat(quant): 接真指数日线 + 实现回测基准
863d2d1 feat(quant): 指数成分股走代理拉取 + seed 真数据
ba62a96 fix(quant): 补完 _17 剩下四条
9335fe3 fix(quant): 修白屏 —— 漏了两处读取方与三类语法坑

演示模式不是借口 —— 要 demo 数据就跑一次真回测把结果存下来当样例,不要在渲染层编。

落地方法

改动前 —— 先全量 grep,把所有假数据来源列一遍再动手:

grep -rn "mock\|_mock\|Object.assign\|writeDefault\|\|\| 0" apps/web/public apps/api/app

修一处后要再全量排查一次 —— 上游 API 转换层常常在真数据上重新挂假字段。前科:先修了 backtest.html 的 mock,但 app.js:197 在 API 转换时又挂了 metrics_mock,真数据流下来被再次污染。

删/改字段名要 grep 所有读取方,不能只搜字段名本身:

• ❌ 只搜 metrics_mock
• ✅ 还要搜 .metrics. 、?.metrics、s.metrics 等直接属性访问
• 前科:白屏事故就是漏了 s.metrics.ann_ret 这种直接读取

前端验证不能只靠 HTTP 200 / node --check / curl —— 这些都测不到内联 <script> 里的错。用 apps/web/public/strategies/render_check.js,在 node 的 vm 里真跑一遍页面脚本,假 document / localStorage / fetch 兜住。

触发词

出现下列任一词的改动,自动触发本铁律:

回测 · 指标 · 因子 · 成分股 · 换手率 · 换仓频率 · 基准 · 超额 · IR · 信息比率 · 胜率 · 净值 · 归因 · 持仓 · 相似度 · 评分 · metrics · sharpe · ann_ret

---

详细文档

完整问题清单与实施记录(在 agentpit repo 内,不在本仓):

• agentpit/doc/开源hunter-community/01详细工作目录/11量化策略/17_20260818_回测可信度问题与修复方案.md
• agentpit/doc/开源hunter-community/01详细工作目录/11量化策略/18_20260818_回测可信度修复实施记录.md