typed-holes-refactor

类型洞重构

使用「通过类型洞进行设计」元框架系统地重构代码库：将架构未知项视为类型洞，通过测试驱动验证迭代解决，并在依赖图中传播约束。

核心工作流

阶段 0：发现类型洞并进行设置

1. 创建安全的工作分支：

git checkout -b refactor/typed-holes-v1
# CRITICAL: Never work in main, never touch .beads/ in main

2. 分析当前状态并识别类型洞：

python scripts/discover_holes.py
# Creates REFACTOR_IR.md with hole catalog

重构 IR 会记录：

• 当前状态类型洞：当前系统有哪些未知项？
• 重构类型洞：要达到理想状态，需要解决哪些问题？
• 约束：哪些内容必须保留、改进或维持？
• 依赖关系：哪些类型洞会阻碍其他类型洞？

3. 编写基线特征测试：

创建 tests/characterization/，以捕获当前行为的确切表现：

# tests/characterization/test_current_behavior.py
def test_api_contracts():
    """All public APIs must behave identically post-refactor"""
    for endpoint in discover_public_apis():
        old_result = run_current(endpoint, test_inputs)
        save_baseline(endpoint, old_result)

def test_performance_baselines():
    """Record current performance - don't regress"""
    baselines = measure_all_operations()
    save_json("baselines.json", baselines)

在 main 分支上运行测试——它们应该全部通过。这些测试是你的安全网。

阶段 1-N：迭代解决类型洞

按依赖顺序处理每个类型洞：

1. 选择下一个已就绪的类型洞：

python scripts/next_hole.py
# Shows holes whose dependencies are resolved

2. 首先编写验证测试（测试驱动）：

# tests/refactor/test_h{N}_resolution.py
def test_h{N}_resolved():
    """Define what 'resolved correctly' means"""
    # This should FAIL initially
    assert desired_state_achieved()

def test_h{N}_equivalence():
    """Ensure no behavioral regressions"""
    old_behavior = load_baseline()
    new_behavior = run_refactored()
    assert old_behavior == new_behavior

3. 实施解决方案：

• 重构代码，使测试通过
• 确保特征测试持续通过
• 使用清晰的提交说明，逐步提交

4. 验证解决方案：

python scripts/validate_resolution.py H{N}
# Checks: tests pass, constraints satisfied, main untouched

5. 传播约束：

python scripts/propagate.py H{N}
# Updates dependent holes based on resolution

6. 编写文档并提交：

git add .
git commit -m "Resolve H{N}: {description}

- Tests: tests/refactor/test_h{N}_*.py pass
- Constraints: {constraints satisfied}
- Propagates to: {dependent holes}"

最终阶段：报告

生成完整的差异报告：

python scripts/generate_report.py > REFACTOR_REPORT.md

报告包括：

• 类型洞解决情况摘要及验证证据
• 指标变化（LOC、复杂度、覆盖率、性能）
• 行为分析（记录有意进行的更改）
• 约束验证（全部满足）
• 风险评估和迁移指南

关键原则

1. 一切以测试驱动

• 在实施前编写验证标准
• 测试定义“正确解决方案”
• 特征测试至关重要——绝不能让它们失败

2. 以类型洞驱动进展

• 按依赖顺序解决类型洞
• 每次解决都会传播约束
• 在重构 IR 中正式记录所有事项

3. 持续验证

每次提交都必须验证：

• ✅ 特征测试通过（行为得到保留）
• ✅ 解决方案测试通过（类型洞已正确解决）
• ✅ 满足约束
• ✅ main 分支未受影响
• ✅ main 中的 .beads/ 完好无损

4. 从设计上确保安全

• 仅在重构分支中工作
• main 只作为只读参考
• Beads 是不可触碰的历史产物

5. 正式完备性

满足以下条件时，设计即为完备：

• 所有类型洞均已解决并验证
• 所有约束均已满足
• 所有阶段关卡均已通过
• 指标有所改善或保持不变

类型洞质量框架

优质类型洞的 SMART 标准

每个类型洞都必须满足：

• 具体：问题清晰、范围明确，并且有具体答案

  • ✓ 好例子：“API 层应如何处理错误？”
  • ✗ 坏例子：“如何改进代码？”

