新项目的头两天：不是写代码，是写文档

新项目的前两天，最自然的冲动是”写代码”。但这个项目的前 26 个 commit 里，20 个是文档。

不是拖延，是先把”代码应该长什么样”写清楚。

两天干了什么

06-04
  14:28  保存当前本地变更
  17:08  归档历史项目备份
  17:11  添加 gitignore
  17:26  模块地图 + 运行手册
  23:23  变更日志 + 架构决策记录（ADR）
  23:39  模块指南 × 3（swing/common/API）
  23:56  模块指南 × 2（tv/exchange）

06-05
  00:08  核心模块指南
  00:28  方向策略模块指南
  00:36  推荐模块指南
  09:29  独立推荐器 + 告警模块指南
  09:49  告警操作模块指南
  09:58  监控模块指南
  10:08  归因 + pump sniper 模块指南
  11:56  feat: dry-run 模式 ← 第一个功能代码
  12:45  部署手册
  13:05  根目录地图
  13:11  编码审计
  14:21  Harness 工程指南

26 个 commit，20 个文档，1 个功能代码（dry-run）。

为什么先写文档

这个项目有 20+ 个模块，横跨推荐、交易执行、风控、监控、告警、归因。如果上来就写代码：

模块边界会在开发中反复调整
新人（包括几个月后的自己）看不懂代码组织
架构决策没有记录，后面改不动的时候忘了当初为什么这么设计

文档不是给产品经理看的——是给两个月后深夜排障的自己看的。

哪些文档是不可跳过的

1. 模块地图

src/
├── smart-trade-swing/  ← 波段交易核心
├── sta-common/         ← 公共库
├── sta-api3c/          ← 第三方 API 封装
├── sta-exchange/        ← 交易所 API
├── sta-tv/             ← TV 信号对接
├── smart-trade/        ← 推荐引擎
├── alert_recommend/    ← 告警推荐
├── alert_ops/          ← 告警运维
├── monitor/            ← 监控
├── attribution/        ← 归因分析
└── pump_sniper/        ← 极速抢单

每个模块一句话说清职责。模块边界不清楚 = 会把推荐逻辑写进交易引擎里。

2. 架构决策记录（ADR）

记录关键的架构选择及理由：

决策	理由
交易执行不走消息队列	延迟不可接受，直接 RPC
风控和策略分离	策略只负责信号，风控负责准入
用 Redis 做状态存储	需要重启恢复，不需要持久化历史

ADR 的价值在于：六个月后你想改架构，知道当初为什么不那么设计。

3. 运行手册（Runbook）

不是”怎么部署”，是”出问题时查什么”：

策略不开仓 → 检查 Redis 里的信号状态
持仓不匹配 → 检查交易所 API 的仓位快照
监控报警 → 按优先级排查清单

元结构映射：广告系统的项目启动

启动广告系统时一样的流程：先写模块边界文档（检索/排序/计费/数据），再写 ADR（为什么倒排索引选这个压缩算法，为什么正排分 L1/L2/L3 三层），然后才是代码。

文档先于代码不是慢，是不给自己挖坑。

一句话

第一天写代码的人两个月后要花两天读代码。第一天写文档的人两个月后花两分钟查文档。