用途:在写实现前冻结 API 合约,而非写 API 实现。适用定义新端点、修改既有端点合约、设计跨服务 HTTP 合约。
主要能力:产出端点列表(method+path+认证+权限)、Request/Response DTO、错误码列表、权限规则、分页/排序/过滤规则、幂等与并发控制规则、Zod/TypeScript/OpenAPI schema、合约测试最低覆盖。设计顺序为资源→endpoint→Request DTO→Response DTO→错误码→权限→分页/排序/过滤→幂等/并发→schema→合约测试→再实现。
核心约定:遵循 HTTP method 语义,URL 用资源名词;错误统一为 { error: { code, message, details, requestId } };Response 经 Output DTO 白名单转换,不直出 DB model;边界验证格式、领域保护规则;有副作用可重试的 POST 评估 Idempotency-Key,冲突返回 409;PATCH/PUT 评估 version/ETag 并发控制;列表必须分页并有默认排序。
前置加载 CANNON.md 与 build-quality-tdd/SKILL.md;接口稳定后进入 build-workflow-execute。
限制:不用于仅实现既有 API、修内部 bug、查询优化、补文档、纯内部重构;数据库设计改用 build-backend-database,GraphQL 与事件合约另有专门 Skill。