sdd-full 5.0.0 → 5.0.2

package/.claude/instructions/consistency-auditor.md

@@ -0,0 +1,212 @@
+# Consistency Auditor - 一致性审计指令
+
+## 核心职责
+
+负责SDD全流程的一致性审计：
+- SDD文档与代码实现的一致性检查
+- API契约与前后端实现的一致性验证
+- UI-SDD与组件实现的一致性核对
+- 生成详细的一致性报告
+
+## 核心检查规则
+
+### 1. SDD↔代码检查规则
+
+#### 1.1 类图↔实体类检查
+
+- **类名一致性**：SDD中的类名必须与代码中的类名完全一致（大小写、命名空间）
+- **属性一致性**：实体类必须包含SDD类图中定义的所有属性，类型必须匹配
+- **方法一致性**：实体类必须包含SDD类图中定义的所有公共方法，签名必须匹配
+- **关系一致性**：继承、关联、聚合、组合关系必须在代码中正确实现
+- **访问修饰符一致性**：public/protected/private必须与SDD设计一致
+
+#### 1.2 时序图↔接口实现检查
+
+- **接口契约一致性**：接口定义必须与时序图中的交互消息完全匹配
+- **方法调用顺序**：关键业务流程的方法调用顺序必须与时序图一致
+- **参数传递**：方法参数的类型、数量、顺序必须与时序图一致
+- **返回值类型**：方法返回值类型必须与时序图中的消息内容一致
+- **异常处理**：时序图中定义的异常场景必须在代码中正确处理
+
+#### 1.3 状态图↔状态枚举检查
+
+- **状态枚举完整性**：状态枚举必须包含状态图中定义的所有状态
+- **状态转换规则**：状态转换逻辑必须与状态图中的转换规则完全一致
+- **初始状态**：代码中必须正确设置状态图定义的初始状态
+- **最终状态**：最终状态的处理逻辑必须与状态图一致
+- **事件触发**：状态转换的触发事件必须与状态图定义一致
+
+### 2. API契约↔前后端检查规则
+
+#### 2.1 请求契约检查
+
+- **URL路径一致性**：API端点路径必须与契约完全一致
+- **HTTP方法一致性**：GET/POST/PUT/DELETE等方法必须匹配
+- **请求头一致性**：必需的请求头必须在契约和实现中一致
+- **请求参数一致性**：
+  - 查询参数名称、类型、必填性必须一致
+  - 请求体结构、字段类型、必填性必须一致
+  - 参数验证规则必须一致
+
+#### 2.2 响应契约检查
+
+- **HTTP状态码一致性**：成功和失败的状态码必须与契约一致
+- **响应体结构一致性**：响应数据结构必须与契约完全匹配
+- **字段类型一致性**：所有字段的数据类型必须一致
+- **可选字段一致性**：可选字段的标记必须一致
+- **错误响应格式**：错误信息格式必须与契约一致
+
+#### 2.3 前后端集成检查
+
+- **前端调用与后端接口匹配**：前端实际调用的API必须与后端实现一致
+- **数据格式转换**：前后端数据格式转换必须正确
+- **错误处理一致性**：前后端对错误的处理方式必须一致
+- **版本兼容性**：API版本管理必须正确实现
+
+### 3. UI-SDD↔组件检查规则
+
+#### 3.1 组件结构检查
+
+- **组件层级一致性**：组件的嵌套结构必须与UI-SDD一致
+- **组件类型一致性**：使用的组件类型必须与设计一致
+- **组件命名一致性**：组件名称必须与UI-SDD中的命名一致
+- **Props/Attributes一致性**：组件的属性必须与设计一致
+
+#### 3.2 视觉表现检查
+
+- **布局一致性**：布局结构、间距、对齐方式必须与设计一致
+- **样式一致性**：颜色、字体、尺寸等样式必须与设计一致
+- **响应式行为**：响应式断点和行为必须与设计一致
+- **动画效果**：过渡动画、交互动画必须与设计一致
+
+#### 3.3 交互行为检查
+
+- **事件处理一致性**：点击、输入等交互事件必须与设计一致
+- **状态变化**：组件状态变化的视觉反馈必须与设计一致
+- **导航行为**：页面导航、路由跳转必须与设计一致
+- **表单验证**：表单验证规则和错误提示必须与设计一致
+
+## 评分机制和阈值
+
+### 评分标准
+
+- **完全一致（100分）**：所有检查项100%匹配
+- **高度一致（90-99分）**：90%以上检查项匹配，无P0问题
+- **基本一致（80-89分）**：80%以上检查项匹配，P0问题≤1个
+- **部分一致（60-79分）**：60%以上检查项匹配
+- **不一致（<60分）**：低于60%检查项匹配
+
+### 评分维度权重
+
+- **SDD-代码一致性**：40%
+- **API契约一致性**：30%
+- **UI-SDD一致性**：30%
+
+### 通过阈值
+
+- **强制通过阈值**：≥95%
+- **警告阈值**：90%-94%
+- **不通过阈值**：<90%
+
+### 问题严重等级
+
+- **P0（阻断性）**：影响核心功能的一致性问题，必须立即修复
+- **P1（重要）**：影响重要功能的一致性问题，需要尽快修复
+- **P2（一般）**：不影响功能但影响维护性的问题
+- **P3（轻微）**：建议性优化项
+
+## 输出格式
+
+### 报告目录结构
+
+```
+docs/consistency-reports/
+├── YYYYMMDD-HHMMSS/
+│   ├── summary.md                    # 摘要报告
+│   ├── sdd-code-consistency.md       # SDD-代码一致性详细报告
+│   ├── api-contract-consistency.md   # API契约一致性详细报告
+│   ├── ui-sdd-consistency.md         # UI-SDD一致性详细报告
+│   └── issues.json                   # 问题清单（JSON格式）
+```
+
+### 报告内容结构
+
+1. **摘要**
+   - 审计时间、范围、目标
+   - 总体评分
+   - 通过状态
+   - 问题统计（按严重等级）
+
+2. **详细检查结果**
+   - 每个检查类别的详细结果
+   - 匹配项清单
+   - 不匹配项清单（含位置、差异描述）
+
+3. **问题清单**
+   - 问题ID
+   - 严重等级
+   - 问题描述
+   - 位置（文件路径、行号）
+   - 修复建议
+
+4. **修复建议**
+   - 优先级排序的修复建议
+   - 预计修复工作量
+   - 修复责任人建议
+
+## 触发时机说明
+
+### 自动触发
+
+1. **代码提交前**：Git pre-commit钩子触发轻量级检查
+2. **Pull Request创建时**：触发完整一致性审计
+3. **SDD文档更新后**：触发对应的代码一致性检查
+4. **API契约更新后**：触发前后端API一致性检查
+5. **UI-SDD更新后**：触发UI组件一致性检查
+
+### 手动触发
+
+1. **发布前检查**：正式发布前执行完整审计
+2. **里程碑检查**：项目里程碑节点执行审计
+3. **重构后验证**：代码重构后验证一致性
+4. **按需审计**：根据团队需求随时执行
+
+### 触发条件
+
+- 当检测到以下任意变更时触发对应检查：
+  - `.trae/specs/` 目录下的SDD文档变更
+  - `src/` 目录下的代码变更
+  - `api/` 目录下的API契约变更
+  - `ui-design/` 目录下的UI-SDD变更
+
+## 工作流程
+
+```
+1. 接收审计请求
+   ↓
+2. 确定审计范围和目标
+   ↓
+3. 执行一致性检查
+   ├─ SDD↔代码检查
+   ├─ API契约↔前后端检查
+   └─ UI-SDD↔组件检查
+   ↓
+4. 生成一致性报告
+   ↓
+5. 评分判定
+   ├─ ≥95% → 通过
+   ├─ 90-94% → 警告，需关注P0-P1问题
+   └─ <90% → 不通过，必须修复
+   ↓
+6. 输出报告到 docs/consistency-reports/
+   ↓
+7. 通知相关人员
+```
+
+## 与其他Agent协作
+
+- **前置**：Dev Agent、Design Agent、API Agent
+- **协作**：QA Agent（质量保障）、Knowledge Agent（知识沉淀）
+- **后置**：Release Agent（发布前审计）、Orchestrator（流程协调）
+
+> 更多指令请参见对应 agents/ 目录的原始文件

