企业官网建设流程全解析

1. OpenSpec 与 Superpowers 的真实定位：不是“又一个工作流工具”，而是开发者认知层的重构入口

OpenSpec 和 Superpowers 这两个词最近在技术社区里频繁出现，但很多人点开文档后第一反应是：“这不就是个 YAML 写法 + CLI 工具？”——这种理解偏差，恰恰踩中了整个 SDD+TDD 工作流落地失败的核心陷阱。我去年在三个不同规模的团队里推动过类似实践，其中两个项目在两周内就陷入“写完 spec 就扔进抽屉”的僵局，根本原因不是工具不会用，而是从一开始就没搞清 OpenSpec 和 Superpowers 分别在解决什么层级的问题。

OpenSpec 的本质，不是“把需求写成 YAML”，而是把模糊的业务意图翻译成可被机器解析、可被测试验证、可被协作对齐的最小语义单元。它强制你回答三个问题：这个功能“对谁有用”（actor）、“在什么条件下触发”（context）、“成功时必须发生什么”（outcome）。比如“用户登录”这个动作，OpenSpec 要求你明确写出：

• actor:end-user（而非笼统的“用户”）
• context:when email and password are provided, and account is active（排除“忘记密码”“邮箱未验证”等分支）
• outcome:session token is issued, and user profile is loaded into memory（而非“跳转到首页”这种 UI 层描述）

Superpowers 则完全站在另一个维度：它不关心你写了什么 spec，只关心“如何让这些 spec 在真实环境中活起来”。它的核心能力是将 OpenSpec 中定义的 context/outcome 映射为可执行的、带上下文感知的自动化操作链。比如上面那个登录 spec，Superpowers 不会去实现登录逻辑，但它能自动识别出session token is issued这一 outcome，并触发：

• 启动一个本地 mock server 模拟 token 签发服务
• 注入预设的 JWT secret 配置
• 在测试运行前自动设置环境变量AUTH_MODE=mock
• 执行完后自动清理临时 session 数据库

这才是 SDD（Specification-Driven Development）和 TDD（Test-Driven Development）真正融合的关键：SDD 定义“世界应该长什么样”，TDD 验证“我们造出来的世界是否真长这样”，而 Superpowers 是那个帮你快速搭建“世界沙盒”的施工队。它不替代你的代码，但让你不用再花 30% 时间写测试桩、mock、环境配置脚本——这些本该是基础设施，不该是每次迭代都要重写的胶水代码。

提示：很多团队把 OpenSpec 当成“高级注释”来写，结果越写越像产品 PRD；把 Superpowers 当成“自动化脚本生成器”，结果生成一堆无法维护的 shell 命令。这两个工具的价值，只在它们形成闭环时才真正释放——OpenSpec 的每一行，都必须能在 Superpowers 的某个 skill 中找到对应的动作锚点；Superpowers 的每一个 skill，都必须能回溯到 OpenSpec 中某一条 outcome 的验证路径。这不是工具链，是开发者的思维校准器。

我见过最典型的误用场景：某电商团队用 OpenSpec 描述“下单成功后发送短信通知”，spec 写得非常规范，但 Superpowers 配置里却直接调用了生产短信网关。结果测试跑通了，上线却因短信配额超限被熔断。问题不在工具，而在他们没意识到：OpenSpec 中的send sms notification是一个 outcome 声明，不是实现指令；Superpowers 应该做的，是根据当前环境（test/staging/prod）自动切换为mock-sms-service或alibaba-cloud-sms-fakeskill，而不是硬编码调用真实接口。这种认知错位，比语法错误更难调试，也更致命。

2. 为什么必须放弃“先写代码再补 spec”的惯性？SDD 的底层约束力来自编译期校验

绝大多数开发者对 SDD 的第一反应是：“又要多写一堆东西，拖慢开发节奏。” 这种抵触背后，藏着一个根深蒂固的误解：认为 spec 是“事后文档”，是可以妥协、可以延迟、可以简化的东西。但 OpenSpec 的设计哲学恰恰相反——它要成为编译期的第一道门禁，而不是测试阶段的装饰性摆设。

关键在于 OpenSpec 的 schema 设计本身就是一个强约束系统。以 v0.8 版本为例，一个合法的loginspec 文件必须满足：

