🇨🇳 简体中文
🇺🇸 English
🇯🇵 日本語

文档更新标准操作流程 (SOP)

版本: 1.0.0 生效日期: 2025-11-18 适用范围: Fire 量化交易系统所有架构文档

目的

本 SOP 定义了在 Fire 项目中更新架构文档的标准流程,确保文档与代码保持同步,维持高质量和一致性。

更新触发器

以下情况 必须 更新相应的架构文档:

1. 架构变更 (Architecture Changes)

触发条件:

需要更新的文档:

2. 领域模型变更 (Domain Model Changes)

触发条件:

需要更新的文档:

3. 策略变更 (Strategy Changes)

触发条件:

需要更新的文档:

4. 开发实践变更 (Development Practice Changes)

触发条件:

需要更新的文档:

5. API 变更 (API Changes)

触发条件:

需要更新的文档:

更新流程

Step 1: 识别受影响的文档

操作: 根据代码变更,确定需要更新的文档

工具: 使用 @doc: 标记快速定位

# 查找模块对应的文档
grep -r "@doc:" backend/core/your_module/

输出: 受影响的文档列表

Step 2: 使用 /archive-spec 自动更新

前提条件:

  1. 功能分支已合并到 main
  2. spec.md 和 plan.md 已完成

操作:

# Dry-run 模式预览变更
python3 .claude/commands/archive-spec.py --dry-run --feature-dir specs/YOUR_FEATURE

# 执行实际更新
python3 .claude/commands/archive-spec.py --feature-dir specs/YOUR_FEATURE

输出:

Step 3: 审查自动更新结果

检查项:

  1. 内容准确性: 文档描述是否与实际代码一致
  2. 完整性: 新增的接口、组件是否都已记录
  3. 格式规范: Markdown 语法是否正确
  4. 代码块合规性: 检查警告中的代码块违规

操作:

# 查看变更
git diff docs/

# 检查报告
cat .tmp/archive-report.json | jq '.warnings'

Step 4: 手动补充和修正

常见需要手动补充的内容:

  1. 数据流图: 复杂的数据流需要绘制 Mermaid 图
  2. 配置说明: 新增的配置项和环境变量
  3. 使用示例: 典型的使用场景和代码示例
  4. 注意事项: 重要的约束和最佳实践

禁止的内容 (遵循 FR-025):

允许的代码块:

Step 5: 验证文档质量

必须检查:

# 1. 未来语言检测
grep -r "将要\|将会\|计划\|未来" docs/architecture/
# 应返回 0 结果

# 2. 禁止词汇检测
grep -r "高性能\|可扩展\|灵活\|鲁棒" docs/architecture/
# 应返回 0 结果

# 3. Markdown 语法验证
markdownlint docs/**/*.md

# 4. 链接检查
markdown-link-check docs/**/*.md

可选检查:

# 文件大小检查
find docs/architecture/ -name "*.md" -exec wc -c {} + | \
  awk '{if($1 > 0) {sum+=$1; count++}} END {print "平均:", sum/count/1024, "KB"}'
# 应 ≥12KB

Step 6: 提交文档更新

Commit 消息格式:

docs(feature-id): 更新架构文档

归档功能 {feature-id} 的架构变更到文档系统

更新的文档:
- docs/architecture/module-name.md: 新增组件 XYZ
- docs/domain/entity-name.md: 更新领域模型

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

提交范围:

质量标准

更新后的文档必须满足:

内容标准

结构标准

代码块标准 (FR-025)

工具和资源

自动化工具

验证工具

参考文档

常见问题

Q1: 什么时候必须运行 /archive-spec?

A: 功能分支合并到 main 后,且该功能修改了代码架构。

Q2: 如果 /archive-spec 报告警告怎么办?

A: 查看 .tmp/archive-report.json 中的 warnings,手动修正文档中的问题。

Q3: 代码块应该展示什么内容?

A: 仅展示如何使用和如何扩展,不展示内部实现。参考 FR-025 原则。

Q4: 文档数量超过 35 个怎么办?

A:

  1. 合并相关文档 (如策略文档)
  2. 归档旧版本文档
  3. 移除重复内容

Q5: 如何验证文档与代码一致?

A: /archive-spec 内置 verify_code_existence() 函数,会检查文档中提到的类和文件是否存在。

变更历史

版本 日期 变更内容 作者
1.0.0 2025-11-18 初始版本 Claude Code

附录 A: 更新触发器快查表

5 类触发器

🏗️ 架构变更: 新模块、模块职责变更、新技术/库、依赖变更、配置变更 📊 领域模型变更: 新实体、字段变更、业务规则、领域事件、值对象 🎯 策略变更: 新策略、策略接口、元数据、注册机制、指标 🛠️ 开发实践变更: 新工具、CI/CD、测试策略、代码规范、环境设置 🔌 API 变更: REST 端点、WebSocket、数据契约、认证、版本控制

快速决策

变更类型 优先级 更新方法 受影响文档
新模块 🔴 高 /archive-spec + 手动 架构文档
新策略 🔴 高 /archive-spec + 手动 策略文档
API 端点 🟡 中 手动 模块文档
领域模型 🔴 高 /archive-spec + 手动 领域文档
CI/CD 变更 🟡 中 手动 contributing.md
代码重构 ⚪ 无 无需更新 N/A

详细触发器说明参见本 SOP 的”更新触发器”章节。

附录 B: @doc: 注释快速指南

语法

# @doc: path/to/document.md

何时添加

放置位置

  1. 优先级: engine.py > manager.py > base.py > __init__.py
  2. 位置: 模块文档字符串后,第一个类/函数前
  3. 路径: 相对于 docs/ 目录

常见路径

architecture/{module-name}.md    # 模块架构
strategies/{strategy-name}.md    # 策略详情
domain/{entity-name}.md          # 领域模型

验证

# 检查注释
./.claude/scripts/check-doc-annotations.sh

# 测试扫描
python3 .claude/commands/archive-spec.py --dry-run --feature-dir specs/YOUR_FEATURE

附录 C: PR 审查快速清单

代码变更

文档更新

文档质量

验证命令

# 未来语言
grep -rn "将要\|计划\|未来" docs/architecture/

# 禁止词汇
grep -rn "高性能\|灵活\|鲁棒" docs/architecture/

# Markdown
markdownlint docs/**/*.md

# 链接
markdown-link-check docs/**/*.md

审查结果模板

## 文档审查结果
✅ 通过: @doc: 注释完整、无未来语言、Markdown 正确
⚠️ 需改进: [具体问题]
❌ 必须修复: [阻塞问题]

附录 D: 更新检查清单

功能完成后,逐项检查:

文档所有者: 架构团队 审查周期: 每季度 联系方式: 参考项目 README.md