feature-spec

技术规范

概述

一条结构化命令，通过引导用户完成架构决策、系统契约和技术设计，帮助创建简洁的技术规范文档，同时避免陷入实现细节。

遵循既定的功能开发流程创建技术规范文档。可用的完整上下文：

必读：

• 功能开发指南：@~/.local/share/dotfiles/ai/guides/feature-development-process.md
• 愿景文档：@vision.md
• 需求文档：@requirements.md

注意：如果项目在 @project/guides/feature-development-process.md 中有本地指南副本，也可以改为参考该副本，以了解项目特定的修改。

可用的其他上下文：

• 完整代码库：检查 backend/ 和 frontend/ 目录中的现有模式
• 实现指南：查看 backend/docs/guides/ 和 frontend/docs/guides/，了解既定模式
• 设计上下文：在相关情况下，使用可用的 MCP 连接访问设计系统

方法：利用所有可用上下文为技术决策提供依据。大多数实现模式和架构决策应通过分析现有代码库得出，而不是询问基本问题。

重要：首先创建 TODO 列表，用于跟踪规范编写的各个阶段（通常为 3 个阶段；如果功能涉及复杂的 UI/UX，可添加可选的第 4 阶段：设计简介）。将第一阶段标记为 "in_progress"，其余阶段标记为 "pending"。

技术规范结构

关键：规范定义的是架构和系统契约，而非实现细节。规范应简洁（5-10 页），聚焦于是什么和为什么，而不是如何编写代码。

规范包括：

• 架构概述：核心决策和系统结构
• 系统组件：包含哪些部分及其职责/契约
• 数据契约：类型定义（适用于前端/后端及其所用语言）、数据库架构、API 契约
• 配置架构：系统的配置方式（不包含详细示例）
• 集成模式：与现有系统的集成方式
• 质量属性：性能、可靠性、可维护性要求

规范不包括：

• ❌ 实现代码示例（应放在计划中）
• ❌ 逐步实现细节
• ❌ 对相同概念的重复解释

流程：按顺序完成以下 3 个阶段

阶段 1：上下文分析与范围确认

首先分析可用上下文，了解功能范围：

上下文分析：

1. 查看愿景和需求文档，了解功能范围
2. 检查代码库，识别现有模式和架构方法
3. 查看 backend/docs/guides/ 和 frontend/docs/guides/ 中的实现指南，寻找相关模式
4. 找出类似的现有功能，以遵循既定模式

范围确认——仅在必要时提出澄清问题：

• 根据需求，这似乎属于 [全栈/仅后端/仅前端/后台处理]——是否正确？
• 需求中未涵盖的任何具体实现约束或偏好吗？
• 这是一个完整的功能实现，还是特定阶段（例如，“阶段 1：后端基础”）？
• 除文档中所述内容外，是否还有与现有系统的集成要求？

目标：确认技术范围，并找出需要遵循的相关现有模式。

一次只问一个问题——等待回答后再继续。

阶段 2：使用现有模式进行实现设计

根据代码库分析和范围确认，遵循既有模式设计实现方案：

设计方法：

1. 遵循现有模式：将代码库中的类似功能用作模板
2. 采用既定约定：遵循实现指南中发现的模式
3. 利用现有系统：集成既有的 RBAC、多租户等系统
4. 提出具体问题：仅询问现有模式未涵盖的独特方面

对于后端/数据库工作：

• 遵循现有实体模式和关系来建模数据
• 使用适合所用语言的类型定义来定义服务契约
• 遵循既定的 REST 约定和响应格式来设计 API 端点
• 使用类型定义记录 API 请求/响应契约和数据结构
• 应用标准的授权权限和验证模式
• 搜索集成：确定搜索范围和索引策略
  • 搜索是否只需覆盖实体自身字段，还是也需覆盖关联实体数据？
  • 记录搜索配置方案
• 排序参数：记录可排序列和默认排序行为
  • 列出具体的可排序列
  • 指定默认排序顺序