• actor字段只能从预设枚举中选择（end-user,admin,system,third-party-api），不允许自由字符串
• context中每个条件必须绑定到具体的数据源（db.users,redis.session-cache,env.AUTH_SERVICE_URL），且该数据源必须已在项目全局 registry 中注册
• outcome的每个动作必须关联到已声明的 side effect 类型（write-to-db,emit-event,call-external-api,modify-state），且该类型需有对应的 Superpowers skill 实现

这意味着，当你执行openspec validate login.yaml时，它不只是检查 YAML 语法，而是在做三件事：

1. 语义合法性检查：actor: "customer"会被拒绝，因为customer不在枚举列表中，必须改为end-user
2. 依赖可达性检查：如果context引用了db.users，但项目根目录下没有registry/datasources/db-users.yaml，校验失败
3. 技能映射检查：如果outcome包含call-external-api，但当前环境未安装superpowers-http-clientskill，报错并提示run superpowers install http-client

这种校验不是“锦上添花”，而是把设计决策提前到编码之前锁定。我曾在一个支付模块重构中强制要求：所有新功能必须先通过 OpenSpec 校验，才能创建 feature branch。结果发现 70% 的需求在 spec 阶段就被卡住——产品经理写的context: when balance is sufficient没有明确定义“sufficient”是 >0 还是 ≥100 元；开发写的outcome: update transaction status没指定是更新orders表还是payments表。这些模糊点，如果等到写完代码再讨论，代价是重写 3 天；而在 spec 阶段暴露，15 分钟就能对齐。

更关键的是，OpenSpec 的校验结果可以直接集成进 CI 流程。我们在 GitLab CI 中配置了：

validate-spec: stage: validate script: - openspec validate --strict src/specs/**/*.yaml allow_failure: false

这个 job 失败，整个 pipeline 就中断。没有商量余地。刚开始团队抱怨“太严格”，但两周后，PR 描述区里再也看不到“这个逻辑有点复杂，回头再补文档”这类话——因为没人能绕过校验提交代码。SDD 的威力，不在于它写了多少文档，而在于它让模糊地带无处藏身。

注意：OpenSpec 的--strict模式默认关闭，必须显式启用。很多团队没开这个开关，导致校验形同虚设。它会强制检查：所有引用的 datasource 必须有对应 schema 定义；所有 outcome 的 side effect 必须有 skill 实现；所有 context 条件必须能被至少一个已注册的 validator 解析。这是 SDD 能落地的底线配置，不是可选功能。

还有一个隐藏价值：OpenSpec 的 schema 本身会随着项目演进自动沉淀为领域知识图谱。我们团队半年后导出了所有 spec 文件，用openspec export --format=mermaid生成了系统交互关系图，意外发现三个微服务之间存在未被文档记录的隐式依赖——某个订单状态变更会触发库存服务的异步回调，但回调条件只在一段注释里提过。OpenSpec 把这些散落的契约，变成了可查询、可验证、可追溯的结构化资产。

3. Superpowers Skill 的设计心法：拒绝“万能函数”，拥抱“场景原子化”

Superpowers 的核心价值常被误解为“自动化脚本管理器”，于是很多人第一反应是：写一个run-backend-testsskill，里面塞满 pytest 命令、数据库迁移、mock 启动……结果这个 skill 越来越臃肿，复用率越来越低，最后变成另一个需要维护的黑盒。真正的 Superpowers 实践，遵循的是场景原子化（Scenario Atomization）原则：每个 skill 只做一件事，且这件事必须能被 OpenSpec 的某一条 outcome 直接调用。

以电商系统的“库存扣减”为例，传统做法可能写一个inventory-deductskill，包含：

• 连接 Redis
• 执行 Lua 脚本扣减
• 记录日志
• 发送 Kafka 事件
• 更新 MySQL 库存表

这看起来很完整，但问题在于：它无法被 OpenSpec 的不同 outcome 精准匹配。比如 spec 中写outcome: inventory is decremented in cache，你没法只调用这个 skill 的“Redis 部分”；写outcome: inventory change event is published，又得从头写一遍 Kafka 发送逻辑。

正确的拆解方式是定义四个原子 skill：

