tech-spec

技术规范

技术规范是带类型的调用栈架构交接文档：包含代码形态的契约和执行流程。凡是精确性至关重要的地方，优先使用 TypeScript 伪代码，而不是散文。

此技能仅用于设计。不要实现。仅在用户要求提供文件时才保存文件；否则直接以内联形式返回规范。

分支选择

1. 当对话、文档或代码库中已有足够背景来描述变更时，使用路径 A：将上下文转换为规范。
2. 当用户想要新的规范，但未提供足够的问题描述、约束、设计方向、受影响代码或验收标准时，使用路径 B：先提问。

如果可以通过探索代码库来回答问题，就先检查代码库，而不是提问。

完成标准：根据实际可用的上下文选择分支；不得凭空臆造缺失的架构决策。

路径 A：将上下文转换为规范

1. 加载规范和本地上下文

检查现有代码和文档，了解本地词汇、模块布局、领域概念、错误、适配器、可观测性、运行时模式和测试风格。

完成标准：规范采用项目词汇；在检查本地先例之前，不引入新的模式、库、适配器、架构风格或测试策略。

2. 提取设计问题

记录：

• 当前状态；
• 问题；
• 用户／调用方；
• 目标；
• 非目标；
• 约束；
• 不变量；
• 受影响的系统；
• 可能的入口点；
• 运维／运行时相关事项；
• 风险；
• 待解决问题。

将未知事项标记为待解决问题，而不是用看似合理的设计填补空白。

完成标准：每项陈述的需求或约束都有对话、代码、文档或明确的待解决问题作为依据。

3. 探索设计备选方案

在选定推荐设计之前，先提出存在实质差异的备选方案。备选方案应在接口形态、接缝位置、所有权、调用栈、运行时拓扑或模块边界上有所不同，而不只是名称不同。

针对每个备选方案，概述：

• 领域类型和状态模型；
• 公共／模块接口和 API；
• 输入／输出类型；
• 预期失败类型；
• 接缝、边界和适配器；
• 从入口点到副作用的调用栈；
• 解析／投影策略；
• 可达时的授权、可观测性、取消、幂等性和事务流程；
• 测试接缝策略；
• 权衡。

比较各备选方案的：

• 调用方负担；
• 模块深度和杠杆效应；
• 不变量和变更的局部性；
• 接缝位置；
• 边界解析和投影；
• 错误和取消模型；
• 通过真实接缝进行测试的能力；
• 运维／运行时适配性；
• 实现复杂度。

完成标准：先比较备选方案，再选择推荐方案。

4. 明确推荐方案的带类型契约

针对推荐设计，概述所有新增、变更或删除的：

• 领域值；
• 品牌化／精化类型；
• 状态机变体；
• 输入／输出类型；
• 请求／响应结构；
• 函数签名；
• 类或模块接口；
• 预期失败／自定义错误类型；
• 适配器接口；
• 协议 DTO；
• 持久化 DTO／投影；
• 运行时边界编解码器；
• 公共 API。

命名接缝、适配器、实现、所有权边界，并说明每个边界上会传递什么。说明每一层可以了解什么，以及哪些内容不得泄漏到接缝之外。

完成标准：每个新增或变更的边界都有具体的类型／接口／API 草图，或明确说明为何无需新契约。

5. 说明调用栈和数据流

对于每个新增、变更或删除的行为，展示从入口点到副作用再到响应的调用栈。

包含类型／数据流：

raw input
  -> boundary DTO / unknown
  -> parser
  -> canonical domain/application input
  -> service/module interface
  -> adapter call
  -> typed result/error
  -> projection
  -> serialized output

变更现有行为时，包含当前流程与提议流程的对比。涉及失败、重试、取消、事务性、幂等性、可观测性、授权和运行时跳转时，也包含相应流程。

完成标准：每个受影响的行为都有端到端调用栈和类型／数据流追踪。

6. 列出文件和模块

列出：

