feature-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature Build Skill

功能构建Skill

Orchestrates the complete feature development lifecycle with clear phases, entry/exit criteria, and conversation loop patterns. This skill transforms feature requests into shipped, tested, and documented code.

通过清晰的阶段、进入/退出标准和对话循环模式，编排完整的功能开发生命周期。该Skill可将功能需求转化为已发布、经过测试且带有文档的代码。

Contract

约定

Inputs:

Feature request or task from TASKS.md
Project with existing component structure (components/ui/)
(Optional) Style guide page for component development

Outputs:

Working feature verified in browser
Components exported from barrel file
PostHog analytics instrumented
TASKS.md and CHANGELOG.md updated
Clean git commit(s) with conventional format

Success Criteria:

All acceptance criteria pass in browser testing
No console errors or build failures
Analytics events firing correctly
Documentation updated

输入项：

来自TASKS.md的功能需求或任务
具有现有组件结构的项目（components/ui/）
（可选）组件开发的样式指南页面

输出项：

在浏览器中验证通过的可运行功能
从桶文件导出的组件
已埋点的PostHog分析
更新后的TASKS.md和CHANGELOG.md
符合规范格式的清晰git提交记录

成功标准：

所有验收标准通过浏览器测试
无控制台错误或构建失败
分析事件正常触发
文档已更新

Philosophy

设计理念

Core Principles

核心原则

Acceptance Criteria First — Define what "done" looks like before writing code. Testable criteria prevent scope creep and enable verification.
Components Live in Style Guide — Every UI component starts in the style-guide page. This ensures reusability, documents all states, and provides a living reference.
Test What You Build — Use browser tools to verify each step. Don't wait until the end to discover issues.
KISS (Keep It Simple, Stupid) — Implement the simplest solution that meets the criteria. Avoid over-engineering.
Loop Back, Don't Push Forward — When something doesn't work, return to the appropriate phase rather than patching around issues.

先定义验收标准 —— 在编写代码前明确“完成”的定义。可测试的标准能防止范围蔓延并支持验证。
组件在样式指南中开发 —— 每个UI组件都从样式指南页面开始构建。这确保了可复用性，记录所有状态，并提供活参考文档。
测试已构建的内容 —— 使用浏览器工具验证每个步骤。不要等到最后才发现问题。
KISS原则（保持简单） —— 实现满足标准的最简方案。避免过度设计。
回溯修正，而非强行推进 —— 当出现问题时，回到对应阶段修正，而非临时补丁。

Conversation Loop Model

对话循环模型

Features are built through phases that can loop back when issues arise:

┌───────────────────────────────────────────────────────────────────────────────┐
│                                                                               │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────────────┐ │
│  │  Task    │──▶│Component │──▶│  Build   │──▶│Analytics │──▶│   Build     │ │
│  │Selection │   │ Design   │   │  Loop    │   │  Setup   │   │Verification │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └─────────────┘ │
│       ▲              │              │              │               │          │
│       │              ▼              ▼              ▼               ▼          │
│       │         ◀────────────◀─────────────◀──────────────────────────────────│
│       │         (loop back if criteria fail or build errors)                  │
│       │                                                                       │
│       │                                                    ┌──────────────┐   │
│       └────────────────────────────────────────────────────│   Commit &   │◀──│
│                (next feature)                              │  Document    │   │
│                                                            └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────────┘

功能通过多个阶段构建，出现问题时可回溯到之前的阶段：

┌───────────────────────────────────────────────────────────────────────────────┐
│                                                                               │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────────────┐ │
│  │  Task    │──▶│Component │──▶│  Build   │──▶│Analytics │──▶│   Build     │ │
│  │Selection │   │ Design   │   │  Loop    │   │  Setup   │   │Verification │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └─────────────┘ │
│       ▲              │              │              │               │          │
│       │              ▼              ▼              ▼               ▼          │
│       │         ◀────────────◀─────────────◀──────────────────────────────────│
│       │         (loop back if criteria fail or build errors)                  │
│       │                                                                       │
│       │                                                    ┌──────────────┐   │
│       └────────────────────────────────────────────────────│   Commit &   │◀──│
│                (next feature)                              │  Document    │   │
│                                                            └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────────┘

