symmetric-dogfooding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Symmetric Dogfooding

Symmetric Dogfooding（对称自验证）

Bidirectional integration validation pattern where two repositories each consume the other for testing, ensuring both sides work correctly together before downstream adoption.

一种双向集成验证模式，两个仓库互相调用对方进行测试，确保在下游系统采用之前，双方能够协同正常工作。

Pattern Overview

模式概述

┌─────────────────────────────────────────────────────────────────┐
│                    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  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    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  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

When to Use This Skill

何时使用该方法

Use this skill when:

Two repos have a producer/consumer relationship
APIs evolve independently and need integration testing
Data formats may drift between repos
Both repos are actively developed

在以下场景中使用该方法：

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

TodoWrite Task Templates

TodoWrite 任务模板

Template A: Setup Symmetric Dogfooding Between Two Repos

模板A：在两个仓库间配置Symmetric Dogfooding

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 mise.toml or Makefile
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

1. 确定集成面（Repo A被Repo B调用的导出内容，以及反之）
2. 记录边界处的数据格式、schema、API签名
3. 在两个仓库中配置跨仓库开发依赖
4. 显式固定版本（使用标签或SHA值，绝不要用main分支）
5. 在两个仓库中创建integration/测试目录
6. 编写双向验证测试（Repo A使用Repo B的输出进行验证，Repo B使用Repo A的输出进行验证）
7. 将验证任务添加到mise.toml或Makefile中
8. 在两个仓库的CLAUDE.md文件中记录发布前流程
9. 运行完整的对称验证以确认配置正确
10. 根据下方的Symmetric Dogfooding检查清单进行验证

Template B: Pre-Release Validation

模板B：发布前验证

1. Run 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

1. 在待发布的仓库中运行validate:symmetric任务
2. 检查另一个仓库是否有影响集成的待处理变更
3. 如果有，针对另一个仓库的功能分支进行测试
4. 在验证日志中记录所有失败情况
5. 在发布前修复集成问题
6. 验证成功后更新版本固定信息
7. 如果是破坏性变更，需协调同步发布
8. 根据下方的Symmetric Dogfooding检查清单进行验证

Template C: Add New Integration Point

模板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

1. 确定要添加的新导出/导入内容
2. 更新集成面文档
3. 在两个仓库中为新集成点添加测试
4. 运行双向对称验证
5. 如有需要，更新版本固定信息
6. 根据下方的Symmetric Dogfooding检查清单进行验证

Symmetric Dogfooding Checklist

Symmetric Dogfooding检查清单

Post-Change Checklist (Self-Maintenance)

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

After modifying THIS skill:

Templates cover common symmetric dogfooding scenarios
Checklist reflects current best practices
Example in references/ still accurate
Append changes to evolution-log.md

修改本方法后：

模板覆盖了Symmetric Dogfooding的常见场景
检查清单反映了当前最佳实践
references/中的示例仍然准确
将变更记录到evolution-log.md中

Implementation Guide

实施指南

Phase 1: Discovery and Mapping

阶段1：发现与映射

Identify the integration surface:

List all exports from Repo A consumed by Repo B
List all exports from Repo B consumed by Repo A
Document data formats, schemas, API signatures

Map validation scenarios:

What real-world data from B can validate A outputs?
What real-world data from A can validate B outputs?
Identify edge cases that only appear in production usage

确定集成面：

列出Repo A中被Repo B调用的所有导出内容
列出Repo B中被Repo A调用的所有导出内容
记录数据格式、schema、API签名

映射验证场景：

Repo B的哪些真实数据可以验证Repo A的输出？
Repo A的哪些真实数据可以验证Repo B的输出？
识别仅在生产环境使用中才会出现的边缘情况

Phase 2: Dependency Configuration

阶段2：依赖配置

Configure cross-repo dev dependencies:

Python (uv/pip):

toml

undefined

配置跨仓库开发依赖：

Python（uv/pip）：

toml

undefined

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


```toml

[project.optional-dependencies] validation = ["repo-b"]

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


```toml

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):**

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

Node.js:

json

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

Critical: Pin to tags or commit SHAs. Never use main/master branches.

[project.optional-dependencies] validation = ["repo-a"]

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


**Rust（Cargo）：**

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

Node.js：

json

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

关键注意事项：固定到标签或提交SHA值。绝不要使用main/master分支。

Phase 3: Test Infrastructure

阶段3：测试基础设施

Directory structure in both repos:

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

Bidirectional validation test pattern:

python

undefined

两个仓库的目录结构：

repo-a/
└── tests/
    ├── unit/              # 单元测试
    └── integration/       # 使用Repo B真实输出的测试
        └── test_with_repo_b.py

repo-b/
└── tests/
    ├── unit/              # 单元测试
    └── integration/       # 使用Repo A真实输出的测试
        └── test_with_repo_a.py

