vault: add missing detailed sections to ECC methodology note
Added: Plankton 3-phase architecture, NanoClaw v2 REPL commands, pass@k/pass^k metrics with calculation example, loop-operator agent with stall detection, code-reviewer 5-step process, instinct import/export/promotion workflow, Skill/Command/Rule file formats, cross-platform adaptation (Cursor/Codex/OpenCode), installation profiles, package manager detection, verification report output, and CLAUDE.md compaction-surviving context design.
This commit is contained in:
Yaojia Wang
@@ -25,6 +25,8 @@ source: "https://github.com/affaan-m/everything-claude-code"
|
|||||||
4. 如果找到 80%+ 匹配的开源项目 → Fork/移植，不要从零写
|
4. 如果找到 80%+ 匹配的开源项目 → Fork/移植，不要从零写
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Exa MCP 用于研究**: 在规划阶段使用 `exa-web-search` MCP 进行更广泛的研究和先例发现。
|
||||||
|
|
||||||
**例子 — JWT 验证中间件**:
|
**例子 — JWT 验证中间件**:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -49,6 +51,34 @@ npm search jwt verify
|
|||||||
|
|
||||||
**自定义链**: `/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"`
|
**自定义链**: `/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 间交接文档格式**:
|
**Agent 间交接文档格式**:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
@@ -214,6 +244,33 @@ ECC 最独特的创新 — **本能学习系统**。
|
|||||||
→ 输出: 结构化 PASS/FAIL 报告
|
→ 输出: 结构化 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) 的设计考量。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 二、社区最佳实践
|
## 二、社区最佳实践
|
||||||
@@ -428,6 +485,100 @@ npx ecc-agentshield scan ~/.claude/
|
|||||||
# └─────────────────────────────────────┘
|
# └─────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**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
|
||||||
|
```
|
||||||
|
|
||||||
**双实例模式 — 新项目启动**:
|
**双实例模式 — 新项目启动**:
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -605,7 +756,127 @@ describe('Auth callback race condition', () => {
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 六、与其他方案对比
|
## 六、扩展与自定义
|
||||||
|
|
||||||
|
### 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 | 自建配置 |
|
| 维度 | ECC | 最小 CLAUDE.md | claude-code-ultimate-guide | 自建配置 |
|
||||||
|------|-----|---------------|---------------------------|---------|
|
|------|-----|---------------|---------------------------|---------|
|
||||||
@@ -619,7 +890,7 @@ describe('Auth callback race condition', () => {
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 七、关键数据
|
## 九、关键数据
|
||||||
|
|
||||||
- GitHub Stars: 50K+（9天内达 31.9K）
|
- GitHub Stars: 50K+（9天内达 31.9K）
|
||||||
- 社区评分: 5/5 CRITICAL（claude-code-ultimate-guide 评价）
|
- 社区评分: 5/5 CRITICAL（claude-code-ultimate-guide 评价）
|
||||||
|
|||||||
Reference in New Issue
Block a user