symmetric-dogfooding

对称式自用验证

双向集成验证模式：两个仓库各自使用对方进行测试，确保双方协同工作正常，再供下游采用。

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

模式概览

┌─────────────────────────────────────────────────────────────────┐
│                    SYMMETRIC DOGFOODING                         │
│                                                                 │
│        Repo A ◄─────── mutual validation ───────► Repo B        │
│                                                                 │
│   EXPORTS:                              EXPORTS:                │
│   - Library/API                         - Library/API           │
│   - Data structures                     - Data structures       │
│                                                                 │
│   VALIDATES WITH:                       VALIDATES WITH:         │
│   - Repo B real outputs                 - Repo A real outputs   │
│   - Production-like data                - Production-like data  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

何时使用此技能

在以下情况下使用此技能：

• 两个仓库存在生产者/消费者关系
• API 独立演进，需要进行集成测试
• 仓库之间的数据格式可能发生偏移
• 两个仓库都在积极开发

---

TodoWrite 任务模板

模板 A：在两个仓库之间设置对称式自用验证

1. Identify integration surface (exports from A consumed by B and vice versa)
2. Document data formats, schemas, API signatures at boundary
3. Configure cross-repo dev dependencies in both repos
4. Pin versions explicitly (tags or SHAs, never main)
5. Create integration/ test directory in both repos
6. Write bidirectional validation tests (A validates with B outputs, B validates with A outputs)
7. Add validation tasks to the repo's task runner (moon.yml where the repo uses moon)
8. Document pre-release protocol in both CLAUDE.md files
9. Run full symmetric validation to verify setup
10. Verify against Symmetric Dogfooding Checklist below

模板 B：发布前验证

1. Run the validate-symmetric task in releasing repo
2. Check if other repo has pending changes affecting integration
3. If yes, test against other repo's feature branch
4. Document any failures in validation log
5. Fix integration issues before release
6. Update version pins after successful validation
7. Coordinate if breaking changes require simultaneous release
8. Verify against Symmetric Dogfooding Checklist below

模板 C：添加新的集成点

1. Identify new export/import being added
2. Update integration surface documentation
3. Add tests in both repos for new integration point
4. Run symmetric validation in both directions
5. Update version pins if needed
6. Verify against Symmetric Dogfooding Checklist below

对称式自用验证检查清单

完成任何对称式自用验证工作后，请确认：

• 两个仓库都有导入对方的集成测试
• 版本固定明确（标签或提交 SHA）
• 发布前检查清单包含跨仓库验证
• 集成测试使用真实数据（而非对另一个仓库进行模拟）
• 已记录破坏性变更的协调方式
• 可通过单条命令运行验证任务

---

变更后检查清单（自我维护）

修改此技能后：

1. 模板涵盖常见的对称式自用验证场景
2. 检查清单体现当前最佳实践
3. references/ 中的示例仍然准确
4. 将变更追加到 evolution-log.md

---

实施指南

阶段 1：发现和映射

确定集成范围：

• 列出 Repo A 中所有由 Repo B 使用的导出项
• 列出 Repo B 中所有由 Repo A 使用的导出项
• 记录数据格式、模式和 API 签名

映射验证场景：

• 来自 B 的哪些真实数据可用于验证 A 的输出？
• 来自 A 的哪些真实数据可用于验证 B 的输出？
• 找出仅在生产环境使用中出现的边缘情况

阶段 2：依赖配置

配置跨仓库开发依赖：

Python（uv/pip）：

# Repo A pyproject.toml
[project.optional-dependencies]
validation = ["repo-b"]

[tool.uv.sources]
repo-b = { git = "https://github.com/org/repo-b", tag = "<tag>" }  # SSoT-OK

# Repo B pyproject.toml
[project.optional-dependencies]
validation = ["repo-a"]

[tool.uv.sources]
repo-a = { git = "https://github.com/org/repo-a", tag = "<tag>" }  # SSoT-OK

Rust（Cargo）：

[dev-dependencies]
repo-b = { git = "https://github.com/org/repo-b", tag = "<tag>" }  # SSoT-OK

