fullstack-feature

资源

scripts/
  validate-feature-workflow.sh
references/
  phase-templates.md

全栈功能编排

此技能定义了跨越技术栈多个层级来实现完整功能的端到端工作流。它通过 7 个不同阶段编排专用 Agent，涵盖从需求澄清到交付的全过程。

何时使用此技能

当用户请求以下内容时，使用 fullstack-feature：

• 需要修改数据库、API 和 UI 的完整功能
• 包含测试和审查的端到端实现
• 涉及多个组件的新用户功能
• 任何描述为“构建 X”“添加 X 功能”“实现 X 能力”的需求

不要在以下情况使用此技能：

• 单层修改（仅 API 或仅 UI）
• Bug 修复（使用 bugfix 或 hotfix 技能）
• 仅代码审查（使用 review-scoring 技能）
• 不涉及新功能的重构

概览

全栈功能工作流包含 7 个阶段：

1. 理解 - 澄清需求、加载技能、确定受影响的层级
2. 基础（顺序执行）- 数据库架构/迁移、类型生成
3. 核心实现（并行执行）- API 端点、UI 组件、状态管理
4. 集成（顺序执行）- 将 UI 接入 API、将状态接入 UI、验证数据流
5. 质量（并行执行）- 测试、安全检查、无障碍检查
6. 审查（由运行时驱动）- 通过运行时 <gv> 指令，完成前序阶段中的 WRFC 链
7. 提交 + 记录 - 运行时发出 complete 指令后触发；执行 git commit、更新记忆/日志并向用户汇报

运行时引擎与 WRFC 链

运行时引擎会自动为每个工作 Agent 创建一个 WRFC（工作-审查-修复-完成）链。当 Agent 完成工作并发出 <gv> 标签时，运行时会：

1. 根据配置的 score_threshold 评估输出（默认值：goodvibes.json 中的 9.5）
2. 通过系统消息向编排器发出指令
3. 由编排器机械地执行这些指令

指令类型：

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

指令遵循规则（绝对）：

1. 立即执行：指令一到达就立即执行。绝不推迟、排队或延迟。
2. 优先执行：在采取任何其他行动之前执行指令。不得插入工具调用、启动其他 Agent 或先向用户发送消息。
3. 自主权终止：WRFC 链收到第一条指令后，编排器不再对该链拥有判断权。只能由指令驱动。
4. 运行时优先：运行时工作流逻辑始终优先于编排器的判断。如果指令要求审查，就进行审查；如果要求完成，就完成。

编排器不会手动启动审查者或修复 Agent。这些操作完全由运行时指令触发。

阶段 1：理解

目的

在启动工作 Agent 之前，确保你完全清楚需要构建什么。本阶段可避免因误解而浪费精力。

步骤

1. 与用户明确需求：

   • 请求的具体功能是什么？
   • 用户是谁，他们的目标是什么？
   • 验收标准是什么（如何判断任务已完成）？
   • 是否有特定限制（性能、无障碍、浏览器支持）？
   • 是否有需要遵循或避免的现有模式？

2. 确定受影响的层：

   • 数据库：新增表/列？迁移？
   • API：新增端点？修改现有端点？
   • 类型：新增类型定义？
   • UI：新增组件？修改现有组件？
   • 状态：新增状态管理？
   • 测试：单元测试、集成测试、端到端测试？

3. 加载相关结果技能：

   • 后端：trpc、prisma、postgresql、clerk、nextauth、graphql、rest-api-design
   • 前端：nextjs、react、tailwindcss、shadcn-ui、framer-motion
   • 协议：gather-plan-apply、review-scoring、goodvibes-memory

4. 检查 goodvibes 记忆：

   • .goodvibes/memory/decisions.json - 架构选择
   • .goodvibes/memory/patterns.json - 编码模式
   • .goodvibes/memory/failures.json - 需要避免的过往失败

5. 制定实现计划：

   • 将功能拆分为子任务
   • 确定子任务之间的依赖关系
   • 估算范围（涉及多少文件/组件）
   • 将子任务映射到各阶段（基础、核心、集成）

输出

在第 1 阶段结束时，必须具备：

• 需求文档（位于 memory/current-task.md）
• 受影响层列表（数据库、API、UI、测试）
• 实现计划（拆分后的子任务及其依赖关系）
• 已加载技能（可用的相关结果技能）

特定模式行为

Vibecoding：继续进入第 2 阶段前，先与用户确认。 Justvibes：需求明确时自动继续。（如有歧义，则暂停并请求澄清。）

