design-sync

DESIGN.md 同步检查

验证 DESIGN.md 是否准确反映当前代码库架构。

当前目录结构

!ls -la internal/ | grep '^d'

DESIGN.md 目录部分

!sed -n '/^## Directory Structure/,/^## /p' DESIGN.md | head -50

DESIGN.md 中的关键文件引用

!grep -oE 'internal/[a-z/]+\.go:[0-9]+-[0-9]+' DESIGN.md | sort -u

自上次更新 DESIGN.md 以来的近期更改

!git log --since="$(git log -1 --format=%ai DESIGN.md 2>/dev/null || echo '1 month ago')" --name-only --oneline -- 'internal/**/*.go' | grep -E '^internal/' | sort -u

当前包导入图

!go list -f '{{.ImportPath}}: {{join .Imports ", "}}' ./internal/... 2>/dev/null | grep 'lazyworktree/internal' | head -30

DESIGN.md 元数据

!head -20 DESIGN.md | grep -E '(Last updated|Version)'

文档记录的主题字段与实际字段

!echo "=== Documented theme fields ===" && grep -A 20 'type Theme struct' DESIGN.md | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l && echo "=== Actual theme fields ===" && grep -A 30 'type Theme struct' internal/app/theme.go | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l

---

分析说明

根据以上数据，检查以下内容：

1. 目录结构偏差

• internal/ 下是否有 DESIGN.md 中未记录的新目录？
• 文档中记录的目录是否已删除或重命名？
• 对比实际目录列表与文档中的结构部分

2. 关键文件引用

• 提取 DESIGN.md 中所有 file:line-range 引用（例如 app.go:77-210）
• 对每个引用：
  • 确认该路径下的文件仍然存在
  • 检查行号是否仍指向文档中所述的代码部分
  • 如果重构导致行号变动，报告新的正确行号
• 报告任何失效引用或显著偏差

3. 近期架构更改

• 检查自上次更新 DESIGN.md 以来发生变更的文件
• 判断这些更改是否影响文档记录的抽象：
  • BubbleTea Model/Update/View 模式
  • Git 服务信号量实现
  • 屏幕管理器堆栈
  • 主题系统
  • 配置级联
• 标记可能需要更新 DESIGN.md 的关键文件变更

4. 导入图一致性

• 将当前包导入与文档记录的依赖图进行对比
• 标记 DESIGN.md 未提及的新增内部依赖
• 标记文档中仍记录但已移除的依赖
• 检查是否存在违反文档所述模式的循环依赖

5. 主题系统准确性

• 确认文档与实际代码中的主题字段数量是否一致
• 如果数量不同，指出文档中缺少哪些字段

6. 过时检查

• 如果 DESIGN.md 超过 90 天未更新，请报告
• 如果结构发生变化，建议更新“Last updated”日期

报告格式

按以下格式输出：

✅ 最新且准确

• 列出仍然准确且同步的具体方面

⚠️ 需要少量更新

• 行号修正（例如 app.go:77-210 → app.go:87-220）
• 需要添加到文档的新目录
• 导入图的轻微变化
• 主题字段数量差异

🔴 需要重大更新

• 未记录的新抽象或组件
• 已移除或发生重大变化的文档记录组件
• 已变化的架构决策
• 失效的文件引用

📝 建议操作

1. 指出需要修改的具体内容及 DESIGN.md 行号
2. 建议新增的章节（附内容大纲）
3. 建议删除或重写的章节
4. 所有文件引用的行号修正

---

使用工作流

何时调用 /design-sync

主动触发（提交前）：

• 在 internal/ 下添加新包
• 重构关键文件（app.go、service.go、model.go 等）
• 更改架构模式（Model-Update-View、信号量等）
• 添加新的屏幕类型或主题字段
• 修改配置级联或优先级规则

定期触发：

• 每季度进行维护审查
• 主要版本发布前
• 合并大型架构 PR 后
• DESIGN.md 感觉已过时时

推荐工作流

# 1. Make architectural changes

# 2. Run design-sync skill
/design-sync

# 3. Review output for needed updates

# 4. Update DESIGN.md based on recommendations

# 5. Update "Last updated" date in DESIGN.md

# 6. Re-run to verify
/design-sync  # Should now show ✅ Up to Date

# 7. Commit changes together