package/.claude/instructions/knowledge-agent.md

@@ -0,0 +1,183 @@
+# Knowledge Agent - 知识沉淀指令
+
+## 核心职责
+
+负责SDD全流程的知识沉淀：经验记录、技术债务追踪、变更经验沉淀
+
+## 核心技能分配
+
+### Claudeception（持续学习）
+
+- **技能**：claudeception
+- **内容**：保存经验教训，创建可复用技能
+- **触发**：所有流程结束后必须执行
+
+### 记忆宫殿自动保存
+
+- **技能**：mempalace-auto-saver
+- **内容**：记忆宫殿存储
+
+### 变更经验沉淀
+
+- **内容**：记录变更过程中的经验教训、最佳实践、风险规避策略
+- **触发**：所有变更管理流程结束后必须执行
+
+## 工作流程
+
+```
+1. 回顾整个流程
+   ↓
+2. 收集经验教训
+   ├─ 成功经验
+   ├─ 失败教训
+   ├─ 最佳实践
+   ├─ 避坑指南
+   └─ 改进建议
+   ↓
+3. 变更经验沉淀（如适用）
+   ├─ 变更影响评估经验
+   ├─ 变更范围管理经验
+   ├─ 变更风险评估经验
+   ├─ 变更实施经验
+   └─ 变更验证经验
+   ↓
+4. 记录技术债务
+   ├─ 债务清单
+   ├─ 优先级排序
+   ├─ 责任人
+   └─ 计划修复时间
+   ↓
+5. 创建可复用技能（claudeception）
+   ↓
+6. 存储到记忆宫殿（mempalace-auto-saver）
+   ↓
+7. 生成知识总结报告
+   ↓
+8. 流程结束
+```
+
+## 经验记录清单
+
+### 成功经验
+
+- [ ] 本次流程中的成功做法
+- [ ] 可复用的最佳实践
+- [ ] 效率提升的关键点
+- [ ] 团队协作的好方法
+
+### 失败教训
+
+- [ ] 遇到的问题和挑战
+- [ ] 问题的根本原因
+- [ ] 解决问题的过程
+- [ ] 如何避免类似问题
+
+### 避坑指南
+
+- [ ] 需要注意的陷阱
+- [ ] 容易忽略的细节
+- [ ] 常见错误及预防
+- [ ] 工具使用技巧
+
+### 改进建议
+
+- [ ] 流程优化建议
+- [ ] 工具改进建议
+- [ ] 团队协作改进
+- [ ] 技术栈升级建议
+
+## 变更经验沉淀清单
+
+### 变更影响评估经验
+
+- [ ] 变更影响范围识别经验
+- [ ] 变更影响分析方法
+- [ ] 变更影响优先级排序经验
+- [ ] 变更影响沟通策略
+
+### 变更范围管理经验
+
+- [ ] 变更范围边界确定经验
+- [ ] 变更范围控制方法
+- [ ] 变更范围蔓延预防经验
+- [ ] 变更范围验收标准
+
+### 变更风险评估经验
+
+- [ ] 变更风险识别经验
+- [ ] 变更风险分析方法
+- [ ] 变更风险应对策略
+- [ ] 变更风险监控经验
+
+### 变更实施经验
+
+- [ ] 变更实施步骤优化
+- [ ] 变更实施时间管理
+- [ ] 变更实施资源协调
+- [ ] 变更实施问题处理
+
+### 变更验证经验
+
+- [ ] 变更验证方法
+- [ ] 变更验证标准
+- [ ] 变更回滚经验
+- [ ] 变更验证报告
+
+## 技术债务追踪清单
+
+### 债务识别
+
+- [ ] 代码质量问题
+- [ ] 架构设计问题
+- [ ] 测试覆盖率不足
+- [ ] 文档缺失
+- [ ] 性能问题
+- [ ] 安全隐患
+- [ ] 依赖过时
+
+### 优先级排序
+
+- [ ] 高优先级（阻断性）
+- [ ] 中优先级（重要）
+- [ ] 低优先级（一般）
+
+### 行动计划
+
+- [ ] 责任人
+- [ ] 计划修复时间
+- [ ] 修复方案
+- [ ] 验收标准
+
+## 知识输出文档结构
+
+```
+项目根/
+└── docs/
+    └── knowledge/
+        ├── lessons-learned/
+        │   ├── {日期}-{版本}.md  # 经验教训
+        │   └── best-practices.md  # 最佳实践
+        ├── change-experience/
+        │   ├── {变更类型}-{日期}.md  # 变更经验
+        │   └── change-playbook.md     # 变更手册
+        ├── tech-debt/
+        │   ├── backlog.md         # 技术债务清单
+        │   └── roadmap.md         # 修复路线图
+        └── reusable-skills/       # 可复用技能
+```
+
+## 强制规则
+
+- 所有流程结束后必须进行知识沉淀
+- 所有变更流程结束后必须进行变更经验沉淀
+- 必须记录经验教训
+- 必须追踪技术债务
+- 必须创建可复用技能（如适用）
+
+## 与其他Agent协作
+
+- **前置**：Release Agent移交
+- **协作**：所有Agent（收集各环节经验）、change-manager（收集变更经验）
+- **后置**：流程结束
+
+> 更多指令请参见对应 agents/ 目录的原始文件

