vault: add ECC methodology deep-dive and zettelkasten insights

New resource note with 6 core methodologies, community best practices, pitfalls, and practical examples. Three zettelkasten notes extract key insights: hook vs prompt reliability, MCP context tradeoffs, and the instinct learning system. Updated existing guides with cross-links.
2026-03-19 23:19:56 +01:00
parent e4382d01bb
commit 872401be72
6 changed files with 430 additions and 32 deletions
--- a/Resources/Everything
+++ b/Resources/Everything
@@ -7,7 +7,7 @@ source: "https://github.com/affaan-m/everything-claude-code"

 # Everything Claude Code 完整指南

-生产级 Claude Code 插件系统，包含 65+ skills、16 agents、40+ commands、hooks 和 rules。v1.8.0，经过 10+ 个月的高强度日常使用演化。
+生产级 Claude Code 插件系统，包含 108 skills、25 agents、57 commands、hooks 和 rules。v1.8.0，经过 10+ 个月的高强度日常使用演化。方法论与最佳实践见 [[Everything Claude Code 方法论与最佳实践]]，按场景速查见 [[Everything Claude Code 用法速查]]。

 ## 项目架构

@@ -185,7 +185,7 @@ cd everything-claude-code
 ## 16 Agents

 | Agent                  | 职责                |
-|-------|------|
+| ---------------------- | ----------------- |
 | `planner`              | 功能实现规划            |
 | `architect`            | 系统设计决策            |
 | `tdd-guide`            | 测试驱动开发            |