双向验证测试模式：

python

undefined

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()

undefined

"""验证Repo A的输出能否正确被Repo B处理。"""

def test_a_output_consumed_by_b(): # 使用Repo A生成输出 a_output = repo_a.generate_data()

# 传入Repo B - 应无错误运行
b_result = repo_b.process(a_output)

# 验证往返流程
assert b_result.is_valid()

undefined

Phase 4: Task Automation

阶段4：任务自动化

mise.toml example:

toml

[tasks."validate:symmetric"]
description = "Validate against partner repo"
run = """
uv sync --extra validation
uv run pytest tests/integration/ -v
"""

[tasks."validate:pre-release"]
description = "Full validation before release"
depends = ["test:unit", "validate:symmetric"]

mise.toml示例：

toml

[tasks."validate:symmetric"]
description = "验证与合作仓库的兼容性"
run = """
uv sync --extra validation
uv run pytest tests/integration/ -v
"""

[tasks."validate:pre-release"]
description = "发布前完整验证"
depends = ["test:unit", "validate:symmetric"]

Phase 5: Pre-Release Protocol

阶段5：发布前流程

Before releasing Repo A:

Run
```
validate:symmetric
```
in Repo A (tests against current Repo B)
If Repo B has pending changes, test against Repo B branch too
Update version pins after successful validation

Before releasing Repo B:

Run
```
validate:symmetric
```
in Repo B (tests against current Repo A)
If Repo A has pending changes, test against Repo A branch too
Update version pins after successful validation

Coordinating breaking changes:

If A needs to break compatibility, update B first
If B needs to break compatibility, update A first
Consider simultaneous releases for tightly coupled changes

发布Repo A前：

在Repo A中运行
```
validate:symmetric
```
（针对当前Repo B版本进行测试）
如果Repo B有待处理变更，同时针对Repo B的分支进行测试
验证成功后更新版本固定信息

发布Repo B前：

在Repo B中运行
```
validate:symmetric
```
（针对当前Repo A版本进行测试）
如果Repo A有待处理变更，同时针对Repo A的分支进行测试
验证成功后更新版本固定信息

破坏性变更协调：

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

Anti-Patterns

反模式

Anti-Pattern	Problem	Solution
One-direction only	Misses half the bugs	Always test both directions
Using main branch	Unstable, breaks randomly	Pin to tags or SHAs
Skipping for small changes	Small changes cause big breaks	Always run full validation
Mocking partner repo	Defeats the purpose	Use real imports
Ignoring version matrix	Silent production failures	Maintain compatibility matrix

反模式	问题点	解决方案
仅单向测试	遗漏半数潜在问题	始终进行双向测试
使用main分支	依赖不稳定，随机出现故障	固定到标签或SHA值
小变更跳过验证	小变更可能引发大故障	始终运行完整验证
模拟合作仓库	失去验证的实际意义	使用真实的导入依赖
忽略版本矩阵	生产环境中出现隐性故障	维护兼容性矩阵

References

参考资料

example-setup.md - Real-world trading-fitness/rangebar-py example
evolution-log.md - Skill change history

External:

example-setup.md - 真实场景示例：trading-fitness/rangebar-py
evolution-log.md - 方法变更历史

外部资源：

Troubleshooting

故障排除

Issue	Cause	Solution
Dependency resolution fails	Version pin outdated	Update tag/SHA pin to latest stable version
Tests pass locally fail CI	Different partner repo version	Pin exact same version in both environments
Breaking change not caught	One-direction testing only	Run validate:symmetric in BOTH repos
Integration surface unclear	Undocumented exports	Map all imports/exports before setting up tests
Too many parts moving	Uncoordinated releases	Coordinate breaking changes, test branches first
Mock data hiding bugs	Using stubs instead of real	Always import real partner repo for integration
Version matrix explosion	Too many combinations	Limit support to N-1 versions, document clearly
Circular dependency	Both repos require each other	Use optional-dependencies for validation only

问题	原因	解决方案
依赖解析失败	版本固定信息过时	将标签/SHA值更新到最新稳定版本
本地测试通过但CI失败	合作仓库版本不一致	在两个环境中固定完全相同的版本
破坏性变更未被发现	仅进行了单向测试	在两个仓库中都运行validate:symmetric任务
集成面不清晰	导出内容未记录	在设置测试前先映射所有导入/导出内容
变更过多难以协调	发布未协调	协调破坏性变更，先针对分支进行测试
模拟数据隐藏故障	使用存根而非真实依赖	集成测试始终导入真实的合作仓库
版本矩阵过于复杂	组合过多	仅支持N-1个版本，并清晰记录
循环依赖	两个仓库互相依赖	仅在验证时使用可选依赖项