build-feature

全栈功能实现工作流

跨数据库、后端、前端和测试层执行全栈功能实现。此技能遵循 /plan-feature 生成的实现计划，并通过集成测试构建所有层。

注意

范围边界：此技能负责实现代码并提交代码。它不会创建拉取请求、推送到远程、执行代码审查或提交任何内容以供合并。实现和提交完成后，立即停止，并建议用户接下来运行 /review-code。不要继续创建 PR——那是 /submit-pr 的工作。

步骤 1：加载实现计划

按以下优先级查找实现计划：

说明

/plan-feature 创建的 GitHub issue 是面向任务的工作项——决策记录仍是记录评审结论、理由和架构背景的权威来源。从 issue 加载时，务必阅读所引用的决策记录，以获取完整背景。

选项 A：GitHub Issue（首选）

如果用户提供了 GitHub issue 编号（例如 /build-feature 42 或 /build-feature #42）：

1. 获取 issue 详情：

   gh issue view <number> --json title,body,labels,state,number
   

2. 验证 issue：

   • 确认其带有 build-ready 标签（如果没有则发出警告——它可能未经过 /plan-feature，或可能需要进一步规划）
   • 如果 issue 已关闭，警告用户并询问是否继续

3. 解析 issue 正文，提取：

   • 实现计划：按层组织的任务复选框（前端、后端、数据库、测试）
   • 技术背景：架构决策、API 合约、架构变更
   • 决策记录路径：阅读所引用的决策记录，以获取完整评审背景
   • 功能标志：适用时的标志名称
   • 成功指标：可衡量的结果

4. 从 issue 指定的路径读取所引用的决策记录，以了解完整的评审理由。

5. 标记工作正在进行（标签管理规则见 AGENTS.md）：

   # Single-developer constraint: only one issue should be in-progress at a time.
   # First, remove in-progress from any other issue that has it:
   gh issue list --label "in-progress" --state open --json number --jq '.[].number' | while read n; do
     gh issue edit "$n" --remove-label "in-progress"
   done
   
   gh issue edit <number> --add-label "in-progress"
   

