10cg 架构文档更新器
快速开始
何时使用？
✅ 使用场景:
- 完成功能开发后同步架构文档
- 新建模块（≥5个文件）需要创建架构文档
- 重构后更新文档结构
- 代码变更需要反映到文档中
❌ 不使用场景:
- 临时实验性代码
- 配置文件修改
- 文档本身的更新
快速示例
# 场景: 新增了一个 provider_factory.py 文件
# 1. 找到归属文档
find backend/llm_provider -name "*ARCHITECTURE*.md"
# 输出: LLM_PROVIDER_ARCHITECTURE.md
# 2. 更新文件列表
# 在文档中添加:
- `provider_factory.py` - 提供者工厂 ⭐新增
# 3. 更新统计和版本
# 总文件数: 8个 → 9个
# 版本: 1.0.0 → 1.0.1
更多详细示例: EXAMPLES.md
核心原则
使用本 Skill 前，请确保理解：
- 三层架构体系 (L0/L1/L2) → 参考
@.claude/skills/arch-common/SKILL.md - 命名规范: 代码目录用大写，docs/目录用小写 → 参考
@.claude/skills/arch-common/SKILL.md - 三步流程: 生成TREE → 创建INDEX → 验证（不得跳过）
- 100%覆盖: 所有代码文件必须在文档中列出
- 使用工具生成数据: 禁止手动估算统计数据
共享配置: @.claude/skills/arch-common/SKILL.md
共享配置
三层架构体系 (L0/L1/L2)、命名规范、模块入口表等共享定义请参考：
@.claude/skills/arch-common/SKILL.md
标准化三步流程
第1步: 生成TREE（强制）
python scripts/architecture/python/arch_tree_generate.py --target [端名]
# 示例
python scripts/architecture/python/arch_tree_generate.py --target mobile
python scripts/architecture/python/arch_tree_generate.py --target backend
输出: [端根目录]/ARCHITECTURE_DOCS_TREE.md
强制要求:
- ❌ 绝对禁止跳过 - TREE是权威数据源
- ❌ 禁止手动估算 - 所有统计必须来自此工具
第2步: 创建INDEX（基于TREE）
数据来源:
- ✅ 必须读取TREE文档
- ✅ 必须使用标准模板 → TEMPLATES.md
- ❌ 禁止凭经验编写
第3步: 验证（强制）
./scripts/architecture/arch_check.sh [目标路径]
# 发现问题时自动修复
./scripts/architecture/arch_check.sh [目标路径] fix
详细验证方法: VALIDATION.md
常用场景
场景1: 新增代码文件
- 找到归属文档:
find [目录] -name "*ARCHITECTURE*.md" - 更新文件列表:
- new_file.py - [功能描述] ⭐新增 - 更新统计和版本
场景2: 创建新模块（≥5个文件）
- 统计:
find [模块] -name "*.py" | wc -l - 选择模板（≥10用L1，5-10用L2）
- 创建:
[模块]/[模块名]_ARCHITECTURE.md - 更新父文档和索引
场景3: 删除代码文件
- 查找:
grep -r "file.py" **/*ARCHITECTURE*.md - 标记:
~~- file.py - [功能]~~ ❌已删除 - 更新统计
场景4: 重构模块
- 记录变更（移动/删除/新增）
- 更新文件架构（标记变更）
- 更新依赖关系
- 添加设计决策
详细步骤: EXAMPLES.md
使用场景决策矩阵
| 场景 | 触发条件 | 操作 | 优先级 |
|---|---|---|---|
| 新增代码文件 | 创建.py/.js/.dart等 | 更新对应架构文档 | 高 |
| 新建模块 | ≥5个文件 | 创建独立架构文档 | 高 |
| 删除文件 | 移除代码 | 标记❌删除 | 中 |
| 重构模块 | 结构变化 | 更新架构和依赖 | 高 |
| 修改依赖 | 引入/移除 | 更新依赖关系 | 高 |
| 小改动 | <3个文件 | 批量处理 | 低 |
最佳实践
及时更新
✅ 好的做法: 完成功能 → 立即更新文档 → 一起提交
❌ 不好的做法: 完成多个功能 → 批量更新文档
100%覆盖
✅ 必须做到:
- 所有代码文件都在架构文档中列出
- 每个文件都有功能描述
- 新增标记⭐，删除标记❌
保持简洁
- 文件功能描述: ≤10字
- 核心价值: ≤30字
- 设计决策: 简要理由
快速检查清单
执行前
- 理解三层架构体系（L0/L1/L2）
- 了解命名规范
执行中
- 找到正确的归属文档
- 使用标准模板
- 标记文件变更（⭐新增，❌删除）
- 更新统计数据和版本号
执行后
- 验证100%文件覆盖
- 运行验证工具
- 与代码一起提交
相关文档
Skill 文档
- 详细示例: EXAMPLES.md
- 模板集合: TEMPLATES.md
- 验证工具: VALIDATION.md
- 共享配置:
@.claude/skills/arch-common/SKILL.md
相关 Skills
- arch-search - 搜索架构文档
- arch-common - 共享配置
规范文档
- 共享配置:
@.claude/skills/arch-common/SKILL.md - 通用方法论:
@standards/core/architecture/README.md - 脚本配置:
scripts/architecture/python/config.yaml
最后更新: 2025-12-28 规范版本: v4.5 Skill 版本: 2.3.0