• 可衡量：具有可测试的验证标准

  • ✓ 好例子：“将重复率从 60% 降至 <15%”
  • ✗ 坏例子：“让代码更好”

• 可实现：利用现有信息即可解决

  • ✓ 好例子：“将解析逻辑提取到独立模块”
  • ✗ 坏例子：“预测所有未来需求”

• 相关：阻碍重构取得有意义的进展

  • ✓ 好例子：“定义核心接口（会阻碍另外 5 个类型洞）”
  • ✗ 坏例子：“决定变量命名约定”

• 有类型：具有清晰的解决方案类型或结构

  • ✓ 好例子：interface Architecture = { layers: Layer[], rules: Rule[] }
  • ✗ 坏例子：“某种结构？”

空洞评估框架

使用以下类别评估空洞规模：

规模	时长	特征	示例
Nano	1-2 小时	简单、机械性的更改	重命名文件、更新导入
Small	4-8 小时	单个模块重构	提取类、整合函数
Medium	1-3 天	跨模块更改	定义接口、重组包
Large	4-7 天	架构更改	提取层、实现模式
Epic	>7 天	拆分此空洞	规模过大，拆分成更小的空洞

评估警示信号：

• 依赖项超过 3 个 → 可能属于 Medium 或更大规模
• 验证方式不明确 → 为探索留出时间
• 新模式/工具 → 预留学习时间

空洞拆分指南

在以下情况下拆分空洞：

1. 预估时间超过 7 天
2. 依赖项超过 5 个
3. 验收标准不明确
4. 混合了多个不同的问题

拆分策略：

Epic hole: "Refactor entire authentication system"
→ Split into:
  R10_auth_interface: Define new auth interface (Medium)
  R11_token_handling: Implement JWT tokens (Small)
  R12_session_management: Refactor sessions (Medium)
  R13_auth_middleware: Update middleware (Small)
  R14_auth_testing: Comprehensive test suite (Medium)

拆分后：

• 更新 REFACTOR_IR.md 中的依赖项
• 运行 python scripts/propagate.py 更新图
• 与 beads 重新同步：python scripts/holes_to_beads.py

常见空洞类型

架构空洞

"?R1_target_architecture": "What should the ideal structure be?"
"?R2_module_boundaries": "How should modules be organized?"
"?R3_abstraction_layers": "What layers/interfaces are needed?"

**验证：**架构测试、依赖分析、层违规检查

实现空洞

"?R4_consolidation_targets": "What code should merge?"
"?R5_extraction_targets": "What code should split out?"
"?R6_elimination_targets": "What code should be removed?"

**验证：**重复检测、等价性测试、死代码分析

质量空洞

"?R7_test_strategy": "How to validate equivalence?"
"?R8_migration_path": "How to safely transition?"
"?R9_rollback_mechanism": "How to undo if needed?"

**验证：**测试覆盖率指标、迁移试运行、回滚测试

请参阅 HOLE_TYPES.md 查看完整目录。

约束传播规则

规则 1：接口解析 → 类型约束

When: Interface hole resolved with concrete types
Then: Propagate type requirements to all consumers

Example:
  Resolve R6: NodeInterface = BaseNode with async run()
  Propagates to:
    → R4: Parallel execution must handle async
    → R5: Error recovery must handle async exceptions

规则 2：实现 → 性能约束

When: Implementation resolved with resource usage
Then: Propagate limits to dependent holes

Example:
  Resolve R4: Parallelization with max_concurrent=3
  Propagates to:
    → R8: Rate limit = provider_limit / 3
    → R7: Memory budget = 3 * single_operation_memory

规则 3：验证 → 测试要求

When: Validation resolved with test requirements
Then: Propagate data needs upstream

Example:
  Resolve R9: Testing needs 50 examples
  Propagates to:
    → R7: Metrics must support batch evaluation
    → R8: Test data collection strategy needed

请参阅 CONSTRAINT_RULES.md 查看完整传播规则。

成功指标

每周进度

• 解决 2-4 个空洞
• 所有测试通过
• 满足约束
• 改进可衡量

警示信号（停止并重新评估）

• ❌ 特征测试失败
• ❌ 无法在约束范围内解决空洞
• ❌ 约束相互矛盾
• ❌ 连续 3 天以上没有进展
• ❌ 意外修改了主分支