6. 验证该 issue 已在 产品路线图 项目看板中跟踪。如果没有，则添加：

   # --limit 200 covers the current board size; increase if the project grows beyond 200 items
   EXISTING=$(gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 \
     | python3 -c "
   import json, sys
   data = json.load(sys.stdin)
   for item in data.get('items', []):
       # <number> must be an integer literal, e.g., == 42, not == '42'
       if item.get('content', {}).get('number') == <number>:
           print(item['id'])
           break
   ")
   
   if [ -z "$EXISTING" ]; then
     ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "https://github.com/{OWNER}/{REPO}/issues/<number>" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
     echo "Warning: Issue #<number> was not on the project board. Added it now (item $ITEM_ID)."
   fi
   

   警告

   如果 issue 不在项目看板中，phase、size 和 date 字段也可能缺失。检查项目条目，并在字段未设置时提醒用户——这表明该 issue 是在 /plan-feature 或 /security-audit 之外创建的，而这两个技能会确保 issue 加入看板并填充字段。

选项 B：从路线图自动选择

如果未提供 issue 编号或描述，则自动从项目路线图中查找下一个 build-ready 工单：

1. 确定当前阶段。 查找当前活跃的里程碑——尚未关闭且截止日期最早、并且仍有未关闭 issue 的里程碑：

   gh api repos/{OWNER}/{REPO}/milestones \
     --jq 'sort_by(.due_on) | map(select(.state == "open" and .open_issues > 0)) | .[0] | {title, number, due_on, open_issues}'
   

   如果某个 issue 已带有 in-progress 标签，则使用该 issue 所属的里程碑：

   gh issue list --state open --label "in-progress" --json number,title,milestone --jq '.[0]'
   

2. 获取 build-ready 候选项。 列出该里程碑中带有 build-ready 标签且尚未关闭的 issue，排除任何已带有 in-progress 标签的 issue：

   gh issue list --state open --label "build-ready" --milestone "<milestone-title>" \
     --json number,title,labels \
     --jq '[.[] | select(.labels | map(.name) | index("in-progress") | not)]'
   

3. 按项目开始日期排序。 获取项目条目，并按 issue 编号与候选项匹配，然后按 start 字段升序排序：

   gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 | python3 -c "
   import json, sys
   data = json.load(sys.stdin)
   # <candidates> is a Python set literal of issue numbers, e.g., {22, 23, 10}
   candidates = <candidates>
   results = []
   for item in data.get('items', []):
       num = item.get('content', {}).get('number')
       if num in candidates:
           # Field is 'start', not 'startDate'
           start = item.get('start') or '9999-12-31'
           results.append((start, num, item.get('title', '')))
   results.sort()
   for start, num, title in results:
       display_start = start if start != '9999-12-31' else 'N/A'
       print(f'{display_start}\t#{num}\t{title}')
   "
   

   第一个候选项（start 日期最早）就是下一个要处理的工单。没有 start 日期的 issue 排在最后。

4. 如果没有找到候选项，则转到选项 C（决策记录）。

检查点：向用户展示推荐的任务单和完整候选列表。

将当前阶段所有 build-ready 候选项按开始日期排序，并用醒目标记突出显示排名第一的候选项作为推荐项：

#	Issue	标题	开始日期
→	#N	排名第一的候选项标题	YYYY-MM-DD
2	#N	其他候选项	YYYY-MM-DD

请用户确认：

• (a) 处理推荐的任务单
• (b) 从列表中选择其他任务单（提供 Issue 编号）
• (c) 跳过自动选择，并描述要构建的内容

如果用户确认了某个任务单，请使用该 Issue 编号，并按照选项 A 的相同流程继续（获取完整 Issue 详情、验证 build-ready、提取计划、设置 in-progress 标签等）。

选项 C：决策记录（备用方案）

如果用户未提供 Issue 编号，且路线图中没有找到 build-ready 任务单：

1. 从 docs/decisions/ 中读取与当前功能匹配的最新决策记录
2. 如果不存在决策记录，则转到选项 D

选项 D：用户描述（最后手段）

如果不存在决策记录，请询问用户要构建什么。

警告

未找到 GitHub Issue 或决策记录。这意味着规划流程（/plan-feature）已被跳过——没有经过委员会评估、没有记录决策理由，也没有结构化的任务拆分。建议先运行 /plan-feature。在没有计划的情况下继续，可能导致未经审查的架构决策。

提取任务

从计划中（无论来源如何）识别以下内容：

• 数据库变更：架构修改、迁移、种子数据
• 后端任务：API 端点、服务、业务逻辑
• 前端任务：组件、路由、状态管理、样式
• 测试要求：覆盖率目标、端到端场景、边界情况
• 功能标志：是否需要通过功能标志控制

确保当前处于基于最新 main 创建的功能分支上。务必先获取更新：

git fetch origin main

如果当前处于 main，请从最新的 origin/main 创建新的功能分支：

git checkout -b feature/<feature-slug> origin/main

如果当前已处于现有功能分支，请将其变基到最新的 origin/main，以纳入所有变更：

git status --porcelain

如果工作树有未提交的变更，请在变基前暂存这些变更：

git stash push -m "build-feature: stash before rebase"
git rebase origin/main
git stash pop

如果工作树干净，请直接变基：

git rebase origin/main

步骤 2：数据库层

如果需要进行数据库变更：

1. 调用 /database-design:postgresql 获取架构设计指导

2. 设计 Prisma 架构变更：

   • 为模型设置适当的字段类型和默认值
   • 设置具有引用完整性的关系
   • 为查询性能添加索引
   • 添加约束和验证
   • 在适当情况下使用枚举

3. 调用 /database-migrations:sql-migrations 获取迁移最佳实践

检查点：向用户展示架构变更和迁移计划。等待批准后再执行。

4. 生成并应用迁移：

   pnpm db:migrate
   

步骤 3：后端实现

调用 /backend-development:feature-development 获取后端搭建指导。

根据计划中的每项后端任务：

类型与验证

• 为请求和响应类型定义 TypeScript 接口
• 创建用于运行时验证的 Zod 架构
• 导出供前端使用的共享类型

服务层

• 在 NestJS 服务中实现业务逻辑
• 使用类型化异常进行适当的错误处理
• 验证业务规则并确保不变量
• 确保服务可测试（依赖注入）

API 层

• 创建 tRPC 程序或 NestJS 控制器
• 配置验证、身份验证守卫和速率限制
• 返回适当的状态码和错误格式

后端测试

• 服务的单元测试（模拟依赖项）
• API 端点的集成测试
• 测试验证、身份验证和错误处理

运行后端测试：

pnpm test

检查点：向用户展示 API 契约（端点、请求/响应类型）。在据此构建前端之前，先确认契约。

第 4 步：前端实现

针对计划中的每项前端任务：

创建组件

调用 /ui-design:create-component，在其指导下创建组件，并满足以下要求：

• 完整的 TypeScript 属性接口
• 使用 Tailwind CSS + shadcn/ui 进行样式设计（调用 /frontend-mobile-development:tailwind-design-system 获取设计模式）
• 键盘导航和 ARIA 属性
• 响应式设计
• 深色模式支持（如适用）

说明

所有用户可见的文本（标题、标签、描述、空状态、错误消息、工具提示）都必须遵循 AGENTS.md 中的面向用户的内容风格规则。不得使用 em dash、AI 腔词汇或夸大宣传的措辞。

状态管理

如果此功能需要客户端状态：

• 调用 /frontend-mobile-development:react-state-management 获取状态管理模式
• 使用 React Query / tRPC hooks 管理服务端状态
• 使用本地状态（useState/useReducer）管理 UI 状态
• 使用 context 或 Zustand 管理共享的客户端状态

路由

如果需要新页面或路由：

• 添加路由定义
• 创建页面组件
• 添加导航链接

内容与 SEO（适用于营销页面或面向用户的页面）

如果此功能涉及营销页面、落地页文案或产品描述：

• 调用 /seo-content-creation:seo-content-writer，提升 SEO 内容质量并优化 E-E-A-T
• 调用 /content-marketing:content-marketer 获取内容策略指导
• 同时调用 /accessibility-compliance:wcag-audit-patterns 和 /ui-design:accessibility-audit，深入满足 WCAG 合规要求

API 集成

• 通过 tRPC 客户端或 API hooks 将组件连接到后端
• 处理加载状态、错误状态和空状态
• 在适当情况下添加乐观更新

功能标志（如适用）

如果计划指定了功能标志：

const isEnabled = useFeatureFlag('FEATURE_NAME');
if (!isEnabled) return <ExistingComponent />;
return <NewFeature />;

前端测试

• 组件渲染测试（React Testing Library）
• 用户交互测试（点击、输入、提交）
• 使用模拟 API 响应的集成测试

检查点：向用户展示前端实现。说明已构建的内容，展示组件结构和关键交互。

第 5 步：端到端测试

为关键用户流程编写 E2E 测试大纲：

• 正常流程：用户成功完成主要流程
• 错误流程：用户遇到验证错误或 API 故障
• 边界情况：空状态、边界条件、并发操作

如果已有 E2E 测试基础设施，则实现这些测试。

运行完整测试套件：

pnpm test

报告覆盖率和任何失败项。

第 6 步：自我审查

向用户展示之前，进行全面的自我审查：

pnpm type-check      # No TypeScript errors
pnpm lint            # No linting violations
pnpm format:check    # No Prettier formatting issues
pnpm test            # All unit tests pass
pnpm test:smoke      # DI wiring and component tree render OK

如果 format:check 失败，请对报告中的文件运行 pnpm exec prettier --write，再继续。

检查以下事项：

• 没有硬编码的密钥或凭据
• 对所有面向用户的输入进行验证
• 正确处理错误（不吞掉错误）
• 组件易于访问（ARIA、键盘导航）
• TypeScript 中没有 any 类型
• UI 中具有适当的加载状态和错误状态

第 7 步：更新文档

如果此功能改变了项目的设置、构建或运行方式，请在提交之前更新相关文档：

1. README.md — 如果此功能引入了新的基础设施、服务、环境变量或命令，请更新 Quick Start、Running the Application 或 Project Structure 章节
2. docs/DEVELOPMENT.md — 根据需要更新 Prerequisites、Local Development Setup、Database Operations 或 Troubleshooting 章节
3. Makefile — 为常见操作添加新目标（例如新的 Docker 服务、数据库命令）
4. .env.example 文件 — 添加新的环境变量，并附上清晰说明和安全默认值
5. docs/INDEX.md — 如果在 docs/ 中添加了新文件，请将它们添加到主文档索引中的相应表格

重要

刚克隆仓库的开发者必须能够只按照 README.md 就运行项目。如果你的功能添加了 Docker 服务、数据库、新的开发服务器或环境变量，文档必须同步更新。

第 8 步：提交

检查点：向用户提供完整摘要：

• 创建和修改的文件（按层分类）
• 数据库变更（如有）
• 新增的 API 端点（如有）
• 创建的组件（如有）
• 测试结果和覆盖率
• 已知限制或推迟处理的事项

提交前等待用户批准。

创建原子化、符合 Conventional Commits 规范的提交。如果功能足够小，可以只创建一个提交：

feat(<scope>): implement <feature-name>

如果功能较大，请拆分为逻辑清晰的多个提交：

feat(db): add <model> schema and migration
feat(api): add <resource> endpoints
feat(web): add <feature> components and pages
test: add tests for <feature>

更新 GitHub Issue

如果实现工作是由 GitHub issue 发起的：

1. 在 issue 中评论进度：

   gh issue comment <number> --body "Implementation committed on branch \`<branch-name>\`. Proceeding to code review via \`/review-code\`."
   

说明

此处不要移除 in-progress 标签。直到 issue 关闭之前，该标签都应保留（由 .github/workflows/label-cleanup.yml 自动处理）。这样可确保在代码审查和提交 PR 期间，issue 始终明确显示为进行中。

第 9 步：交接 — 在此处停止

注意

此技能的工作到此结束。 不要继续创建拉取请求、推送到远程仓库或进行代码审查。这些属于独立技能，有各自的工作流和检查点。

向用户说明下一步：

• 推荐：提交前运行 /review-code，进行多视角审查
• 如果还有更多工作：继续完成实现计划中的剩余任务，然后运行 /review-code
• 如果涉及大量 UI 工作：可考虑在代码审查前运行 /ui-design:design-review

如果工作来自 GitHub issue，请提醒用户：

• PR 应使用 Closes #<number> 引用 issue，以便合并时自动关闭
• /submit-pr 会从提交消息中检测相关 issue

不要在此技能中推送分支、创建 PR 或调用 /submit-pr。