• 要新增的文件／模块；
• 要修改的文件／模块；
• 要删除的文件／模块（如有）；
• 测试文件；
• 配置／迁移／运行时文件（如有）。

对于每个文件，说明它负责的契约、代码路径、边界、适配器、领域概念或测试职责。

完成标准：每项契约和调用栈步骤都对应到一个文件／模块或一个待解决问题。

7. 编写 RGR TDD 测试计划

遵循同级 TDD 工作流和测试标准。规划纵向 Red-Green-Refactor 切片：先编写一个失败的行为测试，再实现最小改动，然后重复。不要采用横向的“先写完所有测试，再写所有代码”计划。

优先通过公共接口和真实接缝测试行为，而不是使用与实现耦合的模拟。

按比例覆盖：

• 成功路径；
• 失败路径；
• 解析器拒绝的形状和接受的形状；
• 领域不变量和状态转换；
• 适配器契约；
• 持久化／运行时语义；
• 取消／重试／幂等路径；
• 相关的可观测性和安全摘要；
• 影响重大的行为端到端流程。

完成标准：每项公共行为、不变量、重要失败路径、变更的边界和变更的接缝，都有一个红色测试切片，或明确说明不测试的理由。

8. 生成规格

除非用户要求提供文件路径，否则直接在回复中输出规格。如果用户指定了文件路径，则保存到该路径。

不要实现，也不要默认询问是否要实现。

完成标准：输出遵循下方大纲，且另一位工程师可据此直接开始实现。

路径 B：先深入访谈

1. 暂不编写完整规格。
   • 说明当前上下文不足以编写可直接用于实现的技术规格。
   • 完成标准：Agent 没有臆造需求、API、文件或调用栈。
2. 开始深入访谈。
   • 一次只问一个问题，并在每个问题中提供建议答案。
   • 如果可以通过探索代码库回答问题，则检查代码库，而不是提问。
   • 完成标准：访谈已获取路径 A 所需的充分上下文：问题、用户／调用方、约束、受影响的系统、期望行为、边界、可能的 API、不变量、风险和验收测试。
3. 转为规格。
   • 访谈上下文充分后，执行路径 A。
   • 完成标准：最终产物是带类型的调用栈架构交接文档，而不是访谈笔记。

规定的规格大纲

除非任务足够简单，可在不丢失契约或调用栈的前提下精简，否则使用以下结构：

# <Title>

## Summary

## Context / Current State

## Goals

## Non-Goals

## Invariants

## Design Constraints

## Alternatives Considered

### Option 1: <name>

### Option 2: <name>

### Option 3: <name>

## Recommendation

## Proposed Design

## Domain Model and Types

## Types, Interfaces, and APIs

## Seams, Boundaries, Adapters, and Implementations

## Call Stacks and Data Flow

### Current / Old Flow

### Proposed / New Flow

### Failure Flow

### Retry / Cancellation / Idempotency Flow

### Observability Flow

## Files to Add / Change / Delete

## RGR TDD Test Plan

## Risks and Open Questions

仅省略确实不适用的章节；不要仅仅因为难以明确说明，就省略带类型的契约、接缝、调用栈或测试。

写作规则

• 代码优先：使用 TypeScript 伪代码定义契约、API 和数据流。
• 文字说明原因；类型和调用栈定义变更内容。
• 聚焦类型、接口、API、输入／输出、接缝、边界、适配器、领域模块、服务模块、外部适配器和调用栈。
• 优先使用精确的领域值，而不是字符串、布尔值、可空对象包或形状松散的对象。
• 保持接缝真实：适配器用于转换框架、持久化、网络、时间、随机性、遥测、运行时或平台边界。
• 避免推测性抽象；每个接缝都必须通过不变量、局部性、复用价值、可测试性或真实边界证明其存在必要性。
• 保持单一事实来源；不要在多个章节重复同一规则，除非一个章节指向另一个章节。
• 未知事项应保留为开放问题。不要为了让规格看起来完整而臆造产品需求、领域规则、API 或调用栈。