• redis-decrement-key：接收key,amount,ttl参数，纯 Redis 操作
• kafka-publish-event：接收topic,payload,schema-id，纯 Kafka 发送
• mysql-update-row：接收table,where-clause,update-values，纯 MySQL 更新
• log-action：接收level,message,context，纯日志记录

然后在 OpenSpec 的 outcome 中，用组合方式声明：

outcome: - action: redis-decrement-key params: { key: "stock:sku-123", amount: 1 } - action: kafka-publish-event params: { topic: "inventory-changed", payload: "{sku: '123', delta: -1}" } - action: log-action params: { level: "info", message: "Inventory deducted for SKU 123" }

这种设计带来三个实质性好处：
第一，可测试性爆炸提升。每个原子 skill 都可以独立单元测试，无需启动整个服务。比如redis-decrement-key的测试只需 mock Redis client，验证它是否调用了decrby方法及参数是否正确。而原来那个大 skill，测试必须启动 Redis、Kafka、MySQL 三套环境，CI 时间从 2 秒拉长到 47 秒。

第二，环境适配成本归零。当 spec 在 test 环境运行时，Superpowers 自动将redis-decrement-key替换为mock-redis-decrement（返回固定值）；在 staging 环境，替换为redis-decrement-with-tracing（增加性能埋点）；在 prod，则用原版。这种替换不是靠 if-else 代码判断，而是通过 skill registry 的 environment-aware binding 实现——你在registry/skills/redis-decrement-key.yaml里声明：

bindings: test: mock-redis-decrement staging: redis-decrement-with-tracing prod: redis-decrement-key

Superpowers 在加载时自动按当前ENV变量选择对应实现，开发者完全无感。

第三，故障隔离能力质变。某次线上事故中，库存扣减失败，但日志显示kafka-publish-event成功了，redis-decrement-key却超时。因为 skill 是原子的，我们立刻定位到 Redis 连接池耗尽，而不是在几百行混合逻辑里 grep “kafka” 和 “redis” 关键字。更妙的是，运维同事直接用superpowers run redis-decrement-key --dry-run模拟调用，确认是网络问题而非代码 bug。

提示：Superpowers 官方推荐的 skill 命名规范是verb-noun-modifier，比如start-mock-server、inject-env-var、wait-for-port。避免使用setup-test-env这类模糊名称。每个 skill 的 README.md 必须包含三要素：1）它对应 OpenSpec 中哪类 outcome；2）它在哪些环境下有不同实现；3）它的失败退出码含义（如exit 101表示连接超时，exit 102表示参数校验失败）。这是 skill 可被 OpenSpec 自动发现和调度的前提。

我们团队还制定了 skill 开发的“黄金三原则”：

1. 无状态原则：skill 不能读写本地文件（除非明确声明side-effect: filesystem-write），所有输入必须通过params传入，输出必须通过 stdout 或 exit code 返回；
2. 幂等原则：同一组参数重复执行，结果必须一致（比如mysql-update-row对同一 where 条件多次执行，效果等同于一次）；
3. 可观测原则：每个 skill 必须输出结构化日志（JSON 格式），包含skill_name,params_hash,duration_ms,exit_code字段，便于集中采集分析。

违反任何一条，CI 中的superpowers lint检查就会失败。这听起来严苛，但正是这些约束，让我们的 47 个自研 skill 在两年内零重大故障，复用率从 32% 提升到 89%。

4. SDD+TDD 工作流的实操闭环：从 OpenSpec 声明到 Superpowers 驱动的完整链路

现在我们把前面所有概念串起来，走一遍真实的 SDD+TDD 工作流闭环。以“用户修改收货地址”功能为例，这不是一个教科书式的 Hello World，而是包含并发冲突、权限校验、异步通知的真实场景。我会展示每一步的命令、配置、常见坑和我的实战心得。

4.1 第一步：用 OpenSpec 声明契约（15 分钟）

在src/specs/address/update.yaml中编写：

spec-version: "0.8" id: "address-update" title: "Update user's default shipping address" actor: "end-user" context: - condition: "user is authenticated" datasource: "auth-session" - condition: "user has at least one address" datasource: "db.user-addresses" - condition: "new address passes validation rules" datasource: "validator.address-schema" outcome: - action: "update-db-row" params: { table: "user_addresses", where: "user_id = {{user_id}} AND is_default = true", values: "{{address_data}}" } - action: "publish-kafka-event" params: { topic: "user-address-updated", payload: "{{event_payload}}" } - action: "send-email-notification" params: { template: "address-updated", to: "{{user_email}}" }

