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

9
docs/skills/claude-collaboration.md
View File

@@ -1,3 +1,8 @@
---
适用CLI: claude
分类: team
---
# Claude Skills - Team Collaboration
## One-Liner
@@ -18,7 +23,7 @@
| Skill | Function | Trigger |
|-------|----------|---------|
| `team-coordinate` | Universal team coordinator (dynamic role generation) | `/team-coordinate` |
| `team-lifecycle-v5` | Full lifecycle team (spec→impl→test→review) | `/team-lifecycle` |
| `team-lifecycle` | Full lifecycle team (spec→impl→test→review) | `/team-lifecycle` |
| `team-planex` | Plan-execute pipeline (plan while executing) | `/team-planex` |
| `team-review` | Code review team (scan→review→fix) | `/team-review` |
| `team-testing` | Testing team (strategy→generate→execute→analyze) | `/team-testing` |
@@ -68,7 +73,7 @@ Task Analysis → Generate Roles → Initialize Session → Create Task Chain
---
### team-lifecycle-v5
### team-lifecycle
**One-Liner**: Full lifecycle team — Complete pipeline from specification to implementation to testing to review

7
docs/skills/claude-index.md
View File

@@ -1,3 +1,8 @@
---
适用CLI: claude
分类: specialized
---
# Claude Skills Overview
## One-Liner
@@ -50,7 +55,7 @@ Claude Code Workflow supports two team architecture models:
- All worker roles are dynamically generated at runtime
- Supports dynamic teams for any task type
2. **team-lifecycle-v5** (Full Lifecycle Team)
2. **team-lifecycle** (Full Lifecycle Team)
- Based on team-worker agent architecture
- All workers share the same agent definition
- Role-specific Phase 2-4 loaded from markdown specs

65
docs/skills/core-skills.md
View File