Relationship to Other Skills

与其他Skill的关联

design-system — Reference for UI patterns, component design principles, style-guide template
feature-gating — Use when building pro/freemium features with PostHog flags
versioning — Follow semantic versioning for releases

design-system —— UI模式、组件设计原则、样式指南模板的参考依据
feature-gating —— 当使用PostHog标志构建专业版/免费增值版功能时使用
versioning —— 发布时遵循语义化版本控制

Phase 1: Task Selection

阶段1：任务选择

Entry Criteria

进入条件

Fresh conversation or user requests a feature
TASKS.md exists in project

新对话或用户提出功能需求
项目中存在TASKS.md

Actions

执行步骤

Read TASKS.md — Identify the next item from Current Sprint

Read TASKS.md and identify the next unchecked item in Current Sprint

Confirm Scope — Clarify with user what's included and excluded
- What exactly should this feature do?
- What should it NOT do?
- Are there edge cases to consider?
Break Down if Complex — Split large features into sub-tasks
- Each sub-task should be completable in one conversation
- Sub-tasks should have clear dependencies
Define Acceptance Criteria — Write testable criteria

读取TASKS.md —— 从当前迭代中识别下一个任务项

Read TASKS.md and identify the next unchecked item in Current Sprint

确认范围 —— 与用户明确包含和排除的内容
- 该功能具体需要实现什么？
- 不需要实现什么？
- 是否需要考虑边缘情况？
复杂任务拆分 —— 将大型功能拆分为子任务
- 每个子任务应能在一次对话中完成
- 子任务应具有清晰的依赖关系
定义验收标准 —— 编写可测试的标准

Acceptance Criteria Format

验收标准格式

markdown

undefined

markdown

undefined

Feature: [Name]

Feature: [名称]

Acceptance Criteria:

User can [specific action]
System [specific behavior] when [condition]
Error case: [scenario] displays [message]
Mobile: [behavior] works on viewport < 768px

undefined

Acceptance Criteria:

用户可以执行[具体操作]
系统在[条件]下会[具体行为]
错误场景：[场景]会显示[提示信息]
移动端：[行为]在视口<768px时正常工作

undefined

Exit Criteria

退出条件

Feature scope is clearly defined
Acceptance criteria are written and agreed
Sub-tasks identified if feature is complex

功能范围已明确定义
验收标准已编写并达成一致
若功能复杂，已识别子任务

Phase 2: Component Design

阶段2：组件设计

Entry Criteria

进入条件

Feature scope is clear
Acceptance criteria are defined

功能范围清晰
验收标准已定义

Actions

执行步骤

Check Style Guide First — Look for existing components that can be reused or extended
```
Navigate to /style-guide and snapshot to see existing components
```
Design in Style Guide — Build new components in the style-guide page
- Components should be isolated and reusable
- Import from
```
components/ui/
```
  barrel file
- Export new components from barrel file
Show All States — Document every component state:
- Default/resting
- Hover/focus
- Loading/pending
- Success/complete
- Error/invalid
- Disabled
- Empty (if applicable)
Mobile Considerations — Test responsive behavior
- Use PhoneFrame component for mobile mockups if available
- Consider touch targets (min 44px)

先检查样式指南 —— 寻找可复用或扩展的现有组件
```
Navigate to /style-guide and snapshot to see existing components
```
在样式指南中设计 —— 在样式指南页面中构建新组件
- 组件应独立且可复用
- 从
```
components/ui/
```
  桶文件导入
- 从桶文件导出新组件
展示所有状态 —— 记录组件的所有状态：
- 默认/初始状态
- 悬停/聚焦状态
- 加载/等待状态
- 成功/完成状态
- 错误/无效状态
- 禁用状态
- 空状态（如适用）
移动端考量 —— 测试响应式行为
- 若有可用的PhoneFrame组件，用于移动端模拟
- 考虑触摸目标（最小44px）

Style Guide Section Template

样式指南章节模板

tsx

