generic-feature-developer

通用功能开发者

指导在任何技术栈中开发功能。

何时使用此技能

适用于：

• 为现有代码库添加新功能
• 修改或扩展当前系统
• 规划架构变更
• 在不同实现方案之间做出选择
• 设计新功能的数据流

不适用于：

• 纯 UI／样式工作 → 使用 generic-design-system
• UX 设计决策 → 使用 generic-ux-designer
• 代码审查 → 使用 generic-code-reviewer

开发工作流

1. 了解 - 阅读 CLAUDE.md，找出受影响的文件，列出约束条件
2. 规划 - 选择模式，设计数据流，找出边界情况
3. 实现 - 进行小规模、便于审查的更改，频繁提交
4. 审查与记录 - 根据边界情况和调用方审查差异，更新文档，检查性能

按项目类型划分的架构

静态网站

project/
├── index.html
├── css/           # variables.css, style.css
├── js/            # main.js, utils.js
└── assets/

模式： CSS 变量、ES 模块、事件委托

React/Next.js

src/
├── components/    # ui/, features/, layout/
├── hooks/
├── stores/
├── services/
└── types/

模式： 容器／展示组件、自定义钩子、Zustand/React Query

NestJS 后端

src/
├── modules/[feature]/
│   ├── feature.module.ts
│   ├── feature.controller.ts
│   ├── feature.service.ts
│   └── dto/
└── common/        # guards, decorators

模式： 模块组织、DTO、守卫、Prisma

功能决策框架

评估范围（首先进行）

范围	操作
单个组件	直接实现
横切关注点	先设计接口
新子系统	编写架构文档并获得批准

自行构建还是集成

因素	自定义构建	使用库
产品核心功能	是
通用功能		是
需要紧密集成	是
时间紧迫		是
长期维护	是

状态管理方案选择

范围	方案
组件本地	useState/useReducer
功能范围内	Context 或 Zustand 切片
整个应用	Zustand/Redux store
服务端状态	React Query/SWR
表单状态	React Hook Form

API 设计检查清单

• 已记录 RESTful 或 GraphQL 的选择
• 已选择身份验证方式
• 已统一错误响应格式
• 已定义分页策略
• 已考虑速率限制

常见功能

添加 UI 组件

1. 创建组件 → 2. 导出 → 3. 审查用法和边界情况 → 4. 编写文档

添加 API 端点

1. 定义路由 → 2. 添加验证 → 3. 实现服务 → 4. 审查错误处理路径

添加状态管理

1. 定义结构 → 2. 创建 store → 3. 添加操作 → 4. 连接组件

数据库变更

1. 设计架构 → 2. 创建迁移 → 3. 更新模型 → 4. 添加服务

数据流模式

前端数据流

User Action → Event Handler → State Update → Re-render → UI Feedback

• 乐观更新： 立即更新 UI，出错时回滚
• 悲观更新： 等待服务端确认
• 选择依据： 低风险操作（点赞）采用乐观更新；高风险操作（付款）采用悲观更新

API 请求流

Request → Auth Check → Validation → Business Logic → Database → Response

• 验证失败时尽早退出
• 在多步骤操作周围设置事务边界
• 使用一致的错误响应格式

事件驱动模式

事件类型	处理方式
用户事件	立即反馈
服务端事件	使用 WebSocket/SSE 实现实时通信
后台任务	对耗时较长的操作使用队列

错误处理策略

错误类型	前端	后端
验证	字段内联错误	400 + 字段错误
身份验证	重定向到登录页	401/403
未找到	空状态或重定向	404
服务器错误	通用消息 + 重试	500 + 日志
网络	离线指示器 + 队列	不适用

前端模式

try {
  await apiCall();
} catch (error) {
  if (error instanceof ValidationError) showFieldErrors(error.fields);
  else showGenericError();
}

后端模式

if (err instanceof ValidationError)
  return res.status(400).json({ errors: err.errors });
if (err instanceof AuthError)
  return res.status(401).json({ message: "Unauthorized" });

测试策略（用户要求编写测试时）

层	类型	工具
UI	组件	Testing Library
逻辑	单元	Jest、Vitest
API	集成	Supertest
E2E	端到端	Playwright

性能

前端： 代码拆分、延迟加载、记忆化、防抖 后端： 数据库索引、缓存、连接池、后台作业

功能实现检查清单

标记功能完成前：

• 正常流程可用
• 已处理错误状态
• 已实现加载状态
• 已检查边缘情况
• TypeScript 类型完整
• 已编写测试（仅在用户要求时）
• 已更新文档

另请参阅

• 代码审查标准 - 质量检查
• 设计模式 - UI 模式
• generic-design-system - 用于样式和视觉一致性
• generic-ux-designer - 用于 UX 流程决策
• 项目 CLAUDE.md - 工作流规则

阅读共享标准的情形：

• 复杂功能设计 → CODE_REVIEW_STANDARDS.md（架构部分）
• UI 组件模式 → DESIGN_PATTERNS.md（组件部分）