Initial commit
This commit is contained in:
Zhongwei Li
158
commands/analyze-dependencies.md
Normal file
158
commands/analyze-dependencies.md
Normal file
@@ -0,0 +1,158 @@
|
||||
## 依赖关系分析
|
||||
|
||||
分析项目的依赖关系，评估架构的健康状况。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/dependency-analysis [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--visual` : 可视化显示依赖关系
|
||||
- `--circular` : 仅检测循环依赖
|
||||
- `--depth <数值>` : 指定分析深度 (默认: 3)
|
||||
- `--focus <路径>` : 聚焦于特定模块/目录
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 整个项目的依赖关系分析
|
||||
/dependency-analysis
|
||||
|
||||
# 检测循环依赖
|
||||
/dependency-analysis --circular
|
||||
|
||||
# 特定模块的详细分析
|
||||
/dependency-analysis --focus src/core --depth 5
|
||||
```
|
||||
|
||||
### 分析项目
|
||||
|
||||
#### 1. 依赖关系矩阵
|
||||
|
||||
数值化显示模块间的依赖关系：
|
||||
|
||||
- 直接依赖
|
||||
- 间接依赖
|
||||
- 依赖深度
|
||||
- 扇入/扇出
|
||||
|
||||
#### 2. 架构违规检测
|
||||
|
||||
- 层级违规 (下层依赖上层)
|
||||
- 循环依赖
|
||||
- 过度耦合 (高依赖度)
|
||||
- 孤立模块
|
||||
|
||||
#### 3. Clean Architecture 合规性检查
|
||||
|
||||
- 领域层的独立性
|
||||
- 基础设施层的适当分离
|
||||
- 用例层的依赖方向
|
||||
- 接口的应用情况
|
||||
|
||||
### 输出示例
|
||||
|
||||
```text
|
||||
依赖关系分析报告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 指标概览
|
||||
├─ 模块总数: 42
|
||||
├─ 平均依赖数: 3.2
|
||||
├─ 最大依赖深度: 5
|
||||
└─ 循环依赖: 检测到 2 个
|
||||
|
||||
⚠️ 架构违规
|
||||
├─ [HIGH] src/domain/user.js → src/infra/database.js
|
||||
│ └─ 领域层直接依赖基础设施层
|
||||
├─ [MED] src/api/auth.js ⟲ src/services/user.js
|
||||
│ └─ 检测到循环依赖
|
||||
└─ [LOW] src/utils/helper.js → 12 modules
|
||||
└─ 扇出过度
|
||||
|
||||
✅ 建议操作
|
||||
1. 引入 UserRepository 接口
|
||||
2. 重新设计认证服务的职责
|
||||
3. 按功能拆分辅助函数
|
||||
|
||||
📈 依赖关系图
|
||||
[用 ASCII 艺术显示可视化依赖关系图]
|
||||
```
|
||||
|
||||
### 高级用法
|
||||
|
||||
```bash
|
||||
# CI/CD 管道中的自动检查
|
||||
/dependency-analysis --circular --fail-on-violation
|
||||
|
||||
# 定义和验证架构规则
|
||||
/dependency-analysis --rules .architecture-rules.yml
|
||||
|
||||
# 追踪依赖关系的时间变化
|
||||
/dependency-analysis --compare HEAD~10
|
||||
```
|
||||
|
||||
### 配置文件示例 (.dependency-analysis.yml)
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: "Domain Independence"
|
||||
source: "src/domain/**"
|
||||
forbidden: ["src/infra/**", "src/api/**"]
|
||||
|
||||
- name: "API Layer Dependencies"
|
||||
source: "src/api/**"
|
||||
allowed: ["src/domain/**", "src/application/**"]
|
||||
forbidden: ["src/infra/**"]
|
||||
|
||||
thresholds:
|
||||
max_dependencies: 8
|
||||
max_depth: 4
|
||||
coupling_threshold: 0.7
|
||||
|
||||
ignore:
|
||||
- "**/test/**"
|
||||
- "**/mocks/**"
|
||||
```
|
||||
|
||||
### 集成工具
|
||||
|
||||
- `madge` : JavaScript/TypeScript 依赖关系可视化
|
||||
- `dep-cruiser` : 依赖关系规则验证
|
||||
- `nx` : 单体仓库依赖关系管理
|
||||
- `plato` : 复杂度与依赖关系综合分析
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 包含 package.json 的分析
|
||||
cat package.json
|
||||
/analyze-dependencies
|
||||
"分析这个项目的依赖关系问题"
|
||||
|
||||
# 结合特定模块的源代码
|
||||
ls -la src/core/
|
||||
/analyze-dependencies --focus src/core
|
||||
"详细评估核心模块的依赖关系"
|
||||
|
||||
# 与架构文档对比
|
||||
cat docs/architecture.md
|
||||
/analyze-dependencies --visual
|
||||
"确认设计文档与实现的差异"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **前提条件**: 需要在项目根目录执行
|
||||
- **限制事项**: 大型项目的分析可能需要较长时间
|
||||
- **建议事项**: 发现循环依赖时应立即考虑处理
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **定期分析**: 每周检查依赖关系的健康状况
|
||||
2. **规则明文化**: 通过配置文件管理架构规则
|
||||
3. **渐进式改进**: 避免大规模重构，逐步改进
|
||||
4. **指标追踪**: 监控依赖关系复杂度的时间序列
|
||||
169
commands/analyze-performance.md
Normal file
169
commands/analyze-performance.md
Normal file
@@ -0,0 +1,169 @@
|
||||
## 性能分析
|
||||
|
||||
从用户体验角度分析应用程序性能，量化改进后的感知速度提升。基于 Core Web Vitals 计算 UX 评分，提出优先级明确的优化策略。
|
||||
|
||||
### UX 性能评分
|
||||
|
||||
```text
|
||||
用户体验评分: B+ (78/100)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
⏱️ Core Web Vitals
|
||||
├─ LCP (加载): 2.3 秒 [Good] 目标<2.5 秒 ✅
|
||||
├─ FID (交互响应): 95ms [Good] 目标<100ms ✅
|
||||
├─ CLS (视觉稳定): 0.08 [Good] 目标<0.1 ✅
|
||||
├─ FCP (首次绘制): 1.8 秒 [Good] 目标<1.8 秒 ✅
|
||||
├─ TTFB (服务器): 450ms [Needs Work] 目标<200ms ⚠️
|
||||
└─ TTI (可交互): 3.5 秒 [Needs Work] 目标<3.8 秒 ⚠️
|
||||
|
||||
📊 用户感知速度
|
||||
├─ 首次显示体验: 2.3 秒 [行业平均: 3.0 秒]
|
||||
├─ 页面切换: 1.1 秒 [行业平均: 1.5 秒]
|
||||
├─ 搜索结果显示: 0.8 秒 [行业平均: 1.2 秒]
|
||||
├─ 表单提交: 1.5 秒 [行业平均: 2.0 秒]
|
||||
└─ 图片加载: 已实现延迟加载 ✅
|
||||
|
||||
😊 用户满意度预测
|
||||
├─ 跳出率预测: 12% (行业平均: 20%)
|
||||
├─ 完成率预测: 78% (目标: 85%)
|
||||
├─ 推荐 NPS: +24 (行业平均: +15)
|
||||
└─ 回访率: 65% (目标: 70%)
|
||||
|
||||
📊 用户体验影响
|
||||
├─ 显示速度缩短 0.5 秒 → 跳出率 -7%
|
||||
├─ 跳出率降低 5% → 会话时长 +15%
|
||||
├─ 搜索改进 → 停留时间 +15%
|
||||
└─ 综合 UX 改进度: +25%
|
||||
|
||||
🎯 改进预期效果 (优先级排序)
|
||||
├─ [P0] TTFB 改善 (CDN 引入) → LCP -0.3 秒 = 感知速度 +15%
|
||||
├─ [P1] JS 包优化 → TTI -0.8 秒 = 可交互时间 -20%
|
||||
├─ [P2] 图片优化 (WebP) → 传输量 -40% = 加载时间 -25%
|
||||
└─ [P3] 缓存策略 → 回访时速度提升 50%
|
||||
```
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# UX 评分综合分析
|
||||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||||
"计算 UX 性能评分，评估 Core Web Vitals"
|
||||
|
||||
# 性能瓶颈检测
|
||||
grep -r "for.*await\|forEach.*await" . --include="*.js"
|
||||
"检测异步处理瓶颈，分析对用户体验的影响"
|
||||
|
||||
# 用户体验影响分析
|
||||
grep -r "addEventListener\|setInterval" . --include="*.js" | grep -v "removeEventListener\|clearInterval"
|
||||
"分析性能问题对用户体验的影响"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 包体积和加载时间
|
||||
npm ls --depth=0 && find ./public -name "*.js" -o -name "*.css" | xargs ls -lh
|
||||
"识别包体积和资源优化的改进点"
|
||||
|
||||
# 数据库性能
|
||||
grep -r "SELECT\|findAll\|query" . --include="*.js" | head -20
|
||||
"分析数据库查询的优化点"
|
||||
|
||||
# 依赖关系的性能影响
|
||||
npm outdated && npm audit
|
||||
"评估过时依赖对性能的影响"
|
||||
|
||||
```
|
||||
|
||||
### 分析视角
|
||||
|
||||
#### 1. 代码层面的问题
|
||||
|
||||
- **O(n²) 算法**: 检测低效的数组操作
|
||||
- **同步 I/O**: 识别阻塞处理
|
||||
- **重复处理**: 删除不必要的计算或请求
|
||||
- **内存泄漏**: 事件监听器和定时器管理
|
||||
|
||||
#### 2. 架构层面的问题
|
||||
|
||||
- **N+1 查询**: 数据库访问模式
|
||||
- **缓存不足**: 重复计算或 API 调用
|
||||
- **包体积**: 不必要的库或代码分割
|
||||
- **资源管理**: 连接池或线程使用量
|
||||
|
||||
#### 3. 技术债务带来的影响
|
||||
|
||||
- **遗留代码**: 旧实现导致的性能下降
|
||||
- **设计问题**: 责任分散不足导致的高耦合度
|
||||
- **测试不足**: 性能回归检测遗漏
|
||||
- **监控不足**: 问题早期发现体系
|
||||
|
||||
### 性能改进 ROI 矩阵
|
||||
|
||||
```text
|
||||
改进 ROI = (时间缩短效果 + 质量提升) ÷ 实现工时
|
||||
```
|
||||
|
||||
| 优先级 | 用户体验提升 | 实现难度 | 时间缩短效果 | 具体示例 | 工时 | 效果 |
|
||||
| --------------------- | ------------ | -------- | ------------ | -------- | ---- | --------- |
|
||||
| **[P0] 应立即实现** | 高 | 低 | > 50% | CDN 引入 | 8h | 响应 -60% |
|
||||
| **[P1] 建议早期实现** | 高 | 中 | 20-50% | 图片优化 | 16h | 加载 -30% |
|
||||
| **[P2] 计划性实现** | 低 | 高 | 10-20% | 代码分割 | 40h | 首次 -15% |
|
||||
| **[P3] 暂缓/观望** | 低 | 低 | < 10% | 微调优化 | 20h | 局部 -5% |
|
||||
|
||||
#### 优先级判定标准
|
||||
|
||||
- **P0(立即实现)**: UX 提升「高」× 难度「低」= ROI 最大
|
||||
- **P1(早期实现)**: UX 提升「高」× 难度「中」= ROI 高
|
||||
- **P2(计划性)**: UX 提升「低」× 难度「高」= ROI 中
|
||||
- **P3(暂缓)**: UX 提升「低」× 难度「低」= ROI 低
|
||||
|
||||
### 测量和工具
|
||||
|
||||
#### Node.js / JavaScript
|
||||
|
||||
```bash
|
||||
# 性能分析
|
||||
node --prof app.js
|
||||
clinic doctor -- node app.js
|
||||
|
||||
# 包分析
|
||||
npx webpack-bundle-analyzer
|
||||
lighthouse --chrome-flags="--headless"
|
||||
```
|
||||
|
||||
#### 数据库
|
||||
|
||||
```sql
|
||||
-- 查询分析
|
||||
EXPLAIN ANALYZE SELECT ...
|
||||
SHOW SLOW LOG;
|
||||
```
|
||||
|
||||
#### 前端
|
||||
|
||||
```bash
|
||||
# React 性能
|
||||
grep -r "useMemo\|useCallback" . --include="*.jsx"
|
||||
|
||||
# 资源分析
|
||||
find ./src -name "*.png" -o -name "*.jpg" | xargs ls -lh
|
||||
```
|
||||
|
||||
### 性能指标与 UX 改进相关性
|
||||
|
||||
| 指标 | 改进幅度 | 感知速度提升 | 用户满意度 | 实现工时 |
|
||||
| ------------------ | -------- | ------------ | ------------- | -------- |
|
||||
| **LCP (加载)** | -0.5 秒 | +30% | 跳出率 -7% | 16h |
|
||||
| **FID (交互响应)** | -50ms | +15% | 压力感 -20% | 8h |
|
||||
| **CLS (视觉稳定)** | -0.05 | +10% | 误操作 -50% | 4h |
|
||||
| **TTFB (服务器)** | -200ms | +25% | 感知速度 +40% | 24h |
|
||||
| **TTI (可交互)** | -1.0 秒 | +35% | 完成率 +15% | 32h |
|
||||
| **包体积** | -30% | +20% | 首次访问 +25% | 16h |
|
||||
|
||||
### 持续改进
|
||||
|
||||
- **定期审计**: 每周性能测试执行
|
||||
- **指标收集**: 响应时间、内存使用量追踪
|
||||
- **告警设置**: 阈值超过时自动通知
|
||||
- **团队共享**: 改进案例和反模式文档化
|
||||
104
commands/check-fact.md
Normal file
104
commands/check-fact.md
Normal file
@@ -0,0 +1,104 @@
|
||||
## 事实检查
|
||||
|
||||
参考项目内的代码库、文档 (docs/、README.md 等)，确认所给信息的正确性。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 基本用法
|
||||
/check-fact "Flutter 应用使用了 Riverpod"
|
||||
|
||||
# 一次性确认多个信息
|
||||
/check-fact "这个项目使用 GraphQL，并通过 auto_route 管理路由"
|
||||
|
||||
# 确认特定技术规范
|
||||
/check-fact "使用 JWT 进行身份验证，未使用 Firebase Auth"
|
||||
```
|
||||
|
||||
### 确认流程
|
||||
|
||||
1. **信息源优先级**
|
||||
- 代码库 (最可靠)
|
||||
- README.md、docs/ 内文档
|
||||
- package.json、pubspec.yaml 等配置文件
|
||||
- Issue、Pull Request 的讨论历史
|
||||
|
||||
2. **判定结果分类**
|
||||
- `✅ 正确` - 信息与代码库完全一致
|
||||
- `❌ 错误` - 信息明显错误
|
||||
- `⚠️ 部分正确` - 部分准确但不完整
|
||||
- `❓ 无法判断` - 缺少必要的确认信息
|
||||
|
||||
3. **依据明示**
|
||||
- 相关文件名和行号
|
||||
- 相关代码片段
|
||||
- 文档相关部分
|
||||
|
||||
### 报告格式
|
||||
|
||||
```text
|
||||
## 事实检查结果
|
||||
|
||||
### 检验对象
|
||||
「[用户提供的信息]」
|
||||
|
||||
### 结论
|
||||
[✅/❌/⚠️/❓] [判定结果]
|
||||
|
||||
### 依据
|
||||
- **文件**: `path/to/file.dart:123`
|
||||
- **内容**: [相关代码/文本]
|
||||
- **补充**: [额外说明]
|
||||
|
||||
### 详细说明
|
||||
[如果错误，提供正确信息]
|
||||
[如果部分正确，指出不准确的部分]
|
||||
[如果无法判断，说明缺少的信息]
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 项目技术栈确认
|
||||
/check-fact "这个应用是 Flutter + Riverpod + GraphQL 的架构"
|
||||
|
||||
# 实现状况确认
|
||||
/check-fact "已实现暗黑模式功能，可从用户设置切换"
|
||||
|
||||
# 架构确认
|
||||
/check-fact "状态管理全部使用 Riverpod，未使用 BLoC"
|
||||
|
||||
# 安全实现确认
|
||||
/check-fact "认证令牌已加密存储在 secure storage 中"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 分析整个代码库后进行确认
|
||||
ls -la && find . -name "pubspec.yaml" -exec cat {} \;
|
||||
/check-fact "这个项目使用的主要依赖有..."
|
||||
|
||||
# 确认特定功能的实现状况
|
||||
grep -r "authentication" . --include="*.dart"
|
||||
/check-fact "认证功能为自定义实现，未使用第三方认证"
|
||||
|
||||
# 确认与文档的一致性
|
||||
cat README.md
|
||||
/check-fact "README 中记载的功能都已实现"
|
||||
```
|
||||
|
||||
### 应用场景
|
||||
|
||||
- 技术规格书编写时: 确认内容准确性
|
||||
- 项目交接时: 确认对现有实现的理解
|
||||
- 客户报告前: 确认实现状况
|
||||
- 技术博客撰写时: 验证文章内容准确性
|
||||
- 面试·说明资料制作时: 确认项目概要准确性
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 代码库是最可靠的信息源
|
||||
- 如果文档过时，以实现为准
|
||||
- 缺少判断所需信息时，坦诚回答"无法判断"
|
||||
- 对涉及安全的信息要特别谨慎验证
|
||||
53
commands/check-github-ci.md
Normal file
53
commands/check-github-ci.md
Normal file
@@ -0,0 +1,53 @@
|
||||
## GitHub CI 监控
|
||||
|
||||
监控 GitHub Actions CI 状态，并跟踪到完成。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 检查 CI 状态
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# PR 创建后的 CI 确认
|
||||
gh pr create --title "新功能添加" --body "说明"
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# CI 确认到修复的流程
|
||||
gh pr checks
|
||||
"分析 CI 检查结果，如有失败项目请提出修复方案"
|
||||
|
||||
# 修复后的再确认
|
||||
git push origin feature-branch
|
||||
gh pr checks
|
||||
"确认修复后的 CI 结果，确保没有问题"
|
||||
```
|
||||
|
||||
### 执行结果示例
|
||||
|
||||
```text
|
||||
All checks were successful
|
||||
0 cancelled, 0 failing, 8 successful, 3 skipped, and 0 pending checks
|
||||
|
||||
NAME DESCRIPTION ELAPSED URL
|
||||
○ Build/test (pull_request) 5m20s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Build/lint (pull_request) 2m15s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Security/scan (pull_request) 1m30s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Type Check (pull_request) 45s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Commit Messages (pull_request) 12s https://github.com/user/repo/actions/runs/123456789
|
||||
- Deploy Preview (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
- Visual Test (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 失败时需要详细确认
|
||||
- 等待所有检查完成后再合并
|
||||
- 必要时重新执行 `gh pr checks`
|
||||
461
commands/check-prompt.md
Normal file
461
commands/check-prompt.md
Normal file
@@ -0,0 +1,461 @@
|
||||
## 提示词检查
|
||||
|
||||
AI Agent 提示词质量评估与改进的全面最佳实践集。基于实际提示词改进过程中积累的经验，系统化地涵盖了消除歧义、信息整合、强制力强化、追踪系统、持续改进等所有重要方面。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 检查提示词文件的质量
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"检查这个提示词的质量并提出改进建议"
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- 无 : 分析当前文件或选中的文本
|
||||
- `--category <name>` : 仅检查特定类别 (structure/execution/restrictions/quality/roles/improvement)
|
||||
- `--score` : 仅计算质量分数
|
||||
- `--fix` : 自动修正建议
|
||||
- `--deep` : 深度分析模式 (重点检查歧义性、信息分散、强制力)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 提示词整体质量评估
|
||||
cat devin/playbooks/code-review.md
|
||||
/check-prompt
|
||||
"从 6 个类别评估这个提示词的质量，指出问题并提出改进方案"
|
||||
|
||||
# 深度分析模式
|
||||
/check-prompt --deep
|
||||
"重点检查歧义性、信息分散、强制力不足，提出根本性改进方案"
|
||||
|
||||
# 特定类别检查
|
||||
/check-prompt --category structure
|
||||
"从结构和清晰度角度检查这个提示词"
|
||||
|
||||
# 模糊表达检测与修正
|
||||
/check-prompt --fix
|
||||
"检测模糊表达并提出明确的修正建议"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心设计原则
|
||||
|
||||
### 原则 1: 完全消除解释空间
|
||||
|
||||
- **绝对禁止**: "原则上"、"推荐"、"如果可能"、"根据情况"、"酌情判断"
|
||||
- **必须使用**: "必须"、"绝对"、"严格遵守"、"无例外"、"强制"
|
||||
- **例外条件**: 用数值严格限定 ("仅以下 3 个条件"、"除这 2 种情况外")
|
||||
|
||||
### 原则 2: 信息的战略性整合
|
||||
|
||||
- 相关重要信息完全整合到一个部分
|
||||
- 在执行清单中总结全貌
|
||||
- 彻底消除循环引用或分散
|
||||
|
||||
### 原则 3: 构建分级强制力
|
||||
|
||||
- 🔴 (执行停止级) → 🟡 (质量重要) → 🟢 (建议事项) 的明确层级
|
||||
- 从推荐级逐步升级到必须级
|
||||
- 明示违反时的影响程度和处理方法
|
||||
|
||||
### 原则 4: 确保可追踪性
|
||||
|
||||
- 所有执行结果可记录、验证
|
||||
- 技术上防止虚假报告
|
||||
- 成功/失败的客观判断标准
|
||||
|
||||
### 原则 5: 反馈驱动改进
|
||||
|
||||
- 从实际失败案例中学习
|
||||
- 持续验证有效性
|
||||
- 自动检测新模式
|
||||
|
||||
---
|
||||
|
||||
## 📋 全面检查项目
|
||||
|
||||
### 1. 📐 结构与清晰度 (配分: 25 分)
|
||||
|
||||
#### 1.1 指示优先级显示 (8 分)
|
||||
|
||||
- [ ] 🔴🟡🟢 优先级标记在所有重要指示上
|
||||
- [ ] 执行停止级条件具体且明确定义
|
||||
- [ ] 各优先级判断标准客观且可验证
|
||||
- [ ] 优先级层级一致应用
|
||||
|
||||
#### 1.2 完全消除模糊表达 (9 分)
|
||||
|
||||
- [ ] **致命模糊表达**: "原则上"、"推荐"、"如果可能"为 0 个
|
||||
- [ ] **强制表达使用**: 适当使用"必须"、"绝对"、"严格遵守"、"无例外"
|
||||
- [ ] **例外条件数值限定**: "仅 3 个条件"等明确边界
|
||||
- [ ] **消除判断余地**: 仅使用不可能多重解释的表达
|
||||
- [ ] **消灭灰色地带**: 所有情况都有明确判断标准
|
||||
|
||||
#### 1.3 信息的战略性整合 (8 分)
|
||||
|
||||
- [ ] 完全解决重要信息在多处分散的问题
|
||||
- [ ] 相关指示逻辑地整合到一个部分
|
||||
- [ ] 执行清单完整总结全貌
|
||||
- [ ] 不存在循环引用或无限循环
|
||||
|
||||
### 2. 🎯 可执行性 (配分: 20 分)
|
||||
|
||||
#### 2.1 具体步骤的完整性 (7 分)
|
||||
|
||||
- [ ] 所有命令示例实际可执行且已验证
|
||||
- [ ] 环境变量、前提条件、依赖关系完整记录
|
||||
- [ ] 错误处理方法具体且可执行
|
||||
- [ ] 步骤顺序逻辑且必然
|
||||
|
||||
#### 2.2 确保可验证性 (7 分)
|
||||
|
||||
- [ ] 执行结果的成功/失败可客观判断
|
||||
- [ ] 输出示例、日志格式、期望值具体展示
|
||||
- [ ] 测试方法、验证步骤可实施
|
||||
- [ ] 中间结果确认点适当配置
|
||||
|
||||
#### 2.3 自动化适应性 (6 分)
|
||||
|
||||
- [ ] 易于脚本化、CI/CD 集成的格式
|
||||
- [ ] 人工判断与 AI 执行部分明确分离
|
||||
- [ ] 支持批处理、并行执行
|
||||
|
||||
### 3. 🚫 明确禁止事项 (配分: 15 分)
|
||||
|
||||
#### 3.1 绝对禁止事项的系统化 (8 分)
|
||||
|
||||
- [ ] 完整列出不可执行的操作
|
||||
- [ ] 明示各禁止事项的违反影响度 (轻微/重大/致命)
|
||||
- [ ] 具体提示替代手段、规避方法
|
||||
- [ ] 说明禁止事项的技术依据
|
||||
|
||||
#### 3.2 严格限定例外条件 (7 分)
|
||||
|
||||
- [ ] 允许例外的条件具体且限定 (数值指定)
|
||||
- [ ] "完全重复"、"明确记载"等客观判断标准
|
||||
- [ ] 不留灰色地带的明确边界
|
||||
- [ ] 明示例外适用时的追加条件、限制
|
||||
|
||||
### 4. 📊 质量保证机制 (配分: 20 分)
|
||||
|
||||
#### 4.1 追踪系统的完整性 (8 分)
|
||||
|
||||
- [ ] 全执行结果自动记录、统计获取功能
|
||||
- [ ] 技术上防止虚假报告的验证功能
|
||||
- [ ] 实时监控、告警功能
|
||||
- [ ] 审计日志防篡改功能
|
||||
|
||||
#### 4.2 模板遵守的强制 (7 分)
|
||||
|
||||
- [ ] 必要元素的明确定义和检查功能
|
||||
- [ ] 禁止自定义部分的技术限制
|
||||
- [ ] 自动化的遵守确认检查点
|
||||
- [ ] 违反时的自动修正、警告功能
|
||||
|
||||
#### 4.3 错误处理的全面性 (5 分)
|
||||
|
||||
- [ ] 预期错误模式的完整目录化
|
||||
- [ ] 错误时的分级处理流程
|
||||
- [ ] 技术上防止将失败报告为成功
|
||||
|
||||
### 5. 🎭 角色与责任的明确化 (配分: 10 分)
|
||||
|
||||
#### 5.1 AI Agent 的权限范围 (5 分)
|
||||
|
||||
- [ ] 可执行操作与禁止操作的明确边界
|
||||
- [ ] 判断权限的具体范围和限制
|
||||
- [ ] 需要人工确认的操作明确分离
|
||||
|
||||
#### 5.2 分类系统的统一 (5 分)
|
||||
|
||||
- [ ] 分类定义的明确性、唯一性、排他性
|
||||
- [ ] 防止分类间重要度误解的明确说明
|
||||
- [ ] 各分类的具体使用示例和判断流程图
|
||||
|
||||
### 6. 🔄 持续改进 (配分: 10 分)
|
||||
|
||||
#### 6.1 反馈收集的自动化 (5 分)
|
||||
|
||||
- [ ] 从执行日志自动提取改进点
|
||||
- [ ] 基于机器学习的失败模式分析
|
||||
- [ ] 最佳实践的自动更新机制
|
||||
|
||||
#### 6.2 学习功能的实现 (5 分)
|
||||
|
||||
- [ ] 新模式的自动检测、分类
|
||||
- [ ] 现有规则有效性的持续监控
|
||||
- [ ] 渐进式改进的自动建议
|
||||
|
||||
---
|
||||
|
||||
## 🚨 致命问题模式 (需立即修正)
|
||||
|
||||
### ❌ 级别 1: 致命歧义 (执行停止级)
|
||||
|
||||
- **多重解释可能的指示**: "酌情判断"、"根据情况"、"原则上"
|
||||
- **模糊的例外条件**: "特殊情况下"、"必要时"
|
||||
- **主观判断标准**: "适当地"、"充分地"、"尽可能"
|
||||
- **未定义的重要概念**: "标准的"、"一般的"、"基本的"
|
||||
|
||||
### ❌ 级别 2: 结构缺陷 (质量重要级)
|
||||
|
||||
- **信息分散**: 相关重要信息散布在 3 处以上
|
||||
- **循环引用**: 部分 A→B→C→A 的无限循环
|
||||
- **矛盾指示**: 不同部分有相反的指示
|
||||
- **执行顺序不明**: 依赖关系不明确的步骤
|
||||
|
||||
### ❌ 级别 3: 质量下降 (建议改进级)
|
||||
|
||||
- **不可验证性**: 成功/失败判断标准不明
|
||||
- **自动化困难**: 依赖人工主观判断的设计
|
||||
- **维护困难**: 更新时影响范围不可预测的结构
|
||||
- **学习困难**: 新人理解需要时间的复杂度
|
||||
|
||||
---
|
||||
|
||||
## 🎯 经过验证的改进方法
|
||||
|
||||
### ✅ 分阶段强化方法
|
||||
|
||||
1. **现状分析**: 问题分类、优先级排序、影响度评估
|
||||
2. **致命问题优先**: 最优先完全解决级别 1 问题
|
||||
3. **分阶段实施**: 不一次性全部更改，以可验证单位实施
|
||||
4. **效果测量**: 改进前后的定量比较
|
||||
5. **持续监控**: 确认改进效果的持续性
|
||||
|
||||
### ✅ 消除歧义的实践方法
|
||||
|
||||
```markdown
|
||||
# ❌ 改进前 (模糊)
|
||||
|
||||
"原则上，请将指摘事项作为内联评论记录在 GitHub 上相应的更改位置"
|
||||
|
||||
# ✅ 改进后 (明确)
|
||||
|
||||
"必须将指摘事项作为内联评论记录在 GitHub 上相应的更改位置。例外仅限于第 3.3 节定义的 3 个条件"
|
||||
```
|
||||
|
||||
### ✅ 信息整合的实践方法
|
||||
|
||||
```markdown
|
||||
# ❌ 改进前 (分散)
|
||||
|
||||
第 2.1 节: "使用必需的 6 个部分"
|
||||
第 3.5 节: "📊 综合评价、📋 指摘事项..."
|
||||
第 4.2 节: "禁止删除部分"
|
||||
|
||||
# ✅ 改进后 (整合)
|
||||
|
||||
执行清单:
|
||||
□ 10. 发布总结评论 (必须使用 6 个部分)
|
||||
🔴 必需的 6 个部分： 1) 📊 综合评价 2) 📋 分类别指摘事项汇总 3) ⚠️ 主要关注点 4) ✅ 值得肯定的点 5) 🎯 结论 6) 🤖 AI 审查质量自我评价
|
||||
❌ 绝对禁止：删除、添加、重命名部分
|
||||
```
|
||||
|
||||
### ✅ 追踪系统的实施模式
|
||||
|
||||
```bash
|
||||
# 严格追踪执行结果
|
||||
POSTED_COMMENTS=0
|
||||
FAILED_COMMENTS=0
|
||||
TOTAL_COMMENTS=0
|
||||
|
||||
# 记录各操作结果
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ 成功: $OPERATION" >> /tmp/execution_log.txt
|
||||
POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
|
||||
else
|
||||
echo "❌ 失败: $OPERATION" >> /tmp/execution_log.txt
|
||||
FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
|
||||
fi
|
||||
|
||||
# 防止虚假报告
|
||||
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
|
||||
echo "🚨 警告: 报告数与实际发布数不一致"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 质量分数计算 (改进版)
|
||||
|
||||
### 综合分数计算
|
||||
|
||||
```text
|
||||
基础分数 = Σ(各类别分数 × 配分) / 100
|
||||
|
||||
致命问题惩罚:
|
||||
- 级别 1 问题: -20 分/个
|
||||
- 级别 2 问题: -10 分/个
|
||||
- 级别 3 问题: -5 分/个
|
||||
|
||||
奖励要素:
|
||||
- 自动化支持: +5 分
|
||||
- 学习功能实施: +5 分
|
||||
- 经验证的改进案例: +5 分
|
||||
|
||||
最终分数 = 基础分数 + 奖励 - 惩罚
|
||||
```
|
||||
|
||||
### 质量级别判定
|
||||
|
||||
```text
|
||||
95-100 分: 世界最高水平 (可作为行业标准推荐)
|
||||
90-94 分: 优秀 (可用于生产环境)
|
||||
80-89 分: 良好 (轻微改进后可运行)
|
||||
70-79 分: 普通 (需要改进)
|
||||
60-69 分: 需改进 (需要大幅修正)
|
||||
50-59 分: 需大幅修正 (需要根本性重新审视)
|
||||
49 分以下: 禁止使用 (需要完全重新设计)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 实践改进流程
|
||||
|
||||
### 阶段 1: 诊断·分析 (1-2 天)
|
||||
|
||||
1. **整体结构把握**: 可视化部分构成、信息流、依赖关系
|
||||
2. **歧义检测**: 全面提取有解释空间的表达
|
||||
3. **信息分散分析**: 映射相关信息分散模式
|
||||
4. **强制力评估**: 评估推荐/必须分类和实效性
|
||||
5. **可追踪性确认**: 评估执行结果记录、验证功能
|
||||
|
||||
### 阶段 2: 优先级排序·计划 (半天)
|
||||
|
||||
1. **致命度分类**: 级别 1-3 问题分类和影响度评估
|
||||
2. **改进顺序决定**: 考虑相互依赖的最优顺序
|
||||
3. **资源分配**: 优化改进效果与成本的平衡
|
||||
4. **风险评估**: 预测改进时的副作用、兼容性问题
|
||||
|
||||
### 阶段 3: 分阶段实施 (2-5 天)
|
||||
|
||||
1. **级别 1 问题解决**: 完全消除致命歧义
|
||||
2. **信息整合实施**: 战略性聚合分散信息
|
||||
3. **强制力强化**: 从推荐逐步升级到必须
|
||||
4. **追踪系统实施**: 自动记录、验证执行结果
|
||||
5. **模板强化**: 明确必要元素并强制遵守
|
||||
|
||||
### 阶段 4: 验证·调整 (1-2 天)
|
||||
|
||||
1. **功能测试**: 确认所有更改点的操作
|
||||
2. **集成测试**: 确认系统整体一致性
|
||||
3. **性能测试**: 确认执行效率、响应
|
||||
4. **可用性测试**: 在实际使用场景中验证
|
||||
|
||||
### 阶段 5: 运行·监控 (持续)
|
||||
|
||||
1. **效果测量**: 改进前后的定量比较
|
||||
2. **持续监控**: 早期检测质量下降
|
||||
3. **反馈收集**: 提取实际运行中的问题
|
||||
4. **持续优化**: 持续改进循环
|
||||
|
||||
---
|
||||
|
||||
## 📊 实际改进案例 (详细版)
|
||||
|
||||
### 案例研究: 大规模提示词的质量改进
|
||||
|
||||
#### 改进前状况
|
||||
|
||||
```bash
|
||||
质量分数: 70 分/100 分
|
||||
- 模糊表达: 发现 15 处
|
||||
- 信息分散: 重要信息散布在 6 处
|
||||
- 强制力不足: 推荐级表达占 80%
|
||||
- 追踪功能: 无执行结果记录
|
||||
- 错误处理: 失败时处理方法不明确
|
||||
```
|
||||
|
||||
#### 实施的改进内容
|
||||
|
||||
```bash
|
||||
# 1. 消除歧义 (2 天)
|
||||
- "原则上"→"例外仅限第 3.3 节的 3 个条件"
|
||||
- "推荐"→"必须"(重要度级别 2 以上)
|
||||
- "酌情"→明示具体判断标准
|
||||
|
||||
# 2. 信息整合 (1 天)
|
||||
- 分散的必需 6 部分信息→整合到执行清单
|
||||
- 相关禁止事项→聚合到一个部分
|
||||
- 解决循环引用→线性信息流
|
||||
|
||||
# 3. 追踪系统实施 (1 天)
|
||||
- 执行结果自动日志记录
|
||||
- 防止虚假报告的验证功能
|
||||
- 实时统计显示
|
||||
|
||||
# 4. 错误处理强化 (半天)
|
||||
- 预期错误模式的完整目录化
|
||||
- 分级处理流程的明文化
|
||||
- 自动恢复功能的实施
|
||||
```
|
||||
|
||||
#### 改进后结果
|
||||
|
||||
```bash
|
||||
质量分数: 90 分/100 分 (提升 20 分)
|
||||
- 模糊表达: 0 处 (完全消除)
|
||||
- 信息整合: 重要信息聚合到 3 处
|
||||
- 强制力: 必须级表达 95%
|
||||
- 追踪功能: 完全自动化
|
||||
- 错误处理: 90% 问题自动解决
|
||||
|
||||
实际改进效果:
|
||||
- 判断错误: 减少 85%
|
||||
- 执行时间: 缩短 40%
|
||||
- 错误发生率: 减少 70%
|
||||
- 用户满意度: 提升 95%
|
||||
```
|
||||
|
||||
### 经验教训·最佳实践
|
||||
|
||||
#### 成功因素
|
||||
|
||||
1. **分阶段方法**: 不一次性全部更改，以可验证单位实施
|
||||
2. **数据驱动**: 基于实测数据而非主观判断的改进
|
||||
3. **持续监控**: 定期确认改进效果的持续性
|
||||
4. **重视反馈**: 积极收集实际用户的意见
|
||||
|
||||
#### 避免失败策略
|
||||
|
||||
1. **过度完美主义**: 达到 90 分后先开始运行，通过持续改进追求 100 分
|
||||
2. **一次性更改的危险**: 大规模更改必须分阶段实施
|
||||
3. **向后兼容性**: 最小化对现有工作流的影响
|
||||
4. **文档不足**: 详细记录、共享所有更改
|
||||
|
||||
---
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 结合提示词文件的质量检查
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"评估这个提示词的质量，提出改进点"
|
||||
|
||||
# 比较多个提示词文件
|
||||
cat prompt-v1.md && echo "---" && cat prompt-v2.md
|
||||
/check-prompt
|
||||
"比较两个版本，分析改进的点和剩余的问题"
|
||||
|
||||
# 结合实际错误日志的分析
|
||||
cat execution-errors.log
|
||||
/check-prompt --deep
|
||||
"识别可能导致这个错误的提示词问题"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **前提条件**: 建议提示词文件以 Markdown 格式编写
|
||||
- **限制事项**: 大规模提示词 (超过 1 万行) 建议分割后分析
|
||||
- **建议事项**: 定期进行提示词质量检查，持续改进
|
||||
|
||||
---
|
||||
|
||||
_这个检查清单是在实际提示词改进项目中验证的完整版知识，并将持续进化。_
|
||||
354
commands/commit-message.md
Normal file
354
commands/commit-message.md
Normal file
@@ -0,0 +1,354 @@
|
||||
## 提交消息
|
||||
|
||||
从暂存的更改 (git diff --staged) 生成合适的提交消息。仅生成消息并复制到剪贴板，不执行 git 命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/commit-message [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--format <格式>` : 指定消息格式 (conventional, gitmoji, angular)
|
||||
- `--lang <语言>` : 强制指定消息语言 (en, zh-cn)
|
||||
- `--breaking` : 检测并记录 Breaking Change
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 从暂存的更改生成消息 (自动判定语言)
|
||||
# 主要候选会自动复制到剪贴板
|
||||
/commit-message
|
||||
|
||||
# 强制指定语言
|
||||
/commit-message --lang zh-cn
|
||||
/commit-message --lang en
|
||||
|
||||
# 检测 Breaking Change
|
||||
/commit-message --breaking
|
||||
```
|
||||
|
||||
### 前提条件
|
||||
|
||||
**重要**: 此命令仅分析暂存的更改。需要先使用 `git add` 暂存更改。
|
||||
|
||||
```bash
|
||||
# 如果没有暂存更改，会显示警告
|
||||
$ /commit-message
|
||||
没有暂存的更改。请先执行 git add。
|
||||
```
|
||||
|
||||
### 自动剪贴板功能
|
||||
|
||||
生成的主要候选会以 `git commit -m "消息"` 的完整格式自动复制到剪贴板。可以直接在终端粘贴执行。
|
||||
|
||||
**实现注意事项**:
|
||||
|
||||
- 将提交命令传递给 `pbcopy` 时，应与消息输出分开执行
|
||||
- 使用 `printf` 而不是 `echo` 以避免末尾换行
|
||||
|
||||
### 项目规范自动检测
|
||||
|
||||
**重要**: 如果存在项目特有的规范，将优先使用。
|
||||
|
||||
#### 1. CommitLint 配置检查
|
||||
|
||||
从以下文件自动检测配置：
|
||||
|
||||
- `commitlint.config.js`
|
||||
- `commitlint.config.mjs`
|
||||
- `commitlint.config.cjs`
|
||||
- `commitlint.config.ts`
|
||||
- `.commitlintrc.js`
|
||||
- `.commitlintrc.json`
|
||||
- `.commitlintrc.yml`
|
||||
- `.commitlintrc.yaml`
|
||||
- `package.json` 的 `commitlint` 部分
|
||||
|
||||
```bash
|
||||
# 搜索配置文件
|
||||
find . -name "commitlint.config.*" -o -name ".commitlintrc.*" | head -1
|
||||
```
|
||||
|
||||
#### 2. 自定义类型检测
|
||||
|
||||
项目特有类型示例：
|
||||
|
||||
```javascript
|
||||
// commitlint.config.mjs
|
||||
export default {
|
||||
extends: ["@commitlint/config-conventional"],
|
||||
rules: {
|
||||
"type-enum": [
|
||||
2,
|
||||
"always",
|
||||
[
|
||||
"feat",
|
||||
"fix",
|
||||
"docs",
|
||||
"style",
|
||||
"refactor",
|
||||
"test",
|
||||
"chore",
|
||||
"wip", // 进行中
|
||||
"hotfix", // 紧急修复
|
||||
"release", // 发布
|
||||
"deps", // 依赖更新
|
||||
"config", // 配置更改
|
||||
],
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. 语言设置检测
|
||||
|
||||
```javascript
|
||||
// 项目使用中文消息时
|
||||
export default {
|
||||
rules: {
|
||||
"subject-case": [0], // 为支持中文而禁用
|
||||
"subject-max-length": [2, "always", 72], // 为中文调整字符数限制
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 4. 现有提交历史分析
|
||||
|
||||
```bash
|
||||
# 从最近的提交学习使用模式
|
||||
git log --oneline -50 --pretty=format:"%s"
|
||||
|
||||
# 使用类型统计
|
||||
git log --oneline -100 --pretty=format:"%s" | \
|
||||
grep -oE '^[a-z]+(\([^)]+\))?' | \
|
||||
sort | uniq -c | sort -nr
|
||||
```
|
||||
|
||||
### 语言自动判定
|
||||
|
||||
根据以下条件自动切换中文/英文：
|
||||
|
||||
1. **CommitLint 配置**中的语言设置
|
||||
2. **git log 分析**的自动判定
|
||||
3. **项目文件**的语言设置
|
||||
4. **更改文件**中的注释和字符串分析
|
||||
|
||||
默认为英文。判定为中文项目时生成中文消息。
|
||||
|
||||
### 消息格式
|
||||
|
||||
#### Conventional Commits (默认)
|
||||
|
||||
```text
|
||||
<type>: <description>
|
||||
```
|
||||
|
||||
**重要**: 必须生成单行提交消息。不生成多行消息。
|
||||
|
||||
**注意**: 如果项目有特有规范，将优先使用。
|
||||
|
||||
### 标准类型
|
||||
|
||||
**必须类型**:
|
||||
|
||||
- `feat`: 新功能 (用户可见的功能添加)
|
||||
- `fix`: 缺陷修复
|
||||
|
||||
**可选类型**:
|
||||
|
||||
- `build`: 构建系统或外部依赖的更改
|
||||
- `chore`: 其他更改 (不影响发布)
|
||||
- `ci`: CI 配置文件或脚本的更改
|
||||
- `docs`: 仅文档更改
|
||||
- `style`: 不影响代码含义的更改 (空格、格式、分号等)
|
||||
- `refactor`: 既不修复缺陷也不添加功能的代码更改
|
||||
- `perf`: 性能改进
|
||||
- `test`: 添加或修正测试
|
||||
|
||||
### 输出示例 (英文项目)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 提交消息建议
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候选:
|
||||
feat: implement JWT-based authentication system
|
||||
|
||||
📋 备选方案:
|
||||
1. feat: add user authentication with JWT tokens
|
||||
2. fix: resolve token validation error in auth middleware
|
||||
3. refactor: extract auth logic into separate module
|
||||
|
||||
✅ `git commit -m "feat: implement JWT-based authentication system"` 已复制到剪贴板
|
||||
```
|
||||
|
||||
**实现示例 (修正版)**:
|
||||
|
||||
```bash
|
||||
# 先将提交命令复制到剪贴板 (无换行)
|
||||
printf 'git commit -m "%s"' "$COMMIT_MESSAGE" | pbcopy
|
||||
|
||||
# 然后显示消息
|
||||
cat << EOF
|
||||
📝 提交消息建议
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候选:
|
||||
$COMMIT_MESSAGE
|
||||
|
||||
📋 备选方案:
|
||||
1. ...
|
||||
2. ...
|
||||
3. ...
|
||||
|
||||
✅ `git commit -m "$COMMIT_MESSAGE"` 已复制到剪贴板
|
||||
EOF
|
||||
```
|
||||
|
||||
### 输出示例 (中文项目)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 提交消息建议
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候选:
|
||||
feat: 实现 JWT 认证系统
|
||||
|
||||
📋 备选方案:
|
||||
1. feat: 添加基于 JWT 令牌的用户认证
|
||||
2. fix: 解决认证中间件的令牌验证错误
|
||||
3. docs: 将认证逻辑分离到单独模块
|
||||
|
||||
✅ `git commit -m "feat: 实现 JWT 认证系统"` 已复制到剪贴板
|
||||
```
|
||||
|
||||
### 工作概要
|
||||
|
||||
1. **分析**: 分析 `git diff --staged` 的内容
|
||||
2. **生成**: 生成合适的提交消息
|
||||
3. **复制**: 自动将主要候选复制到剪贴板
|
||||
|
||||
**注意**: 此命令不执行 git add 或 git commit。仅生成提交消息并复制到剪贴板。
|
||||
|
||||
### 智能功能
|
||||
|
||||
#### 1. 更改内容自动分类 (仅暂存文件)
|
||||
|
||||
- 新文件添加 → `feat`
|
||||
- 错误修复模式 → `fix`
|
||||
- 仅测试文件 → `test`
|
||||
- 配置文件更改 → `chore`
|
||||
- README/docs 更新 → `docs`
|
||||
|
||||
#### 2. 项目规范自动检测
|
||||
|
||||
- `.gitmessage` 文件
|
||||
- `CONTRIBUTING.md` 中的规范
|
||||
- 过去提交历史模式
|
||||
|
||||
#### 3. 语言判定详情 (仅暂存更改)
|
||||
|
||||
```bash
|
||||
# 判定基准 (优先级)
|
||||
1. 从 git diff --staged 的内容判定语言
|
||||
2. 暂存文件的注释分析
|
||||
3. git log --oneline -20 的语言分析
|
||||
4. 项目主要语言设置
|
||||
```
|
||||
|
||||
#### 4. 暂存分析详情
|
||||
|
||||
分析使用的信息 (仅读取):
|
||||
|
||||
- `git diff --staged --name-only` - 更改文件列表
|
||||
- `git diff --staged` - 实际更改内容
|
||||
- `git status --porcelain` - 文件状态
|
||||
|
||||
### Breaking Change 检测时
|
||||
|
||||
当有 API 破坏性更改时：
|
||||
|
||||
**英文**:
|
||||
|
||||
```bash
|
||||
feat!: change user API response format
|
||||
|
||||
BREAKING CHANGE: user response now includes additional metadata
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
feat(api)!: change authentication flow
|
||||
```
|
||||
|
||||
**中文**:
|
||||
|
||||
```bash
|
||||
feat!: 更改用户 API 响应格式
|
||||
|
||||
BREAKING CHANGE: 响应现在包含额外的元数据
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
feat(api)!: 更改认证流程
|
||||
```
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **适应项目**: 遵循现有的提交语言
|
||||
2. **简洁性**: 50 字符内要清楚
|
||||
3. **一致性**: 不要混合使用 (英文就统一英文)
|
||||
4. **OSS**: 开源软件推荐英文
|
||||
5. **坚持单行**: 必须单行提交消息 (需要详细说明时在 PR 中补充)
|
||||
|
||||
### 常见模式
|
||||
|
||||
**英文**:
|
||||
|
||||
```text
|
||||
feat: add user registration endpoint
|
||||
fix: resolve memory leak in cache manager
|
||||
docs: update API documentation
|
||||
```
|
||||
|
||||
**中文**:
|
||||
|
||||
```text
|
||||
feat: 添加用户注册端点
|
||||
fix: 解决缓存管理器内存泄漏
|
||||
docs: 更新 API 文档
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 与暂存更改结合使用
|
||||
git add -p # 交互式暂存
|
||||
/commit-message
|
||||
"生成最优的提交消息"
|
||||
|
||||
# 仅暂存特定文件后分析
|
||||
git add src/auth/*.js
|
||||
/commit-message --lang zh-cn
|
||||
"为认证相关更改生成合适的消息"
|
||||
|
||||
# Breaking Change 检测和应对
|
||||
git add -A
|
||||
/commit-message --breaking
|
||||
"如有破坏性更改请适当标记"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **前提条件**: 更改需要先通过 `git add` 暂存
|
||||
- **限制事项**: 未暂存的更改不在分析范围内
|
||||
- **推荐事项**: 请事先确认项目现有的提交规范
|
||||
50
commands/context7.md
Normal file
50
commands/context7.md
Normal file
@@ -0,0 +1,50 @@
|
||||
## Context7
|
||||
|
||||
使用 MCP 的 Context7 搜索技术文档。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 以请求 Claude 的形式
|
||||
"用 context7 搜索 [搜索关键词]"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# React hooks 调研
|
||||
"用 context7 搜索 React hooks"
|
||||
|
||||
# 错误解决方法搜索
|
||||
"用 context7 查找 TypeScript 的类型错误"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 技术调研请求
|
||||
"用 context7 查找 Rust 的所有权系统，并以初学者友好的方式解释"
|
||||
|
||||
# 错误解决请求
|
||||
"用 context7 搜索 Python 的 ImportError 常见原因和解决方法"
|
||||
|
||||
# 最佳实践确认
|
||||
"用 context7 查找 React 性能优化的最佳实践"
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 从多个角度调研
|
||||
"用 context7 从以下角度调研 GraphQL：
|
||||
1. 基本概念和与 REST API 的区别
|
||||
2. 实现方法和最佳实践
|
||||
3. 常见问题和解决方法"
|
||||
|
||||
# 特定版本或环境的调研
|
||||
"用 context7 搜索 Next.js 14 的新功能，重点说明 App Router 的使用方法"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
如果 Context7 找不到信息，Claude 会自动建议其他方法，如 Web 搜索等。
|
||||
186
commands/design-patterns.md
Normal file
186
commands/design-patterns.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## 设计模式
|
||||
|
||||
提出可应用于代码库的设计模式，评估 SOLID 原则的遵守情况。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/design-patterns [分析对象] [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--suggest` : 提出可应用的模式 (默认)
|
||||
- `--analyze` : 分析现有模式的使用情况
|
||||
- `--refactor` : 生成重构方案
|
||||
- `--solid` : 检查 SOLID 原则的遵守情况
|
||||
- `--anti-patterns` : 检测反模式
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 整个项目的模式分析
|
||||
/design-patterns
|
||||
|
||||
# 对特定文件提出模式建议
|
||||
/design-patterns src/services/user.js --suggest
|
||||
|
||||
# SOLID 原则检查
|
||||
/design-patterns --solid
|
||||
|
||||
# 反模式检测
|
||||
/design-patterns --anti-patterns
|
||||
```
|
||||
|
||||
### 分析类别
|
||||
|
||||
#### 1. 创建型模式
|
||||
|
||||
- **Factory Pattern**: 对象创建的抽象化
|
||||
- **Builder Pattern**: 复杂对象的分步构建
|
||||
- **Singleton Pattern**: 保证实例的唯一性
|
||||
- **Prototype Pattern**: 对象的克隆生成
|
||||
|
||||
#### 2. 结构型模式
|
||||
|
||||
- **Adapter Pattern**: 接口转换
|
||||
- **Decorator Pattern**: 动态添加功能
|
||||
- **Facade Pattern**: 简化复杂子系统
|
||||
- **Proxy Pattern**: 对象访问控制
|
||||
|
||||
#### 3. 行为型模式
|
||||
|
||||
- **Observer Pattern**: 事件通知的实现
|
||||
- **Strategy Pattern**: 算法切换
|
||||
- **Command Pattern**: 操作封装
|
||||
- **Iterator Pattern**: 集合遍历
|
||||
|
||||
### SOLID 原则检查项
|
||||
|
||||
```text
|
||||
S - Single Responsibility Principle (单一职责原则)
|
||||
O - Open/Closed Principle (开闭原则)
|
||||
L - Liskov Substitution Principle (里氏替换原则)
|
||||
I - Interface Segregation Principle (接口隔离原则)
|
||||
D - Dependency Inversion Principle (依赖倒置原则)
|
||||
```
|
||||
|
||||
### 输出示例
|
||||
|
||||
```text
|
||||
设计模式分析报告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
当前使用的模式
|
||||
├─ Observer Pattern: EventEmitter (12 处)
|
||||
├─ Factory Pattern: UserFactory (3 处)
|
||||
├─ Singleton Pattern: DatabaseConnection (1 处)
|
||||
└─ Strategy Pattern: PaymentProcessor (5 处)
|
||||
|
||||
推荐模式
|
||||
├─ [HIGH] Repository Pattern
|
||||
│ └─ 对象: src/models/*.js
|
||||
│ └─ 原因: 分离数据访问逻辑
|
||||
│ └─ 示例:
|
||||
│ class UserRepository {
|
||||
│ async findById(id) { ... }
|
||||
│ async save(user) { ... }
|
||||
│ }
|
||||
│
|
||||
├─ [MED] Command Pattern
|
||||
│ └─ 对象: src/api/handlers/*.js
|
||||
│ └─ 原因: 统一请求处理
|
||||
│
|
||||
└─ [LOW] Decorator Pattern
|
||||
└─ 对象: src/middleware/*.js
|
||||
└─ 原因: 改进功能组合
|
||||
|
||||
SOLID 原则违反
|
||||
├─ [S] UserService: 同时负责认证和权限管理
|
||||
├─ [O] PaymentGateway: 添加新支付方式需要修改
|
||||
├─ [D] EmailService: 直接依赖具体类
|
||||
└─ [I] IDataStore: 包含未使用的方法
|
||||
|
||||
重构建议
|
||||
1. 将 UserService 拆分为认证和权限管理
|
||||
2. 引入 PaymentStrategy 接口
|
||||
3. 定义 EmailService 接口
|
||||
4. 按用途拆分 IDataStore
|
||||
```
|
||||
|
||||
### 高级用法
|
||||
|
||||
```bash
|
||||
# 模式应用的影响分析
|
||||
/design-patterns --impact-analysis Repository
|
||||
|
||||
# 生成特定模式的实现示例
|
||||
/design-patterns --generate Factory --for src/models/Product.js
|
||||
|
||||
# 模式组合建议
|
||||
/design-patterns --combine --context "带缓存的 API"
|
||||
|
||||
# 架构模式评估
|
||||
/design-patterns --architecture MVC
|
||||
```
|
||||
|
||||
### 模式应用示例
|
||||
|
||||
#### Before (有问题的代码)
|
||||
|
||||
```javascript
|
||||
class OrderService {
|
||||
processOrder(order, paymentType) {
|
||||
if (paymentType === "credit") {
|
||||
// 信用卡处理
|
||||
} else if (paymentType === "paypal") {
|
||||
// PayPal 处理
|
||||
}
|
||||
// 其他支付方式...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### After (应用 Strategy Pattern)
|
||||
|
||||
```javascript
|
||||
// 策略接口
|
||||
class PaymentStrategy {
|
||||
process(amount) {
|
||||
throw new Error("必须实现 process 方法");
|
||||
}
|
||||
}
|
||||
|
||||
// 具体策略
|
||||
class CreditCardPayment extends PaymentStrategy {
|
||||
process(amount) {
|
||||
/* 实现 */
|
||||
}
|
||||
}
|
||||
|
||||
// 上下文
|
||||
class OrderService {
|
||||
constructor(paymentStrategy) {
|
||||
this.paymentStrategy = paymentStrategy;
|
||||
}
|
||||
|
||||
processOrder(order) {
|
||||
this.paymentStrategy.process(order.total);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 反模式检测
|
||||
|
||||
- **God Object**: 承担过多职责的类
|
||||
- **Spaghetti Code**: 控制流复杂纠缠的代码
|
||||
- **Copy-Paste Programming**: 过度使用重复代码
|
||||
- **Magic Numbers**: 硬编码的常量
|
||||
- **Callback Hell**: 深度嵌套的回调
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **渐进式应用**: 不要一次应用太多模式
|
||||
2. **必要性验证**: 模式是解决问题的手段而非目的
|
||||
3. **团队共识**: 应用模式前团队讨论
|
||||
4. **文档化**: 记录应用模式的意图
|
||||
75
commands/explain-code.md
Normal file
75
commands/explain-code.md
Normal file
@@ -0,0 +1,75 @@
|
||||
## 代码解释
|
||||
|
||||
详细解释代码的运行机制。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 显示文件内容并请求 Claude
|
||||
cat <file>
|
||||
"解释这段代码的运行机制"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 理解 Rust 的所有权
|
||||
cat main.rs
|
||||
"从 Rust 的所有权和生命周期角度解释"
|
||||
|
||||
# 算法解释
|
||||
grep -A 50 "quicksort" sort.rs
|
||||
"解释这个排序算法的机制和时间复杂度"
|
||||
|
||||
# 设计模式说明
|
||||
cat factory.rs
|
||||
"说明使用的设计模式及其优点"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 初学者友好的解释
|
||||
cat complex_function.py
|
||||
"用初学者也能理解的方式逐行解释这段代码"
|
||||
|
||||
# 性能分析
|
||||
cat algorithm.rs
|
||||
"指出这段代码的性能问题并提出改进方案"
|
||||
|
||||
# 带图解的说明
|
||||
cat state_machine.js
|
||||
"用 ASCII 艺术图解说明这段代码的处理流程"
|
||||
|
||||
# 安全审查
|
||||
cat auth_handler.go
|
||||
"指出这段代码的安全隐患"
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 复杂逻辑的解释
|
||||
cat recursive_parser.rs
|
||||
"从以下角度解释这个递归解析器的运行机制：
|
||||
1. 整体处理流程
|
||||
2. 各函数的角色和职责
|
||||
3. 边界情况处理
|
||||
4. 可改进的地方"
|
||||
|
||||
# 异步处理的解释
|
||||
cat async_handler.ts
|
||||
"解释这个异步处理的以下方面：
|
||||
1. Promise 链的流程
|
||||
2. 错误处理机制
|
||||
3. 是否有并发处理
|
||||
4. 死锁的可能性"
|
||||
|
||||
# 架构说明
|
||||
ls -la src/ && cat src/main.rs src/lib.rs
|
||||
"解释这个项目的架构和模块结构"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
代码解释不仅说明运行机制，还会解释为什么这样实现、有什么优点、潜在问题是什么等深层洞察。
|
||||
319
commands/fix-error.md
Normal file
319
commands/fix-error.md
Normal file
@@ -0,0 +1,319 @@
|
||||
## 错误修复
|
||||
|
||||
从错误信息中识别根本原因，预测解决时间，提出经过验证的解决方案。学习类似错误的模式，立即提供合适的处理方法。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/fix-error [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- 无 : 标准错误分析
|
||||
- `--deep` : 深度分析模式 (包括依赖关系·环境因素)
|
||||
- `--preventive` : 重视预防措施的分析
|
||||
- `--quick` : 仅提供立即可用的修复方案
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 标准错误分析
|
||||
npm run build 2>&1
|
||||
/fix-error
|
||||
"分析构建错误并提出修复方法"
|
||||
|
||||
# 深度分析模式
|
||||
python app.py 2>&1
|
||||
/fix-error --deep
|
||||
"包括环境因素在内分析错误的根本原因"
|
||||
|
||||
# 即时修复重视
|
||||
cargo test 2>&1
|
||||
/fix-error --quick
|
||||
"提供可立即应用的修复方法"
|
||||
|
||||
# 预防措施重视
|
||||
./app 2>&1 | tail -50
|
||||
/fix-error --preventive
|
||||
"提出错误修复和未来的预防措施"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 错误日志分析
|
||||
cat error.log
|
||||
/fix-error
|
||||
"识别错误的根本原因，提出修复方法"
|
||||
|
||||
# 测试失败的解决
|
||||
npm test 2>&1
|
||||
/fix-error --quick
|
||||
"分析失败的测试，提出可立即应用的修复方案"
|
||||
|
||||
# 堆栈跟踪的解析
|
||||
python script.py 2>&1
|
||||
/fix-error --deep
|
||||
"从这个堆栈跟踪中定位问题，包括环境因素一起分析"
|
||||
|
||||
# 批量解决多个错误
|
||||
grep -E "ERROR|WARN" app.log | tail -20
|
||||
/fix-error
|
||||
"按优先级分类这些错误和警告，分别提出解决方法"
|
||||
```
|
||||
|
||||
### 错误解决时间预测
|
||||
|
||||
```text
|
||||
🚀 即时修复 (5 分钟内)
|
||||
├─ 拼写错误、import 遗忘
|
||||
├─ 环境变量未设置
|
||||
├─ 未定义变量引用
|
||||
└─ 预测时间: 2-5 分钟
|
||||
|
||||
⚡ 快速修复 (30 分钟内)
|
||||
├─ 依赖关系不一致
|
||||
├─ 配置文件错误
|
||||
├─ 类型不匹配
|
||||
└─ 预测时间: 10-30 分钟
|
||||
|
||||
🔧 需要调查 (2 小时内)
|
||||
├─ 复杂逻辑错误
|
||||
├─ 异步处理竞争
|
||||
├─ API 集成问题
|
||||
└─ 预测时间: 30 分钟-2 小时
|
||||
|
||||
🔌 深层分析 (半天以上)
|
||||
├─ 架构原因
|
||||
├─ 多系统集成
|
||||
├─ 性能降级
|
||||
└─ 预测时间: 4 小时-数日
|
||||
```
|
||||
|
||||
### 类似错误模式数据库
|
||||
|
||||
```text
|
||||
高频错误及即时解决方案
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 "Cannot read property 'X' of undefined/null" (频出度: 极高)
|
||||
├─ 主要原因: 对象的 null 检查不足
|
||||
├─ 解决时间: 5-10 分钟
|
||||
└─ 处理方法: 可选链式调用 (?.) 或添加 null 检查
|
||||
|
||||
📊 "ECONNREFUSED" / "ENOTFOUND" (频出度: 高)
|
||||
├─ 主要原因: 服务未启动或 URL 配置错误
|
||||
├─ 解决时间: 5-15 分钟
|
||||
└─ 处理方法: 确认服务启动、检查环境变量
|
||||
|
||||
📊 "Module not found" / "Cannot resolve" (频出度: 高)
|
||||
├─ 主要原因: 包未安装、路径指定错误
|
||||
├─ 解决时间: 2-5 分钟
|
||||
└─ 处理方法: 执行 npm install、确认相对路径
|
||||
|
||||
📊 "Unexpected token" / "SyntaxError" (频出度: 中)
|
||||
├─ 主要原因: 括号、引号不匹配、使用保留字
|
||||
├─ 解决时间: 2-10 分钟
|
||||
└─ 处理方法: 确认语法高亮、执行 Linter
|
||||
|
||||
📊 "CORS policy" / "Access-Control-Allow-Origin" (频出度: 中)
|
||||
├─ 主要原因: 服务端 CORS 配置不足
|
||||
├─ 解决时间: 15-30 分钟
|
||||
└─ 处理方法: 服务端 CORS 配置、代理设置
|
||||
|
||||
📊 "Maximum call stack size exceeded" (频出度: 低)
|
||||
├─ 主要原因: 无限循环、递归、循环引用
|
||||
├─ 解决时间: 30 分钟-2 小时
|
||||
└─ 处理方法: 确认递归的终止条件、解决循环引用
|
||||
```
|
||||
|
||||
### 错误分析优先级矩阵
|
||||
|
||||
| 优先级 | 图标 | 影响范围 | 解决难度 | 处理期限 | 说明 |
|
||||
| ----------------- | ----------- | -------- | -------- | ------------- | -------------------------- |
|
||||
| **Critical** | 🔴 紧急处理 | 广 | 低 | 15 分钟内着手 | 系统全体停止、数据丢失风险 |
|
||||
| **High Priority** | 🟠 早期处理 | 广 | 高 | 1 小时内着手 | 主要功能停止、多数用户影响 |
|
||||
| **Medium** | 🟡 计划处理 | 狭 | 高 | 当日内处理 | 部分功能限制、有规避方案 |
|
||||
| **Low** | 🟢 经过观察 | 狭 | 低 | 下次修改时 | 轻微不具、UX 影响小 |
|
||||
|
||||
### 分析流程
|
||||
|
||||
#### 阶段 1: 错误信息收集
|
||||
|
||||
```bash
|
||||
🔴 必须执行:
|
||||
- 完整获取错误信息
|
||||
- 确认堆栈跟踪
|
||||
- 确定发生条件 (可重现性)
|
||||
|
||||
🟡 尽早执行:
|
||||
- 收集环境信息 (OS、版本、依赖)
|
||||
- 最近的更改历史 (git log、最近提交)
|
||||
- 确认相关日志
|
||||
|
||||
🟢 附加执行:
|
||||
- 系统资源状况
|
||||
- 网络状态
|
||||
- 外部服务状态
|
||||
```
|
||||
|
||||
#### 阶段 2: 根本原因分析
|
||||
|
||||
1. **整理表面症状**
|
||||
- 错误信息的准确内容
|
||||
- 发生时机和模式
|
||||
- 确定影响范围
|
||||
|
||||
2. **识别深层原因**
|
||||
- 应用 5 Whys 分析
|
||||
- 追踪依赖关系
|
||||
- 确认环境差异
|
||||
|
||||
3. **验证假设**
|
||||
- 创建最小重现代码
|
||||
- 执行隔离测试
|
||||
- 缩小原因范围
|
||||
|
||||
#### 阶段 3: 实施解决方案
|
||||
|
||||
```bash
|
||||
🔴 立即处理 (热修复):
|
||||
- 抑制症状的最小修复
|
||||
- 应用临时解决方案
|
||||
- 准备紧急部署
|
||||
|
||||
🟡 根本解决:
|
||||
- 针对原因的本质修复
|
||||
- 添加测试用例
|
||||
- 更新文档
|
||||
|
||||
🟢 实施预防措施:
|
||||
- 加强错误处理
|
||||
- 设置监控·告警
|
||||
- 改进 CI/CD 管道
|
||||
```
|
||||
|
||||
### 输出示例
|
||||
|
||||
```text
|
||||
🚨 错误分析报告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📍 错误概要
|
||||
├─ 类型: [编译/运行时/逻辑/环境]
|
||||
├─ 紧急度: 🔴 高 / 🟡 中 / 🟢 低
|
||||
├─ 影响范围: [功能名/组件]
|
||||
├─ 重现性: [100% / 间歇性 / 特定条件]
|
||||
└─ 预测解决时间: [2-5 分钟 / 30 分钟-2 小时 / 4 小时+]
|
||||
|
||||
🔍 根本原因
|
||||
├─ 直接原因: [具体原因]
|
||||
├─ 背景因素: [环境/设置/依赖关系]
|
||||
├─ 触发器: [发生条件]
|
||||
└─ 类似模式: [已知错误类型 / 首次发生]
|
||||
|
||||
💡 解决方案
|
||||
🔴 即时处理 (预计: X 分钟):
|
||||
1. [具体修复命令/代码]
|
||||
2. [临时解决方案]
|
||||
|
||||
🟡 根本解决 (预计: Y 小时):
|
||||
1. [本质修复方法]
|
||||
2. [必要的重构]
|
||||
|
||||
🟢 预防措施:
|
||||
1. [错误处理改进]
|
||||
2. [测试添加]
|
||||
3. [监控设置]
|
||||
|
||||
📋 风险评估
|
||||
├─ 修复失败风险: [低/中/高]
|
||||
├─ 副作用影响: [无/有限/广泛]
|
||||
└─ 回滚计划: [简单/复杂/不可能]
|
||||
|
||||
📝 验证步骤
|
||||
1. [修复后的确认方法]
|
||||
2. [测试执行命令]
|
||||
3. [功能确认项目]
|
||||
4. [性能影响检查]
|
||||
```
|
||||
|
||||
### 错误类型别分析方法
|
||||
|
||||
#### 编译/构建错误
|
||||
|
||||
```bash
|
||||
# TypeScript 类型错误
|
||||
必须确认 (高):
|
||||
- tsconfig.json 设置
|
||||
- 类型定义文件 (.d.ts) 存在
|
||||
- import 语句的准确性
|
||||
|
||||
# Rust 生命周期错误
|
||||
必须确认 (高):
|
||||
- 所有权转移
|
||||
- 引用的有效期
|
||||
- 可变性冲突
|
||||
```
|
||||
|
||||
#### 运行时错误
|
||||
|
||||
```bash
|
||||
# Null/Undefined 引用
|
||||
必须确认 (高):
|
||||
- 可选链不足
|
||||
- 初始化时机
|
||||
- 异步处理的完成等待
|
||||
|
||||
# 内存相关错误
|
||||
必须确认 (高):
|
||||
- 获取堆转储
|
||||
- 分析 GC 日志
|
||||
- 检测循环引用
|
||||
```
|
||||
|
||||
#### 依赖关系错误
|
||||
|
||||
```bash
|
||||
# 版本冲突
|
||||
必须确认 (高):
|
||||
- lock 文件的一致性
|
||||
- peer dependencies 的要求
|
||||
- 传递依赖关系
|
||||
|
||||
# 模块解析错误
|
||||
必须确认 (高):
|
||||
- NODE_PATH 设置
|
||||
- 路径别名设置
|
||||
- 符号链接
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **绝对禁止**: 仅凭部分错误信息判断、未经验证就应用 Stack Overflow 的解决方案
|
||||
- **例外条件**: 临时解决方案仅在以下 3 个条件下允许
|
||||
1. 生产环境紧急响应 (24 小时内必须根本解决)
|
||||
2. 外部服务故障 (等待恢复期间的替代手段)
|
||||
3. 已知框架 bug(等待修复版本发布)
|
||||
- **建议事项**: 优先识别根本原因，避免表面修复
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **完整信息收集**: 确认错误信息从头到尾
|
||||
2. **确认重现性**: 优先创建最小重现代码
|
||||
3. **渐进式方法**: 从小修复开始验证
|
||||
4. **文档化**: 记录解决过程以便知识共享
|
||||
|
||||
#### 常见陷阱
|
||||
|
||||
- **处理症状**: 表面修复忽略根本原因
|
||||
- **过度泛化**: 将特定案例的解决方案广泛应用
|
||||
- **省略验证**: 不确认修复后的副作用
|
||||
- **知识孤岛**: 不记录解决方法
|
||||
|
||||
### 相关命令
|
||||
|
||||
- `/design-patterns` : 分析代码结构问题并提出模式建议
|
||||
- `/tech-debt` : 从技术债务角度分析错误的根本原因
|
||||
- `/analyzer` : 需要更深入的根本原因分析时使用
|
||||
314
commands/multi-role.md
Normal file
314
commands/multi-role.md
Normal file
@@ -0,0 +1,314 @@
|
||||
## 多角色分析
|
||||
|
||||
使用多个角色并行分析同一对象，生成综合报告的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/multi-role <角色 1>,<角色 2> [--agent|-a] [分析对象]
|
||||
/multi-role <角色 1>,<角色 2>,<角色 3> [--agent|-a] [分析对象]
|
||||
```
|
||||
|
||||
### 可用角色
|
||||
|
||||
#### 专业分析角色
|
||||
|
||||
- `security` : 安全审计专家
|
||||
- `performance` : 性能优化专家
|
||||
- `analyzer` : 根本原因分析专家
|
||||
- `frontend` : 前端·UI/UX 专家
|
||||
- `mobile` : 移动开发专家
|
||||
- `backend` : 后端与服务器端专家
|
||||
|
||||
#### 开发支持角色
|
||||
|
||||
- `reviewer` : 代码审查专家
|
||||
- `architect` : 系统架构师
|
||||
- `qa` : 测试工程师
|
||||
|
||||
**重要**:
|
||||
|
||||
- `--agent` 选项需要放在角色指定之后
|
||||
- 消息要写在 `--agent` 之后
|
||||
- 正确示例: `/multi-role qa,architect --agent 评估计划`
|
||||
- 错误示例: `/multi-role qa,architect 评估计划 --agent`
|
||||
|
||||
### 选项
|
||||
|
||||
- `--agent` 或 `-a` : 将各角色作为子代理并行执行 (推荐用于大规模分析)
|
||||
- 使用此选项时，如果角色的 description 中包含自动委托促进短语 (如 "use PROACTIVELY" 等)，将启用更积极的自动委托
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 安全和性能的双重分析 (常规)
|
||||
/multi-role security,performance
|
||||
"评估这个 API 端点"
|
||||
|
||||
# 大规模系统的并行分析 (子代理)
|
||||
/multi-role security,performance --agent
|
||||
"全面分析系统的安全性和性能"
|
||||
|
||||
# 前端·移动·性能的综合分析
|
||||
/multi-role frontend,mobile,performance
|
||||
"考虑这个界面的优化方案"
|
||||
|
||||
# 架构设计的多角度评估 (子代理)
|
||||
/multi-role architect,security,performance --agent
|
||||
"评估微服务化的设计"
|
||||
```
|
||||
|
||||
### 分析流程
|
||||
|
||||
### 阶段 1: 并行分析
|
||||
|
||||
各角色独立分析同一对象
|
||||
|
||||
- 从专业视角进行评估
|
||||
- 按角色特有标准判定
|
||||
- 生成独立的建议
|
||||
|
||||
### 阶段 2: 综合分析
|
||||
|
||||
结构化整合结果
|
||||
|
||||
- 整理各角色的评估结果
|
||||
- 识别重复·矛盾点
|
||||
- 明确互补关系
|
||||
|
||||
### 阶段 3: 综合报告
|
||||
|
||||
生成最终建议
|
||||
|
||||
- 带优先级的行动计划
|
||||
- 明示权衡取舍
|
||||
- 提供实施路线图
|
||||
|
||||
### 输出格式示例
|
||||
|
||||
### 2 角色分析的情况
|
||||
|
||||
```text
|
||||
多角色分析: Security + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
分析对象: API 端点 /api/users
|
||||
|
||||
Security 分析结果:
|
||||
认证: JWT 验证实施得当
|
||||
授权: 基于角色的访问控制不完整
|
||||
加密: API 密钥在日志中以明文输出
|
||||
|
||||
评估分数: 65/100
|
||||
重要度: High(因为访问敏感数据)
|
||||
|
||||
Performance 分析结果:
|
||||
响应时间: 平均 180ms(目标 200ms 以内)
|
||||
数据库查询: 检测到 N+1 问题
|
||||
缓存: Redis 缓存未实施
|
||||
|
||||
评估分数: 70/100
|
||||
重要度: Medium(目前在可接受范围内)
|
||||
|
||||
相互关联分析:
|
||||
协同效应机会:
|
||||
- 实施 Redis 缓存时同时考虑加密
|
||||
- 改进日志输出提升安全性和性能
|
||||
|
||||
权衡点:
|
||||
- 加强授权检查 ↔ 对响应时间的影响
|
||||
- 日志加密 ↔ 调试效率降低
|
||||
|
||||
综合优先级:
|
||||
Critical: 修复 API 密钥明文输出
|
||||
High: 解决 N+1 查询
|
||||
Medium: 实施 Redis 缓存 + 加密
|
||||
Low: 细化授权控制
|
||||
|
||||
实施路线图:
|
||||
第 1 周: 实施 API 密钥屏蔽
|
||||
第 2 周: 优化数据库查询
|
||||
第 3-4 周: 设计·实施缓存层
|
||||
第 2 月: 逐步加强授权控制
|
||||
```
|
||||
|
||||
### 3 角色分析的情况
|
||||
|
||||
```text
|
||||
多角色分析: Frontend + Mobile + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
分析对象: 用户资料界面
|
||||
|
||||
Frontend 分析结果:
|
||||
可用性: 直观的布局
|
||||
可访问性: WCAG 2.1 符合率 85%
|
||||
响应式: 平板显示有问题
|
||||
|
||||
Mobile 分析结果:
|
||||
触摸目标: 确保 44pt 以上
|
||||
单手操作: 重要按钮在上方
|
||||
离线支持: 未实施
|
||||
|
||||
Performance 分析结果:
|
||||
初始显示: LCP 2.1 秒 (良好)
|
||||
图像优化: 不支持 WebP
|
||||
延迟加载: 未实施
|
||||
|
||||
综合建议:
|
||||
1. 移动优化 (单手操作 + 离线支持)
|
||||
2. 图像优化 (WebP + 延迟加载)
|
||||
3. 改进平板 UI
|
||||
|
||||
优先级: Mobile > Performance > Frontend
|
||||
实施期间: 3-4 周
|
||||
```
|
||||
|
||||
### 有效的组合模式
|
||||
|
||||
### 安全重视
|
||||
|
||||
```bash
|
||||
/multi-role security,architect
|
||||
"认证系统的设计"
|
||||
|
||||
/multi-role security,frontend
|
||||
"登录界面的安全性"
|
||||
|
||||
/multi-role security,mobile
|
||||
"移动应用的数据保护"
|
||||
```
|
||||
|
||||
### 性能重视
|
||||
|
||||
```bash
|
||||
/multi-role performance,architect
|
||||
"可扩展性设计"
|
||||
|
||||
/multi-role performance,frontend
|
||||
"Web 页面高速化"
|
||||
|
||||
/multi-role performance,mobile
|
||||
"应用运行优化"
|
||||
```
|
||||
|
||||
### 用户体验重视
|
||||
|
||||
```bash
|
||||
/multi-role frontend,mobile
|
||||
"跨平台 UI"
|
||||
|
||||
/multi-role frontend,performance
|
||||
"UX 与性能的平衡"
|
||||
|
||||
/multi-role mobile,performance
|
||||
"移动 UX 优化"
|
||||
```
|
||||
|
||||
### 全面分析
|
||||
|
||||
```bash
|
||||
/multi-role architect,security,performance
|
||||
"系统整体评估"
|
||||
|
||||
/multi-role frontend,mobile,performance
|
||||
"用户体验综合评估"
|
||||
|
||||
/multi-role security,performance,mobile
|
||||
"移动应用综合诊断"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 结合文件分析
|
||||
cat src/components/UserProfile.tsx
|
||||
/multi-role frontend,mobile
|
||||
"从多个视角评估这个组件"
|
||||
|
||||
# 设计文档评估
|
||||
cat architecture-design.md
|
||||
/multi-role architect,security,performance
|
||||
"从多个专业领域评估这个设计"
|
||||
|
||||
# 错误分析
|
||||
cat performance-issues.log
|
||||
/multi-role performance,analyzer
|
||||
"多角度分析性能问题"
|
||||
```
|
||||
|
||||
### multi-role vs role-debate 的使用区分
|
||||
|
||||
### 使用 multi-role 的场合
|
||||
|
||||
- 需要各专业领域的独立评估
|
||||
- 想制定综合改进计划
|
||||
- 需要整理矛盾或重复
|
||||
- 要决定实施优先级
|
||||
|
||||
### 使用 role-debate 的场合
|
||||
|
||||
- 专业领域间存在权衡
|
||||
- 技术选型可能有分歧
|
||||
- 想通过讨论决定设计方针
|
||||
- 想听取不同视角的辩论
|
||||
|
||||
### 子代理并行执行 (--agent)
|
||||
|
||||
使用 `--agent` 选项时，各角色作为独立的子代理并行执行。
|
||||
|
||||
#### 自动委托的促进
|
||||
|
||||
当角色文件的 description 字段包含以下短语时，使用 `--agent` 会启用更积极的自动委托：
|
||||
|
||||
- "use PROACTIVELY"
|
||||
- "MUST BE USED"
|
||||
- 其他强调表达
|
||||
|
||||
#### 执行流程
|
||||
|
||||
```text
|
||||
常规执行:
|
||||
角色 1 → 角色 2 → 角色 3 → 综合
|
||||
(顺序执行，约 3-5 分钟)
|
||||
|
||||
--agent 执行:
|
||||
角色 1 ─┐
|
||||
角色 2 ─┼→ 综合
|
||||
角色 3 ─┘
|
||||
(并行执行，约 1-2 分钟)
|
||||
```
|
||||
|
||||
#### 有效使用示例
|
||||
|
||||
```bash
|
||||
# 大规模系统的综合评估
|
||||
/multi-role architect,security,performance,qa --agent
|
||||
"新系统的全面评估"
|
||||
|
||||
# 多视角的详细分析
|
||||
/multi-role frontend,mobile,performance --agent
|
||||
"所有界面的 UX 优化分析"
|
||||
```
|
||||
|
||||
#### 性能比较
|
||||
|
||||
| 角色数 | 常规执行 | --agent 执行 | 缩短率 |
|
||||
| ------ | -------- | ------------ | ------ |
|
||||
| 2 角色 | 2-3 分钟 | 1 分钟 | 50% |
|
||||
| 3 角色 | 3-5 分钟 | 1-2 分钟 | 60% |
|
||||
| 4 角色 | 5-8 分钟 | 2-3 分钟 | 65% |
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 同时执行 3 个以上角色时输出会变长
|
||||
- 复杂分析可能需要更长执行时间
|
||||
- 出现相互矛盾的建议时，也可考虑 role-debate
|
||||
- 最终判断请参考综合结果由用户决定
|
||||
- **使用 --agent 时**: 会使用更多资源，但对大规模分析更高效
|
||||
|
||||
### 角色配置详情
|
||||
|
||||
- 各角色的详细配置、专业知识与讨论特性都定义在 `.claude/agents/roles/` 目录中
|
||||
- 包含 Evidence-First 方法与认知偏差对策
|
||||
- 角色专属触发短语会自动启用特化模式
|
||||
134
commands/plan.md
Normal file
134
commands/plan.md
Normal file
@@ -0,0 +1,134 @@
|
||||
## 计划模式
|
||||
|
||||
启动实施前的计划制定模式，制定详细的实施策略。通过在代码实施前制定结构化计划，支持高效开发。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 请求 Claude 进入 Plan Mode
|
||||
"制定 [实施内容] 的实施计划"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 新功能的实施计划
|
||||
"制定用户认证功能的实施计划"
|
||||
|
||||
# 系统设计计划
|
||||
"制定微服务拆分的实施计划"
|
||||
|
||||
# 重构计划
|
||||
"制定遗留代码的重构计划"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 复杂功能实施
|
||||
"制定聊天功能的实施计划。包括 WebSocket、实时通知、历史管理"
|
||||
|
||||
# 数据库设计
|
||||
"制定电商网站的数据库设计计划。包括商品、订单、用户管理"
|
||||
|
||||
# API 设计
|
||||
"制定 GraphQL API 的实施计划。包括认证、缓存、速率限制"
|
||||
|
||||
# 基础设施设计
|
||||
"制定 Docker 化的实施计划。包括开发环境、生产环境、CI/CD"
|
||||
```
|
||||
|
||||
### Plan Mode 的特点
|
||||
|
||||
**自动启动**
|
||||
|
||||
- 检测到实施任务时自动启动 Plan Mode
|
||||
- 可通过"制定实施计划"等关键词明确启动
|
||||
|
||||
**结构化规格书**
|
||||
|
||||
- 需求定义 (用户故事·验收标准)
|
||||
- 设计书 (架构·数据设计·UI 设计)
|
||||
- 实施计划 (任务分解·进度跟踪·质量保证)
|
||||
- 风险分析与对策
|
||||
|
||||
**审批流程**
|
||||
|
||||
- 通过 `exit_plan_mode` 工具提交计划
|
||||
- **重要**: 无论工具返回值如何，必须等待用户的明确批准
|
||||
- 禁止未经批准就开始实施
|
||||
- 可以修改·调整计划
|
||||
- 仅在批准后才开始使用 TodoWrite 进行任务管理
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 复杂系统实施
|
||||
"制定在线支付系统的实施计划。包括 Stripe 集成、安全性、错误处理"
|
||||
|
||||
# 前端实施
|
||||
"制定 React 仪表板的实施计划。包括状态管理、组件设计、测试"
|
||||
|
||||
# 后端实施
|
||||
"制定 RESTful API 的实施计划。包括认证、验证、日志记录"
|
||||
|
||||
# DevOps 实施
|
||||
"制定 CI/CD 管道的实施计划。包括测试自动化、部署、监控"
|
||||
```
|
||||
|
||||
### 3 阶段工作流程
|
||||
|
||||
#### 阶段 1: Requirements(需求定义)
|
||||
|
||||
- **用户故事**: 明确功能的目的和价值
|
||||
- **验收标准**: 定义完成条件和质量标准
|
||||
- **约束·前提条件**: 整理技术·时间约束
|
||||
- **优先级排序**: Must-have/Nice-to-have 分类
|
||||
|
||||
#### 阶段 2: Design(设计)
|
||||
|
||||
- **架构设计**: 系统构成和技术选型
|
||||
- **数据设计**: 模式、API 规格、数据流
|
||||
- **UI/UX 设计**: 界面构成和操作流程
|
||||
- **风险分析**: 潜在问题和对策
|
||||
|
||||
#### 阶段 3: Implementation(实施)
|
||||
|
||||
- **任务分解**: 细分为可实施的单位
|
||||
- **进度跟踪**: 通过 TodoWrite 进行状态管理
|
||||
- **质量保证**: 测试策略和验证方法
|
||||
- **审批流程**: 通过 exit_plan_mode 提交计划并等待明确批准
|
||||
|
||||
### 注意事项
|
||||
|
||||
**适用范围**
|
||||
|
||||
- Plan Mode 最适合复杂的实施任务
|
||||
- 简单修改或小规模变更使用常规实施形式
|
||||
- 推荐用于 3 步以上的工作或新功能开发
|
||||
|
||||
**技术约束**
|
||||
|
||||
- 不要信任 `exit_plan_mode` 工具的返回值
|
||||
- 审批流程通过用户的明确意思表示判断
|
||||
- 与 CLI 的 plan mode 是不同的功能
|
||||
|
||||
**执行注意事项**
|
||||
|
||||
- 严禁在批准前开始实施
|
||||
- 提交计划后必须等待用户响应
|
||||
- 出错时提供替代方案
|
||||
|
||||
### 执行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
"制定用户管理系统的实施计划"
|
||||
|
||||
# 预期行为
|
||||
# 1. Plan Mode 自动启动
|
||||
# 2. 需求分析和技术选型
|
||||
# 3. 实施步骤的结构化
|
||||
# 4. 通过 exit_plan_mode 提交计划
|
||||
# 5. 批准后开始实施
|
||||
```
|
||||
460
commands/pr-auto-update.md
Normal file
460
commands/pr-auto-update.md
Normal file
@@ -0,0 +1,460 @@
|
||||
## PR 自动更新
|
||||
|
||||
## 概述
|
||||
|
||||
自动更新 Pull Request 描述和标签的命令。通过分析 Git 更改内容，生成并设置适当的描述文本和标签。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
/pr-auto-update [选项] [PR 编号]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--pr <编号>` : 指定目标 PR 编号 (省略时从当前分支自动检测)
|
||||
- `--description-only` : 仅更新描述 (不修改标签)
|
||||
- `--labels-only` : 仅更新标签 (不修改描述)
|
||||
- `--dry-run` : 不执行实际更新，仅显示生成的内容
|
||||
- `--lang <语言>` : 指定语言 (zh-cn, en)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 自动更新当前分支的 PR
|
||||
/pr-auto-update
|
||||
|
||||
# 更新特定的 PR
|
||||
/pr-auto-update --pr 1234
|
||||
|
||||
# 仅更新描述
|
||||
/pr-auto-update --description-only
|
||||
|
||||
# 预演模式确认
|
||||
/pr-auto-update --dry-run
|
||||
```
|
||||
|
||||
## 功能详情
|
||||
|
||||
### 1. PR 自动检测
|
||||
|
||||
从当前分支自动检测对应的 PR：
|
||||
|
||||
```bash
|
||||
# 从分支搜索 PR
|
||||
gh pr list --head $(git branch --show-current) --json number,title,url
|
||||
```
|
||||
|
||||
### 2. 更改内容分析
|
||||
|
||||
收集和分析以下信息：
|
||||
|
||||
- **文件更改**: 添加、删除、修改的文件
|
||||
- **代码分析**: import 语句、函数定义、类定义的更改
|
||||
- **测试**: 测试文件的存在与内容
|
||||
- **文档**: README、docs 的更新
|
||||
- **配置**: package.json、pubspec.yaml、配置文件的更改
|
||||
- **CI/CD**: GitHub Actions、workflow 的更改
|
||||
|
||||
### 3. 描述文本自动生成
|
||||
|
||||
#### 模板处理优先级
|
||||
|
||||
1. **现有 PR 描述**: **完全遵循**已存在的内容
|
||||
2. **项目模板**: 从 `.github/PULL_REQUEST_TEMPLATE.md` 获取结构
|
||||
3. **默认模板**: 上述不存在时的后备方案
|
||||
|
||||
#### 现有内容保留规则
|
||||
|
||||
**重要**: 不修改现有内容
|
||||
|
||||
- 保留已写的部分
|
||||
- 仅补充空白部分
|
||||
- 保留功能性注释 (如 Copilot review rule 等)
|
||||
|
||||
#### 项目模板的使用
|
||||
|
||||
```bash
|
||||
# 解析 .github/PULL_REQUEST_TEMPLATE.md 的结构
|
||||
parse_template_structure() {
|
||||
local template_file="$1"
|
||||
|
||||
if [ -f "$template_file" ]; then
|
||||
# 提取部分结构
|
||||
grep -E '^##|^###' "$template_file"
|
||||
|
||||
# 识别注释占位符
|
||||
grep -E '<!--.*-->' "$template_file"
|
||||
|
||||
# 完全遵循现有模板结构
|
||||
cat "$template_file"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 标签自动设置
|
||||
|
||||
#### 标签获取机制
|
||||
|
||||
**优先级**:
|
||||
|
||||
1. **`.github/labels.yml`**: 从项目特定的标签定义获取
|
||||
2. **GitHub API**: 使用 `gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'` 获取现有标签
|
||||
|
||||
#### 自动判定规则
|
||||
|
||||
**基于文件模式**:
|
||||
|
||||
- 文档: `*.md`, `README`, `docs/` → 包含 `documentation|docs|doc` 的标签
|
||||
- 测试: `test`, `spec` → 包含 `test|testing` 的标签
|
||||
- CI/CD: `.github/`, `*.yml`, `Dockerfile` → 包含 `ci|build|infra|ops` 的标签
|
||||
- 依赖: `package.json`, `pubspec.yaml`, `requirements.txt` → 包含 `dependencies|deps` 的标签
|
||||
|
||||
**基于更改内容**:
|
||||
|
||||
- Bug 修复: `fix|bug|error|crash|修复` → 包含 `bug|fix` 的标签
|
||||
- 新功能: `feat|feature|add|implement|新功能|实装` → 包含 `feature|enhancement|feat` 的标签
|
||||
- 重构: `refactor|clean|重构` → 包含 `refactor|cleanup|clean` 的标签
|
||||
- 性能: `performance|perf|optimize|性能` → 包含 `performance|perf` 的标签
|
||||
- 安全: `security|secure|安全` → 包含 `security` 的标签
|
||||
|
||||
#### 约束
|
||||
|
||||
- **最多 3 个**: 自动选择的标签数量上限
|
||||
- **仅限现有标签**: 禁止创建新标签
|
||||
- **部分匹配**: 根据标签名是否包含关键词判定
|
||||
|
||||
#### 实际使用示例
|
||||
|
||||
**存在 `.github/labels.yml` 时**:
|
||||
|
||||
```bash
|
||||
# 从标签定义自动获取
|
||||
grep "^- name:" .github/labels.yml | sed "s/^- name: '\\?\\([^']*\\)'\\?/\\1/"
|
||||
|
||||
# 例：使用项目特定的标签体系
|
||||
```
|
||||
|
||||
**从 GitHub API 获取时**:
|
||||
|
||||
```bash
|
||||
# 获取现有标签列表
|
||||
gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'
|
||||
|
||||
# 例：使用 bug, enhancement, documentation 等标准标签
|
||||
```
|
||||
|
||||
### 5. 执行流程
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 1. PR 检测与获取
|
||||
detect_pr() {
|
||||
if [ -n "$PR_NUMBER" ]; then
|
||||
echo $PR_NUMBER
|
||||
else
|
||||
gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'
|
||||
fi
|
||||
}
|
||||
|
||||
# 2. 更改内容分析
|
||||
analyze_changes() {
|
||||
local pr_number=$1
|
||||
|
||||
# 获取文件更改
|
||||
gh pr diff $pr_number --name-only
|
||||
|
||||
# 内容分析
|
||||
gh pr diff $pr_number | head -1000
|
||||
}
|
||||
|
||||
# 3. 描述生成
|
||||
generate_description() {
|
||||
local pr_number=$1
|
||||
local changes=$2
|
||||
|
||||
# 获取当前 PR 描述
|
||||
local current_body=$(gh pr view $pr_number --json body --jq -r .body)
|
||||
|
||||
# 如有现有内容则直接使用
|
||||
if [ -n "$current_body" ]; then
|
||||
echo "$current_body"
|
||||
else
|
||||
# 从模板生成新内容
|
||||
local template_file=".github/PULL_REQUEST_TEMPLATE.md"
|
||||
if [ -f "$template_file" ]; then
|
||||
generate_from_template "$(cat "$template_file")" "$changes"
|
||||
else
|
||||
generate_from_template "" "$changes"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# 从模板生成
|
||||
generate_from_template() {
|
||||
local template="$1"
|
||||
local changes="$2"
|
||||
|
||||
if [ -n "$template" ]; then
|
||||
# 直接使用模板 (保留 HTML 注释)
|
||||
echo "$template"
|
||||
else
|
||||
# 使用默认格式生成
|
||||
echo "## What does this change?"
|
||||
echo ""
|
||||
echo "$changes"
|
||||
fi
|
||||
}
|
||||
|
||||
# 4. 标签确定
|
||||
determine_labels() {
|
||||
local changes=$1
|
||||
local file_list=$2
|
||||
local pr_number=$3
|
||||
|
||||
# 获取可用标签
|
||||
local available_labels=()
|
||||
if [ -f ".github/labels.yml" ]; then
|
||||
# 从 labels.yml 提取标签名
|
||||
available_labels=($(grep "^- name:" .github/labels.yml | sed "s/^- name: '\\?\\([^']*\\)'\\?/\\1/"))
|
||||
else
|
||||
# 从 GitHub API 获取标签
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
available_labels=($(gh api "repos/$owner/$repo/labels" --jq '.[].name'))
|
||||
fi
|
||||
|
||||
local suggested_labels=()
|
||||
|
||||
# 通用模式匹配
|
||||
analyze_change_patterns "$file_list" "$changes" available_labels suggested_labels
|
||||
|
||||
# 限制最多 3 个
|
||||
echo "${suggested_labels[@]:0:3}"
|
||||
}
|
||||
|
||||
# 根据更改模式确定标签
|
||||
analyze_change_patterns() {
|
||||
local file_list="$1"
|
||||
local changes="$2"
|
||||
local -n available_ref=$3
|
||||
local -n suggested_ref=$4
|
||||
|
||||
# 根据文件类型判定
|
||||
if echo "$file_list" | grep -q "\\.md$\\|README\\|docs/"; then
|
||||
add_matching_label "documentation\\|docs\\|doc" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$file_list" | grep -q "test\\|spec"; then
|
||||
add_matching_label "test\\|testing" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
# 根据更改内容判定
|
||||
if echo "$changes" | grep -iq "fix\\|bug\\|error\\|crash\\|修复"; then
|
||||
add_matching_label "bug\\|fix" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$changes" | grep -iq "feat\\|feature\\|add\\|implement\\|新功能\\|实现"; then
|
||||
add_matching_label "feature\\|enhancement\\|feat" available_ref suggested_ref
|
||||
fi
|
||||
}
|
||||
|
||||
# 添加匹配的标签
|
||||
add_matching_label() {
|
||||
local pattern="$1"
|
||||
local -n available_ref=$2
|
||||
local -n suggested_ref=$3
|
||||
|
||||
# 如果已有 3 个则跳过
|
||||
if [ ${#suggested_ref[@]} -ge 3 ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
# 添加匹配模式的第一个标签
|
||||
for available_label in "${available_ref[@]}"; do
|
||||
if echo "$available_label" | grep -iq "$pattern"; then
|
||||
# 重复检查
|
||||
local already_exists=false
|
||||
for existing in "${suggested_ref[@]}"; do
|
||||
if [ "$existing" = "$available_label" ]; then
|
||||
already_exists=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$already_exists" = false ]; then
|
||||
suggested_ref+=("$available_label")
|
||||
return
|
||||
fi
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
# 为兼容性保留旧函数
|
||||
find_and_add_label() {
|
||||
add_matching_label "$@"
|
||||
}
|
||||
|
||||
# 5. PR 更新
|
||||
update_pr() {
|
||||
local pr_number=$1
|
||||
local description="$2"
|
||||
local labels="$3"
|
||||
|
||||
if [ "$DRY_RUN" = "true" ]; then
|
||||
echo "=== DRY RUN ==="
|
||||
echo "Description:"
|
||||
echo "$description"
|
||||
echo "Labels: $labels"
|
||||
else
|
||||
# 获取仓库信息
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
|
||||
# 使用 GitHub API 更新正文 (保留 HTML 注释)
|
||||
# 正确处理 JSON 转义
|
||||
local escaped_body=$(echo "$description" | jq -R -s .)
|
||||
gh api \
|
||||
--method PATCH \
|
||||
"/repos/$owner/$repo/pulls/$pr_number" \
|
||||
--field body="$description"
|
||||
|
||||
# 标签使用常规 gh 命令即可
|
||||
if [ -n "$labels" ]; then
|
||||
gh pr edit $pr_number --add-label "$labels"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
## 配置文件 (未来扩展用)
|
||||
|
||||
`~/.claude/pr-auto-update.config`:
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "zh-cn",
|
||||
"max_labels": 3
|
||||
}
|
||||
```
|
||||
|
||||
## 常见模式
|
||||
|
||||
### Flutter 项目
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
实现了{功能名}。解决了用户的{问题}。
|
||||
|
||||
### 主要更改内容
|
||||
|
||||
- **UI 实现**: 新建{画面名}
|
||||
- **状态管理**: 添加 Riverpod Provider
|
||||
- **API 集成**: 实现 GraphQL 查询与变更
|
||||
- **测试**: 添加 Widget 测试和单元测试
|
||||
|
||||
### 技术规格
|
||||
|
||||
- **架构**: {使用的模式}
|
||||
- **依赖**: {新增的包}
|
||||
- **性能**: {优化内容}
|
||||
```
|
||||
|
||||
### Node.js 项目
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
实现了{API 名}端点。支持{用例}。
|
||||
|
||||
### 主要更改内容
|
||||
|
||||
- **API 实现**: 新建{端点}
|
||||
- **验证**: 添加请求验证逻辑
|
||||
- **数据库**: 实现对{表名}的操作
|
||||
- **测试**: 添加集成测试和单元测试
|
||||
|
||||
### 安全性
|
||||
|
||||
- **认证**: JWT 令牌验证
|
||||
- **授权**: 基于角色的访问控制
|
||||
- **输入验证**: SQL 注入防护
|
||||
```
|
||||
|
||||
### CI/CD 改进
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
改进了 GitHub Actions 工作流。实现了{效果}。
|
||||
|
||||
### 改进内容
|
||||
|
||||
- **性能**: 构建时间减少{时间}
|
||||
- **可靠性**: 增强错误处理
|
||||
- **安全性**: 改进密钥管理
|
||||
|
||||
### 技术细节
|
||||
|
||||
- **并行化**: {作业名}并行执行
|
||||
- **缓存**: 优化{缓存对象}的缓存策略
|
||||
- **监控**: 添加{指标}监控
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **完全保留现有内容**:
|
||||
- **一字不改**现有描述内容
|
||||
- 仅补充空白注释和占位符
|
||||
- 尊重用户有意编写的内容
|
||||
|
||||
2. **模板优先级**:
|
||||
- 现有 PR 描述 > `.github/PULL_REQUEST_TEMPLATE.md` > 默认
|
||||
- 完全遵循项目特定的模板结构
|
||||
|
||||
3. **标签约束**:
|
||||
- 如存在 `.github/labels.yml` 则优先使用
|
||||
- 不存在时从 GitHub API 获取现有标签
|
||||
- 禁止创建新标签
|
||||
- 自动选择最多 3 个
|
||||
|
||||
4. **安全更新**:
|
||||
- 推荐使用 `--dry-run` 预先确认
|
||||
- 包含敏感信息的更改时显示警告
|
||||
- 保存原始描述作为备份
|
||||
|
||||
5. **保持一致性**:
|
||||
- 符合项目现有 PR 风格
|
||||
- 统一语言 (日语/英语)
|
||||
- 继承标签规则
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **找不到 PR**: 检查分支名与 PR 的关联
|
||||
2. **权限错误**: 检查 GitHub CLI 的认证状态
|
||||
3. **无法设置标签**: 检查仓库权限
|
||||
4. **HTML 注释被转义**: GitHub CLI 的规格导致 `<!-- -->` 被转换为 `<!-- -->`
|
||||
|
||||
### GitHub CLI 的 HTML 注释转义问题
|
||||
|
||||
**重要**: GitHub CLI (`gh pr edit`) 会自动转义 HTML 注释。此外，Shell 的重定向处理可能混入 `EOF < /dev/null` 等非法字符串。
|
||||
|
||||
#### 根本解决方案
|
||||
|
||||
1. **使用 GitHub API 的 --field 选项**: 使用 `--field` 进行适当的转义处理
|
||||
2. **简化 Shell 处理**: 避免复杂的重定向和管道处理
|
||||
3. **简化模板处理**: 废除 HTML 注释移除处理，完全保留
|
||||
4. **正确处理 JSON 转义**: 正确处理特殊字符
|
||||
|
||||
### 调试选项
|
||||
|
||||
```bash
|
||||
# 输出详细日志 (实现时添加)
|
||||
/pr-auto-update --verbose
|
||||
```
|
||||
251
commands/pr-create.md
Normal file
251
commands/pr-create.md
Normal file
@@ -0,0 +1,251 @@
|
||||
## PR 创建 (已不推荐)
|
||||
|
||||
> 不再推荐：请优先使用 `/pr-create-smart` 生成高质量的 PR 描述草稿，然后使用 gh/GUI 创建 PR。本命令属于“端到端自动创建 PR(保留模板、自动打标签、创建 Draft)”的旧方案，仅为兼容保留。
|
||||
|
||||
基于 Git 变更分析的自动 PR 创建，实现高效的 Pull Request 工作流程。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 基于变更分析的自动 PR 创建
|
||||
git add . && git commit -m "feat: 实现用户认证功能"
|
||||
"分析变更内容并使用适当的描述和标签创建 Draft PR"
|
||||
|
||||
# 保留现有模板的更新
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
"完全保留模板结构并补充变更内容"
|
||||
|
||||
# 逐步提升质量
|
||||
gh pr ready
|
||||
"质量确认完成后，更改为 Ready for Review"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 创建分支并提交
|
||||
git checkout main && git pull
|
||||
git checkout -b feat-user-profile
|
||||
git add . && git commit -m "feat: 实现用户档案功能"
|
||||
git push -u origin feat-user-profile
|
||||
|
||||
# 2. PR 创建
|
||||
"请按以下步骤创建 PR：
|
||||
1. 使用 git diff --cached 确认变更内容
|
||||
2. 使用 .github/PULL_REQUEST_TEMPLATE.md 创建描述
|
||||
3. 从变更内容选择最多 3 个适当的标签
|
||||
4. 创建 Draft PR(保留 HTML 注释)"
|
||||
|
||||
# 3. CI 确认后转为 Ready
|
||||
"CI 通过后将 PR 更改为 Ready for Review"
|
||||
```
|
||||
|
||||
### 执行步骤
|
||||
|
||||
#### 1. 分支创建
|
||||
|
||||
```bash
|
||||
# 遵循准则的命名规则: {type}-{subject}
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b feat-user-authentication
|
||||
|
||||
# 确认分支 (显示当前分支名)
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
#### 2. 提交
|
||||
|
||||
```bash
|
||||
# 暂存变更
|
||||
git add .
|
||||
|
||||
# 遵循准则的提交消息
|
||||
git commit -m "feat: 实现用户认证 API"
|
||||
```
|
||||
|
||||
#### 3. 推送到远程
|
||||
|
||||
```bash
|
||||
# 首次推送 (设置 upstream)
|
||||
git push -u origin feat-user-authentication
|
||||
|
||||
# 后续推送
|
||||
git push
|
||||
```
|
||||
|
||||
#### 4. 基于自动分析创建 Draft PR
|
||||
|
||||
**步骤 1: 分析变更内容**
|
||||
|
||||
```bash
|
||||
# 获取文件变更 (确认已暂存的变更)
|
||||
git diff --cached --name-only
|
||||
|
||||
# 内容分析 (最多 1000 行)
|
||||
git diff --cached | head -1000
|
||||
```
|
||||
|
||||
**步骤 2: 自动生成描述**
|
||||
|
||||
```bash
|
||||
# 模板处理优先级
|
||||
# 1. 现有 PR 描述 (完全保留)
|
||||
# 2. .github/PULL_REQUEST_TEMPLATE.md
|
||||
# 3. 默认模板
|
||||
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
# 保留 HTML 注释·分隔线，仅补充空白部分
|
||||
```
|
||||
|
||||
**步骤 3: 自动选择标签**
|
||||
|
||||
```bash
|
||||
# 获取可用标签 (非交互式)
|
||||
"从 .github/labels.yml 或 GitHub 仓库获取可用标签，根据变更内容自动选择适当的标签"
|
||||
|
||||
# 通过模式匹配自动选择 (最多 3 个)
|
||||
# - 文档: *.md, docs/ → documentation|docs
|
||||
# - 测试: test, spec → test|testing
|
||||
# - Bug 修复: fix|bug → bug|fix
|
||||
# - 新功能: feat|feature → feature|enhancement
|
||||
```
|
||||
|
||||
**步骤 4: 通过 GitHub API 创建 PR(保留 HTML 注释)**
|
||||
|
||||
```bash
|
||||
# PR 创建
|
||||
"使用以下信息创建 Draft PR：
|
||||
- 标题: 从提交消息自动生成
|
||||
- 描述: 使用 .github/PULL_REQUEST_TEMPLATE.md 适当填写
|
||||
- 标签: 从变更内容自动选择 (最多 3 个)
|
||||
- 基础分支: main
|
||||
- 完全保留 HTML 注释"
|
||||
```
|
||||
|
||||
**方法 B: GitHub MCP(备用)**
|
||||
|
||||
```javascript
|
||||
// 保留 HTML 注释的 PR 创建
|
||||
mcp_github_create_pull_request({
|
||||
owner: "organization",
|
||||
repo: "repository",
|
||||
base: "main",
|
||||
head: "feat-user-authentication",
|
||||
title: "feat: 实现用户认证",
|
||||
body: prBodyContent, // 包含 HTML 注释的完整内容
|
||||
draft: true,
|
||||
maintainer_can_modify: true,
|
||||
});
|
||||
```
|
||||
|
||||
### 自动标签选择系统
|
||||
|
||||
#### 基于文件模式的判定
|
||||
|
||||
- **文档**: `*.md`, `README`, `docs/` → `documentation|docs|doc`
|
||||
- **测试**: `test`, `spec` → `test|testing`
|
||||
- **CI/CD**: `.github/`, `*.yml`, `Dockerfile` → `ci|build|infra|ops`
|
||||
- **依赖**: `package.json`, `pubspec.yaml` → `dependencies|deps`
|
||||
|
||||
#### 基于变更内容的判定
|
||||
|
||||
- **Bug 修复**: `fix|bug|error|crash|修复` → `bug|fix`
|
||||
- **新功能**: `feat|feature|add|implement|新功能|实现` → `feature|enhancement|feat`
|
||||
- **重构**: `refactor|clean|重构` → `refactor|cleanup|clean`
|
||||
- **性能**: `performance|perf|optimize` → `performance|perf`
|
||||
- **安全**: `security|secure` → `security`
|
||||
|
||||
#### 约束条件
|
||||
|
||||
- **最多 3 个**: 自动选择的上限
|
||||
- **仅现有标签**: 禁止新建
|
||||
- **部分匹配**: 通过关键词包含进行判定
|
||||
|
||||
### 项目准则
|
||||
|
||||
#### 基本原则
|
||||
|
||||
1. **必须以 Draft 开始**: 所有 PR 都以 Draft 状态创建
|
||||
2. **逐步提升质量**: 阶段 1(基本实现)→ 阶段 2(添加测试)→ 阶段 3(更新文档)
|
||||
3. **适当的标签**: 必须添加最多 3 种标签
|
||||
4. **使用模板**: 必须使用 `.github/PULL_REQUEST_TEMPLATE.md`
|
||||
5. **中文空格**: 中文与半角英数字之间必须有半角空格
|
||||
|
||||
#### 分支命名规则
|
||||
|
||||
```text
|
||||
{type}-{subject}
|
||||
|
||||
示例:
|
||||
- feat-user-profile
|
||||
- fix-login-error
|
||||
- refactor-api-client
|
||||
```
|
||||
|
||||
#### 提交消息
|
||||
|
||||
```text
|
||||
{type}: {description}
|
||||
|
||||
示例:
|
||||
- feat: 实现用户认证 API
|
||||
- fix: 修复登录错误
|
||||
- docs: 更新 README
|
||||
```
|
||||
|
||||
### 模板处理系统
|
||||
|
||||
#### 处理优先级
|
||||
|
||||
1. **现有 PR 描述**: **完全沿用**已编写的内容
|
||||
2. **项目模板**: 保持 `.github/PULL_REQUEST_TEMPLATE.md` 结构
|
||||
3. **默认模板**: 以上不存在时使用
|
||||
|
||||
#### 现有内容保留规则
|
||||
|
||||
- **一字不改**: 已编写的内容
|
||||
- **仅补充空白部分**: 用变更内容填充占位符部分
|
||||
- **保留功能性注释**: 保持 `<!-- Copilot review rule -->` 等
|
||||
- **保留 HTML 注释**: 完全保留 `<!-- ... -->`
|
||||
- **保留分隔线**: 保持 `---` 等结构
|
||||
|
||||
#### HTML 注释保留的处理方法
|
||||
|
||||
**重要**: GitHub CLI (`gh pr edit`) 会自动转义 HTML 注释，在 Shell 处理中可能混入 `EOF < /dev/null` 等非法字符串。
|
||||
|
||||
**根本解决方案**:
|
||||
|
||||
1. **使用 GitHub API 的 --field 选项**: 通过适当的转义处理保留 HTML 注释
|
||||
2. **简化模板处理**: 避免复杂的管道处理和重定向
|
||||
3. **完全保留方法**: 废除 HTML 注释删除处理，完全保留模板
|
||||
|
||||
### 审查评论响应
|
||||
|
||||
```bash
|
||||
# 变更后重新提交
|
||||
git add .
|
||||
git commit -m "fix: 基于审查反馈的修正"
|
||||
git push
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
#### HTML 注释保留的重要性
|
||||
|
||||
- **GitHub CLI 限制**: `gh pr edit` 会转义 HTML 注释，混入非法字符串
|
||||
- **根本规避策略**: 使用 GitHub API 的 `--field` 选项进行适当的转义处理
|
||||
- **模板完全保留**: 废除 HTML 注释删除处理，完全维护结构
|
||||
|
||||
#### 自动化的约束
|
||||
|
||||
- **禁止新建标签**: 不可创建 `.github/labels.yml` 定义外的标签
|
||||
- **最多 3 个标签**: 自动选择的上限
|
||||
- **现有内容优先**: 不更改手动编写的内容
|
||||
|
||||
#### 逐步提升质量
|
||||
|
||||
- **Draft 必须**: 所有 PR 以 Draft 开始
|
||||
- **CI 确认**: 使用 `gh pr checks` 确认状态
|
||||
- **转为 Ready**: 质量确认完成后使用 `gh pr ready`
|
||||
- **完全遵守模板**: 维护项目特有的结构
|
||||
143
commands/pr-feedback.md
Normal file
143
commands/pr-feedback.md
Normal file
@@ -0,0 +1,143 @@
|
||||
## PR 反馈处理
|
||||
|
||||
高效处理 Pull Request 的审查评论，采用错误分析三阶段方法寻求根本解决方案。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 获取并分析审查评论
|
||||
gh pr view --comments
|
||||
「请按优先级分类审查评论并创建应对计划」
|
||||
|
||||
# 错误相关评论的详细分析
|
||||
gh pr checks
|
||||
「请用三阶段方法分析 CI 错误并找出根本原因」
|
||||
|
||||
# 修复完成后的质量确认
|
||||
npm test && npm run lint
|
||||
「修复已完成，请检查回归测试和代码质量」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 执行评论分类
|
||||
gh pr view 123 --comments | head -20
|
||||
"请将审查评论分类为 must/imo/nits/q 并决定处理顺序"
|
||||
|
||||
# 收集错误信息
|
||||
npm run build 2>&1 | tee error.log
|
||||
"请找出构建错误的根本原因并提出适当的修复方法"
|
||||
|
||||
# 确认修复实现
|
||||
git diff HEAD~1
|
||||
"请评估此修复是否恰当解决了审查指出的问题"
|
||||
```
|
||||
|
||||
### 评论分类体系
|
||||
|
||||
```text
|
||||
🔴 must: 必须修复
|
||||
├─ 安全问题
|
||||
├─ 功能缺陷
|
||||
├─ 设计原则违反
|
||||
└─ 规范违反
|
||||
|
||||
🟡 imo: 改进建议
|
||||
├─ 更好的实现方法
|
||||
├─ 性能改进
|
||||
├─ 可读性提升
|
||||
└─ 重构建议
|
||||
|
||||
🟢 nits: 轻微指摘
|
||||
├─ 拼写错误修正
|
||||
├─ 缩进调整
|
||||
├─ 注释添加
|
||||
└─ 命名微调
|
||||
|
||||
🔵 q: 问题与确认
|
||||
├─ 实现意图确认
|
||||
├─ 规格明确化
|
||||
├─ 设计决策背景
|
||||
└─ 替代方案探讨
|
||||
```
|
||||
|
||||
### 错误分析三阶段方法
|
||||
|
||||
#### 第一阶段：信息收集
|
||||
|
||||
**必须执行**
|
||||
|
||||
- 完整获取错误消息
|
||||
- 确认堆栈跟踪
|
||||
- 确定重现条件
|
||||
|
||||
**推荐执行**
|
||||
|
||||
- 收集环境信息
|
||||
- 最近的更改历史
|
||||
- 确认相关日志
|
||||
|
||||
#### 第二阶段：根本原因分析
|
||||
|
||||
- 应用 5 Whys 分析
|
||||
- 追踪依赖关系
|
||||
- 确认环境差异
|
||||
- 创建最小重现代码
|
||||
|
||||
#### 第三阶段：解决方案实施
|
||||
|
||||
- 立即处理 (热修复)
|
||||
- 根本解决 (本质修复)
|
||||
- 预防措施 (防止复发)
|
||||
|
||||
### 应对流程
|
||||
|
||||
1. **评论分析**: 按优先级分类
|
||||
2. **修复计划**: 决定处理顺序
|
||||
3. **阶段性修复**: Critical → High → Medium → Low
|
||||
4. **质量确认**: 测试、代码检查、构建
|
||||
5. **进度报告**: 具体说明修复内容
|
||||
|
||||
### 修复后的确认
|
||||
|
||||
```bash
|
||||
# 基本检查
|
||||
npm test
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# 回归测试
|
||||
npm run test:e2e
|
||||
|
||||
# 代码质量
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### 回复模板
|
||||
|
||||
**修复完成报告**
|
||||
|
||||
```markdown
|
||||
@reviewer 感谢您的指正。
|
||||
修复已完成：
|
||||
|
||||
- [具体修复内容]
|
||||
- [测试结果]
|
||||
- [确认方法]
|
||||
```
|
||||
|
||||
**技术判断说明**
|
||||
|
||||
```markdown
|
||||
实现背景：[原因]
|
||||
考虑的替代方案：[选项与判断依据]
|
||||
采用方案的优点：[优势]
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **遵守优先级**: 按 Critical → High → Medium → Low 顺序处理
|
||||
- **测试优先**: 修复前确认回归测试
|
||||
- **明确报告**: 具体描述修复内容和确认方法
|
||||
- **建设性对话**: 基于技术依据的礼貌沟通
|
||||
78
commands/pr-issue.md
Normal file
78
commands/pr-issue.md
Normal file
@@ -0,0 +1,78 @@
|
||||
## Issue 列表
|
||||
|
||||
显示当前仓库的开放 Issue 列表，并按优先级排序。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 请求
|
||||
「请按优先级显示开放的 Issue 列表」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 获取仓库信息
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 获取开放 Issue 信息并请求 Claude
|
||||
gh issue list --state open --json number,title,author,createdAt,updatedAt,labels,assignees,comments --limit 30
|
||||
|
||||
「请按优先级整理上述 Issue，并包含每个 Issue 的 2 行概要。使用上面获取的仓库名生成 URL」
|
||||
```
|
||||
|
||||
### 显示格式
|
||||
|
||||
```text
|
||||
开放 Issue 列表 (按优先级排序)
|
||||
|
||||
### 高优先级
|
||||
#编号 标题 [标签] | 作者 | 开放时长 | 评论数 | 负责人
|
||||
├─ 概要第 1 行
|
||||
└─ 概要第 2 行
|
||||
https://github.com/owner/repo/issues/编号
|
||||
|
||||
### 中优先级
|
||||
(相同格式)
|
||||
|
||||
### 低优先级
|
||||
(相同格式)
|
||||
```
|
||||
|
||||
### 优先级判定标准
|
||||
|
||||
**高优先级**
|
||||
|
||||
- 带有 `bug` 标签的 Issue
|
||||
- 带有 `critical` 或 `urgent` 标签的 Issue
|
||||
- 带有 `security` 标签的 Issue
|
||||
|
||||
**中优先级**
|
||||
|
||||
- 带有 `enhancement` 标签的 Issue
|
||||
- 带有 `feature` 标签的 Issue
|
||||
- 已分配负责人的 Issue
|
||||
|
||||
**低优先级**
|
||||
|
||||
- 带有 `documentation` 标签的 Issue
|
||||
- 带有 `good first issue` 标签的 Issue
|
||||
- 带有 `wontfix` 或 `duplicate` 标签的 Issue
|
||||
|
||||
### 按标签筛选
|
||||
|
||||
```bash
|
||||
# 仅获取特定标签的 Issue
|
||||
gh issue list --state open --label "bug" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
|
||||
# 使用多个标签筛选 (AND 条件)
|
||||
gh issue list --state open --label "bug,high-priority" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 需要安装 GitHub CLI (`gh`)
|
||||
- 仅显示开放状态的 Issue
|
||||
- 最多显示 30 个 Issue
|
||||
- 时长是从 Issue 开放至今的时间
|
||||
- Issue URL 根据实际仓库名自动生成
|
||||
66
commands/pr-list.md
Normal file
66
commands/pr-list.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## PR 列表
|
||||
|
||||
显示当前仓库的开放 PR 列表，并按优先级排序。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 请求
|
||||
「请按优先级显示开放的 PR 列表」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 获取仓库信息
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 获取开放 PR 信息并请求 Claude
|
||||
gh pr list --state open --draft=false --json number,title,author,createdAt,additions,deletions,reviews --limit 30
|
||||
|
||||
「请按优先级整理上述 PR，并包含每个 PR 的 2 行概要。使用上面获取的仓库名生成 URL」
|
||||
```
|
||||
|
||||
### 显示格式
|
||||
|
||||
```text
|
||||
开放 PR 列表 (按优先级排序)
|
||||
|
||||
### 高优先级
|
||||
#编号 标题 [Draft/DNM] | 作者 | 开放时长 | 批准数 | +添加/-删除
|
||||
├─ 概要第 1 行
|
||||
└─ 概要第 2 行
|
||||
https://github.com/owner/repo/pull/编号
|
||||
|
||||
### 中优先级
|
||||
(相同格式)
|
||||
|
||||
### 低优先级
|
||||
(相同格式)
|
||||
```
|
||||
|
||||
### 优先级判定标准
|
||||
|
||||
**高优先级**
|
||||
|
||||
- `fix:` Bug 修复
|
||||
- `release:` 发布工作
|
||||
|
||||
**中优先级**
|
||||
|
||||
- `feat:` 新功能
|
||||
- `update:` 功能改进
|
||||
- 其他常规 PR
|
||||
|
||||
**低优先级**
|
||||
|
||||
- 包含 DO NOT MERGE 的 PR
|
||||
- Draft 状态的 `test:`、`build:`、`perf:` PR
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 需要安装 GitHub CLI (`gh`)
|
||||
- 仅显示开放状态的 PR(排除 Draft)
|
||||
- 最多显示 30 个 PR
|
||||
- 时长是从 PR 开放至今的时间
|
||||
- PR URL 根据实际仓库名自动生成
|
||||
165
commands/pr-review.md
Normal file
165
commands/pr-review.md
Normal file
@@ -0,0 +1,165 @@
|
||||
## PR 审查
|
||||
|
||||
通过 Pull Request 的系统化审查确保代码质量和架构健全性。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# PR 的全面审查
|
||||
gh pr view 123 --comments
|
||||
"系统化审查这个 PR，从代码质量、安全性、架构角度提供反馈"
|
||||
|
||||
# 安全性专注审查
|
||||
gh pr diff 123
|
||||
"专注于安全风险和漏洞进行审查"
|
||||
|
||||
# 架构视角的审查
|
||||
gh pr checkout 123 && find . -name "*.js" | head -10
|
||||
"从层级分离、依赖关系、SOLID 原则的角度评估架构"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 代码质量的数值评估
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -5
|
||||
"评估代码的复杂度、函数大小、重复度并指出改进点"
|
||||
|
||||
# 安全漏洞检查
|
||||
grep -r "password\|secret\|token" . --include="*.js" | head -10
|
||||
"检查敏感信息泄露、硬编码、认证绕过的风险"
|
||||
|
||||
# 架构违规检测
|
||||
grep -r "import.*from.*\\.\\./\\.\\." . --include="*.js"
|
||||
"评估层级违规、循环依赖、耦合度问题"
|
||||
```
|
||||
|
||||
### 评论分类体系
|
||||
|
||||
```text
|
||||
🔴 critical.must: 致命问题
|
||||
├─ 安全漏洞
|
||||
├─ 数据一致性问题
|
||||
└─ 系统故障风险
|
||||
|
||||
🟡 high.imo: 高优先级改进
|
||||
├─ 功能故障风险
|
||||
├─ 性能问题
|
||||
└─ 可维护性大幅降低
|
||||
|
||||
🟢 medium.imo: 中优先级改进
|
||||
├─ 可读性提升
|
||||
├─ 代码结构改进
|
||||
└─ 测试质量提升
|
||||
|
||||
🟢 low.nits: 轻微指摘
|
||||
├─ 风格统一
|
||||
├─ 拼写错误修正
|
||||
└─ 注释添加
|
||||
|
||||
🔵 info.q: 问题·信息提供
|
||||
├─ 实现意图确认
|
||||
├─ 设计决策背景
|
||||
└─ 最佳实践分享
|
||||
```
|
||||
|
||||
### 审查观点
|
||||
|
||||
#### 1. 代码正确性
|
||||
|
||||
- **逻辑错误**: 边界值、Null 检查、异常处理
|
||||
- **数据一致性**: 类型安全、验证
|
||||
- **错误处理**: 全面性、适当处理
|
||||
|
||||
#### 2. 安全性
|
||||
|
||||
- **认证·授权**: 适当检查、权限管理
|
||||
- **输入验证**: SQL 注入、XSS 对策
|
||||
- **敏感信息**: 禁止日志输出、加密
|
||||
|
||||
#### 3. 性能
|
||||
|
||||
- **算法**: 时间复杂度、内存效率
|
||||
- **数据库**: N+1 查询、索引优化
|
||||
- **资源**: 内存泄漏、缓存利用
|
||||
|
||||
#### 4. 架构
|
||||
|
||||
- **层级分离**: 依赖方向、适当分离
|
||||
- **耦合度**: 松耦合、接口使用
|
||||
- **SOLID 原则**: 单一职责、开闭原则、依赖倒置
|
||||
|
||||
### 审查流程
|
||||
|
||||
1. **事前确认**: PR 信息、变更差异、相关 Issue
|
||||
2. **系统化检查**: 安全性 → 正确性 → 性能 → 架构
|
||||
3. **建设性反馈**: 具体改进建议和代码示例
|
||||
4. **后续跟进**: 修正确认、CI 状态、最终批准
|
||||
|
||||
### 评论模板
|
||||
|
||||
#### 安全问题模板
|
||||
|
||||
**格式：**
|
||||
|
||||
- 严重程度：`critical.must.`
|
||||
- 问题：明确描述问题
|
||||
- 代码示例：提供修复方案
|
||||
- 理由：解释为什么需要修复
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
critical.must. 密码以明文保存
|
||||
|
||||
修复方案：
|
||||
const bcrypt = require('bcrypt');
|
||||
const hashedPassword = await bcrypt.hash(password, 12);
|
||||
|
||||
为防止安全风险，必须进行哈希处理。
|
||||
```
|
||||
|
||||
#### 性能改进模板
|
||||
|
||||
**格式：**
|
||||
|
||||
- 严重程度：`high.imo.`
|
||||
- 问题：解释性能影响
|
||||
- 代码示例：提供改进方案
|
||||
- 效果：描述预期改进
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
high.imo. 会发生 N+1 查询问题
|
||||
|
||||
改进方案：Eager Loading
|
||||
const users = await User.findAll({ include: [Post] });
|
||||
|
||||
可以大幅减少查询数量。
|
||||
```
|
||||
|
||||
#### 架构违规模板
|
||||
|
||||
**格式：**
|
||||
|
||||
- 严重程度：`high.must.`
|
||||
- 问题：指出架构原则违规
|
||||
- 解决方案：提供架构改进方向
|
||||
- 原则：引用相关设计原则
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
high.must. 发生了层级违规
|
||||
|
||||
领域层直接依赖基础设施层。
|
||||
请通过依赖倒置原则引入接口。
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **建设性语气**: 协作而非攻击性的沟通
|
||||
- **具体建议**: 不仅指出问题，还要提供解决方案
|
||||
- **优先级排序**: 按 Critical → High → Medium → Low 顺序处理
|
||||
- **持续改进**: 将审查结果知识库化
|
||||
324
commands/refactor.md
Normal file
324
commands/refactor.md
Normal file
@@ -0,0 +1,324 @@
|
||||
## 重构
|
||||
|
||||
实施安全且渐进式的代码重构，定量评估 SOLID 原则的遵守情况。将技术债务可视化，明确改进的优先级。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 识别复杂代码并制定重构计划
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -10
|
||||
"重构大文件以降低复杂度"
|
||||
|
||||
# 检测并整合重复代码
|
||||
grep -r "function processUser" . --include="*.js"
|
||||
"通过 Extract Method 将重复函数共通化"
|
||||
|
||||
# 检测 SOLID 原则违反
|
||||
grep -r "class.*Service" . --include="*.js" | head -10
|
||||
"评估这些类是否遵循单一职责原则"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 检测长方法
|
||||
grep -A 50 "function" src/*.js | grep -B 50 -A 50 "return" | wc -l
|
||||
"用 Extract Method 拆分 50 行以上的方法"
|
||||
|
||||
# 条件分支的复杂度
|
||||
grep -r "if.*if.*if" . --include="*.js"
|
||||
"用 Strategy 模式改进嵌套的条件语句"
|
||||
|
||||
# 检测代码异味
|
||||
grep -r "TODO\|FIXME\|HACK" . --exclude-dir=node_modules
|
||||
"解决成为技术债务的注释"
|
||||
```
|
||||
|
||||
### 重构技法
|
||||
|
||||
#### Extract Method(提取方法)
|
||||
|
||||
```javascript
|
||||
// Before: 冗长的方法
|
||||
function processOrder(order) {
|
||||
// 50 行复杂处理
|
||||
}
|
||||
|
||||
// After: 职责分离
|
||||
function processOrder(order) {
|
||||
validateOrder(order);
|
||||
calculateTotal(order);
|
||||
saveOrder(order);
|
||||
}
|
||||
```
|
||||
|
||||
#### Replace Conditional with Polymorphism(多态替换条件)
|
||||
|
||||
```javascript
|
||||
// Before: switch 语句
|
||||
function getPrice(user) {
|
||||
switch (user.type) {
|
||||
case "premium":
|
||||
return basePrice * 0.8;
|
||||
case "regular":
|
||||
return basePrice;
|
||||
}
|
||||
}
|
||||
|
||||
// After: Strategy 模式
|
||||
class PremiumPricing {
|
||||
calculate(basePrice) {
|
||||
return basePrice * 0.8;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SOLID 原则评分 (0-100 分)
|
||||
|
||||
#### 评估标准与计分
|
||||
|
||||
```text
|
||||
S - Single Responsibility(20 分)
|
||||
├─ 类的职责数: 1 个 (20 分) | 2 个 (15 分) | 3 个 (10 分) | 4 个以上 (5 分)
|
||||
├─ 方法数: <7 个 (+5 分) | 7-15 个 (+3 分) | >15 个 (0 分)
|
||||
├─ 变更原因的明确性: 明确 (+5 分) | 模糊 (0 分)
|
||||
└─ 评分例: UserService(认证+数据处理) = 10 分
|
||||
|
||||
O - Open/Closed(20 分)
|
||||
├─ 扩展点: Strategy/Template Method(20 分) | 仅继承 (10 分) | 无 (5 分)
|
||||
├─ 新功能添加时的现有代码变更: 不需要 (+5 分) | 最小限 (+3 分) | 需要 (0 分)
|
||||
├─ 接口利用: 适当 (+5 分) | 部分 (+3 分) | 无 (0 分)
|
||||
└─ 评分例: PaymentProcessor(Strategy) = 20 分
|
||||
|
||||
L - Liskov Substitution(20 分)
|
||||
├─ 派生类的契约遵守: 完全 (20 分) | 部分 (10 分) | 违反 (0 分)
|
||||
├─ 先决条件的加强: 无 (+5 分) | 有 (-5 分)
|
||||
├─ 后决条件的弱化: 无 (+5 分) | 有 (-5 分)
|
||||
└─ 评分例: Square extends Rectangle = 0 分 (违反)
|
||||
|
||||
I - Interface Segregation(20 分)
|
||||
├─ 接口大小: 1-3 方法 (20 分) | 4-7(15 分) | 8+(5 分)
|
||||
├─ 未使用方法实现: 无 (+5 分) | 1-2 个 (+2 分) | 3 个以上 (0 分)
|
||||
├─ 角色的明确性: 单一角色 (+5 分) | 多个角色 (0 分)
|
||||
└─ 评分例: Readable/Writable 分离 = 20 分
|
||||
|
||||
D - Dependency Inversion(20 分)
|
||||
├─ 依赖方向: 仅抽象 (20 分) | 混合 (10 分) | 仅具象 (5 分)
|
||||
├─ DI 利用: Constructor Injection(+5 分) | Setter(+3 分) | 无 (0 分)
|
||||
├─ 可测试性: Mock 可能 (+5 分) | 困难 (0 分)
|
||||
└─ 评分例: Repository Pattern = 20 分
|
||||
|
||||
总评分 = S + O + L + I + D
|
||||
├─ 90-100 分: Excellent(SOLID 完全遵守)
|
||||
├─ 70-89 分: Good(轻微改进余地)
|
||||
├─ 50-69 分: Fair(重构建议)
|
||||
├─ 30-49 分: Poor(大規模改进必要)
|
||||
└─ 0-29 分: Critical(设计重新考虑必要)
|
||||
```
|
||||
|
||||
### 重构步骤
|
||||
|
||||
1. **现状分析**
|
||||
- 复杂度测量 (循环复杂度)
|
||||
- 重复代码检测
|
||||
- 依赖关系分析
|
||||
|
||||
2. **渐进式执行**
|
||||
- 小步骤 (15-30 分钟单位)
|
||||
- 每次变更后执行测试
|
||||
- 频繁提交
|
||||
|
||||
3. **质量确认**
|
||||
- 维持测试覆盖率
|
||||
- 性能测量
|
||||
- 代码审查
|
||||
|
||||
### 常见的代码异味
|
||||
|
||||
- **God Object**: 承担过多职责的类
|
||||
- **Long Method**: 超过 50 行的长方法
|
||||
- **Duplicate Code**: 相同逻辑的重复
|
||||
- **Large Class**: 超过 300 行的大类
|
||||
- **Long Parameter List**: 4 个以上的参数
|
||||
|
||||
### 自动化支持
|
||||
|
||||
```bash
|
||||
# 静态分析
|
||||
npx complexity-report src/
|
||||
sonar-scanner
|
||||
|
||||
# 代码格式化
|
||||
npm run lint:fix
|
||||
prettier --write src/
|
||||
|
||||
# 测试执行
|
||||
npm test
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### 技术债务的定量化
|
||||
|
||||
#### 债务计算公式
|
||||
|
||||
```text
|
||||
技术债务 (时间) = 复杂度评分 × 影响范围 × 修复难度
|
||||
|
||||
复杂度评分:
|
||||
├─ 循环复杂度: 1-5(低) | 6-10(中) | 11-20(高) | 21+(危险)
|
||||
├─ 认知复杂度: 嵌套深度 × 条件分支数
|
||||
├─ 代码行数: <50(1 点) | 50-200(2 点) | 200-500(3 点) | 500+(5 点)
|
||||
└─ 重复率: 0-10%(1 点) | 10-30%(2 点) | 30-50%(3 点) | 50%+(5 点)
|
||||
|
||||
影响范围:
|
||||
├─ 依赖模块数: 直接依赖 + 间接依赖 × 0.5
|
||||
├─ 使用频率: API 调用次数/日
|
||||
├─ 业务重要度: Critical(×3) | High(×2) | Medium(×1) | Low(×0.5)
|
||||
└─ 团队知识: 理解者 1 名 (×3) | 2-3 名 (×2) | 4 名以上 (×1)
|
||||
|
||||
修复难度:
|
||||
├─ 测试覆盖率: 0%(×3) | <50%(×2) | 50-80%(×1.5) | >80%(×1)
|
||||
├─ 文档: 无 (×2) | 不充分 (×1.5) | 充分 (×1)
|
||||
├─ 依赖关系: 密耦合 (×3) | 中等 (×2) | 疏耦合 (×1)
|
||||
└─ 变更风险: Breaking Change(×3) | 兼容性考虑 (×2) | 安全 (×1)
|
||||
|
||||
成本换算:
|
||||
├─ 时间成本: 债务时间 × 开发者时薪
|
||||
├─ 机会损失: 新功能开发延迟日数 × 日次销售影响
|
||||
├─ 质量成本: 缺陷发生概率 × 修复成本 × 发生频率
|
||||
└─ 总成本: 时间 + 机会损失 + 质量成本
|
||||
```
|
||||
|
||||
#### 优先级矩阵
|
||||
|
||||
| 优先级 | 影响度 | 修复成本 | 处理期限 | 具体例 | 推荐行动 |
|
||||
| ------------------------- | ------ | -------- | -------- | ------------------------ | -------------------- |
|
||||
| **Critical(即座处理)** | 高 | 低 | 1 周内 | God Object、循环依赖 | 即座重构开始 |
|
||||
| **Important(计划性处理)** | 高 | 高 | 1 个月内 | 大规模职责分离、架构变更 | 纳入 Sprint 计划 |
|
||||
| **Watch(监视对象)** | 低 | 高 | 3 个月内 | 复杂度高的内部处理 | 指标监视、恶化时处理 |
|
||||
| **Acceptable(容许范围)** | 低 | 低 | 无需处理 | 轻微的代码异味 | 通常重构时处理 |
|
||||
|
||||
### 重构步骤
|
||||
|
||||
1. **现状分析和测量**
|
||||
- 复杂度测量 (循环、认知)
|
||||
- SOLID 评分计算 (0-100 分)
|
||||
- 技术债务定量化 (时间/成本)
|
||||
- 优先级矩阵创建
|
||||
|
||||
2. **渐进式执行**
|
||||
- 小步骤 (15-30 分钟单位)
|
||||
- 每次变更后测试执行
|
||||
- 频繁提交
|
||||
- SOLID 评分的持续测量
|
||||
|
||||
3. **质量确认**
|
||||
- 测试覆盖率维持
|
||||
- 性能测量
|
||||
- 技术债务删减确认
|
||||
- 代码审查
|
||||
|
||||
### 常见代码异味和债务评分
|
||||
|
||||
| 代码异味 | 检测标准 | 债务评分 | 改进手法 |
|
||||
| ----------------------- | -------------------- | ----------- | ----------------------- |
|
||||
| **God Object** | 职责 >3, 方法 >20 | 高 (15-20h) | Extract Class, SRP 适用 |
|
||||
| **Long Method** | 行数 >50, 复杂度 >10 | 中 (5-10h) | Extract Method |
|
||||
| **Duplicate Code** | 重复率 >30% | 高 (10-15h) | Extract Method/Class |
|
||||
| **Large Class** | 行数 >300, 方法 >15 | 高 (10-20h) | Extract Class |
|
||||
| **Long Parameter List** | 参数 >4 | 低 (2-5h) | Parameter Object |
|
||||
| **Feature Envy** | 其他类引用 >5 | 中 (5-10h) | Move Method |
|
||||
| **Data Clumps** | 同一参数群重复 | 低 (3-5h) | Extract Class |
|
||||
| **Primitive Obsession** | 原始类型过度使用 | 中 (5-8h) | Replace with Object |
|
||||
| **Switch Statements** | case >5 | 中 (5-10h) | Strategy Pattern |
|
||||
| **Shotgun Surgery** | 变更时影响位置 >3 | 高 (10-15h) | Move Method/Field |
|
||||
|
||||
### 实践例: SOLID 评分评估
|
||||
|
||||
```javascript
|
||||
// 评估对象: UserService 类
|
||||
class UserService {
|
||||
constructor(db, cache, logger, emailService) { // 4 个依赖
|
||||
this.db = db;
|
||||
this.cache = cache;
|
||||
this.logger = logger;
|
||||
this.emailService = emailService;
|
||||
}
|
||||
|
||||
// 职责 1: 认证
|
||||
authenticate(username, password) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
|
||||
// 职责 2: 用户管理
|
||||
createUser(data) { /* ... */ }
|
||||
updateUser(id, data) { /* ... */ }
|
||||
deleteUser(id) { /* ... */ }
|
||||
|
||||
// 职责 3: 通知
|
||||
sendWelcomeEmail(user) { /* ... */ }
|
||||
sendPasswordReset(email) { /* ... */ }
|
||||
}
|
||||
|
||||
// SOLID 评分评估结果
|
||||
S: 10 分 (职责 3 个: 认证、CRUD、通知)
|
||||
O: 5 分 (无扩展点，直接实现)
|
||||
L: 15 分 (无继承，不适用)
|
||||
I: 10 分 (接口未分离)
|
||||
D: 10 分 (具象类依赖)
|
||||
总合: 50 分 (Fair - 重构建议)
|
||||
|
||||
// 技术债务
|
||||
复杂度: 15 (方法 7 个，职责 3 个)
|
||||
影响范围: 8 (认证系在全功能使用)
|
||||
修复难度: 2 (有测试，文档不足)
|
||||
债务时间: 15 × 8 × 2 = 240 小时
|
||||
优先级: Critical (认证系应即座处理)
|
||||
```
|
||||
|
||||
### 改进后实现例
|
||||
|
||||
```javascript
|
||||
// SOLID 原则适用后 (评分: 90 分)
|
||||
|
||||
// S: 单一职责 (20 分)
|
||||
class AuthenticationService {
|
||||
authenticate(credentials) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
}
|
||||
|
||||
// O: 开放封闭 (20 分)
|
||||
class UserRepository {
|
||||
constructor(storage) { // Strategy Pattern
|
||||
this.storage = storage;
|
||||
}
|
||||
save(user) { return this.storage.save(user); }
|
||||
}
|
||||
|
||||
// I: 接口分离 (20 分)
|
||||
interface Readable {
|
||||
find(id);
|
||||
findAll();
|
||||
}
|
||||
interface Writable {
|
||||
save(entity);
|
||||
delete(id);
|
||||
}
|
||||
|
||||
// D: 依赖倒置 (20 分)
|
||||
class UserService {
|
||||
constructor(
|
||||
private auth: IAuthService,
|
||||
private repo: IUserRepository,
|
||||
private notifier: INotificationService
|
||||
) {}
|
||||
}
|
||||
|
||||
// 债务删减: 240 小时 → 20 小时 (92% 删减)
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **禁止功能变更**: 不改变外部行为
|
||||
- **测试优先**: 重构前添加测试
|
||||
- **渐进式方法**: 不要一次性大幅变更
|
||||
- **持续验证**: 每步都执行测试
|
||||
571
commands/role-debate.md
Normal file
571
commands/role-debate.md
Normal file
@@ -0,0 +1,571 @@
|
||||
## 角色辩论
|
||||
|
||||
不同专业角色进行辩论，考虑权衡取舍并导出最优解的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role-debate <角色 1>,<角色 2> [议题]
|
||||
/role-debate <角色 1>,<角色 2>,<角色 3> [议题]
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 安全性 vs 性能的权衡
|
||||
/role-debate security,performance
|
||||
"关于 JWT 令牌的有效期设置"
|
||||
|
||||
# 可用性 vs 安全性的平衡
|
||||
/role-debate frontend,security
|
||||
"关于双因素认证的 UX 优化"
|
||||
|
||||
# 技术选型的辩论
|
||||
/role-debate architect,mobile
|
||||
"关于 React Native vs Flutter 的选择"
|
||||
|
||||
# 三方辩论
|
||||
/role-debate architect,security,performance
|
||||
"关于微服务化的必要性"
|
||||
```
|
||||
|
||||
### 辩论的基本原则
|
||||
|
||||
#### 建设性辩论准则
|
||||
|
||||
- **相互尊重**: 尊重其他角色的专业性和视角
|
||||
- **基于事实**: 基于数据·证据的辩论，而非情绪化反驳
|
||||
- **解决导向**: 旨在寻找更好的解决方案，而非为批判而批判
|
||||
- **重视实施**: 考虑可实现性的提案，而非理想论
|
||||
|
||||
#### 论据的质量要求
|
||||
|
||||
- **官方文档**: 引用标准·指南·官方文档
|
||||
- **实证案例**: 具体引用成功案例·失败案例
|
||||
- **定量评估**: 尽可能使用数值·指标进行比较
|
||||
- **时间考虑**: 评估短期·中期·长期的影响
|
||||
|
||||
#### 辩论伦理
|
||||
|
||||
- **诚实性**: 承认自身专业领域的局限
|
||||
- **开放性**: 对新信息·视角保持灵活性
|
||||
- **透明性**: 明示判断依据·前提条件
|
||||
- **责任性**: 包括提案的实施风险
|
||||
|
||||
### 辩论流程
|
||||
|
||||
### 阶段 1: 初始立场表明
|
||||
|
||||
各角色从专业视角独立表达意见
|
||||
|
||||
- 提出推荐方案
|
||||
- 明示依据的标准·文档
|
||||
- 说明预期的风险·挑战
|
||||
- 定义成功指标
|
||||
|
||||
### 阶段 2: 相互辩论·反驳
|
||||
|
||||
角色间的交叉辩论
|
||||
|
||||
- 对其他角色提案的建设性反驳
|
||||
- 指出被忽视的视角
|
||||
- 明确权衡取舍
|
||||
- 提出替代方案
|
||||
|
||||
### 阶段 3: 妥协点探索
|
||||
|
||||
寻求可实施的解决方案
|
||||
|
||||
- 评估各视角的重要性
|
||||
- 考虑双赢解决方案
|
||||
- 分阶段实施方法
|
||||
- 考虑风险缓解策略
|
||||
|
||||
### 阶段 4: 综合结论
|
||||
|
||||
决定最终推荐事项
|
||||
|
||||
- 达成共识的解决方案
|
||||
- 实施路线图
|
||||
- 成功指标·测量方法
|
||||
- 未来的审查点
|
||||
|
||||
### 输出格式示例
|
||||
|
||||
### 2 角色辩论的情况
|
||||
|
||||
```text
|
||||
角色辩论: Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
议题: JWT 令牌的有效期设置
|
||||
|
||||
Security 角色的主张:
|
||||
"推荐 15 分钟的短期有效期"
|
||||
|
||||
依据:
|
||||
- 符合 OWASP JWT Security Cheat Sheet
|
||||
- 最小化令牌泄露时的损害时间窗口
|
||||
- 限制攻击者的可用时间
|
||||
|
||||
担忧事项:
|
||||
- 长期有效期使攻击风险呈指数级增长
|
||||
- 合规要求 (金融系统) 必须使用短期
|
||||
|
||||
成功指标:
|
||||
- 安全事件发生率 < 0.1%
|
||||
- 平均攻击检测时间 < 5 分钟
|
||||
|
||||
Performance 角色的反驳:
|
||||
"推荐 2 小时的有效期"
|
||||
|
||||
依据:
|
||||
- 参考 Google OAuth 2.0 Best Practices
|
||||
- 避免频繁重新认证导致的服务器负载增加
|
||||
- 最小化用户体验 (工作中断)
|
||||
|
||||
担忧事项:
|
||||
- 15 分钟间隔的重新认证使 API 负载增加 8 倍
|
||||
- 移动环境下连接中断频发
|
||||
|
||||
成功指标:
|
||||
- 保持 API 响应时间 < 200ms
|
||||
- 服务器 CPU 使用率 < 60%
|
||||
|
||||
相互辩论:
|
||||
Security → Performance:
|
||||
"安全漏洞的业务损失远大于服务器负载。
|
||||
例: Equifax 事件造成 7 亿美元损失"
|
||||
|
||||
Performance → Security:
|
||||
"通过刷新令牌机制可以两全其美。
|
||||
后台更新可确保安全而不损害 UX"
|
||||
|
||||
Security → Performance:
|
||||
"刷新令牌也是攻击目标。需要正确实施"
|
||||
|
||||
Performance → Security:
|
||||
"建议分阶段方法。普通操作 30 分钟，敏感操作 15 分钟"
|
||||
|
||||
妥协点探索:
|
||||
共同理解:
|
||||
- 需要兼顾用户体验和安全性
|
||||
- 根据风险级别灵活应对
|
||||
- 现实考虑实施·运维成本
|
||||
|
||||
双赢要素:
|
||||
- 利用刷新令牌机制
|
||||
- 逐步引入基于风险的认证
|
||||
- 通过自动登出功能补充
|
||||
|
||||
综合结论:
|
||||
"30 分钟有效期 + 刷新令牌 + 基于风险的认证"
|
||||
|
||||
实施详情:
|
||||
1. 访问令牌: 30 分钟有效期
|
||||
2. 刷新令牌: 7 天有效期
|
||||
3. 高风险操作: 15 分钟强制重新认证
|
||||
4. 无操作 30 分钟自动登出
|
||||
|
||||
分阶段实施:
|
||||
第 1-2 周: 基本的 30 分钟令牌实施
|
||||
第 3-4 周: 添加刷新令牌机制
|
||||
第 2 月: 引入基于风险的认证
|
||||
|
||||
成功指标:
|
||||
- 安全: 事件发生率 < 0.1%
|
||||
- 性能: API 负载增加率 < 20%
|
||||
- UX: 用户满意度 > 85%
|
||||
|
||||
未来审查:
|
||||
- 3 个月后: 评估实际攻击模式·负载情况
|
||||
- 6 个月后: 考虑迁移到更精细的基于风险的认证
|
||||
```
|
||||
|
||||
### 3 角色辩论的情况
|
||||
|
||||
```text
|
||||
角色辩论: Architect vs Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
议题: 微服务化的必要性
|
||||
|
||||
Architect 角色的主张:
|
||||
"推荐分阶段微服务化"
|
||||
依据: 明确领域边界、独立部署、技术选择自由度
|
||||
|
||||
Security 角色的担忧:
|
||||
"服务间通信的安全性复杂化"
|
||||
依据: API Gateway、mTLS、分布式认证的管理成本
|
||||
|
||||
Performance 角色的担忧:
|
||||
"网络通信导致延迟增加"
|
||||
依据: 内部 API 调用导致的 N+1 问题、分布式事务
|
||||
|
||||
3 方辩论:
|
||||
Architect → Security: "通过 API Gateway 集中管理可以控制"
|
||||
Security → Architect: "成为单点故障的风险"
|
||||
Performance → Architect: "服务拆分的粒度很重要"
|
||||
...(辩论继续)
|
||||
|
||||
综合结论:
|
||||
"领域驱动设计的分阶段拆分 + 安全优先设计"
|
||||
```
|
||||
|
||||
### 有效的辩论模式
|
||||
|
||||
### 技术选型
|
||||
|
||||
```bash
|
||||
/role-debate architect,performance
|
||||
"数据库选择: PostgreSQL vs MongoDB"
|
||||
|
||||
/role-debate frontend,mobile
|
||||
"UI 框架: React vs Vue"
|
||||
|
||||
/role-debate security,architect
|
||||
"认证方式: JWT vs Session Cookie"
|
||||
```
|
||||
|
||||
### 设计决策
|
||||
|
||||
```bash
|
||||
/role-debate security,frontend
|
||||
"用户认证的 UX 设计"
|
||||
|
||||
/role-debate performance,mobile
|
||||
"数据同步策略的优化"
|
||||
|
||||
/role-debate architect,qa
|
||||
"测试策略与架构设计"
|
||||
```
|
||||
|
||||
### 权衡问题
|
||||
|
||||
```bash
|
||||
/role-debate security,performance
|
||||
"加密级别 vs 处理速度"
|
||||
|
||||
/role-debate frontend,performance
|
||||
"丰富 UI vs 页面加载速度"
|
||||
|
||||
/role-debate mobile,security
|
||||
"便利性 vs 数据保护级别"
|
||||
```
|
||||
|
||||
### 角色别辩论特性
|
||||
|
||||
#### 🔒 Security 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 保守方法 (风险最小化)
|
||||
- 重视规则遵守 (谨慎偏离标准)
|
||||
- 最坏情况假设 (攻击者视角)
|
||||
- 重视长期影响 (安全作为技术债务)
|
||||
|
||||
典型论点:
|
||||
- "安全 vs 便利性" 的权衡
|
||||
- "合规要求的必达"
|
||||
- "攻击成本 vs 防御成本的比较"
|
||||
- "隐私保护的彻底性"
|
||||
|
||||
论据来源:
|
||||
- OWASP 指南
|
||||
- NIST 框架
|
||||
- 行业标准 (ISO 27001, SOC 2)
|
||||
- 实际攻击案例·统计
|
||||
|
||||
辩论优势:
|
||||
- 风险评估的精度
|
||||
- 监管要求的知识
|
||||
- 对攻击手法的理解
|
||||
|
||||
需注意的偏见:
|
||||
- 过度保守 (阻碍创新)
|
||||
- 对 UX 的考虑不足
|
||||
- 忽视实施成本
|
||||
```
|
||||
|
||||
#### ⚡ Performance 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 数据驱动决策 (基于测量)
|
||||
- 重视效率 (成本效益优化)
|
||||
- 用户体验优先 (重视体感速度)
|
||||
- 持续改进 (分阶段优化)
|
||||
|
||||
典型论点:
|
||||
- "性能 vs 安全"
|
||||
- "优化成本 vs 效果的投资回报"
|
||||
- "现在 vs 未来的可扩展性"
|
||||
- "用户体验 vs 系统效率"
|
||||
|
||||
论据来源:
|
||||
- Core Web Vitals 指标
|
||||
- 基准测试结果·统计
|
||||
- 对用户行为的影响数据
|
||||
- 行业性能标准
|
||||
|
||||
辩论优势:
|
||||
- 定量评估能力
|
||||
- 瓶颈识别
|
||||
- 优化手法的知识
|
||||
|
||||
需注意的偏见:
|
||||
- 忽视安全性
|
||||
- 对可维护性考虑不足
|
||||
- 过早优化
|
||||
```
|
||||
|
||||
#### 🏗️ Architect 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 重视长期视角 (考虑系统演进)
|
||||
- 追求平衡 (全局优化)
|
||||
- 分阶段变更 (风险管理)
|
||||
- 标准遵守 (优先经过验证的模式)
|
||||
|
||||
典型论点:
|
||||
- "短期效率 vs 长期可维护性"
|
||||
- "技术债务 vs 开发速度"
|
||||
- "微服务 vs 单体"
|
||||
- "新技术采用 vs 稳定性"
|
||||
|
||||
论据来源:
|
||||
- 架构模式集
|
||||
- 设计原则 (SOLID, DDD)
|
||||
- 大规模系统案例
|
||||
- 技术演进趋势
|
||||
|
||||
辩论优势:
|
||||
- 全局俯瞰能力
|
||||
- 设计模式的知识
|
||||
- 长期影响的预测
|
||||
|
||||
需注意的偏见:
|
||||
- 过度泛化
|
||||
- 对新技术的保守性
|
||||
- 对实施细节的理解不足
|
||||
```
|
||||
|
||||
#### 🎨 Frontend 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 用户中心设计 (UX 最优先)
|
||||
- 包容性方法 (考虑多样性)
|
||||
- 重视直观性 (最小化学习成本)
|
||||
- 可访问性标准 (WCAG 准拠)
|
||||
|
||||
典型论点:
|
||||
- "可用性 vs 安全性"
|
||||
- "设计统一 vs 平台优化"
|
||||
- "功能性 vs 简洁性"
|
||||
- "性能 vs 丰富体验"
|
||||
|
||||
论据来源:
|
||||
- UX 研究·可用性测试结果
|
||||
- 可访问性指南
|
||||
- 设计系统标准
|
||||
- 用户行为数据
|
||||
|
||||
辩论优势:
|
||||
- 代表用户视角
|
||||
- 设计原则的知识
|
||||
- 可访问性要求
|
||||
|
||||
需注意的偏见:
|
||||
- 对技术约束的理解不足
|
||||
- 忽视安全要求
|
||||
- 低估性能影响
|
||||
```
|
||||
|
||||
#### 📱 Mobile 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 平台特化 (考虑 iOS/Android 差异)
|
||||
- 场景适应 (移动中·单手操作)
|
||||
- 资源约束 (电池·内存·通信)
|
||||
- 商店准拠 (审核指南)
|
||||
|
||||
典型论点:
|
||||
- "原生 vs 跨平台"
|
||||
- "离线支持 vs 实时同步"
|
||||
- "电池效率 vs 功能性"
|
||||
- "平台统一 vs 优化"
|
||||
|
||||
论据来源:
|
||||
- iOS HIG / Android Material Design
|
||||
- App Store / Google Play 指南
|
||||
- 移动 UX 研究
|
||||
- 设备性能统计
|
||||
|
||||
辩论优势:
|
||||
- 理解移动特有约束
|
||||
- 平台差异的知识
|
||||
- 触摸界面设计
|
||||
|
||||
需注意的偏见:
|
||||
- 对 Web 平台的理解不足
|
||||
- 忽视服务器端约束
|
||||
- 对桌面环境的考虑不足
|
||||
```
|
||||
|
||||
#### 🔍 Analyzer 角色
|
||||
|
||||
```yaml
|
||||
辩论立场:
|
||||
- 重视证据 (数据优先)
|
||||
- 假设验证 (科学方法)
|
||||
- 结构思维 (系统思维)
|
||||
- 偏差排除 (追求客观性)
|
||||
|
||||
典型论点:
|
||||
- "相关性 vs 因果关系"
|
||||
- "对症疗法 vs 根本解决"
|
||||
- "假设 vs 事实的区别"
|
||||
- "短期症状 vs 结构问题"
|
||||
|
||||
论据来源:
|
||||
- 实测数据·日志分析
|
||||
- 统计方法·分析结果
|
||||
- 系统思维理论
|
||||
- 认知偏差研究
|
||||
|
||||
辩论优势:
|
||||
- 逻辑分析能力
|
||||
- 证据评估的客观性
|
||||
- 结构问题的发现
|
||||
|
||||
需注意的偏见:
|
||||
- 分析瘫痪 (行动力不足)
|
||||
- 完美主义 (忽视实用性)
|
||||
- 数据万能主义
|
||||
```
|
||||
|
||||
### 辩论进行模板
|
||||
|
||||
#### 阶段 1: 立场表明模板
|
||||
|
||||
```text
|
||||
【角色名】的推荐方案:
|
||||
"[具体提案]"
|
||||
|
||||
依据:
|
||||
- [官方文档·标准的引用]
|
||||
- [实证案例·数据]
|
||||
- [专业领域的原则]
|
||||
|
||||
预期效果:
|
||||
- [短期效果]
|
||||
- [中长期效果]
|
||||
|
||||
担忧·风险:
|
||||
- [实施风险]
|
||||
- [运维风险]
|
||||
- [对其他领域的影响]
|
||||
|
||||
成功指标:
|
||||
- [可测量指标 1]
|
||||
- [可测量指标 2]
|
||||
```
|
||||
|
||||
#### 阶段 2: 反驳模板
|
||||
|
||||
```text
|
||||
对 [目标角色] 的反驳:
|
||||
"[对目标提案的具体反驳]"
|
||||
|
||||
反驳依据:
|
||||
- [被忽视的视角]
|
||||
- [对立的证据·案例]
|
||||
- [专业领域的担忧]
|
||||
|
||||
替代方案:
|
||||
"[改进的提案]"
|
||||
|
||||
可妥协点:
|
||||
- [可接受的条件]
|
||||
- [分阶段实施的可能性]
|
||||
```
|
||||
|
||||
#### 阶段 3: 综合解决模板
|
||||
|
||||
```text
|
||||
综合解决方案:
|
||||
"[考虑各角色担忧的最终提案]"
|
||||
|
||||
对各角色的考虑:
|
||||
- [Security]: [如何满足安全要求]
|
||||
- [Performance]: [如何满足性能要求]
|
||||
- [其他]: [如何满足其他要求]
|
||||
|
||||
实施路线图:
|
||||
- 阶段 1 (立即): [紧急应对事项]
|
||||
- 阶段 2 (短期): [基本实施]
|
||||
- 阶段 3 (中期): [完整实施]
|
||||
|
||||
成功指标·测量方法:
|
||||
- [综合成功指标]
|
||||
- [测量方法·频率]
|
||||
- [审查时机]
|
||||
```
|
||||
|
||||
### 辩论质量检查清单
|
||||
|
||||
#### 论据质量
|
||||
|
||||
- [ ] 引用了官方文档·标准
|
||||
- [ ] 提供了具体案例·数据
|
||||
- [ ] 明确区分了推测和事实
|
||||
- [ ] 明示了信息来源
|
||||
|
||||
#### 辩论的建设性
|
||||
|
||||
- [ ] 准确理解了对方的提案
|
||||
- [ ] 逻辑而非情绪化的反驳
|
||||
- [ ] 也提出了替代方案
|
||||
- [ ] 探索了双赢的可能性
|
||||
|
||||
#### 可实施性
|
||||
|
||||
- [ ] 考虑了技术可实现性
|
||||
- [ ] 估算了实施成本·期间
|
||||
- [ ] 检讨了分阶段实施的可能性
|
||||
- [ ] 提出了风险缓解策略
|
||||
|
||||
#### 综合性
|
||||
|
||||
- [ ] 考虑了对其他领域的影响
|
||||
- [ ] 追求全局优化
|
||||
- [ ] 包含长期视角
|
||||
- [ ] 设置了可测量的成功指标
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 基于设计文档的辩论
|
||||
cat system-design.md
|
||||
/role-debate architect,security
|
||||
"辩论这个设计在安全方面的挑战"
|
||||
|
||||
# 基于问题的解决方案辩论
|
||||
cat performance-issues.md
|
||||
/role-debate performance,architect
|
||||
"辩论性能问题的根本解决方案"
|
||||
|
||||
# 基于需求的技术选型辩论
|
||||
/role-debate mobile,frontend
|
||||
"辩论 iOS·Android·Web 的统一 UI 策略"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 辩论可能需要时间 (复杂议题需要更长时间)
|
||||
- 3 个以上角色可能导致辩论发散
|
||||
- 最终决策请用户参考辩论结果做出
|
||||
- 紧急性高的问题请先考虑 single role 或 multi-role
|
||||
276
commands/role-help.md
Normal file
276
commands/role-help.md
Normal file
@@ -0,0 +1,276 @@
|
||||
## 角色帮助
|
||||
|
||||
迷茫时的角色选择指南和帮助系统。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role-help # 全面的角色选择指南
|
||||
/role-help <情况/问题> # 特定情况的推荐角色
|
||||
/role-help compare <角色 1>,<角色 2> # 角色比较
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 一般指导
|
||||
/role-help
|
||||
→ 显示可用角色及特点列表
|
||||
|
||||
# 情况别推荐
|
||||
/role-help "担心 API 的安全性"
|
||||
→ 推荐 security 角色及使用方法
|
||||
|
||||
# 角色比较
|
||||
/role-help compare frontend,mobile
|
||||
→ frontend 和 mobile 的区别与使用场景
|
||||
```
|
||||
|
||||
### 情况别角色选择指南
|
||||
|
||||
### 安全相关
|
||||
|
||||
```text
|
||||
这种情况使用 security 角色:
|
||||
✅ 登录·认证功能的实现
|
||||
✅ API 的安全漏洞检查
|
||||
✅ 数据加密·隐私保护
|
||||
✅ 安全合规性确认
|
||||
✅ 渗透测试·渗透测试
|
||||
|
||||
使用方法: /role security
|
||||
```
|
||||
|
||||
### 🏗️ 架构·设计
|
||||
|
||||
```text
|
||||
这种情况使用 architect 角色:
|
||||
✅ 系统整体设计评估
|
||||
✅ 微服务 vs 单体判断
|
||||
✅ 数据库设计·技术选型
|
||||
✅ 可扩展性·扩展性考虑
|
||||
✅ 技术债务评估·改进计划
|
||||
|
||||
使用方法: /role architect
|
||||
```
|
||||
|
||||
### ⚡ 性能问题
|
||||
|
||||
```text
|
||||
这种情况使用 performance 角色:
|
||||
✅ 应用程序运行缓慢
|
||||
✅ 数据库查询优化
|
||||
✅ Web 页面加载速度改进
|
||||
✅ 内存·CPU 使用量优化
|
||||
✅ 扩展·负载对策
|
||||
|
||||
使用方法: /role performance
|
||||
```
|
||||
|
||||
### 🔍 问题原因调查
|
||||
|
||||
```text
|
||||
这种情况使用 analyzer 角色:
|
||||
✅ Bug·错误的根本原因分析
|
||||
✅ 系统故障原因究明
|
||||
✅ 复杂问题的结构分析
|
||||
✅ 数据分析·统计调查
|
||||
✅ 为什么会发生这个问题的解明
|
||||
|
||||
使用方法: /role analyzer
|
||||
```
|
||||
|
||||
### 🎨 前端·UI/UX
|
||||
|
||||
```text
|
||||
这种情况使用 frontend 角色:
|
||||
✅ 用户界面改进
|
||||
✅ 可访问性支持
|
||||
✅ 响应式设计
|
||||
✅ 可用性·易用性提升
|
||||
✅ Web 前端技术全般
|
||||
|
||||
使用方法: /role frontend
|
||||
```
|
||||
|
||||
### 📱 移动应用开发
|
||||
|
||||
```text
|
||||
这种情况使用 mobile 角色:
|
||||
✅ iOS·Android 应用优化
|
||||
✅ 移动特有的 UX 设计
|
||||
✅ 触摸界面优化
|
||||
✅ 离线支持·同步功能
|
||||
✅ App Store·Google Play 支持
|
||||
|
||||
使用方法: /role mobile
|
||||
```
|
||||
|
||||
### 👀 代码审查·质量
|
||||
|
||||
```text
|
||||
这种情况使用 reviewer 角色:
|
||||
✅ 代码质量检查
|
||||
✅ 可读性·可维护性评估
|
||||
✅ 编码规范确认
|
||||
✅ 重构建议
|
||||
✅ PR·提交审查
|
||||
|
||||
使用方法: /role reviewer
|
||||
```
|
||||
|
||||
### 🧪 测试·质量保证
|
||||
|
||||
```text
|
||||
这种情况使用 qa 角色:
|
||||
✅ 测试策略制定
|
||||
✅ 测试覆盖率评估
|
||||
✅ 自动测试实施方针
|
||||
✅ Bug 预防·质量提升策略
|
||||
✅ CI/CD 中的测试自动化
|
||||
|
||||
使用方法: /role qa
|
||||
```
|
||||
|
||||
### 需要多个角色的情况
|
||||
|
||||
### 🔄 multi-role (并行分析)
|
||||
|
||||
```text
|
||||
这种情况使用 multi-role:
|
||||
✅ 需要多个专业视角的评估
|
||||
✅ 想制定综合改进计划
|
||||
✅ 想比较各领域的评估
|
||||
✅ 想整理矛盾·重复
|
||||
|
||||
例: /multi-role security,performance
|
||||
```
|
||||
|
||||
### 🗣️ role-debate (辩论)
|
||||
|
||||
```text
|
||||
这种情况使用 role-debate:
|
||||
✅ 专业领域间存在权衡
|
||||
✅ 技术选型有分歧
|
||||
✅ 想通过辩论决定设计方针
|
||||
✅ 想听取不同视角的辩论
|
||||
|
||||
例: /role-debate security,performance
|
||||
```
|
||||
|
||||
### 🤖 smart-review (自动建议)
|
||||
|
||||
```text
|
||||
这种情况使用 smart-review:
|
||||
✅ 不知道该使用哪个角色
|
||||
✅ 想了解当前情况的最佳方法
|
||||
✅ 想从多个选项中选择
|
||||
✅ 初学者不知如何判断
|
||||
|
||||
例: /smart-review
|
||||
```
|
||||
|
||||
### 角色比较表
|
||||
|
||||
### 安全系
|
||||
|
||||
| 角色 | 主要用途 | 擅长领域 | 不擅长领域 |
|
||||
| -------- | ------------- | ------------------ | ---------------- |
|
||||
| security | 漏洞·攻击对策 | 威胁分析、认证设计 | UX、性能 |
|
||||
| analyzer | 根本原因分析 | 逻辑分析、证据收集 | 预防策、未来规划 |
|
||||
|
||||
### 设计系
|
||||
|
||||
| 角色 | 主要用途 | 擅长领域 | 不擅长领域 |
|
||||
| --------- | -------- | ------------------ | ------------------ |
|
||||
| architect | 系统设计 | 长期视角、全局优化 | 详细实现、短期解决 |
|
||||
| reviewer | 代码质量 | 实现级别、可维护性 | 业务需求、UX |
|
||||
|
||||
### 性能系
|
||||
|
||||
| 角色 | 主要用途 | 擅长领域 | 不擅长领域 |
|
||||
| ----------- | ----------- | ------------ | ---------- |
|
||||
| performance | 高速化·优化 | 测量、瓶颈 | 安全性、UX |
|
||||
| qa | 质量保证 | 测试、自动化 | 设计、架构 |
|
||||
|
||||
### 用户体验系
|
||||
|
||||
| 角色 | 主要用途 | 擅长领域 | 不擅长领域 |
|
||||
| -------- | --------- | ---------------- | ------------- |
|
||||
| frontend | Web UI/UX | 浏览器、可访问性 | 服务器端、DB |
|
||||
| mobile | 移动 UX | 触摸、离线支持 | 服务器端、Web |
|
||||
|
||||
### 迷茫时的流程图
|
||||
|
||||
```text
|
||||
问题的性质是？
|
||||
├─ 安全相关 → security
|
||||
├─ 性能问题 → performance
|
||||
├─ Bug·故障调查 → analyzer
|
||||
├─ UI/UX 改进 → frontend or mobile
|
||||
├─ 设计·架构 → architect
|
||||
├─ 代码质量 → reviewer
|
||||
├─ 测试相关 → qa
|
||||
└─ 复合·复杂 → smart-review 建议
|
||||
|
||||
跨越多个领域？
|
||||
├─ 想要综合分析 → multi-role
|
||||
├─ 辩论·权衡 → role-debate
|
||||
└─ 不知如何判断 → smart-review
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
### Q: frontend 和 mobile 的区别是？
|
||||
|
||||
```text
|
||||
A:
|
||||
frontend: 以 Web 浏览器为中心、HTML/CSS/JavaScript
|
||||
mobile: 以移动应用为中心、iOS/Android 原生·React Native 等
|
||||
|
||||
两者都相关时推荐 multi-role frontend,mobile
|
||||
```
|
||||
|
||||
### Q: security 和 analyzer 的使用场景？
|
||||
|
||||
```text
|
||||
A:
|
||||
security: 攻击·威胁预防、安全设计
|
||||
analyzer: 已发生问题的原因分析、调查
|
||||
|
||||
安全事件调查使用 multi-role security,analyzer
|
||||
```
|
||||
|
||||
### Q: architect 和 performance 的区别是？
|
||||
|
||||
```text
|
||||
A:
|
||||
architect: 系统整体的长期设计、扩展性
|
||||
performance: 具体的速度·效率改进
|
||||
|
||||
大规模系统的性能设计使用 multi-role architect,performance
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 结合情况说明
|
||||
/role-help
|
||||
"React 应用页面加载慢，用户投诉很多"
|
||||
|
||||
# 结合文件内容
|
||||
cat problem-description.md
|
||||
/role-help
|
||||
"推荐适合这个问题的角色"
|
||||
|
||||
# 特定选项的迷茫
|
||||
/role-help compare security,performance
|
||||
"JWT 令牌有效期问题该用哪个角色？"
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 复杂问题多角色组合更有效
|
||||
- 紧急性高时使用 single role 快速应对
|
||||
- 迷茫时推荐使用 smart-review 获得自动建议
|
||||
- 最终判断请用户根据问题性质决定
|
||||
367
commands/role.md
Normal file
367
commands/role.md
Normal file
@@ -0,0 +1,367 @@
|
||||
## 角色
|
||||
|
||||
切换到特定角色 (role)，执行专业分析或工作。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role <角色名> [--agent|-a]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--agent` 或 `-a` : 作为子代理独立执行 (推荐用于大规模分析)
|
||||
- 使用此选项时，如果角色的 description 包含自动委托促进短语 (如 "use PROACTIVELY" 等)，将启用更积极的自动委托
|
||||
|
||||
### 可用角色
|
||||
|
||||
#### 专业分析角色 (Evidence-First 集成)
|
||||
|
||||
- `security` : 安全审计专家 (OWASP Top 10·威胁建模·Zero Trust 原则·CVE 对照)
|
||||
- `performance` : 性能优化专家 (Core Web Vitals·RAIL 模型·渐进式优化·ROI 分析)
|
||||
- `analyzer` : 根本原因分析专家 (5 Whys·系统思维·假设驱动·认知偏差对策)
|
||||
- `frontend` : 前端·UI/UX 专家 (WCAG 2.1·设计系统·用户中心设计)
|
||||
- `mobile` : 移动开发专家 (iOS HIG·Android Material Design·跨平台策略)
|
||||
- `backend` : 后端与服务器端专家 (RESTful 设计·可扩展性·数据库优化)
|
||||
|
||||
#### 开发支持角色
|
||||
|
||||
- `reviewer` : 代码审查专家 (可读性·可维护性·性能·重构建议)
|
||||
- `architect` : 系统架构师 (Evidence-First 设计·MECE 分析·演进式架构)
|
||||
- `qa` : 测试工程师 (测试覆盖率·E2E/集成/单元策略·自动化建议)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 切换到安全审计模式 (常规)
|
||||
/role security
|
||||
"检查这个项目的安全漏洞"
|
||||
|
||||
# 使用子代理执行安全审计 (大规模分析)
|
||||
/role security --agent
|
||||
"执行整个项目的安全审计"
|
||||
|
||||
# 切换到代码审查模式
|
||||
/role reviewer
|
||||
"审查最近的变更并指出改进点"
|
||||
|
||||
# 切换到性能优化模式
|
||||
/role performance
|
||||
"分析应用程序的瓶颈"
|
||||
|
||||
# 切换到根本原因分析模式
|
||||
/role analyzer
|
||||
"调查这个故障的根本原因"
|
||||
|
||||
# 切换到前端专业模式
|
||||
/role frontend
|
||||
"评估 UI/UX 的改进点"
|
||||
|
||||
# 切换到移动开发专业模式
|
||||
/role mobile
|
||||
"评估这个应用的移动优化"
|
||||
|
||||
# 返回常规模式
|
||||
/role default
|
||||
"返回常规 Claude"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 安全专注分析
|
||||
/role security
|
||||
cat app.js
|
||||
"详细分析这段代码的潜在安全风险"
|
||||
|
||||
# 架构视角评估
|
||||
/role architect
|
||||
ls -la src/
|
||||
"提出当前结构的问题和改进方案"
|
||||
|
||||
# 测试策略制定
|
||||
/role qa
|
||||
"为这个项目提出最佳测试策略"
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 多角色分析
|
||||
/role security
|
||||
"首先从安全角度检查"
|
||||
git diff HEAD~1
|
||||
|
||||
/role reviewer
|
||||
"接下来审查一般代码质量"
|
||||
|
||||
/role architect
|
||||
"最后从架构角度评估"
|
||||
|
||||
# 角色特定的输出格式
|
||||
/role security
|
||||
安全分析结果
|
||||
━━━━━━━━━━━━━━━━━━━━━
|
||||
漏洞: SQL 注入
|
||||
严重度: High
|
||||
位置: db.js:42
|
||||
修复建议: 使用参数化查询
|
||||
```
|
||||
|
||||
### Evidence-First 集成功能
|
||||
|
||||
#### 核心理念
|
||||
|
||||
各角色采用 **Evidence-First(基于证据)** 方法，基于 **经过验证的方法·官方指南·客观数据** 而非推测进行分析·建议。
|
||||
|
||||
#### 共同特征
|
||||
|
||||
- **官方文档准拠**: 优先参考各领域权威官方指南
|
||||
- **MECE 分析**: 无遗漏无重复的系统化问题分解
|
||||
- **多角度评估**: 技术·业务·运维·用户的多视角
|
||||
- **认知偏差对策**: 排除确认偏差等的机制
|
||||
- **辩论特性**: 角色特有的专业辩论立场
|
||||
|
||||
### 专业分析角色详情
|
||||
|
||||
#### security(安全审计专家)
|
||||
|
||||
**Evidence-Based 安全审计**
|
||||
|
||||
- 通过 OWASP Top 10·Testing Guide·SAMM 进行系统评估
|
||||
- 通过 CVE·NVD 数据库对照检查已知漏洞
|
||||
- 通过 STRIDE·Attack Tree·PASTA 进行威胁建模
|
||||
- 通过 Zero Trust 原则·最小权限进行设计评估
|
||||
|
||||
**专业报告格式**
|
||||
|
||||
```text
|
||||
Evidence-Based 安全审计结果
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
OWASP Top 10 合规度: XX% / CVE 对照: 完成
|
||||
威胁建模: STRIDE 分析完成
|
||||
```
|
||||
|
||||
#### performance(性能优化专家)
|
||||
|
||||
**Evidence-First 性能优化**
|
||||
|
||||
- Core Web Vitals(LCP·FID·CLS)·RAIL 模型准拠
|
||||
- Google PageSpeed Insights 建议实施
|
||||
- 渐进式优化流程 (测量→分析→优先级→实施)
|
||||
- 通过 ROI 分析进行投资回报的定量评估
|
||||
|
||||
**专业报告格式**
|
||||
|
||||
```text
|
||||
Evidence-First 性能分析
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Core Web Vitals: LCP[XXXms] FID[XXXms] CLS[X.XX]
|
||||
Performance Budget: XX% / ROI 分析: XX% 改进预测
|
||||
```
|
||||
|
||||
#### analyzer(根本原因分析专家)
|
||||
|
||||
**Evidence-First 根本原因分析**
|
||||
|
||||
- 5 Whys + α方法 (包含反证检讨)
|
||||
- 基于系统思维的结构分析 (Peter Senge 原则)
|
||||
- 认知偏差对策 (排除确认偏差·锚定效应等)
|
||||
- 彻底的假设驱动分析 (并行验证多个假设)
|
||||
|
||||
**专业报告格式**
|
||||
|
||||
```text
|
||||
Evidence-First 根本原因分析
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
分析可信度: 高 / 偏差对策: 已实施
|
||||
假设验证矩阵: XX% 确信度
|
||||
```
|
||||
|
||||
#### frontend(前端·UI/UX 专家)
|
||||
|
||||
**Evidence-First 前端开发**
|
||||
|
||||
- WCAG 2.1 可访问性准拠
|
||||
- Material Design·iOS HIG 官方指南准拠
|
||||
- 用户中心设计·设计系统标准应用
|
||||
- 通过 A/B 测试·用户行为分析进行验证
|
||||
|
||||
### 开发支持角色详情
|
||||
|
||||
#### reviewer(代码审查专家)
|
||||
|
||||
- 可读性·可维护性·性能的多角度评估
|
||||
- 编码规范遵守检查·重构建议
|
||||
- 安全性·可访问性的横向确认
|
||||
|
||||
#### architect(系统架构师)
|
||||
|
||||
- Evidence-First 设计原则·MECE 分析的分阶段思考
|
||||
- 演进式架构·多视角评估 (技术·业务·运维·用户)
|
||||
- 官方架构模式·最佳实践参考
|
||||
|
||||
#### qa(测试工程师)
|
||||
|
||||
- 测试覆盖率分析·E2E/集成/单元测试策略
|
||||
- 测试自动化建议·质量指标设计
|
||||
|
||||
#### mobile(移动开发专家)
|
||||
|
||||
- iOS HIG·Android Material Design 官方指南准拠
|
||||
- 跨平台策略·Touch-First 设计
|
||||
- 应用商店审核指南·移动特化 UX 优化
|
||||
|
||||
#### backend (后端与服务器端专家)
|
||||
|
||||
- RESTful/GraphQL API 设计、领域驱动设计、整洁架构
|
||||
- 可扩展性、容错能力、性能优化
|
||||
- 数据库优化、缓存策略、可靠性提升
|
||||
|
||||
### 角色特有的辩论特性
|
||||
|
||||
各角色根据专业领域具有独特的辩论立场·论据来源·优势。
|
||||
|
||||
#### security 角色的辩论特性
|
||||
|
||||
- **立场**: 保守方法·风险最小化优先·最坏情况假设
|
||||
- **论据**: OWASP 指南·NIST 框架·实际攻击案例
|
||||
- **优势**: 风险评估精度·深厚的监管要求知识·全面的攻击手法理解
|
||||
- **注意**: 过度保守·对 UX 的考虑不足·忽视实施成本
|
||||
|
||||
#### performance 角色的辩论特性
|
||||
|
||||
- **立场**: 数据驱动决策·效率重视·用户体验优先·持续改进
|
||||
- **论据**: Core Web Vitals·基准测试结果·用户行为数据·行业标准
|
||||
- **优势**: 定量评估能力·瓶颈识别精度·ROI 分析
|
||||
- **注意**: 忽视安全性·对可维护性考虑不足·过度重视测量
|
||||
|
||||
#### analyzer 角色的辩论特性
|
||||
|
||||
- **立场**: 证据重视·假设验证·结构思维·偏差排除
|
||||
- **论据**: 实测数据·统计方法·系统思维理论·认知偏差研究
|
||||
- **优势**: 逻辑分析能力·证据评估的客观性·结构问题的发现力
|
||||
- **注意**: 分析瘫痪·完美主义·数据万能主义·过度怀疑
|
||||
|
||||
#### frontend 角色的辩论特性
|
||||
|
||||
- **立场**: 用户中心·可访问性重视·设计原则准拠·体验价值优先
|
||||
- **论据**: UX 调研·可访问性标准·设计系统·可用性测试
|
||||
- **优势**: 用户视角·设计原则·可访问性·体验设计
|
||||
- **注意**: 忽视技术约束·对性能考虑不足·实施复杂性
|
||||
|
||||
### 多角色协作的效果
|
||||
|
||||
通过组合具有不同辩论特性的角色，可以实现平衡的分析：
|
||||
|
||||
#### 典型的协作模式
|
||||
|
||||
- **security + frontend**: 安全性与可用性的平衡
|
||||
- **performance + security**: 速度与安全的两立
|
||||
- **analyzer + architect**: 问题分析与结构设计的整合
|
||||
- **reviewer + qa**: 代码质量与测试策略的协作
|
||||
|
||||
## 高级角色功能
|
||||
|
||||
### 智能角色选择
|
||||
|
||||
- `/smart-review` : 通过项目分析自动建议角色
|
||||
- `/role-help` : 根据情况的最佳角色选择指南
|
||||
|
||||
### 多角色协作
|
||||
|
||||
- `/multi-role <角色 1>,<角色 2>` : 多角色同时分析
|
||||
- `/role-debate <角色 1>,<角色 2>` : 角色间辩论
|
||||
|
||||
### 使用示例
|
||||
|
||||
#### 自动角色建议
|
||||
|
||||
```bash
|
||||
/smart-review
|
||||
→ 分析当前情况并建议最佳角色
|
||||
|
||||
/smart-review src/auth/
|
||||
→ 从认证相关文件推荐 security 角色
|
||||
```
|
||||
|
||||
#### 多角色分析
|
||||
|
||||
```bash
|
||||
/multi-role security,performance
|
||||
"从多个视角评估这个 API"
|
||||
→ 从安全和性能两方面进行综合分析
|
||||
|
||||
/role-debate frontend,security
|
||||
"讨论双因素认证的 UX"
|
||||
→ 从可用性和安全性角度进行辩论
|
||||
```
|
||||
|
||||
#### 角色选择困惑时
|
||||
|
||||
```bash
|
||||
/role-help "API 慢且担心安全"
|
||||
→ 建议适当的方法 (multi-role 或 debate)
|
||||
|
||||
/role-help compare frontend,mobile
|
||||
→ 前端和移动角色的区别与使用分场
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 关于角色行为
|
||||
|
||||
- 切换角色时，Claude 的 **行为·优先事项·分析方法·报告格式** 会专门化
|
||||
- 各角色通过 **Evidence-First 方法** 优先应用官方指南·经过验证的方法
|
||||
- 使用 `default` 返回常规模式 (解除角色特化)
|
||||
- 角色仅在当前会话内有效
|
||||
|
||||
### 有效使用方法
|
||||
|
||||
- **简单问题**: 单一角色的专业分析足够
|
||||
- **复杂问题**: multi-role 或 role-debate 的多角度分析有效
|
||||
- **困惑时**: 请使用 smart-review 或 role-help
|
||||
- **持续改进**: 同一角色也会通过新证据·方法提高分析精度
|
||||
|
||||
### 子代理功能 (--agent 选项)
|
||||
|
||||
需要大规模分析或独立专业处理时，可使用 `--agent` 选项将角色作为子代理执行。
|
||||
|
||||
#### 优点
|
||||
|
||||
- **独立上下文**: 不干扰主对话
|
||||
- **并行执行**: 可同时执行多个分析
|
||||
- **专业特化**: 更深入的分析和详细报告
|
||||
- **促进自动委托**: 角色的 description 包含 "use PROACTIVELY" 或 "MUST BE USED" 时，启用更积极的自动委托
|
||||
|
||||
#### 推荐使用场景
|
||||
|
||||
```bash
|
||||
# 安全: OWASP 全项目检查、CVE 对照
|
||||
/role security --agent
|
||||
"全代码库的安全审计"
|
||||
|
||||
# 分析器: 大量日志的根本原因分析
|
||||
/role analyzer --agent
|
||||
"分析过去一周的错误日志"
|
||||
|
||||
# 审查员: 大规模 PR 的详细审查
|
||||
/role reviewer --agent
|
||||
"审查 PR #500 的 1000 行变更"
|
||||
```
|
||||
|
||||
#### 常规角色 vs 子代理
|
||||
|
||||
| 场景 | 推荐 | 命令 |
|
||||
| ---------- | -------- | ------------------------ |
|
||||
| 简单确认 | 常规角色 | `/role security` |
|
||||
| 大规模分析 | 子代理 | `/role security --agent` |
|
||||
| 交互式工作 | 常规角色 | `/role frontend` |
|
||||
| 独立审计 | 子代理 | `/role qa --agent` |
|
||||
|
||||
### 角色设置详情
|
||||
|
||||
- 各角色的详细设置·专业知识·辩论特性在 `.claude/agents/roles/` 目录内定义
|
||||
- 包含 Evidence-First 方法·认知偏差对策
|
||||
- 通过角色特有的触发短语自动启用特化模式
|
||||
- 实际角色文件由 200 行以上的专业内容构成
|
||||
103
commands/screenshot.md
Normal file
103
commands/screenshot.md
Normal file
@@ -0,0 +1,103 @@
|
||||
## 截图
|
||||
|
||||
在 macOS 上截取屏幕并分析图像。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/screenshot [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- 无 : 选择窗口 (Claude 会确认选项)
|
||||
- `--window` : 指定窗口截图
|
||||
- `--full` : 截取整个屏幕
|
||||
- `--crop` : 选择范围截图
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 截取窗口并分析
|
||||
/screenshot --window
|
||||
"分析截取的画面"
|
||||
|
||||
# 选择范围并分析
|
||||
/screenshot --crop
|
||||
"说明选中范围的内容"
|
||||
|
||||
# 全屏截图并分析
|
||||
/screenshot --full
|
||||
"分析整个屏幕的构成"
|
||||
```
|
||||
|
||||
### 与 Claude 的协作
|
||||
|
||||
```bash
|
||||
# 无特定问题 - 情况分析
|
||||
/screenshot --crop
|
||||
(Claude 会自动分析屏幕内容，说明元素和构成)
|
||||
|
||||
# UI/UX 问题分析
|
||||
/screenshot --window
|
||||
"提出这个 UI 的问题点和改进方案"
|
||||
|
||||
# 错误分析
|
||||
/screenshot --window
|
||||
"告诉我这个错误消息的原因和解决方法"
|
||||
|
||||
# 设计审查
|
||||
/screenshot --full
|
||||
"从 UX 角度评估这个设计"
|
||||
|
||||
# 代码分析
|
||||
/screenshot --crop
|
||||
"指出这段代码的问题"
|
||||
|
||||
# 数据可视化分析
|
||||
/screenshot --crop
|
||||
"分析从这个图表中可以读取的趋势"
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 从多个角度分析
|
||||
/screenshot --window
|
||||
"分析这个画面的以下方面：
|
||||
1. UI 的一致性
|
||||
2. 可访问性问题
|
||||
3. 改进建议"
|
||||
|
||||
# 为比较分析多次截图
|
||||
/screenshot --window
|
||||
# (保存 before 图像)
|
||||
# 进行更改
|
||||
/screenshot --window
|
||||
# (保存 after 图像)
|
||||
"比较 before 和 after 图像，分析变更点和改进效果"
|
||||
|
||||
# 聚焦特定元素
|
||||
/screenshot --crop
|
||||
"评估选中按钮的设计是否与其他元素协调"
|
||||
```
|
||||
|
||||
### 禁止事项
|
||||
|
||||
- **禁止在未截图的情况下说"已截图"**
|
||||
- **禁止尝试分析不存在的图像文件**
|
||||
- **`/screenshot` 命令不会实际执行截图**
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 未指定选项时，请提示以下选择：
|
||||
|
||||
```
|
||||
"请选择截图方式？
|
||||
1. 选择窗口 (--window) → screencapture -W
|
||||
2. 整个屏幕 (--full) → screencapture -x
|
||||
3. 选择范围 (--crop) → screencapture -i"
|
||||
```
|
||||
|
||||
- 请在用户执行 screencapture 命令后开始图像分析
|
||||
- 指定具体问题或观点可以进行更有针对性的分析
|
||||
66
commands/search-gemini.md
Normal file
66
commands/search-gemini.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## Gemini 网络搜索
|
||||
|
||||
使用 Gemini CLI 执行网络搜索以获取最新信息。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 通过 Gemini CLI 进行网络搜索 (必须)
|
||||
gemini --prompt "WebSearch: <搜索查询>"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 使用 Gemini CLI
|
||||
gemini --prompt "WebSearch: React 19 新功能"
|
||||
gemini --prompt "WebSearch: TypeError Cannot read property of undefined 解决方法"
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 文档搜索和摘要
|
||||
gemini --prompt "WebSearch: Next.js 14 App Router 官方文档"
|
||||
「请总结搜索结果并说明主要功能」
|
||||
|
||||
# 错误调查
|
||||
cat error.log
|
||||
gemini --prompt "WebSearch: [错误消息] 解决方法"
|
||||
「请从搜索结果中提出最合适的解决方法」
|
||||
|
||||
# 技术比较
|
||||
gemini --prompt "WebSearch: Rust vs Go performance benchmark 2024"
|
||||
「请从搜索结果总结性能差异」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 从多个来源收集信息
|
||||
gemini --prompt "WebSearch: GraphQL best practices 2024 multiple sources"
|
||||
「请从搜索结果整理多个可靠来源的信息」
|
||||
|
||||
# 调查时间序列变化
|
||||
gemini --prompt "WebSearch: JavaScript ES2015 ES2016 ES2017 ES2018 ES2019 ES2020 ES2021 ES2022 ES2023 ES2024 features"
|
||||
「请按时间顺序整理各版本的主要变更」
|
||||
|
||||
# 限定特定域名搜索
|
||||
gemini --prompt "WebSearch: site:github.com Rust WebAssembly projects stars:>1000"
|
||||
「请按星标数量从高到低列出 10 个项目」
|
||||
|
||||
# 最新的安全信息
|
||||
gemini --prompt "WebSearch: CVE-2024 Node.js vulnerabilities"
|
||||
「请总结发现的漏洞影响和对策」
|
||||
```
|
||||
|
||||
### 禁止事项
|
||||
|
||||
- **禁止使用 Claude 的内置 WebSearch 工具**
|
||||
- 需要网络搜索时，必须使用 `gemini --prompt "WebSearch: ..."`
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **如果 Gemini CLI 可用，必须使用 `gemini --prompt "WebSearch: ..."`**
|
||||
- 网络搜索结果不一定总是最新的
|
||||
- 重要信息建议通过官方文档或可靠来源确认
|
||||
1137
commands/semantic-commit.md
Normal file
1137
commands/semantic-commit.md
Normal file
File diff suppressed because it is too large
Load Diff
90
commands/sequential-thinking.md
Normal file
90
commands/sequential-thinking.md
Normal file
@@ -0,0 +1,90 @@
|
||||
## 顺序思考
|
||||
|
||||
通过动态且迭代的思考过程，逐步解决复杂问题。这是一种在思考过程中可以调整方向和重新审视的灵活方法。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 请求 Claude 进行分阶段思考
|
||||
「请用 sequential-thinking 考虑[课题]」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 算法设计
|
||||
「请用 sequential-thinking 设计高效的缓存策略」
|
||||
|
||||
# 问题解决
|
||||
「请用 sequential-thinking 解决数据库性能问题」
|
||||
|
||||
# 设计探讨
|
||||
「请用 sequential-thinking 探讨实时通知系统的设计」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 复杂的实现方针
|
||||
「请用 sequential-thinking 探讨认证系统的实现方针。考虑 OAuth2、JWT、会话管理」
|
||||
|
||||
# Bug 原因分析
|
||||
「请用 sequential-thinking 分析内存泄漏的原因。包含代码审查和性能分析结果」
|
||||
|
||||
# 重构策略
|
||||
cat src/complex_module.js
|
||||
「请用 sequential-thinking 制定此模块的重构策略」
|
||||
|
||||
# 技术选型
|
||||
「请用 sequential-thinking 分析前端框架的选择。考虑项目需求和约束」
|
||||
```
|
||||
|
||||
### 思考过程
|
||||
|
||||
1. **初始分析** - 基本理解和分解问题
|
||||
2. **假设生成** - 建立解决方案的假设
|
||||
3. **验证与修正** - 验证假设，必要时修正
|
||||
4. **分支与探索** - 探索多个解决路径
|
||||
5. **整合与结论** - 得出最优解
|
||||
|
||||
### 特点
|
||||
|
||||
- **动态调整** - 可在思考过程中转换方向
|
||||
- **假设验证** - 建立假设并验证的循环
|
||||
- **分支思考** - 同时探索多个思考路径
|
||||
- **逐步细化** - 逐步优化解决方案
|
||||
- **灵活性** - 基于新信息调整方针
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 复杂系统设计
|
||||
「请用 sequential-thinking 探讨电商网站的微服务设计。包括订单处理、库存管理、支付的协作」
|
||||
|
||||
# 安全设计
|
||||
「请用 sequential-thinking 探讨 API 安全设计。包括认证、授权、速率限制、审计日志」
|
||||
|
||||
# 性能优化
|
||||
「请用 sequential-thinking 探讨大规模数据处理的优化。考虑内存使用、处理速度、可扩展性」
|
||||
|
||||
# 依赖管理
|
||||
「请用 sequential-thinking 探讨 monorepo 的依赖管理策略。包括构建时间、部署、测试执行」
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
sequential-thinking 最适合需要逐步深化思考的复杂问题。对于简单问题或有明确答案的情况，请使用常规的提问形式。
|
||||
|
||||
### 执行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
「请用 sequential-thinking 探讨 GraphQL Schema 的设计」
|
||||
|
||||
# 预期行为
|
||||
# 1. 初始分析：分析 GraphQL Schema 的基本需求
|
||||
# 2. 假设生成：探讨多种设计模式
|
||||
# 3. 验证：验证各模式的优缺点
|
||||
# 4. 分支：必要时探索新方法
|
||||
# 5. 整合：提出最优的 Schema 设计
|
||||
```
|
||||
59
commands/show-plan.md
Normal file
59
commands/show-plan.md
Normal file
@@ -0,0 +1,59 @@
|
||||
## 显示计划
|
||||
|
||||
显示当前会话中正在执行或已执行的计划。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 确认当前计划
|
||||
/show-plan
|
||||
「显示正在执行的计划」
|
||||
|
||||
# 没有计划时
|
||||
/show-plan
|
||||
「当前会话没有计划」
|
||||
```
|
||||
|
||||
### 功能
|
||||
|
||||
- 检测由 exit_plan_mode 创建的计划
|
||||
- 搜索包含实施计划、实施内容、计划等关键词的标题
|
||||
- 格式化并显示计划内容
|
||||
- 没有计划时明确通知
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 实施过程中确认计划
|
||||
「我在实施什么来着？」
|
||||
/show-plan
|
||||
|
||||
# 执行多个任务时
|
||||
「让我再确认一下当前计划」
|
||||
/show-plan
|
||||
|
||||
# 计划执行后回顾
|
||||
「请显示刚才执行的计划内容」
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 检测模式
|
||||
|
||||
基于 exit_plan_mode 生成的计划格式，检测以下模式：
|
||||
|
||||
- 以 `##` 开头的标题 (包含计划、Plan)
|
||||
- `### 变更内容`
|
||||
- `### 实施内容`
|
||||
- `### 实施计划`
|
||||
- `### 1.` 等带编号的标题
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 仅显示当前会话内的计划 (不包括过去的会话)
|
||||
- 优先显示最新的计划
|
||||
174
commands/smart-review.md
Normal file
174
commands/smart-review.md
Normal file
@@ -0,0 +1,174 @@
|
||||
## 智能审查
|
||||
|
||||
分析当前情况，自动建议最佳角色和方法的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/smart-review # 分析当前目录
|
||||
/smart-review <文件/目录> # 分析特定对象
|
||||
```
|
||||
|
||||
### 自动判定逻辑
|
||||
|
||||
### 基于文件扩展名的判定
|
||||
|
||||
- `package.json`, `*.tsx`, `*.jsx`, `*.css`, `*.scss` → **frontend**
|
||||
- `Dockerfile`, `docker-compose.yml`, `*.yaml` → **architect**
|
||||
- `*.test.js`, `*.spec.ts`, `test/`, `__tests__/` → **qa**
|
||||
- `*.rs`, `Cargo.toml`, `performance/` → **performance**
|
||||
|
||||
### 安全相关文件检测
|
||||
|
||||
- `auth.js`, `security.yml`, `.env`, `config/auth/` → **security**
|
||||
- `login.tsx`, `signup.js`, `jwt.js` → **security + frontend**
|
||||
- `api/auth/`, `middleware/auth/` → **security + architect**
|
||||
|
||||
### 复合判定模式
|
||||
|
||||
- `mobile/` + `*.swift`, `*.kt`, `react-native/` → **mobile**
|
||||
- `webpack.config.js`, `vite.config.js`, `large-dataset/` → **performance**
|
||||
- `components/` + `responsive.css` → **frontend + mobile**
|
||||
- `api/` + `auth/` → **security + architect**
|
||||
|
||||
### 错误与问题分析
|
||||
|
||||
- 堆栈跟踪、`error.log`, `crash.log` → **analyzer**
|
||||
- `memory leak`, `high CPU`, `slow query` → **performance + analyzer**
|
||||
- `SQL injection`, `XSS`, `CSRF` → **security + analyzer**
|
||||
|
||||
### 建议模式
|
||||
|
||||
### 单一角色建议
|
||||
|
||||
```bash
|
||||
$ /smart-review src/auth/login.js
|
||||
→ 「检测到认证文件」
|
||||
→ 「推荐使用 security 角色分析」
|
||||
→ 「是否执行？ [y]es / [n]o / [m]ore options」
|
||||
```
|
||||
|
||||
### 多角色建议
|
||||
|
||||
```bash
|
||||
$ /smart-review src/mobile/components/
|
||||
→ 「📱🎨 检测到移动端 + 前端元素」
|
||||
→ 「推荐方法：」
|
||||
→ 「[1] mobile 角色单独」
|
||||
→ 「[2] frontend 角色单独」
|
||||
→ 「[3] multi-role mobile,frontend」
|
||||
→ 「[4] role-debate mobile,frontend」
|
||||
```
|
||||
|
||||
### 问题分析时的建议
|
||||
|
||||
```bash
|
||||
$ /smart-review error.log
|
||||
→ 「⚠️ 检测到错误日志」
|
||||
→ 「使用 analyzer 角色开始根本原因分析」
|
||||
→ 「[自动执行] /role analyzer」
|
||||
|
||||
$ /smart-review slow-api.log
|
||||
→ 「🐌 检测到性能问题」
|
||||
→ 「推荐：[1]/role performance [2]/role-debate performance,analyzer」
|
||||
```
|
||||
|
||||
### 复杂设计决策时的建议
|
||||
|
||||
```bash
|
||||
$ /smart-review architecture-design.md
|
||||
→ 「🏗️🔒⚡ 检测到架构 + 安全 + 性能元素」
|
||||
→ 「由于设计决策复杂，推荐讨论形式」
|
||||
→ 「[推荐] /role-debate architect,security,performance」
|
||||
→ 「[替代] /multi-role architect,security,performance」
|
||||
```
|
||||
|
||||
### 建议逻辑详情
|
||||
|
||||
### 优先级判定
|
||||
|
||||
1. **Security** - 认证、授权、加密相关最优先
|
||||
2. **Critical Errors** - 系统停机、数据丢失紧急处理
|
||||
3. **Architecture** - 大规模变更、技术选型慎重考虑
|
||||
4. **Performance** - 直接影响用户体验
|
||||
5. **Frontend/Mobile** - UI/UX 改进
|
||||
6. **QA** - 质量保证、测试相关
|
||||
|
||||
### 推荐讨论的条件
|
||||
|
||||
- 涉及 3 个以上角色时
|
||||
- 存在安全性与性能的权衡时
|
||||
- 包含架构大幅变更时
|
||||
- 同时影响移动端和 Web 时
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 分析当前目录
|
||||
/smart-review
|
||||
「请建议最佳的角色和方法」
|
||||
|
||||
# 分析特定文件
|
||||
/smart-review src/auth/login.js
|
||||
「请建议此文件的最佳审查方法」
|
||||
|
||||
# 分析错误日志
|
||||
/smart-review error.log
|
||||
「请建议解决此错误的最佳方法」
|
||||
```
|
||||
|
||||
### 实际示例
|
||||
|
||||
### 项目整体分析
|
||||
|
||||
```bash
|
||||
$ /smart-review
|
||||
→ 「📊 正在分析项目...」
|
||||
→ 「检测到 React + TypeScript 项目」
|
||||
→ 「确认包含认证功能 + API + 移动端支持」
|
||||
→ 「」
|
||||
→ 「💡 推荐工作流程：」
|
||||
→ 「1. security 检查认证系统」
|
||||
→ 「2. frontend 评估 UI/UX」
|
||||
→ 「3. mobile 确认移动端优化」
|
||||
→ 「4. architect 审查整体设计」
|
||||
→ 「」
|
||||
→ 「是否自动执行？ [y]es / [s]elect role / [c]ustom」
|
||||
```
|
||||
|
||||
### 特定问题分析
|
||||
|
||||
```bash
|
||||
$ /smart-review "JWT 有效期应该如何设置"
|
||||
→ 「🤔 检测到技术设计决策」
|
||||
→ 「这是需要多个专业视角的问题」
|
||||
→ 「」
|
||||
→ 「推荐方法：」
|
||||
→ 「/role-debate security,performance,frontend」
|
||||
→ 「原因：需要平衡安全性、性能和用户体验」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 结合文件内容分析
|
||||
cat src/auth/middleware.js
|
||||
/smart-review
|
||||
「请结合此文件内容从安全角度分析」
|
||||
|
||||
# 结合错误分析
|
||||
npm run build 2>&1 | tee build-error.log
|
||||
/smart-review build-error.log
|
||||
「请建议构建错误的解决方法」
|
||||
|
||||
# 设计咨询
|
||||
/smart-review
|
||||
「请讨论应该选择 React Native 还是 Progressive Web App」
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 建议仅供参考，最终决定由用户做出
|
||||
- 复杂问题推荐使用讨论形式 (role-debate)
|
||||
- 简单问题使用单一角色通常就足够
|
||||
- 安全相关问题必须推荐使用专业角色确认
|
||||
559
commands/spec.md
Normal file
559
commands/spec.md
Normal file
@@ -0,0 +1,559 @@
|
||||
## Spec
|
||||
|
||||
**「在编写代码之前赋予结构」** - 完全遵循 Kiro 的规格驱动开发
|
||||
|
||||
与传统代码生成工具不同，实现 Kiro 的规格驱动开发，重点是为开发的混沌赋予结构。从最少的需求输入，逐步展开到产品经理级别的详细规格和可实施的设计，**从原型到生产环境**保证一致的质量。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 请求 Claude 的 Spec Mode(最少需求输入)
|
||||
「创建[功能描述]的 spec」
|
||||
|
||||
# Kiro 式分阶段展开：
|
||||
# 1. 简单需求 → 自动生成详细用户故事
|
||||
# 2. 使用 EARS 记法的结构化需求描述
|
||||
# 3. 通过分阶段对话精细化规格
|
||||
# 4. 生成 3 个独立文件：
|
||||
# - requirements.md: EARS 记法的需求定义
|
||||
# - design.md: 包含 Mermaid 图、TypeScript 接口的设计
|
||||
# - tasks.md: 自动应用最佳实践的实施计划
|
||||
```
|
||||
|
||||
### 实证效果 (Kiro 实绩)
|
||||
|
||||
**2 天完成安全文件共享应用**
|
||||
|
||||
```bash
|
||||
「创建文件共享系统 (支持加密) 的 spec」
|
||||
→ 2 天完成生产级别的加密文件共享应用
|
||||
→ 自动应用安全最佳实践
|
||||
→ 无需额外提示
|
||||
```
|
||||
|
||||
**新手一晚开发游戏**
|
||||
|
||||
```bash
|
||||
「创建 2D 益智游戏的 spec」
|
||||
→ 游戏开发新手的开源开发者
|
||||
→ 一晚完成游戏创建
|
||||
→ 实现逻辑由 Kiro 处理，开发者专注创造性
|
||||
```
|
||||
|
||||
**周末从原型到生产**
|
||||
|
||||
```bash
|
||||
「创建电商网站商品管理系统的 spec」
|
||||
→ 一个周末从概念到可运行的原型
|
||||
→ 从原型到生产环境的一致质量
|
||||
→ 通过 spec-driven development 的结构化方法
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 新功能的 spec 创建 (最少输入)
|
||||
「商品评论系统
|
||||
- 星级评分功能
|
||||
- 评论发布
|
||||
- 图片上传」
|
||||
|
||||
# 系统功能的 spec 创建
|
||||
「用户认证
|
||||
- OAuth 支持
|
||||
- 多因素认证」
|
||||
|
||||
# API 功能的 spec 创建
|
||||
「支付系统 API
|
||||
- Stripe 集成
|
||||
- 重视安全性」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 复杂功能 spec
|
||||
「创建聊天功能的 spec。包括 WebSocket、实时通知、历史管理」
|
||||
|
||||
# 数据库关联功能 spec
|
||||
「创建电商网站库存管理功能的 spec。包括商品添加、库存更新、警报功能」
|
||||
|
||||
# 前端功能 spec
|
||||
「创建 React 仪表板的 spec。包括图表显示、筛选器、导出功能」
|
||||
|
||||
# 后端功能 spec
|
||||
「创建 RESTful API 的 spec。包括认证、验证、日志记录」
|
||||
```
|
||||
|
||||
### Spec Mode 的特点
|
||||
|
||||
**分阶段对话工作流**
|
||||
|
||||
- 完全再现 Kiro 的核心价值——分阶段讨论
|
||||
- 在各阶段与用户合作精细化规格
|
||||
- 经过疑问解决、选项讨论、批准流程后生成文件
|
||||
|
||||
**3 阶段的交互式展开**
|
||||
|
||||
- **Phase 1**: Requirements Discovery → 讨论 → 批准 → 生成 `requirements.md`
|
||||
- **Phase 2**: Design Exploration → 讨论 → 批准 → 生成 `design.md`
|
||||
- **Phase 3**: Implementation Planning → 讨论 → 批准 → 生成 `tasks.md`
|
||||
|
||||
**动态规格制定**
|
||||
|
||||
- 通过对话解决需求的模糊性
|
||||
- 提示和讨论技术选项
|
||||
- 说明权衡并确认判断
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 复杂系统功能
|
||||
「创建在线支付系统的 spec。包括 Stripe 集成、安全性、错误处理」
|
||||
|
||||
# 前端功能
|
||||
「创建 React 组件的 spec。包括状态管理、属性设计、测试」
|
||||
|
||||
# 后端功能
|
||||
「创建 GraphQL API 的 spec。包括 Schema 设计、解析器、认证」
|
||||
|
||||
# DevOps 功能
|
||||
「创建 CI/CD 管道的 spec。包括测试自动化、部署、监控」
|
||||
```
|
||||
|
||||
### 分阶段对话工作流 (Phase by Phase)
|
||||
|
||||
#### Phase 1: Requirements Discovery & Discussion
|
||||
|
||||
**1. 从最少输入自动扩展 (Kiro 式)**
|
||||
|
||||
```text
|
||||
用户：「用户管理系统
|
||||
- 登录功能
|
||||
- 个人资料编辑
|
||||
- 管理员权限」
|
||||
|
||||
Claude：「从需求生成详细用户故事。
|
||||
这个理解正确吗？
|
||||
|
||||
自动生成的用户故事：
|
||||
- 用户注册和认证功能 (支持 OAuth)
|
||||
- 个人资料管理功能 (头像、设置)
|
||||
- 权限管理功能 (RBAC)
|
||||
- 密码重置功能
|
||||
- 安全审计日志
|
||||
|
||||
已补充未明确的细节。还需要其他功能吗？」
|
||||
```
|
||||
|
||||
**2. 使用 EARS 记法的结构化需求描述**
|
||||
|
||||
```text
|
||||
Claude：「使用 Kiro 的 EARS 记法结构化需求：
|
||||
|
||||
EARS 记法需求定义：
|
||||
|
||||
WHEN 用户尝试登录时
|
||||
GIVEN 输入正确的邮箱和密码
|
||||
THEN 系统确认认证
|
||||
AND 成功时重定向到仪表板
|
||||
|
||||
WHILE 用户在个人资料编辑页面时
|
||||
THE SYSTEM SHALL 实时执行验证
|
||||
AND 预览显示更改内容
|
||||
|
||||
WHERE 需要管理员权限的功能
|
||||
IS 尝试访问时
|
||||
THE SYSTEM SHALL 确认权限级别
|
||||
AND 不足时拒绝访问」
|
||||
```
|
||||
|
||||
**3. 边缘情况和安全需求的自动补充**
|
||||
|
||||
```text
|
||||
Claude：「基于 Kiro 的最佳实践，还考虑了以下情况：
|
||||
|
||||
安全需求 (自动补充)：
|
||||
- 暴力攻击对策
|
||||
- 会话管理和超时
|
||||
- CSRF 保护和 XSS 对策
|
||||
- 密码强度要求
|
||||
|
||||
边缘情况 (自动检测)：
|
||||
- 同时登录限制
|
||||
- 账户锁定功能
|
||||
- 数据迁移时的一致性保证
|
||||
- 大量请求时的负载均衡
|
||||
|
||||
这些需求合适吗？」
|
||||
```
|
||||
|
||||
**5. Phase 1 完成和批准**
|
||||
|
||||
```text
|
||||
Claude：「Requirements Phase 已完成。
|
||||
可以生成 requirements.md 吗？」
|
||||
→ 「继续」→ 生成 requirements.md
|
||||
```
|
||||
|
||||
#### Phase 2: Design Exploration & Discussion
|
||||
|
||||
**1. 代码库分析 + 自动设计建议 (Kiro 式)**
|
||||
|
||||
```text
|
||||
Claude：「分析现有代码库，提出最佳架构：
|
||||
|
||||
代码库分析结果：
|
||||
- 认证：JWT + Express.js(v4.18.x)
|
||||
- 数据库：PostgreSQL(v14+)
|
||||
- 前端：React + TypeScript(v18+)
|
||||
- 现有模式：Repository 模式、Service 层分离
|
||||
|
||||
Kiro 推荐架构：
|
||||
- 符合 Clean Architecture
|
||||
- Domain-Driven Design 元素
|
||||
- 部分应用 CQRS 模式
|
||||
- 自动化的安全最佳实践
|
||||
|
||||
使用这个设计吗？」
|
||||
```
|
||||
|
||||
**2. 使用 Mermaid 图的可视化设计**
|
||||
|
||||
```text
|
||||
Claude：「自动生成系统设计的 Mermaid 图：
|
||||
|
||||
自动生成的架构图：
|
||||
|
||||
graph TB
|
||||
Client[React Client] --> API[Express API Gateway]
|
||||
API --> Auth[Auth Service]
|
||||
API --> User[User Service]
|
||||
API --> Profile[Profile Service]
|
||||
|
||||
Auth --> AuthDB[(Auth Database)]
|
||||
User --> UserDB[(User Database)]
|
||||
Profile --> ProfileDB[(Profile Database)]
|
||||
|
||||
Auth --> JWT[JWT Service]
|
||||
Auth --> OAuth[OAuth Provider]
|
||||
|
||||
还需要生成数据流图吗？」
|
||||
```
|
||||
|
||||
**3. TypeScript 接口自动生成**
|
||||
|
||||
```text
|
||||
Claude：「基于设计自动生成 TypeScript 接口：
|
||||
|
||||
自动生成的 TypeScript 接口：
|
||||
|
||||
// Domain entities
|
||||
interface User {
|
||||
readonly id: UserId;
|
||||
readonly email: Email;
|
||||
readonly profile: UserProfile;
|
||||
readonly auth: AuthSettings;
|
||||
readonly permissions: Permission[];
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
}
|
||||
|
||||
interface UserProfile {
|
||||
readonly displayName: string;
|
||||
readonly avatar: AvatarUrl;
|
||||
readonly preferences: UserPreferences;
|
||||
}
|
||||
|
||||
interface AuthSettings {
|
||||
readonly passwordHash: PasswordHash;
|
||||
readonly mfaEnabled: boolean;
|
||||
readonly lastLoginAt: Date;
|
||||
readonly failedAttempts: number;
|
||||
}
|
||||
|
||||
// Use cases
|
||||
interface UserRepository {
|
||||
findById(id: UserId): Promise<User | null>;
|
||||
findByEmail(email: Email): Promise<User | null>;
|
||||
save(user: User): Promise<void>;
|
||||
}
|
||||
|
||||
interface AuthenticationService {
|
||||
authenticate(credentials: LoginCredentials): Promise<AuthResult>;
|
||||
refreshToken(token: RefreshToken): Promise<AccessToken>;
|
||||
}
|
||||
|
||||
使用这个接口设计吗？」
|
||||
```
|
||||
|
||||
**4. Phase 2 完成和批准**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Design Phase 已完成。
|
||||
可以生成 design.md 吗？」
|
||||
→ 「继续」→ 生成 design.md
|
||||
|
||||
```
|
||||
|
||||
#### Phase 3: Implementation Planning & Discussion
|
||||
|
||||
**1. 最佳实践自动应用 (Kiro 式)**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「生成了自动应用 Kiro 最佳实践的实施计划：
|
||||
|
||||
自动生成的实施策略：
|
||||
|
||||
1. 安全第一开发
|
||||
- 自动集成 OWASP Top 10 对策
|
||||
- 自动实现加密和哈希
|
||||
- 自动生成安全测试
|
||||
|
||||
2. 强制清洁架构
|
||||
- 自动实现层分离
|
||||
- 自动应用依赖倒置
|
||||
- 强制可测试设计
|
||||
|
||||
3. 性能优化
|
||||
- 自动实现缓存策略
|
||||
- 数据库优化
|
||||
- 利用异步处理
|
||||
|
||||
使用这个方法吗？」
|
||||
|
||||
```
|
||||
|
||||
**2. 质量检查点自动设置**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自动设置各实施阶段的质量检查点：
|
||||
|
||||
自动质量保证流程：
|
||||
|
||||
Phase 3a: 后端实施
|
||||
|
||||
- [ ] 安全扫描 (SAST/DAST)
|
||||
- [ ] API 规范测试 (OpenAPI 合规)
|
||||
- [ ] 性能测试 (负载和响应)
|
||||
- [ ] 漏洞扫描 (依赖关系和 CVE)
|
||||
|
||||
Phase 3b: 前端实施
|
||||
|
||||
- [ ] 无障碍测试 (WCAG 2.1 AA)
|
||||
- [ ] 浏览器兼容性测试
|
||||
- [ ] 响应式设计验证
|
||||
- [ ] 安全头确认
|
||||
|
||||
Phase 3c: 集成和部署
|
||||
|
||||
- [ ] E2E 测试套件
|
||||
- [ ] CI/CD 管道配置
|
||||
- [ ] 监控和日志设置
|
||||
- [ ] 生产环境安全审计
|
||||
|
||||
全部自动执行。有额外的质量标准吗？」
|
||||
|
||||
```
|
||||
|
||||
**3. 依赖关系和风险缓解的自动分析**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自动分析实施顺序和风险缓解策略：
|
||||
|
||||
优化的实施顺序：
|
||||
|
||||
Week 1: 基础设施和安全基础
|
||||
|
||||
- 数据库设计和模式创建
|
||||
- 认证基础 (JWT + 会话管理)
|
||||
- 安全中间件实施
|
||||
- 基本 API 端点
|
||||
|
||||
Week 2: 核心功能实施
|
||||
|
||||
- 用户管理功能
|
||||
- 个人资料管理功能
|
||||
- 权限管理系统
|
||||
- 验证和错误处理
|
||||
|
||||
Week 3: 高级功能和优化
|
||||
|
||||
- 多因素认证实施
|
||||
- 审计日志功能
|
||||
- 性能优化
|
||||
- 前端集成
|
||||
|
||||
自动检测的风险缓解策略：
|
||||
|
||||
- 多因素认证：分阶段引入 (SMS→应用认证)
|
||||
- 会话管理：Redis 集群配置
|
||||
- 大量访问：速率限制 + CDN 利用
|
||||
- 数据一致性：加强事务管理
|
||||
|
||||
这个计划没有问题吗？」
|
||||
|
||||
```
|
||||
|
||||
**4. Phase 3 完成和批准**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Implementation Planning Phase 已完成。
|
||||
可以生成 tasks.md 吗？」
|
||||
→ 「继续」→ 生成 tasks.md
|
||||
|
||||
```
|
||||
|
||||
### Kiro 特有的功能
|
||||
|
||||
**EARS 记法 (Easy Approach to Requirements Syntax)**
|
||||
|
||||
```text
|
||||
# Kiro 标准的 EARS 记法模式
|
||||
|
||||
WHEN [情况・触发器]
|
||||
GIVEN [前提条件]
|
||||
THEN [系统行为]
|
||||
AND [额外行为]
|
||||
|
||||
WHILE [状态・流程]
|
||||
THE SYSTEM SHALL [必须行为]
|
||||
AND [相关行为]
|
||||
|
||||
WHERE [功能・组件]
|
||||
IS [条件・状态]
|
||||
THE SYSTEM SHALL [对应行为]
|
||||
```
|
||||
|
||||
**自动生成功能**
|
||||
|
||||
- **Mermaid 图**: 自动生成架构和数据流图
|
||||
- **TypeScript 接口**: 基于设计自动创建类型定义
|
||||
- **最佳实践**: 自动集成安全和性能对策
|
||||
- **质量检查点**: 自动设置分阶段质量标准
|
||||
|
||||
**hooks 联动**
|
||||
|
||||
- 文件保存时的自动质量检查
|
||||
- 自动应用代码标准
|
||||
- 自动执行安全扫描
|
||||
- 自动验证 OWASP Top 10 对策
|
||||
|
||||
**原型→生产质量保证**
|
||||
|
||||
- 通过结构化方法的一致设计
|
||||
- 强制安全第一开发
|
||||
- 自动应用可扩展架构
|
||||
- 集成持续质量管理
|
||||
|
||||
### 注意事项
|
||||
|
||||
**适用范围**
|
||||
|
||||
- Spec Mode 最适合功能实施
|
||||
- 简单修复或小规模更改使用常规实施形式
|
||||
- 推荐用于新功能开发或复杂功能改造
|
||||
|
||||
**质量保证**
|
||||
|
||||
- 明确各阶段的完成标准
|
||||
- 实施前的设计审查
|
||||
- 包括测试和无障碍的全面质量标准
|
||||
|
||||
**执行注意事项**
|
||||
|
||||
- 解决需求的模糊性后再进入设计阶段
|
||||
- 设计完成后生成实施任务
|
||||
- 重视各阶段的批准流程
|
||||
|
||||
### 触发短语和控制
|
||||
|
||||
#### 分阶段工作流控制
|
||||
|
||||
**开始触发器**
|
||||
|
||||
- 「创建[功能名]的 spec」
|
||||
- 「想用 spec 驱动开发[功能名]」
|
||||
- 「从规格书设计[功能名]」
|
||||
|
||||
**阶段进度控制**
|
||||
|
||||
- **「继续」**: 完成当前阶段并生成文件，进入下一阶段
|
||||
- **「修改」**: 在当前阶段内调整和改进内容
|
||||
- **「重做」**: 从头开始当前阶段
|
||||
- **「详细说明」**: 提供更详细的说明或选项
|
||||
- **「跳过」**: 跳过当前阶段进入下一个 (不推荐)
|
||||
|
||||
**文件生成时机**
|
||||
|
||||
```text
|
||||
Phase 1 完成 → 「继续」 → 生成 requirements.md
|
||||
Phase 2 完成 → 「继续」 → 生成 design.md
|
||||
Phase 3 完成 → 「继续」 → 生成 tasks.md
|
||||
```
|
||||
|
||||
### 执行示例 (分阶段流程)
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
用户：「创建用户管理系统的 spec」
|
||||
|
||||
# Phase 1: Requirements Discovery
|
||||
Claude: [开始需求确认和讨论]
|
||||
用户: [响应・讨论・修改]
|
||||
Claude: 「Requirements Phase 已完成。可以继续吗？」
|
||||
用户: 「继续」
|
||||
→ 生成 requirements.md
|
||||
|
||||
# Phase 2: Design Exploration
|
||||
Claude: [开始设计提案和讨论]
|
||||
用户: [技术选择・架构讨论]
|
||||
Claude: 「Design Phase 已完成。可以继续吗？」
|
||||
用户: 「继续」
|
||||
→ 生成 design.md
|
||||
|
||||
# Phase 3: Implementation Planning
|
||||
Claude: [开始实施计划讨论]
|
||||
用户: [优先级・风险・工时讨论]
|
||||
Claude: 「Implementation Phase 已完成。可以继续吗？」
|
||||
用户: 「继续」
|
||||
→ 生成 tasks.md
|
||||
|
||||
# 完成
|
||||
Claude: 「spec 驱动开发的准备已完成。可以开始实施。」
|
||||
```
|
||||
|
||||
### 与 /plan 的区别
|
||||
|
||||
| 特征 | /plan | /spec |
|
||||
| -------- | ---------------- | --------------------------------------------------- |
|
||||
| 对象 | 一般实施计划 | 功能规格驱动开发 |
|
||||
| 输出格式 | 单一计划文档 | 3 个独立文件 (requirements.md、design.md、tasks.md) |
|
||||
| 需求定义 | 基本需求整理 | 使用 EARS 记法的详细验收标准 |
|
||||
| 设计 | 以技术选型为中心 | 基于代码库分析 |
|
||||
| 实施 | 一般任务分解 | 考虑依赖关系的序列 |
|
||||
| 质量保证 | 基本测试策略 | 全面质量要求 (测试、无障碍、性能) |
|
||||
| 同步 | 静态计划 | 动态 spec 更新 |
|
||||
|
||||
### 推荐用例
|
||||
|
||||
**推荐使用 spec**
|
||||
|
||||
- 新功能开发
|
||||
- 复杂功能改造
|
||||
- API 设计
|
||||
- 数据库设计
|
||||
- UI/UX 实施
|
||||
|
||||
**推荐使用 plan**
|
||||
|
||||
- 系统整体设计
|
||||
- 基础设施构建
|
||||
- 重构
|
||||
- 技术选型
|
||||
- 架构变更
|
||||
186
commands/style-ai-writing.md
Normal file
186
commands/style-ai-writing.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## AI 写作检查
|
||||
|
||||
检测 AI 生成文本的机械化模式，并提供更自然的中文改进建议。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/ai-writing-check [选项]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- 无参数 : 分析当前文件或选中的文本
|
||||
- `--file <path>` : 分析特定文件
|
||||
- `--dir <path>` : 批量分析目录内的文件
|
||||
- `--severity <level>` : 检测级别 (all/high/medium)
|
||||
- `--fix` : 自动修复检测到的模式
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 检查文件的 AI 痕迹
|
||||
cat README.md
|
||||
/ai-writing-check
|
||||
「检查这个文档的 AI 痕迹并提供改进方案」
|
||||
|
||||
# 分析特定文件
|
||||
/ai-writing-check --file docs/guide.md
|
||||
「检测 AI 风格的表达并建议自然的表达方式」
|
||||
|
||||
# 扫描整个项目
|
||||
/ai-writing-check --dir . --severity high
|
||||
「只报告项目中重要的 AI 痕迹问题」
|
||||
```
|
||||
|
||||
### 检测模式
|
||||
|
||||
#### 1. 列表格式的机械化模式
|
||||
|
||||
```markdown
|
||||
检测示例：
|
||||
|
||||
- **重要**: 这是重要的项目
|
||||
- 已完成的项目 (带勾选标记)
|
||||
- 热门话题 (带火焰表情)
|
||||
- 准备启动 (带火箭表情)
|
||||
|
||||
改进示例：
|
||||
|
||||
- 重要项目：这是重要的项目
|
||||
- 已完成的项目
|
||||
- 热门话题
|
||||
- 准备启动
|
||||
```
|
||||
|
||||
#### 2. 夸张和炒作表达
|
||||
|
||||
```markdown
|
||||
检测示例：
|
||||
革命性的技术将改变行业。
|
||||
这完全解决了问题。
|
||||
像魔法一样运行。
|
||||
|
||||
改进示例：
|
||||
有效的技术将为行业带来变化。
|
||||
解决了许多问题。
|
||||
运行流畅。
|
||||
```
|
||||
|
||||
#### 3. 机械化的强调模式
|
||||
|
||||
```markdown
|
||||
检测示例：
|
||||
**想法**: 有新的提议 (带灯泡表情)
|
||||
**注意**: 重要警告事项 (带警告表情)
|
||||
|
||||
改进示例：
|
||||
想法：有新的提议
|
||||
注意事项：重要警告事项
|
||||
```
|
||||
|
||||
#### 4. 冗余的技术写作
|
||||
|
||||
```markdown
|
||||
检测示例：
|
||||
首先先进行设置。
|
||||
可以使用这个工具。
|
||||
大幅提升性能。
|
||||
|
||||
改进示例：
|
||||
首先进行设置。
|
||||
可以使用这个工具。
|
||||
性能提升 30%。
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 文档整体的 AI 痕迹分析
|
||||
cat article.md
|
||||
/ai-writing-check
|
||||
「从以下角度分析并提供改进方案：
|
||||
1. 机械化表达的检测
|
||||
2. 自然中文的修改建议
|
||||
3. 按优先级排列的改进列表」
|
||||
|
||||
# 聚焦特定模式
|
||||
/ai-writing-check --file blog.md
|
||||
「特别关注夸张表达和冗余表达并提供改进建议」
|
||||
|
||||
# 批量检查多个文件
|
||||
find . -name "*.md" -type f
|
||||
/ai-writing-check --dir docs/
|
||||
「分析整个文档的 AI 痕迹并创建摘要」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 改进前后对比
|
||||
/ai-writing-check --file draft.md
|
||||
「检测 AI 风格的表达，按以下格式展示：
|
||||
- 问题位置 (带行号)
|
||||
- 问题类型和原因
|
||||
- 具体改进方案
|
||||
- 改进效果」
|
||||
|
||||
# 自动修复模式
|
||||
/ai-writing-check --file report.md --fix
|
||||
「自动修复检测到的模式并报告结果」
|
||||
|
||||
# 项目 AI 痕迹报告
|
||||
/ai-writing-check --dir . --severity all
|
||||
「分析整个项目的 AI 痕迹：
|
||||
1. 统计信息 (按模式分类的检测数)
|
||||
2. 问题最多的文件 TOP 5
|
||||
3. 改进优先级矩阵
|
||||
4. 分阶段改进计划」
|
||||
```
|
||||
|
||||
### 高级用法
|
||||
|
||||
```bash
|
||||
# 应用自定义规则
|
||||
/ai-writing-check --file spec.md
|
||||
「作为技术规格书，使用以下额外标准检查：
|
||||
- 模糊表达 (适当的、根据需要)
|
||||
- 缺乏具体性 (高速 → 具体数值)
|
||||
- 术语使用不一致」
|
||||
|
||||
# CI/CD 集成检查
|
||||
/ai-writing-check --dir docs/ --severity high
|
||||
「以可在 GitHub Actions 执行的格式输出结果：
|
||||
- 错误数和文件名
|
||||
- 需要修复的行号
|
||||
- exit code 设置」
|
||||
|
||||
# 风格指南合规检查
|
||||
/ai-writing-check --file manual.md
|
||||
「基于公司风格指南进行额外检查：
|
||||
- 敬语使用 (统一礼貌用语)
|
||||
- 专业术语的适当使用
|
||||
- 对读者的考虑」
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- AI 痕迹的判定因上下文而异，建议仅作参考
|
||||
- 根据文档类型 (技术文档、博客、手册等) 调整标准
|
||||
- 不必接受所有建议，选择合适的即可
|
||||
- `--fix` 选项会自动修复检测到的模式
|
||||
|
||||
### 命令执行时的行为
|
||||
|
||||
执行 `/ai-writing-check` 命令时，Claude 会进行以下处理：
|
||||
|
||||
1. **模式检测**: 从指定的文件或文本中检测 AI 风格的模式
|
||||
2. **具体修改建议**: 为每个问题提供带行号的修改方案
|
||||
3. **--fix 模式**: 自动修复检测到的模式，并显示结果摘要
|
||||
4. **报告生成**: 提供检测数、改进优先级、修改前后对比
|
||||
|
||||
Claude 会读取实际文件内容，基于 textlint-rule-preset-ai-writing 的规则进行分析。
|
||||
|
||||
### 参考
|
||||
|
||||
此命令参考了 [textlint-rule-preset-ai-writing](https://github.com/textlint-ja/textlint-rule-preset-ai-writing) 的规则集创建。这是一个 textlint 规则预设，用于检测 AI 生成文本的机械化模式，促进更自然的表达。
|
||||
223
commands/task.md
Normal file
223
commands/task.md
Normal file
@@ -0,0 +1,223 @@
|
||||
## Task
|
||||
|
||||
启动专用代理，自主执行复杂的搜索、调查和分析任务。通过组合多个工具进行大规模信息处理，重视上下文效率。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 请求 Task
|
||||
「用 Task 调查[课题]」
|
||||
```
|
||||
|
||||
### Task 的特点
|
||||
|
||||
**自主执行**
|
||||
|
||||
- 自动组合多个工具执行
|
||||
- 分阶段信息收集和分析
|
||||
- 结果整合和结构化报告
|
||||
|
||||
**高效信息处理**
|
||||
|
||||
- 优化上下文消耗
|
||||
- 大规模文件搜索和解析
|
||||
- 从外部信息源收集数据
|
||||
|
||||
**质量保证**
|
||||
|
||||
- 信息源可靠性检查
|
||||
- 多角度验证
|
||||
- 自动补充缺失信息
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 复杂代码库调查
|
||||
「用 Task 调查这个功能在哪些文件中实现」
|
||||
|
||||
# 大规模文件搜索
|
||||
「用 Task 识别配置文件的不一致」
|
||||
|
||||
# 外部信息收集
|
||||
「用 Task 调查最新的 AI 技术趋势」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 复杂问题分析
|
||||
「用 Task 分析内存泄漏的原因。包括性能分析结果和日志」
|
||||
|
||||
# 依赖关系调查
|
||||
「用 Task 调查这个 npm 包的漏洞」
|
||||
|
||||
# 竞品分析
|
||||
「用 Task 调查竞品服务的 API 规格」
|
||||
|
||||
# 架构分析
|
||||
「用 Task 分析这个微服务的依赖关系」
|
||||
```
|
||||
|
||||
### 与其他命令的区别
|
||||
|
||||
#### Task vs 其他命令
|
||||
|
||||
| 命令 | 主要用途 | 执行方式 | 信息收集 |
|
||||
| ------------------- | ---------------- | ---------- | -------------- |
|
||||
| **Task** | 调查・分析・搜索 | 自主执行 | 多源 |
|
||||
| ultrathink | 深度思考・判断 | 结构化思考 | 以现有知识为主 |
|
||||
| sequential-thinking | 问题解决・设计 | 分阶段思考 | 按需 |
|
||||
| plan | 制定实施计划 | 批准流程 | 需求分析 |
|
||||
|
||||
#### 判断流程图
|
||||
|
||||
```text
|
||||
需要信息收集？
|
||||
├─ Yes → 多源・大规模？
|
||||
│ ├─ Yes → **Task**
|
||||
│ └─ No → 常规提问
|
||||
└─ No → 需要深度思考？
|
||||
├─ Yes → ultrathink/sequential-thinking
|
||||
└─ No → 常规提问
|
||||
```
|
||||
|
||||
### 有效场景・不需要的场景
|
||||
|
||||
**有效场景**
|
||||
|
||||
- 复杂代码库调查 (依赖关系、架构分析)
|
||||
- 大规模文件搜索 (特定实现模式、配置文件)
|
||||
- 外部信息收集和整理 (技术趋势、库调查)
|
||||
- 多源信息整合 (日志解析、指标分析)
|
||||
- 重复调查工作 (安全审计、技术债务调查)
|
||||
- 想避免上下文消耗的大规模分析
|
||||
|
||||
**不需要的场景**
|
||||
|
||||
- 简单问题或可用现有知识回答的内容
|
||||
- 短时间完成的单次工作
|
||||
- 需要交互式确认和咨询的工作
|
||||
- 实施或设计判断 (plan 或思考类命令更合适)
|
||||
|
||||
### 分类详细示例
|
||||
|
||||
#### 系统分析・调查
|
||||
|
||||
```bash
|
||||
# 复杂系统分析
|
||||
「用 Task 识别电商网站的瓶颈。调查数据库、API、前端的整体」
|
||||
|
||||
# 架构分析
|
||||
「用 Task 分析这个微服务的依赖关系。包括 API 通信和数据流」
|
||||
|
||||
# 技术债务调查
|
||||
「用 Task 分析遗留代码的技术债务。包括重构优先级」
|
||||
```
|
||||
|
||||
#### 安全・合规
|
||||
|
||||
```bash
|
||||
# 安全审计
|
||||
「用 Task 调查这个应用的漏洞。基于 OWASP Top 10」
|
||||
|
||||
# 许可证调查
|
||||
「用 Task 调查项目依赖的许可证问题」
|
||||
|
||||
# 配置文件审计
|
||||
「用 Task 识别安全配置的不一致。包括环境间的差异」
|
||||
```
|
||||
|
||||
#### 性能・优化
|
||||
|
||||
```bash
|
||||
# 性能分析
|
||||
「用 Task 识别应用中的慢查询。包括执行计划和优化方案」
|
||||
|
||||
# 资源使用调查
|
||||
「用 Task 调查内存泄漏的原因。包括性能分析结果和代码解析」
|
||||
|
||||
# 打包大小分析
|
||||
「用 Task 调查前端打包大小问题。包括优化建议」
|
||||
```
|
||||
|
||||
#### 外部信息收集
|
||||
|
||||
```bash
|
||||
# 技术趋势调查
|
||||
「用 Task 调查 2024 年的 JavaScript 框架动向」
|
||||
|
||||
# 竞品分析
|
||||
「用 Task 调查竞品服务的 API 规格。包括功能对比表」
|
||||
|
||||
# 库评估
|
||||
「用 Task 调查状态管理库的比较。包括性能和学习成本」
|
||||
```
|
||||
|
||||
### 执行流程和质量保证
|
||||
|
||||
#### Task 的执行流程
|
||||
|
||||
```text
|
||||
1. 初始分析
|
||||
├─ 分解课题和确定调查范围
|
||||
├─ 选择必要的工具和信息源
|
||||
└─ 制定执行计划
|
||||
|
||||
2. 信息收集
|
||||
├─ 文件搜索・代码解析
|
||||
├─ 收集外部信息
|
||||
└─ 数据结构化
|
||||
|
||||
3. 分析・整合
|
||||
├─ 分析收集信息的关联性
|
||||
├─ 识别模式和问题点
|
||||
└─ 验证假设
|
||||
|
||||
4. 报告・建议
|
||||
├─ 结构化结果
|
||||
├─ 创建改进建议
|
||||
└─ 提示下一步行动
|
||||
```
|
||||
|
||||
#### 质量保证
|
||||
|
||||
- **信息源可靠性检查**: 通过多源确认事实
|
||||
- **完整性确认**: 检查调查对象是否有遗漏
|
||||
- **一致性验证**: 确认矛盾信息的整合性
|
||||
- **实用性评估**: 评估建议的可行性和效果
|
||||
|
||||
### 错误处理和约束事项
|
||||
|
||||
#### 常见约束
|
||||
|
||||
- **外部 API 使用限制**: 速率限制和认证错误
|
||||
- **大文件处理限制**: 内存和超时约束
|
||||
- **访问权限问题**: 文件和目录的访问限制
|
||||
|
||||
#### 错误时的处理
|
||||
|
||||
- **部分结果报告**: 仅使用获取的信息进行分析
|
||||
- **替代方案建议**: 在约束下的替代调查方法
|
||||
- **分阶段执行**: 分割执行大规模任务
|
||||
|
||||
### 注意事项
|
||||
|
||||
- Task 最适合复杂且自主的调查和分析任务
|
||||
- 简单问题或需要即时回答时，请使用常规提问形式
|
||||
- 调查结果作为参考信息，重要判断必须验证
|
||||
- 收集外部信息时，注意信息的时效性和准确性
|
||||
|
||||
### 执行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
「用 Task 调查 GraphQL Schema 的问题」
|
||||
|
||||
# 预期行为
|
||||
# 1. 启动专用代理
|
||||
# 2. 搜索 GraphQL 相关文件
|
||||
# 3. 解析 Schema 定义
|
||||
# 4. 与最佳实践比较
|
||||
# 5. 识别问题并提出改进建议
|
||||
# 6. 创建结构化报告
|
||||
```
|
||||
181
commands/tech-debt.md
Normal file
181
commands/tech-debt.md
Normal file
@@ -0,0 +1,181 @@
|
||||
## 技术债务
|
||||
|
||||
分析项目的技术债务，创建按优先级排序的改进计划。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 确认项目结构并分析技术债务
|
||||
ls -la
|
||||
「分析这个项目的技术债务并创建改进计划」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 分析 TODO/FIXME 注释
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
|
||||
「按优先级整理这些 TODO 注释并制定改进计划」
|
||||
|
||||
# 确认项目依赖关系
|
||||
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
|
||||
「分析项目的依赖关系，识别过时的依赖和风险」
|
||||
|
||||
# 检测大文件和复杂函数
|
||||
find . -type f -not -path "*/\.*" -not -path "*/node_modules/*" -exec wc -l {} + | sort -rn | head -10
|
||||
「识别过大的文件和复杂的结构，提出改进方案」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的技术债务分析
|
||||
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
|
||||
「从以下角度分析这个项目的技术债务：
|
||||
1. 代码质量 (复杂度、重复、可维护性)
|
||||
2. 依赖关系健康度
|
||||
3. 安全风险
|
||||
4. 性能问题
|
||||
5. 测试覆盖不足」
|
||||
|
||||
# 架构债务分析
|
||||
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
|
||||
「识别架构层面的技术债务，提出重构计划」
|
||||
|
||||
# 按优先级排序的改进计划
|
||||
「按以下标准评估技术债务并以表格形式展示：
|
||||
- 影响度 (高/中/低)
|
||||
- 修复成本 (时间)
|
||||
- 业务风险
|
||||
- 改进效果
|
||||
- 推荐实施时期」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 自动检测项目类型并分析
|
||||
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
|
||||
「基于检测到的项目类型，分析以下内容：
|
||||
1. 语言和框架特定的技术债务
|
||||
2. 偏离最佳实践的情况
|
||||
3. 现代化机会
|
||||
4. 分阶段改进策略」
|
||||
|
||||
# 代码质量指标分析
|
||||
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
|
||||
「分析项目的代码质量，展示以下指标：
|
||||
- 循环复杂度高的函数
|
||||
- 重复代码检测
|
||||
- 过长的文件/函数
|
||||
- 缺乏适当的错误处理」
|
||||
|
||||
# 安全债务检测
|
||||
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
|
||||
「检测安全相关的技术债务，提出修复优先级和对策」
|
||||
|
||||
# 测试不足分析
|
||||
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
|
||||
「分析测试覆盖的技术债务，提出测试策略」
|
||||
```
|
||||
|
||||
### 项目健康度仪表盘
|
||||
|
||||
```text
|
||||
项目健康度评分：72/100
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 分类评分
|
||||
├─ 依赖关系新鲜度：████████░░ 82%(最新：45/55)
|
||||
├─ 文档完整度：███░░░░░░░ 35%(缺少 README、API 文档)
|
||||
├─ 测试覆盖率：██████░░░░ 65%(目标：80%)
|
||||
├─ 安全性：███████░░░ 78%(漏洞：2 个中等风险)
|
||||
├─ 架构：██████░░░░ 60%(循环依赖：3 处)
|
||||
└─ 代码质量：███████░░░ 70%(高复杂度：12 个文件)
|
||||
|
||||
📈 趋势 (过去 30 天)
|
||||
├─ 总体评分：68 → 72 (+4) ↗️
|
||||
├─ 改进项目：12 项 ✅
|
||||
├─ 新增债务：3 项 ⚠️
|
||||
├─ 已解决债务：8 项 🎉
|
||||
└─ 改进速度：+0.13/天
|
||||
|
||||
⏱️ 债务的时间影响
|
||||
├─ 开发速度降低：-20%(新功能开发需要正常 1.25 倍时间)
|
||||
├─ Bug 修复时间增加：+15%(平均修复时间 2h → 2.3h)
|
||||
├─ 代码审查开销：+30%(复杂度导致理解时间增加)
|
||||
├─ 入职延迟：+50%(新成员理解所需时间)
|
||||
└─ 累积延迟时间：相当于每周 40 小时
|
||||
|
||||
🎯 改进预期效果 (基于时间)
|
||||
├─ 即时效果：开发速度 +10%(1 周后)
|
||||
├─ 短期效果：Bug 率 -25%(1 个月后)
|
||||
├─ 中期效果：开发速度 +30%(3 个月后)
|
||||
├─ 长期效果：维护时间 -50%(6 个月后)
|
||||
└─ ROI：投资 40 小时 → 回收 120 小时 (3 个月)
|
||||
```
|
||||
|
||||
### 优先级矩阵
|
||||
|
||||
| 优先级 | 开发影响 | 修复成本 | 时间节省效果 | 投资效率 | 响应期限 |
|
||||
| ----------------- | -------- | -------- | ------------ | ------------------- | -------- |
|
||||
| **[P0] 立即修复** | 高 | 低 | > 5 倍 | 投资 1h → 节省 5h+ | 立即 |
|
||||
| **[P1] 本周内** | 高 | 中 | 2-5 倍 | 投资 1h → 节省 2-5h | 1 周内 |
|
||||
| **[P2] 本月内** | 低 | 高 | 1-2 倍 | 投资 1h → 节省 1-2h | 1 个月内 |
|
||||
| **[P3] 本季度内** | 低 | 低 | < 1 倍 | 投资=节省时间 | 3 个月内 |
|
||||
|
||||
### 债务类型评估标准
|
||||
|
||||
| 债务类型 | 检测方法 | 开发影响 | 修复时间 |
|
||||
| ---------------- | --------------------- | ------------------------ | -------- |
|
||||
| **架构债务** | 循环依赖、紧耦合 | 变更影响范围大、测试困难 | 40-80h |
|
||||
| **安全债务** | CVE 扫描、OWASP | 漏洞风险、合规问题 | 8-40h |
|
||||
| **性能债务** | N+1 查询、内存泄漏 | 响应时间增加、资源消耗 | 16-40h |
|
||||
| **测试债务** | 覆盖率 < 60% | Bug 检测延迟、质量不稳定 | 20-60h |
|
||||
| **文档债务** | 缺少 README、API 文档 | 入职时间增加 | 8-24h |
|
||||
| **依赖债务** | 2 年以上未更新 | 安全风险、兼容性问题 | 4-16h |
|
||||
| **代码质量债务** | 复杂度 > 10 | 理解/修改时间增加 | 2-8h |
|
||||
|
||||
### 技术债务影响度计算
|
||||
|
||||
```text
|
||||
影响度 = Σ(各要素权重 × 测量值)
|
||||
|
||||
📊 可测量的影响指标：
|
||||
├─ 开发速度影响
|
||||
│ ├─ 代码理解时间：+X%(与复杂度成正比)
|
||||
│ ├─ 变更时影响范围：Y 个文件 (通过耦合度测量)
|
||||
│ └─ 测试执行时间：Z 分钟 (CI/CD 流水线)
|
||||
│
|
||||
├─ 质量影响
|
||||
│ ├─ Bug 发生率：复杂度每 10 分增加 +25%
|
||||
│ ├─ 代码审查时间：代码行数 × 复杂度系数
|
||||
│ └─ 测试不足风险：覆盖率 < 60% 时高风险
|
||||
│
|
||||
└─ 团队效率影响
|
||||
├─ 入职时间：缺少文档时增加 +100%
|
||||
├─ 知识孤岛：单一贡献者比例 >80% 时需要注意
|
||||
└─ 代码重复修复位置：重复率 × 变更频率
|
||||
```
|
||||
|
||||
### 基于时间的 ROI 计算
|
||||
|
||||
```text
|
||||
ROI = (节省时间 - 投资时间) ÷ 投资时间 × 100
|
||||
|
||||
示例：解决循环依赖
|
||||
├─ 投资时间：16 小时 (重构)
|
||||
├─ 每月节省：
|
||||
│ ├─ 编译时间：-10 分钟/天 × 20 天 = 200 分钟
|
||||
│ ├─ 调试时间：-2 小时/周 × 4 周 = 8 小时
|
||||
│ └─ 新功能开发：-30% 时间缩短 = 12 小时
|
||||
├─ 每月节省时间：23.3 小时
|
||||
└─ 3 个月 ROI：(70 - 16) ÷ 16 × 100 = 337%
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 自动检测项目的语言和框架，进行相应的分析
|
||||
- 健康度评分采用 0-100 分制：70 分以上健康，50 分以下需要改进
|
||||
- 计算具体的时间成本和改进效果，支持基于数据的决策制定
|
||||
- 如需货币换算，请单独指定团队平均时薪或项目特定系数
|
||||
242
commands/token-efficient.md
Normal file
242
commands/token-efficient.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Token 效率模式
|
||||
|
||||
AI 响应压缩模式，可减少上下文使用量 30-50%。
|
||||
|
||||
## 概述
|
||||
|
||||
Token 效率模式通过视觉符号和缩写系统来压缩 Claude 的响应。
|
||||
**生成代码的质量或内容不会发生任何改变**。仅改变的是说明方式。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
# 启用模式
|
||||
「使用 Token 效率模式响应」
|
||||
「使用 --uc 模式」
|
||||
「使用简洁模式」
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
### 1. 符号体系
|
||||
|
||||
#### 逻辑与流程
|
||||
|
||||
| 符号 | 含义 | 使用示例 |
|
||||
| ---- | ------------ | ------------------------------ |
|
||||
| → | 导致、引起 | `auth.js:45 → 🛡️ 安全风险` |
|
||||
| ⇒ | 转换为 | `input ⇒ validated_output` |
|
||||
| ← | 回滚、撤回 | `migration ← rollback` |
|
||||
| ⇄ | 双向 | `sync ⇄ remote` |
|
||||
| & | 并且、结合 | `🛡️ security & ⚡ performance` |
|
||||
| \| | 或者、分隔 | `react\|vue\|angular` |
|
||||
| : | 定义、指定 | `scope: file\|module` |
|
||||
| » | 接下来、序列 | `build » test » deploy` |
|
||||
| ∴ | 因此 | `tests ❌ ∴ code broken` |
|
||||
| ∵ | 因为 | `slow ∵ O(n²) algorithm` |
|
||||
|
||||
#### 状态与进度
|
||||
|
||||
| 符号 | 含义 | 用途 |
|
||||
| ---- | ---------- | ------------ |
|
||||
| ✅ | 完成、成功 | 任务正常结束 |
|
||||
| ❌ | 失败、错误 | 需要立即处理 |
|
||||
| ⚠️ | 警告 | 建议审查 |
|
||||
| 🔄 | 进行中 | 当前活跃状态 |
|
||||
| ⏳ | 等待中 | 稍后执行 |
|
||||
| 🚨 | 紧急、重要 | 高优先级 |
|
||||
|
||||
#### 技术领域
|
||||
|
||||
| 符号 | 领域 | 用途 |
|
||||
| ---- | ------ | ------------ |
|
||||
| ⚡ | 性能 | 速度、优化 |
|
||||
| 🔍 | 分析 | 搜索、调查 |
|
||||
| 🔧 | 配置 | 设置、工具 |
|
||||
| 🛡️ | 安全 | 保护、安全性 |
|
||||
| 📦 | 部署 | 包、打包 |
|
||||
| 🎨 | 设计 | UI、前端 |
|
||||
| 🏗️ | 架构 | 系统结构 |
|
||||
| 🗄️ | 数据库 | 数据持久化 |
|
||||
| ⚙️ | 后端 | 服务器处理 |
|
||||
| 🧪 | 测试 | 质量保证 |
|
||||
|
||||
### 2. 缩写系统
|
||||
|
||||
#### 系统与架构
|
||||
|
||||
- `cfg` → configuration(配置)
|
||||
- `impl` → implementation(实现)
|
||||
- `arch` → architecture(架构)
|
||||
- `perf` → performance(性能)
|
||||
- `ops` → operations(运维)
|
||||
- `env` → environment(环境)
|
||||
|
||||
#### 开发流程
|
||||
|
||||
- `req` → requirements(需求)
|
||||
- `deps` → dependencies(依赖关系)
|
||||
- `val` → validation(验证)
|
||||
- `auth` → authentication(认证)
|
||||
- `docs` → documentation(文档)
|
||||
- `std` → standards(标准)
|
||||
|
||||
#### 质量与分析
|
||||
|
||||
- `qual` → quality(质量)
|
||||
- `sec` → security(安全)
|
||||
- `err` → error(错误)
|
||||
- `rec` → recovery(恢复)
|
||||
- `sev` → severity(严重程度)
|
||||
- `opt` → optimization(优化)
|
||||
|
||||
## 实例对比
|
||||
|
||||
### 例 1: 错误报告
|
||||
|
||||
**正常模式 (49 字符)**
|
||||
|
||||
```text
|
||||
在用户验证函数的第 45 行发现了安全漏洞。
|
||||
```
|
||||
|
||||
**Token 高效模式 (32 字符)**
|
||||
|
||||
```text
|
||||
auth.js:45 → 🛡️ sec vuln in user val()
|
||||
```
|
||||
|
||||
### 例 2: 构建状态
|
||||
|
||||
**正常模式 (41 字符)**
|
||||
|
||||
```text
|
||||
构建过程已完成。正在运行测试，然后进行部署。
|
||||
```
|
||||
|
||||
**Token 高效模式 (29 字符)**
|
||||
|
||||
```text
|
||||
build ✅ » test 🔄 » deploy ⏳
|
||||
```
|
||||
|
||||
### 例 3: 性能分析
|
||||
|
||||
**正常模式 (65 字符)**
|
||||
|
||||
```text
|
||||
性能分析结果显示，算法的 O(n²) 复杂度导致处理速度缓慢。
|
||||
```
|
||||
|
||||
**Token 高效模式 (37 字符)**
|
||||
|
||||
```text
|
||||
⚡ perf: slow ∵ O(n²) → optimize to O(n)
|
||||
```
|
||||
|
||||
## 适用场景
|
||||
|
||||
### ✅ 有效场合
|
||||
|
||||
- **长时间调试会话**: 保持历史记录的同时高效处理
|
||||
- **大规模代码审查**: 简洁分析大量文件
|
||||
- **CI/CD 监控**: 实时状态更新
|
||||
- **项目进度报告**: 多任务状态一览
|
||||
- **错误跟踪**: 可视化问题链
|
||||
|
||||
### ❌ 应避免的场合
|
||||
|
||||
- 向初学者说明
|
||||
- 详细文档编写
|
||||
- 初次需求定义
|
||||
- 与非技术人员沟通
|
||||
|
||||
## 实现示例
|
||||
|
||||
### 调试会话
|
||||
|
||||
```text
|
||||
[14:23] breakpoint → vars: {user: null, token: expired}
|
||||
[14:24] step → auth.validate() ❌
|
||||
[14:25] check → token.exp < Date.now() ∴ expired
|
||||
[14:26] fix → refresh() → ✅
|
||||
[14:27] continue → main flow 🔄
|
||||
```
|
||||
|
||||
### 文件分析结果
|
||||
|
||||
```text
|
||||
/src/auth/: 🛡️ issues × 3
|
||||
/src/api/: ⚡ bottleneck in handler()
|
||||
/src/db/: ✅ clean
|
||||
/src/utils/: ⚠️ deprecated methods
|
||||
/tests/: 🧪 coverage 78%
|
||||
```
|
||||
|
||||
### 项目状态
|
||||
|
||||
```text
|
||||
Frontend: 🎨 ✅ 100%
|
||||
Backend: ⚙️ 🔄 75%
|
||||
Database: 🗄️ ✅ migrated
|
||||
Tests: 🧪 ⚠️ 68% (target: 80%)
|
||||
Deploy: 📦 ⏳ scheduled
|
||||
Security: 🛡️ 🚨 1 critical
|
||||
```
|
||||
|
||||
## 配置选项
|
||||
|
||||
```javascript
|
||||
// 压缩级别
|
||||
--uc; // Ultra Compressed: 最大压缩
|
||||
--mc; // Moderate Compressed: 中等压缩
|
||||
--lc; // Light Compressed: 轻度压缩
|
||||
|
||||
// 领域专门化
|
||||
--dev; // 开发专用压缩
|
||||
--ops; // 运维专用压缩
|
||||
--sec; // 安全专用压缩
|
||||
```
|
||||
|
||||
## 优势
|
||||
|
||||
1. **上下文节约**: 减少 30-50% token 消耗
|
||||
2. **视觉理解**: 符号直观把握
|
||||
3. **信息密度提高**: 相同空间内更多信息
|
||||
4. **历史保持**: 维持更长对话历史
|
||||
5. **模式识别**: 视觉模式便于发现问题
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 此模式仅改变 **AI 的响应风格**
|
||||
- 生成的**代码质量**不会改变
|
||||
- 可根据需要切换为「详细模式说明」
|
||||
- 对初学者或非技术人员建议使用正常模式
|
||||
|
||||
## 命令示例
|
||||
|
||||
```bash
|
||||
# 启用
|
||||
「启用 Token 效率模式」
|
||||
「简洁响应」
|
||||
「使用 --uc 分析」
|
||||
|
||||
# 禁用
|
||||
「切换为正常模式」
|
||||
「详细说明」
|
||||
「关闭 Token 效率模式」
|
||||
```
|
||||
|
||||
## 实现影响
|
||||
|
||||
| 项目 | 影响 |
|
||||
| ------------ | -------------- |
|
||||
| 生成代码质量 | 无变化 ✅ |
|
||||
| 实现准确性 | 无变化 ✅ |
|
||||
| 功能性 | 无变化 ✅ |
|
||||
| AI 说明方式 | 压缩 🔄 |
|
||||
| 上下文使用 | 减少 30-50% ⚡ |
|
||||
|
||||
---
|
||||
|
||||
💡 **专业提示**: 在长时间工作会话中，先用正常模式加深理解，然后切换到 Token 效率模式，可以优化效率与上下文保持的平衡。
|
||||
65
commands/ultrathink.md
Normal file
65
commands/ultrathink.md
Normal file
@@ -0,0 +1,65 @@
|
||||
## Ultrathink
|
||||
|
||||
对复杂课题或重要决策执行分阶段的结构化思考过程。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 请求 Claude 进行深度思考
|
||||
「用 ultrathink 探讨[课题]」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 架构设计探讨
|
||||
「用 ultrathink 探讨应该选择微服务还是单体架构」
|
||||
|
||||
# 技术选型分析
|
||||
「用 ultrathink 分析这个项目适合 Rust 还是 TypeScript」
|
||||
|
||||
# 问题解决深入探讨
|
||||
「用 ultrathink 探讨应用性能差的原因和改进方法」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 业务判断
|
||||
「用 ultrathink 探讨新功能的优先级排序。从用户价值、开发成本、技术风险的角度」
|
||||
|
||||
# 系统设计
|
||||
「用 ultrathink 探讨认证系统的设计。考虑安全性、可扩展性、可维护性」
|
||||
|
||||
# 权衡分析
|
||||
「用 ultrathink 分析 GraphQL vs REST API 的选择。基于项目需求」
|
||||
|
||||
# 重构策略
|
||||
cat src/legacy_code.js
|
||||
「用 ultrathink 制定这个遗留代码的重构策略」
|
||||
```
|
||||
|
||||
### 思考过程
|
||||
|
||||
1. **问题分解** - 将课题分解为组成要素
|
||||
2. **MECE 分析** - 无遗漏无重复地整理
|
||||
3. **多角度探讨** - 从技术、业务、用户角度分析
|
||||
4. **交互式确认** - 在重要判断点向用户确认
|
||||
5. **有依据的建议** - 基于数据和逻辑的结论
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 复杂技术债务的解决
|
||||
「用 ultrathink 探讨将 10 年的遗留系统现代化的策略。包括分阶段迁移、风险、ROI」
|
||||
|
||||
# 组织性课题
|
||||
「用 ultrathink 探讨开发团队的扩展策略。假设从目前 5 人扩展到 20 人」
|
||||
|
||||
# 数据库迁移
|
||||
「用 ultrathink 分析从 PostgreSQL 迁移到 DynamoDB。考虑成本、性能、运维」
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
ultrathink 最适合需要花时间深入思考的课题。对于简单问题或需要即时回答的情况，请使用常规提问形式。
|
||||
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## 更新 Dart 文档
|
||||
|
||||
系统地管理 Dart 文件的 DartDoc 注释，维护高质量的中文文档。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 同时执行新增和更新
|
||||
「为没有 DartDoc 注释的类添加注释，并更新不符合标准的注释」
|
||||
|
||||
# 确认 PR 的更改文件
|
||||
「确认 PR #4308 中更改的文件是否有 Claude 标记」
|
||||
|
||||
# 特定目录的文档整理
|
||||
「为 packages/app/lib/ui/screen/ 下的 Widget 类添加 DartDoc」
|
||||
|
||||
# 不带标记执行
|
||||
/update-dart-doc --marker false
|
||||
「改进现有项目的 DartDoc(不添加 Claude 标记)」
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--marker <true|false>` : 是否添加 Claude 标记 (默认：true)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 分析目标文件
|
||||
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
||||
「识别缺少 DartDoc 的类 (注释行数为 0 或少于 30 个字符)」
|
||||
|
||||
# 2. 添加文档
|
||||
「为识别的类添加包含必要元素的 DartDoc 注释」
|
||||
|
||||
# 3. 确认标记
|
||||
「确认所有添加或更新的 DartDoc 都有 Claude 标记」
|
||||
```
|
||||
|
||||
### 执行步骤
|
||||
|
||||
#### 1. 目标元素的优先级
|
||||
|
||||
1. 🔴 **最优先**: 没有 DartDoc 注释的元素 (注释行数为 0)
|
||||
2. 🟡 **次优先**: 不符合标准的元素 (少于 30 个字符或缺少必要元素)
|
||||
3. 🟢 **确认对象**: 没有 Claude 标记的现有注释
|
||||
|
||||
**目标元素**：
|
||||
|
||||
- Class(所有类定义)
|
||||
- Enum(枚举类型)
|
||||
- Extension(扩展方法)
|
||||
- 重要函数 (顶级函数，可选)
|
||||
|
||||
#### 2. DartDoc 编写规则
|
||||
|
||||
**基本结构**：
|
||||
|
||||
```dart
|
||||
/// {元素的概要说明}(30-60 个字符，必需)
|
||||
///
|
||||
/// {详细说明}(必须包含角色、使用场景、注意事项，50-200 个字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@注解 // 不更改现有注解
|
||||
class 类名 {
|
||||
```
|
||||
|
||||
**文体风格**：
|
||||
|
||||
- 礼貌用语 (敬语体)："显示内容"、"管理状态的类"
|
||||
- 使用中文标点："。"、"，"
|
||||
- 中文与半角英数字之间加半角空格
|
||||
- 技术术语使用英文："Authentication 状态"
|
||||
- 每行不超过 80 个字符
|
||||
|
||||
#### 3. 按类别的描述示例
|
||||
|
||||
**状态管理类 (Riverpod)**：
|
||||
|
||||
```dart
|
||||
/// 管理水平滑动手势禁用状态的 State。
|
||||
///
|
||||
/// 在需要禁用水平滑动的特定画面或操作中使用。
|
||||
/// 例如，轮播显示或特定输入时。
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@Riverpod(keepAlive: true, dependencies: [])
|
||||
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
||||
```
|
||||
|
||||
**Widget 类**：
|
||||
|
||||
```dart
|
||||
/// 显示用户个人资料的 Widget。
|
||||
///
|
||||
/// 垂直排列头像图片、用户名和状态信息，
|
||||
/// 点击时跳转到个人资料详情页面。
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends HookConsumerWidget {
|
||||
```
|
||||
|
||||
#### 4. 现有内容保留规则
|
||||
|
||||
1. **现有注释符合标准时**: 保持原样 (不新增)
|
||||
- 标准：30 个字符以上且包含必要元素 (概要、详细、标记)
|
||||
2. **现有注释不符合标准时**: 完全替换 (不重复)
|
||||
3. **没有现有注释时**: 添加新注释
|
||||
|
||||
**应保留的重要信息**：
|
||||
|
||||
- URL 和链接：以 `See also:` 开头的引用
|
||||
- TODO 注释：`TODO(user_name):` 格式
|
||||
- 注意事项：`注意:` 或 `Warning:` 等警告
|
||||
- 使用示例：以 `例:` 或 `Example:` 开头的代码
|
||||
- 技术约束：性能或限制的描述
|
||||
|
||||
### Claude 标记管理
|
||||
|
||||
```bash
|
||||
# 标记格式
|
||||
/// Generated by Claude 🤖
|
||||
|
||||
# 在 PR 更改文件中确认标记
|
||||
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
|
||||
「为没有标记的文件添加标记」
|
||||
```
|
||||
|
||||
### 质量检查清单
|
||||
|
||||
- ✅ **字符数**: 严格遵守概要 30-60 个字符、详细 50-200 个字符
|
||||
- ✅ **必要元素**: 必须包含概要、详细说明、Claude 标记三个元素
|
||||
- ✅ **完整性**: 记载角色、使用场景、注意事项
|
||||
- ✅ **一致性**: 统一使用礼貌用语 (敬语体)
|
||||
- ✅ **格式**: 中文与英文之间加半角空格
|
||||
- ✅ **准确性**: 分析实现，仅记载基于事实的描述
|
||||
- ✅ **结构**: 保留注解，注释放在上方
|
||||
- ✅ **长度**: 每行不超过 80 个字符
|
||||
- ✅ **标记**: Claude 的更改必须添加标记
|
||||
|
||||
### 注意事项
|
||||
|
||||
**🔴 绝对禁止事项**：
|
||||
|
||||
- ❌ 更改文档注释以外的代码
|
||||
- ❌ 推测实现细节 (仅记载事实)
|
||||
- ❌ 中英文不自然的混用
|
||||
- ❌ 删除或更改现有注解
|
||||
- ❌ 与现有注释重复
|
||||
- ❌ 为测试文件 (`*_test.dart`) 添加不符合字符数标准的注释
|
||||
- ❌ 为 VRT 文件 (`*_vrt.dart`) 添加不符合字符数标准的注释
|
||||
|
||||
**静态分析和提交**：
|
||||
|
||||
```bash
|
||||
# 记录执行结果
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 更改后确认
|
||||
melos analyze
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 错误：静态分析失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 输出执行摘要
|
||||
echo "📊 执行结果："
|
||||
echo "- 添加的注释：$ADDED_COMMENTS 条"
|
||||
echo "- 更新的注释：$UPDATED_COMMENTS 条"
|
||||
echo "- 错误数：$ERRORS 个"
|
||||
|
||||
# 提交示例
|
||||
git commit -m "docs: 添加和更新 DartDoc 注释
|
||||
|
||||
- 为不符合标准的类、enum、extension 添加 DartDoc
|
||||
- 更新少于 30 个字符的注释以符合标准
|
||||
- 统一添加 Claude 标记
|
||||
|
||||
执行结果：
|
||||
- 添加：$ADDED_COMMENTS 条
|
||||
- 更新：$UPDATED_COMMENTS 条
|
||||
|
||||
Generated by Claude 🤖"
|
||||
```
|
||||
|
||||
### 执行成功标准
|
||||
|
||||
1. **完成判定**: 满足以下所有条件时成功
|
||||
- `melos analyze` 显示 PASSED
|
||||
- 错误数为 0
|
||||
- 添加和更新的注释都符合标准
|
||||
|
||||
2. **部分成功**: 以下情况
|
||||
- 错误数少于 5 个
|
||||
- 90% 以上符合标准
|
||||
|
||||
3. **失败**: 以下情况
|
||||
- `melos analyze` 显示 FAILED
|
||||
- 错误数为 5 个或以上
|
||||
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## 更新文档字符串
|
||||
|
||||
系统地管理多语言的 docstring/注释，维护高质量的文档。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 自动检测语言并执行
|
||||
「为没有 docstring 的类和函数添加注释，并更新不符合标准的注释」
|
||||
|
||||
# 指定语言执行
|
||||
/update-doc-string --lang python
|
||||
「按照 PEP 257 规范更新 Python 文件的 docstring」
|
||||
|
||||
# 特定目录的文档整理
|
||||
「为 src/components/ 下的函数添加 JSDoc」
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
- `--lang <en|zh-cn>` : 文档记述语言 (默认：从现有注释自动判定，无则为 en)
|
||||
- `--style <风格>` : 指定文档风格 (有语言特定的默认值)
|
||||
- `--marker <true|false>` : 是否添加 Claude 标记 (默认：true)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 分析目标文件 (自动检测编程语言)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
||||
「识别缺少 docstring 的元素 (注释行数为 0 或少于 30 个字符)」
|
||||
|
||||
# 2. 添加文档 (自动判定语言)
|
||||
「为识别的元素添加包含语言特定必要元素的 docstring」
|
||||
# → 如果现有注释中有中文则用中文，否则用英文
|
||||
|
||||
# 3. 添加文档 (明确指定英文)
|
||||
/update-doc-string --lang en
|
||||
「Add docstrings with required elements to the identified elements」
|
||||
|
||||
# 4. 确认标记
|
||||
「确认所有添加或更新的 docstring 都有 Claude 标记」
|
||||
```
|
||||
|
||||
### 执行步骤
|
||||
|
||||
#### 1. 目标元素的优先级
|
||||
|
||||
1. 🔴 **最优先**: 没有 docstring/注释的元素 (注释行数为 0)
|
||||
2. 🟡 **次优先**: 不符合标准的元素 (少于 30 个字符或缺少必要元素)
|
||||
3. 🟢 **确认对象**: 没有 Claude 标记的现有注释
|
||||
|
||||
**目标元素 (通用)**：
|
||||
|
||||
- Class/类定义
|
||||
- Function/函数和方法
|
||||
- Module/模块 (Python, Go)
|
||||
- Enum/枚举类型
|
||||
- Interface/接口 (TypeScript, Go)
|
||||
|
||||
#### 2. 语言特定编写规则
|
||||
|
||||
**Python (PEP 257)**：
|
||||
|
||||
```python
|
||||
# 中文版 (默认)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""计算商品列表的总金额。(30-60 个字符)
|
||||
|
||||
将每个商品的价格和数量相乘，返回含税总额。
|
||||
空列表时返回 0.0。(50-200 个字符)
|
||||
|
||||
Args:
|
||||
items: 要计算的商品列表
|
||||
|
||||
Returns:
|
||||
含税总金额
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
|
||||
# 英文版 (--lang en)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 chars)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript (JSDoc)**：
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* 显示用户个人资料的组件。(30-60 个字符)
|
||||
*
|
||||
* 显示头像图片、用户名和状态信息，
|
||||
* 点击时跳转到个人资料详情页面。(50-200 个字符)
|
||||
*
|
||||
* @param {Object} props - 组件属性
|
||||
* @param {string} props.userId - 用户 ID
|
||||
* @param {boolean} [props.showStatus=true] - 状态显示标志
|
||||
* @returns {JSX.Element} 渲染的组件
|
||||
*
|
||||
* @generated by Claude 🤖
|
||||
*/
|
||||
const UserProfile = ({ userId, showStatus = true }) => {
|
||||
```
|
||||
|
||||
**Go**：
|
||||
|
||||
```go
|
||||
// CalculateTotal 计算商品列表的总金额。(30-60 个字符)
|
||||
//
|
||||
// 将每个商品的价格和数量相乘，返回含税总额。
|
||||
// 空切片时返回 0.0。(50-200 个字符)
|
||||
//
|
||||
// Generated by Claude 🤖
|
||||
func CalculateTotal(items []Item) float64 {
|
||||
```
|
||||
|
||||
**Rust**：
|
||||
|
||||
```rust
|
||||
/// 计算商品列表的总金额。(30-60 个字符)
|
||||
///
|
||||
/// 将每个商品的价格和数量相乘，返回含税总额。
|
||||
/// 空向量时返回 0.0。(50-200 个字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
pub fn calculate_total(items: &[Item]) -> f64 {
|
||||
```
|
||||
|
||||
**Dart (DartDoc)**：
|
||||
|
||||
```dart
|
||||
/// 显示用户个人资料的 Widget。(30-60 个字符)
|
||||
///
|
||||
/// 垂直排列头像图片、用户名和状态信息，
|
||||
/// 点击时跳转到个人资料详情页面。(50-200 个字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends StatelessWidget {
|
||||
```
|
||||
|
||||
#### 3. 现有内容保留规则
|
||||
|
||||
1. **现有注释符合标准时**: 保持原样 (不新增)
|
||||
- 标准：30 个字符以上且包含必要元素 (概要、详细、标记)
|
||||
2. **现有注释不符合标准时**: 完全替换 (不重复)
|
||||
3. **没有现有注释时**: 添加新注释
|
||||
|
||||
**应保留的重要信息**：
|
||||
|
||||
- URL 和链接：`See also:`、`@see`、`参照:` 等
|
||||
- TODO 注释：`TODO:`、`FIXME:`、`XXX:` 格式
|
||||
- 注意事项：`Note:`、`Warning:`、`注意:` 等
|
||||
- 使用示例：`Example:`、`例:`、`# Examples` 等
|
||||
- 现有的参数和返回值说明
|
||||
|
||||
### 语言特定设置
|
||||
|
||||
```yaml
|
||||
# 语言特定默认设置
|
||||
languages:
|
||||
python:
|
||||
style: "google" # google, numpy, sphinx
|
||||
indent: 4
|
||||
quotes: '"""'
|
||||
|
||||
javascript:
|
||||
style: "jsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
typescript:
|
||||
style: "tsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
go:
|
||||
style: "godoc"
|
||||
indent: 0
|
||||
prefix: "//"
|
||||
|
||||
rust:
|
||||
style: "rustdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
|
||||
dart:
|
||||
style: "dartdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
```
|
||||
|
||||
### 质量检查清单
|
||||
|
||||
- ✅ **字符数**: 严格遵守概要 30-60 个字符、详细 50-200 个字符
|
||||
- ✅ **必要元素**: 必须包含概要、详细说明、Claude 标记三个元素
|
||||
- ✅ **完整性**: 记载角色、使用场景、注意事项
|
||||
- ✅ **语言规范**: 遵循各语言的官方风格指南
|
||||
- ✅ **异常**: 错误和异常的说明 (如适用)
|
||||
- ✅ **准确性**: 分析实现，仅记载基于事实的描述
|
||||
|
||||
### 注意事项
|
||||
|
||||
**🔴 绝对禁止事项**：
|
||||
|
||||
- ❌ 更改文档注释以外的代码
|
||||
- ❌ 推测实现细节 (仅记载事实)
|
||||
- ❌ 违反语言规范的格式
|
||||
- ❌ 删除或更改现有的类型注解
|
||||
- ❌ 与现有注释重复
|
||||
- ❌ 为测试文件添加不符合字符数标准的注释
|
||||
|
||||
**执行和验证**：
|
||||
|
||||
```bash
|
||||
# 记录执行结果
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 从现有注释自动判定语言
|
||||
# 检测中文字符则为 zh-cn，否则为 en
|
||||
DOC_LANGUAGE="en" # 默认
|
||||
if grep -r '[一-龥]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
||||
DOC_LANGUAGE="zh-cn"
|
||||
fi
|
||||
|
||||
# 自动检测编程语言并执行静态分析
|
||||
if [ -f "*.py" ]; then
|
||||
pylint --disable=all --enable=missing-docstring .
|
||||
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
||||
eslint . --rule 'jsdoc/require-jsdoc: error'
|
||||
elif [ -f "*.go" ]; then
|
||||
golint ./...
|
||||
elif [ -f "*.rs" ]; then
|
||||
cargo doc --no-deps
|
||||
elif [ -f "*.dart" ]; then
|
||||
melos analyze
|
||||
fi
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 错误：静态分析失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 输出执行摘要
|
||||
echo "📊 执行结果："
|
||||
echo "- 文档语言：$DOC_LANGUAGE"
|
||||
echo "- 添加的注释：$ADDED_COMMENTS 条"
|
||||
echo "- 更新的注释：$UPDATED_COMMENTS 条"
|
||||
echo "- 错误数：$ERRORS 个"
|
||||
```
|
||||
|
||||
### 执行成功标准
|
||||
|
||||
1. **完成判定**: 满足以下所有条件时成功
|
||||
- 语言特定的静态分析显示 PASSED
|
||||
- 错误数为 0
|
||||
- 添加和更新的注释都符合标准
|
||||
|
||||
2. **部分成功**: 以下情况
|
||||
- 错误数少于 5 个
|
||||
- 90% 以上符合标准
|
||||
|
||||
3. **失败**: 以下情况
|
||||
- 静态分析显示 FAILED
|
||||
- 错误数为 5 个或以上
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 分析整个项目 (自动判定语言)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
||||
/update-doc-string
|
||||
「按照语言特定的最佳实践更新这个项目的 docstring」
|
||||
# → 如果现有注释中有中文则用 ja，否则用 en
|
||||
|
||||
# 明确指定英文文档
|
||||
/update-doc-string --lang en
|
||||
"Update docstrings following language-specific best practices"
|
||||
|
||||
# 明确指定中文文档
|
||||
/update-doc-string --lang zh-cn
|
||||
「按照语言特定的最佳实践更新这个项目的 docstring」
|
||||
|
||||
# 不带标记执行 (自动判定语言)
|
||||
/update-doc-string --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
|
||||
# 英文文档，不带标记
|
||||
/update-doc-string --lang en --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
```
|
||||
105
commands/update-flutter-deps.md
Normal file
105
commands/update-flutter-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Flutter 依赖更新
|
||||
|
||||
安全地更新 Flutter 项目的依赖关系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 确认依赖状态并请求 Claude
|
||||
flutter pub deps --style=compact
|
||||
「将 pubspec.yaml 的依赖更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 确认当前依赖
|
||||
cat pubspec.yaml
|
||||
「分析这个 Flutter 项目的依赖并告诉我可更新的包」
|
||||
|
||||
# 升级后确认
|
||||
flutter pub upgrade --dry-run
|
||||
「确认这个升级计划中是否有破坏性变更」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依赖更新
|
||||
cat pubspec.yaml
|
||||
「分析 Flutter 的依赖并执行以下操作：
|
||||
1. 调查各包的最新版本
|
||||
2. 确认是否有破坏性变更
|
||||
3. 评估危险度 (安全・注意・危险)
|
||||
4. 提出必要的代码更改
|
||||
5. 生成更新版 pubspec.yaml」
|
||||
|
||||
# 安全的分阶段更新
|
||||
flutter pub outdated
|
||||
「避免主版本升级，只更新可以安全升级的包」
|
||||
|
||||
# 特定包的更新影响分析
|
||||
「告诉我将 provider 更新到最新版本的影响和必要的更改」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的详细分析
|
||||
cat pubspec.yaml && flutter pub outdated
|
||||
「分析依赖，为每个包提供：
|
||||
1. 当前 → 最新版本
|
||||
2. 危险度评估 (安全・注意・危险)
|
||||
3. 主要变更 (来自 CHANGELOG)
|
||||
4. 必要的代码修改
|
||||
以表格形式展示」
|
||||
|
||||
# Null Safety 迁移分析
|
||||
cat pubspec.yaml
|
||||
「识别不支持 Null Safety 的包，制定迁移计划」
|
||||
```
|
||||
|
||||
### 危险度标准
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 补丁版本升级 (1.2.3 → 1.2.4)
|
||||
- 仅修复 bug
|
||||
- 保证向后兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升级 (1.2.3 → 1.3.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危险 (🔴)：
|
||||
- 主版本升级 (1.2.3 → 2.0.0)
|
||||
- 破坏性变更
|
||||
- API 的删除或更改
|
||||
```
|
||||
|
||||
### 执行更新
|
||||
|
||||
```bash
|
||||
# 创建备份
|
||||
cp pubspec.yaml pubspec.yaml.backup
|
||||
cp pubspec.lock pubspec.lock.backup
|
||||
|
||||
# 执行更新
|
||||
flutter pub upgrade
|
||||
|
||||
# 更新后确认
|
||||
flutter analyze
|
||||
flutter test
|
||||
flutter pub deps --style=compact
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
更新后必须进行功能测试。如果出现问题，使用以下命令恢复：
|
||||
|
||||
```bash
|
||||
cp pubspec.yaml.backup pubspec.yaml
|
||||
cp pubspec.lock.backup pubspec.lock
|
||||
flutter pub get
|
||||
```
|
||||
105
commands/update-node-deps.md
Normal file
105
commands/update-node-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Node 依赖更新
|
||||
|
||||
安全地更新 Node.js 项目的依赖关系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 确认依赖状态并请求 Claude
|
||||
npm outdated
|
||||
「将 package.json 的依赖更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 确认当前依赖
|
||||
cat package.json
|
||||
「分析这个 Node.js 项目的依赖并告诉我可更新的包」
|
||||
|
||||
# 确认可更新列表
|
||||
npm outdated
|
||||
「分析这些包更新的危险度」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依赖更新
|
||||
cat package.json
|
||||
「分析 Node.js 的依赖并执行以下操作：
|
||||
1. 调查各包的最新版本
|
||||
2. 确认是否有破坏性变更
|
||||
3. 评估危险度 (安全・注意・危险)
|
||||
4. 提出必要的代码更改
|
||||
5. 生成更新版 package.json」
|
||||
|
||||
# 安全的分阶段更新
|
||||
npm outdated
|
||||
「避免主版本升级，只更新可以安全升级的包」
|
||||
|
||||
# 特定包的更新影响分析
|
||||
「告诉我将 express 更新到最新版本的影响和必要的更改」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的详细分析
|
||||
cat package.json && npm outdated
|
||||
「分析依赖，为每个包提供：
|
||||
1. 当前 → 最新版本
|
||||
2. 危险度评估 (安全・注意・危险)
|
||||
3. 主要变更 (来自 CHANGELOG)
|
||||
4. 必要的代码修改
|
||||
以表格形式展示」
|
||||
|
||||
# TypeScript 项目的类型定义考虑
|
||||
cat package.json tsconfig.json
|
||||
「包括 TypeScript 的类型定义更新依赖，制定不会产生类型错误的更新计划」
|
||||
```
|
||||
|
||||
### 危险度标准
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 补丁版本升级 (1.2.3 → 1.2.4)
|
||||
- 仅修复 bug
|
||||
- 保证向后兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升级 (1.2.3 → 1.3.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危险 (🔴)：
|
||||
- 主版本升级 (1.2.3 → 2.0.0)
|
||||
- 破坏性变更
|
||||
- API 的删除或更改
|
||||
```
|
||||
|
||||
### 执行更新
|
||||
|
||||
```bash
|
||||
# 创建备份
|
||||
cp package.json package.json.backup
|
||||
cp package-lock.json package-lock.json.backup
|
||||
|
||||
# 执行更新
|
||||
npm update
|
||||
|
||||
# 更新后确认
|
||||
npm test
|
||||
npm run build
|
||||
npm audit
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
更新后必须进行功能测试。如果出现问题，使用以下命令恢复：
|
||||
|
||||
```bash
|
||||
cp package.json.backup package.json
|
||||
cp package-lock.json.backup package-lock.json
|
||||
npm install
|
||||
```
|
||||
107
commands/update-rust-deps.md
Normal file
107
commands/update-rust-deps.md
Normal file
@@ -0,0 +1,107 @@
|
||||
## Rust 依赖更新
|
||||
|
||||
安全地更新 Rust 项目的依赖关系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 确认依赖状态并请求 Claude
|
||||
cargo tree
|
||||
「将 Cargo.toml 的依赖更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 确认当前依赖
|
||||
cat Cargo.toml
|
||||
「分析这个 Rust 项目的依赖并告诉我可更新的 crate」
|
||||
|
||||
# 确认可更新列表
|
||||
cargo update --dry-run
|
||||
「分析这些 crate 更新的危险度」
|
||||
```
|
||||
|
||||
### 与 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依赖更新
|
||||
cat Cargo.toml
|
||||
「分析 Rust 的依赖并执行以下操作：
|
||||
1. 调查各 crate 的最新版本
|
||||
2. 确认是否有破坏性变更
|
||||
3. 评估危险度 (安全・注意・危险)
|
||||
4. 提出必要的代码更改
|
||||
5. 生成更新版 Cargo.toml」
|
||||
|
||||
# 安全的分阶段更新
|
||||
cargo tree
|
||||
「避免主版本升级，只更新可以安全升级的 crate」
|
||||
|
||||
# 特定 crate 的更新影响分析
|
||||
「告诉我将 tokio 更新到最新版本的影响和必要的更改」
|
||||
```
|
||||
|
||||
### 详细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的详细分析
|
||||
cat Cargo.toml && cargo tree
|
||||
「分析依赖，为每个 crate 提供：
|
||||
1. 当前 → 最新版本
|
||||
2. 危险度评估 (安全・注意・危险)
|
||||
3. 主要变更 (来自 CHANGELOG)
|
||||
4. trait 边界的变更
|
||||
5. 必要的代码修改
|
||||
以表格形式展示」
|
||||
|
||||
# 异步运行时的迁移分析
|
||||
cat Cargo.toml src/main.rs
|
||||
「展示从 async-std 迁移到 tokio，或 tokio 主版本升级所需的所有更改」
|
||||
```
|
||||
|
||||
### 危险度标准
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 补丁版本升级 (0.1.2 → 0.1.3)
|
||||
- 仅修复 bug
|
||||
- 保证向后兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升级 (0.1.0 → 0.2.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危险 (🔴)：
|
||||
- 主版本升级 (0.x.y → 1.0.0、1.x.y → 2.0.0)
|
||||
- 破坏性变更
|
||||
- API 的删除或更改
|
||||
- trait 边界的变更
|
||||
```
|
||||
|
||||
### 执行更新
|
||||
|
||||
```bash
|
||||
# 创建备份
|
||||
cp Cargo.toml Cargo.toml.backup
|
||||
cp Cargo.lock Cargo.lock.backup
|
||||
|
||||
# 执行更新
|
||||
cargo update
|
||||
|
||||
# 更新后确认
|
||||
cargo check
|
||||
cargo test
|
||||
cargo clippy
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
更新后必须进行功能测试。如果出现问题，使用以下命令恢复：
|
||||
|
||||
```bash
|
||||
cp Cargo.toml.backup Cargo.toml
|
||||
cp Cargo.lock.backup Cargo.lock
|
||||
cargo build
|
||||
```
|
||||
Reference in New Issue
Block a user