sdd-full 5.0.4 → 5.0.5

package/.claude/skills/code-review-standard/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: code-review-standard
+description: 代码审查标准技能 - 具体的代码审查检查清单和审查流程规范
+---
+
+# code-review-standard - 代码审查标准技能
+
+## 概述
+
+提供具体的代码审查检查清单和审查流程规范，确保代码质量。
+
+**核心原则：客观、具体、建设性**
+
+---
+
+## 1. 代码审查流程
+
+### 1.1 审查前准备
+
+```
+1. 变更范围：PR 不超过 400 行（建议）
+2. 描述清晰：说明变更目的、影响范围
+3. 自测通过：提交前已验证功能
+4. 检查清单：作者先自查
+```
+
+### 1.2 审查中
+
+```
+1. 理解意图：先理解代码做什么
+2. 逐项检查：对照清单检查
+3. 具体反馈：指明问题位置和原因
+4. 建议优先：用建议代替命令
+```
+
+### 1.3 审查后
+
+```
+1. 讨论分歧：有不同意见时及时沟通
+2. 确认修复：确保所有问题都处理
+3. 记录学习：记录有价值的审查点
+```
+
+---
+
+## 2. 代码审查检查清单
+
+### 2.1 功能性检查
+
+- [ ] 功能实现正确，符合需求
+- [ ] 边界条件处理（空值、最大值等）
+- [ ] 错误处理完整
+- [ ] 没有明显的 bug
+
+### 2.2 代码质量检查
+
+- [ ] 命名清晰、有意义
+- [ ] 函数/类单一职责
+- [ ] 没有重复代码
+- [ ] 注释适量，不冗余
+- [ ] 遵循项目代码规范
+
+### 2.3 架构/设计检查
+
+- [ ] 模块划分合理
+- [ ] 依赖关系清晰
+- [ ] 没有引入不必要的依赖
+- [ ] 考虑可扩展性
+
+### 2.4 性能检查
+
+- [ ] 没有明显的性能问题
+- [ ] 避免不必要的计算
+- [ ] 合理使用缓存
+
+### 2.5 安全检查
+
+- [ ] 输入验证/ sanitization
+- [ ] 没有安全漏洞（SQL注入、XSS等）
+- [ ] 敏感数据处理得当
+
+### 2.6 测试检查
+
+- [ ] 有对应的单元测试
+- [ ] 测试覆盖核心场景
+- [ ] 测试清晰、可维护
+
+---
+
+## 3. 审查反馈的写法
+
+### 3.1 好的反馈 vs 坏的反馈
+
+```
+坏的反馈：
+  "这代码写得不好"
+  "你应该用另一种方法"
+
+好的反馈：
+  "这里可以考虑用 xxx 方法，原因是..."
+  "这个变量命名可以更清晰一点，建议叫 xxx"
+  "这部分逻辑有点复杂，能否加个注释？"
+```
+
+### 3.2 反馈分类
+
+- **必须修改**：功能问题、安全问题
+- **建议修改**：可改进点
+- **可选**：风格问题
+
+---
+
+## 4. 常见问题处理
+
+### 4.1 意见分歧
+
+```
+1. 理解对方观点
+2. 提供客观理由
+3. 必要时寻求第三方意见
+4. 以目标为导向，而非个人
+```
+
+### 4.2 大 PR 处理
+
+```
+建议拆分：
+  1. 按功能模块拆分
+  2. 按重构 vs 新功能拆分
+  3. 分阶段提交审查
+```
+
+---
+
+## 5. Flutter/前端/后端 专项检查
+
+### 5.1 Flutter 专项
+
+- [ ] Widget 拆分合理
+- [ ] 状态管理恰当
+- [ ] 性能优化考虑（const、key等）
+
+### 5.2 前端专项
+
+- [ ] 组件复用合理
+- [ ] 状态管理恰当
+- [ ] 响应式/适配考虑
+
+### 5.3 后端专项
+
+- [ ] API 设计合理
+- [ ] 数据库查询优化
+- [ ] 事务处理正确
+
+---
+
+## 6. 审查文化
+
+```
+- 对事不对人
+- 互相学习
+- 感谢审查者的时间
+- 快速响应反馈
+```
+
+## 与其他技能的衔接
+
+- **配合**：code-split-spec、test-driven-development
+- **参考**：sdd-code、quality-gate