@@ -1,12 +1,17 @@
---
适用CLI: claude
分类: specialized
---
# Core Skills
CCW includes **32 built-in skills** organized across 3 categories, with **15 workflow combinations** for common development scenarios.
CCW includes **33 built-in skills** organized across 3 categories, with **15 workflow combinations** for common development scenarios.
## Categories Overview
| Category | Count | Description |
|----------|-------|-------------|
| [Standalone](#standalone-skills) | 11 | Single-purpose skills for specific tasks |
| [Standalone](#standalone-skills) | 12 | Single-purpose skills for specific tasks |
| [Team](#team-skills) | 14 | Multi-agent collaborative skills |
| [Workflow](#workflow-skills) | 7 | Planning and execution pipeline skills |
@@ -255,15 +260,38 @@ Skill(skill="software-manual")
---
### command-generator
**Purpose**: Command file generation meta-skill
**Triggers**: `generate command`
**Description**: Generates CCW command files with standardized structure.
**Phases**:
1. Requirements Gathering
2. Command File Generation
3. Validation
**Outputs**: Command definition files
```bash
Skill(skill="command-generator")
```
---
## Team Skills
### team-lifecycle-v4
### team-lifecycle-v4 [已废弃]
**Purpose**: Unified team skill for full lifecycle - spec/impl/test
**Triggers**: `team lifecycle`
**Description**: Optimized cadence with inline discuss subagent and shared explore.
**Description**: **[已废弃]** 请使用 `team-lifecycle` (v5)。v4 保留用于向后兼容。
**Status**: Legacy - 已被 team-lifecycle (v5) 取代
**Roles**:
@@ -677,7 +705,7 @@ Skill(skill="workflow-lite-plan")
**Purpose**: Multi-CLI collaborative planning and execution skill
**Triggers**: `workflow-multi-cli-plan`, `workflow:lite-execute`
**Triggers**: `workflow-multi-cli-plan`, `workflow:multi-cli-plan`
**Description**: Route to multi-cli-plan or lite-execute with prompt enhancement.
@@ -812,7 +840,7 @@ Skill(skill="workflow-execute")
Skill(skill="review-cycle")
```
**Team Alternative**: `team-lifecycle-v4`
**Team Alternative**: `team-lifecycle`
---
@@ -1013,13 +1041,13 @@ Skill(skill="skill-tuning")
| Meta Skills | skill-generator, skill-tuning, workflow-skill-designer |
| Orchestrators | workflow-plan, workflow-lite-plan, workflow-multi-cli-plan |
| Executors | workflow-execute |
| Team Leads | team-lifecycle-v4, team-lifecycle-v3 |
| Team Leads | team-lifecycle (v5) |
### Integrations
| Integration | Skills |
|-------------|--------|
| ui-ux-pro-max | team-uidesign, team-frontend, team-lifecycle-v4 |
| ui-ux-pro-max | team-uidesign, team-frontend, team-lifecycle |
| ACE Context | workflow-multi-cli-plan |
| Chrome MCP | software-manual |
@@ -1055,18 +1083,27 @@ Quick reference for skill triggers:
| `brainstorm`, `头脑风暴` | brainstorm |
| `review code`, `code review`, `审查代码` | review-code |
| `manage issue` | issue-manage |
| `workflow-plan` | workflow-plan |
| `workflow-plan`, `workflow-plan-verify`, `workflow:replan` | workflow-plan |
| `workflow-execute` | workflow-execute |
| `workflow-lite-plan` | workflow-lite-plan |
| `workflow-multi-cli-plan` | workflow-multi-cli-plan |
| `workflow-multi-cli-plan`, `workflow:multi-cli-plan` | workflow-multi-cli-plan |
| `workflow-tdd-plan` | workflow-tdd-plan |
| `workflow-test-fix` | workflow-test-fix |
| `team lifecycle` | team-lifecycle-v4 |
| `workflow-test-fix`, `test fix workflow` | workflow-test-fix |
| `design workflow skill`, `create workflow skill`, `workflow skill designer` | workflow-skill-designer |
| `generate command` | command-generator |
| `team lifecycle` | team-lifecycle (v5) |
| `team brainstorm` | team-brainstorm |
| `team frontend` | team-frontend |
| `team issue` | team-issue |
| `team qa` | team-quality-assurance |
| `tech debt cleanup`, `技术债务` | team-tech-debt |
| `team qa`, `team quality-assurance` | team-quality-assurance |
| `tech debt cleanup`, `team tech-debt`, `技术债务` | team-tech-debt |
| `team ultra-analyze`, `team analyze` | team-ultra-analyze |
| `memory capture`, `compact session`, `记录`, `压缩会话` | memory-capture |
| `memory manage`, `update claude`, `update memory`, `generate docs`, `更新记忆`, `生成文档` | memory-manage |
| `generate spec`, `create specification`, `spec generator`, `workflow:spec` | spec-generator |
| `create skill`, `new skill` | skill-generator |
| `skill tuning`, `tune skill`, `skill diagnosis` | skill-tuning |
| `software manual`, `user guide`, `generate manual`, `create docs` | software-manual |
---

23
docs/skills/index.md
View File

@@ -1,6 +1,6 @@
# Skills Library
Complete reference for all **32 CCW built-in skills** across 3 categories, plus custom skill development.
Complete reference for all **33 CCW built-in skills** across 3 categories, plus custom skill development.
## What are Skills?
@@ -10,7 +10,7 @@ Skills are reusable, domain-specific capabilities that CCW can execute. Each ski
| Category | Count | Description |
|----------|-------|-------------|
| [Standalone](./core-skills.md#standalone-skills) | 11 | Single-purpose skills for specific tasks |
| [Standalone](./core-skills.md#standalone-skills) | 12 | Single-purpose skills for specific tasks |
| [Team](./core-skills.md#team-skills) | 14 | Multi-agent collaborative skills |
| [Workflow](./core-skills.md#workflow-skills) | 7 | Planning and execution pipeline skills |
@@ -23,14 +23,15 @@ Skills are reusable, domain-specific capabilities that CCW can execute. Each ski
| [brainstorm](./core-skills.md#brainstorm) | `brainstorm`, `头脑风暴` | Unified brainstorming with dual-mode operation |
| [ccw-help](./core-skills.md#ccw-help) | `ccw-help`, `ccw-issue` | Command help system |
| [memory-capture](./core-skills.md#memory-capture) | `memory capture`, `compact session` | Session compact or quick tips |
| [memory-manage](./core-skills.md#memory-manage) | `memory manage`, `update claude` | CLAUDE.md updates and docs generation |
| [memory-manage](./core-skills.md#memory-manage) | `memory manage`, `update claude`, `更新记忆` | CLAUDE.md updates and docs generation |
| [issue-manage](./core-skills.md#issue-manage) | `manage issue`, `list issues` | Interactive issue management |
| [review-code](./core-skills.md#review-code) | `review code`, `code review` | 6-dimensional code review |
| [review-cycle](./core-skills.md#review-cycle) | `workflow:review-cycle` | Review with automated fix |
| [skill-generator](./core-skills.md#skill-generator) | `create skill`, `new skill` | Meta-skill for creating skills |
| [skill-tuning](./core-skills.md#skill-tuning) | `skill tuning`, `tune skill` | Skill diagnosis and optimization |
| [spec-generator](./core-skills.md#spec-generator) | `generate spec`, `spec generator` | 6-phase specification generation |
| [spec-generator](./core-skills.md#spec-generator) | `generate spec`, `create specification`, `spec generator` | 6-phase specification generation |
| [software-manual](./core-skills.md#software-manual) | `software manual`, `user guide` | Interactive HTML documentation |
| [command-generator](./core-skills.md#command-generator) | `generate command` | Command file generation |
### Team Skills
@@ -42,25 +43,25 @@ Skills are reusable, domain-specific capabilities that CCW can execute. Each ski
| [team-issue](./core-skills.md#team-issue) | `team issue` | 6 | Issue resolution pipeline |
| [team-iterdev](./core-skills.md#team-iterdev) | `team iterdev` | 5 | Generator-critic loop |
| [team-planex](./core-skills.md#team-planex) | `team planex` | 3 | Plan-and-execute pipeline |
| [team-quality-assurance](./core-skills.md#team-quality-assurance) | `team qa` | 6 | QA testing workflow |
| [team-quality-assurance](./core-skills.md#team-quality-assurance) | `team qa`, `team quality-assurance` | 6 | QA testing workflow |
| [team-review](./core-skills.md#team-review) | `team-review` | 4 | Code scanning and fix |
| [team-roadmap-dev](./core-skills.md#team-roadmap-dev) | `team roadmap-dev` | 4 | Roadmap-driven development |
| [team-tech-debt](./core-skills.md#team-tech-debt) | `tech debt cleanup` | 6 | Tech debt identification |
| [team-tech-debt](./core-skills.md#team-tech-debt) | `tech debt cleanup`, `技术债务` | 6 | Tech debt identification |
| [team-testing](./core-skills.md#team-testing) | `team testing` | 5 | Progressive test coverage |
| [team-uidesign](./core-skills.md#team-uidesign) | `team uidesign` | 4 | UI design with tokens |
| [team-ultra-analyze](./core-skills.md#team-ultra-analyze) | `team analyze` | 5 | Deep collaborative analysis |
| [team-ultra-analyze](./core-skills.md#team-ultra-analyze) | `team ultra-analyze`, `team analyze` | 5 | Deep collaborative analysis |
### Workflow Skills
| Skill | Triggers | Description |
|-------|----------|-------------|
| [workflow-plan](./core-skills.md#workflow-plan) | `workflow-plan` | 4-phase planning with verification |
| [workflow-plan](./core-skills.md#workflow-plan) | `workflow-plan`, `workflow-plan-verify`, `workflow:replan` | 4-phase planning with verification |
| [workflow-lite-plan](./core-skills.md#workflow-lite-plan) | `workflow-lite-plan` | Lightweight planning |
| [workflow-multi-cli-plan](./core-skills.md#workflow-multi-cli-plan) | `workflow-multi-cli-plan` | Multi-CLI collaborative planning |
| [workflow-multi-cli-plan](./core-skills.md#workflow-multi-cli-plan) | `workflow-multi-cli-plan`, `workflow:multi-cli-plan` | Multi-CLI collaborative planning |
| [workflow-execute](./core-skills.md#workflow-execute) | `workflow-execute` | Task execution coordination |
| [workflow-tdd-plan](./core-skills.md#workflow-tdd-plan) | `workflow-tdd-plan` | TDD with Red-Green-Refactor |
| [workflow-test-fix](./core-skills.md#workflow-test-fix) | `workflow-test-fix` | Test-fix pipeline |
| [workflow-skill-designer](./core-skills.md#workflow-skill-designer) | `design workflow skill` | Meta-skill for workflow creation |
| [workflow-test-fix](./core-skills.md#workflow-test-fix) | `workflow-test-fix`, `test fix workflow` | Test-fix pipeline |
| [workflow-skill-designer](./core-skills.md#workflow-skill-designer) | `design workflow skill`, `create workflow skill` | Meta-skill for workflow creation |
## Workflow Combinations

52
docs/skills/reference.md
View File

@@ -1,6 +1,11 @@
---
适用CLI: claude
分类: specialized
---
# Skills Reference
Quick reference guide for all **32 CCW built-in skills**.
Quick reference guide for all **33 CCW built-in skills**.
## Core Skills
@@ -10,8 +15,8 @@ Quick reference guide for all **32 CCW built-in skills**.
| **review-code** | `review code`, `code review`, `审查代码` | Multi-dimensional code review (6 dimensions) |
| **review-cycle** | `workflow:review-cycle` | Code review + automated fix orchestration |
| **memory-capture** | `memory capture`, `compact session` | Session compact or quick tips capture |
| **memory-manage** | `memory manage`, `update claude`, `更新记忆` | CLAUDE.md updates and documentation generation |
| **spec-generator** | `generate spec`, `create specification` | 6-phase specification generator (brief → PRD → architecture → epics) |
| **memory-manage** | `memory manage`, `update claude`, `update memory`, `generate docs`, `更新记忆`, `生成文档` | CLAUDE.md updates and documentation generation |
| **spec-generator** | `generate spec`, `create specification`, `spec generator`, `workflow:spec` | 6-phase specification generator (brief → PRD → architecture → epics) |
| **skill-generator** | `create skill`, `new skill` | Meta-skill for creating new Claude Code skills |
| **skill-tuning** | `skill tuning`, `tune skill` | Universal skill diagnosis and optimization tool |
| **issue-manage** | `manage issue`, `list issues` | Interactive issue management (CRUD operations) |
@@ -24,18 +29,17 @@ Quick reference guide for all **32 CCW built-in skills**.
|-------|---------|---------|
| **workflow-plan** | `workflow-plan`, `workflow-plan-verify`, `workflow:replan` | 4-phase planning workflow with verification and interactive replanning |
| **workflow-lite-plan** | `workflow-lite-plan`, `workflow:lite-execute` | Lightweight planning and execution skill |
| **workflow-multi-cli-plan** | `workflow-multi-cli-plan` | Multi-CLI collaborative planning with ACE context engine |
| **workflow-multi-cli-plan** | `workflow-multi-cli-plan`, `workflow:multi-cli-plan` | Multi-CLI collaborative planning with ACE context engine |
| **workflow-execute** | `workflow-execute` | Coordinate agent execution for workflow tasks |
| **workflow-tdd-plan** | `workflow-tdd-plan`, `workflow-tdd-verify` | TDD workflow with Red-Green-Refactor task chain |
| **workflow-test-fix** | `workflow-test-fix`, `workflow-test-fix` | Unified test-fix pipeline with adaptive strategy |
| **workflow-skill-designer** | `design workflow skill`, `create workflow skill` | Meta-skill for designing orchestrator+phases structured workflow skills |
| **workflow-test-fix** | `workflow-test-fix`, `test fix workflow` | Unified test-fix pipeline with adaptive strategy |
| **workflow-skill-designer** | `design workflow skill`, `create workflow skill`, `workflow skill designer` | Meta-skill for designing orchestrator+phases structured workflow skills |
## Team Skills
| Skill | Trigger | Roles | Purpose |
|-------|---------|-------|---------|
| **team-lifecycle-v4** | `team lifecycle` | 8 | Full spec/impl/test lifecycle team |
| **team-lifecycle-v5** | `team lifecycle v5` | variable | Latest lifecycle team (team-worker architecture) |
| **team-lifecycle** | `team lifecycle` | variable | Full spec/impl/test lifecycle team (v5, team-worker architecture) |
| **team-coordinate** | `team coordinate` | variable | Generic team coordination (legacy) |
| **team-coordinate-v2** | - | variable | team-worker architecture coordination |
| **team-executor** | `team executor` | variable | Lightweight session execution |
@@ -50,7 +54,7 @@ Quick reference guide for all **32 CCW built-in skills**.
| **team-frontend** | `team frontend` | 6 | Frontend development with UI/UX integration |
| **team-review** | `team-review` | 4 | Code scanning and automated fix |
| **team-roadmap-dev** | `team roadmap-dev` | 4 | Roadmap-driven development |
| **team-tech-debt** | `tech debt cleanup`, `技术债务` | 6 | Tech debt identification and cleanup |
| **team-tech-debt** | `tech debt cleanup`, `team tech-debt`, `技术债务` | 6 | Tech debt identification and cleanup |
| **team-ultra-analyze** | `team ultra-analyze`, `team analyze` | 5 | Deep collaborative analysis |
## Command Generation Skills
@@ -63,11 +67,11 @@ Quick reference guide for all **32 CCW built-in skills**.
| Category | Count | Description |
|----------|-------|-------------|
| Core Skills | 11 | Single-purpose skills for specific tasks |
| Core Skills | 12 | Single-purpose skills for specific tasks |
| Workflow Skills | 7 | Planning and execution pipeline skills |
| Team Skills | 17+ | Multi-agent collaborative skills |
| Command Gen Skills | 1 | Command file generation |
| **Total** | **36+** | |
| **Total** | **37+** | |
## Usage
@@ -75,7 +79,7 @@ Quick reference guide for all **32 CCW built-in skills**.
```javascript
Skill(skill="brainstorm")
Skill(skill="team-lifecycle-v4", args="Build user authentication system")
Skill(skill="team-lifecycle", args="Build user authentication system")
Skill(skill="workflow-plan", args="--mode verify")
```
@@ -100,11 +104,12 @@ team lifecycle
| `workflow:review-cycle` | review-cycle |
| `workflow-plan` | workflow-plan |
| `workflow-lite-plan` | workflow-lite-plan |
| `workflow-multi-cli-plan` | workflow-multi-cli-plan |
| `workflow-multi-cli-plan`, `workflow:multi-cli-plan` | workflow-multi-cli-plan |
| `workflow-execute` | workflow-execute |
| `workflow-tdd-plan` | workflow-tdd-plan |
| `workflow-test-fix` | workflow-test-fix |
| `team lifecycle` | team-lifecycle-v4 (or v5) |
| `workflow-test-fix`, `test fix workflow` | workflow-test-fix |
| `design workflow skill`, `create workflow skill`, `workflow skill designer` | workflow-skill-designer |
| `team lifecycle` | team-lifecycle (v5) |
| `team planex` | team-planex |
| `team iterdev` | team-iterdev |
| `team issue` | team-issue |
@@ -115,15 +120,16 @@ team lifecycle
| `team frontend` | team-frontend |
| `team-review` | team-review |
| `team roadmap-dev` | team-roadmap-dev |
| `tech debt cleanup`, `技术债务` | team-tech-debt |
| `team analyze` | team-ultra-analyze |
| `tech debt cleanup`, `team tech-debt`, `技术债务` | team-tech-debt |
| `team ultra-analyze`, `team analyze` | team-ultra-analyze |
| `memory capture`, `compact session`, `记录`, `压缩会话` | memory-capture |
| `memory manage`, `update claude`, `更新记忆`, `生成文档` | memory-manage |
| `generate spec`, `create specification`, `spec generator` | spec-generator |
| `memory manage`, `update claude`, `update memory`, `generate docs`, `更新记忆`, `生成文档` | memory-manage |
| `generate spec`, `create specification`, `spec generator`, `workflow:spec` | spec-generator |
| `create skill`, `new skill` | skill-generator |
| `skill tuning`, `tune skill`, `skill diagnosis` | skill-tuning |
| `manage issue`, `list issues`, `edit issue` | issue-manage |
| `software manual`, `user guide`, `generate manual` | software-manual |
| `software manual`, `user guide`, `generate manual`, `create docs` | software-manual |
| `generate command` | command-generator |
## Team Skill Architecture
@@ -138,7 +144,7 @@ team lifecycle
### v5 Team Worker Roles
The latest team-lifecycle-v5 uses the team-worker agent with dynamic role assignment:
The latest team-lifecycle (v5) uses the team-worker agent with dynamic role assignment:
| Role | Prefix | Phase |
|------|--------|-------|
@@ -153,12 +159,12 @@ The latest team-lifecycle-v5 uses the team-worker agent with dynamic role assign
| Pattern | Skills Using It |
|---------|----------------|
| Orchestrator + Workers | team-lifecycle-v4, team-testing, team-quality-assurance |
| Orchestrator + Workers | team-lifecycle, team-testing, team-quality-assurance |
| Generator-Critic Loop | team-iterdev |
| Wave Pipeline | team-planex |
| Red-Green-Refactor | workflow-tdd-plan |
| Pure Orchestrator | workflow-plan, workflow-lite-plan |
| Progressive Phase Loading | workflow-plan, workflow-tdd-plan, team-lifecycle-v5 |
| Progressive Phase Loading | workflow-plan, workflow-tdd-plan, team-lifecycle |
::: info See Also
- [Core Skills Detail](./core-skills.md) - Detailed skill documentation

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)

245
docs/skills/templates/architecture-doc.md Normal file
View File

@@ -0,0 +1,245 @@
# Architecture Doc Template
> 用途: 架构文档模板，用于 spec-generator Phase 4 输出
## 模板
### _index.md 模板
```markdown
# Architecture - Index
> **Product**: {Product Name}
> **Generated**: {YYYY-MM-DD}
> **Session**: {session-id}
## Overview
架构概述（2-3 段）
## Architecture Principles
1. **Principle 1**: Description
2. **Principle 2**: Description
3. **Principle 3**: Description
## System Architecture
### High-Level Architecture
```plaintext
┌─────────────────────────────────────────────────┐
│ Frontend │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Web UI │ │ Mobile │ │ API │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Backend Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Gateway │ │ Services │ │ Events │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Data Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ | Database │ │ Cache │ │ Storage │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘
```
## Components
| Component | Responsibility | Technology |
|-----------|----------------|------------|
| Component 1 | 描述 | 技术栈 |
| Component 2 | 描述 | 技术栈 |
| Component 3 | 描述 | 技术栈 |
## Technology Stack
### Frontend
| Layer | Technology | Rationale |
|-------|-----------|-----------|
| Framework | {framework} | 选择理由 |
| State | {state lib} | 选择理由 |
| UI | {ui lib} | 选择理由 |
### Backend
| Layer | Technology | Rationale |
|-------|-----------|-----------|
| Runtime | {runtime} | 选择理由 |
| Framework | {framework} | 选择理由 |
| Database | {database} | 选择理由 |
## Architecture Decisions
详见各 ADR 文档：
- [ADR-001-{title}](./ADR-001-{slug}.md)
- [ADR-002-{title}](./ADR-002-{slug}.md)
## Requirements Traceability
| Requirement | ADR | Component |
|-------------|-----|-----------|
| REQ-001 | ADR-001 | Service A |
| REQ-002 | ADR-002 | Service B |
## Change Log
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial version |
```
---
### ADR-*.md 模板
```markdown
# ADR-{NNN}: {Decision Title}
> **Status**: {Accepted|Deprecated|Superseded}
> **Date**: {YYYY-MM-DD}
> **Decision Type**: {Technical|Process|Architecture}
## Context
描述背景和问题：
- 当前状况
- 需要解决的问题
- 约束条件
## Decision
**决策内容**: 一句话概括
详细说明决策内容
### Options Considered
| Option | Pros | Cons | Selected |
|--------|------|------|----------|
| Option 1 | 优点 | 缺点 | No |
| Option 2 | 优点 | 缺点 | **Yes** |
| Option 3 | 优点 | 缺点 | No |
### Rationale
选择此方案的原因：
1. Reason 1
2. Reason 2
3. Reason 3
## Consequences
### Positive
- Benefit 1
- Benefit 2
### Negative
- Risk 1
- Risk 2
### Mitigation
如何缓解负面影响
## Related Requirements
| Requirement | Relation |
|-------------|----------|
| REQ-001 | Enables |
| NFR-PERF-001 | Addresses |
## Alternatives Considered
1. Alternative 1: Description - Rejected because...
2. Alternative 2: Description - Rejected because...
## References
- [Related Doc](path)
- [External Reference](url)
```
## 使用说明
1. **触发**: spec-generator Phase 4
2. **输入**: Phase 3 Requirements (PRD)
3. **输出**: architecture/ 目录，包含 _index.md 和所有 ADR 文件
4. **验证**: 确保追溯链接有效
---
## 示例
### 简化示例 - ADR-001.md
```markdown
# ADR-001: Use Operational Transformation for Real-Time Sync
> **Status**: Accepted
> **Date**: 2026-03-01
> **Decision Type**: Technical
## Context
实时协作平台需要支持多用户同时编辑同一文档。
- 简单的"最后写入胜出"策略会导致数据丢失
- 需要自动解决编辑冲突
- 网络延迟和离线编辑需要支持
## Decision
**决策内容**: 使用 Operational Transformation (OT) 算法实现实时同步
OT 通过转换操作序列来解决冲突，确保最终一致性。
### Options Considered
| Option | Pros | Cons | Selected |
|--------|------|------|----------|
| Last Write Wins | 简单 | 数据丢失 | No |
| OT (Yjs) | 成熟方案 | 复杂度高 | **Yes** |
| CRDT | 理论优雅 | 性能开销 | No |
### Rationale
1. **成熟度**: Yjs 是成熟的 OT 实现，被广泛应用
2. **性能**: OT 比 CRDT 性能更好，适合文档编辑场景
3. **社区**: 活跃的社区支持和丰富的集成
## Consequences
### Positive
- 自动解决冲突，无需用户干预
- 支持离线编辑，重连后自动同步
- 低延迟，良好的用户体验
### Negative
- 实现复杂，学习曲线陡峭
- 需要维护操作历史，内存开销
### Mitigation
- 使用成熟的 Yjs 库，降低实现复杂度
- 实现历史压缩策略，控制内存使用
## Related Requirements
| Requirement | Relation |
|-------------|----------|
| REQ-001 | Enables |
| NFR-PERF-001 | Addresses |
```

260
docs/skills/templates/autonomous-action.md Normal file
View File

@@ -0,0 +1,260 @@
# Autonomous Action Template
> 用途: 自主行动模板，用于 Autonomous 类型 Skill 的具体行动
## 模板
```markdown
# Action: {Action Name}
> **Skill**: {Skill Name}
> **Action Type**: {Analysis|Execution|Verification}
> **Estimated Duration**: {X minutes}
## Description
详细描述这个行动的目的和功能
## Trigger Conditions
| Condition | Description | Check Method |
|-----------|-------------|--------------|
| condition1 | 描述 | 如何检查 |
| condition2 | 描述 | 如何检查 |
## Input Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| param1 | string | Yes | 参数描述 | - |
| param2 | number | No | 参数描述 | 42 |
| param3 | array | No | 参数描述 | [] |
## Output
| Field | Type | Description |
|-------|------|-------------|
| result1 | string | 结果描述 |
| result2 | object | 结果描述 |
| success | boolean | 行动是否成功 |
## Execution Logic
### Step 1: {Step Name}
**Description**: 步骤描述
**Implementation**:
```typescript
// 示例代码
const step1Result = await doSomething(input);
if (!step1Result) {
throw new Error('Step 1 failed');
}
```
**Validation**: 如何验证步骤成功
### Step 2: {Step Name}
**Description**: 步骤描述
**Implementation**:
```typescript
// 示例代码
const step2Result = await process(step1Result);
```
**Validation**: 如何验证步骤成功
### Step 3: {Step Name}
...
## Error Handling
| Error | Cause | Handling | Retry |
|-------|-------|----------|-------|
| ErrorType1 | 原因描述 | 处理方式 | Yes/No |
| ErrorType2 | 原因描述 | 处理方式 | Yes/No |
**Error Recovery Logic**:
```typescript
try {
return await execute();
} catch (error) {
if (error instanceof RecoverableError) {
return await recover(error);
}
throw error;
}
```
## Side Effects
| Effect | Description | Mitigation |
|--------|-------------|------------|
| Side effect 1 | 描述 | 缓解措施 |
| Side effect 2 | 描述 | 缓解措施 |
## Dependencies
| Dependency | Type | Version | Description |
|------------|------|---------|-------------|
| dep1 | internal | - | 内部依赖描述 |
| dep2 | external | ^1.0.0 | 外部依赖描述 |
## Testing
### Test Cases
| Case | Input | Expected Output |
|------|-------|-----------------|
| Normal case | `{param: "value"}` | `{result: "expected"}` |
| Edge case | `{param: null}` | `{result: "default"}` |
| Error case | `{param: "invalid"}` | Throws Error |
### Test Implementation
```typescript
describe('ActionName', () => {
it('should handle normal case', async () => {
const result = await actionName({ param: 'value' });
expect(result).toEqual({ result: 'expected' });
});
it('should handle edge case', async () => {
const result = await actionName({ param: null });
expect(result).toEqual({ result: 'default' });
});
it('should throw on invalid input', async () => {
await expect(actionName({ param: 'invalid' }))
.rejects.toThrow(Error);
});
});
```
## Metrics
| Metric | Type | Unit |
|--------|------|------|
| duration | histogram | milliseconds |
| success_rate | gauge | percentage |
| error_count | counter | count |
## Example Usage
```typescript
// 基本使用
const result = await actionName({
param1: 'value1',
param2: 100
});
console.log(result);
// 带重试
const result = await actionName.withRetry({
param1: 'value1'
}, { maxRetries: 3 });
// 带回调
await actionName.withCallback({
param1: 'value1'
}, {
onProgress: (progress) => console.log(progress),
onComplete: (result) => console.log('Done', result)
});
```
```
## 使用说明
1. **触发**: skill-generator Phase 3 (Autonomous 模式)
2. **输入**: Phase 2 skill-config.json
3. **输出**: actions/{action-name}.md
4. **命名**: 使用动词-名词格式 (如 collect-context.md)
---
## 示例
### 简化示例
```markdown
# Action: quick-scan
> **Skill**: review-code
> **Action Type**: Analysis
> **Estimated Duration**: 5 minutes
## Description
快速扫描目标代码，识别高风险区域，为深度审查提供焦点
## Trigger Conditions
| Condition | Description | Check Method |
|-----------|-------------|--------------|
| context_collected | 上下文收集完成 | state.context != null |
| target_exists | 目标路径有效 | file exists check |
## Input Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| files | array | Yes | 要扫描的文件列表 | - |
| dimensions | array | No | 要检查的维度 | ["all"] |
| risk_threshold | number | No | 风险阈值 | 0.5 |
## Output
| Field | Type | Description |
|-------|------|-------------|
| risk_areas | array | 高风险区域列表 |
| scan_summary | object | 扫描摘要 |
| recommendations | array | 建议的审查重点 |
## Execution Logic
### Step 1: 按文件类型分组
```typescript
const groups = groupBy(files, f => f.extension);
// ts/tsx -> TypeScript review rules
// py -> Python review rules
```
### Step 2: 应用快速检查规则
```typescript
const risks = [];
for (const file of files) {
const fileRisks = applyQuickChecks(file);
risks.push(...fileRisks);
}
```
### Step 3: 聚合和排序
```typescript
const aggregated = aggregateByLocation(risks);
const sorted = sortBySeverity(aggregated);
```
## Error Handling
| Error | Cause | Handling | Retry |
|-------|-------|----------|-------|
| FileAccessError | 文件无法读取 | 跳过文件，记录警告 | No |
| ParseError | 代码解析失败 | 标记为需要人工审查 | No |
## Testing
| Case | Input | Expected Output |
|------|-------|-----------------|
| Normal | 10 files | risk_areas non-empty |
| Empty | 0 files | risk_areas empty |
| ParseError | Invalid code | Area marked for manual review |
```

311
docs/skills/templates/autonomous-orchestrator.md Normal file
View File

@@ -0,0 +1,311 @@
# Autonomous Orchestrator Template
> 用途: 自主编排器模板，用于 Autonomous 类型 Skill
## 模板
```markdown
# Orchestrator
> **Skill**: {Skill Name}
> **Type**: Autonomous (State-Driven)
> **Version**: 1.0.0
## Overview
本编排器使用状态驱动的决策引擎，根据当前状态自动选择下一步行动。
## State Machine
### State Definition
| State | Description | Entry Condition | Exit Actions |
|-------|-------------|-----------------|--------------|
| `initialized` | 初始状态，等待目标 | Skill 启动 | 转到 `collecting_context` |
| `collecting_context` | 收集上下文信息 | 进入状态 | 收集完成后转到 `analyzing` |
| `analyzing` | 分析目标内容 | 上下文就绪 | 分析完成后转到 `planning` 或 `executing` |
| `planning` | 制定执行计划 | 需要复杂规划 | 计划完成后转到 `executing` |
| `executing` | 执行具体行动 | 计划就绪 | 执行完成后转到 `verifying` |
| `verifying` | 验证执行结果 | 执行完成 | 验证通过转到 `completed`，否则转到 `analyzing` |
| `completed` | 任务完成 | 所有目标达成 | 结束 |
| `error` | 错误状态 | 发生错误 | 根据错误类型恢复或终止 |
### State Transitions
```plaintext
┌─────────────────┐
│ initialized │
└────────┬────────┘
│
▼
┌─────────────────┐
│collecting_context│
└────────┬────────┘
│
▼
┌─────────────────┐
│ analyzing │◄─────────┐
└────────┬────────┘ │
│ │
┌────────┴────────┐ │
│ │ │
▼ ▼ │
┌──────────┐ ┌──────────┐ │
│ planning │ │executing │────┘
└────┬─────┘ └────┬─────┘
│ │
│ ┌────────┴────────┐
│ │ │
▼ ▼ ▼
┌──────────────────────────────┐
│ verifying │
└───────────┬──────────────────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│completed │ │ error │
└──────────┘ └──────────┘
```
## Action Registry
### Available Actions
| Action | From States | To States | Description |
|--------|------------|-----------|-------------|
| `collect_context` | `initialized`, `error` | `analyzing` | 收集必要的上下文信息 |
| `analyze_target` | `collecting_context` | `planning` or `executing` | 分析目标，决定需要规划还是直接执行 |
| `create_plan` | `analyzing` | `executing` | 创建详细执行计划 |
| `execute_action` | `planning`, `analyzing` | `verifying` | 执行具体行动 |
| `verify_result` | `executing` | `completed` or `analyzing` | 验证执行结果 |
| `handle_error` | Any | `error` or `analyzing` | 处理错误情况 |
| `complete` | `verifying` | `completed` | 标记任务完成 |
## Routing Logic
### Decision Tree
```typescript
// 伪代码：状态路由决策
function route(currentState: State, context: Context): Action {
switch (currentState) {
case 'initialized':
return Action.COLLECT_CONTEXT;
case 'collecting_context':
if (context.hasEnoughData()) {
return Action.ANALYZE_TARGET;
}
return Action.COLLECT_CONTEXT; // 继续收集
case 'analyzing':
if (context.needsPlanning()) {
return Action.CREATE_PLAN;
}
return Action.EXECUTE_ACTION;
case 'planning':
return Action.EXECUTE_ACTION;
case 'executing':
return Action.VERIFY_RESULT;
case 'verifying':
if (context.isResultValid()) {
return Action.COMPLETE;
}
return Action.ANALYZE_TARGET; // 重新分析
case 'error':
if (context.isRecoverable()) {
return Action.ANALYZE_TARGET;
}
throw new UnrecoverableError(context.error);
default:
throw new UnknownStateError(currentState);
}
}
```
### Condition Evaluation
| Condition | Evaluation | Result |
|-----------|------------|--------|
| `hasEnoughData()` | context.files.length > 0 | Boolean |
| `needsPlanning()` | context.complexity > threshold | Boolean |
| `isResultValid()` | validation.checks passed | Boolean |
| `isRecoverable()` | error.type in recoverableErrors | Boolean |
## State Persistence
### State File Structure
```json
{
"state": "analyzing",
"history": [
{ "state": "initialized", "timestamp": "2026-03-01T10:00:00Z" },
{ "state": "collecting_context", "timestamp": "2026-03-01T10:00:05Z" },
{ "state": "analyzing", "timestamp": "2026-03-01T10:00:15Z" }
],
"context": {
"target": "...",
"files": [],
"findings": []
},
"metrics": {
"actionsExecuted": 3,
"errors": 0,
"startTime": "2026-03-01T10:00:00Z"
}
}
```
### Save/Restore
- **Save**: 每次状态转换后保存
- **Restore**: Skill 重启时从文件恢复
- **Reset**: 新任务开始时重置状态
## Error Handling
### Error Classification
| Error Type | Severity | Recovery |
|------------|----------|----------|
| `ContextError` | Medium | 重新收集上下文 |
| `ValidationError` | High | 重新分析并调整 |
| `ExecutionError` | High | 尝试替代行动 |
| `FatalError` | Critical | 终止并报告 |
### Error Recovery Strategies
```typescript
function handleError(error: Error, state: State): RecoveryAction {
if (error instanceof ContextError) {
return RecoveryAction.RETRY_WITH_ALTERNATIVE_SOURCE;
}
if (error instanceof ValidationError) {
return RecoveryAction.ADJUST_AND_RETRY;
}
if (error instanceof ExecutionError) {
return RecoveryAction.TRY_ALTERNATIVE_ACTION;
}
return RecoveryAction.ABORT;
}
```
## Metrics and Observability
### Tracked Metrics
| Metric | Type | Description |
|--------|------|-------------|
| `state_transitions` | Counter | 状态转换次数 |
| `action_duration` | Histogram | 每个行动的执行时间 |
| `error_count` | Counter | 错误发生次数 |
| `completion_rate` | Gauge | 任务完成率 |
### Logging
```typescript
// 每次状态转换记录日志
log.info('State transition', {
from: oldState,
to: newState,
action: executedAction,
timestamp: now()
});
```
## Testing
### Test Scenarios
1. **Happy Path**: 正常流程从初始化到完成
2. **Error Recovery**: 错误发生后正确恢复
3. **State Persistence**: 状态正确保存和恢复
4. **Edge Cases**: 边界条件处理
### Test Example
```typescript
describe('Orchestrator', () => {
it('should complete happy path', async () => {
const orchestrator = new Orchestrator();
await orchestrator.run({ target: 'test' });
expect(orchestrator.state).toBe('completed');
});
it('should recover from errors', async () => {
const orchestrator = new Orchestrator();
// 模拟错误后恢复
await expect(orchestrator.run()).toEventuallyComplete();
});
});
```
```
## 使用说明
1. **触发**: skill-generator Phase 3 (Autonomous 模式)
2. **输入**: Phase 2 skill-config.json
3. **输出**: phases/_orchestrator.md
4. **验证**: 确保状态转换逻辑完整
---
## 示例
### 简化示例
```markdown
# Orchestrator
> **Skill**: review-code
> **Type**: Autonomous (State-Driven)
> **Version**: 1.0.0
## State Transitions
```plaintext
initialized → collecting_context → analyzing
↓
┌───────┴────────┐
↓ ↓
quick_scan deep_review
↓ ↓
└───────┬────────┘
↓
generating_report
↓
completed
```
## Action Registry
| Action | Description |
|--------|-------------|
| `collect_context` | 收集目标文件信息 |
| `quick_scan` | 快速扫描识别高风险区域 |
| `deep_review` | 按 6 维度深度审查 |
| `generate_report` | 生成审查报告 |
## Routing Logic
```typescript
function route(state, context) {
if (state === 'initialized') return 'collect_context';
if (state === 'collecting_context') return 'quick_scan';
if (state === 'analyzing') {
if (context.hasHighRiskAreas()) return 'deep_review';
return 'generate_report';
}
if (state === 'deep_review') return 'generate_report';
return 'complete';
}
```
```

311
docs/skills/templates/epics-template.md Normal file
View File

@@ -0,0 +1,311 @@
# Epics Template
> 用途: Epic 和 Story 文档模板，用于 spec-generator Phase 5 输出
## 模板
### _index.md 模板
```markdown
# Epics - Index
> **Product**: {Product Name}
> **Generated**: {YYYY-MM-DD}
> **Session**: {session-id}
## Overview
Epic 概述（2-3 段）
## Epic Summary
| Epic | Title | Stories | Status | Priority |
|------|-------|---------|--------|----------|
| EPIC-001 | Epic 标题 | N stories | {Draft|Ready|In Progress} | {P0|P1|P2} |
| EPIC-002 | Epic 标题 | N stories | {Draft|Ready|In Progress} | {P0|P1|P2} |
## Dependency Graph
```plaintext
EPIC-001 (Foundation)
│
├── EPIC-002 (Feature A)
│ │
│ └── EPIC-004 (Enhancement)
│
└── EPIC-003 (Feature B)
```
## MVP Scope
以下 Epic 属于 MVP:
- [ ] EPIC-001: {Epic title}
- [ ] EPIC-002: {Epic title}
- [ ] EPIC-003: {Epic title}
**Estimated MVP Duration**: {X weeks}
## Requirements Traceability
| Requirement | Epic(s) | Story Count |
|-------------|---------|-------------|
| REQ-001 | EPIC-001 | 3 |
| REQ-002 | EPIC-001, EPIC-002 | 5 |
## Architecture Traceability
| ADR | Epic(s) | Component |
|-----|---------|-----------|
| ADR-001 | EPIC-001 | Service A |
| ADR-002 | EPIC-002 | Service B |
## Epics
详见各 Epic 文档：
- [EPIC-001-{title}](./EPIC-001-{slug}.md)
- [EPIC-002-{title}](./EPIC-002-{slug}.md)
## Change Log
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial version |
```
---
### EPIC-*.md 模板
```markdown
# EPIC-{NNN}: {Epic Title}
> **Priority**: {P0|P1|P2|P3}
> **Status**: {Draft|Ready|In Progress|Done}
> **MVP**: {Yes|No}
> **Created**: {YYYY-MM-DD}
## Description
详细描述 Epic 的目标和范围
## Business Value
| Value | Description |
|-------|-------------|
| 业务价值1 | 描述 |
| 业务价值2 | 描述 |
## Related Requirements
| Requirement | Relation |
|-------------|----------|
| REQ-001 | Addresses |
| REQ-002 | Partially Addresses |
## Stories
| Story | Title | Points | Status |
|-------|-------|--------|--------|
| STORY-001 | Story 标题 | {points} | {Todo|In Progress|Done} |
| STORY-002 | Story 标题 | {points} | {Todo|In Progress|Done} |
### STORY-001: {Story Title}
**As a** {user type},
**I want** {action},
**So that** {benefit}.
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
**Technical Notes**:
- Notes for developers
- API endpoints, data models, etc.
**Dependencies**:
- STORY-002 (must complete first)
- External dependency description
---
### STORY-002: {Story Title}
... (same structure)
## Dependencies
| Depends On | Type | Epic |
|------------|------|------|
| EPIC-XXX | Finish-to-Start | {epic title} |
| External API | External | {description} |
## Estimate
| Category | Estimate |
|----------|----------|
| Development | {X days} |
| Testing | {X days} |
| Documentation | {X days} |
| **Total** | **{X days}** |
## Definition of Done
- [ ] All stories completed and tested
- [ ] Code reviewed
- [ ] Documentation updated
- [ ] Acceptance criteria met
- [ ] No known bugs
## Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| Risk 1 | High/Low | 缓解措施 |
| Risk 2 | High/Low | 缓解措施 |
```
## 使用说明
1. **触发**: spec-generator Phase 5
2. **输入**: Phase 4 Architecture
3. **输出**: epics/ 目录，包含 _index.md 和所有 Epic 文件
4. **验证**: 确保追溯链接有效
---
## 示例
### 简化示例 - _index.md
```markdown
# Epics - Index
> **Product**: Real-Time Collaboration Platform
> **Generated**: 2026-03-01
> **Session**: SPEC-rtc-platform-2026-03-01
## Overview
本文档定义实时协作平台的 Epic 和 Story 分解。
## Epic Summary
| Epic | Title | Stories | Status | Priority |
|------|-------|---------|--------|----------|
| EPIC-001 | Core Sync Engine | 4 | Ready | P0 |
| EPIC-002 | User Interface | 3 | Ready | P1 |
| EPIC-003 | Conflict Resolution | 2 | Draft | P0 |
## Dependency Graph
```plaintext
EPIC-001 (Core Sync Engine)
│
├── EPIC-002 (User Interface)
│
└── EPIC-003 (Conflict Resolution)
```
## MVP Scope
以下 Epic 属于 MVP:
- [ ] EPIC-001: Core Sync Engine
- [ ] EPIC-002: User Interface
**Estimated MVP Duration**: 6 weeks
```
### 简化示例 - EPIC-001.md
```markdown
# EPIC-001: Core Sync Engine
> **Priority**: P0
> **Status**: Ready
> **MVP**: Yes
> **Created**: 2026-03-01
## Description
实现基于 OT 算法的实时文档同步引擎，支持多用户并发编辑。
## Business Value
| Value | Description |
|-------|-------------|
| 无缝协作 | 用户可同时编辑而无需担心冲突 |
| 数据安全 | 自动保存，防止数据丢失 |
## Related Requirements
| Requirement | Relation |
|-------------|----------|
| REQ-001 | Addresses |
| NFR-PERF-001 | Must satisfy |
## Stories
| Story | Title | Points | Status |
|-------|-------|--------|--------|
| STORY-001 | WebSocket Connection | 5 | Todo |
| STORY-002 | Operation Transformer | 8 | Todo |
| STORY-003 | State Persistence | 3 | Todo |
| STORY-004 | Conflict Resolution | 5 | Todo |
### STORY-001: WebSocket Connection
**As a** system,
**I want** to establish WebSocket connections,
**So that** clients can receive real-time updates.
**Acceptance Criteria**:
- [ ] Server accepts WebSocket connections
- [ ] Connection authentication implemented
- [ ] Reconnection logic handles network issues
**Technical Notes**:
- Use ws library for Node.js
- Implement JWT-based authentication
- Store active connections in memory
**Dependencies**:
- None
---
### STORY-002: Operation Transformer
**As a** system,
**I want** to transform concurrent operations,
**So that** conflicts are automatically resolved.
**Acceptance Criteria**:
- [ ] OT transform function implemented
- [ ] Handles insert and delete operations
- [ ] Maintains document consistency
**Technical Notes**:
- Use Yjs library for OT implementation
- Implement transform() function per OT spec
**Dependencies**:
- STORY-001 must complete first
## Estimate
| Category | Estimate |
|----------|----------|
| Development | 10 days |
| Testing | 5 days |
| Documentation | 2 days |
| **Total** | **17 days** |
## Definition of Done
- [ ] All stories completed and tested
- [ ] Unit tests coverage > 80%
- [ ] API documentation complete
- [ ] Performance benchmarks meet NFR-PERF-001
```

295
docs/skills/templates/issue-template.md Normal file
View File

@@ -0,0 +1,295 @@
# Issue Template
> 用途: Issue 记录模板，用于代码审查和问题追踪
## 模板
```markdown
### [{Severity}] {Issue Title}
**Location**: `{file-path}:{line}`
**Category**: {Correctness|Readability|Performance|Security|Testing|Architecture}
**Dimension**: {Dimension Name}
#### Issue Description
{Detailed description of the issue, 1-3 sentences}
#### Current Code
```typescript
// {file-path}:{line}
{current code snippet}
```
#### Severity
{Critical|High|Medium|Low|Info} - {为什么是这个严重性的理由}
#### Recommendation
```typescript
// Suggested fix
{fixed code snippet}
```
**Explanation**: {解释为什么这样修复}
#### Impact
- **Breaks**: {什么功能会受影响}
- **Risk**: {风险等级}
- **Users Affected**: {受影响的用户范围}
#### Effort
- **Complexity**: {Low|Medium|High}
- **Estimated Time**: {X hours/days}
- **Files to Change**: {N files}
#### Related
- **Requirement**: {REQ-XXX} (if applicable)
- **ADR**: {ADR-XXX} (if applicable)
- **Similar Issues**: {link to similar issues}
---
**Tags**: {tag1}, {tag2}, {tag3}
```
## 使用说明
1. **触发**: 任何问题记录场景
2. **输入**: 问题发现时的上下文
3. **输出**: 结构化 issue 记录
4. **位置**: 可在审查报告、Issue 追踪系统等使用
---
## 变体
### 简化变体 (用于快速记录)
```markdown
### [{Severity}] {Title}
**Location**: `{file}:{line}`
**Category**: {category}
{Brief description}
**Fix**:
```typescript
// Before
{code}
// After
{fix}
```
```
### 安全 Issue 变体
```markdown
### [{Severity}] Security: {Title}
**Location**: `{file}:{line}`
**CVSS**: {score}
**CWE**: {CWE-ID}
**Vulnerability**: {漏洞描述}
**Exploit Scenario**: {攻击场景}
**Mitigation**:
```typescript
{修复代码}
```
**References**:
- {OWASP link}
- {CVE link}
```
### 性能 Issue 变体
```markdown
### [{Severity}] Performance: {Title}
**Location**: `{file}:{line}`
**Complexity**: {O(n) / O(n²) / etc.}
**Current Performance**: {当前性能指标}
**Target Performance**: {目标性能指标}
**Bottleneck**: {瓶颈描述}
**Optimization**:
```typescript
{优化代码}
```
**Expected Improvement**: {预期改进}
```
---
## 示例
### 完整示例
```markdown
### [C] SQL Injection Vulnerability
**Location**: `src/auth/login.ts:45`
**Category**: Security
**Dimension**: Security
#### Issue Description
User input is directly concatenated into SQL query without sanitization,
allowing attackers to inject arbitrary SQL commands.
#### Current Code
```typescript
// src/auth/login.ts:45
const userId = req.params.id;
const query = `SELECT * FROM users WHERE id='${userId}'`;
const result = await db.query(query);
```
#### Severity
Critical - Allows unauthorized data access and potential data breach
#### Recommendation
```typescript
// Use parameterized query
const userId = req.params.id;
const query = 'SELECT * FROM users WHERE id = ?';
const result = await db.query(query, [userId]);
```
**Explanation**: Parameterized queries prevent SQL injection by separating
SQL logic from data. The database driver properly escapes the parameter.
#### Impact
- **Breaks**: User authentication, data integrity
- **Risk**: Data breach, unauthorized access
- **Users Affected**: All users
#### Effort
- **Complexity**: Low
- **Estimated Time**: 1 hour
- **Files to Change**: 3 files (all query locations)
#### Related
- **Requirement**: NFR-SEC-001
- **ADR**: ADR-002 (Security Standards)
- **Similar Issues**: None in this codebase
---
**Tags**: security, sql-injection, critical, authentication
```
### 简化示例
```markdown
### [M] Long Function
**Location**: `src/utils/data.ts:123`
**Category**: Readability
Function `processUserData` is 120 lines long, handles too many responsibilities.
**Fix**:
```typescript
// Before: One big function
function processUserData(user) {
// 120 lines...
}
// After: Split into smaller functions
function processUserData(user) {
validateUser(user);
enrichUserData(user);
saveUser(user);
}
```
```
### 安全 Issue 示例
```markdown
### [C] Hardcoded API Key
**Location**: `src/config/api.ts:10`
**CVSS**: 7.5 (High)
**CWE**: 798
**Vulnerability**: API key is hardcoded in source code and will be exposed
in version control.
**Exploit Scenario**: Anyone with repository access can extract the API key
and make unauthorized API calls.
**Mitigation**:
```typescript
// Before
const API_KEY = 'sk-1234567890abcdef';
// After
const API_KEY = process.env.API_KEY || throw new Error('API_KEY required');
```
**References**:
- OWASP: https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_cryptographic_key
- CWE-798: https://cwe.mitre.org/data/definitions/798.html
```
### 性能 Issue 示例
```markdown
### [H] Nested Loop Performance
**Location**: `src/processing/analyzer.ts:67`
**Complexity**: O(n²)
**Current Performance**: Processing 10k items takes ~5 seconds
**Target Performance**: Should be < 1 second
**Bottleneck**: Nested loop comparing every item with every other item.
**Optimization**:
```typescript
// Before: O(n²)
for (let i = 0; i < items.length; i++) {
for (let j = i + 1; j < items.length; j++) {
if (compare(items[i], items[j])) {
// ...
}
}
}
// After: O(n) using Map
const map = new Map();
for (const item of items) {
const key = item.category;
if (!map.has(key)) {
map.set(key, []);
}
map.get(key).push(item);
}
```
**Expected Improvement**: ~100x faster for large datasets
```
```

160
docs/skills/templates/product-brief.md Normal file
View File

@@ -0,0 +1,160 @@
# Product Brief Template
> 用途: 产品简介文档模板，用于 spec-generator Phase 2 输出
## 模板
```markdown
# {Product Name} - Product Brief
> **Generated**: {YYYY-MM-DD}
> **Source**: spec-generator Phase 2
> **Session**: {session-id}
## One-Liner
**简短描述** — 详细说明
## Problem Statement
### Pain Points
| Pain Point | Current State | Impact | Solution |
|------------|---------------|--------|----------|
| Pain Point 1 | 当前问题描述 | 影响程度 | 解决方案概述 |
| Pain Point 2 | 当前问题描述 | 影响程度 | 解决方案概述 |
| Pain Point 3 | 当前问题描述 | 影响程度 | 解决方案概述 |
## Target Audience
### Primary Users
| User Type | Description | Key Needs |
|-----------|-------------|-----------|
| 用户类型1 | 描述 | 核心需求 |
| 用户类型2 | 描述 | 核心需求 |
### Secondary Users
| User Type | Description | Key Needs |
|-----------|-------------|-----------|
| 用户类型 | 描述 | 核心需求 |
## Solution Overview
### Core Value Proposition
一句话描述核心价值主张
### Key Features
| Feature | Description | Priority |
|---------|-------------|----------|
| Feature 1 | 功能描述 | Must/Should/Could |
| Feature 2 | 功能描述 | Must/Should/Could |
| Feature 3 | 功能描述 | Must/Should/Could |
## MoSCoW Analysis
| Category | Features | Rationale |
|----------|----------|-----------|
| **Must Have** | Feature 1, Feature 2 | 核心功能，必须实现 |
| **Should Have** | Feature 3, Feature 4 | 重要功能，尽快实现 |
| **Could Have** | Feature 5 | 有价值的功能，时间允许时实现 |
| **Won't Have** | Feature 6 | 明确不实现的功能 |
## Success Metrics
| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| 指标1 | 目标值 | 测量方法 |
| 指标2 | 目标值 | 测量方法 |
| 指标3 | 目标值 | 测量方法 |
## Feasibility Assessment
### Technical Feasibility
- **技术栈**: {技术栈选择}
- **复杂度**: {高/中/低}
- **风险**: {主要技术风险}
### Resource Requirements
| Resource | Estimate | Notes |
|----------|----------|-------|
| 开发时间 | {estimate} | |
| 测试时间 | {estimate} | |
| 其他资源 | {estimate} | |
## Next Steps
1. [ ] Review and approve Product Brief
2. [ ] Proceed to Requirements (PRD) phase
3. [ ] Conduct technical feasibility study
## References
- [Discovery Context](../discovery-context.json)
- [Session Config](../spec-config.json)
```
## 使用说明
1. **触发**: spec-generator Phase 2
2. **输入**: Phase 1 Discovery 结果 + 多 CLI 分析结果
3. **输出**: product-brief.md
4. **验证**: 确保所有必需字段填充完整
---
## 示例
### 简化示例
```markdown
# Real-Time Collaboration Platform - Product Brief
> **Generated**: 2026-03-01
> **Session**: SPEC-rtc-platform-2026-03-01
## One-Liner
**实时协作平台** — 让团队成员能够同时编辑文档并进行实时沟通
## Problem Statement
### Pain Points
| Pain Point | Current State | Impact | Solution |
|------------|---------------|--------|----------|
| 版本冲突 | 多人编辑同一文件时产生冲突 | 降低效率 | OT 算法自动合并 |
| 沟通割裂 | 编辑和沟通在不同工具间切换 | 上下文丢失 | 内嵌即时通讯 |
| 状态不明 | 不知道谁在编辑什么 | 协作混乱 | 实时光标显示 |
## Target Audience
### Primary Users
| User Type | Description | Key Needs |
|-----------|-------------|-----------|
| 内容团队 | 需要协作编辑文档的团队 | 实时同步、冲突解决 |
| 开发团队 | 需要协作编写代码的团队 | 代码合并、审查 |
## MoSCoW Analysis
| Category | Features | Rationale |
|----------|----------|-----------|
| **Must Have** | 实时编辑、冲突解决、用户在线状态 | 核心功能 |
| **Should Have** | 评论系统、版本历史、权限管理 | 重要功能 |
| **Could Have** | AI 辅助编辑、模板系统 | 增值功能 |
| **Won't Have** | 视频通话（使用现有工具） | 非核心 |
## Success Metrics
| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| 冲突自动解决率 | >95% | 系统日志统计 |
| 实时延迟 | <200ms | 性能监控 |
| 用户活跃度 | 日活 >1000 | 分析平台 |
```

262
docs/skills/templates/requirements-prd.md Normal file
View File

@@ -0,0 +1,262 @@
# Requirements PRD Template
> 用途: 产品需求文档模板，用于 spec-generator Phase 3 输出
## 模板
### _index.md 模板
```markdown
# Requirements (PRD) - Index
> **Product**: {Product Name}
> **Generated**: {YYYY-MM-DD}
> **Session**: {session-id}
## Overview
产品需求概述（2-3 段）
## Requirements Summary
| Category | Count | Status |
|----------|-------|--------|
| Functional Requirements | {N} | |
| Non-Functional Requirements | {N} | |
## MoSCoW Summary
| Category | Count | Items |
|----------|-------|-------|
| Must | {N} | REQ-001, REQ-002, ... |
| Should | {N} | REQ-003, REQ-004, ... |
| Could | {N} | REQ-005, ... |
## Requirements Traceability
### From Product Brief
| Brief Feature | Requirement(s) |
|---------------|----------------|
| Feature 1 | REQ-001, REQ-002 |
| Feature 2 | REQ-003 |
### To Architecture
| Requirement | ADR |
|-------------|-----|
| REQ-001 | ADR-001 |
| REQ-002 | ADR-002 |
## Functional Requirements
详见各需求文档：
- [REQ-001-{title}](./REQ-001-{slug}.md)
- [REQ-002-{title}](./REQ-002-{slug}.md)
## Non-Functional Requirements
详见各 NFR 文档：
- [NFR-PERF-001](./NFR-PERF-001.md)
- [NFR-SEC-001](./NFR-SEC-001.md)
## Change Log
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial version |
```
---
### REQ-*.md 模板
```markdown
# REQ-{NNN}: {Requirement Title}
> **Type**: Functional Requirement
> **Priority**: {Must|Should|Could}
> **Status**: {Draft|Approved|Implemented}
> **Created**: {YYYY-MM-DD}
## Description
详细描述需求内容
## User Story
**As a** {user type},
**I want** {action/feature},
**So that** {benefit/value}.
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Functional Specifications
### Input
| Input | Type | Description | Validation |
|-------|------|-------------|------------|
| input1 | type | 描述 | 验证规则 |
### Output
| Output | Type | Description |
|--------|------|-------------|
| output1 | type | 描述 |
### Business Rules
1. Rule 1
2. Rule 2
## Dependencies
| Dependency | Type | Status |
|------------|------|--------|
| REQ-XXX | Functional | |
| NFR-XXX | Non-Functional | |
## References
- [Product Brief](../product-brief.md) - Related Feature
- [ADR-XXX](../architecture/ADR-XXX.md) - Technical Decision
```
---
### NFR-*.md 模板
```markdown
# NFR-{TYPE}-{NNN}: {Non-Functional Requirement Title}
> **Type**: {Performance|Security|Scalability|Reliability|Usability}
> **Priority**: {Must|Should|Could}
> **Status**: {Draft|Approved}
> **Created**: {YYYY-MM-DD}
## Description
详细描述非功能需求
## Metrics
| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| metric1 | value | 测量方法 |
| metric2 | value | 测量方法 |
## Specifications
### {Type} Requirements
1. Requirement 1
2. Requirement 2
### Testing Strategy
- Test 1: Description
- Test 2: Description
## Related Requirements
| Requirement | Relation |
|-------------|----------|
| REQ-001 | Impacts |
| REQ-002 | Enables |
```
## 使用说明
1. **触发**: spec-generator Phase 3
2. **输入**: Phase 2 Product Brief
3. **输出**: requirements/ 目录，包含 _index.md 和所有需求文件
4. **验证**: 确保追溯链接有效
---
## 示例
### 简化示例 - _index.md
```markdown
# Requirements (PRD) - Index
> **Product**: Real-Time Collaboration Platform
> **Generated**: 2026-03-01
> **Session**: SPEC-rtc-platform-2026-03-01
## Overview
本文档包含实时协作平台的完整需求规格说明。
## Requirements Summary
| Category | Count | Status |
|----------|-------|--------|
| Functional Requirements | 8 | Draft |
| Non-Functional Requirements | 3 | Draft |
## MoSCoW Summary
| Category | Count | Items |
|----------|-------|-------|
| Must | 4 | REQ-001, REQ-002, REQ-003, REQ-004 |
| Should | 3 | REQ-005, REQ-006, REQ-007 |
| Could | 1 | REQ-008 |
```
### 简化示例 - REQ-001.md
```markdown
# REQ-001: Real-Time Document Sync
> **Type**: Functional Requirement
> **Priority**: Must
> **Status**: Draft
> **Created**: 2026-03-01
## Description
用户编辑文档时，更改应实时同步到所有协作者
## User Story
**As a** content editor,
**I want** to see others' changes in real-time,
**So that** we can collaborate without conflicts.
## Acceptance Criteria
- [ ] Changes sync within 200ms
- [ ] Multiple users can edit simultaneously
- [ ] Conflicts are auto-resolved using OT algorithm
- [ ] User cursors are visible to others
## Functional Specifications
### Input
| Input | Type | Description | Validation |
|-------|------|-------------|------------|
| document_id | string | Document identifier | Required, valid UUID |
| operations | array | OT operations | Required, non-empty |
### Output
| Output | Type | Description |
|--------|------|-------------|
| status | string | "synced" or "conflict" |
| merged_ops | array | Merged operations |
## Dependencies
| Dependency | Type | Status |
|------------|------|--------|
| NFR-PERF-001 | Performance | |
| ADR-001 | OT Algorithm Choice | |
```

382
docs/skills/templates/review-report.md Normal file
View File

@@ -0,0 +1,382 @@
# Review Report Template
> 用途: 代码审查报告模板，用于 review-code 输出
## 模板
```markdown
# Code Review Report
> **Target**: {target-path}
> **Generated**: {YYYY-MM-DD HH:MM}
> **Reviewer**: {skill-name}
> **Session**: {session-id}
## Executive Summary
| Metric | Value |
|--------|-------|
| **Overall Score** | {X/100} |
| Files Reviewed | {N} |
| Total Issues | {N} |
| Critical | {N} |
| High | {N} |
| Medium | {N} |
| Low | {N} |
### Quality Grade
{A/B/C/D}
**Rationale**: 简要说明评分理由
---
## Dimensions Summary
| Dimension | Score | Issues | Top Issues |
|-----------|-------|--------|------------|
| Correctness | {X/10} | {N} | [C] Issue 1, [H] Issue 2 |
| Readability | {X/10} | {N} | [M] Issue 3 |
| Performance | {X/10} | {N} | [H] Issue 4 |
| Security | {X/10} | {N} | [C] Issue 5 |
| Testing | {X/10} | {N} | [L] Issue 6 |
| Architecture | {X/10} | {N} | [M] Issue 7 |
---
## Risk Areas Identified
| Area | Risk Level | Files | Issues |
|------|------------|-------|--------|
| {area1} | {High/Medium/Low} | {file list} | {N} issues |
| {area2} | {High/Medium/Low} | {file list} | {N} issues |
---
## Detailed Findings
### Correctness: {X/10}
**Summary**: 简要总结正确性方面的发现
#### [C] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述（1-2 句话）
**Severity**: Critical - 必须修复
**Recommendation**:
```typescript
// Before (problematic)
const code = "problematic code";
// After (fixed)
const code = "fixed code";
```
**Reference**: [specs/review-dimensions.md](specs/review-dimensions.md) - Correctness section
---
#### [H] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: High - 应该修复
**Recommendation**:
```typescript
// Fix suggestion
const fixedCode = "fixed code";
```
---
### Readability: {X/10}
**Summary**: 简要总结可读性方面的发现
#### [M] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: Medium - 建议改进
**Recommendation**:
```typescript
// Suggestion
const betterCode = "more readable code";
```
---
### Performance: {X/10}
**Summary**: 简要总结性能方面的发现
#### [H] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: High - 影响性能
**Recommendation**:
```typescript
// Optimization
const optimizedCode = "optimized code";
```
---
### Security: {X/10}
**Summary**: 简要总结安全方面的发现
#### [C] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: Critical - 安全风险
**Recommendation**:
```typescript
// Security fix
const secureCode = "secure code";
```
---
### Testing: {X/10}
**Summary**: 简要总结测试方面的发现
#### [L] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: Low - 建议添加测试
**Recommendation**:
```typescript
// Test example
describe('Function', () => {
it('should handle edge case', () => {
// test code
});
});
```
---
### Architecture: {X/10}
**Summary**: 简要总结架构方面的发现
#### [M] {Issue Title}
**Location**: `{file-path}:{line}`
**Issue**: 问题描述
**Severity**: Medium - 架构改进建议
**Recommendation**:
```typescript
// Architecture suggestion
// Consider using {pattern} instead
```
---
## Recommendations
### Priority Actions (Do First)
1. **[Critical] Fix security vulnerability in {file}:{line}**
- Action: 修复 SQL 注入风险
- Estimate: 1 hour
2. **[Critical] Handle null pointer in {file}:{line}**
- Action: 添加空检查
- Estimate: 30 minutes
### High Priority (Do Soon)
3. **[High] Optimize performance bottleneck in {file}:{line}**
- Action: 重构算法
- Estimate: 2 hours
### Medium Priority (Do When Possible)
4. **[Medium] Improve code readability in {file}:{line}**
- Action: 重构函数
- Estimate: 1 hour
---
## Appendix
### Files Reviewed
| File | Lines | Issues | Score |
|------|-------|--------|-------|
| {file1} | {N} | {N} | {X/10} |
| {file2} | {N} | {N} | {X/10} |
| {file3} | {N} | {N} | {X/10} |
### Issue Distribution
```
Critical: ████ 4
High: ████████ 8
Medium: ████████████ 12
Low: ██████ 6
```
### Review Metadata
| Key | Value |
|-----|-------|
| Review Duration | {X minutes} |
| Review Method | {Quick Scan + Deep Review} |
| Dimensions Covered | {All / Specific} |
| Review Configuration | {config details} |
---
## Next Steps
1. **Review this report**: 确认所有问题理解正确
2. **Fix Critical issues**: 优先修复高风险问题
3. **Run review-cycle**: 使用 `/review-cycle` 自动修复和验证
4. **Re-review**: 修复后重新审查确认
---
**Generated by**: {skill-name} v{version}
**Review Standards**: [specs/review-dimensions.md](specs/review-dimensions.md)
```
## 使用说明
1. **触发**: review-code Phase 4
2. **输入**: Phase 3 的 findings 数据
3. **输出**: review-report.md
4. **格式**: Markdown，支持 GitHub/GitLab 渲染
---
## 示例
### 简化示例
```markdown
# Code Review Report
> **Target**: src/auth/**
> **Generated**: 2026-03-01 10:30
> **Reviewer**: review-code
## Executive Summary
| Metric | Value |
|--------|-------|
| **Overall Score** | 65/100 |
| Files Reviewed | 5 |
| Total Issues | 15 |
| Critical | 2 |
| High | 4 |
| Medium | 6 |
| Low | 3 |
### Quality Grade
**C - Needs Improvement**
存在 2 个严重安全问题需要立即修复
---
## Dimensions Summary
| Dimension | Score | Issues |
|-----------|-------|--------|
| Correctness | 6/10 | 3 |
| Readability | 7/10 | 2 |
| Performance | 7/10 | 2 |
| Security | 4/10 | 4 |
| Testing | 5/10 | 2 |
| Architecture | 6/10 | 2 |
---
## Detailed Findings
### Security: 4/10
#### [C] SQL Injection Risk
**Location**: `src/auth/login.ts:45`
**Issue**: 用户输入直接拼接 SQL，可被注入攻击
**Severity**: Critical - 必须修复
**Recommendation**:
```typescript
// Before (vulnerable)
const query = `SELECT * FROM users WHERE id='${userId}'`;
// After (safe)
const query = 'SELECT * FROM users WHERE id = ?';
await db.query(query, [userId]);
```
---
### Correctness: 6/10
#### [H] Null Pointer Risk
**Location**: `src/auth/user.ts:23`
**Issue**: user 对象可能为 null
**Severity**: High - 可能导致崩溃
**Recommendation**:
```typescript
// Add null check
if (user?.profile) {
return user.profile.name;
}
return 'Anonymous';
```
---
## Recommendations
### Priority Actions
1. **[Critical] Fix SQL injection in login.ts:45**
- Use parameterized queries
- Estimate: 1 hour
2. **[Critical] Add null check in user.ts:23**
- Add optional chaining
- Estimate: 15 minutes
```

218
docs/skills/templates/sequential-phase.md Normal file
View File

@@ -0,0 +1,218 @@
# Sequential Phase Template
> 用途: 顺序执行阶段的模板，用于 Sequential 类型 Skill
## 模板
```markdown
# Phase {N}: {Phase Name}
> **Skill**: {Skill Name}
> **Phase Number**: {N}
> **Execution Mode**: Sequential
> **Estimated Duration**: {X minutes}
## Objective
本阶段的目标描述（1-2 句话）
## Prerequisites
在执行本阶段之前，必须满足以下条件：
- [ ] Prerequisite 1
- [ ] Prerequisite 2
- [ ] Prerequisite 3
## Input Data
| Data | Source | Format | Required |
|------|--------|--------|----------|
| data1 | {source} | {format} | Yes |
| data2 | {source} | {format} | Yes |
| data3 | {source} | {format} | No |
## Execution Steps
### Step 1: {Step Name}
**Description**: 详细描述步骤内容
**Action**: 具体要执行的操作
**Validation**: 如何验证步骤完成
**Output**: 产出什么数据或文件
### Step 2: {Step Name}
**Description**: 详细描述步骤内容
**Action**: 具体要执行的操作
**Validation**: 如何验证步骤完成
**Output**: 产出什么数据或文件
### Step 3: {Step Name}
...
## Output
本阶段将产生以下输出：
| Output | Format | Location | Description |
|--------|--------|----------|-------------|
| output1 | {format} | {path} | 描述 |
| output2 | {format} | {path} | 描述 |
## Quality Checks
执行完成后，检查以下项目：
- [ ] 所有步骤已执行
- [ ] 输出文件已创建
- [ ] 输出格式正确
- [ ] 数据完整性验证
- [ ] 无错误或警告
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Error 1 | 原因描述 | 解决方案 |
| Error 2 | 原因描述 | 解决方案 |
## Next Phase
完成本阶段后，进入 **Phase {N+1}: {Next Phase Name}**
**传递数据**:
- data1 → Next phase input 1
- data2 → Next phase input 2
## Completion Criteria
本阶段被视为完成，当：
1. 所有执行步骤已完成
2. 所有质量检查已通过
3. 输出文件已生成并验证
4. 无未处理的错误
```
## 使用说明
1. **触发**: skill-generator Phase 3 (Sequential 模式)
2. **输入**: Phase 2 生成的目录结构
3. **输出**: phases/NN-{phase-name}.md
4. **命名**: 使用数字前缀排序 (01-, 02-, 03-)
---
## 示例
### 简化示例
```markdown
# Phase 1: Context Collection
> **Skill**: review-code
> **Phase Number**: 1
> **Execution Mode**: Sequential
> **Estimated Duration**: 5 minutes
## Objective
收集目标代码的上下文信息，识别技术栈和代码结构
## Prerequisites
- [ ] Phase 0: 规范学习已完成
- [ ] 目标路径已提供
- [ ] specs/ 文档已阅读
## Input Data
| Data | Source | Format | Required |
|------|--------|--------|----------|
| target_path | User input | string | Yes |
| review_dimensions | specs/review-dimensions.md | list | Yes |
## Execution Steps
### Step 1: 扫描目标目录
**Description**: 使用 Glob 或 ACE 搜索工具扫描目标路径
**Action**:
```bash
# 扫描所有源文件
Glob(pattern="{target}/**/*.ts")
Glob(pattern="{target}/**/*.tsx")
```
**Validation**: 至少找到 1 个文件
**Output**: file_list.json
### Step 2: 识别技术栈
**Description**: 分析配置文件和依赖，识别技术栈
**Action**:
- 读取 package.json
- 读取 tsconfig.json
- 分析导入语句
**Validation**: 识别出主要语言和框架
**Output**: tech_stack.json
### Step 3: 构建代码模型
**Description**: 构建代码的依赖关系图
**Action**: 使用 ACE 工具分析代码关系
**Validation**: 依赖图构建完成
**Output**: code_model.json
## Output
| Output | Format | Location | Description |
|--------|--------|----------|-------------|
| file_list | JSON | state/context/files.json | 所有扫描到的文件 |
| tech_stack | JSON | state/context/tech-stack.json | 技术栈信息 |
| code_model | JSON | state/context/code-model.json | 代码关系图 |
## Quality Checks
- [ ] 文件列表非空
- [ ] 技术栈识别准确
- [ ] 代码模型无循环依赖警告
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| No files found | 路径错误或路径为空 | 提示用户检查路径 |
| Unknown tech | 无法识别技术栈 | 使用默认配置 |
## Next Phase
完成本阶段后，进入 **Phase 2: Quick Scan**
**传递数据**:
- file_list → Quick Scan 输入
- tech_stack → Quick Scan 输入
## Completion Criteria
1. 所有文件已扫描
2. 技术栈已识别
3. 代码模型已构建
4. state/context/ 目录已创建
```

274
docs/skills/templates/skill-md.md Normal file
View File

@@ -0,0 +1,274 @@
# SKILL.md Template
> 用途: Skill 入口文档模板 (SKILL.md)，用于 skill-generator
## 模板
```markdown
# {Skill Name}
> **Type**: {Sequential|Autonomous}
> **Version**: {1.0.0}
> **Status**: {Stable|Experimental}
> **Category**: {Team|Workflow|Standalone|Specialized}
## One-Liner
**简短描述** — 详细说明
## Pain Points Solved
| Pain Point | Current State | {Skill Name} Solution |
|------------|---------------|----------------------|
| Pain Point 1 | 当前问题描述 | 解决方案描述 |
| Pain Point 2 | 当前问题描述 | 解决方案描述 |
| Pain Point 3 | 当前问题描述 | 解决方案描述 |
## Skills List / 功能列表
| Skill / Phase | Function | Trigger |
|---------------|----------|---------|
| {sub-skill-1} | 功能描述 | 触发命令 |
| {sub-skill-2} | 功能描述 | 触发命令 |
## Skills Details / 详细说明
### {Sub-Skill Name}
**One-Liner**: 一句话描述
**Trigger**:
```shell
/trigger-command <args>
/trigger-command --flag <value>
```
**Features**:
- Feature 1
- Feature 2
- Feature 3
**Architecture Overview**:
```plaintext
┌─────────────────────────────────────────────────┐
│ {Skill Name} Architecture │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Phase 1 │ -> │ Phase 2 │ -> │ Phase 3 │ │
│ │ {Desc} │ │ {Desc} │ │ {Desc} │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────┘
```
**⚠️ Mandatory Prerequisites**:
> **Do not skip**: Before executing any operations, you **must** completely read the following documents.
**Specification Documents** (required):
| Document | Purpose | Priority |
|----------|---------|----------|
| [specs/{doc-name}.md](specs/{doc-name}.md) | Description | **P0 - Highest** |
**Template Files** (read before generation):
| Document | Purpose |
|----------|---------|
| [templates/{template}.md](templates/{template}.md) | Template description |
**Execution Flow**:
```plaintext
Phase 1: {Phase Name}
-> Action 1: Description
-> Action 2: Description
-> Output: {output description}
Phase 2: {Phase Name}
-> Action 1: Description
-> Action 2: Description
-> Output: {output description}
Phase 3: {Phase Name}
-> Action 1: Description
-> Output: {output description}
```
**Output Structure**:
```plaintext
{output-directory}/
├── file1.md # Description
├── file2.md # Description
└── subdirectory/ # Description
├── file3.md
└── file4.md
```
---
### {Another Sub-Skill}
**One-Liner**: 一句话描述
**Trigger**:
```shell
/trigger-command <args>
```
**Features**:
- Feature 1
- Feature 2
**Use Cases**:
- Use case 1
- Use case 2
## Related Commands
- [Related Command 1](../commands/claude/{command}.md)
- [Related Command 2](../commands/claude/{command}.md)
## Best Practices
1. **Practice 1**: Description
2. **Practice 2**: Description
3. **Practice 3**: Description
## Usage Examples
```bash
# Example 1: Description
/trigger-command <args>
# Example 2: Description
/trigger-command --flag <args>
# Example 3: Description
/trigger-command sub-command <args>
```
## Output Example
```
### Example Output Title
**Location**: `file/path:line`
**Issue**: Description of the finding
**Severity**: {Critical|High|Medium|Low}
**Recommendation**:
```typescript
// Before (problematic)
const code = "problematic code";
// After (fixed)
const code = "fixed code";
```
**Reference**: [specs/reference.md](specs/reference.md) - Section name
```
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Problem 1 | Solution 1 |
| Problem 2 | Solution 2 |
| Problem 3 | Solution 3 |
## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial release |
```
## 使用说明
1. **触发**: skill-generator Phase 2
2. **输入**: Phase 1 skill-config.json
3. **输出**: SKILL.md
4. **验证**: 确保所有链接有效，所有章节完整
---
## 示例
### 简化示例
```markdown
# Review Code
> **Type**: Autonomous
> **Version**: 1.0.0
> **Status**: Stable
> **Category**: Specialized
## One-Liner
**多维度代码审查** — 通过 6 个维度自动分析代码质量并提供修复建议
## Pain Points Solved
| Pain Point | Current State | Review Code Solution |
|------------|---------------|----------------------|
| 审查维度不全 | 手动审查容易遗漏 | 6 维度自动审查 |
| 问题分类混乱 | 难以区分严重性 | 结构化问题分类 |
| 修复建议模糊 | 缺乏具体方案 | 可执行的修复建议 |
## Skills List
| Skill | Function | Trigger |
|-------|----------|---------|
| review-code | 6 维度代码审查 | `/review-code <target>` |
| review-cycle | 审查和修复循环 | `/review-cycle <target>` |
## Skills Details
### review-code
**One-Liner**: 6 维度代码审查
**Trigger**:
```shell
/review-code src/**
/review-code --dimensions=sec,perf src/
```
**Features**:
- 6 维度审查：正确性、可读性、性能、安全、测试、架构
- 快速扫描识别高风险区域
- 深度审查聚焦关键问题
- 结构化报告分级输出
**Execution Flow**:
```plaintext
Phase 0: Specification Study (Mandatory)
-> Read specs/review-dimensions.md
-> Read specs/issue-classification.md
Phase 1: Collect Context
-> Scan target files
-> Identify tech stack
-> Output: state.context
Phase 2: Quick Scan
-> Identify high-risk areas
-> Output: state.risk_areas
Phase 3: Deep Review (per dimension)
-> Analyze each dimension
-> Record findings
-> Output: state.findings[]
Phase 4: Generate Report
-> Aggregate findings
-> Generate review-report.md
```
## Best Practices
1. **完整阅读规范**: 执行前必须阅读 specs/ 文档
2. **快速扫描先行**: 先识别高风险，再深度审查
3. **结构化报告**: 使用生成的报告作为修复指南
```