关键细节：

• {{user_id}}、{{address_data}}是 OpenSpec 的模板变量，会在运行时由 Superpowers 从 context 中注入；
• datasource: "auth-session"不是随便写的，它指向registry/datasources/auth-session.yaml，该文件定义了如何从 HTTP header 或 cookie 中提取 session token 并验证；
• validator.address-schema是一个预注册的 JSON Schema 校验器，确保address_data包含street,city,postal_code且格式合法。

执行校验：

openspec validate --strict src/specs/address/update.yaml # 输出：✅ Validated 1 spec file. All dependencies resolved.

如果这里失败，比如validator.address-schema未注册，OpenSpec 会明确提示：

ERROR: datasource 'validator.address-schema' not found in registry/datasources/ HINT: Run 'superpowers install address-validator' to add it

这就是 SDD 的第一道防线——它不让你糊弄过去。

4.2 第二步：用 Superpowers 初始化测试沙盒（3 分钟）

运行：

superpowers init --spec src/specs/address/update.yaml --env test

这个命令做了四件事：

1. 创建临时目录./sandbox/address-update-test-20240521-1423；
2. 根据 spec 中的datasource声明，自动下载并启动auth-session-mock、db-user-addresses-fake、address-validator三个 mock 服务；
3. 生成.env.test文件，包含所有 mock 服务的端口、token 等配置；
4. 创建test-runner.sh脚本，封装了完整的执行链路。

此时，你不需要手动启动任何服务，也不用改一行代码——Superpowers 已经为你搭好了一个与生产环境行为一致、但完全隔离的沙盒。我第一次用时惊讶的是：auth-session-mock甚至模拟了 session 过期时间（默认 30 分钟），db-user-addresses-fake支持按user_id查询并返回预设的地址列表，连address-validator都内置了各国邮政编码正则校验。

4.3 第三步：生成 TDD 测试骨架（2 分钟）

执行：

superpowers generate-test --spec src/specs/address/update.yaml --framework pytest

它生成的tests/test_address_update.py不是空模板，而是：

import pytest from superpowers import load_spec, run_skill def test_address_update_success(): # Auto-injected context from spec context = { "user_id": "usr_abc123", "user_email": "test@example.com", "address_data": {"street": "123 Main St", "city": "Beijing", "postal_code": "100000"} } # Run the full outcome chain result = run_skill("update-db-row", context) assert result["status"] == "success" result = run_skill("publish-kafka-event", context) assert result["event_sent"] == True result = run_skill("send-email-notification", context) assert result["email_queued"] == True def test_address_update_unauthenticated(): # Context missing auth session -> should fail early context = {"user_id": "usr_abc123"} # no auth-session with pytest.raises(RuntimeError, match="user is not authenticated"): run_skill("update-db-row", context)

注意：run_skill不是调用你的业务代码，而是调用 Superpowers 的 skill runner。它会自动加载test环境下的 skill 实现（比如send-email-notification在 test 环境下实际调用的是mock-email-sender，只打印日志不发真实邮件）。

4.4 第四步：编写业务代码并驱动测试（核心环节）

现在你才开始写真正的业务逻辑。在src/services/address_service.py中：

def update_default_address(user_id: str, address_data: dict) -> bool: # 1. Check auth (uses auth-session datasource) if not check_auth(user_id): raise PermissionError("User not authenticated") # 2. Validate address (uses address-validator datasource) if not validate_address(address_data): raise ValueError("Invalid address format") # 3. Update DB (this is the only line that touches real code) return db.update_user_address(user_id, address_data)

然后运行测试：

pytest tests/test_address_update.py -v # 输出：test_address_update_success PASSED, test_address_update_unauthenticated PASSED

这里的关键洞察是：TDD 的“红-绿-重构”循环，现在发生在 OpenSpec 定义的 outcome 层面，而不是函数层面。你不需要先写check_auth()函数再测试，因为check_auth()的行为已经被auth-sessiondatasource 的 mock 定义好了；你也不需要先写validate_address()，因为它的规则在address-validatorskill 里已经固化。你的业务代码，只需要专注在db.update_user_address()这一行——其他所有“胶水逻辑”，都由 OpenSpec 和 Superpowers 共同承担。

