catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add Chinese documentation for custom skills development and reference guide

Browse Source 
- Created a new document for custom skills development (`custom.md`) detailing the structure, creation, implementation, and best practices for developing custom CCW skills.
- Added an index document (`index.md`) summarizing all built-in skills, their categories, and usage examples.
- Introduced a reference guide (`reference.md`) providing a quick reference for all 33 built-in CCW skills, including triggers and purposes.
This commit is contained in:
catlog22
2026-03-01 13:08:12 +08:00
parent 2fb93d20e0
commit 8ceae6d6fd
78 changed files with 12352 additions and 3638 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/skills/specs/document-standards.md Normal file
View File

@@ -0,0 +1,248 @@
# Document Standards
> 本文档定义 CCW Skills 生态系统中所有文档的格式规范、frontmatter 要求、命名约定和结构标准。
## 概述
本规范确保 CCW Skills 文档的一致性、可维护性和可扩展性。所有文档（包括 Skill 文档、规格文档、模板文档）都应遵循此规范。
## Frontmatter 标准
### 必需字段
所有文档必须包含以下 frontmatter：
```yaml
---
title: "文档标题"
description: "简短描述（一句话）"
version: "1.0.0"
last_updated: "YYYY-MM-DD"
tags: ["tag1", "tag2"]
category: "specification|template|reference"
---
```
### 可选字段
```yaml
---
author: "作者名称"
status: "draft|stable|deprecated"
related_docs:
- "path/to/related-doc.md"
- "path/to/another-doc.md"
cli_support:
- "claude"
- "codex"
- "both"
---
```
## 文件命名约定
### 规格文档 (specs/)
| 模式 | 示例 | 用途 |
|------|------|------|
| `{domain}-standards.md` | `quality-standards.md` | 质量标准 |
| `{domain}-gates.md` | `quality-gates.md` | 质量门禁 |
| `{domain}-dimensions.md` | `review-dimensions.md` | 审查维度 |
| `{domain}-classification.md` | `issue-classification.md` | 分类标准 |
| `{domain}-spec.md` | `reference-docs-spec.md` | 参考规范 |
### 模板文档 (templates/)
| 模式 | 示例 | 用途 |
|------|------|------|
| `{document-type}.md` | `product-brief.md` | 产品简介模板 |
| `{workflow-type}.md` | `sequential-phase.md` | 工作流阶段模板 |
| `{output-type}.md` | `review-report.md` | 输出报告模板 |
### Skill 文档
| 模式 | 示例 | 用途 |
|------|------|------|
| `claude-{category}.md` | `claude-meta.md` | Claude 专属技能 |
| `codex-{category}.md` | `codex-workflow.md` | Codex 专属技能 |
| `{concept}.md` | `core-skills.md` | 通用概念文档 |
## 文档结构标准
### 标准章节结构
```markdown
# 标题
> 概述/简介（一句话说明）
## One-Liner
**简短描述** — 详细说明
## Pain Points Solved
| Pain Point | Current State | Solution |
|------------|---------------|----------|
| 问题 | 当前状态 | 解决方案 |
## Skills List / 功能列表
| Skill | Function | Trigger |
|-------|----------|---------|
| 技能名 | 功能描述 | 触发命令 |
## Skills Details / 详细说明
### skill-name
**One-Liner**: 简短描述
**Trigger**:
```shell
/example command
```
**Features**:
- 特性1
- 特性2
**Architecture Overview**:
```plaintext
架构图或流程图
```
## Related Commands / 相关命令
## Best Practices / 最佳实践
## Usage Examples / 使用示例
```bash
# 示例命令
/example usage
```
```
### 规格文档结构
```markdown
# {规范名称}
> 本文档定义 {用途}
## 概述
简要说明规范的目的和范围。
## 规范内容
### {分类1}
| 项目 | 标准 | 说明 |
|------|------|------|
| 项目1 | 标准描述 | 详细说明 |
### {分类2}
...
## 参考
- [相关文档链接](relative/path.md)
- [外部参考](https://example.com)
```
### 模板文档结构
```markdown
# {模板名称}
> 用途: {描述}
## 模板
\`\`\`markdown
{模板内容}
\`\`\`
## 使用说明
1. 步骤1
2. 步骤2
3. 步骤3
## 示例
### 示例标题
\`\`\`markdown
{示例填充内容}
\`\`\`
```
## 格式规范
### 标题层级
| 级别 | 用途 | 示例 |
|------|------|------|
| H1 (#) | 文档标题，每文档仅一次 | `# Document Title` |
| H2 (##) | 主要章节 | `## Overview` |
| H3 (###) | 子章节 | `### Section Name` |
| H4 (####) | 细节说明 | `#### Details` |
### 代码块
| 语言 | 用途 |
|------|------|
| `shell` / `bash` | 命令行示例 |
| `markdown` | Markdown 模板 |
| `plaintext` | 架构图/流程图 |
| `typescript` / `python` | 代码示例 |
### 表格
- 列对齐: 默认左对齐
- 表头: 必须包含
- 说明列: 必要时添加
### 引用块
| 类型 | 语法 | 用途 |
|------|------|------|
| 警告 | `> **⚠️ Warning**: ` | 重要提醒 |
| 注意 | `> **Note**: ` | 补充说明 |
| 不可跳过 | `> **Do not skip**: ` | 必读内容 |
| 概述 | `> 简短描述` | 章节概述 |
## 版本控制
### 版本号格式
```
major.minor.patch
```
- **major**: 重大结构变更
- **minor**: 新增章节或字段
- **patch**: 小修小补
### 更新日志
在文档末尾添加变更记录：
```markdown
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-03-01 | Initial version |
| 1.1.0 | 2026-03-15 | Added new section |
```
## 参考
- [CCW Skills Design Spec](../_shared/SKILL-DESIGN-SPEC.md)
- [Markdown Guide](https://www.markdownguide.org/)
- [VitePress Documentation](https://vitepress.dev/)

200
docs/skills/specs/issue-classification.md Normal file
View File

@@ -0,0 +1,200 @@
# Issue Classification
> 本文档定义代码审查中发现的问题分类标准和严重性等级。
## 概述
问题分类确保审查报告的一致性和可操作性。所有问题应按严重性等级标记，并提供明确的修复建议。
## 严重性等级
| 等级 | 前缀 | 描述 | 修复优先级 | 必须修复 |
|------|------|------|-----------|---------|
| **Critical** | [C] | 阻塞性问题，必须立即修复 | P0 - 立即 | 是，合并前必须修复 |
| **High** | [H] | 重要问题，需要修复 | P1 - 高 | 是，应该尽快修复 |
| **Medium** | [M] | 建议改进 | P2 - 中 | 建议，有时间应修复 |
| **Low** | [L] | 可选优化 | P3 - 低 | 可选，最好修复 |
| **Info** | [I] | 信息性建议 | P4 - 建议 | 无，仅供参考 |
## 分类标准
### Critical (严重)
**定义**: 阻止代码正常工作或造成严重后果的问题。
**典型问题**:
- 安全漏洞（SQL 注入、XSS、硬编码密钥）
- 数据丢失风险（未处理错误导致状态不一致）
- 崩溃风险（空指针、未捕获异常）
- 业务逻辑错误（核心功能不正确）
**示例**:
```typescript
// [C] SQL Injection Risk
const query = `SELECT * FROM users WHERE id='${userId}'`;
// 用户输入直接拼接 SQL，可被注入攻击
// [C] Null Pointer Crash
return user.profile.name; // user 可能为 null
```
---
### High (高)
**定义**: 影响代码质量或可维护性的重要问题。
**典型问题**:
- 性能问题（明显的低效算法）
- 错误处理缺失（网络请求、文件操作）
- 类型安全问题（过度使用 any）
- 资源泄漏（未关闭连接、未释放内存）
**示例**:
```typescript
// [H] Unhandled Promise
fetch(url).then(res => res.json()); // 没有错误处理
// [H] Memory Leak
const listeners = [];
listeners.push(callback); // 永不移除
```
---
### Medium (中)
**定义**: 改进空间，不影响当前功能。
**典型问题**:
- 代码重复（相同逻辑出现多次）
- 命名不清晰（变量名含糊）
- 函数过长（超过 50 行）
- 缺少文档（复杂逻辑没有注释）
**示例**:
```typescript
// [M] Code Duplication
if (user.role === 'admin') { /* 20 lines */ }
if (user.role === 'moderator') { /* similar 20 lines */ }
// [M] Unclear Naming
const d = data[0]; // "d" 含义不明
```
---
### Low (低)
**定义**: 小改进，代码风格问题。
**典型问题**:
- 格式不一致（缩进、空行）
- 未使用的变量/导入
- 魔法数字（直接使用的常量）
- 注释风格不统一
**示例**:
```typescript
// [L] Unused Import
import { unused } from './lib';
// [L] Magic Number
if (count > 42) { /* ... */ } // 42 是什么？
```
---
### Info (信息)
**定义**: 提示性建议，非问题。
**典型问题**:
- 可以使用更简洁的语法
- 推荐使用的新特性
- 性能优化建议（非关键）
**示例**:
```typescript
// [I] Could use optional chaining
user && user.profile && user.profile.name;
// 可简化为: user?.profile?.name
```
---
## 问题格式模板
每个问题应包含以下信息：
```markdown
### [等级] 问题标题
**位置**: `文件路径:行号`
**问题**: 问题描述（1-2 句话）
**严重性**: {Critical|High|Medium|Low|Info} - 修复必要性说明
**推荐修复**:
```typescript
// 修复前代码
// ↓
// 修复后代码
```
**参考**: [相关文档链接](relative/path.md)
```
---
## 按维度分类
| 维度 | 常见 Critical | 常见 High | 常见 Medium |
|------|---------------|-----------|-------------|
| **Correctness** | 空指针、类型错误 | 边界条件 | 命名、格式 |
| **Readability** | - | 长函数、深嵌套 | 注释、命名 |
| **Performance** | O(n²) 以上 | I/O 在循环 | 缓存优化 |
| **Security** | 注入、密钥泄露 | 权限检查 | - |
| **Testing** | 关键路径无测试 | 边界测试 | 覆盖率 |
| **Architecture** | 循环依赖 | 违反 SOLID | 设计模式 |
---
## 修复优先级
### P0 - 立即修复 (Critical)
- 阻塞合并
- 安全风险
- 数据风险
### P1 - 高优先级 (High)
- 本迭代内修复
- 影响用户体验
- 技术债务积累
### P2 - 中优先级 (Medium)
- 下迭代修复
- 代码质量改进
- 可维护性提升
### P3 - 低优先级 (Low)
- 有空时修复
- 代码风格统一
- 优化改进
### P4 - 建议 (Info)
- 可选修复
- 学习参考
---
## 参考
- [Review Dimensions](review-dimensions.md)
- [Quality Standards](quality-standards.md)

157
docs/skills/specs/quality-gates.md Normal file
View File

@@ -0,0 +1,157 @@
# Quality Gates
> 本文档定义 CCW Skills 各阶段的质量门禁标准和评分规则。
## 概述
质量门禁确保每个阶段完成前达到最低质量标准。门禁标准涵盖内容完整性、格式规范性、可执行性等方面。
## 质量门禁矩阵
### Phase 1: Discovery
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 输出文件存在 | `discovery-context.json` | 20% | 文件存在且格式正确 |
| 代码库覆盖 | 至少扫描 3 个目录 | 20% | 扫描目录 ≥ 3 |
| 关键发现 | 识别关键模式/问题 | 30% | 发现项 ≥ 5 |
| 技术栈识别 | 正确识别语言/框架 | 15% | 识别准确 |
| 可执行性 | 下一步可基于发现执行 | 15% | 可行动建议 ≥ 3 |
**最低通过分数**: 70/100
---
### Phase 2: Product Brief
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 输出文件存在 | `product-brief.md` | 15% | 文件存在 |
| 问题陈述清晰度 | Pain Point 明确 | 20% | 至少 3 个 Pain Point |
| 目标用户定义 | Target Audience 具体 | 15% | 用户画像清晰 |
| MoSCoW 分析 | 优先级分类完整 | 20% | Must/Should/Could 完整 |
| 可行性评估 | 技术可行性讨论 | 15% | 评估合理 |
| 格式规范 | 符合模板格式 | 15% | 符合模板 |
**最低通过分数**: 75/100
---
### Phase 3: Requirements (PRD)
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 输出文件存在 | `requirements/` 目录 | 10% | 目录结构完整 |
| 索引文件 | `_index.md` 完整 | 15% | 包含摘要、MoSCoW、追溯 |
| 功能需求 | `REQ-*.md` 数量 | 20% | 需求 ≥ 3 个 |
| 需求完整性 | Who/What/Why/How | 20% | 所有字段完整 |
| 非功能需求 | `NFR-*.md` 数量 | 15% | 至少 1 个 |
| 追溯性 | 从 Brief 到需求的链接 | 10% | 链接有效 |
| 格式规范 | 符合模板格式 | 10% | 符合模板 |
**最低通过分数**: 75/100
---
### Phase 4: Architecture
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 输出文件存在 | `architecture/` 目录 | 10% | 目录结构完整 |
| 索引文件 | `_index.md` 完整 | 15% | 包含组件、技术栈 |
| ADR 数量 | `ADR-*.md` 数量 | 20% | 决策记录 ≥ 2 |
| 决策质量 | Context/Decision/Consequence | 20% | 结构完整 |
| 技术栈选择 | 有理由支持 | 15% | 评估合理 |
| 追溯性 | 从 PRD 到架构的链接 | 10% | 链接有效 |
| 格式规范 | 符合模板格式 | 10% | 符合模板 |
**最低通过分数**: 75/100
---
### Phase 5: Epics
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 输出文件存在 | `epics/` 目录 | 10% | 目录结构完整 |
| 索引文件 | `_index.md` 完整 | 15% | 包含 Epic 表、依赖图 |
| Epic 数量 | `EPIC-*.md` 数量 | 20% | Epic ≥ 2 |
| Story 质量 | User Story 格式 | 20% | 作为...我想要...以便... |
| 依赖关系 | Epic 间依赖清晰 | 15% | 依赖图或说明 |
| MVP 范围 | MVP 定义明确 | 10% | MVP Epic 标记 |
| 追溯性 | 从架构到 Epic 的链接 | 10% | 链接有效 |
**最低通过分数**: 75/100
---
### Phase 6: Readiness Check
| 检查项 | 标准 | 权重 | 通过条件 |
|--------|------|------|----------|
| 就绪报告 | `readiness-report.md` | 30% | 文件存在且完整 |
| 摘要文档 | `spec-summary.md` | 20% | 一页摘要 |
| 质量评分 | 所有阶段通过 | 30% | 所有阶段 ≥ 最低分 |
| 移交选项 | Handoff 选项清晰 | 10% | 选项明确 |
| 格式规范 | 符合模板格式 | 10% | 符合模板 |
**最低通过分数**: 80/100
---
## 质量评分计算
### 自动检查项
```bash
# 文件存在性
if [ -f "$expected_file" ]; then score=$((score + weight)); fi
# 格式验证
if markdownlint "$file"; then score=$((score + weight)); fi
# 链接有效性
if check-links "$file"; then score=$((score + weight)); fi
```
### 手动评审项
- 内容质量
- 逻辑连贯性
- 可执行性
- 实用性
### 综合评分
```
最终得分 = 自动检查得分 × 60% + 手动评审得分 × 40%
```
## 质量等级
| 等级 | 分数范围 | 描述 |
|------|----------|------|
| **A - 优秀** | 90-100 | 超出标准，可直接移交 |
| **B - 良好** | 80-89 | 满足标准，可移交 |
| **C - 及格** | 70-79 | 基本达标，需要改进 |
| **D - 不及格** | < 70 | 未达标，需要返工 |
## 不合格处理
### 返工流程
1. **识别问题**: 在就绪报告中列出不合格项
2. **修复**: 返回对应阶段进行修复
3. **重新评估**: 重新执行质量检查
4. **记录**: 记录修复过程和结果
### 豁免条件
- 探索性项目（POC）
- 时间受限的快速原型
- 明确标注为"草稿"的输出
## 参考
- [Document Standards](document-standards.md)
- [Quality Standards](quality-standards.md)

190
docs/skills/specs/quality-standards.md Normal file
View File

@@ -0,0 +1,190 @@
# Quality Standards
> 本文档定义 CCW Skills 审查的质量标准和评分规则。
## 概述
质量标准确保审查过程的规范性和审查结果的一致性。审查者应遵循此标准进行审查。
## 审查者资格
### 必需能力
| 能力 | 要求 |
|------|------|
| 代码理解 | 能够理解代码逻辑和设计意图 |
| 标准掌握 | 熟悉本质量标准和相关规范 |
| 语言能力 | 代码编写语言的熟练度 |
| 架构理解 | 理解系统架构和设计模式 |
### 培训要求
- 新审查者必须完成审查培训
- 每季度参加标准更新培训
- 参与审查校准会议
---
## 审查过程标准
### 1. 准备阶段
- ✅ 阅读 `specs/review-dimensions.md`
- ✅ 阅读 `specs/issue-classification.md`
- ✅ 了解被审查代码的上下文
### 2. 快速扫描阶段
- 扫描所有文件，识别高风险区域
- 标记明显的问题（Critical/High）
- 评估整体代码质量
**时间限制**: 5-10 分钟
### 3. 深度审查阶段
- 逐个维度进行审查
- 记录发现的问题
- 提供具体的修复建议
**时间限制**: 20-40 分钟
### 4. 报告生成阶段
- 汇总所有发现
- 生成结构化报告
- 提供修复优先级
---
## 审查质量评分
### 审查完整性
| 检查项 | 权重 | 标准 |
|--------|------|------|
| 覆盖所有维度 | 30% | 6 个维度全部审查 |
| 高风险区域识别 | 20% | 快速扫描识别关键问题 |
| 问题记录详细 | 25% | 每个问题包含位置、描述、建议 |
| 报告格式规范 | 15% | 符合报告模板 |
| 修复建议可执行 | 10% | 建议具体可操作 |
**最低要求**: 70/100
---
## 问题发现率标准
### 期望发现率
| 严重性 | 期望发现率 | 说明 |
|--------|-----------|------|
| Critical | 100% | 所有 Critical 问题必须发现 |
| High | ≥ 90% | 大部分 High 问题应发现 |
| Medium | ≥ 60% | 主要 Medium 问题应发现 |
| Low | ≥ 30% | 部分 Low 问题应发现 |
### 质量验证
通过以下方式验证审查质量：
1. **交叉审查**: 重要 PR 由多人审查
2. **审查回顾**: 定期回顾审查质量
3. **问题追踪**: 审查遗漏问题的跟踪
---
## 审查效率标准
### 时间标准
| 代码规模 | 预期时间 |
|----------|----------|
| 小型 (< 200 行) | 15-20 分钟 |
| 中型 (200-500 行) | 30-40 分钟 |
| 大型 (500-1000 行) | 60-80 分钟 |
| 超大 (> 1000 行) | 分批审查 |
### 响应时间
| 优先级 | 响应时间 |
|--------|----------|
| 紧急 (P0) | 2 小时内 |
| 高 (P1) | 1 个工作日内 |
| 正常 (P2) | 2 个工作日内 |
| 低 (P3) | 1 周内 |
---
## 审查行为规范
### 应该做 ✅
- 提供建设性反馈
- 解释问题原因
- 给出具体修复建议
- 认可好的代码实践
- 保持礼貌和专业
### 不应该做 ❌
- 攻击性语言
- 模糊的批评
- 只提问题不提建议
- 忽视上下文
- 延迟审查无反馈
---
## 报告质量检查清单
### 完整性检查
- [ ] 所有 6 个维度已审查
- [ ] Critical/High 问题已记录
- [ ] 每个问题包含位置信息
- [ ] 每个问题有修复建议
- [ ] 报告格式符合模板
### 准确性检查
- [ ] 问题严重性分类正确
- [ ] 问题描述准确无误
- [ ] 修复建议可行有效
- [ ] 代码示例正确
### 可行性检查
- [ ] 修复建议可执行
- [ ] 优先级排序合理
- [ ] 工作量评估合理
---
## 审查者绩效
### KPI 指标
| 指标 | 目标值 |
|------|--------|
| 审查响应时间 | < 2 个工作日 |
| 问题发现率 | High 级别 ≥ 90% |
| 报告质量评分 | ≥ 80/100 |
| 修复建议采纳率 | ≥ 70% |
### 改进计划
未达标的审查者应：
1. 参加额外培训
2. 接受导师指导
3. 参与审查校准
4. 定期自我评估
---
## 参考
- [Review Dimensions](review-dimensions.md)
- [Issue Classification](issue-classification.md)
- [Document Standards](document-standards.md)

348
docs/skills/specs/reference-docs-spec.md Normal file
View File

@@ -0,0 +1,348 @@
# Reference Docs Spec
> 本文档定义 Skill 参考文档的生成规范和结构要求。
## 概述
参考文档是 Skill 的重要组成部分，为使用者和维护者提供清晰的指导。本规范确保所有 Skill 生成规范一致的参考文档。
## 参考文档类型
| 类型 | 用途 | 位置 |
|------|------|------|
| SKILL.md | 入口文件，总览和快速开始 | 技能根目录 |
| README.md | 详细文档，面向使用者 | 技能根目录 |
| Phase 文档 | 各阶段执行说明 | phases/ 目录 |
| 规格文档 | 领域规范和质量标准 | specs/ 目录 |
| 模板文档 | 输出模板和格式 | templates/ 目录 |
---
## SKILL.md 规范
### 必需章节
```markdown
# {Skill Name}
> One-liner 描述
## One-Liner
**简短描述** — 详细说明
## Pain Points Solved
| Pain Point | Current State | Solution |
|------------|---------------|----------|
| 问题1 | 当前状态 | 解决方案 |
| 问题2 | 当前状态 | 解决方案 |
## Skills List / 功能列表
| Skill | Function | Trigger |
|-------|----------|---------|
| 子技能1 | 功能描述 | 触发命令 |
| 子技能2 | 功能描述 | 触发命令 |
## Skills Details / 详细说明
### 子技能名
**One-Liner**: 一句话描述
**Trigger**:
```shell
/trigger-command <args>
```
**Features**:
- 特性1
- 特性2
**Architecture Overview**:
```plaintext
架构图/流程图
```
**Execution Flow**:
```plaintext
Phase 1: 描述
→ Action 1
→ Action 2
Phase 2: 描述
→ Action 1
→ Action 2
```
**Output Structure**:
```plaintext
输出目录结构
```
## Related Commands / 相关命令
- [相关命令链接](path)
## Best Practices / 最佳实践
1. 实践1
2. 实践2
## Usage Examples / 使用示例
```bash
# 示例1
/command args
# 示例2
/command --flag args
```
```
---
## README.md 规范
### 结构要求
```markdown
# {Skill Name}
详细标题和徽章
## 概述
详细描述技能的用途和价值
## 功能特性
- 特性1
- 特性2
## 安装配置
配置步骤
## 使用指南
详细使用说明
## 输出说明
输出内容和格式
## 故障排除
常见问题和解决方案
## 贡献指南
如何贡献
## 许可证
许可证信息
```
---
## Phase 文档规范
### Phase 文件命名
```
phases/
├── _orchestrator.md # 编排器（可选）
├── workflow.json # 工作流定义（可选）
├── 01-{phase-name}.md # Phase 1
├── 02-{phase-name}.md # Phase 2
└── 03-{phase-name}.md # Phase 3
```
### Phase 内容结构
```markdown
# Phase {N}: {Phase Name}
## 目标
简要说明本阶段目标
## 前置条件
- 条件1
- 条件2
## 执行步骤
### 步骤 1: {步骤名称}
**操作**: 具体操作描述
**输入**: 输入说明
**输出**: 输出说明
**验证**: 如何验证完成
### 步骤 2: ...
## 输出
本阶段产生的输出文件和数据
## 质量检查
- [ ] 检查项1
- [ ] 检查项2
## 阶段完成标准
满足以下条件视为阶段完成：
1. 标准1
2. 标准2
```
---
## Orchestrator 文档规范
### 编排器结构
```markdown
# Orchestrator
## 工作流类型
{Sequential|Autonomous}
## 状态定义
| 状态 | 描述 | 触发条件 |
|------|------|---------|
| state1 | 描述 | 触发条件 |
| state2 | 描述 | 触发条件 |
## 动作定义
| 动作 | 描述 | 前置状态 | 后置状态 |
|------|------|---------|---------|
| action1 | 描述 | state1 | state2 |
| action2 | 描述 | state2 | state3 |
## 路由逻辑
```typescript
// 伪代码描述状态转换
if (condition) {
return nextAction;
}
```
## 错误处理
- 错误情况1 → 处理方式
- 错误情况2 → 处理方式
```
---
## Action 文档规范
### Action 结构
```markdown
# {Action Name}
## 描述
详细描述动作的功能
## 输入参数
| 参数 | 类型 | 描述 | 必需 |
|------|------|------|------|
| param1 | type | 描述 | 是 |
| param2 | type | 描述 | 否 |
## 输出
| 字段 | 类型 | 描述 |
|------|------|------|
| field1 | type | 描述 |
| field2 | type | 描述 |
## 执行逻辑
1. 步骤1
2. 步骤2
3. 步骤3
## 错误处理
| 错误 | 处理 |
|------|------|
| error1 | 处理方式 |
## 示例
```typescript
// 示例代码
```
```
---
## 文档生成模板
### 使用模板的好处
- **一致性**: 所有 Skill 文档格式统一
- **完整性**: 确保所有必需章节都包含
- **可维护性**: 模板更新自动同步到所有文档
### 模板文件位置
```
docs/skills/templates/
├── skill-md.md # SKILL.md 模板
├── sequential-phase.md # 顺序阶段模板
├── autonomous-orchestrator.md # 自主编排模板
├── autonomous-action.md # 自主行动模板
└── review-report.md # 审查报告模板
```
---
## 文档质量检查
### 自动检查
```bash
# 使用 markdownlint
markdownlint **/*.md
# 检查链接
markdown-link-check **/*.md
# 检查拼写
cspell **/*.md
```
### 手动检查清单
- [ ] 所有章节完整
- [ ] 代码示例正确
- [ ] 链接有效
- [ ] 格式一致
- [ ] 语法正确
- [ ] 无拼写错误
---
## 参考
- [Document Standards](document-standards.md)
- [SKILL-DESIGN-SPEC](../_shared/SKILL-DESIGN-SPEC.md)

182
docs/skills/specs/review-dimensions.md Normal file
View File

@@ -0,0 +1,182 @@
# Review Dimensions
> 本文档定义代码审查的 6 个维度及每个维度的检查点。
## 概述
代码审查分为 6 个维度，每个维度包含多个检查点。审查时应对每个维度进行评分和记录。
## 审查维度
### 1. Correctness (正确性)
**关注点**: 代码逻辑是否正确，边界条件是否处理，错误处理是否完善。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 边界条件 | 空、null、undefined、数组越界 | Critical |
| 错误处理 | try-catch、错误传播、用户反馈 | High |
| 类型安全 | 类型转换、类型断言、any 使用 | High |
| 数据验证 | 输入验证、输出校验 | High |
| 并发安全 | 竞态条件、死锁风险 | Medium |
**评分标准**:
- **9-10**: 无明显问题，处理完善
- **7-8**: 有小问题但不影响功能
- **5-6**: 存在潜在问题，需要修复
- **< 5**: 严重问题，必须修复
---
### 2. Readability (可读性)
**关注点**: 代码是否易于理解，命名是否清晰，注释是否恰当。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 命名规范 | 变量、函数、类名语义化 | Medium |
| 函数长度 | 单一职责，长度适中 | Medium |
| 复杂度 | 圈复杂度、嵌套层级 | Medium |
| 注释质量 | 解释"为什么"而非"是什么" | Low |
| 代码格式 | 缩进、空行、对齐 | Low |
**评分标准**:
- **9-10**: 代码如散文般清晰
- **7-8**: 大部分清晰，少量困惑点
- **5-6**: 需要额外时间理解
- **< 5**: 代码难以理解
---
### 3. Performance (性能)
**关注点**: 算法效率、资源使用、I/O 优化。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 算法复杂度 | 时间/空间复杂度合理 | High |
| 数据结构选择 | 使用合适的数据结构 | High |
| I/O 优化 | 减少网络/磁盘访问 | Medium |
| 缓存策略 | 适当使用缓存 | Medium |
| 资源释放 | 内存泄漏、连接关闭 | High |
**评分标准**:
- **9-10**: 性能优化充分
- **7-8**: 性能可接受，有小优化空间
- **5-6**: 存在明显性能问题
- **< 5**: 严重性能问题
---
### 4. Security (安全)
**关注点**: 注入风险、敏感数据、权限控制。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 注入风险 | SQL、命令、XSS 注入 | Critical |
| 敏感数据 | 密码、密钥、token 处理 | Critical |
| 权限控制 | 认证、授权检查 | High |
| 数据验证 | 输入净化、输出编码 | High |
| 依赖安全 | 已知漏洞的依赖 | Medium |
**评分标准**:
- **9-10**: 无明显安全问题
- **7-8**: 低风险问题
- **5-6**: 中等风险，需要修复
- **< 5**: 高风险问题，必须修复
---
### 5. Testing (测试)
**关注点**: 测试覆盖度、测试质量、测试可维护性。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 覆盖度 | 单元测试、集成测试覆盖 | High |
| 边界测试 | 边界条件、异常情况测试 | Medium |
| 断言质量 | 断言有意义、不脆弱 | Medium |
| 测试可读性 | 测试意图清晰 | Low |
| Mock/Stub | 适当使用测试替身 | Medium |
**评分标准**:
- **9-10**: 测试充分，质量高
- **7-8**: 测试覆盖主要场景
- **5-6**: 测试不足，需要补充
- **< 5**: 缺少测试
---
### 6. Architecture (架构)
**关注点**: 设计模式、分层结构、依赖管理。
| 检查点 | 描述 | 严重性 |
|--------|------|--------|
| 设计模式 | 适当使用设计模式 | Medium |
| 模块化 | 高内聚、低耦合 | High |
| 依赖方向 | 依赖倒置、循环依赖 | High |
| 接口设计 | 接口稳定、扩展点明确 | Medium |
| 一致性 | 与现有架构风格一致 | Medium |
**评分标准**:
- **9-10**: 架构清晰，易于扩展
- **7-8**: 架构合理，小问题
- **5-6**: 架构问题，需要重构
- **< 5**: 架构混乱
---
## 审查报告格式
### 单维度报告模板
```markdown
### Correctness: 7/10
**发现的问题**:
#### [H] Null pointer risk
- **位置**: `src/auth.ts:45`
- **问题**: 用户对象可能为 null，直接访问属性会崩溃
- **建议**:
```typescript
// 添加空检查
if (user) {
return user.name;
}
return 'Anonymous';
```
#### [M] Missing error handling
- **位置**: `src/api.ts:78`
- **问题**: 网络请求没有错误处理
- **建议**: 添加 try-catch
**优点**:
- 边界条件检查完善
- 类型使用恰当
```
---
## 快速扫描检查点
快速扫描阶段只检查高优先级问题：
| 维度 | 高优先级检查点 |
|------|----------------|
| Correctness | 空指针、类型断言、未处理 Promise |
| Readability | 过长函数 (>50行)、过深嵌套 (>4层) |
| Performance | O(n²) 以上算法、循环中 I/O |
| Security | SQL 注入、XSS、硬编码密钥 |
| Testing | 关键路径缺少测试 |
| Architecture | 循环依赖、上帝对象 |
---
## 参考
- [Issue Classification](issue-classification.md)
- [Quality Standards](quality-standards.md)