第 2 阶段：基础（顺序执行）

目的

在构建任何上游代码之前，先建立数据模型和类型基础。这可以确保各层之间的类型安全和一致性。

步骤

1. 数据库架构（如有需要）：

   • 启动数据库 Agent 设计架构
   • 创建迁移文件
   • 运行迁移（开发环境）
   • 验证迁移成功

2. 类型生成（如果使用 Prisma/Drizzle 等）：

   • 运行 ORM 类型生成命令
   • 验证类型已生成
   • 提交生成的类型（如有必要）

3. 共享类型定义（如果不使用 ORM）：

   • 创建 src/types/[...].ts 文件
   • 定义实体、DTO、请求/响应类型
   • 从 barrel index.ts 导出

Agent 指令

数据库 Agent：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 使用 gather-plan-apply 协议
• 遵循现有架构模式（检查 memory/decisions.json）
• 为查询性能添加适当的索引
• 添加外键约束
• 使用时间戳（createdAt、updatedAt）
• 完成前测试迁移

工程师 Agent（类型生成）：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 运行类型生成命令
• 验证类型正确（抽查生成的代码）
• 运行 tsc，确认没有类型错误

明确的完成定义

• 数据库架构已创建，迁移已应用
• 类型已生成并导出
• npm run typecheck 通过
• 所有文件均已提交

特定模式行为

Vibecoding：在此阶段后设置检查点。使用提交信息 checkpoint: foundation - schema and types 提交。 Justvibes：自动继续到第 3 阶段。

第 3 阶段：核心实现（并行）

目的

并行实现 API 和 UI 层的主要功能，从而最大限度地提高吞吐量并减少等待时间。

子阶段

以下子阶段并行执行：

1. API 端点（API Agent）
2. UI 组件（UI Agent）
3. 状态管理（状态 Agent）

Agent 指令

API Agent：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 按照现有模式实现端点（查看 decisions.json 了解 API 风格）
• 添加输入验证（使用 Zod 或类似工具）
• 添加错误处理
• 添加身份验证／授权检查
• 使用 ORM 访问数据库
• 在适当的级别添加日志记录
• 使用 gather-plan-apply 协议

UI Agent：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 按照现有模式创建组件（查看 decisions.json 了解 UI 库）
• 遵循无障碍最佳实践（ARIA 属性、键盘导航）
• 实现响应式设计
• 添加加载和错误状态
• 优化性能（useMemo、useCallback）
• 使用 gather-plan-apply 协议

状态 Agent：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 按照现有模式实现状态管理（Zustand、Redux 等）
• 定义状态结构和操作
• 为派生状态添加选择器
• 根据需要添加持久化（localStorage、sessionStorage）
• 使用 gather-plan-apply 协议

明确的完成定义

• 所有 API 端点均已实现并通过验证
• 所有 UI 组件均已创建
• 已实现状态管理
• npm run typecheck 通过
• npm run lint 通过
• 所有文件均已提交

特定模式行为

Vibecoding：此阶段结束后设立检查点。提交时使用消息 checkpoint: core implementation。 Justvibes：自动进入阶段 4。

阶段 4：集成（顺序执行）

目的

将 UI 连接到 API，将状态接入 UI，并端到端验证数据流。此阶段必须按顺序执行，因为它依赖于阶段 3 的完成。

步骤

1. 将 UI 接入 API：

   • 在组件中添加 API 客户端调用
   • 处理 API 调用期间的加载状态
   • 处理 API 返回的错误状态
   • 在 UI 中显示 API 响应

2. 将状态接入 UI：

   • 将状态管理连接到组件
   • 使用选择器访问状态
   • 根据用户交互分发操作
   • 验证状态变化时 UI 是否更新

3. 端到端验证：

   • 手动测试数据流：UI -> API -> Database -> API -> UI
   • 确认加载状态会显示
   • 确认失败时会显示错误状态
   • 确认成功时会显示成功状态

4. 修复集成问题：

   • 修复 UI 与 API 之间的类型不匹配问题
   • 修复数据映射问题
   • 修复状态同步问题

Agent 指令

集成 Agent：

协议技能（所有 Agent 必须具备）：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 阅读 API 和 UI 代码以了解接口
• 在正确的生命周期钩子（useEffect、事件处理程序）中添加 API 客户端调用
• 确保包含错误处理
• 确保显示加载状态
• 手动测试每个集成点
• 使用 gather-plan-apply 协议

明确的完成定义