• 多上下文注意事项：适用于跨多个应用上下文（内部/外部、管理员/用户等）的功能
  • 如果不同上下文需要不同数据，则创建单独的响应结构
  • 示例：面向外部的上下文可能会排除管理员上下文所需的内部字段
  • 始终明确区分上下文以实现安全隔离，即使目前它们相同
• 允许的参数：记录每个上下文允许使用的参数
  • 列出可创建/更新的字段
  • 注明所有排除的字段（自动生成、计算得出或受限字段）
• 多上下文授权：对于具有多个上下文的功能，定义每个上下文的权限
  • 内部上下文：完整的 CRUD 权限
  • 外部上下文：有限权限（通常为只读）
  • 公共 API：可能使用不同的身份验证方式（API 密钥与会话身份验证）
  • 相同的权限名称可存在于多个上下文中，但作用范围不同
• 询问：类似功能中未出现的独特业务逻辑、约束或数据关系有哪些？

对于前端/UI 工作：

• 遵循现有 UI 组件架构和数据契约模式
• 使用既定的响应式设计和导航集成方案
• 采用标准的设计系统和组件库用法
• 类型组织：确定类型应针对特定上下文，还是共享
  • 上下文专用类型：当应用的不同部分需要不同的数据结构时使用
  • 共享/核心类型：仅用于所有上下文真正共享的类型
  • 请求负载类型：与使用它们的代码放在一起
• 询问：不同上下文是否需要相同的数据结构，还是需要不同的子集？
• 询问：是否有独特的 UI 交互或集成要求？

对于后台处理：

• 遵循现有的任务处理和调度模式
• 采用标准的错误处理和监控方案
• 询问：是否有独特的处理需求或时间限制？

目标：利用现有代码库模式，仅询问独特的实现方面。

阶段 3：创建规范文档

目标：创建一份简洁（5-10 页）、侧重架构的规范文档， 聚焦系统设计和契约。

建议的章节顺序：

组织章节，使内容从基础数据自然过渡到后端，再到前端，方便各领域人员连续阅读：

1. 概述 - 通用背景（所有人阅读）
2. 架构概述 - 核心设计决策（所有人阅读）
3. 数据架构 - 数据库架构、模型、验证（后端从此处开始）
4. API 架构 - 端点、请求/响应契约（后端继续阅读）
5. 授权架构 - 权限、策略（后端继续阅读）
6. 集成架构 - 搜索、审计、文档、外部系统（后端继续阅读）
7. 前端架构 - 类型、组件、页面（前端阅读，并根据需要参考 API 部分）
8. 设计与 UX 要求 - 设计简报参考和开发摘要（设计师 + 前端）
9. 配置架构 - 设置、功能标志（支持性事项）
10. 文件组织 - 文件存放位置（支持性事项）
11. 质量属性 - 性能、安全性、可靠性（支持性事项）

此流程的优势：

• 连续阅读：后端开发人员阅读第 1-6 节，前端开发人员阅读第 1-2 节和第 7-8 节
• 自然递进：数据层 → 后端 → 表现层 → 支持性事项
• 无需跳读：每个专业方向的内容都集中在一个部分
• 共享基础：所有人都从概述和架构背景开始

灵活性：省略与功能无关的部分（例如，仅涉及后端的功能可跳过前端/设计部分）。

---

需要包含的关键部分（各部分类型的详细信息）：

• API 架构（涉及后端/API 工作时）：
  • 端点定义（路由、参数、查询参数、可排序列）
  • 请求/响应契约（仅限后端 - 结构和格式）
    • 列出响应模板/序列化器文件（架构）
    • 展示各上下文的实体结构（契约）
    • 展示响应包装器（集合/单个实体模式）
    • 展示请求负载示例
    • 记录允许的属性
    • 不要包含实现代码——那属于计划的内容
    • 将后端契约与前端类型分开