验证关卡

关卡	标准	检查
关卡 1：发现完成	已记录所有空洞，已梳理依赖关系	python scripts/check_discovery.py
关卡 2：基础空洞	已解析核心接口，测试通过	python scripts/check_foundation.py
关卡 3：实现	已解决所有重构空洞，指标有所改善	python scripts/check_implementation.py
关卡 4：生产就绪	已测试迁移，已验证回滚	python scripts/check_production.py

Claude 协作工作流

此技能旨在实现与 Claude/大模型的高效协作。以下是分工方式：

阶段 0：发现

Claude 的职责：

• 运行 discover_holes.py 分析代码库
• 根据代码分析提出空洞建议
• 生成初始 REFACTOR_IR.md 结构
• 编写特征测试以捕获当前行为
• 设置测试基础设施

你的职责：

• 确认空洞范围界定合理
• 确定优先处理哪些空洞
• 审查并批准 REFACTOR_IR.md
• 定义关键约束

阶段 1-N：空洞解决

Claude 的职责：

• 在实现之前编写解决方案测试（TDD）
• 实施空洞解决方案，使测试通过
• 运行验证脚本：validate_resolution.py、check_foundation.py
• 在 REFACTOR_IR.md 中更新解决详情
• 传播约束：python scripts/propagate.py H{N}
• 生成记录更改内容的提交消息

你的职责：

• 做出架构决策（使用哪种模式、采用哪种方法）
• 评估风险并确定约束优先级
• 审查代码更改的正确性
• 完成后批准合并到 main

最终阶段：报告

Claude 的职责：

• 生成完整的 REFACTOR_REPORT.md
• 记录所有指标变化
• 列出所有验证证据
• 创建迁移指南
• 准备 PR 描述

你的职责：

• 最后审查报告的准确性
• 批准用于生产环境部署
• 开展重构后的回顾

有效的提示词模式

开始会话：

"I need to refactor [description]. Use typed-holes-refactor skill.
Start with discovery phase."

解决一个缺口：

"Resolve H3 (target_architecture). Write tests first, then implement.
Use [specific pattern/approach]."

检查进度：

"Run check_completeness.py and show me the dashboard.
What's ready to work on next?"

生成可视化图表：

"Generate dependency graph showing bottlenecks and critical path.
Use visualize_graph.py with --analyze."

Claude 的局限性

Claude 无法：

• 做出主观的架构决策（必须由你决定）
• 确定业务关键约束（必须由你指定）
• 运行需要外部服务的测试（使用模拟，或由你运行）
• 合并到 main（必须由你批准并合并）

Claude 可以：

• 分析代码并提出缺口
• 编写全面的测试套件
• 在你的约束范围内实现解决方案
• 生成报告和文档
• 跨会话跟踪进度（通过 beads + REFACTOR_IR.md）

多会话连续性

会话开始时：

"Continue typed-holes refactoring. Import beads state and
show current status from REFACTOR_IR.md."

Claude 将会：

• 阅读 REFACTOR_IR.md，了解当前状态
• 检查哪些缺口已解决
• 找出下一个可处理的缺口
• 从上一个会话停止的地方继续

你应该：

• 将 REFACTOR_IR.md 和 .beads/ 提交到 git
• 在会话结束时导出 beads 状态：bd export -o .beads/issues.jsonl
• 在开始前使用 /context，确保 Claude 拥有完整上下文

Beads 集成

为什么要结合使用 beads 和类型化缺口？

• Beads 可跨会话跟踪问题（防止工作丢失）
• 缺口可跟踪重构相关状态（依赖项、约束）
• 两者结合：确保长期重构的完整连续性

设置

# Install beads (once)
go install github.com/steveyegge/beads/cmd/bd@latest

# After running discover_holes.py
python scripts/holes_to_beads.py

# Check what's ready
bd ready --json

工作流集成

解决缺口期间：

# Start work on a hole
bd update bd-5 --status in_progress --json

# Implement resolution
# ... write tests, implement code ...

# Validate resolution
python scripts/validate_resolution.py H3

# Close bead
bd close bd-5 --reason "Resolved H3: target_architecture" --json

# Export state
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl REFACTOR_IR.md
git commit -m "Resolve H3: Define target architecture"