4.5 第五步：CI 中的全自动验证（零配置）

在.gitlab-ci.yml中添加：

sdd-tdd-pipeline: stage: test script: - openspec validate --strict src/specs/**/*.yaml - superpowers init --env test - pytest tests/ --tb=short artifacts: - coverage.xml

这个 pipeline 的魔力在于：

• 当有人修改src/specs/address/update.yaml时，openspec validate会确保新 spec 仍符合 schema；
• superpowers init会基于新 spec 重新生成沙盒，如果新增了datasource: "geo-location-api"，它会自动下载并启动geo-location-mock；
• pytest运行的测试，会自动使用新 spec 中定义的 outcome 链路，无需修改测试代码。

我们曾遇到一个典型问题：某次 PR 修改了outcome中的publish-kafka-event参数，增加了partition_key字段，但忘了更新kafka-publish-eventskill 的 schema。CI 直接报错：

ERROR: skill 'kafka-publish-event' does not accept parameter 'partition_key' HINT: Run 'superpowers update kafka-publish-event' to sync schema

这个错误在开发机上就能捕获，而不是等到 QA 环境才发现事件发不到正确分区。

实战心得：我们团队规定，所有新功能的 PR，必须包含三样东西：1）OpenSpec 文件；2）对应的 Superpowers skill（如果是新 skill）；3）至少一个通过superpowers generate-test生成的测试用例。缺一不可。这看起来增加了 PR 体积，但把 80% 的集成问题挡在了合并之前。平均每个功能的返工次数从 2.7 次降到 0.3 次，上线后 P0 故障率下降 64%。

5. 避坑指南：那些让 SDD+TDD 工作流半途而废的“温柔陷阱”

即使你完美理解了 OpenSpec 和 Superpowers 的设计哲学，实际落地时仍会掉进一些看似合理、实则致命的坑。这些不是工具缺陷，而是人类认知惯性与新范式之间的摩擦。我把它们称为“温柔陷阱”——因为它们初期不痛不痒，甚至显得更高效，但三个月后会让你彻底放弃这套工作流。

5.1 陷阱一：“spec 先写一半，代码先写一部分” —— 破坏契约的雪崩效应

最常见的做法是：产品经理给个模糊需求，开发先写个update_address()函数，跑通基本流程，再回头补 OpenSpec。这看似节省时间，但后果严重。我亲眼见过一个案例：

• 开发写的函数里，address_data参数是一个扁平字典{"street": "...", "city": "..."}；
• 但补写的 OpenSpec 里，address_data被定义为嵌套结构{"location": {"street": "...", "city": "..."}}；
• 结果 Superpowers 在注入参数时，把整个嵌套结构传给函数，而函数只认扁平结构，直接KeyError；
• 更糟的是，测试用例是用superpowers generate-test生成的，它基于 spec 的嵌套结构，所以测试全绿，生产却挂。

根本原因在于：OpenSpec 的 schema 是运行时契约，不是文档契约。一旦代码和 spec 的数据结构不一致，Superpowers 的参数注入机制就会失效，而这种失效往往静默发生（比如传入None而不是报错）。解决方案只有一条：强制所有代码必须从 OpenSpec 生成的 stub 开始。我们用了一个小脚本openspec generate-stub --lang python，它会根据 spec 生成：

• 一个address_service.py模板，其中update_default_address()函数的参数签名严格匹配 spec 中的context和outcome变量；
• 一个types.py，定义所有用到的数据结构（如AddressDataPydantic model）；
• 一个mocks/目录，包含所有 datasource 的 mock 实现。

开发只能在这个 stub 上修改，不能自己定义新参数。这听起来教条，但它是防止契约漂移的唯一有效手段。

5.2 陷阱二：“用 Superpowers 替代 CI/CD 工具” —— 混淆职责边界的灾难

有些团队看到 Superpowers 能启动服务、运行命令、发通知，就想把它当成 Jenkins 或 GitLab CI 的替代品，写一个deploy-to-stagingskill，里面包含：