package/.claude/skills/code-split-spec/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: code-split-spec
+description: 代码拆分规范 - 指导代码文件、模块、组件的拆分原则和最佳实践
+---
+
+# code-split-spec - 代码拆分规范技能
+
+## 概述
+
+提供代码拆分的统一规范和最佳实践，指导如何合理拆分代码文件、模块、组件，确保代码可维护性、可扩展性。
+
+**核心原则：高内聚、低耦合、单一职责**
+
+## 1. 代码拆分判断标准
+
+### 1.1 何时需要拆分
+
+| 判断维度 | 拆分阈值 | 说明 |
+|---------|---------|------|
+| 文件行数 | >500行 | 单个文件过大，考虑拆分 |
+| 函数行数 | >50行 | 函数过长，提取子函数 |
+| 类/组件职责 | >3个 | 职责过多，拆分为多个类 |
+| 模块依赖 | >5个外部依赖 | 依赖过多，考虑解耦 |
+| 变更频率 | 不同部分变更频率差异大 | 按变更频率拆分 |
+
+### 1.2 何时不应拆分
+
+- 高度耦合的逻辑（必须一起修改）
+- 拆分后导致接口过度复杂
+- 过度设计（YAGNI原则）
+- 小功能（<100行，清晰易懂）
+
+---
+
+## 2. 通用代码拆分规范
+
+### 2.1 文件拆分原则
+
+```
+单一职责：每个文件只负责一个核心功能
+命名清晰：文件名准确表达内容
+层级合理：目录深度不超过5层
+```
+
+### 2.2 模块拆分原则
+
+```
+按功能域拆分：用户、订单、支付等
+按层次拆分：UI层、业务层、数据层
+按依赖方向：核心模块不依赖边缘模块
+```
+
+### 2.3 通用目录结构示例
+
+```
+src/
+├── core/           # 核心基础设施
+│   ├── utils/      # 工具函数
+│   ├── constants/  # 常量定义
+│   └── types/      # 类型定义
+├── features/       # 功能模块（按领域拆分）
+│   ├── user/       # 用户模块
+│   └── order/      # 订单模块
+├── shared/         # 共享组件/模块
+└── app/            # 应用入口、配置
+```
+
+---
+
+## 3. 前端代码拆分规范
+
+### 3.1 React/Vue 组件拆分
+
+#### 组件拆分层级
+
+```
+1. Pages/Views - 页面级组件（路由对应）
+2. Layouts - 布局组件
+3. Features - 业务功能组件
+4. Shared/Common - 通用UI组件
+5. UI Kit - 基础原子组件
+```
+
+#### 组件文件结构示例
+
+```
+features/
+└── user-profile/
+    ├── index.ts           # 模块入口
+    ├── UserProfile.tsx    # 主组件
+    ├── UserProfile.test.tsx
+    ├── components/        # 子组件
+    │   ├── Avatar.tsx
+    │   └── BioEditor.tsx
+    ├── hooks/             # 自定义Hooks
+    │   └── useUserProfile.ts
+    ├── services/          # 服务层
+    │   └── userApi.ts
+    └── types/             # 类型定义
+        └── user.types.ts
+```
+
+### 3.2 状态与逻辑拆分
+
+- **状态管理**：单独的 store/state 目录
+- **业务逻辑**：放在 hooks/services 中，不在组件内
+- **纯函数**：提取到 utils/helpers
+
+---
+
+## 4. 后端代码拆分规范
+
+### 4.1 分层架构拆分
+
+```
+Controller/Handler 层：请求处理、参数校验
+Service 层：业务逻辑
+Repository/DAO 层：数据访问
+Model/Entity 层：数据模型
+```
+
+### 4.2 后端目录结构示例
+
+```
+src/
+├── controllers/    # 控制器层
+├── services/       # 服务层
+├── repositories/   # 数据访问层
+├── models/         # 数据模型
+├── dto/            # 数据传输对象
+├── middleware/     # 中间件
+└── utils/          # 工具
+```
+
+### 4.3 按领域拆分（DDD）
+
+```
+src/
+├── modules/
+│   ├── user/
+│   │   ├── UserController.ts
+│   │   ├── UserService.ts
+│   │   ├── UserRepository.ts
+│   │   └── User.ts
+│   └── order/
+└── shared/
+```
+
+---
+
+## 5. Flutter 代码拆分规范
+
+### 5.1 Flutter 目录结构
+
+```
+lib/
+├── core/
+│   ├── constants/
+│   ├── utils/
+│   ├── theme/
+│   └── router/
+├── features/
+│   └── feature_name/
+│       ├── data/          # 数据层
+│       │   ├── models/
+│       │   ├── datasources/
+│       │   └── repositories/
+│       ├── domain/        # 领域层
+│       │   ├── entities/
+│       │   ├── repositories/
+│       │   └── usecases/
+│       └── presentation/  # 表现层
+│           ├── pages/
+│           ├── widgets/
+│           └── bloc/      # 或 provider/riverpod
+└── shared/
+    ├── widgets/
+    └── utils/
+```
+
+### 5.2 Widget 拆分原则
+
+- 一个 Widget 一个文件
+- 拆分为小的、可复用的 Widget
+- 业务逻辑放在 State 或外部管理类中
+
+---
+
+## 6. 代码拆分检查清单
+
+### 6.1 拆分前检查
+
+- [ ] 明确拆分目标（可维护性、可测试性、复用性）
+- [ ] 分析依赖关系，避免循环依赖
+- [ ] 规划拆分后的目录结构
+- [ ] 评估对现有代码的影响
+
+### 6.2 拆分后检查
+
+- [ ] 单一职责：每个模块/文件职责清晰
+- [ ] 低耦合：模块间依赖最小化
+- [ ] 可测试：拆分后的代码更容易测试
+- [ ] 命名规范：文件/模块命名准确
+- [ ] 文档更新：相关文档同步更新
+
+---
+
+## 7. 常见拆分模式
+
+### 7.1 按职责拆分
+
+```
+// Bad: 一个文件包含太多职责
+class UserManager {
+  validateUser() { ... }
+  saveUser() { ... }
+  sendWelcomeEmail() { ... }
+}
+
+// Good: 按职责拆分
+class UserValidator { ... }
+class UserRepository { ... }
+class EmailService { ... }
+```
+
+### 7.2 按变更频率拆分
+
+- 稳定的核心逻辑 → 独立模块
+- 频繁变更的配置 → 配置文件
+- 可选的功能 → 插件/扩展机制
+
+### 7.3 按复用范围拆分
+
+- 全局复用 → shared/common
+- 模块内复用 → 模块内部
+- 一次性使用 → 就地定义
+
+---
+
+## 8. 重构拆分流程
+
+1. **分析现状**：绘制依赖图，识别耦合点
+2. **制定计划**：明确拆分步骤，避免 breaking change
+3. **小步迭代**：每次只拆分一小部分，确保可运行
+4. **保持测试**：每次拆分后运行测试
+5. **提交验证**：频繁提交，方便回滚
+
+## 与其他技能的衔接
+
+- **前置**：sdd-code（SDD拆分）
+- **配合**：component-split、architecture-refactor
+- **后置**：test-driven-development（测试保障）

