943 lines
31 KiB
Markdown
943 lines
31 KiB
Markdown
---
|
||
created: "2026-03-19 12:00"
|
||
type: resource
|
||
tags: [resource, claude-code, AI-tools, methodology, best-practices, agent-orchestration]
|
||
source: "https://github.com/affaan-m/everything-claude-code"
|
||
---
|
||
|
||
# Everything Claude Code 方法论与最佳实践
|
||
|
||
深度分析 ECC 的六大核心方法论、社区最佳实践、常见陷阱与实战例子。组件列表见 [[Everything Claude Code 完整指南]]，按场景速查见 [[Everything Claude Code 用法速查]]。
|
||
|
||
> **命令命名空间**: 通过插件安装的 ECC，所有命令需要加 `everything-claude-code:` 前缀（如 `/everything-claude-code:plan`）。手动安装到 `~/.claude/commands/` 的可用短名（如 `/plan`）。本文中用 **短名** 书写以保持可读性，实际使用时请加前缀。`/compact` 是 Claude Code 内置命令，无需前缀。
|
||
|
||
**命令名映射速查**:
|
||
|
||
| 短名 | 插件全名 |
|
||
|------|---------|
|
||
| `/plan` | `/everything-claude-code:plan` |
|
||
| `/tdd` | `/everything-claude-code:tdd` |
|
||
| `/verify` | `/everything-claude-code:verify` |
|
||
| `/learn` | `/everything-claude-code:learn-eval` |
|
||
| `/evolve` | `/everything-claude-code:evolve` |
|
||
| `/claw` | `/everything-claude-code:claw` |
|
||
| `/e2e` | `/everything-claude-code:e2e` |
|
||
| `/orchestrate` | `/everything-claude-code:plan` (含编排) |
|
||
| `/search-first` | `/everything-claude-code:search-first` |
|
||
| `/eval` | `/everything-claude-code:eval-harness` |
|
||
| `/instinct-export` | `/everything-claude-code:instinct-export` |
|
||
| `/instinct-import` | `/everything-claude-code:instinct-import` |
|
||
| `/instinct-status` | `/everything-claude-code:instinct-status` |
|
||
| `/configure-ecc` | `/everything-claude-code:configure-ecc` |
|
||
| `/security-scan` | `/everything-claude-code:security-scan` |
|
||
| `/compact` | `/compact` (内置，无需前缀) |
|
||
|
||
---
|
||
|
||
## 一、六大核心方法论
|
||
|
||
### 1. Research-First Development（研究优先开发）
|
||
|
||
在写任何代码之前，必须搜索现有实现。这是 ECC 工作流的**步骤 0（强制）**。
|
||
|
||
```
|
||
流程:
|
||
1. gh search repos / gh search code → 搜索 GitHub 现有实现
|
||
2. 搜索包注册表（npm, PyPI, crates.io）→ 优先用成熟库
|
||
3. Web 搜索 → 发现先例和最佳实践
|
||
4. 如果找到 80%+ 匹配的开源项目 → Fork/移植，不要从零写
|
||
```
|
||
|
||
**Exa MCP 用于研究**: 在规划阶段使用 `exa-web-search` MCP 进行更广泛的研究和先例发现。
|
||
|
||
**例子 — JWT 验证中间件**:
|
||
|
||
```bash
|
||
# 先搜索，不要直接写
|
||
gh search code "jwt middleware verify" --language=typescript
|
||
# 找到 jose 库 → 直接用，而不是手写 crypto
|
||
npm search jwt verify
|
||
```
|
||
|
||
### 2. Agent Orchestration（Agent 编排）
|
||
|
||
将复杂任务分解给专业 Agent，支持串行链和并行执行。
|
||
|
||
**四种预设工作流**:
|
||
|
||
| 工作流 | Agent 链 |
|
||
| -------- | ------------------------------------------------------- |
|
||
| feature | planner → tdd-guide → code-reviewer → security-reviewer |
|
||
| bugfix | planner → tdd-guide → code-reviewer |
|
||
| refactor | architect → code-reviewer → tdd-guide |
|
||
| security | security-reviewer → code-reviewer → architect |
|
||
|
||
**自定义链**: `/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"`
|
||
|
||
**独立检查可并行执行**: 例如 code-reviewer + security-reviewer + architect 可同时运行。
|
||
|
||
**特殊 Agent**:
|
||
|
||
| Agent | 特殊能力 |
|
||
|-------|---------|
|
||
| **loop-operator** | 自主循环执行，带失速检测、检查点追踪、重试风暴检测。连续 2 个检查点无进展或成本超预算时自动升级 |
|
||
| **chief-of-staff** | 跨 email/Slack/LINE/Messenger 的通信分级（skip/info/meeting/action），自动草拟回复 |
|
||
| **code-reviewer** | 5 步流程: 收集上下文 → 理解范围 → 读周围代码 → 应用检查清单 → 出报告。信心阈值 >80% 过滤低置信度问题。输出 approve/warning/block 判决 |
|
||
|
||
**loop-operator 例子**:
|
||
|
||
```
|
||
# 自主执行迁移任务
|
||
/loop-operator "Migrate all API endpoints from Express to Fastify"
|
||
|
||
# 内部行为:
|
||
# Checkpoint 1: GET /users migrated ✓
|
||
# Checkpoint 2: POST /users migrated ✓
|
||
# Checkpoint 3: GET /orders migrated ✓
|
||
# ⚠ Stall detected: DELETE /orders failing for 3 attempts
|
||
# → Scope reduction: skip DELETE /orders, flag for manual review
|
||
# → Continue with remaining endpoints
|
||
# Checkpoint 4: PUT /orders migrated ✓
|
||
# ...
|
||
# ⚠ Cost drift: 120% of budget → escalate to user
|
||
```
|
||
|
||
**Agent 间交接文档格式**:
|
||
|
||
```markdown
|
||
## Handoff: planner → tdd-guide
|
||
### Context
|
||
- 实现 OAuth2 登录流程，使用 passport.js + Google provider
|
||
### Findings
|
||
- 需要新建 3 个文件: auth.controller, auth.service, auth.guard
|
||
### Files Modified
|
||
- (none yet - planning phase)
|
||
### Open Questions
|
||
- 是否需要 refresh token 支持?
|
||
### Recommendations
|
||
- 先写 auth.service 的单元测试
|
||
```
|
||
|
||
### 3. Hook-Driven Enforcement（Hook 驱动的强制执行）
|
||
|
||
**核心洞察**: Hook 触发率 100%（确定性），Skill/提示词触发率仅 50-80%（概率性）。因此关键质量控制应通过 Hook 实现，而非依赖提示词。
|
||
|
||
| Hook 类型 | 触发时机 | 用途举例 |
|
||
| ------------ | ------ | ----------------- |
|
||
| PreToolUse | 工具执行前 | 开发服务器自启、安全监控 |
|
||
| PostToolUse | 工具执行后 | 自动格式化、类型检查 |
|
||
| PreCompact | 上下文压缩前 | 保存会话状态到 MEMORY.md |
|
||
| SessionStart | 新会话开始 | 加载上次上下文、检测包管理器 |
|
||
| Stop | 每次响应后 | 检查 debug 语句、持久化指标 |
|
||
|
||
**例子 — hooks.json 配置**:
|
||
|
||
```json
|
||
{
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Write|Edit",
|
||
"command": "prettier --write $FILEPATH && eslint --fix $FILEPATH",
|
||
"description": "每次文件编辑后自动格式化和 lint"
|
||
},
|
||
{
|
||
"matcher": "Write|Edit",
|
||
"command": "npx tsc --noEmit $FILEPATH 2>&1 | head -20",
|
||
"description": "每次文件编辑后自动类型检查"
|
||
}
|
||
],
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "Bash",
|
||
"command": "node hooks/dev-server-check.js",
|
||
"description": "执行 bash 命令前确保开发服务器在 tmux 中运行"
|
||
}
|
||
],
|
||
"PreCompact": [
|
||
{
|
||
"command": "node hooks/save-session-state.js",
|
||
"description": "上下文压缩前自动保存会话状态到 MEMORY.md"
|
||
}
|
||
],
|
||
"Stop": [
|
||
{
|
||
"command": "grep -rn 'console.log\\|debugger' src/ --include='*.ts' | head -5",
|
||
"description": "每次响应后检查是否遗留了 debug 语句"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**运行时控制**（无需编辑文件）:
|
||
|
||
```bash
|
||
export ECC_HOOK_PROFILE=minimal # 最小化（减少开销）
|
||
export ECC_HOOK_PROFILE=standard # 标准
|
||
export ECC_HOOK_PROFILE=strict # 严格（全部启用）
|
||
export ECC_DISABLED_HOOKS=security-monitor,learning-observer # 禁用特定 hook
|
||
```
|
||
|
||
### 4. Continuous Learning（持续学习系统）v2.1
|
||
|
||
ECC 最独特的创新 — **本能学习系统**。
|
||
|
||
```
|
||
观察(Hook) → 检测模式(Haiku) → 形成本能(Instinct) → 演化为技能(Skill)
|
||
```
|
||
|
||
**工作流程**:
|
||
|
||
1. Hook 捕获每次工具调用到 `observations.jsonl`
|
||
2. Haiku 模型后台观察器检测模式
|
||
3. 模式成为"本能"— 原子化学习行为，带信心分数 (0.3-0.9)
|
||
4. 本能按项目隔离（git remote URL hash）防止跨项目污染
|
||
5. `/evolve` 将相关本能聚类为新的 skill/command/agent
|
||
6. 信心 >= 0.8 且在 2+ 项目中出现 → 从项目级提升到全局级
|
||
|
||
**例子**:
|
||
|
||
```bash
|
||
# 会话结束后提取模式
|
||
/learn
|
||
# → [Instinct] confidence=0.7 scope=project
|
||
# → "When editing React components, always check for missing useCallback"
|
||
|
||
# 多次确认后
|
||
/evolve
|
||
# → 自动生成新 skill: react-performance-patterns
|
||
```
|
||
|
||
### 5. Strategic Compaction（策略性压缩）
|
||
|
||
**问题**: 自动压缩在 ~83.5% 上下文使用率时随机触发，可能丢失关键上下文。
|
||
|
||
**解决方案**: 在逻辑工作节点手动触发 `/compact`。
|
||
|
||
```
|
||
推荐压缩时机:
|
||
├── 探索阶段完成后
|
||
├── 里程碑完成后
|
||
├── 切换任务类型时（调试 → 开发）
|
||
└── 工具调用次数达到阈值时（Hook 自动提醒）
|
||
```
|
||
|
||
**例子 — 好的 vs 坏的压缩时机**:
|
||
|
||
```
|
||
# 坏: 在重构中途自动压缩，丢失函数签名和依赖关系上下文
|
||
# ❌ Auto-compact at 167K tokens mid-refactor
|
||
# → 压缩后 Claude 忘记了之前分析的接口签名
|
||
# → 重新读取 5 个文件，浪费 ~20K tokens
|
||
|
||
# 好: 在完成一个模块后手动压缩
|
||
# Phase 1: Auth module complete ✓
|
||
# → 所有测试通过，代码已提交
|
||
/compact
|
||
# Phase 2: Start payment module (clean context)
|
||
# → 只需加载 payment 相关文件，不需要 auth 的上下文
|
||
|
||
# 好: 从调试切到开发时压缩
|
||
# Debug session: found root cause → fixed → committed
|
||
/compact
|
||
# Feature development: start new feature (清除调试噪音)
|
||
```
|
||
|
||
禁用自动压缩的配置:
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. Verification Loop（验证循环）
|
||
|
||
6 阶段质量门，建议每 15 分钟或每次重大变更后执行:
|
||
|
||
```
|
||
/verify → 6 阶段:
|
||
1. Build → 编译是否通过
|
||
2. Types → 类型检查
|
||
3. Lint → 代码规范
|
||
4. Tests → 测试通过 + 覆盖率 >= 80%
|
||
5. Security → 安全扫描
|
||
6. Diff → 变更审查
|
||
→ 输出: 结构化 PASS/FAIL 报告
|
||
```
|
||
|
||
**例子 — 验证报告输出**:
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ Verification Report — 2026-03-19 14:30 │
|
||
├──────────────────────────────────────────┤
|
||
│ 1. Build ✅ PASS (3.2s) │
|
||
│ 2. Types ✅ PASS (1.8s, 0 errors) │
|
||
│ 3. Lint ⚠️ WARN (0.9s) │
|
||
│ → 2 warnings: unused imports │
|
||
│ 4. Tests ✅ PASS (12.4s) │
|
||
│ → 147/147 passed, 0 failed │
|
||
│ → Coverage: 84.2% (target: 80%) │
|
||
│ 5. Security ✅ PASS (2.1s) │
|
||
│ → 0 critical, 0 high, 1 medium │
|
||
│ → medium: CSP header missing (info) │
|
||
│ 6. Diff ✅ PASS │
|
||
│ → 4 files changed, +127 -43 │
|
||
│ → No secrets detected in diff │
|
||
├──────────────────────────────────────────┤
|
||
│ VERDICT: PASS (5/6 green, 1 warning) │
|
||
│ Ready to commit: YES │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
**CLAUDE.md 的特殊角色**: CLAUDE.md 是唯一在上下文压缩后仍被保留的文件内容。因此应将最关键的项目约定写在 CLAUDE.md 中，而非依赖会话记忆。这是"压缩幸存上下文"(compaction-surviving context) 的设计考量。
|
||
|
||
---
|
||
|
||
## 二、社区最佳实践
|
||
|
||
### 渐进式采用路线
|
||
|
||
| 阶段 | 重点 | 内容 |
|
||
|------|------|------|
|
||
| 第1周 | 基础 | Rules + 基本 Commands (`/plan`, `/tdd`) |
|
||
| 第2周 | 管理 | Session logging + Memory + Strategic compact |
|
||
| 第3周 | 高级 | Agents + Custom skills + Verification loops |
|
||
| 第4周 | 优化 | Token optimization + 并行执行 |
|
||
| 持续 | 积累 | `/learn` 提取模式，构建项目专用 Agent |
|
||
|
||
### Token/成本优化
|
||
|
||
```json
|
||
// settings.json 推荐配置
|
||
{
|
||
"model": "sonnet",
|
||
"env": {
|
||
"MAX_THINKING_TOKENS": "10000",
|
||
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
|
||
}
|
||
}
|
||
// → ~60% 成本降低 (Sonnet vs Opus)
|
||
// → ~70% thinking 成本降低
|
||
```
|
||
|
||
**模型选择策略**:
|
||
|
||
| 模型 | 场景 | 能力/成本比 |
|
||
|------|------|-----------|
|
||
| Haiku | 简单任务、频繁调用的轻量 Agent | 90% 能力，3x 省钱 |
|
||
| Sonnet | 90% 的日常编码工作 | 最佳性价比 |
|
||
| Opus | 架构决策、首次失败重试、5+ 文件跨度 | 最强推理 |
|
||
|
||
### MCP 管理
|
||
|
||
- 启用的 MCP <= 10 个，活跃工具总数 <= 80 个
|
||
- 10+ MCP 时，有效上下文从 200K 降至 ~70K tokens
|
||
- 用 `disabledMcpServers` 禁用不用的
|
||
- 重操作优先用 CLI（如 `gh`）而不是 MCP
|
||
- 使用 `llms.txt` 模式（如 `vercel.com/docs/llms.txt`）代替 MCP 获取文档
|
||
|
||
### 会话管理
|
||
|
||
- 命名会话，特别是使用 git worktree 并行工作时
|
||
- 保存会话状态到 `.tmp` 文件
|
||
- 同一问题纠正 Claude 超过 2 次 → 开新会话（失败方法污染上下文）
|
||
- 新项目用双实例模式：实例 1 做脚手架，实例 2 做研究，合并后实施
|
||
|
||
---
|
||
|
||
## 三、常见陷阱
|
||
|
||
| 陷阱 | 影响 | 解决方案 |
|
||
|------|------|---------|
|
||
| 同时启用所有 MCP | 上下文降至 ~70K | 保持 <= 10 个 |
|
||
| 跳过 Plan 阶段 | 需求不清，大量返工 | 始终先 `/plan` |
|
||
| 过多并行实例 | 心智负担 > 生产力 | 按需添加 |
|
||
| 文件超 500 行 | 重读消耗大量 Token | 拆分为小文件 |
|
||
| 不提取可复用模式 | 每次重复设置 | 用 `/learn` 固化 |
|
||
| 忽略上下文健康 | 模型性能下降、幻觉 | 监控使用率，里程碑处压缩 |
|
||
| 死代码累积 | Token 浪费 | 定期用 refactor-cleaner |
|
||
| 忽略 Agent 质量门 | 遗漏回归和安全问题 | 让 Agent 触发运行 |
|
||
|
||
---
|
||
|
||
## 四、ECC 独特创新
|
||
|
||
| 创新 | 说明 |
|
||
|------|------|
|
||
| **Hookify** | 对话式 Hook 创建 — 描述需求自动生成 Hook 配置 |
|
||
| **pass@k / pass^k** | 形式化验证 Agent 任务成功率的度量 |
|
||
| **Sandboxed Subagents** | 按 Agent 限制工具（planner 只读，tdd-guide 可写代码+测试）|
|
||
| **Cascade Method** | 多实例管理用于并行开发 |
|
||
| **AgentShield** | 安全审计（1282 测试，98% 覆盖率，14 种密钥模式检测）|
|
||
| **Plankton** | 写入时代码质量工具（20+ linter + Claude 子进程修复）|
|
||
| **NanoClaw v2** | 模型路由、技能热加载、会话分支/搜索/导出 |
|
||
| **Continuous Learning v2.1** | Hook 观察 → 模式检测 → 本能形成 → 技能演化 |
|
||
|
||
### 各创新功能详细例子
|
||
|
||
**Hookify — 对话式创建 Hook**:
|
||
|
||
```
|
||
用户: "每次我编辑 .py 文件后自动运行 black 格式化"
|
||
|
||
# Hookify 自动生成:
|
||
{
|
||
"PostToolUse": [{
|
||
"matcher": "Write|Edit",
|
||
"command": "if [[ \"$FILEPATH\" == *.py ]]; then black \"$FILEPATH\"; fi",
|
||
"description": "Auto-format Python files with black"
|
||
}]
|
||
}
|
||
# → 写入 hooks/hooks.json，立即生效
|
||
```
|
||
|
||
**Sandboxed Subagents — 工具限制**:
|
||
|
||
```yaml
|
||
# agents/planner.md frontmatter
|
||
---
|
||
name: planner
|
||
model: opus
|
||
tools: [Read, Glob, Grep, WebSearch, WebFetch] # 只读，不能写代码
|
||
---
|
||
|
||
# agents/tdd-guide.md frontmatter
|
||
---
|
||
name: tdd-guide
|
||
model: sonnet
|
||
tools: [Read, Write, Edit, Bash, Glob, Grep] # 可以写代码和运行测试
|
||
---
|
||
|
||
# agents/security-reviewer.md frontmatter
|
||
---
|
||
name: security-reviewer
|
||
tools: [Read, Grep, Glob, Bash] # 可以读和扫描，不能修改
|
||
---
|
||
```
|
||
|
||
**Cascade Method — 多实例并行开发**:
|
||
|
||
```bash
|
||
# 实例 1: 主开发（feature branch）
|
||
claude --session "auth-feature" --worktree feature/auth
|
||
# → 在独立 worktree 中开发 auth 模块
|
||
|
||
# 实例 2: 并行研究
|
||
claude --session "auth-research"
|
||
# → 研究 OAuth2 最佳实践、比较库
|
||
# → 输出研究报告到 .tmp 文件
|
||
|
||
# 实例 3: 并行测试基础设施
|
||
claude --session "test-infra" --worktree feature/test-setup
|
||
# → 搭建测试环境、mock 服务器
|
||
|
||
# 合并时:
|
||
# 实例 1 读取实例 2 的研究结果
|
||
# 实例 1 合并实例 3 的测试基础设施
|
||
```
|
||
|
||
**Tmux/Worktree 编排**:
|
||
|
||
```json
|
||
// orchestration-plan.json
|
||
{
|
||
"workers": [
|
||
{
|
||
"name": "api-worker",
|
||
"branch": "feature/api-endpoints",
|
||
"task": "Implement REST API endpoints for user CRUD",
|
||
"seedPaths": ["src/types/", "src/config/"]
|
||
},
|
||
{
|
||
"name": "db-worker",
|
||
"branch": "feature/db-schema",
|
||
"task": "Create database migrations and repository layer",
|
||
"seedPaths": ["src/types/", "prisma/"]
|
||
},
|
||
{
|
||
"name": "test-worker",
|
||
"branch": "feature/e2e-tests",
|
||
"task": "Write E2E tests for user flows",
|
||
"seedPaths": ["src/types/", "tests/fixtures/"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# 启动编排
|
||
node scripts/orchestrate-worktrees.js orchestration-plan.json
|
||
# → 创建 3 个 git worktree
|
||
# → 每个在独立 tmux pane 中运行 Claude
|
||
# → seedPaths 从主分支复制共享文件到各 worktree
|
||
|
||
# 查看状态
|
||
node scripts/orchestration-status.js
|
||
# → api-worker: 3/5 tasks done, branch: feature/api-endpoints
|
||
# → db-worker: 5/5 tasks done ✓, branch: feature/db-schema
|
||
# → test-worker: 2/4 tasks done, branch: feature/e2e-tests
|
||
```
|
||
|
||
**AgentShield — 安全扫描**:
|
||
|
||
```bash
|
||
npx ecc-agentshield scan ~/.claude/
|
||
|
||
# 输出:
|
||
# ┌─────────────────────────────────────┐
|
||
# │ AgentShield Security Report │
|
||
# │ Grade: B (82/100) │
|
||
# ├─────────────────────────────────────┤
|
||
# │ CRITICAL (0) │
|
||
# │ HIGH (1) │
|
||
# │ → settings.json: acceptEdits │
|
||
# │ without scope restriction │
|
||
# │ MEDIUM (3) │
|
||
# │ → CLAUDE.md: no input validation │
|
||
# │ guidance for MCP tool results │
|
||
# │ → hooks/: PreToolUse hook runs │
|
||
# │ arbitrary shell without sandbox │
|
||
# │ → agents/: planner agent has │
|
||
# │ Write tool (should be read-only)│
|
||
# │ LOW (2) │
|
||
# │ → 2 MCP servers without auth │
|
||
# │ SECRET PATTERNS: 0 found │
|
||
# └─────────────────────────────────────┘
|
||
```
|
||
|
||
**Plankton — 写入时代码质量工具**:
|
||
|
||
三阶段架构: 自动格式化(静默) → 收集违规(JSON) → 委派修复(Claude 子进程)。
|
||
|
||
```
|
||
# 开发者编辑文件 → PostToolUse Hook 触发 Plankton
|
||
|
||
# Phase 1: Auto-format (静默，用户无感知)
|
||
prettier --write src/api/users.ts
|
||
eslint --fix src/api/users.ts
|
||
|
||
# Phase 2: Collect violations (JSON 格式)
|
||
{
|
||
"file": "src/api/users.ts",
|
||
"violations": [
|
||
{"rule": "no-any", "line": 23, "severity": "error"},
|
||
{"rule": "prefer-const", "line": 45, "severity": "warn"},
|
||
{"rule": "complexity", "line": 67, "severity": "error", "detail": "cyclomatic complexity 12 > max 10"}
|
||
]
|
||
}
|
||
|
||
# Phase 3: Delegate fixes (Claude 子进程)
|
||
# → 主 Agent 不处理，由 Plankton 生成的子进程自动修复
|
||
# → 子进程只针对特定 violation，最小化改动
|
||
# → 20+ linter 支持: ESLint, Prettier, stylelint, markdownlint...
|
||
```
|
||
|
||
**NanoClaw v2 — Agent REPL**:
|
||
|
||
```bash
|
||
# 启动 NanoClaw REPL
|
||
/claw
|
||
|
||
# 功能:
|
||
> /model sonnet # 切换模型（不重启会话）
|
||
> /skill load tdd # 热加载技能（不重启会话）
|
||
> /branch auth-feature # 会话分支（保留当前上下文创建分支副本）
|
||
> /search "payment" # 搜索历史会话
|
||
> /export session.json # 导出当前会话
|
||
> /compact # 手动压缩
|
||
> /metrics # 查看 token 使用、成本、工具调用统计
|
||
|
||
# 模型路由: NanoClaw 根据任务复杂度自动选择模型
|
||
# → 简单查询 → Haiku
|
||
# → 代码生成 → Sonnet
|
||
# → 架构决策 → Opus
|
||
```
|
||
|
||
**pass@k / pass^k — Agent 成功率度量**:
|
||
|
||
```
|
||
# pass@k: 同一任务运行 k 次，至少 1 次通过的概率
|
||
# 类似 LLM 评估中的 pass@1, pass@5 指标
|
||
|
||
# 例子: 评估 tdd-guide agent 生成测试的能力
|
||
/eval pass@5 "Generate unit tests for UserService.createUser()"
|
||
# → Run 1: PASS (覆盖率 85%)
|
||
# → Run 2: PASS (覆盖率 82%)
|
||
# → Run 3: FAIL (漏测 edge case)
|
||
# → Run 4: PASS (覆盖率 88%)
|
||
# → Run 5: PASS (覆盖率 84%)
|
||
# → pass@5 = 4/5 = 80%
|
||
# → pass@1 ≈ 80% (单次通过概率)
|
||
|
||
# pass^k: 连续 k 次全部通过的概率（更严格）
|
||
# → pass^5 = 0.8^5 ≈ 33% (连续5次全通过)
|
||
# 用于评估 Agent 在 CI/CD 中的可靠性
|
||
```
|
||
|
||
**本能的导入/导出/跨项目提升**:
|
||
|
||
```bash
|
||
# 导出当前项目的本能
|
||
/instinct-export
|
||
# → 输出: instincts-project-abc123.json
|
||
# → 包含所有 confidence >= 0.5 的本能
|
||
|
||
# 导入队友的本能
|
||
/instinct-import instincts-from-alice.json
|
||
# → 导入 12 个本能，初始 confidence 降为 0.5（需要在本项目中重新验证）
|
||
|
||
# 查看本能状态
|
||
/instinct-status
|
||
# → [0.9] GLOBAL "Always run prettier on .ts files after edit"
|
||
# → [0.8] GLOBAL "Use zod for API input validation" (2 projects confirmed)
|
||
# → [0.7] PROJECT "React components: check useCallback on handlers"
|
||
# → [0.5] PROJECT "Imported: Use testcontainers for DB tests" (unverified)
|
||
|
||
# 提升规则:
|
||
# → 项目本能 confidence >= 0.8 + 出现在 2+ 项目
|
||
# → 自动提升为 GLOBAL 本能
|
||
# → GLOBAL 本能可通过 /evolve 演化为正式 Skill
|
||
```
|
||
|
||
**双实例模式 — 新项目启动**:
|
||
|
||
```
|
||
# 实例 1: 脚手架
|
||
claude --session "scaffold"
|
||
> /plan "Create a Next.js 15 app with auth, payments, and admin panel"
|
||
> # → 生成项目结构、配置文件、基础路由
|
||
> # → 提交到 main 分支
|
||
|
||
# 实例 2: 研究（同时进行）
|
||
claude --session "research"
|
||
> "Research: Next.js 15 app router best practices for auth"
|
||
> "Research: Stripe integration patterns for Next.js"
|
||
> "Research: Admin panel libraries compatible with Next.js 15"
|
||
> # → 输出研究笔记到 .claude/research/
|
||
|
||
# 合并洞察:
|
||
# 回到实例 1，读取研究结果
|
||
> "Read .claude/research/ and apply findings to current scaffold"
|
||
> # → 根据研究结果调整架构决策
|
||
```
|
||
|
||
---
|
||
|
||
## 五、实战完整例子
|
||
|
||
### 例子: 从零开发 REST API 端点
|
||
|
||
```
|
||
# Step 0: Research（研究优先）
|
||
/search-first "express rate limiting middleware"
|
||
→ 发现 express-rate-limit 库 (26K stars, 维护活跃)
|
||
|
||
# Step 1: Plan（规划）
|
||
/plan "Add POST /api/users endpoint with validation and rate limiting"
|
||
→ planner agent (Opus):
|
||
- 架构: Controller → Service → Repository 分层
|
||
- 依赖: express-rate-limit, zod, bcrypt
|
||
- 风险: 并发注册的竞态条件
|
||
→ 等待用户确认
|
||
|
||
# Step 2: TDD（测试驱动）
|
||
/tdd
|
||
→ tdd-guide agent:
|
||
- users.controller.test.ts (RED → GREEN)
|
||
- users.service.test.ts (RED → GREEN)
|
||
- users.repository.test.ts (RED → GREEN)
|
||
→ 覆盖率 82% ✓
|
||
|
||
# Step 3: Review（代码审查，自动触发）
|
||
→ code-reviewer agent:
|
||
- CRITICAL: 无
|
||
- HIGH: "bcrypt rounds should be configurable" → 修复
|
||
- MEDIUM: "Consider adding request ID" → 记录
|
||
|
||
# Step 4: Security（安全检查，自动触发）
|
||
→ security-reviewer agent:
|
||
- ✓ 参数化查询、输入验证、速率限制
|
||
- ⚠ "Add helmet middleware" → 修复
|
||
|
||
# Step 5: Verify（验证循环）
|
||
/verify → Build ✓ | Types ✓ | Lint ✓ | Tests ✓ (82%) | Security ✓ | Diff ✓
|
||
|
||
# Step 6: Learn（提取模式）
|
||
/learn
|
||
→ [Instinct] "Express API 端点始终加: rate limiting + zod + helmet"
|
||
→ confidence=0.6, scope=project
|
||
```
|
||
|
||
### 例子: Bug 修复工作流
|
||
|
||
```
|
||
# 用户报告: "登录后偶尔跳转到 404 页面"
|
||
|
||
# Step 1: 研究（自动触发 planner）
|
||
/orchestrate bugfix "Login redirect sometimes lands on 404"
|
||
|
||
# → planner agent 分析:
|
||
# - 可能原因: race condition in auth callback
|
||
# - 相关文件: auth.callback.ts, router.middleware.ts
|
||
# - 重现条件: 快速连续点击登录按钮
|
||
|
||
# Step 2: TDD（先写复现测试）
|
||
# → tdd-guide agent:
|
||
describe('Auth callback race condition', () => {
|
||
it('should not redirect to 404 when callback fires twice', async () => {
|
||
// 模拟快速连续两次 callback
|
||
const result1 = authCallback(mockReq, mockRes);
|
||
const result2 = authCallback(mockReq, mockRes);
|
||
await Promise.all([result1, result2]);
|
||
expect(mockRes.redirect).toHaveBeenCalledWith('/dashboard');
|
||
expect(mockRes.redirect).not.toHaveBeenCalledWith('/404');
|
||
});
|
||
});
|
||
# → 测试 RED ✓ (确认 bug 存在)
|
||
|
||
# Step 3: 修复
|
||
# → 添加 idempotency guard:
|
||
# if (session.redirectHandled) return;
|
||
# session.redirectHandled = true;
|
||
# → 测试 GREEN ✓
|
||
|
||
# Step 4: Review
|
||
# → code-reviewer agent:
|
||
# - 确认修复正确
|
||
# - 建议: "Add comment explaining the race condition for future maintainers"
|
||
```
|
||
|
||
### 例子: 安全审计工作流
|
||
|
||
```
|
||
# 代码审计请求
|
||
/orchestrate security "Audit payment processing module"
|
||
|
||
# → security-reviewer agent 扫描:
|
||
# ┌────────────────────────────────────────────┐
|
||
# │ Security Audit: src/payments/ │
|
||
# ├────────────────────────────────────────────┤
|
||
# │ CRITICAL (1): │
|
||
# │ payment.service.ts:45 │
|
||
# │ → Stripe secret key in string literal │
|
||
# │ → FIX: Move to env var STRIPE_SECRET_KEY │
|
||
# │ │
|
||
# │ HIGH (2): │
|
||
# │ webhook.controller.ts:12 │
|
||
# │ → Missing Stripe signature verification │
|
||
# │ → FIX: Add stripe.webhooks.construct() │
|
||
# │ │
|
||
# │ refund.service.ts:78 │
|
||
# │ → No rate limiting on refund endpoint │
|
||
# │ → FIX: Add express-rate-limit (5/min) │
|
||
# │ │
|
||
# │ MEDIUM (3): │
|
||
# │ → Amount not validated as positive int │
|
||
# │ → Error messages expose internal IDs │
|
||
# │ → Missing audit log for payment actions │
|
||
# └────────────────────────────────────────────┘
|
||
|
||
# → code-reviewer agent 确认修复:
|
||
# - CRITICAL: Stripe key moved to .env ✓
|
||
# - HIGH: Webhook signature verification added ✓
|
||
# - HIGH: Rate limiting configured ✓
|
||
|
||
# → architect agent 建议:
|
||
# - "Consider adding idempotency keys for payment requests"
|
||
# - "Add circuit breaker for Stripe API calls"
|
||
```
|
||
|
||
### 例子: 重构工作流
|
||
|
||
```
|
||
/orchestrate refactor "Split monolithic UserService into domain services"
|
||
|
||
# → architect agent 分析:
|
||
# UserService (1200 lines) 应拆分为:
|
||
# - AuthService (认证/授权, ~200 lines)
|
||
# - ProfileService (用户资料, ~150 lines)
|
||
# - NotificationService (通知偏好, ~100 lines)
|
||
# - SubscriptionService (订阅管理, ~180 lines)
|
||
# 依赖图:
|
||
# AuthService ← ProfileService
|
||
# NotificationService ← SubscriptionService
|
||
# (无循环依赖 ✓)
|
||
|
||
# → code-reviewer agent 审查拆分:
|
||
# - 接口一致性 ✓
|
||
# - 依赖注入正确 ✓
|
||
# - 无遗漏的 public method ✓
|
||
|
||
# → tdd-guide agent 验证:
|
||
# - 原有 45 个测试全部通过 ✓
|
||
# - 新增 12 个测试覆盖拆分后的交互 ✓
|
||
# - 覆盖率: 原 78% → 现 85% ✓
|
||
```
|
||
|
||
---
|
||
|
||
## 六、扩展与自定义
|
||
|
||
### Skill 文件格式
|
||
|
||
```markdown
|
||
<!-- skills/my-skill/SKILL.md -->
|
||
---
|
||
name: my-custom-skill
|
||
description: "Domain-specific workflow for X"
|
||
origin: custom
|
||
version: 1.0.0
|
||
---
|
||
|
||
## When to Activate
|
||
- 当用户请求 X 相关操作时
|
||
- 当检测到 .config/x.json 文件存在时
|
||
|
||
## Workflow
|
||
1. Step one...
|
||
2. Step two...
|
||
|
||
## Configuration
|
||
- `PARAM_A`: 描述 (默认值: xxx)
|
||
|
||
## Output Format
|
||
- 预期输出结构...
|
||
```
|
||
|
||
每个 Skill 可选配 `agents/openai.yaml` 实现跨平台兼容（Codex/OpenCode）。
|
||
|
||
### Command 文件格式
|
||
|
||
```markdown
|
||
<!-- commands/my-command.md -->
|
||
---
|
||
description: "Short description shown in /help"
|
||
---
|
||
|
||
执行以下步骤:
|
||
1. ...
|
||
2. ...
|
||
3. 调用 `my-custom-skill` 技能
|
||
```
|
||
|
||
### Rule 分层覆盖
|
||
|
||
```
|
||
rules/
|
||
├── common/coding-style.md # 通用: "优先不可变"
|
||
├── golang/coding-style.md # Go 覆盖: "惯用 Go 使用指针接收器进行结构体变异"
|
||
├── python/coding-style.md # Python 覆盖: "使用 dataclasses(frozen=True)"
|
||
└── typescript/coding-style.md # TS 覆盖: "使用 Readonly<T> 和 as const"
|
||
```
|
||
|
||
**优先级**: 语言特定规则 > 通用规则（类似 CSS specificity）。
|
||
|
||
语言特定文件的开头模式:
|
||
|
||
```markdown
|
||
> This file extends [common/coding-style.md](../common/coding-style.md)
|
||
> with Go-specific content.
|
||
```
|
||
|
||
### 安装配置文件
|
||
|
||
| 配置文件 | 包含组件 | 适用场景 |
|
||
|---------|---------|---------|
|
||
| **core** | Rules + 基础 Commands | 轻量使用、小项目 |
|
||
| **developer** | core + Agents + TDD/Review Skills | 日常开发 |
|
||
| **security** | core + Security Agent + AgentShield | 安全审计 |
|
||
| **full** | 全部 108 Skills + 25 Agents + 57 Commands | 重度使用 |
|
||
|
||
```bash
|
||
# 交互式安装（推荐）
|
||
/configure-ecc
|
||
# → 引导选择配置文件
|
||
# → 选择安装到 user-level (~/.claude/) 或 project-level (.claude/)
|
||
# → 验证路径和兼容性
|
||
|
||
# 或通过插件市场
|
||
claude plugin marketplace add affaan-m/everything-claude-code
|
||
```
|
||
|
||
### 跨平台适配
|
||
|
||
ECC 通过适配层支持多个 AI 编码工具:
|
||
|
||
| 平台 | 适配方式 | 配置位置 |
|
||
|------|---------|---------|
|
||
| **Claude Code** | 原生支持 | `agents/`, `skills/`, `hooks/` |
|
||
| **Cursor** | Hook 桥接 | `.cursor/hooks/` → 映射到 Claude Code Hook 脚本 |
|
||
| **Codex (OpenAI)** | Agent YAML | `.codex/` + `skills/*/agents/openai.yaml` |
|
||
| **OpenCode** | 配置映射 | `.opencode/` |
|
||
|
||
Cursor 适配器的 DRY 设计: Cursor 的 15 个 Hook 事件映射回 Claude Code 的 Hook 脚本，避免重复维护。
|
||
|
||
```
|
||
.cursor/hooks/
|
||
├── on-file-save.sh → hooks/post-tool-use-format.sh
|
||
├── on-build.sh → hooks/pre-tool-use-build-check.sh
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 七、包管理器检测
|
||
|
||
ECC 自动检测项目使用的包管理器，遵循 6 级优先级:
|
||
|
||
```
|
||
1. 环境变量 (ECC_PACKAGE_MANAGER=pnpm)
|
||
2. 项目配置 (.npmrc 中的 package-manager 字段)
|
||
3. package.json 的 packageManager 字段
|
||
4. Lock 文件检测 (pnpm-lock.yaml → pnpm, yarn.lock → yarn, 等)
|
||
5. 全局配置 (~/.claude/settings.json)
|
||
6. 回退默认值 (npm)
|
||
```
|
||
|
||
---
|
||
|
||
## 八、与其他方案对比
|
||
|
||
| 维度 | ECC | 最小 CLAUDE.md | claude-code-ultimate-guide | 自建配置 |
|
||
|------|-----|---------------|---------------------------|---------|
|
||
| 定位 | 生产级框架 | 轻量约定 | 教学材料 | 定制化 |
|
||
| 复杂度 | 高 | 低 | 中 | 可控 |
|
||
| Token 开销 | 较大 | 最小 | 无 | 可控 |
|
||
| 学习曲线 | 陡峭 | 平缓 | 教程式 | 渐进 |
|
||
| 自动化 | 全面（Hook 驱动）| 手动 | 无 | 按需 |
|
||
| 学习系统 | 完整本能系统 | 无 | 无 | 无/部分 |
|
||
| 适用场景 | 重度日常使用 | 简单项目 | 入门学习 | 特定需求 |
|
||
|
||
---
|
||
|
||
## 九、关键数据
|
||
|
||
- GitHub Stars: 50K+（9天内达 31.9K）
|
||
- 社区评分: 5/5 CRITICAL（claude-code-ultimate-guide 评价）
|
||
- 作者实战: 10+ 个月日常高强度使用
|
||
- 跨平台: Claude Code, Cursor, Codex, OpenCode
|
||
- 许可: MIT
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
### Resources
|
||
- [[Everything Claude Code 完整指南]]
|
||
- [[Everything Claude Code 用法速查]]
|
||
- [[GSD 方法论与最佳实践]]
|
||
|
||
### Zettelkasten
|
||
- [[Everything Claude Code 最佳实践]]
|
||
- [[Everything Claude Code Agent 编排模式]]
|
||
- [[Everything Claude Code Token 优化]]
|
||
- [[Everything Claude Code 多服务编排详解]]
|
||
- [[Claude Code Memory 日常最佳实践]]
|
||
- [[Hook驱动优于提示词驱动]]
|
||
- [[MCP数量与上下文窗口的反比关系]]
|
||
- [[本能学习系统的演化路径]]
|
||
- [[上下文腐烂与全新窗口隔离]]
|