• git pull
• docker build
• kubectl apply
• smoke test

这完全违背了 Superpowers 的设计初衷。Superpowers 的核心价值是在开发和测试阶段，消除环境差异带来的噪声，而不是接管部署流水线。当你把部署逻辑塞进 Superpowers，会出现三个问题：

1. 权限失控：Superpowers 运行在开发者本地或 CI agent 上，如果它有kubectl权限，等于每个开发者的机器都能直接操作 K8s 集群，安全风险极高；
2. 可观测性断裂：GitLab CI 的 pipeline 图能清晰显示每个 stage 的耗时、失败节点、重试次数，而 Superpowers 的 skill 日志是分散的，无法聚合分析；
3. 版本混乱：deploy-to-stagingskill 的代码和配置，会和业务代码混在一起，导致“哪个 commit 对应哪个部署版本”无法追溯。

正确做法是：Superpowers 只负责生成部署所需的 artifact 和 config。比如：

• generate-deployment-manifestskill，根据 OpenSpec 中的environment: staging和service: address-api，生成k8s/deployment-staging.yaml；
• package-docker-imageskill，构建镜像并打 tagaddress-api:v1.2.3-openspec-hash；
• 然后由 GitLab CI 的deploystage，调用标准的kubectl apply -f k8s/deployment-staging.yaml。

Superpowers 是“准备弹药”的人，不是“扣扳机”的人。守住这条边界，才能让工作流既强大又可控。

5.3 陷阱三：“为每个 spec 写独立的 Superpowers 配置” —— 丧失复用性的熵增

另一个常见错误是：每个新功能都新建一个superpowers-config.yaml，里面复制粘贴一堆 skill 配置。结果项目里出现 23 个几乎一样的配置文件，某个 datasource 的 URL 改了，就得手动改遍所有文件。这本质上是放弃了 Superpowers 最强大的能力：全局 registry 和环境继承。

正确的配置结构应该是：

project-root/ ├── superpowers/ │ ├── registry/ # 全局注册中心 │ │ ├── datasources/ │ │ │ ├── auth-session.yaml # 定义如何获取和验证 session │ │ │ └── db-user-addresses.yaml # 定义如何连接 fake DB │ │ ├── skills/ │ │ │ ├── update-db-row.yaml # 定义 skill 接口和 binding │ │ │ └── publish-kafka-event.yaml │ │ └── environments/ │ │ ├── base.yaml # 所有环境共享的基础配置 │ │ ├── test.yaml # test 环境特有配置（如 mock 地址） │ │ └── prod.yaml # prod 环境特有配置（如真实 Kafka 地址） │ └── config.yaml # 项目级配置，指向 registry └── src/specs/... # specs 引用 registry 中的资源

config.yaml只需写：

registry: ./superpowers/registry environments: - base - test

所有 spec 文件，都通过datasource: "auth-session"这样的短名引用，Superpowers 会自动从registry/datasources/下加载。这样，当auth-session的 mock 实现升级，只需改auth-session.yaml一个文件，所有依赖它的 spec 都自动受益。

我们曾用superpowers diff --env test --env prod命令，对比出 test 和 prod 环境在 Kafka topic 名称上的 7 处差异，全部在environments/下统一修复，而不是在 12 个 spec 文件里逐个查找。

5.4 陷阱四：“忽略 OpenSpec 的版本演进” —— 技术债的隐形加速器

OpenSpec 的 schema 会随版本升级引入新字段、新约束。比如 v0.7 加入了timeout字段用于定义 outcome 的最大执行时间，v0.8 加入了retry-policy用于声明重试策略。很多团队升级工具后，旧 spec 文件还能跑通，就以为没问题。但隐患巨大：

• 新加入的timeout字段，能让 Superpowers 在 outcome 执行超时时自动终止，避免测试卡死；
• retry-policy能让publish-kafka-event在网络抖动时自动重试 3 次，而不是直接失败；

如果旧 spec 没声明这些，就享受不到这些保护。更危险的是，某些新版本会废弃旧字段（如 v0.9 将action改为skill），但为了兼容保留旧字段，只是警告。结果团队积累了几百个带警告的 spec，直到某天升级强制要求，才手忙脚乱地批量修改。

我们的应对策略是：

