| name | go-backend-technical-design |
| description | Go 后端技术设计：包边界、handler-service-repository 分层、API 契约、存储设计、事务、一致性、可观测性、发布策略与 ADR 权衡。需求稳定后使用。 |
| allowed-tools | Read, Bash, Glob, Grep |
| disable-model-invocation | true |
| context | fork |
Go 后端技术设计
需求分析完成且稳定后使用，用于规划实现细节。
适用时机
- 用户说"出一个技术方案" / "technical design" / "设计一下这个功能"
- 需求分析已完成，进入实现规划阶段
- 需要确定包结构、接口契约、存储方案、事务边界
- 涉及跨服务集成、异步任务或复杂一致性要求的功能
输入
按优先级定位需求文档：
- 对话上下文：若当前会话已包含需求分析结果，直接使用，无需读取文件
- 用户提供路径：用户在消息中指定了文档路径，直接读取
- 自动发现：在当前工作目录中查找最近修改的需求文档
ls -t $(find . -maxdepth 3 \( -name "*requirement*" -o -name "*需求*" \) -name "*.md" 2>/dev/null) 2>/dev/null | head -5
若自动发现到多个候选文件，列出并让用户确认使用哪份。若未找到任何文件，提示用户提供路径或在当前会话中粘贴需求内容。
设计先行硬规则
在技术设计文档得到确认之前，禁止进入编码阶段。
- 技术设计必须覆盖所有 Req# 到实现组件的映射
- 设计文档需要用户显式确认（"OK" / "同意" / "可以开始"）后才视为已批准
- 如果用户直接要求编码，先输出简化设计摘要并等待确认，再开始编码；如用户明确跳过，标记为
SPEC-skipped，后续 review 时重点检查是否偏离需求
- 设计变更必须先更新文档再更新代码
目标
- 将需求转化为可执行的设计方案
- 保持设计的具体性，足以支撑实现规划
- 显式说明权衡取舍
设计文档结构
使用以下结构：
# 技术设计
## 背景
## 需求映射表
| Req# | 设计组件 | 验证方式 |
|------|---------|---------|
| R1 | service.CreateOrder() | 单元测试: TestCreateOrder |
| R2 | middleware.RateLimiter | 集成测试: TestRateLimit |
## 变更影响摘要
| 变更范围 | 影响组件 | 影响评估 | 回滚方案 |
|----------|----------|----------|----------|
| 新增 API | transport 层 | 低风险，纯新增 | 关闭路由注册 |
| Schema 变更 | repository 层 | 需要迁移脚本 | 执行回滚迁移 |
## 设计方案（流程图）
## 包与职责划分
## API 或 RPC 契约
## 数据模型与持久化
## 一致性与事务模型
## 错误模型
## 可观测性
## 安全控制
## 发布与回滚
## 备选方案
需求差异管理
技术设计可以基于工程判断对需求做简化或分期，但不得静默丢弃需求：
- 对需求文档中每条 Req# 和 AC#，设计文档必须有对应处理（实现 / 显式延迟 / 显式拒绝）
- 若设计简化了某条需求（如移除参数、缩减场景），必须在需求映射表或变更影响摘要中标注：
AC8: 延迟至后续迭代——理由：MVP 范围收窄 或 R5: 设计拒绝——理由：...
- 禁止出现需求文档有但设计文档中无踪迹的条目
设计规则
分层明确
典型服务定义以下层次：
- transport / handler 层
- application service 层
- domain logic 层
- repository / gateway 层
- 后台任务层（如有）
写流程必须显式
每个写操作流程需记录：
- 校验
- 鉴权
- 领域检查
- 持久化
- 异步副作用
- 响应映射
失败路径与成功路径同等重要
始终明确：
- 重试归属（谁负责重试）
- 超时归属（谁设置超时）
- 幂等键或去重策略
- 部分失败行为
- 补偿机制（如需要）
Go 专项清单
context.Context 是否从入口一路传递到下游调用？- 接口是否只在依赖边界引入？
- 事务是否收窄到最小范围？
- goroutine 是否有边界、可取消、可观测？
- 共享可变状态是否同步或已避免？
- 错误类型与包装规则是否已定义？
- 配置归属是否明确？
推荐包结构
仅在适合当前仓库时采用：
internal/
transport/http/
app/
domain/
repository/
jobs/
platform/
参考资料
- Gin HTTP 服务，参见
references/gin-http.md
- gRPC 优先服务，参见
references/grpc.md
- 存储变更较重，参见
references/persistence.md
交接
设计文档输出完成后，在对话末尾告知用户可选的后续步骤，等待用户明确指示后再继续，不得自动进入下一阶段：
/go-backend-architecture — 系统边界或演进路径尚未确定时（可选）/go-backend-reviewer — 实现完成后对照本设计进行代码审查
