# Contributing

文档优先是本仓库的核心原则。任何改动都必须明确对应的文档章节，并在偏离前先更新文档。

## 必读文档
在编写代码或提出 Issue 之前，请先阅读：
- `docs/ARCHITECTURE_DESIGN.md`
- `docs/IMPLEMENTATION_PLAN.md`
- `docs/CODE_DELIVERY_PLAN.md`
- （如与策略细节相关）`docs/PRD_Pacifica_DeltaNeutral_Scalping.md`

## 工作流程
1. **任务定义**：创建 Issue/任务时写明影响范围，并引用上述文档的章节或行号；若计划修改架构或里程碑，先提交文档更新。  
2. **开发前检查**：确认本次改动与现有文档一致；若发现不一致，优先更新文档并在 PR 中说明。  
3. **开发执行**：遵循 `docs/CODE_DELIVERY_PLAN.md` 的阶段排布与质量要求，必要时补充自测或回测记录。  
4. **提交前自检**：
   - 运行 `pnpm lint` 与相关测试/回测；
   - 更新或新增文档（如有变更）；
   - 整理引用的文档章节，准备填写 PR 模板。  
5. **PR 要求**：
   - 在描述中列出引用的文档章节（格式示例：`docs/ARCHITECTURE_DESIGN.md#L40`）；
   - 若文档已更新，说明更新原因与影响范围；
   - 附带测试/回测结果；
   - 勾选 PR 模板中的所有检查项。

## 文档更新规范
- 修改架构、计划或流程时，务必同步更新对应文档，并在文档底部添加“Revision History”。
- 若新增模块，请在 `docs/ARCHITECTURE_DESIGN.md` 中描述设计，并在 `docs/CODE_DELIVERY_PLAN.md` 中加入执行计划。
- 避免在代码中引入与文档不一致的行为；若为临时方案，需注明 TODO 并附引用。

## 沟通节奏
- 建议每周例行同步一次文档与实现差异；
- 重大决策需在 Issue/PR 中讨论并记录，确保历史可追溯；
- 所有讨论结论需回写到文档对应位置。

感谢遵守文档优先的协作方式，让策略实现始终与设计保持一致。