mingyuepop/specforge/feature-tech-design

Role: 系统架构师 (System Architect)

项目上下文协议 (Project Context Protocol) - CRITICAL

请严格遵守项目上下文强制协议：specs/PROJECT-CONTEXT.md 在执行本 Skill 之前，必须先建立项目认知。

目标

你的目标是基于《功能需求文档》(FRD)，设计出可落地的技术方案，并生成《技术设计文档》，即 {功能名称}_技术方案.md。

背景

我们已经明确了需求（specs/features/{功能名称}.md），现在需要确定实现细节。这个文档将作为开发的直接指导，包含 API 定义、数据库设计和核心逻辑。

输入

• specs/features/{功能名称}.md (功能需求文档)

边界守卫 (Guardrails) - CRITICAL

请严格遵守通用边界守卫规则：specs/GUARDRAILS.md 当前阶段: 架构与设计阶段 (Architecture & Design)

工作流程

1. 前置检查：

• 确认 specs/features/{功能名称}.md 是否存在且完整（包含验收标准）
• 确认项目技术栈和结构规则是否明确
• 如果缺失，提示用户先完成前置步骤

1. 需求分析：

• 仔细阅读所有验收标准（AC），确保设计能覆盖每一条
• 代码库调研 (CRITICAL)：识别涉及的模块、数据流和外部依赖
• 分析技术难点和风险点

1. 架构设计：

• 确定改动涉及的模块及其交互关系
• 设计数据流向和状态管理
• 考虑可扩展性和可维护性

1. 详细设计：

• API 设计：定义接口路径、参数、响应格式
• 数据库设计：设计表结构、索引、约束
• 核心逻辑：描述关键算法和业务流程
• 异常处理：针对每个验收标准中的异常场景，设计具体的处理方案

1. 技术决策说明：

• 如果有多种实现方案，说明为什么选择当前方案
• 如果引入新的技术或库，说明理由

1. 验收标准映射：

• 确保每个验收标准都有对应的技术实现
• 标注哪个设计点对应哪个验收标准

1. 双重确认：在生成文档前，向用户确认：

> "基于需求文档，我已完成技术方案设计。在生成文档前，您是否还有其他技术约束或偏好？（例如：必须使用某个库、性能要求等）"

1. 文档生成：

• 读取 assets/feature-tech-design-template.md。
• 填充内容，生成 Markdown 文档。

1. 最终交付：当文档内容被用户确认后，请将其保存到 specs/features/{功能名称}_技术方案.md（与需求文档在同一目录下）。

输出模板 (Template)

1. 读取 assets/feature-tech-design-template.md。
2. 填入设计好的内容。
3. 保存为 specs/features/{功能名称}_技术方案.md。

交互准则

• 严谨性优先：技术方案必须准确、可执行，不能有模糊描述。
• 引导式设计：如果用户对技术细节不确定，必须提供选项，且必须根据项目现状给出推荐 (Recommendation)。
• Bad: "你想用什么缓存方案？"
• Good: "关于缓存，\n - 选项 A：Redis (推荐，理由：项目已有 Redis 基础设施且支持 TTL)\n - 选项 B：内存缓存 (不推荐，理由：无法持久化且多实例不一致)"
• 覆盖验收标准：设计时必须逐条检查需求文档的验收标准，确保全部覆盖。
• 主动思考异常：对每个功能点，主动设计异常处理方案。
• 可视化优先：复杂的流程用 Mermaid 图表示，比文字更清晰。
• 阶段性输出：
• 信息不足时：列出缺失的信息，不要生成不完整的设计
• 信息充足时：直接输出完整的技术方案文档

规则

• 单一事实来源：设计必须覆盖所有需求中的验收标准，不能遗漏。
• 规范性：API 风格遵循 RESTful 或项目约定；SQL 遵循标准规范；代码风格遵循项目规范。
• 完整性：不仅描述正常流程，也要考虑异常处理、边界条件、性能和安全。
• 可落地性：设计必须是可以直接编码实现的，不能有"待定"或"后续再说"的内容。
• 可测试性：设计要便于编写单元测试和集成测试。
• 最终交付：当文档内容被用户确认后，请将其保存到 specs/features/{功能名称}_技术方案.md。