<section id="my-component">
  <SectionHeader title="My Component" />
  
  <div className="space-y-6">
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      Variants
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent variant="default" />
      <MyComponent variant="secondary" />
    </div>
    
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      States
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent loading />
      <MyComponent disabled />
      <MyComponent error="Error message" />
    </div>
  </div>
</section>

tsx

<section id="my-component">
  <SectionHeader title="My Component" />
  
  <div className="space-y-6">
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      Variants
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent variant="default" />
      <MyComponent variant="secondary" />
    </div>
    
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      States
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent loading />
      <MyComponent disabled />
      <MyComponent error="Error message" />
    </div>
  </div>
</section>

Exit Criteria

退出条件

Components visible in
```
/style-guide
```
All states documented and interactive
Components exported from
```
components/ui/index.ts
```
Responsive behavior verified

组件在
```
/style-guide
```
中可见
所有状态已记录且可交互
组件已从
```
components/ui/index.ts
```
导出
响应式行为已验证

Phase 3: Build Loop

阶段3：构建循环

Entry Criteria

进入条件

Components designed and in style-guide
Acceptance criteria ready for testing

组件已设计并添加到样式指南
验收标准可用于测试

Actions

执行步骤

3.1 Backend First

3.1 先做后端

Build data layer and API before wiring to UI:

Database schema — Add migrations if needed
Service layer — Business logic functions
API routes — REST endpoints with Zod validation
Test API — Use browser network panel or curl to verify

在连接UI之前构建数据层和API：

数据库模式 —— 如有需要添加迁移
服务层 —— 业务逻辑函数
API路由 —— 带有Zod验证的REST端点
测试API —— 使用浏览器网络面板或curl验证

3.2 Frontend Integration

3.2 前端集成

Wire components to backend:

State management — Zustand store or React state
API hooks — Data fetching with proper loading/error states
Component wiring — Connect UI to state and actions

将组件与后端连接：

状态管理 —— Zustand存储或React状态
API钩子 —— 带有正确加载/错误状态的数据获取
组件连接 —— 将UI与状态和操作关联

3.3 Browser Testing

3.3 浏览器测试

Test at each step using Cursor browser tools:

1. Navigate to the page being tested
2. Snapshot to get element references
3. Interact with elements (click, type, etc.)
4. Re-snapshot after state changes
5. Verify expected behavior
6. Screenshot if visual verification needed

See
references/testing-patterns.md
for detailed testing scenarios.

使用Cursor浏览器工具在每个步骤进行测试：

1. Navigate to the page being tested
2. Snapshot to get element references
3. Interact with elements (click, type, etc.)
4. Re-snapshot after state changes
5. Verify expected behavior
6. Screenshot if visual verification needed

详细测试场景请参考
references/testing-patterns.md
。

Testing Checklist by Component Type

按组件类型分类的测试清单

Loop Back Triggers

回溯触发条件

Return to Phase 2 if:

Component needs additional states not designed
UI pattern isn't working as expected
Need to refactor component API

Return to Phase 1 if:

Scope is unclear or expanding
Acceptance criteria need revision
Feature should be split differently

回到阶段2的情况：

组件需要添加未设计的状态
UI模式未按预期工作
需要重构组件API

回到阶段1的情况：

范围不清晰或扩大
验收标准需要修订
功能需要重新拆分

Exit Criteria

退出条件

All acceptance criteria pass in browser
No console errors
Mobile viewport tested (if applicable)
Error states handled gracefully

所有验收标准通过浏览器测试
无控制台错误
已测试移动端视口（如适用）
错误状态已妥善处理

Phase 4: Analytics Setup

阶段4：分析设置

Entry Criteria

进入条件

Feature is working in browser
All acceptance criteria pass

功能在浏览器中正常工作
所有验收标准已通过

Actions

执行步骤

Identify Tracking Needs — What user actions matter?

Feature Type	Typical Events
Form	`{form}_submitted` , `{form}_error`
Feature	`{feature}_used` , `{feature}_completed`
Navigation	`{page}_viewed`
Pro Feature	`{feature}_attempted` , `{feature}_upgrade_shown`

Implement Events — Add PostHog capture calls

typescript