package/.claude/skills/component-split/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: component-split
+description: 组件拆分技能 - 前端组件化拆分的最佳实践和可复用性指导
+---
+
+# component-split - 组件拆分技能
+
+## 概述
+
+提供前端组件拆分的统一规范，指导如何将复杂界面拆分为可复用、可测试的小组件。
+
+**核心原则：单一职责、可复用、可组合、可测试**
+
+---
+
+## 1. 组件拆分判断标准
+
+### 1.1 何时拆分组件
+
+| 判断维度 | 拆分阈值 | 说明 |
+|---------|---------|------|
+| JSX/模板行数 | >100行 | 组件过大 |
+| 职责数量 | >2个 | 职责过多 |
+| Props数量 | >7个 | 接口复杂 |
+| 嵌套层级 | >5层 | 难以理解 |
+| 可复用性 | 2+处使用 | 提取为组件 |
+
+### 1.2 组件类型拆分
+
+```
+1. 容器组件（Smart）：负责数据、逻辑
+2. 展示组件（Dumb）：负责UI、样式
+3. 业务组件：特定业务场景
+4. 通用组件：跨场景复用
+5. 布局组件：页面结构
+```
+
+---
+
+## 2. React 组件拆分实践
+
+### 2.1 按职责拆分示例
+
+```typescript
+// Bad: 大而全的组件
+function UserPage() {
+  const [user, setUser] = useState();
+  const [loading, setLoading] = useState();
+  const [formData, setFormData] = useState();
+  
+  useEffect(() => { fetchUser(); }, []);
+  
+  const handleSubmit = () => { ... };
+  
+  return (
+    <div>
+      <header>
+        <nav>...</nav>
+      </header>
+      <main>
+        <div>
+          <img src={user.avatar} />
+          <h1>{user.name}</h1>
+          <form onSubmit={handleSubmit}>
+            ...大量表单代码
+          </form>
+        </div>
+      </main>
+    </div>
+  );
+}
+
+// Good: 按职责拆分
+function UserPage() {
+  const { user, loading } = useUser();
+  return (
+    <PageLayout>
+      <UserHeader user={user} />
+      <UserProfileForm user={user} />
+    </PageLayout>
+  );
+}
+```
+
+### 2.2 组件目录结构
+
+```
+src/components/
+├── layout/
+│   ├── PageLayout.tsx
+│   ├── Header.tsx
+│   └── Sidebar.tsx
+├── ui/                    # 基础UI组件
+│   ├── Button.tsx
+│   ├── Input.tsx
+│   ├── Card.tsx
+│   └── Modal.tsx
+├── user/                  # 用户相关组件
+│   ├── UserAvatar.tsx
+│   ├── UserProfile.tsx
+│   └── UserForm.tsx
+└── product/               # 产品相关组件
+```
+
+---
+
+## 3. Vue 组件拆分实践
+
+### 3.1 组合式函数拆分
+
+```vue
+<!-- Bad: 大组件 -->
+<script setup>
+const user = ref();
+const loading = ref();
+const formData = ref();
+async function fetchUser() { ... }
+function handleSubmit() { ... }
+</script>
+
+<template>
+  <div>
+    <!-- 大量代码 -->
+  </div>
+</template>
+
+<!-- Good: 拆分 -->
+<script setup>
+const { user, loading } = useUser();
+</script>
+
+<template>
+  <PageLayout>
+    <UserHeader :user="user" />
+    <UserProfileForm :user="user" />
+  </PageLayout>
+</template>
+```
+
+---
+
+## 4. Flutter Widget 拆分实践
+
+### 4.1 Widget 拆分原则
+
+```dart
+// Bad: 大而全的 build 方法
+class UserPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('User')),
+      body: Column(
+        children: [
+          // ... 大量嵌套代码
+        ],
+      ),
+    );
+  }
+}
+
+// Good: 拆分为小 Widget
+class UserPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: const UserPageAppBar(),
+      body: Column(
+        children: const [
+          UserAvatar(),
+          UserProfile(),
+          UserActionButtons(),
+        ],
+      ),
+    );
+  }
+}
+
+class UserPageAppBar extends StatelessWidget { ... }
+class UserAvatar extends StatelessWidget { ... }
+class UserProfile extends StatelessWidget { ... }
+```
+
+---
+
+## 5. 组件设计原则
+
+### 5.1 Props 设计
+
+- **少而精**：不超过7个props
+- **单一数据结构**：相关数据组合为对象
+- **回调函数命名**：on+动作，如 `onClick`、`onSubmit`
+
+```typescript
+// Bad: props过多
+<Component 
+  title="..." 
+  subtitle="..." 
+  avatar="..." 
+  onClick={...} 
+  onEdit={...}
+/>
+
+// Good: 组合数据
+<Component user={user} onAction={handleAction} />
+```
+
+### 5.2 组件通信
+
+```
+1. 父 → 子：Props
+2. 子 → 父：回调函数
+3. 兄弟：共同父组件 + 状态提升
+4. 跨层级：Context/Provider/状态管理
+```
+
+---
+
+## 6. 可复用性设计
+
+### 6.1 组件抽象层级
+
+```
+原子组件：Button、Input、Icon
+  ↓
+复合组件：SearchBar（Input+Button）、FormField
+  ↓
+业务组件：UserCard、ProductList
+  ↓
+页面组件：UserPage、ProductDetail
+```
+
+### 6.2 复用 vs 复制
+
+- **复用**：逻辑相同，仅数据不同
+- **复制**：看起来相似，实则独立演进
+
+---
+
+## 7. 组件拆分检查清单
+
+- [ ] 单一职责：每个组件只做一件事
+- [ ] Props简洁：不超过7个
+- [ ] 可测试：容易编写单元测试
+- [ ] 可复用：考虑未来复用场景
+- [ ] 命名清晰：见名知意
+- [ ] 文档完整：关键用法有示例
+
+## 与其他技能的衔接
+
+- **配合**：code-split-spec、state-management
+- **参考**：design-to-code、sdd-code