zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/.agents/skills/contract-first-development.md
lili a207cb8d65
Some checks failed
contract-gates / contract-gates (push) Has been cancelled
Details
docs-gate / docs-gate (push) Has been cancelled
Details
docs(agents): skill 规范化双层收口 + 席位context skill 新增 + W-NSTAR/W-TPL/W-GENLOG 设计波落档 
- .agents/skills 25 件全量 frontmatter 规范化与评审修入(含 prompt-governance 大修);.claude/skills 7 件薄壳按双层方案①落位
- 新增 skill:agentic-seat-context-design(agentic 席位与 context 工程设计基线,2026-07-05 探索蒸馏)
- 设计波三件落档:复杂游戏北极星件(W-NSTAR 终审稿待拍)/黄金模板规格件(W-TPL 定稿待批)/生成侧过程蒸馏回路(W-GENLOG 骨架)
- protocol/在飞板/作战清单/数据飞轮 SoT/契约 prompts 索引同步;breakout 九门证据刷新
- .gitignore 补 /localagents.md 真实忽略行(该文件自声明绝不提交,此前声明未被机器执行)
- 刻意不入库:nacos-data/ 与 _tier2-gen、c2v-*、amgen-* 生成产物(可重生成,忽略行格式待拍)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 05:32:56 -07:00

6.9 KiB
Raw Blame History

name, description
name description
contract-first-development 当多工位(前端/后端/SDK/AI/数据)并行开发同一交付时使用:先锁 contracts/ 八类契约、各自按契约 mock 对方接口解耦并行、最后集中联调,含 Day-0 契约清单、mock 策略、真实对接切换与联调规则。

契约先行与并行解耦联调手册（contract-first-development）

蒸馏来源：docs/superpowers/specs/mvp-execution-spec-design.md（§3 契约先行 / §6 并行解耦与 Mock / §8.3 联调规则）、docs/architecture/架构/README.md（§6 联调协议）、docs/architecture/架构/README.md（§7.7 API 契约与版本）。 适用：多工位（前端/后端/SDK/AI/数据）并行开发同一交付时，先锁契约、再各自 mock 解耦、最后集中联调。 配套：工程规范（错误码/API 路径/-api 包）见 ../rules/engineering-conventions.md；新模块契约落地见 ./add-business-module.md；生成链路见 ./agentic-amodel-generation.md 与编排 ./saa-graph-orchestration.md；SDK 契约见 ./runtime-and-multichannel.md；任务协议见 ../workflows/ai-development-protocol.md。

目标

现状说明：方法论（先锁契约 → mock 并行 → 集中联调）现行有效；文中 Day-N / WS1–5 具体数字出自已降级为视图的三周 execution spec，日常排期按 16 周主计划波次走。

Day0（开发首日）半天全员锁定契约，写入 contracts/ 并提交 git；之后各工位基于契约 mock 对方接口独立开发，集中联调在 Day11 开始。把"等对方接口"的串行依赖，换成"对着契约并行"。

前置

  • 已读 ../knowledge/product-and-architecture.md，对齐 13 模块边界与端（/app vs /admin）。
  • 工位划分明确（MVP spec：WS1 基座 / WS2 AI / WS3 运行时+SDK / WS4 前端 / WS5 数据变现）。

1. 理念

Day0 上午（半天）：全员对齐 → 锁定 7 个 Day-0 契约文件 → 提交 git（里程碑 M0）
       ↓
Day1~Day10：各工位基于契约 mock 对方接口，独立并行开发
       ↓
Day11~Day12：集中联调（只联调、不加功能）

契约体系共 8 类契约：下列 7 个 Day-0 contracts/ 文件 + Prompt Registry（contracts/prompts/ 目录）为第 8 类（见 ./prompt-governance.md）。本手册聚焦 Day-0 锁定的 7 个文件。

契约一旦锁定即为各工位的"对接面"。变更契约必须同步 contracts/ 并通知相关方（见第 4 节）。

2. 7 个 Day-0 契约文件清单（第 8 类 Prompt Registry 见 prompt-governance.md）