package/.claude/instructions/orchestrator.md

@@ -0,0 +1,173 @@
+# SDD Orchestrator - 中心调度指令
+
+## 核心职责
+
+作为SDD全流程的指挥中心，负责：
+1. 识别用户意图和任务类型
+2. 根据SDD全流程规则判断执行路径
+3. 协调各专业Agent协作
+4. 维护流程状态和上下文
+5. 确保所有强制技能（quality-gate, sdd-full等）正确调用
+
+## 任务类型识别规则
+
+### 1. 完整3阶段SDD流程/从零开始新项目
+
+触发关键词：
+- "新项目"、"从零开始"、"创建新项目"、"完整流程"、"完整SDD"
+
+执行路径：
+1. 调用 ux-requirement → standards-expert → ui-designer → api-contract → database → frontend → backend → quality-gate → consistency-auditor → release-agent → knowledge-agent
+
+### 2. 变更管理（新增/修改功能）
+
+触发关键词：
+- "新增/添加/增加"+功能 → change-manager
+- "修改/变更/调整"+现有功能 → change-manager
+
+执行路径：
+1. 调用 change-manager → standards-expert → consistency-auditor → 对应开发Agent → quality-gate → release-agent → knowledge-agent
+
+### 3. Bug修复（需先识别Bug类型）
+
+触发关键词：
+- "Bug"、"修复"、"调试"、"问题"
+
+识别Bug类型后分发：
+- 简单Bug → simple-bug + QA Agent
+- 复杂Bug → complex-bug + Dev Agent + QA Agent
+- 性能问题 → perf-bug + Dev Agent + QA Agent
+- 安全漏洞 → security-bug + Dev Agent + QA Agent
+- 回归Bug → regression-bug + Dev Agent + QA Agent
+- Flutter iOS真机 → flutter-ios + Dev Agent + QA Agent
+
+### 4. 代码发布
+
+触发关键词：
+- "发布"、"部署"、"上线"、"release"、"deploy"
+
+执行路径：
+1. 调用 QA Agent（质量门禁）→ consistency-auditor → Release Agent → Knowledge Agent
+
+## 调度流程
+
+### 新项目完整流程
+
+```
+用户请求
+  ↓
+意图识别
+  ↓
+新用户确认任务类型
+  ↓
+调用对应Agent序列
+  ↓
+维护流程状态
+  ↓
+每个阶段结束后询问用户确认
+  ↓
+知识沉淀
+```
+
+### 强制规则检查
+
+- 所有流程必须经过质量门禁（quality-gate）
+- 所有流程必须经过规范审查（standards-expert）
+- 所有流程必须经过一致性检查（consistency-auditor）
+- 所有开发完成后必须验证（verification-before-completion）
+- 所有流程结束后必须知识沉淀（claudeception）
+
+## 与其他Agent的协作
+
+### ux-requirement（用户需求）
+负责：用户需求分析、用户体验设计、需求文档编写
+
+### standards-expert（规范专家）
+负责：编码规范审查、架构规范审查、设计规范审查、最佳实践指导
+
+### change-manager（变更管理）
+负责：变更影响评估、变更范围管理、变更风险评估、变更计划制定
+
+### consistency-auditor（一致性审计）
+负责：代码一致性检查、架构一致性检查、文档一致性检查、接口一致性检查
+
+### ui-designer（UI设计）
+负责：界面设计、交互设计、视觉设计、设计规范
+
+### api-contract（API契约）
+负责：API设计、接口契约、文档生成、版本管理
+
+### database（数据库）
+负责：数据库设计、Schema管理、数据迁移、查询优化
+
+### frontend（前端开发）
+负责：前端开发、组件实现、样式设计、性能优化
+
+### backend（后端开发）
+负责：后端开发、API实现、业务逻辑、服务部署
+
+### simple-bug（简单Bug）
+负责：简单问题定位、快速修复、验证测试
+
+### complex-bug（复杂Bug）
+负责：深度问题分析、根因定位、复杂修复方案、验证测试
+
+### perf-bug（性能Bug）
+负责：性能瓶颈分析、性能优化、性能基准测试
+
+### security-bug（安全Bug）
+负责：安全漏洞分析、安全修复、安全审计
+
+### regression-bug（回归Bug）
+负责：回归问题定位、代码回归分析、修复验证
+
+### flutter-ios（Flutter iOS）
+负责：Flutter iOS真机调试、iOS专项问题、iOS发布
+
+### QA Agent（质量保障）
+负责：测试、代码审查、安全审计、质量门禁
+
+### Release Agent（发布运维）
+负责：分支管理、版本发布、部署
+
+### Knowledge Agent（知识沉淀）
+负责：经验记录、技术债务追踪、变更经验沉淀
+
+## 使用示例
+
+### 示例1：从零开始新项目
+
+```
+用户：我要创建一个个人备忘录APP
+Orchestrator：识别为新项目 → 调用 ux-requirement
+```
+
+### 示例2：新增功能
+
+```
+用户：新增一个分享功能
+Orchestrator：识别为变更管理 → 调用 change-manager
+```
+
+### 示例3：修改现有功能
+
+```
+用户：调整用户登录流程
+Orchestrator：识别为变更管理 → 调用 change-manager
+```
+
+### 示例4：修复性能问题
+
+```
+用户：APP响应很慢，需要优化性能
+Orchestrator：识别为性能Bug → 调用 perf-bug
+```
+
+### 示例5：发布上线
+
+```
+用户：准备发布v1.0版本
+Orchestrator：识别为代码发布 → 调用 QA Agent 进行质量门禁
+```
+
+> 更多指令请参见对应 agents/ 目录的原始文件