• UI 组件能够调用 API 端点
• 数据流从 UI -> API -> DB -> API -> UI
• 状态运行正常
• 显示加载状态
• 显示错误状态
• npm run typecheck 通过
• 所有文件均已提交

特定模式行为

Vibecoding：此阶段结束后设立检查点。提交时使用消息 checkpoint: integration。 Justvibes：自动进入阶段 5。

阶段 5：质量（并行执行）

目的

从多个维度验证实现是否符合质量标准。这些检查会并行运行。每个启动的 Agent 都会拥有由运行时引擎管理的独立 WRFC 链。

子阶段

以下子阶段并行运行：

1. 测试（Tester Agent）
2. 安全检查（Security Agent）
3. 无障碍检查（A11y Agent）

Agent 指令

测试 Agent：

所有 Agent 必须具备的协议技能：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 为 API 端点编写单元测试
• 为 UI 编写组件测试
• 为数据流编写集成测试
• 新代码的覆盖率目标为 >=80%
• 测试正常流程和边缘情况
• 使用 gather-plan-apply 协议

安全 Agent：

所有 Agent 必须具备的协议技能：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 检查所有端点的输入验证
• 检查身份验证/授权检查
• 检查 SQL 注入漏洞
• 检查 XSS 漏洞
• 检查是否暴露机密
• 检查 CORS 配置
• 使用 gather-plan-apply 协议

A11y Agent：

所有 Agent 必须具备的协议技能：gather-plan-apply、precision-mastery、error-recovery、goodvibes-memory

• 检查交互元素是否具有 ARIA 属性
• 检查是否支持键盘导航
• 检查颜色对比度（WCAG AA）
• 检查焦点指示器
• 检查图片的替代文本
• 使用 gather-plan-apply 协议

明确的完成定义

• 已编写并通过测试
• 已完成安全检查（无严重问题）
• 已完成无障碍检查（无严重问题）
• 所有文件均已提交

特定模式行为

Vibecoding：此阶段完成后设置检查点。使用提交信息 checkpoint: quality checks 进行提交。 Justvibes：自动继续；运行时负责处理审核周期。

阶段 6：审核（由运行时驱动）

目的

通过系统化审核和修复，确保所有代码符合生产标准。运行时引擎通过 <gv> 指令自动管理此阶段。

工作方式

编排器不会手动启动审核者。相反：

1. 阶段 2-5 的每个工作 Agent 完成工作并输出一个 <gv> 标签
2. 运行时引擎评估输出并发出指令：
   • 如需审核：{"action":"spawn","type":"reviewer","task":"..."}
   • 审核后如需修复：{"action":"spawn","type":"engineer","task":"Fix: ..."}
   • 若评分达到 score_threshold（在 goodvibes.json 中配置）：{"action":"complete"}
   • 若 max_fix_attempts 已耗尽：{"action":"escalate","reason":"..."}
3. 编排器立即按指令执行，不作额外判断

编排器行为

• 收到 spawn 指令时：使用提供的任务提示词启动指定 Agent
• 收到 complete 指令时：将链标记为完成；所有链均完成后继续进入阶段 7
• 收到 escalate 指令时：向用户报告升级原因；不要尝试手动修复该链

明确的完成定义

• 所有 WRFC 链均已收到运行时发出的 complete 指令
• 没有等待解决升级事项的链

特定模式行为

Vibecoding 和 Justvibes 模式均以相同方式遵循指令。运行时引擎决定审核周期何时结束。本阶段中，除执行指令外，编排器没有特定于模式的行为。

阶段 7：提交 + 记录

目的

当运行时针对阶段 2-5 的所有 WRFC 链发出 complete 指令后，触发此阶段，以提交到 git 并更新项目记忆，从而完成该功能。

步骤

1. 创建 git 提交：

   • 暂存所有新增／修改的文件
   • 编写清晰的提交消息（遵循现有约定）
   • 包含 Co-Authored-By: Claude Opus 4.6 <[email protected]>
   • 提交

2. 更新 goodvibes 记忆：

   • 将新出现的模式添加到 .goodvibes/memory/patterns.json（如果有）
   • 将新做出的决策添加到 .goodvibes/memory/decisions.json（如果有）
   • 使用 goodvibes-memory 技能

3. 更新 goodvibes 日志：

   • 将功能完成情况记录到 .goodvibes/logs/tasks.jsonl
   • 包含功能名称、变更的文件和最终评分
   • 使用 goodvibes-memory 技能