• 授权架构（需要授权时）：
  • 权限定义（按上下文区分）
    • 内部上下文权限（完全访问类别）
    • 外部上下文权限（受限访问类别）
    • 说明公共 API 是否使用不同的身份验证方式
  • 授权策略契约（为每个上下文定义类型）
    • 按上下文命名策略：“内部策略”、“外部策略”
    • 公共 API：可使用 API 密钥身份验证，而非基于角色的身份验证
    • 添加引用权限部分的授权说明（不要重复列出权限）
• 前端架构（涉及 UI 工作时）：
  • 类型定义（使用前端语言的类型系统）
    • 实体接口（不同上下文分别定义）
    • 响应包装器类型
    • 请求负载类型（与用法放在一起）
    • 区分上下文的类型与共享类型的决策
  • 组件、模块、页面（按上下文组织）
    • 每个上下文部分都以“文件摘要”开头（路由、页面、模块、类型、组件）
    • 接着是“详细说明”，介绍实现细节
    • 文件摘要为开发人员提供便于快速查阅的速查表 规范内容指南：
• 包含目录，并按照 Markdown 标准对章节进行系统编号（1.1、1.2、2.1、2.2 等）
• 架构概览：核心决策、技术选型、系统结构
• 系统组件：使用适合所用语言的类型定义，明确组件的职责与契约
• 数据架构：数据库架构、API 契约、事件结构——展示形状与契约，而非实现
• 配置架构：组件的配置方式（环境变量、配置文件）——无需提供详细示例
• 文件组织：说明组件所在位置及原因
• 质量属性：性能、可靠性、可维护性方面的考量
• 集成模式：说明与现有系统的连接方式
• 需求交叉引用：引用需求时使用需求 ID （例如：“实现 REQ-2.1.1”“满足 US-1.1.2”“符合 SC-3”）

后端 API 响应设计（请求/响应契约）：

• ✅ 聚焦响应结构：展示响应应是什么样子，而非如何构建
• ✅ 文件架构：列出响应模板/序列化器文件，说明逻辑所在位置
• ✅ 响应示例：针对每种上下文提供具体示例
• ✅ 纯后端聚焦：前端类型与后端契约分开
• ✅ 按上下文区分：对于包含多种上下文的功能，展示独立契约
  • 示例：内部 API 实体（包含完整数据和内部字段）
  • 示例：外部 API 实体（数据有限，仅包含公开字段）
  • 示例：公共 API 实体（如与外部 API 实体不同）
• ✅ 包装模式：展示实体的包装方式（例如 data 和 metadata 键）
• ✅ 标准模式：引用标准分页/筛选模式，无需逐一列出所有字段
• ❌ 不包含实现代码：实现细节留到计划中
• ❌ 不重复示例：引用前面的契约，而非重复展示

前端类型定义：

• ✅ 按上下文区分类型：数据结构不同时，按上下文组织类型
  • 内部上下文可能需要包含所有字段的完整实体
  • 外部上下文可能需要字段有限的简化实体
• ✅ 共享类型：只有真正适用于所有上下文的通用类型才使用共享/核心类型
• ✅ 请求负载类型：与使用它们的代码放在一起，而非放入单独的类型文件
  • 遵循适合所用框架的命名模式
• ✅ 匹配后端结构：前端类型应与后端响应完全一致
• ✅ 包含导入语句：展示共享类型的正确导入语句

写作指南：

• ✅ 保持简洁：每个概念只解释一次，不重复
• ✅ 聚焦契约：类型定义、数据库架构、API 结构
• ✅ 架构决策：说明要构建什么以及为什么，而非如何编码
• ✅ 结构清晰：按概览 → 组件 → 集成的逻辑顺序组织
• ✅ 分离后端与前端：API 章节只涵盖后端（响应结构），前端章节只涵盖前端（类型）
• ❌ 不包含实现代码：不提供详细代码示例（留给实现计划）
• ❌ 不重复示例：某种模式展示一次后，不再重复展示
• ❌ 保持分层清晰：API 契约与前端类型分开

第 4 阶段：创建设计简报（可选）