契约文件 内容 负责人
contracts/api-schemas/*.yaml 所有模块 API 的 OpenAPI 3.0 定义（Request/Response） WS1 lead 主笔，全员 review
contracts/db-schemas/V1__*.sql 核心表结构（Flyway 迁移脚本） WS1
contracts/sdk-interface.d.ts WanxiangGameSDK 全部 public API 类型 + postMessage 协议 WS3 SDK 负责人
contracts/game-package.schema.json GamePackage manifest 格式 + 目录结构 WS3 + WS2
contracts/events.schema.json telemetry 事件名 + 字段（v1） WS5
contracts/dify-workflow-io.json（⚠️ 降级远期未部署，见 contracts/DEPRECATED-dify-workflow-io.md；现行生成主线=new-api 网关） Dify workflow 的输入/输出契约 WS2
contracts/ad-slot.schema.json 广告位配置格式 WS5

3. Mock 策略表

工位 依赖谁 Mock 方式 真实对接时间
WS4 前端 WS1/WS2/WS3/WS5 的 API vite-plugin-mock 基于契约 yaml 自动生成 Day6 起逐步替换
WS3 SDK WS4（宿主） 独立测试页模拟 postMessage Day6 集成
WS2 aigc WS1（project） 内存态写入 + MQ mock Day5 真实对接
WS5 telemetry WS3（SDK 上报） curl 模拟 /events/batch Day6 真实对接

4. 真实对接切换

场景 做法
前端 mock → 真实 API 改 .env 中 VITE_API_BASE_URL 即可（开发团队版 §6.1，MVP spec §8.3）
后端新增/变更 API 必须同步 contracts/api-schemas/ 并通知前端（MVP spec §8.3）
契约定义顺序 后端先写 -api 包的 VO/DTO，前端据此定义 TS 类型（开发团队版 §6.1）

"开发团队版"/"技术决策版" = 两版《系统概要设计》，已归档 _archive，节号按历史读；现行规范见 ../rules/engineering-conventions.md 与 docs/architecture/README.md。

API 演进规则：新增字段不算 breaking；删除/重命名字段 = 升版本（技术决策版 §7.7）。

5. 联调规则

规则 说明 出处
时间窗 Day11~Day12 预留 2 天，只联调不加新功能 MVP spec §6.3
主导与响应 前端主导提 bug，后端 30 分钟内响应 MVP spec §6.3
Bug 优先级 P0 当天必修；P1 联调期内修复 MVP spec §6.3
阻塞升级 阻塞 > 30 分钟立即升级到每日站会 MVP spec §6.2 / §8.3
每日站会 每天 10:00，每人 2 分钟（昨天/今天/阻塞点） MVP spec §6.2
问题跟踪 联调 bug 提 Issue，打标签 联调 + 模块名 开发团队版 §6.1

6. 联调速查

观察点 地址 / 工具
后端 API 文档 Swagger / Knife4j http://localhost:48080/doc.html
生成链路日志 Dify UI http://localhost:3001（已降级远期未部署）→ 现行=编排器批跑日志 git show 6d2f8789^:docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/(已删,git 可查) + new-api 网关 http://100.64.0.8:3000
SDK 事件流 game-studio 开发模式 DebugPanel（实时 postMessage 事件流，开发团队版 §6.3）

7. 常见坑

坑 后果 应对
契约偏差到联调才暴露 Day11 集中爆雷、返工 WS1 在 Day10 预留时间专门修对接时发现的契约偏差（MVP spec §4 Week1 Day10）；前端 Day6 起提前对接早暴露
契约变更未同步 前后端字段不一致、联调失败 任何 API 增改先改 contracts/ 再写代码，并通知相关方（MVP spec §8.3）
前端先于 -api 定 TS 类型 与后端 VO/DTO 错位 顺序固定：后端 -api VO/DTO 先行 → 前端据此定 TS（开发团队版 §6.1）
mock 与真实响应结构不一致 切真实 API 后页面崩 mock 严格依据契约 yaml 生成，不手捏假数据
阻塞硬扛不升级 拖垮整条链路进度 阻塞 > 30 分钟必升级站会，会后 10 分钟两人对齐（MVP spec §6.2）