OpenCode 开发工作使用指南
基于 superpowers、oh-my-openagent、OpenSpec 和 everything-claude-code 的最佳实践
目录
- 概述
- 基础设施要求
- 开发流程总览
- 阶段一：需求分析与技术方案
- 阶段二：技术方案生成
- 阶段三：开发执行
- 阶段四：单元测试
- 阶段五：Code Review
- 阶段六：Git Worktree 合并
- 阶段七：测试用例生成
- ECC高级模式
- 自主工作流
- 会话与记忆管理
- 验证与质量保证
- 技能参考
- 命令参考
1. 概述
本指南整合了以下开源项目的最佳实践：
| 项目 | 贡献 |
|---|---|
| obra/superpowers | 14个核心开发技能 |
| code-yeongyu/oh-my-openagent | 多模型编排框架 |
| Fission-AI/OpenSpec | 规格驱动开发框架 |
| affaan-m/everything-claude-code | 完整开发工作流 |
核心原则
1. Agent-First — 将任务委托给专业代理处理
2. Test-Driven — 先写测试，测试驱动开发
3. Security-First — 从不妥协安全性
4. Plan Before Execute — 复杂功能先规划后执行
5. Evidence Over Claims — 验证后再宣布成功
2. 基础设施要求
2.1 必须安装
| 组件 | 安装方式 | 说明 |
|---|---|---|
| OpenCode | 官网安装 | 基础运行环境 |
| superpowers | plugin marketplace add obra/superpowers then plugin install superpowers@superpowers | 14个核心技能 |
| oh-my-openagent | plugin marketplace add code-yeongyu/oh-my-openagent | ultrawork 懒人模式 |
2.2安装步骤
# 1. 安装 OpenCode (如果未安装)
npm i -g opencode-ai
# 2. 安装 superpowers (必须)
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
# 3. 可选: 安装 oh-my-openagent
Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/dev/docs/guide/installation.md
4. 开发流程总览
1. Agent-First — 将任务委托给专业代理处理
2. Test-Driven — 先写测试，测试驱动开发
3. Security-First — 从不妥协安全性
4. Plan Before Execute — 复杂功能先规划后执行
5. Evidence Over Claims — 验证后再宣布成功
5. 阶段一：需求分析与技术方案
5.1 使用 brainstorming 技能
当您有新的开发需求时，首先使用 brainstorming 技能进行需求分析：
/brainstorm
或者直接描述您的需求，AI 会自动触发 brainstorming 流程。
5.2 brainstorming 流程
┌─────────────────────────────────────────┐
│ brainstorming 流程 │
├─────────────────────────────────────────┤
│ │
│ 1. 理解真实意图 │
│ ↓ │
│ 2. 探索需求细节 │
│ ↓ │
│ 3. 识别遗漏和歧义 │
│ ↓ │
│ 4. 展示设计方案 │
│ ↓ │
│ 5. 获得批准后继续 │
│ │
└─────────────────────────────────────────┘
5.3 输出：需求分析文档
brainstorming 完成后，您将获得：
- 需求澄清: 明确的功能描述
- 范围定义: 包含和不包含的功能
- 初步设计: 架构思路和技术选型
- 风险识别: 潜在问题和挑战
6. 阶段二：技术方案生成
6.1 使用 writing-plans 技能
在获得需求批准后，使用 writing-plans 技能生成详细的技术方案：
/write-plan
或者直接说明需要生成技术方案。
6.2 技术方案模板 (基于 OpenSpec)
生成的方案应包含以下结构：
# [功能名称] 技术方案
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** [一句话描述要构建的内容]
**Architecture:** [2-3 句关于架构方法的描述]
**Tech Stack:** [关键技术/库]
---
## 1. Proposal (提案)
### Intent (意图)
[描述你想要实现的目标]
### Scope (范围)
- **In Scope:** [包含的功能]
- **Out of Scope:** [不包含的功能]
### Approach (方法)
[实现方法的概述]
---
## 2. Technical Design (技术设计)
### Architecture Decisions (架构决策)
- [决策1]: [原因]
- [决策2]: [原因]
### Data Flow (数据流)
[描述数据如何流动]
### File Changes (文件变更)
- Create: `src/path/to/new-file.ts`
- Modify: `src/path/to/existing.ts:123-145`
- Delete: `src/path/to/old.ts`
---
## 3. Implementation Tasks (实现任务)
### Task 1: [组件名称]
**Files:**
- Create: `src/path/to/file.ts`
**Step 1: Write the failing test**
```typescript
test('specific behavior', () => {
expect(function(input)).toBe(expected);
});
Step 2: Run test to verify it fails
Run: npm test path/to/test.test.ts
Expected: FAIL
Step 3: Write minimal implementation
function function(input) {
return expected;
}
Step 4: Run test to verify it passes
Run: npm test path/to/test.test.ts
Expected: PASS
Step 5: Commit
git add src/path/file.ts tests/path/test.test.ts
git commit -m "feat: add specific feature"
Task N: [组件名称]
[继续上述模式]
4. Acceptance Criteria (验收标准)
- 标准1: [描述]
- 标准2: [描述]
- 标准3: [描述]
### 6.3 保存位置 (根据计划性质自动选择)
writing-plans 技能会根据计划的**规模和性质**自动选择最佳保存位置：
| 计划类型 | 保存位置 | 说明 |
|----------|----------|------|
| **大计划** - 新功能、架构变更、重构 | `docs/plans/` | 需要详细技术方案、多阶段规划 |
| **小迭代** - 迭代开发、Bug修复、小优化 | `openspec/changes/` | 轻量级变更、Delta 规格 |
**判断逻辑**:
-
评估计划性质:
- 规模大? (涉及多个模块/服务)
- 需要架构决策?
- 是全新功能?
→ 是 → 放到 docs/plans/ - 小迭代/增量变更?
- Bug修复?
- 小优化/改进?
→ 是 → 放到 openspec/changes/
-
检查 OpenSpec 目录:
- 有 openspec/ → 可选 openspec/changes/
- 无 openspec/ → 强制 docs/plans/
**输出文件**:
大计划 (docs/plans/)
docs/plans/YYYY-MM-DD-.md
小迭代 (openspec/changes/)
openspec/changes//
├── proposal.md # Intent, Scope, Approach
├── design.md # 技术设计
├── tasks.md # 任务清单
└── specs//spec.md # Delta 规格
> **示例**:
> - 大计划: "实现用户认证系统" → `docs/plans/2024-01-15-user-auth.md`
> - 小迭代: "添加密码重置功能" → `openspec/changes/add-password-reset/`
---
## 7. 阶段三：开发执行
### 7.1 创建隔离的工作区
在开始实现之前，使用 **using-git-worktrees** 技能创建隔离的工作区：
/start-work
或者让 AI 自动触发。
### 7.2 工作区创建流程
┌─────────────────────────────────────────┐
│ using-git-worktrees 流程 │
├─────────────────────────────────────────┤
│ │
│ 1. 检测现有目录 │
│ ↓ │
│ 2. 验证 .gitignore │
│ ↓ │
│ 3. 创建 worktree │
│ ↓ │
│ 4. 运行项目设置 │
│ ↓ │
│ 5. 验证测试基线 │
│ │
└─────────────────────────────────────────┘
### 7.3 使用 subagent-driven-development 执行任务
使用 **subagent-driven-development** 技能将任务分派给专业子代理：
┌─────────────────────────────────────────┐
│ subagent-driven-development 流程 │
├─────────────────────────────────────────┤
│ │
│ 1. 为每个任务创建新子代理 │
│ ↓ │
│ 2. 第一阶段审查: 规格符合性 │
│ ↓ │
│ 3. 如需修改: 返回给子代理 │
│ ↓ │
│ 4. 第二阶段审查: 代码质量 │
│ ↓ │
│ 5. 合并或返回修改 │
│ │
└─────────────────────────────────────────┘
### 7.4 任务执行模板
每个任务按以下顺序执行：
1. **创建失败测试** — 遵循 TDD 原则
2. **验证测试失败** — 确认失败原因正确
3. **编写最小实现** — 只为通过测试
4. **验证测试通过** — 确认实现正确
5. **提交代码** — 原子提交
### 7.5 ECC 专业代理集成
在开发过程中，系统会自动调用以下 ECC 专业代理：
- **tdd-guide** - 测试驱动开发专家
- **code-reviewer** - 代码质量专家
- **build-error-resolver** - 构建错误修复专家
- **security-reviewer** - 安全审查专家
这些代理会在适当的时机自动介入，确保代码质量。
---
## 8. 阶段四：单元测试
### 8.1 使用 test-driven-development 技能
所有开发必须遵循 **test-driven-development** 流程：
┌─────────────────────────────────────────┐
│ TDD 红-绿-重构循环 │
├─────────────────────────────────────────┤
│ │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ RED │────▶│GREEN│────▶│REFAC│ │
│ │测试失败 │ │通过 │ │ │
│ └─────┘ └─────┘ └─────┘ │
│ ↑ │ │
│ └──────────────────────────────┘ │
│ │
│ RED: 写失败的测试 │
│ GREEN: 写最小代码让测试通过 │
│ REFACTOR: 重构改进代码 │
│ │
└─────────────────────────────────────────┘
### 8.2 TDD 规则
| 规则 | 说明 |
|------|------|
| **无测试不编码** | 没有失败的测试就不能写实现代码 |
| **最小实现** | 只写刚好能让测试通过的代码 |
| **不跳过验证** | 必须运行测试确认失败/通过 |
| **真实代码测试** | 避免 mock，除非不可避免 |
### 8.3 测试命名规范
```typescript
// Good: 描述行为
test('retries failed operations 3 times', async () => { ... })
test('rejects empty email with validation error', async () => { ... })
// Bad: 模糊命名
test('retry works', async () => { ... })
test('test1', async () => { ... })
8.4 测试覆盖要求
根据 everything-claude-code 的实践：
- 最低覆盖率: 80%+
- 关键路径: 100%
- 边界条件: 必须覆盖
8.5 全面的测试策略 (ECC TDD-Workflow)
根据 ECC 的 TDD-Workflow 技能，测试包括：
1. 单元测试 (Unit Tests)
- 个体函数、工具、组件
- 组件逻辑
- 純函数
- 辅助函数
2. 集成测试 (Integration Tests)
- API 端点
- 数据库操作
- 服务交互
- 外部 API 调用
3. 端到端测试 (E2E Tests - Playwright)
- 关键用户流程
- 完整工作流
- 浏览器自动化
- UI 交互
4. 边界情况测试
- 空值/未定义 输入
- 空数组/字符串
- 无效类型 传递
- 边界值 (最小/最大)
- 错误路径 (网络故障、数据库错误)
- 竞争条件 (并发操作)
- 大数据 (10k+ 项性能)
- 特殊字符 (Unicode, emoji, SQL 字符)
5. Mock 策略
- Supabase Mock
- Redis Mock
- OpenAI Mock
- 使用模拟外部服务
9. 阶段五：Code Review
9.1 使用 requesting-code-review 技能
在代码完成后，使用 requesting-code-review 技能发起代码审查：
/request-code-review
9.2 ECC 专业审查代理
系统会自动调用以下 ECC 专业审查代理：
| 代理 | 用途 | 适用场景 |
|---|---|---|
| code-reviewer | 代码质量与可维护性 | 编写/修改代码后 |
| security-reviewer | 漏洞检测 | 提交前、敏感代码 |
| go-reviewer | Go 代码审查 | Go 项目 |
| python-reviewer | Python 代码审查 | Python 项目 |
| database-reviewer | 数据库专家 | 模式设计、查询优化 |
9.3 代码审查流程
┌─────────────────────────────────────────┐
│ requesting-code-review 流程 │
├─────────────────────────────────────────┤
│ │
│ 1. 准备审查材料 │
│ - 代码变更 │
│ - 测试结果 │
│ - 自审查注释 │
│ ↓ │
│ 2. 选择审查者 │
│ - 代码审查代理 │
│ - 安全审查代理 │
│ - 语言特定审查 │
│ ↓ │
│ 3. 执行审查 │
│ - 规格符合性 │
│ - 代码质量 │
│ - 安全性检查 │
│ ↓ │
│ 4. 处理反馈 │
│ - 使用 receiving-code-review │
│ - 修复或讨论 │
│ │
└─────────────────────────────────────────┘
9.4 使用 receiving-code-review 技能
当收到审查反馈时，使用 receiving-code-review 技能处理：
# 当收到审查意见时，AI 会自动使用此技能
重要原则：
- 不要盲目实现所有建议
- 需要技术验证，不是表面同意
- 如果建议不清晰，询问澄清
10. 阶段六：Git Worktree 合并
10.1 使用 finishing-a-development-branch 技能
在代码审查通过后，使用 finishing-a-development-branch 技能完成分支：
/finish-branch
10.2 完成选项
┌─────────────────────────────────────────┐
│ finishing-a-development-branch │
├─────────────────────────────────────────┤
│ │
│ 选项 1: 直接合并 │
│ - 适用于小改动 │
│ - 快进合并 │
│ │
│ 选项 2: 创建 PR │
│ - 适用于大改动 │
│ - 需要团队审查 │
│ │
│ 选项 3: 清理并保留 │
│ - 不合并 │
│ - 保留分支供将来使用 │
│ │
│ 选项 4: 压缩并合并 │
│ - 整理提交历史 │
│ - 保持主分支干净 │
│ │
└─────────────────────────────────────────┘
10.3 PR 创建流程
如果选择创建 PR：
-
推送分支
git push -u origin feature/xxx -
创建 PR
gh pr create --title "feat: 功能名称" \ --body "$(cat <<'EOF' ## Summary - 功能描述 ## Test Plan - [ ] 测试1 - [ ] 测试2 EOF )" -
等待审查
- 使用 receiving-code-review 处理反馈
- 修复问题后更新 PR
-
合并
- 合并后删除分支
- 清理 worktree
10.4 Worktree 清理
# 列出所有 worktree
git worktree list
# 删除已完成功能的 worktree
git worktree remove .worktrees/feature-xxx
# 清理分支
git branch -d feature/xxx
11. ECC高级模式
11.1 自主循环模式 (ECC Autonomous Loops)
everything-claude-code 提供了多种自主工作循环模式：
| 模式 | 复杂度 | 最佳使用场景 |
|---|---|---|
| 顺序管道 | 低 | 日常开发步骤、脚本化工作流 |
| 持续 Claude PR 循环 | 中 | 多日迭代项目 |
| RFC 驱动 DAG | 高 | 大型功能、多单元并行工作 |
11.1.1 顺序管道
最简单的循环。将日常开发分解为一系列非交互式调用。每个调用都是有明确提示的焦点步骤。
核心设计原则：
- 每步隔离 — 每个调用都有新的上下文窗口，步骤之间没有上下文渗透
- 顺序重要 — 步骤按顺序执行。每个步骤构建在前一个步骤留下的文件系统状态上
- 负面指令危险 — 不说"不要测试类型系统"。而是添加单独的清理步骤
- 退出码传播 —
set -e在失败时停止管道
示例脚本：
#!/bin/bash
# daily-dev.sh — 特性分支的顺序管道
set -e
# 步骤 1: 实现功能
claude -p "阅读 docs/auth-spec.md 中的规范。在 src/auth/ 中实现 OAuth2 登录。先写测试 (TDD)。不要创建任何新文档文件。"
# 步骤 2: De-sloppify (清理)
claude -p "查看上一提交更改的所有文件。删除任何不必要的类型测试、过度防御性检查或测试语言特性(例如，测试 TypeScript 泛型工作)。保留所有业务逻辑测试。运行测试套件后清理。"
# 步骤 3: 验证
claude -p "运行完整的构建、lint、类型检查和测试套件。修复任何故障。不要添加新功能。"
# 步骤 4: 提交
claude -p "为所有暂存的更改创建约定提交。使用 'feat: add OAuth2 登录流程' 作为消息。"
11.1.2 持续 Claude PR 循环
生产级 Shell 脚本，运行 Claude Code 在持续循环中，创建 PRs，等待 CI，自动合并。
核心循环：
┌─────────────────────────────────────────────────────┐
│ CONTINUOUS CLAUDE ITERATION │
│ │
│ 1. 创建分支 (continuous-claude/iteration-N) │
│ 2. 使用增强提示运行 claude -p │
│ 3. (可选) 审查员通过 — 单独 claude -p │
│ 4. 提交更改 (claude 生成消息) │
│ 5. 推送 + 创建 PR (gh pr create) │
│ 6. 等待 CI 检查 (轮询 gh pr checks) │
│ 7. CI 失败? → 自动修复通过 (claude -p) │
│ 8. 合并 PR (squash/merge/rebase) │
│ 9. 返回主分支 → 重复 │
│ │
│ 限制: --max-runs N | --max-cost $X │
│ --max-duration 2h | 完成信号 │
└─────────────────────────────────────────────────────┘
跨迭代上下文: SHARED_TASK_NOTES.md
关键创新：一个 SHARED_TASK_NOTES.md 文件在迭代间持久化：
## 进度
- [x] 添加 auth 模块测试 (迭代 1)
- [x] 修复令牌刷新边缘情况 (迭代 2)
- [ ] 仍需要: 速率限制测试、错误边界测试
## 下一步
- 重点关注速率限制模块
- 测试助手中的模拟设置可以重用
11.1.3 RFC 驱动 DAG
最复杂的模式。RFC 驱动的多代理管道，将规范分解为依赖 DAG，通过分层质量管道运行每个单元，通过代理驱动的合并队列落地。
架构概览：
RFC/PRD 文档
│
▼
分解 (AI)
将 RFC 分解为带有依赖 DAG 的工作单元
│
▼
┌──────────────────────────────────────────────────────┐
│ RALPH LOOP (最多 3 次通过) │
│ │
│ 对于每个 DAG 层 (按依赖关系顺序): │
│ │
│ ┌── 质量管道 (每个单元并行) ──────┐ │
│ │ 每个单元都在其工作树中: │ │
│ │ 研究 → 计划 → 实现 → 测试 → 审查 │ │
│ │ (深度因复杂度等级而异) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌── 合并队列 ─────────────────────────────────┐ │
│ │ 变基到主分支 → 运行测试 → 登陆或驱逐 │ │
│ │ 驱逐的单元重新进入冲突上下文 │ │
│ └────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘
11.2 De-Sloppify 模式
任何循环的附加模式。在每个实现步骤后添加专门的清理/重构步骤。
关键见解：
与其添加有下游质量影响的负面指令，不如添加单独的 de-sloppify 通过。两个专注的代理比一个受约束的代理效果更好。
12. 自主工作流
12.1 Loop Start 命令
开始具有安全默认值的托管自主循环模式：
/loop-start [pattern] [--mode safe|fast]
支持的模式：
sequential- 顺序管道continuous-pr- 持续 PR 循环rfc-dag- RFC 驱动 DAGinfinite- 无限代理循环
安全模式 vs 快速模式：
safe(默认)：严格的质量门和检查点fast：为速度减少门
12.2 模型路由策略
根据任务类型使用不同的模型：
| 任务类型 | 模型 | 原因 |
|---|---|---|
| 探索/搜索 | Haiku | 快速、便宜、对查找文件足够好 |
| 简单编辑 | Haiku | 单文件更改、明确指令 |
| 多文件实现 | Sonnet | 编码的最佳平衡 |
| 复杂架构 | Opus | 需要深度推理 |
| PR 审查 | Sonnet | 理解上下文、捕获细微之处 |
| 安全分析 | Opus | 不能错过漏洞 |
| 写文档 | Haiku | 结构简单 |
| 调试复杂错误 | Opus | 需要保持整个系统在脑海中 |
12.3 并行化策略
Git Worktrees
用于并行工作，每个工作树运行一个独立的 Claude 实例。
级联方法
- 在右侧为新任务打开新标签
- 从左到右扫描，最旧到最新
- 同时最多专注 3-4 个任务
两实例启动模式
- 实例1：脚手架代理 - 铺设脚手架和基础
- 实例2：深度研究代理 - 连接到所有服务、网络搜索、创建详细 PRD
13. 会话与记忆管理
13.1 记忆持久化钩子 (ECC Continuous Learning v2.1)
ECC 实现了一种本能驱动的学习系统，通过钩子观察会话、创建带置信度评分的原子本能，并将它们演化为技能/命令/代理。
本能模型
本能是小程序行为：
---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---
# 偏好函数式风格
## 行动
在适当时候使用函数式模式而非类。
## 证据
- 观察到 5 个函数式模式偏好实例
- 用户在 2025-01-15 将基于类的方法校正为函数式
项目检测
系统自动检测当前项目：
CLAUDE_PROJECT_DIR环境变量 (最高优先级)git remote get-url origin-- 哈希化创建可移植项目 IDgit rev-parse --show-toplevel-- 回退使用仓库路径- 全局回退 -- 如果未检测到项目，本能进入全局范围
范围决策指南
| 模式类型 | 范围 | 示例 |
|---|---|---|
| 语言/框架约定 | 项目 | "使用 React hooks"、"遵循 Django REST 模式" |
| 文件结构偏好 | 项目 | "测试在 __tests__/"、"组件在 src/components/" |
| 代码风格 | 项目 | "使用函数式风格"、"偏好数据类" |
| 错误处理策略 | 项目 | "为此使用 Result 类型" |
| 安全实践 | 全局 | "验证用户输入"、"净化 SQL" |
| 通用最佳实践 | 全局 | "先写测试"、"始终处理错误" |
| 工具工作流偏好 | 全局 | "编辑前 grep"、"写入前读取" |
| Git 实践 | 全局 | "约定提交"、"小专注提交" |
13.2 会话管理钩子
ECC 提供了完整的会话管理钩子链：
PreCompact 钩子
在上下文压缩前保存状态：
- 时机: 上下文压缩前
- 作用: 保存重要状态到文件
SessionStart 钩子
在新会话时加载以前上下文：
- 时机: 会话开始时
- 作用: 加载以前上下文，检测包管理器
Stop 钩子
每次响应后检查控制台日志，持久化会话状态：
-
时机: 每次 Claude 响应后
-
作用:
- 检查修改文件中的控制台日志
- 持久化会话状态（Stop 携带 transcript_path）
- 评估会话以提取可提取模式
- 跟踪每个会话的令牌和成本指标
SessionEnd 钩子
会话结束生命周期标记：
- 时机: 会话结束时
- 作用: 非阻塞的会话结束生命周期标记
13.3 动态系统提示注入
使用 CLI 标志以手术方式加载上下文：
# 日常开发
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
# PR 审查模式
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
# 研究/探索模式
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'
14. 验证与质量保证
14.1 Verify 命令
运行当前代码库状态的全面验证：
验证流程 (按顺序) :
- 构建检查 - 运行构建命令
- 类型检查 - 运行 TypeScript/类型检查器
- Lint 检查 - 运行 Linter
- 测试套件 - 运行所有测试
- 控制台日志审计 - 搜索源文件中的 console.log
- Git 状态 - 显示未提交的更改
输出格式:
VERIFICATION: [PASS/FAIL]
Build: [OK/FAIL]
Types: [OK/X errors]
Lint: [OK/X issues]
Tests: [X/Y passed, Z% coverage]
Secrets: [OK/X found]
Logs: [OK/X console.logs]
Ready for PR: [YES/NO]
14.2 Eval 驱动开发
ECC 支持评估驱动开发工作流。
Define Evals
创建 .claude/evals/feature-name.md:
## EVAL: feature-name
Created: $(date)
### Capability Evals
- [ ] [功能1描述]
- [ ] [功能2描述]
### Regression Evals
- [ ] [现有行为1仍然工作]
- [ ] [现有行为2仍然工作]
### Success Criteria
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals
Check Evals
运行功能的评估：
- 记录 pass@1, pass@3, pass^3 指标
- 为回归评估比较基线
Report Evals
生成综合评估报告：
- 能力评估状态
- 回归评估状态
- 指标 (pass@1, pass@3, pass^3)
- 建议 (SHIP/NEEDS WORK/BLOCKED)
14.3 质量门 (Quality Gates)
在 PostToolUse 阶段自动运行质量门检查：
- 代码质量检查
- 安全扫描
- 格式检查
- 类型检查
15. 技能参考
15.1 核心技能列表
| 技能 | 用途 | 触发条件 | 提供者 |
|---|---|---|---|
| brainstorming | 需求分析 | 开始新功能时 | superpowers |
| writing-plans | 生成技术方案 | 需求明确后 | superpowers |
| using-git-worktrees | 创建隔离工作区 | 开始实现前 | superpowers |
| subagent-driven-development | 任务执行 | 实现功能时 | superpowers |
| test-driven-development | 测试开发 | 编写代码时 | superpowers |
| systematic-debugging | 调试问题 | 遇到 bug 时 | superpowers |
| requesting-code-review | 代码审查 | 代码完成后 | superpowers |
| receiving-code-review | 处理审查反馈 | 收到审查意见时 | superpowers |
| finishing-a-development-branch | 分支完成 | 准备合并时 | superpowers |
| verification-before-completion | 完成验证 | 声称完成前 | superpowers |
15.2 ECC 增强技能
| 技能 | 用途 | 提供者 |
|---|---|---|
| autonomous-loops | 自主循环模式 | everything-claude-code |
| continuous-learning-v2 | 直觉驱动学习 | everything-claude-code |
| tdd-workflow | 全面 TDD 模式 | everything-claude-code |
writing-plans
-
何时使用: 需求明确后，实现前
-
做什么: 将设计拆分为2-5分钟的可执行任务
-
输出: 实现计划文档
-
输出路径 (自动选择) :
- 项目有
openspec/→openspec/changes/<change-name>/ - 项目无 OpenSpec →
docs/plans/YYYY-MM-DD-<feature-name>.md
- 项目有
16. 命令参考
16.1 核心命令
| 命令 | 功能 | 提供者 |
|---|---|---|
/brainstorm | 触发 brainstorming 技能 | superpowers |
/write-plan | 触发 writing-plans 技能 | superpowers |
/start-work | 开始执行计划 | superpowers |
/request-code-review | 发起代码审查 | superpowers |
/verify | 验证完成状态 | superpowers |
/finish-branch | 完成分支 | superpowers |
16.2 ECC 专业命令
| 命令 | 功能 | 提供者 |
|---|---|---|
/plan | 创建实施计划 | everything-claude-code |
/tdd | 强制测试驱动开发 | everything-claude-code |
/build-fix | 修复构建/类型错误 | everything-claude-code |
/code-review | 代码质量检查 | everything-claude-code |
/e2e | 端到端测试 | everything-claude-code |
/instinct-status | 显示学习的本能 | everything-claude-code |
/evolve | 将本能聚类为技能/命令 | everything-claude-code |
/instinct-export | 导出本能 | everything-claude-code |
/instinct-import | 导入他人本能 | everything-claude-code |
/promote | 将项目本能提升到全局范围 | everything-claude-code |
/projects | 列出所有已知项目 | everything-claude-code |
/eval | 评估驱动开发 | everything-claude-code |
/loop-start | 开始自主循环 | everything-claude-code |
16.3 懒人模式 (可选)
| 输入 | 触发 | 提供者 |
|---|---|---|
ulw | /ultrawork | oh-my-openagent |
ulw loop | /ulw-loop | oh-my-openagent |
附录
A. OpenSpec 风格目录结构 (推荐)
project/
├── openspec/ # OpenSpec 规格驱动开发
│ ├── specs/ # 权威规格 (系统当前行为)
│ │ └── <domain>/ # 按领域组织
│ │ └── spec.md # 主规格文档
│ ├── changes/ # 变更提议 (每个变更一个文件夹)
│ │ ├── <change-name>/ # 例如: add-user-auth
│ │ │ ├── proposal.md # 意图、范围、方法
│ │ │ ├── design.md # 技术方案和架构决策
│ │ │ ├── tasks.md # 实现检查清单
│ │ │ └── specs/ # Delta 规格
│ │ │ └── <domain>/
│ │ │ └── spec.md # ADDED/MODIFIED/REMOVED
│ │ └── archive/ # 已完成的变更
│ │ └── <archived-change>/
│ └── config.yaml # 项目配置
├── src/ # 源代码
├── tests/ # 测试文件
├── .worktrees/ # Worktrees (已忽略)
└── CLAUDE.md # 项目配置
规格文档结构 (specs/spec.md)
# 用户认证规格
## Purpose
描述该规格领域的高层次目的
## Requirements
### Requirement: 用户可以注册
用户 SHALL 能够通过提供邮箱和密码创建新账户
#### Scenario: 正常注册
- GIVEN 用户在注册页面
- WHEN 填写有效邮箱和密码并提交
- THEN 创建新账户并跳转到首页
### Requirement: 密码强度验证
密码 SHALL 至少包含 8 个字符
Delta 规格格式 (changes//specs//spec.md)
# 用户认证规格 (Delta)
## ADDED Requirements
### Requirement: 密码重置
用户 SHALL 能够通过邮箱重置密码
#### Scenario: 请求密码重置
- GIVEN 用户已注册
- WHEN 点击"忘记密码"并输入邮箱
- THEN 发送重置链接到邮箱
## MODIFIED Requirements
### Requirement: 密码强度验证 (Previously: 至少 8 个字符)
密码 SHALL 至少包含 12 个字符，包括大小写和数字
## REMOVED Requirements
### Requirement: 注册验证码
此需求已废弃，改用邮箱验证链接
proposal.md 模板
# [变更名称] 提案
## Intent
[描述你想要实现的目标]
## Scope
### In Scope
- [包含的功能]
### Out of Scope
- [不包含的功能]
## Approach
[实现方法的概述]
design.md 模板
# [变更名称] 技术设计
## Technical Approach
[技术方案描述]
## Architecture Decisions
- [决策1]: [原因]
- [决策2]: [原因]
## Data Flow
[描述数据如何流动]
## File Changes
- Create: `src/path/to/new-file.ts`
- Modify: `src/path/to/existing.ts:123-145`
- Delete: `src/path/to/old.ts`
tasks.md 模板
# [变更名称] 实现任务
## 1. 核心功能
- [ ] 1.1 任务描述
- [ ] 1.2 任务描述
## 2. 相关功能
- [ ] 2.1 任务描述
## 3. 测试
- [ ] 3.1 单元测试
- [ ] 3.2 集成测试
## 4. 文档
- [ ] 4.1 更新 API 文档
- [ ] 4.2 更新 README
归档流程
当变更完成后，执行归档：
-
合并 Delta 规格到主规格
- ADDED → 追加到主规格
- MODIFIED → 替换主规格中对应需求
- REMOVED → 从主规格中删除
-
移动变更文件夹
mv openspec/changes/<change-name> openspec/changes/archive/<change-name> -
保留所有 Artifact
- 保留 proposal.md、design.md、tasks.md 供审计
B. 简化目录结构 (轻量级)
project/
├── docs/
│ ├── plans/ # 技术方案
│ │ └── YYYY-MM-DD-feature.md
│ ├── specs/ # 规格文档
│ │ └── domain/
│ │ └── spec.md
│ └── changes/ # 变更
│ └── YYYY-MM-DD-feature/
│ ├── proposal.md
│ ├── design.md
│ └── tasks.md
├── src/ # 源代码
├── tests/ # 测试文件
├── .worktrees/ # Worktrees (已忽略)
└── CLAUDE.md # 项目配置
C. 提交信息规范
<type>(<scope>): <subject>
<body>
<footer>
类型 (type):
feat: 新功能fix: Bug 修复docs: 文档style: 格式refactor: 重构test: 测试chore: 杂项
示例:
feat(auth): add JWT token refresh
- Implement refresh token rotation
- Add token expiration handling
- Update auth middleware
Closes #123
D. 常用命令速查
# 创建新分支 worktree
git worktree add .worktrees/feature-name -b feature/name
# 列出所有 worktree
git worktree list
# 删除 worktree
git worktree remove .worktrees/feature-name
# 运行测试
npm test
# 运行特定测试
npm test path/to/test.test.ts
# 构建项目
npm run build
# 代码检查
npm run lint
