diff --git a/4 - Resources/Everything Claude Code 方法论与最佳实践.md b/4 - Resources/Everything Claude Code 方法论与最佳实践.md index 83ee913..2072739 100644 --- a/4 - Resources/Everything Claude Code 方法论与最佳实践.md +++ b/4 - Resources/Everything Claude Code 方法论与最佳实践.md @@ -25,6 +25,8 @@ source: "https://github.com/affaan-m/everything-claude-code" 4. 如果找到 80%+ 匹配的开源项目 → Fork/移植，不要从零写 ``` +**Exa MCP 用于研究**: 在规划阶段使用 `exa-web-search` MCP 进行更广泛的研究和先例发现。 + **例子 — JWT 验证中间件**: ```bash @@ -49,6 +51,34 @@ npm search jwt verify **自定义链**: `/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 @@ -214,6 +244,33 @@ ECC 最独特的创新 — **本能学习系统**。 → 输出: 结构化 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 + +--- +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 + +--- +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 和 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 | 自建配置 | |------|-----|---------------|---------------------------|---------| @@ -619,7 +890,7 @@ describe('Auth callback race condition', () => { --- -## 七、关键数据 +## 九、关键数据 - GitHub Stars: 50K+（9天内达 31.9K） - 社区评分: 5/5 CRITICAL（claude-code-ultimate-guide 评价）