创建时机：包含 UI/UX 组件且需要与设计师协作的功能。

跳过时机：

• 仅涉及后端的功能
• 遵循既定模式的简单 UI 更新
• 需求中已包含充足设计细节的功能

目标：将与设计相关的信息提取到独立文档中，让设计师无需翻阅需求和规格说明。

设计简报内容（design-brief.md）：

• 页面清单：需要设计哪些页面／屏幕
• 组件需求：需要哪些组件，以及这些组件要显示哪些数据（使用通俗语言，不写代码）
• 交互模式：关键交互的用户流程
• 表单字段：字段、标签、验证规则和帮助文本
• 响应式设计注意事项：移动优先、断点、无障碍设计
• 设计交付物：设计师应提供给开发人员的内容

编写指南：

• ✅ 通俗易懂：不写代码，不使用技术术语
• ✅ 数据需求：“组件显示：标题、日期、地点”，而非实现细节
• ✅ 独立完整：设计师无需查阅需求文档
• ✅ 可执行：每个部分都能帮助设计师做出决策
• ❌ 不要指定颜色：让设计师自行做出视觉选择
• ❌ 不要包含后端细节：聚焦用户看到和操作的内容

规格说明集成：在 spec.md 中添加简短章节，引用完整的设计简报，并为开发人员提供快速摘要。

更新 discussion-summary.md

生成规格说明文档后，更新讨论摘要：

• 检查功能目录中是否存在 discussion-summary.md
• 如果存在：添加一个“规格说明阶段”章节，包含：
  • 架构决策及其理由
  • 探讨并选定的技术方案
  • 规格说明阶段开展的技术调研
  • 将规格说明阶段的决策添加到关键决策日志中（延续编号）
  • 将新引用的文件添加到技术上下文中
• 如果不存在：创建该文件，并包含完整结构以及早期阶段的占位内容

可供参考的代码库模式

在做出技术决策前，务必检查现有代码：

后端模式：

• API 响应：查看现有响应模板／序列化器，寻找包含多个字段的实体示例
• 响应包装器：检查实体的包装方式（数据和元数据模式）
• 搜索模式：了解搜索功能的实现方式
• 上下文分离：查找不同上下文需要不同响应时的现有模式

前端模式：

• 类型组织：查看现有类型文件中的实体和响应类型模式
• 数据变更：查看创建／更新操作的现有模式
• 特定上下文的类型：查看具有特定上下文类型和共享类型的现有功能
• 响应结构：了解前端类型如何与后端响应保持一致

授权模式：

• 权限组织：查看权限如何按上下文组织
• 特定上下文的权限：不同上下文中可能存在名称相同但范围不同的权限
• 策略结构：检查现有授权策略模式
• 公共 API：注意公共 API 是否使用不同的身份验证方式（API 密钥或会话）

实现指南

如果项目有实现指南，请引用这些指南，而不要在规格说明中包含实现代码。规格说明应说明需要实现什么，并引用相应指南来说明如何实现。

可考虑的常见指南主题：

• 搜索功能模式
• 文件上传和附件模式
• 审计跟踪 / 变更跟踪
• 多租户方案
• 基于角色的授权
• 状态机模式
• 测试模式和约定
• 身份验证策略
• 数据库迁移最佳实践

如何在规格说明中引用指南（如果项目有相关指南）：

• ✅ “请参阅实现指南，了解搜索配置详情”
• ✅ “遵循既定的文件附件处理模式”
• ✅ “请参阅授权指南，了解权限结构”
• ❌ 不要在规格说明中包含实现代码
• ❌ 不要在规格说明中重复指南内容

多上下文架构模式

当功能涉及多个应用上下文（内部、外部、公开）时，请遵循以下模式：

完全分离原则：

• 处理器 / 控制器：为每个上下文分别设置请求处理器
• 响应模板：为每个上下文分别设置响应结构，即使当前结构相同也不例外
• 授权：为每个上下文分别设置授权策略；公开 API 可以使用不同的身份验证方式
• 权限：为每个上下文定义权限，并设置适当的作用域
• 类型：当数据结构不同时，为每个上下文定义专用类型
• 路由：为每个上下文设置不同的路由命名空间或前缀