Node.js：

{
  "devDependencies": {
    "repo-b": "github:org/repo-b#<tag>"
  }
}

重要：固定到标签或提交 SHA。绝不要使用 main/master 分支。

阶段 3：测试基础设施

两个仓库中的目录结构：

repo-a/
└── tests/
    ├── unit/              # Internal tests
    └── integration/       # Tests using repo-b real outputs
        └── test_with_repo_b.py

repo-b/
└── tests/
    ├── unit/              # Internal tests
    └── integration/       # Tests using repo-a real outputs
        └── test_with_repo_a.py

双向验证测试模式：

# repo-a/tests/integration/test_with_repo_b.py
"""Validate Repo A outputs work correctly with Repo B inputs."""

def test_a_output_consumed_by_b():
    # Generate output using Repo A
    a_output = repo_a.generate_data()

    # Feed to Repo B - should work without errors
    b_result = repo_b.process(a_output)

    # Validate the round-trip
    assert b_result.is_valid()

阶段 4：任务自动化

moon.yml 示例（任务 ID 使用 -，因为 moon 保留 : 作为项目/任务分隔符）：

tasks:
  validate-symmetric:
    description: "Validate against partner repo"
    script: "uv sync --extra validation && uv run pytest tests/integration/ -v"

  validate-pre-release:
    description: "Full validation before release"
    deps: ["~:test-unit", "~:validate-symmetric"]

阶段 5：发布前流程

发布 Repo A 之前：

1. 在 Repo A 中运行 moon run :validate-symmetric（针对当前 Repo B 进行测试）
2. 如果 Repo B 有待处理的变更，也要针对 Repo B 分支进行测试
3. 验证成功后更新版本固定项

发布 Repo B 之前：

1. 在 Repo B 中运行 moon run :validate-symmetric（针对当前 Repo A 进行测试）
2. 如果 Repo A 有待处理的变更，也要针对 Repo A 分支进行测试
3. 验证成功后更新版本固定项

协调破坏性变更：

• 如果 A 需要破坏兼容性，请先更新 B
• 如果 B 需要破坏兼容性，请先更新 A
• 对于紧密耦合的变更，可考虑同步发布

---

反模式

反模式	问题	解决方案
仅单向验证	会遗漏一半的问题	始终测试两个方向
使用 main 分支	不稳定，会随机导致故障	固定到标签或 SHA
跳过小改动的验证	小改动也可能造成重大故障	始终运行完整验证
模拟协作仓库	违背验证目的	使用真实导入
忽略版本矩阵	会导致生产环境故障却不易察觉	维护兼容性矩阵

参考资料

• example-setup.md - 真实场景中的 trading-fitness/rangebar-py 示例
• evolution-log.md - 技能变更历史

外部资料：

• Dogfooding (DevIQ)
• CDC Testing (Microsoft)

---

故障排除

问题	原因	解决方案
依赖解析失败	版本固定值已过时	将标签/SHA 固定值更新到最新稳定版本
本地测试通过，CI 测试失败	合作方仓库版本不同	在两个环境中固定到完全相同的版本
未捕获到破坏性变更	仅进行单向测试	在两个仓库中都运行 validate-symmetric
集成范围不明确	导出项未记录	设置测试前，梳理所有导入项/导出项
同时变动的部分太多	发布未协调	协调破坏性变更，先测试分支
模拟数据掩盖了错误	使用了桩，而非真实数据	集成时始终导入真实的合作方仓库
版本矩阵膨胀	组合过多	将支持范围限制在 N-1 个版本，并明确记录
循环依赖	两个仓库互相依赖	仅将 optional-dependencies 用于验证

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认当前位置。 — 编辑前，找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修复导致失败的指令。
2. 哪些地方的效果超出预期？ — 将其提升为推荐做法。
3. 哪些内容发生了偏差？ — 修复不再符合实际情况的脚本、参考资料或依赖项。
4. 记录下来。 — 在 evolution-log 中记录触发原因、修复内容和证据。

不要拖延。下一次调用会继承你留下的一切。