同步缺口 ↔ beads：

# After updating REFACTOR_IR.md manually
python scripts/holes_to_beads.py  # Sync changes to beads

# After resolving holes
python scripts/holes_to_beads.py  # Update bead statuses

跨会话连续性：

# Session start
bd import -i .beads/issues.jsonl
bd ready --json  # Shows ready holes
python scripts/check_completeness.py  # Shows overall progress

# Session end
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
git commit -m "Session checkpoint: 3 holes resolved"

Bead 的优势：

• 跨天或跨周跟踪工作
• 显示依赖关系图：bd deps bd-5
• 防止上下文丢失
• 与整体项目管理集成

脚本参考

所有脚本都位于 scripts/ 中：

• discover_holes.py - 分析代码库并生成 REFACTOR_IR.md
• next_hole.py - 根据依赖关系显示下一个可解决的缺口
• validate_resolution.py - 检查缺口解决方案是否满足约束
• propagate.py - 在缺口解决后更新依赖它的缺口
• generate_report.py - 创建完整的变化报告
• check_discovery.py - 验证阶段 0 是否完成（Gate 1）
• check_foundation.py - 验证阶段 1 是否完成（Gate 2）
• check_implementation.py - 验证阶段 2 是否完成（Gate 3）
• check_production.py - 验证阶段 3 是否已就绪（Gate 4）
• check_completeness.py - 总体进度仪表板
• visualize_graph.py - 生成缺口依赖关系可视化图
• holes_to_beads.py - 将缺口与 beads 问题同步

运行任意脚本并添加 --help，即可查看详细用法。

元一致性

此技能运用了自身的原则：

类型化缺口原则	在重构中的应用
类型化缺口	按类型对架构未知项进行分类
约束传播	设计约束沿依赖关系图传递
迭代优化	逐个解决缺口的循环
测试驱动验证	测试定义正确性
形式化完整性	通过关卡验证设计完整性

我们用这个系统来重构这个系统。

高级主题

复杂场景请参阅：

• HOLE_TYPES.md - 详细的缺口分类
• CONSTRAINT_RULES.md - 完整的传播规则
• VALIDATION_PATTERNS.md - 不同缺口类型的测试模式
• EXAMPLES.md - 完整的实例演练

快速入门示例

# 1. Setup
git checkout -b refactor/typed-holes-v1
python scripts/discover_holes.py

# 2. Write baseline tests
# Create tests/characterization/test_*.py

# 3. Resolve first hole
python scripts/next_hole.py  # Shows H1 is ready
# Write tests/refactor/test_h1_*.py (fails initially)
# Refactor code until tests pass
python scripts/validate_resolution.py H1
python scripts/propagate.py H1
git commit -m "Resolve H1: ..."

# 4. Repeat for each hole
# ...

# 5. Generate report
python scripts/generate_report.py > REFACTOR_REPORT.md

故障排除

特征测试失败

症状：记录基线行为的测试现在失败了

解决方法：

1. 回退更改：使用 git diff 查看发生了哪些变化
2. 调查：行为发生了什么变化，为什么？
3. 决策树：
   • 有意更改：更新基线并记录说明

     # 更新基线并说明原因
     save_baseline("v2_api", new_behavior,
                   reason="Switched to async implementation")
     

   • 无意回归：修复代码，确保测试通过

预防：每次解决漏洞前后都运行特征测试。

无法解决漏洞

症状：某个漏洞卡了 3 天以上，不清楚该如何继续

解决方法：

1. 检查依赖项：它们真的都已解决吗？

   python scripts/visualize_graph.py --analyze
   # Look for unresolved dependencies
   

2. 检查约束：它们是否相互矛盾？

   • 示例：C1「保留所有行为」+ C5「更改 API 契约」→ 矛盾
   • 解决方法：与相关方重新协商约束

3. 拆分漏洞：如果漏洞范围太大

   # Original: R4_consolidate_all (Epic, 10+ days)
   # Split into:
   R4a_consolidate_parsers (Medium, 2 days)
   R4b_consolidate_validators (Small, 1 day)
   R4c_consolidate_handlers (Medium, 2 days)
   