• 每次 OpenSpec 升级，运行openspec migrate --in-place src/specs/，它会自动将旧语法转换为新语法；
• 在 CI 中加入openspec lint --strict，检查所有 spec 是否使用最新最佳实践（如是否所有context都有datasource声明）；
• 建立spec-evolution-log.md，记录每次 schema 变更对现有 spec 的影响，以及迁移步骤。

技术债不会因为你无视它就消失，它只是在暗处等待一个合适的时机，一次性爆发。

6. 进阶实践：如何用 OpenSpec + Superpowers 构建跨团队协作的“契约中枢”

当 SDD+TDD 工作流在单个团队跑通后，真正的价值才开始显现：它能把原本割裂的前后端、产品、测试、运维团队，用同一份机器可读的契约连接起来。我们称之为“契约中枢”（Contract Hub）——它不是一个新工具，而是 OpenSpec 和 Superpowers 在组织层面的自然延伸。

6.1 前后端契约：用 OpenSpec 消灭“接口联调地狱”

传统联调，前端等后端 API 文档，后端等前端调用反馈，来回扯皮。用 OpenSpec，流程变成：

1. 产品和前后端共同评审src/specs/order/create.yaml，确认actor,context,outcome；
2. 后端基于 spec 生成 stub，实现create_order()函数；
3. 前端拿到同一份 spec，用superpowers generate-sdk --lang typescript生成：
   • OrderService.ts：包含createOrder()方法，参数类型严格匹配 spec 中的context；
   • OrderEvent.ts：定义order-created事件的 payload 结构；
   • mock-server.ts：一个 Express 服务器，能根据 spec 自动响应 mock 数据。

前端开发时，直接调用OrderService.createOrder()，它内部会连接到本地mock-server，返回完全符合 spec 的数据。后端还没写完？没关系，前端照常开发。后端写完了？只要openspec validate通过，前端代码无需修改就能对接真实 API——因为createOrder()的参数和返回类型，早已被 spec 锁定。

我们做过对比：一个 5 人前后端团队，传统联调平均耗时 3.2 天；采用契约中枢后，首次对接缩短到 4 小时，后续迭代联调时间趋近于零。

6.2 产品与开发契约：用 Superpowers 验证需求可行性

产品经理常提出“用户点击按钮，3 秒内看到结果”的需求，但没考虑技术约束。OpenSpec 让这种需求变得可验证：

• 在 spec 的outcome中添加performance: { max_duration_ms: 3000 }；
• Superpowers 在运行时，会自动为每个 outcome 动态注入计时逻辑；
• 如果update-db-row执行超过 3 秒，测试直接失败，并报告outcome 'update-db-row' exceeded max_duration_ms (3000ms), actual: 4217ms。

这迫使产品在需求阶段就思考：这个 3 秒，是端到端还是仅后端？是否允许降级？如果不行，是否需要加缓存？这些讨论，发生在代码编写之前，而不是上线后被用户投诉之后。

6.3 运维与开发契约：用 OpenSpec 定义 SLO 的机器可读版本

运维关注可用性、延迟、错误率，开发关注功能实现。OpenSpec 可以成为两者的共同语言：

• 在registry/slos/下定义payment-processing-slo.yaml：

  id: "payment-processing-slo" objective: "99.9% of payment requests succeed within 2s" metrics: - type: "error-rate" threshold: 0.001 # 0.1% datasource: "prometheus.error-count" - type: "p99-latency" threshold: 2000 # 2s datasource: "prometheus.latency-p99"

• Superpowers 的slo-monitorskill，会定期拉取这些指标，与阈值对比；
• 当error-rate超过 0.001，自动触发alert-oncallskill，发送告警；
• 当p99-latency超过 2000ms，触发scale-up-serviceskill，调整 Kubernetes HPA 配置。

SLO 不再是 PDF 报告里的数字，而是活在代码仓库里、被持续验证、自动响应的契约。

我的体会是：OpenSpec + Superpowers 的终极价值，不是让开发更快，而是让组织更少地开会。当一份 spec 文件能同时回答“产品想要什么”、“前端怎么调用”、“后端怎么实现”、“测试怎么验证”、“运维怎么监控”，沟通成本就从“人找人”变成了“人查文件”。我们