4. 向用户汇报：

   • 总结已构建的内容
   • 列出创建／修改的文件
   • 列出提交 SHA
   • 提供后续步骤（如有）

明确的完成定义

• 所有文件均已提交到 git
• 已更新记忆
• 已更新日志
• 已向用户汇报

特定模式的行为

Vibecoding：提交前先向用户确认提交消息。 Justvibes：使用生成的消息自动提交。

特定模式的行为

Vibecoding 模式

Vibecoding 模式采用协作方式。编排器：

• 在第 1 阶段（理解）后确认再继续
• 在第 2、3、4、5 阶段后设置检查点（创建 git 提交）
• 在第 7 阶段最终提交前确认提交消息
• 出现不确定情况时暂停，等待批准

启动 Agent 后，运行时引擎会自动驱动 WRFC 链。无论处于哪种模式，编排器都会机械地执行指令。

检查点提交消息：

• checkpoint: foundation - schema and types
• checkpoint: core implementation
• checkpoint: integration
• checkpoint: quality checks

Justvibes 模式

Justvibes 模式采用自主运行方式。编排器：

• 无需用户输入即可自动推进所有阶段
• 仅在需求含糊或需要做出关键决策时暂停
• 在第 7 阶段自动提交（生成提交消息）

在两种模式下，运行时引擎都会以相同方式管理所有 WRFC 循环。

Agent 编排模式

顺序阶段

第 2、4、7 阶段必须按顺序执行：

• 第 2 阶段（基础）：必须在第 3 阶段之前完成，因为 API／UI 代码依赖类型
• 第 4 阶段（集成）：必须在第 3 阶段之后执行，因为它会连接 API 和 UI
• 第 7 阶段（提交＋日志）：必须是最后阶段；所有链收到 complete 指令后才会触发

并行阶段

第 3、5 阶段会并行启动多个 Agent：

• 第 3 阶段（核心）：API Agent、UI Agent、状态 Agent 并行运行
• 第 5 阶段（质量）：测试 Agent、安全 Agent、无障碍 Agent 并行运行

并行阶段中的所有 Agent 都必须收到 complete 指令，才能进入下一阶段。

Agent 通信

Agent 不应直接通信，而应：

• Agent 将结果写入文件系统
• 编排器读取 Agent 的输出
• 编排器将相关信息传递给后续 Agent

与其他协议的集成

Gather-Plan-Apply（GPA）

所有工作 Agent 都必须遵循 GPA 循环：

1. 发现：使用 discover 工具并行运行 grep、glob 和符号查询
2. 规划：确定要创建／修改的文件、操作顺序和可批处理的机会
3. 批处理：将操作分组为批量 precision_engine 调用
4. 循环：假设发生变化时，返回发现阶段

详情请参阅 gather-plan-apply 技能。

Review-Scoring（WRFC）

运行时引擎在启动审查者时会在内部使用 review-scoring 评分标准。编排器不会直接为代码评分。审查阈值在 goodvibes.json 中配置（score_threshold、max_fix_attempts）。

关于审查者 Agent 的职责，请参阅 review-scoring 技能。

Goodvibes 记忆

使用 goodvibes-memory 技能来：

• 在第 1 阶段读取 .goodvibes/memory/{decisions,patterns,failures}.json
• 在第 7 阶段写入 .goodvibes/logs/tasks.jsonl
• 在第 7 阶段使用新模式／决策更新记忆文件

常见陷阱

过早开始实施

第 1 阶段完成前，不要启动工作 Agent。先明确需求。

并行执行顺序阶段

不要并行执行第 2 阶段和第 3 阶段。第 3 阶段依赖第 2 阶段的类型。

跳过质量阶段

不要跳过第 5 阶段。测试不是可选项。安全性也不是可选项。

手动安排审查者

不要在第 6 阶段手动添加审查者任务。每个工作 Agent 完成时，运行时引擎会自动发出启动审查者的指令。手动安排会绕过运行时的阈值强制机制。

延迟执行指令

不要延迟、重排或跳过 <gv> 指令。收到后立即将其作为首要操作执行。

所有链条完成前提交

在第 7 阶段，所有 WRFC 链都收到 complete 指令之前，不要提交。部分完成不算完成。

忘记更新记忆

不要跳过第 7 阶段的记忆更新。后续 Agent 会依赖这些上下文。

验证

使用 scripts/validate-feature-workflow.sh 验证你的编排是否遵循此工作流。详细模板和示例请参阅 references/phase-templates.md。