--- a/方法论与最佳实践.md
+++ b/方法论与最佳实践.md
@@ -0,0 +1,316 @@
+---
+created: "2026-03-19 12:00"
+type: resource
+tags: [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 用法速查]]。
+
+---
+
+## 一、六大核心方法论
+
+### 1. Research-First Development（研究优先开发）
+
+在写任何代码之前，必须搜索现有实现。这是 ECC 工作流的**步骤 0（强制）**。
+
+```
+流程:
+1. gh search repos / gh search code → 搜索 GitHub 现有实现
+2. 搜索包注册表（npm, PyPI, crates.io）→ 优先用成熟库
+3. Web 搜索 → 发现先例和最佳实践
+4. 如果找到 80%+ 匹配的开源项目 → Fork/移植，不要从零写
+```
+
+**例子 — 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"`
+
+**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 语句、持久化指标 |
+
+**运行时控制**（无需编辑文件）:
+
+```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 自动提醒）
+```
+
+禁用自动压缩的配置:
+
+```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 报告
+```
+
+---
+
+## 二、社区最佳实践
+
+### 渐进式采用路线
+
+| 阶段 | 重点 | 内容 |
+|------|------|------|
+| 第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 观察 → 模式检测 → 本能形成 → 技能演化 |
+
+---
+
+## 五、实战完整例子
+
+### 例子: 从零开发 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
+```
+
+---
+
+## 六、与其他方案对比
+
+| 维度 | 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
+
+- [[Everything Claude Code 完整指南]]
+- [[Everything Claude Code 用法速查]]
--- a/Resources/Everything
+++ b/Resources/Everything
@@ -16,7 +16,7 @@ source: "https://github.com/affaan-m/everything-claude-code"
 ### 1. 规划阶段

 | 场景      | 用什么                        | 怎么用                                |
-|------|--------|--------|
+| ------- | -------------------------- | ---------------------------------- |
 | 复杂功能设计  | `/plan` 命令 → planner agent | 输入需求，生成分阶段实施计划，等用户确认后再动手           |
 | 系统架构决策  | architect agent            | 自动启用，做 trade-off 分析、模式推荐、可扩展性评审    |
 | 多模型并行规划 | `/multi-plan`              | Claude + Codex + Gemini 并行出方案，对比择优 |
@@ -44,7 +44,7 @@ source: "https://github.com/affaan-m/everything-claude-code"
 ### 4. 语言专用审查

 | 语言         | 命令                      | 检查内容                                     |
-|------|------|----------|
+| ---------- | ----------------------- | ---------------------------------------- |
 | Python     | `/python-review`        | PEP 8、类型提示、安全、ruff/mypy/pylint           |
 | Go         | `/go-review`            | 惯用 Go 模式、并发安全、error handling、staticcheck |
 | Go 测试      | `/go-test`              | 表驱动测试、覆盖率分析                              |
--- a/Hook驱动优于提示词驱动.md
+++ b/Hook驱动优于提示词驱动.md
@@ -0,0 +1,24 @@
+---
+created: "2026-03-19 12:01"
+type: zettel
+tags: [claude-code, agent-reliability, automation]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# Hook 驱动优于提示词驱动
+
+AI Agent 的行为控制有两种机制：提示词（Skill/Rule）和 Hook。核心区别在于**确定性**：
+
+- **Hook**: 触发率 100%，确定性执行，不依赖模型判断
+- **提示词**: 触发率 50-80%，概率性，受上下文长度、模型注意力影响
+
+因此，**关键质量控制（格式化、安全检查、状态保存）应通过 Hook 实现，而非依赖提示词**。提示词适合灵活的、需要判断力的任务；Hook 适合必须每次都执行的不变量。
+
+这解释了 ECC v2 为什么把学习观察从 Skill 迁移到了 Hook — v1 中观察经常遗漏，v2 通过 PreToolUse/PostToolUse Hook 实现了 100% 捕获率。
+
+---
+
+## Related
+
+- [[Everything Claude Code 方法论与最佳实践]]
+- [[Everything Claude Code 完整指南]]
--- a/MCP数量与上下文窗口的反比关系.md
+++ b/MCP数量与上下文窗口的反比关系.md
@@ -0,0 +1,28 @@
+---
+created: "2026-03-19 12:02"
+type: zettel
+tags: [claude-code, context-window, performance, mcp]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# MCP 数量与上下文窗口的反比关系
+
+每个启用的 MCP Server 都会占用上下文窗口空间（工具定义、schema 描述等）。实测数据：
+
+- 0-5 个 MCP: 有效上下文接近 200K tokens
+- 10+ 个 MCP: 有效上下文降至 ~70K tokens（降幅 65%）
+
+**最佳实践**:
+- 活跃 MCP <= 10 个，活跃工具总数 <= 80 个
+- 用 `disabledMcpServers` 动态禁用不用的
+- 重操作优先用 CLI（如 `gh`）而不是 MCP
+- 使用 `llms.txt` 模式获取文档，避免 MCP 常驻开销
+
+这是 Claude Code 性能优化中**最重要的单一因素** — 比任何 Agent 或 Skill 都重要。
+
+---
+
+## Related
+
+- [[Everything Claude Code 方法论与最佳实践]]
+- [[Hook驱动优于提示词驱动]]
--- a/本能学习系统的演化路径.md
+++ b/本能学习系统的演化路径.md
@@ -0,0 +1,30 @@
+---
+created: "2026-03-19 12:03"
+type: zettel
+tags: [claude-code, machine-learning, continuous-improvement, agent-evolution]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# 本能学习系统的演化路径
+
+ECC 的 Continuous Learning v2.1 实现了一个 AI Agent 自我改进的闭环：
+
+```
+观察(Hook捕获) → 模式检测(Haiku模型) → 本能(Instinct) → 技能(Skill)
+```
+
+关键设计决策：
+
+1. **原子性**: 每个本能只描述一个行为，带信心分数 (0.3-0.9)
+2. **项目隔离**: 用 git remote URL hash 作命名空间，防止跨项目污染
+3. **渐进提升**: 单项目本能 → 多项目验证(2+项目, 信心>=0.8) → 全局技能
+4. **可逆性**: `/evolve` 生成的技能可以回退到本能级别
+
+这本质上是一个**强化学习循环** — 用户的接受/拒绝作为奖励信号，信心分数作为 Q-value 近似。与传统 fine-tuning 不同，它在推理时（通过 context injection）而非训练时改变行为，成本低且可控。
+
+---
+
+## Related
+
+- [[Everything Claude Code 方法论与最佳实践]]
+- [[Hook驱动优于提示词驱动]]