posthog.capture('{feature}_{action}', {
  feature: 'feature-name',
  // action-specific properties
})

Create Dashboard (if appropriate) — Use PostHog MCP tools

Use mcp_posthog-study-bible_dashboard-create for new dashboards
Use mcp_posthog-study-bible_insight-create-from-query for insights

Pro Features — If feature is gated, follow feature-gating skill:
- Create PostHog feature flag
- Implement
```
useProFeature()
```
  hook
- Track
```
_attempted
```
  ,
```
_upgrade_shown
```
  ,
```
_upgrade_clicked
```
  events

确定跟踪需求 —— 哪些用户操作需要跟踪？
功能类型典型事件
表单
{form}_submitted
,
{form}_error
功能
{feature}_used
,
{feature}_completed
导航
{page}_viewed
专业版功能
{feature}_attempted
,
{feature}_upgrade_shown

功能类型	典型事件
表单	`{form}_submitted` , `{form}_error`
功能	`{feature}_used` , `{feature}_completed`
导航	`{page}_viewed`
专业版功能	`{feature}_attempted` , `{feature}_upgrade_shown`

实现事件 —— 添加PostHog捕获调用

typescript

posthog.capture('{feature}_{action}', {
  feature: 'feature-name',
  // 操作相关属性
})

创建仪表盘（如适用） —— 使用PostHog MCP工具

Use mcp_posthog-study-bible_dashboard-create for new dashboards
Use mcp_posthog-study-bible_insight-create-from-query for insights

专业版功能 —— 若功能是 gated 类型，遵循feature-gating skill：
- 创建PostHog功能标志
- 实现
```
useProFeature()
```
  钩子
- 跟踪
```
_attempted
```
  ,
```
_upgrade_shown
```
  ,
```
_upgrade_clicked
```
  事件

Event Naming Convention

事件命名规范

{feature}_{action}

Examples:
- notes_created
- notes_synced
- chat_message_sent
- upgrade_modal_shown
- model_changed

{feature}_{action}

示例：
- notes_created
- notes_synced
- chat_message_sent
- upgrade_modal_shown
- model_changed

Exit Criteria

退出条件

Key user actions instrumented
Events firing correctly (verify in PostHog)
Dashboard created (if feature warrants it)
Pro feature flags configured (if applicable)

关键用户操作已埋点
事件正常触发（在PostHog中验证）
已创建仪表盘（如功能需要）
专业版功能标志已配置（如适用）

Phase 5: Build Verification

阶段5：构建验证

Entry Criteria

进入条件

Feature is working in browser
Analytics implemented (or skipped if not applicable)

功能已完成并测试
分析已实现（或无需实现）

Actions

执行步骤

Run Production Build
bash
```
npm run build
```
- Must complete with exit code 0
- Fix any TypeScript errors
- Fix any framework-specific build errors (unused exports, client/server boundaries, etc.)
Check Linter
bash
```
npm run lint
```
- Fix any lint errors (warnings acceptable)
Verify No Regressions
- If build fails, loop back to Phase 3 to fix issues
- Do NOT proceed to commit until build passes

运行生产构建
bash
```
npm run build
```
- 必须以退出码0完成
- 修复所有TypeScript错误
- 修复所有框架特定的构建错误（未使用的导出、客户端/服务端边界等）
检查代码规范
bash
```
npm run lint
```
- 修复所有lint错误（警告可接受）
验证无回归问题
- 若构建失败，回到阶段3修复问题
- 构建通过前不要进行提交

Loop Back Triggers

回溯触发条件

Return to Phase 3 if:

TypeScript errors in new/modified files
Build errors related to imports or exports
Client/server component boundary issues

回到阶段3的情况：

新修改的文件存在TypeScript错误
构建错误与导入或导出相关
客户端/服务端组件边界问题

Exit Criteria

退出条件

```
npm run build
```
succeeds with exit code 0
```
npm run lint
```
passes (no errors)
No TypeScript errors

```
npm run build
```
以退出码0成功执行
```
npm run lint
```
通过（无错误）
无TypeScript错误

Phase 6: Commit & Document

阶段6：提交与文档编写

Entry Criteria

进入条件