4. 检查循环依赖：

   python scripts/visualize_graph.py
   # Look for cycles: R4 → R5 → R6 → R4
   

   • 解决方法：引入中间漏洞或重新定义依赖关系，以打破循环

升级处理：如果 5 天后仍然受阻，请考虑采用其他重构方案。

约束相互矛盾

症状：无法同时满足所有约束

示例：

• C1：「保留当前的精确行为」（向后兼容）
• C5：「将响应时间缩短 50%」（性能提升）
• 当前行为包含缓慢的同步操作

解决框架：

1. 找出冲突：

   C1 requires: Keep synchronous operations
   C5 requires: Switch to async operations
   → Contradiction: Can't be both sync and async
   

2. 协商优先级：

   选项	C1	C5	权衡
   A：保留同步	✓	✗	无性能提升
   B：切换为异步	✗	✓	破坏性更改
   C：新增异步并弃用同步	⚠️	✓	迁移负担

3. 选择解决策略：

   • 放宽约束：将 C1 改为「尽可能保留行为」
   • 增加迁移期：在 2 个版本中实现 C
   • 分阶段实施：阶段 1（C1）、阶段 2（C5）

4. 记录决策：

   ## Constraint Resolution: C1 vs C5
   
   **Decision**: Relax C1 to allow async migration
   **Rationale**: Performance critical for user experience
   **Migration**: 3-month deprecation period for sync API
   **Approved by**: [Stakeholder], [Date]
   

循环依赖

症状：visualize_graph.py 显示存在循环

示例：

R4 (consolidate parsers) → depends on R6 (define interface)
R6 (define interface) → depends on R4 (needs parser examples)

解决策略：

1. 引入中间漏洞：

   H0_parser_analysis: Analyze existing parsers (no dependencies)
   R6_interface: Define interface using H0 analysis
   R4_consolidate: Implement using R6 interface
   

2. 重新定义依赖关系：

   • 也许 R4 实际上并不需要 R6
   • 或者 R6 只需要 R4 的一部分（拆分 R4）

3. 接受迭代式改进：

   R6_interface_v1: Initial interface (simple)
   R4_consolidate: Implement with v1 interface
   R6_interface_v2: Refine based on R4 learnings
   

预防：在定义实现漏洞之前，先定义架构漏洞。

连续 3 天以上没有进展

症状：感觉受阻，没有提交记录，不确定该如何继续

解决检查清单：

• 检查 REFACTOR_IR.md：漏洞定义得是否清晰（SMART 标准）？

  • 如果不清晰：重新编写漏洞，使其更加具体

• 检查漏洞规模：当前漏洞的预估解决时间是否超过 7 天？

  • 如果是：将其拆分成更小的漏洞

• 运行仪表板：python scripts/check_completeness.py

  • 你正在处理的漏洞是否受阻？
  • 改为处理一个已就绪的漏洞

• 可视化依赖关系：python scripts/visualize_graph.py --analyze

  • 找出瓶颈
  • 寻找并行工作的机会

• 检查约束：这些约束是否可实现？

  • 如有必要，重新协商

• 寻求外部评审：

  • 与同事分享 REFACTOR_IR.md
  • 征求对方案的反馈

• 考虑替代方案：也许这次重构不可行

  • 记录原因
  • 提出不同的方案

重置流程：如果仍然受阻，请回退到上一个可用状态，并尝试其他方案。

估算失误

症状：某个 Hole 花费的时间比估算长了 3 倍

分析：

1. 为什么估算会出错？

   • 低估了复杂度
   • 遇到了意料之外的依赖项
   • 需求不明确
   • 技术问题（工具故障、基础设施问题）

2. 立即采取的措施：

   • 在 REFACTOR_IR.md 中更新修订后的估算
   • 如果超过 7 天，将该 Hole 拆分
   • 更新 beads：bd update bd-5 --note "Revised estimate: 5 days (was 2)"

3. 后续改进：

   • 使用实际耗时来校准未来的估算
   • 为探索预留缓冲时间（额外增加 20%）
   • 在 IR 中注明不确定性：“估算：2-4 天（不确定性较高）”

经验总结：在 REFACTOR_REPORT.md 中记录实际耗时与估算耗时，供日后参考。

---

从阶段 0：探索开始。始终在分支中工作。先测试，再重构。