go-backend-technical-design

Go Backend Technical Design

Use after requirements analysis is complete and stable, to plan implementation details.

When to Use

• The user says "produce a technical solution" / "technical design" / "design this feature"
• Requirements analysis is complete and entering the implementation planning stage
• The package structure, interface contracts, storage solution, and transaction boundaries need to be determined
• Features involving cross-service integration, asynchronous tasks, or complex consistency requirements

Input

Locate the requirements document by priority:

1. Conversation context: If the current session already contains the requirements analysis results, use them directly without reading files
2. User-provided path: The user specified a document path in the message, read it directly
3. Auto-discovery: Search the current working directory for the most recently modified requirements document

# 自动发现：查找最近修改的需求文档
ls -t $(find . -maxdepth 3 \( -name "*requirement*" -o -name "*需求*" \) -name "*.md" 2>/dev/null) 2>/dev/null | head -5

If auto-discovery finds multiple candidate files, list them and ask the user to confirm which one to use. If no file is found, prompt the user to provide a path or paste the requirements content in the current session.

Design-First Hard Rules

Before the technical design document is confirmed, entering the coding stage is prohibited.

• The technical design must cover the mapping of all Req# to implementation components
• The design document is considered approved only after the user explicitly confirms it ("OK" / "agree" / "you can start")
• If the user directly requests coding, first output a simplified design summary and wait for confirmation before starting to code; if the user explicitly skips it, mark it as SPEC-skipped, and focus on checking for deviation from requirements during subsequent review
• Design changes must update the document first, then the code

Goals

• Transform requirements into an executable design solution
• Keep the design concrete enough to support implementation planning
• Explicitly state trade-offs

Design Document Structure

Use the following structure:

# 技术设计

## 背景

## 需求映射表

| Req# | 设计组件 | 验证方式 |
|------|---------|---------|
| R1   | service.CreateOrder() | 单元测试: TestCreateOrder |
| R2   | middleware.RateLimiter | 集成测试: TestRateLimit |

## 变更影响摘要

| 变更范围 | 影响组件 | 影响评估 | 回滚方案 |
|----------|----------|----------|----------|
| 新增 API | transport 层 | 低风险，纯新增 | 关闭路由注册 |
| Schema 变更 | repository 层 | 需要迁移脚本 | 执行回滚迁移 |

## 设计方案（流程图）

## 包与职责划分

## API 或 RPC 契约

## 数据模型与持久化

## 一致性与事务模型

## 错误模型

## 可观测性

## 安全控制

## 发布与回滚

## 备选方案

Requirements Deviation Management

A technical design may simplify or phase requirements based on engineering judgment, butmust not silently discard requirements：

• For every Req# and AC# in the requirements document, the design document must have corresponding handling (implemented / explicitly deferred / explicitly rejected)
• If the design simplifies a requirement (e.g., removing a parameter, reducing scenarios), it must be marked in the requirements mapping table or change impact summary:AC8: 延迟至后续迭代——理由：MVP 范围收窄 or R5: 设计拒绝——理由：...
• Entries that exist in the requirements document but have no trace in the design document are prohibited

Design Rules

Clear layering

A typical service defines the following layers:

• transport / handler layer
• application service layer
• domain logic layer
• repository / gateway layer
• background job layer (if any)

Write flows must be explicit

Each write operation flow must record:

• validation
• authentication
• domain checks
• persistence
• asynchronous side effects
• response mapping

Failure paths are as important as success paths

Always clarify:

• Retry ownership (who is responsible for retrying)
• Timeout ownership (who sets the timeout)
• Idempotency key or deduplication strategy
• Partial failure behavior
• Compensation mechanism (if needed)

Go-specific checklist

• context.Context Is it passed all the way from the entry point to downstream calls?
• Are interfaces introduced only at dependency boundaries?
• Are transactions narrowed to the smallest possible scope?
• Do goroutines have boundaries, support cancellation, and provide observability?
• Is shared mutable state synchronized or avoided?
• Are error types and wrapping rules defined?
• Is configuration ownership clear?

Recommended package structure

Adopt only when suitable for the current repository:

internal/
  transport/http/
  app/
  domain/
  repository/
  jobs/
  platform/

References

• Gin HTTP service, see references/gin-http.md
• gRPC-first service, see references/grpc.md
• Heavy storage changes, see references/persistence.md

Handover

After the design document output is complete, inform the user at the end of the conversation of the optional next steps,wait for explicit user instruction before continuing, and do not automatically proceed to the next phase：

• /go-backend-architecture — when the system boundary or evolution path has not yet been determined (optional)
• /go-backend-reviewer — review the code against this design after implementation is complete