Feature complete and tested
Analytics implemented
Build verification passed

功能已完成并测试
分析已实现
构建验证已通过

Actions

执行步骤

Update TASKS.md
- Move completed items to Completed section
- Add completion date
- Check off sub-tasks
- Add any new backlog items discovered
Update CHANGELOG.md
- Add entry under current version or "Unreleased"
- Summarize what was added/changed/fixed
- Reference any breaking changes
Stage and Commit
- Use conventional commit format
- Keep commits atomic (one logical change per commit)

更新TASKS.md
- 将已完成的项移至“已完成”部分
- 添加完成日期
- 标记子任务为已完成
- 添加发现的新待办项
更新CHANGELOG.md
- 在当前版本或“未发布”下添加条目
- 总结新增/修改/修复的内容
- 提及任何破坏性变更
暂存并提交
- 使用规范的提交格式
- 保持提交原子性（每个提交对应一个逻辑变更）

Conventional Commit Format

规范提交格式

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert

<type>(<scope>): <subject>

类型：feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert

Commit Summary Block

提交摘要块

Provide at end of feature for easy copy-paste:

markdown

undefined

在功能结束时提供，方便复制粘贴：

markdown

undefined

Done

Summary: [Brief description of what was built]

Commits (ohmyzsh): gaa && gcmsg "feat(scope): add feature description" gcmsg "fix(scope): fix related issue" gp

undefined

Summary: [构建内容的简要描述]

Commits (ohmyzsh): gaa && gcmsg "feat(scope): add feature description" gcmsg "fix(scope): fix related issue" gp

undefined

TASKS.md Update Pattern

TASKS.md更新模板

markdown

undefined

markdown

undefined

Completed

Exit Criteria

退出条件

TASKS.md updated with completion status
CHANGELOG.md updated with feature summary
Clean commit(s) with conventional format
Ready for next feature

TASKS.md已更新完成状态
CHANGELOG.md已更新功能摘要
符合规范格式的清晰提交记录
准备好进行下一个功能开发

Quick Reference

快速参考

Phase Entry/Exit Summary

阶段进入/退出摘要

Phase	Entry	Exit
1. Task Selection	Feature request	Criteria defined
2. Component Design	Criteria clear	Components in style-guide
3. Build Loop	Components ready	All criteria pass in browser
4. Analytics	Feature working	Events instrumented
5. Build Verification	Analytics done	`npm run build` succeeds
6. Commit	Build passes	Docs updated, committed

阶段	进入条件	退出条件
1. 任务选择	功能需求提出	标准已定义
2. 组件设计	标准清晰	组件已添加到样式指南
3. 构建循环	组件就绪	所有标准通过浏览器测试
4. 分析设置	功能正常工作	事件已埋点
5. 构建验证	分析已完成	`npm run build` 成功
6. 提交	构建通过	文档已更新，已提交

Common Commands

常用命令

bash

undefined

bash

undefined

Start dev server

启动开发服务器

npm run dev

Clear Next.js cache if issues

若出现问题，清除Next.js缓存

rm -rf .next

Rebuild native modules

重建原生模块

npm rebuild better-sqlite3

Git workflow (ohmyzsh)

Git工作流（ohmyzsh）

gaa && gcmsg "feat(scope): description" gp

undefined

gaa && gcmsg "feat(scope): description" gp

undefined

Browser Testing Quick Reference

浏览器测试快速参考

1. mcp_cursor-ide-browser_browser_navigate → load page
2. mcp_cursor-ide-browser_browser_snapshot → get elements
3. mcp_cursor-ide-browser_browser_click/type → interact
4. mcp_cursor-ide-browser_browser_snapshot → verify changes
5. mcp_cursor-ide-browser_browser_take_screenshot → visual check

1. mcp_cursor-ide-browser_browser_navigate → 加载页面
2. mcp_cursor-ide-browser_browser_snapshot → 获取元素引用
3. mcp_cursor-ide-browser_browser_click/type → 交互操作
4. mcp_cursor-ide-browser_browser_snapshot → 验证变更
5. mcp_cursor-ide-browser_browser_take_screenshot → 视觉检查