完全分离的原因：

• 安全性：防止上下文之间意外泄露数据
• 灵活性：每个上下文都可以独立演进
• 清晰性：明确的边界可以清楚表达意图
• 可维护性：对一个上下文的更改不会影响其他上下文

常见上下文模式：

• 内部 / 管理上下文：完整的 CRUD，包含管理和审计字段
• 外部 / 用户上下文：操作受限，不包含内部字段
• 公开 API：通常限制最多，可能使用不同的身份验证方式（API 密钥而非会话）

应避免的常见规格说明陷阱

后端 / API 部分的陷阱

❌ 展示实现代码 - 展示响应结构，而不是如何构建它
❌ 混合层级 - API 部分应仅包含后端内容，前端类型应单独列出
❌ 过度设计搜索 - 仅在确有需要时添加复杂搜索
❌ 不必要的字段 - 确认审计 / 时间戳字段是否应包含在 API 响应中
❌ 逐一说明标准模式 - 引用标准模式即可，无需重复细节
❌ 参数位置错误 - 在授权层中记录允许的属性
❌ 跨上下文复用结构 - 始终创建独立结构以确保安全
❌ 缺少上下文授权 - 为所有上下文定义权限
❌ 笼统地说“所有内容都可排序” - 列出具体可排序的列
❌ 身份验证不一致 - 记录各上下文采用的不同身份验证方式

前端 / 类型部分的陷阱

❌ 为上下文专属数据使用共享类型 - 不同上下文通常需要不同的类型结构
❌ 集中定义请求类型 - 将请求类型与其使用位置放在一起
❌ 重复定义类型 - 不要在 API 和前端部分重复定义类型
❌ 缺少导入 - 类型定义需要正确的导入语句
❌ 未使用的导入 - 仅导入实际使用的类型
❌ 缺少文件摘要部分 - 每个上下文开头都应提供快速参考速查表

规格说明的常见陷阱

❌ 实现代码过多 - 规格说明定义约定，计划定义实现
❌ 重复示例 - 只展示一次模式，并在其他地方引用
❌ 缺少架构说明 - 说明为何需要分离（安全性、隔离）
❌ 重复列出权限 - 引用“权限定义”部分，不要重复列出

指南

• 上下文优先：提问前始终先分析现有代码库模式和实施指南
• 精准提问：只询问现有模式未涵盖的独特方面
• 遵循模式：技术决策应基于代码库中已确立的约定
• 关注架构：定义系统结构和契约，而非实施步骤
• 沟通简洁：清晰地解释每个概念一次，避免重复
• 尽量减少交互：充分利用上下文，减少来回提问
• 随各阶段完成更新 TODO 列表
• 阶段 1：分析上下文并确认范围，而非进行基础探索
• 阶段 2：使用现有模式进行设计，只询问独特方面
• 阶段 3：创建架构规范，说明系统契约和决策
• 阶段 4（可选）：对于 UI/UX 复杂的功能，创建设计简报，为设计师提供独立文档
• 业务上下文：参考愿景和需求以便理解，而非用于追溯
• 注重实用：设计可立即构建且采用成熟模式的解决方案
• 后端/前端分离：将后端契约与前端类型分开

开始流程

1. 立即创建 TODO 列表（3 个阶段；如需设计简报，则为 4 个阶段）
2. 询问用户：“你正在处理哪个功能目录？请提供完整路径（例如，project/features/FT033-feature-name）”
3. 询问用户：“请将愿景文档标记为 @vision.md，并将需求文档标记为 @requirements.md”
4. 验证目录是否存在，并确认将在何处创建 spec.md
5. 查看愿景和需求文档，了解功能上下文
6. 进入阶段 1，提出第一个技术探索问题
7. 聚焦提问，并等待回答后再继续提问