Sync

6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md

@@ -0,0 +1,47 @@
+---
+created: "2026-03-08 21:30"
+type: zettel
+tags: [claude-code, best-practices, AI-tools]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# Everything Claude Code 最佳实践
+
+## 上下文窗口是最稀缺资源
+
+200k 上下文窗口在启用太多 MCP 后可能只剩 70k。三条铁律：
+
+1. **MCP < 10 个启用，< 80 个工具活跃** — 用 CLI + skill 替代 MCP（如 `gh` CLI 替代 GitHub MCP）
+2. **关闭 auto compact** — 在逻辑断点手动 `/compact`，避免在关键推理中被截断
+3. **CLAUDE.md < 200 行** — 详细规则放 `rules/`，利用 skill 的渐进式加载
+
+## Token 成本路由
+
+90% 任务用 Sonnet，只在架构决策和安全分析时用 Opus，搜索探索用 Haiku。设置：
+
+```json
+{ "model": "sonnet", "env": { "MAX_THINKING_TOKENS": "10000", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" } }
+```
+
+用 mgrep 替代 grep 可减少约 50% token 使用。
+
+## 记忆持久化
+
+- 每个 session 结束保存摘要到 `.tmp` 文件（记录：有效方法、无效尝试、待办事项）
+- 下次 session 提供文件路径作为上下文
+- 动态注入：`claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"`
+
+## 并行但有纪律
+
+- 最小可行并行度 — 不盲目开多终端
+- Git worktree 隔离并行实例
+- `/rename` 命名每个 chat，`/fork` 分叉非重叠工作
+- 级联方法：新任务右开，从左到右扫描，同时不超过 3-4 个
+
+---
+
+## Related
+
+- [[Everything Claude Code 完整指南]]
+- [[Everything Claude Code Agent 编排模式]]
+- [[Everything Claude Code Token 优化]]

6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md

@@ -0,0 +1,52 @@
+---
+created: "2026-03-08 21:31"
+type: zettel
+tags: [claude-code, agent-orchestration, workflow]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# Everything Claude Code Agent 编排模式
+
+## 顺序阶段模式
+
+```
+Phase 1: RESEARCH (Explore agent) → research-summary.md
+Phase 2: PLAN (planner agent)     → plan.md
+Phase 3: IMPLEMENT (tdd-guide)    → code changes
+Phase 4: REVIEW (code-reviewer)   → review-comments.md
+Phase 5: VERIFY (build-error-resolver) → done or loop
+```
+
+规则：每个 agent 一个输入一个输出；输出成为下一阶段输入；不跳过阶段；阶段间 `/clear`；中间结果保存到文件。
+
+## 迭代检索模式
+
+解决子代理上下文丢失问题：
+
+1. 主代理评估每个子代理返回
+2. 在接受前追问（传递目标上下文，不只是查询）
+3. 子代理回源获取答案
+4. 循环直到充分（最多 3 轮）
+
+核心洞察：子代理只知道字面查询，不知道请求背后的目的。必须传递 objective context。
+
+## 两终端启动模式（新项目）
+
+- **终端 1 (Scaffolding Agent)**: 创建项目结构、配置 CLAUDE.md、rules、agents
+- **终端 2 (Research Agent)**: 连接服务、搜索文档、创建 PRD、架构图
+
+## 模型选择
+
+| 任务 | 模型 | 原因 |
+|------|------|------|
+| 搜索/探索/文档 | Haiku | 快速便宜 |
+| 多文件实现/PR 审查 | Sonnet | 编码最佳平衡 |
+| 架构决策/安全分析/复杂 debug | Opus | 深度推理 |
+
+---
+
+## Related
+
+- [[Everything Claude Code 多服务编排详解]]
+- [[Everything Claude Code 最佳实践]]
+- [[Everything Claude Code 完整指南]]

6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md

@@ -0,0 +1,47 @@
+---
+created: "2026-03-08 21:32"
+type: zettel
+tags: [claude-code, token-optimization, cost]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# Everything Claude Code Token 优化
+
+## 节省 60%+ 成本的四个策略
+
+### 1. 模型路由
+90% 任务用 Sonnet，Haiku 做搜索/文档，Opus 只用于架构和安全。用 `/model-route` 自动路由。
+
+### 2. MCP 精简
+- 保持 < 10 个 MCP 启用
+- 用 CLI + skill 替代 MCP wrapper（如 gh CLI 替代 GitHub MCP）
+- 每个 MCP 消耗上下文窗口，多到一定程度 200k 变 70k
+
+### 3. 工具替换
+mgrep 替代 grep/ripgrep，在 50 任务 benchmark 中减少约 2x token 使用。
+
+### 4. 代码模块化
+文件保持 200-400 行（最大 800）。模块化代码库让 agent 不需要读取大文件，减少上下文消耗，且首次成功率更高。
+
+## 配置
+
+```json
+{
+  "model": "sonnet",
+  "env": {
+    "MAX_THINKING_TOKENS": "10000",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
+  }
+}
+```
+
+## Skill 的渐进式加载
+
+Skill 启动时只读描述（约 100 tokens），只在相关时才加载完整内容。这比把所有内容放在 CLAUDE.md 系统提示中高效得多。
+
+---
+
+## Related
+
+- [[Everything Claude Code 最佳实践]]
+- [[Everything Claude Code Agent 编排模式]]

6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md

@@ -0,0 +1,586 @@
+---
+created: "2026-03-08 22:15"
+type: zettel
+tags: [claude-code, multi-agent, orchestration, workflow]
+source: "https://github.com/affaan-m/everything-claude-code"
+---
+
+# Everything Claude Code 多服务编排详解
+
+ECC 的多服务编排分为两个层次，对应不同命令，加上社区总结的实战模式。
+
+---
+
+## 层次 1：/orchestrate — 单模型多 Agent 流水线
+
+核心思路：把一个复杂任务拆成多个阶段，每个阶段由不同专用 Agent 处理，通过 Handoff 文档传递上下文。
+
+### 4 种预设工作流
+
+| 类型 | Agent 链 | 适用场景 |
+|------|----------|----------|
+| `feature` | planner → tdd-guide → code-reviewer → security-reviewer | 新功能开发全流程 |
+| `bugfix` | planner → tdd-guide → code-reviewer | Bug 调查与修复 |
+| `refactor` | architect → code-reviewer → tdd-guide | 安全重构 |
+| `security` | security-reviewer → code-reviewer → architect | 安全专项审查 |
+
+### 用法
+
+```bash
+# 完整功能开发流水线
+/orchestrate feature "添加用户认证系统"
+
+# 自定义 Agent 链
+/orchestrate custom "architect,tdd-guide,code-reviewer" "重新设计缓存层"
+```
+
+### 执行过程
+
+1. Planner 分析需求 → 生成 Handoff 文档
+2. TDD Guide 读取 Handoff → 先写测试再实现 → 生成新 Handoff
+3. Code Reviewer 审查 → 发现问题 → 传递给下一个
+4. Security Reviewer 安全审计 → 最终报告 (SHIP / NEEDS WORK / BLOCKED)
+
+独立阶段可以并行执行（如 code-reviewer + security-reviewer + architect 同时跑）。
+
+### Handoff 文档格式
+
+```markdown
+## HANDOFF: [previous-agent] -> [next-agent]
+### Context — 做了什么
+### Findings — 关键发现或决策
+### Files Modified — 修改的文件
+### Open Questions — 未解决的问题
+### Recommendations — 建议的下一步
+```
+
+---
+
+## 层次 2：/multi-workflow — 多模型协作 6 阶段流水线
+
+核心思路：Claude 作为编排者（Orchestrator），调度 Codex（后端权威）和 Gemini（前端权威）并行工作，最终由 Claude 综合并实施。
+
+### 6 个阶段
+
+```
+Research → Ideation → Plan → Execute → Optimize → Review
+```
+
+| 阶段 | 做什么 | 谁来做 |
+|------|--------|--------|
+| 1. Research | 需求理解、上下文收集、打分(0-10) | Claude + MCP |
+| 2. Ideation | 技术可行性分析、方案对比 | Codex + Gemini 并行 |
+| 3. Plan | 后端架构 + 前端架构分别规划 | Codex + Gemini 并行 |
+| 4. Execute | 按计划写代码 | Claude（唯一写代码的） |
+| 5. Optimize | 安全/性能/可访问性审查 | Codex + Gemini 并行 |
+| 6. Review | 最终验证，对照计划检查完成度 | Claude |
+
+### 关键规则
+
+- **Code Sovereignty**：只有 Claude 能写文件，Codex/Gemini 只输出 Unified Diff（"脏原型"）
+- **Trust Rules**：后端听 Codex，前端听 Gemini
+- **每阶段评分 < 7 分自动停止**，要求用户确认后才继续
+- **Session 复用**：每次调用返回 SESSION_ID，后续阶段用 `resume` 保持上下文
+
+### 用法
+
+```bash
+/multi-workflow 开发一个实时聊天功能，包含 WebSocket 后端和 React 前端
+```
+
+---
+
+## 多实例 vs 单实例：两种并行模型
+
+编排的底层机制有本质区别，选错方式会浪费 token 或产生文件冲突。
+
+### 模型对比
+
+| | 多实例（Agent Teams / 多终端） | 单实例（Subagent / /orchestrate） |
+|---|---|---|
+| 进程数 | N 个独立 Claude Code 进程 | 1 个主进程 |
+| Context | 每个独立 context window | 共享主进程 context |
+| Token 消耗 | 3-7 倍 | 1-2 倍 |
+| 文件协调 | git 自动合并 / worktree 隔离 | 主进程统一写入，无冲突 |
+| 适合场景 | 大项目、多模块并行开发 | 单功能、流水线审查 |
+| 通信方式 | git commit + 共享文档 | Handoff 文档 + 内存传递 |
+
+### 多实例方式 1：Agent Teams（官方实验功能）
+
+一个 Team Lead 进程自动 spawn 多个 Teammate 子进程：
+- 每个 Teammate 在独立 context window 中工作
+- 通过 git 自动协调：认领任务、合并变更、解决冲突
+- 需要启用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+- Teammate 通常 20-30 秒内启动，1 分钟内开始产出
+
+### 多实例方式 2：多终端手动运行
+
+```
+终端 1: claude → 后端架构
+终端 2: claude → 数据库设计
+终端 3: claude → 前端开发
+终端 4: claude → 测试
+```
+
+- 每个终端是一个独立 Claude Code 实例
+- 人工协调（通过共享 Plan 文件）
+- 用 `claude --worktree` 让每个实例在独立 git worktree 中工作，避免文件冲突
+
+### 单实例方式：Subagent（/orchestrate 和 Agent tool）
+
+`/orchestrate` 在一个主进程内启动子代理：
+- 子代理共享同一个会话，各自独立执行
+- 主进程统一控制文件写入，不会冲突
+- 通过 Handoff 文档在 Agent 间传递上下文
+- 独立的子任务可并行（`run_in_background: true`）
+
+### 选择决策
+
+```
+项目规模？
+├── 小功能（1-3 文件）→ 单实例 /orchestrate feature
+├── 中型功能（5-10 文件）→ 单实例 /orchestrate custom（多 Agent 链）
+├── 大型模块（10+ 文件）→ 多实例 Agent Teams 或多终端
+└── 全栈项目（多模块）→ 多实例 + 文件所有权分配
+```
+
+---
+
+## 层次 3：社区实战模式
+
+### 多 Agent 并行调查（Bug Hunt）
+
+启动 5 个 Agent 分别调查不同假设：
+- log-analyst: 分析日志模式
+- code-archaeologist: 追溯 git 历史
+- reproducer: 尝试复现
+- db-detective: 检查数据库状态
+- network-inspector: 抓包分析
+
+让它们互相"辩论"，交叉验证结论。
+
+### 全栈 7+ Agent 生产级编排
+
+将一个全栈项目拆成 7 个专职 Agent，按依赖关系分 4 个阶段执行，能并行的并行，有依赖的串行。
+
+#### 7 个 Agent 角色定义
+
+| Agent | 职责 | 对应 ECC Agent | 输出物 |
+|-------|------|---------------|--------|
+| backend-architect | 后端架构：API 设计、服务分层、中间件、错误处理 | architect + planner | API 契约文档、路由定义、Service 接口 |
+| database-architect | 数据库架构：Schema 设计、索引、迁移、RLS | database-reviewer | DDL 迁移文件、ER 图、索引策略 |
+| frontend-developer | 前端实现：组件、状态管理、路由、UI/UX | code-reviewer (前端) | React/Vue 组件、页面、样式 |
+| test-automator | 自动化测试：单元 + 集成 + E2E | tdd-guide + e2e-runner | 测试文件、覆盖率报告 |
+| security-auditor | 安全审计：OWASP Top 10、secrets、注入防护 | security-reviewer | 安全报告、修复补丁 |
+| deployment-engineer | 部署：Docker、CI/CD、环境配置 | (自定义) | Dockerfile、GitHub Actions、部署脚本 |
+| observability-engineer | 可观测性：日志、监控、告警、tracing | (自定义) | 日志配置、Prometheus metrics、告警规则 |
+
+#### 4 阶段执行流程
+
+```
+阶段 1 (并行)    阶段 2 (串行)         阶段 3 (串行)      阶段 4 (并行)
+┌──────────────┐  ┌───────────────────┐  ┌──────────────┐  ┌─────────────────────┐
+│ backend-     │  │                   │  │              │  │ security-auditor    │
+│ architect    │──│ frontend-         │──│ test-        │──│ deployment-engineer │
+│              │  │ developer         │  │ automator    │  │ observability-      │
+│ database-    │  │ (依赖后端API契约) │  │ (依赖实现代码)│  │ engineer            │
+│ architect    │  │                   │  │              │  │ (三者可并行)         │
+└──────────────┘  └───────────────────┘  └──────────────┘  └─────────────────────┘
+```
+
+**阶段 1：架构设计（并行）**
+- backend-architect 和 database-architect 同时工作
+- backend-architect 输出 API 契约（RESTful 路由、请求/响应类型、中间件链）
+- database-architect 输出 Schema DDL、索引策略、RLS 策略
+- 两者通过共享的数据模型文档协调
+- 产出：`HANDOFF: architects -> frontend-developer`
+
+**阶段 2：前端实现（串行）**
+- 依赖阶段 1 的 API 契约和数据模型
+- frontend-developer 基于 API 契约生成类型定义和 API client
+- 实现页面组件、状态管理、路由
+- 产出：`HANDOFF: frontend-developer -> test-automator`
+
+**阶段 3：测试（串行）**
+- 依赖阶段 1+2 的全部实现代码
+- 写单元测试（后端 Service、前端组件）
+- 写集成测试（API 端点 + 数据库）
+- 写 E2E 测试（关键用户流程）
+- 验证覆盖率 >= 80%
+- 产出：`HANDOFF: test-automator -> final-review`
+
+**阶段 4：交付保障（并行）**
+- security-auditor：OWASP Top 10 扫描、secrets 检测、依赖漏洞审计
+- deployment-engineer：编写 Dockerfile、CI/CD pipeline、环境变量管理
+- observability-engineer：配置结构化日志、metrics endpoint、告警规则
+- 三者独立，可完全并行
+
+#### 实际实现方式
+
+**方式 A：用 /orchestrate custom**
+
+```bash
+# 阶段 1：并行架构设计
+/orchestrate custom "architect,database-reviewer" "设计电商平台后端架构和数据库 Schema"
+
+# 阶段 2：前端开发
+/orchestrate custom "planner,tdd-guide,code-reviewer" "基于 API 契约实现 React 前端"
+
+# 阶段 3+4：测试 + 安全 + 部署
+/orchestrate custom "tdd-guide,e2e-runner,security-reviewer" "编写测试套件并进行安全审计"
+```
+
+**方式 B：用 Agent Teams（实验性功能）**
+
+```bash
+# 启用 Agent Teams
+# 在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+
+# Team Lead 自动协调，启动多个 teammate
+# 每个 teammate 在独立 context window 中工作
+# 通过 git 自动协调文件修改
+```
+
+**方式 C：多终端手动编排**
+
+```
+终端 1 (Team Lead):    协调、规划、合并结果
+终端 2 (Backend):      后端架构 + API 实现
+终端 3 (Database):     Schema + 迁移 + 索引
+终端 4 (Frontend):     组件 + 页面 + 状态管理
+终端 5 (Testing):      测试编写 + 覆盖率验证
+```
+
+#### 关键协调机制
+
+**文件所有权**：每个 Agent 拥有不同的文件集，避免冲突
+```
+backend-architect:       src/api/**, src/services/**, src/middleware/**
+database-architect:      src/db/**, migrations/**, prisma/**
+frontend-developer:      src/components/**, src/pages/**, src/hooks/**
+test-automator:          tests/**, e2e/**, __tests__/**
+security-auditor:        只读审计，不直接改文件
+deployment-engineer:     Dockerfile, .github/**, docker-compose.yml
+observability-engineer:  src/logging/**, src/metrics/**, alerting/**
+```
+
+**Handoff 文档**：每个阶段结束后生成结构化交接文档，包含上下文、发现、修改文件、未解决问题、建议。
+
+**Git Worktree 隔离**：每个 Agent 在独立 worktree 中工作，最后由 Team Lead 合并。
+
+#### 实际注意事项
+
+- Token 消耗：7 个 Agent 约消耗单 Agent 的 5-7 倍 token
+- 起步建议：先用 3-4 个核心 Agent（architect + tdd-guide + code-reviewer + security-reviewer），稳定后再扩展
+- 协调开销：超过 4-5 个 Agent 后，协调成本开始上升，需权衡
+- 适用规模：中大型项目（10+ 文件的功能模块），小功能用 `/orchestrate feature` 更高效
+
+### 最佳实践
+
+- 起步用 3-5 个 Agent，在并行效率和协调成本之间取平衡
+- Agent 间通过共享文档（Handoff / Plan 文件）通信
+- 用 git worktree 隔离不同 Agent 的工作区，避免冲突
+- 每个 Agent 拥有独立的文件集，避免同时编辑同一文件
+- 开发时间可缩减约 75%（社区用户反馈）
+
+---
+
+## 全自动编排实操 Prompt
+
+两种方式实现全自动，不需要手动开关实例。
+
+### 方式 1：/orchestrate custom（单实例，求稳）
+
+一条命令，全自动串行执行 Agent 链：
+
+```bash
+/orchestrate custom "architect,database-reviewer,planner,tdd-guide,e2e-runner,code-reviewer,security-reviewer" "
+
+## 项目需求
+电商平台用户系统
+
+## 功能范围
+- 用户注册/登录（JWT）
+- 个人资料 CRUD
+- 密码重置流程
+- 角色权限（admin/user）
+
+## 技术栈
+- 后端：Node.js + Express + TypeScript
+- 数据库：PostgreSQL + Prisma
+- 前端：React + TailwindCSS
+
+## 约束
+- RESTful API 设计
+- 80%+ 测试覆盖率
+- RLS 启用
+"
+```
+
+### 方式 2：Agent Teams（多实例，求快）
+
+Team Lead 自动 spawn teammate，控制阶段顺序：
+
+```bash
+claude "
+你是 Team Lead。任务：设计并实现电商平台用户系统。
+
+## 技术栈
+- 后端：Node.js + Express + TypeScript
+- 数据库：PostgreSQL + Prisma
+- 前端：React + TailwindCSS
+
+## 执行计划
+
+### 阶段 1（并行启动 2 个 teammate）
+- teammate-1 'backend-architect': 设计 RESTful API 路由、Service 层接口、中间件链。
+  输出 API 契约文档到 docs/api-contract.md，实现 src/api/**、src/services/**、src/middleware/**
+- teammate-2 'database-architect': 设计用户表 Schema，编写 Prisma migration，定义索引和 RLS。
+  输出到 prisma/**、docs/schema.md
+
+等待阶段 1 全部完成后继续。
+
+### 阶段 2（启动 1 个 teammate）
+- teammate-3 'frontend-developer': 读取 docs/api-contract.md，生成 API client 和类型。
+  实现登录、注册、个人资料、密码重置页面。输出到 src/components/**、src/pages/**、src/hooks/**
+
+等待阶段 2 完成后继续。
+
+### 阶段 3（启动 1 个 teammate）
+- teammate-4 'test-automator': 单元测试覆盖 Service 层，集成测试覆盖 API 端点，
+  E2E 测试覆盖注册→登录→修改资料流程。覆盖率 >= 80%。输出到 tests/**、e2e/**
+
+等待阶段 3 完成后继续。
+
+### 阶段 4（并行启动 2 个 teammate）
+- teammate-5 'security-auditor': 审计全部代码，OWASP Top 10 + secrets 检测。
+  输出到 docs/security-report.md
+- teammate-6 'deployment-engineer': Dockerfile、docker-compose.yml、GitHub Actions。
+  输出到 .github/workflows/**、Dockerfile
+
+## 文件所有权（避免冲突）
+- teammate-1: src/api/**, src/services/**, src/middleware/**
+- teammate-2: prisma/**, docs/schema.md
+- teammate-3: src/components/**, src/pages/**, src/hooks/**, src/lib/api-client.ts
+- teammate-4: tests/**, e2e/**
+- teammate-5: docs/security-report.md（只读审计）
+- teammate-6: Dockerfile, docker-compose.yml, .github/**
+
+## 规则
+- 每个阶段必须等前一阶段全部完成
+- 每个 teammate 只修改自己负责的文件
+- 发现阻塞性问题立即报告，不要猜测
+"
+```
+
+### Prompt 写作要点
+
+| 要素 | 为什么重要 |
+|------|-----------|
+| 功能范围 | 明确边界，防止 Agent 做多余的事 |
+| 技术栈 | 避免 Agent 自行选型产生冲突 |
+| 阶段划分 + 等待指令 | 控制串行/并行顺序 |
+| 文件所有权 | 防止多 Agent 同时改同一文件 |
+| 输出物路径 | 让下游 Agent 知道去哪里读上游产出 |
+| 约束条件 | 覆盖率、安全标准等硬性要求 |
+
+### 两种方式对比
+
+| | /orchestrate custom | Agent Teams |
+|---|---|---|
+| 自动化程度 | 全自动 | 全自动 |
+| 并行能力 | 有限（子代理级） | 真并行（多进程） |
+| 速度 | 串行为主，较慢 | 并行阶段快 3-5 倍 |
+| Token 消耗 | 1-2 倍 | 3-7 倍 |
+| 稳定性 | 成熟稳定 | 实验性功能 |
+| 上手难度 | 零配置 | 需启用实验 flag |
+
+---
+
+## 全新项目开发策略
+
+### 单个功能：直接 /orchestrate feature
+
+```bash
+/orchestrate feature "Add JWT-based user authentication with login, register, password reset"
+```
+
+4 个 Agent 依次执行：
+
+1. **Planner** — 规划出 controller、service、middleware、routes 等文件结构
+2. **TDD Guide** — 先写 `auth.test.ts`，再写 `auth.service.ts`、`auth.controller.ts`
+3. **Code Reviewer** — 检查错误处理、输入验证、代码质量
+4. **Security Reviewer** — 检查 JWT 存储、密码哈希、CSRF、rate limiting
+
+### 整个项目：先 /plan 拆分，再逐模块 /orchestrate
+
+```bash
+# 第 1 步：整体规划，拆分模块
+/plan "电商平台：用户系统 + 商品管理 + 订单系统 + 支付集成"
+
+# 第 2 步：按模块逐个走完整流水线
+/orchestrate feature "用户注册登录系统"
+/orchestrate feature "商品 CRUD 和分类管理"
+/orchestrate feature "购物车和订单流程"
+/orchestrate feature "支付网关集成"
+```
+
+### 需要架构设计时：自定义 Agent 链
+
+全新项目往往需要先做架构决策，在链头加上 architect：
+
+```bash
+/orchestrate custom "architect,planner,tdd-guide,code-reviewer,security-reviewer" "设计并实现微服务网关"
+```
+
+### 前后端全栈：用 /multi-workflow
+
+当前后端都要从头开发时，用多模型协作更高效：
+
+```bash
+/multi-workflow "电商平台用户系统，包含 React 前端和 Node.js 后端"
+```
+
+Codex 负责后端架构，Gemini 负责前端设计，Claude 综合实施。
+
+### 选择决策树
+
+```
+全新项目？
+├── 单个功能 → /orchestrate feature
+├── 多模块项目 → /plan 拆分 → 逐个 /orchestrate feature
+├── 需要架构设计 → /orchestrate custom (加 architect)
+└── 前后端全栈 → /multi-workflow
+```
+
+---
+
+## 阶段追踪最佳实践
+
+ECC 本身没有内建 Kanban/Sprint board，但可以组合 3 层机制实现"完成一个阶段就 mark 完成"的效果。
+
+### 3 层机制
+
+| 层 | 机制 | 属于 | 作用 |
+|---|------|------|------|
+| 1 | TaskCreate + TaskUpdate | Claude Code 原生（v2.1.16+） | 状态追踪 + 依赖关系 + 跨 session 持久化 |
+| 2 | `/checkpoint` | ECC | Git 级别快照，可回滚 |
+| 3 | Handoff 文档 | ECC `/orchestrate` | Agent 间上下文传递 |
+
+### Claude Code 原生 Tasks 系统
+
+取代了旧的 TodoWrite，是最接近 Kanban 的原生机制：
+
+```
+TaskCreate("backend-architecture")
+  → TaskUpdate(status: in_progress)    # 开始时标记
+  → TaskUpdate(status: completed)       # 完成时标记
+```
+
+核心能力：
+- **依赖关系**：`addBlockedBy` 让阶段 2 等阶段 1 完成
+- **跨 session 持久化**：context 压缩后 task 状态不丢
+- **跨实例共享**：设置 `CLAUDE_CODE_TASK_LIST_ID` 环境变量，多个 Claude 实例看到同一个任务板
+- **3-Task 规则**：少于 3 步的直接做，不值得建 task
+
+### 组合实践：/orchestrate + Tasks + /checkpoint
+
+在 `/orchestrate` 的 prompt 中加入 Task 追踪指令：
+
+```bash
+/orchestrate custom "architect,database-reviewer,planner,tdd-guide,code-reviewer,security-reviewer" "
+
+## 项目需求
+电商平台用户系统
+
+## 技术栈
+Node.js + Express + TypeScript + PostgreSQL + Prisma + React
+
+## 阶段追踪要求
+每个 Agent 开始时：
+1. TaskCreate 创建当前阶段任务
+2. TaskUpdate 标记 in_progress
+3. 如果依赖前一阶段，用 addBlockedBy 关联
+
+每个 Agent 完成时：
+1. /checkpoint create 'phase-N-done'
+2. TaskUpdate 标记 completed
+3. 生成 Handoff 文档传递给下一个 Agent
+"
+```
+
+### Agent Teams + 共享 Task Board
+
+多实例场景下，用共享 Task 列表实现自动阶段协调：
+
+```bash
+# 所有实例共享同一个任务板
+export CLAUDE_CODE_TASK_LIST_ID="ecommerce-user-system"
+
+claude "
+你是 Team Lead。
+
+## 任务追踪规则
+- 用 TaskCreate 为每个阶段创建任务，带依赖关系
+- teammate 开始工作时 TaskUpdate → in_progress
+- teammate 完成后 TaskUpdate → completed
+- 所有 teammate 共享同一个 CLAUDE_CODE_TASK_LIST_ID
+- 通过 Task 状态判断前置阶段是否完成，自动启动下一阶段
+
+## 阶段依赖
+- Task: 'backend-architecture' → teammate-1
+- Task: 'database-schema' → teammate-2
+- Task: 'frontend' (blockedBy: backend-architecture, database-schema) → teammate-3
+- Task: 'testing' (blockedBy: frontend) → teammate-4
+- Task: 'security-audit' (blockedBy: testing) → teammate-5
+- Task: 'deployment' (blockedBy: testing) → teammate-6
+"
+```
+
+Team Lead 通过 Task 状态自动判断何时启动下一阶段，不需要人工干预。
+
+### 追踪机制选择
+
+| 需求 | 用什么 |
+|------|--------|
+| 阶段状态（pending/in_progress/completed） | TaskCreate + TaskUpdate（原生） |
+| 阶段间依赖 | addBlockedBy（原生） |
+| 多实例共享进度 | CLAUDE_CODE_TASK_LIST_ID（原生） |
+| Git 级别快照回滚 | `/checkpoint`（ECC） |
+| Agent 间上下文传递 | Handoff 文档（ECC `/orchestrate`） |
+| 自主循环 + 质量门禁 | `/loop-start` + `/quality-gate`（ECC） |
+| 完整 Kanban 3 文件看板 | planning-with-files（第三方插件，非 ECC） |
+
+---
+
+## 命令选择速查
+
+| 场景 | 用哪个 |
+|------|--------|
+| 单个功能从规划到上线 | `/orchestrate feature` |
+| 修 Bug 全流程 | `/orchestrate bugfix` |
+| 安全重构 | `/orchestrate refactor` |
+| 前后端都要改，多 AI 协作 | `/multi-workflow` |
+| 只要多模型并行出方案 | `/multi-plan` |
+| 只要多模型并行写代码 | `/multi-execute` |
+
+---
+
+## Related
+
+- [[Everything Claude Code 用法速查]]
+- [[Everything Claude Code Agent 编排模式]]
+- [[Everything Claude Code 完整指南]]
+
+## Source
+
+- [Claude Code Task Management 原生指南](https://claudefa.st/blog/guide/development/task-management)
+- [Claude Code Tasks 更新公告](https://venturebeat.com/orchestration/claude-codes-tasks-update-lets-agents-work-longer-and-coordinate-across)
+- [Claude Code Checkpointing 官方文档](https://code.claude.com/docs/en/checkpointing)
+- [Claude Code Agent Teams 官方文档](https://code.claude.com/docs/en/agent-teams)
+- [Claude Code 多 Agent 编排完整指南 2026](https://www.eesel.ai/blog/claude-code-multiple-agent-systems-complete-2026-guide)
+- [Shipyard: Multi-agent orchestration](https://shipyard.build/blog/claude-code-multi-agent/)
+- [10+ Claude 实例并行编排实战](https://dev.to/bredmond1019/multi-agent-orchestration-running-10-claude-instances-in-parallel-part-3-29da)
+- [Claude Code Swarm 编排 Skill](https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea)
+- [Ruflo: Agent 编排平台](https://github.com/ruvnet/ruflo)
+- [Claude Code Workflow 框架](https://github.com/catlog22/Claude-Code-Workflow)

6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md

@@ -0,0 +1,192 @@
+---
+created: "2026-03-08 23:30"
+type: zettel
+tags: [claude-code, memory, persistence, workflow, best-practice]
+source: "daily usage + ECC documentation"
+---
+
+# Claude Code Memory 日常最佳实践
+
+Claude Code 有 5 层 memory 机制，从自动到手动，每层解决不同问题。
+
+---
+
+## 5 层 Memory 全景
+
+```
+层 1: CLAUDE.md (全局人设，每次会话自动加载)
+层 2: Auto Memory (~/.claude/projects/*/memory/)    ← 最有用
+层 3: Session Persistence (~/.claude/sessions/)      ← 自动运行
+层 4: Instincts (~/.claude/homunculus/instincts/)    ← 自动学习
+层 5: Project CLAUDE.md (项目根目录)                  ← 团队共享
+```
+
+---
+
+## 层 1：~/.claude/CLAUDE.md — 全局人设
+
+每次会话自动加载。放什么：
+- 个人偏好（no emoji、文件大小限制、commit 格式）
+- 技术栈声明（Python, C#/.NET, Java, TypeScript）
+- 工作流规则的索引（指向 rules/ 而不是重复内容）
+
+不放什么：
+- 具体项目细节（放项目 CLAUDE.md）
+- 临时任务状态（放 Auto Memory）
+- 技术文档（放 rules/ 或 skills/）
+
+保持简洁（30 行左右），越短 = 每次加载消耗越少 token。
+
+---
+
+## 层 2：Auto Memory — 项目级持久记忆
+
+位置：`~/.claude/projects/<project-hash>/memory/`
+
+### MEMORY.md 结构模板
+
+```markdown
+# 项目名 - Memory Index
+> MEMORY.md = index (always loaded, max 200 lines). Details in topic files.
+
+## Environment
+- 运行环境、依赖版本、特殊配置
+
+## Key Architecture
+- 核心目录结构、关键文件路径
+- See [architecture.md](architecture.md) for details
+
+## Workflow Rules
+- 这个项目的开发流程
+
+## Active Session State
+**Task**: 当前任务描述
+**Status**: in_progress / complete
+**Plan file**: 计划文件路径
+
+## Known Issues
+- 已知的坑、预期的测试失败、临时 workaround
+
+## Topic Files
+- [architecture.md](architecture.md)
+- [test-locations.md](test-locations.md)
+- [debugging.md](debugging.md)
+```
+
+### 关键规则
+
+- MEMORY.md 超过 200 行会被截断，保持它是**索引**而不是详情
+- 详情拆到 topic file，从 MEMORY.md 链接过去
+- 只存**稳定模式**，不存临时信息
+- topic file 按主题组织（architecture、debugging、config、test-locations）
+
+---
+
+## 层 3：Session Persistence — 会话自动摘要
+
+位置：`~/.claude/sessions/`
+
+ECC hook 自动运行：
+- 会话开始 → 自动加载最近 7 天的 session 文件
+- 会话结束 → 自动保存摘要（任务、修改文件、使用工具）
+
+日常操作：
+```bash
+/sessions list                              # 查看历史
+/sessions load 2026-03-08                   # 加载特定会话
+/sessions alias 2026-03-08 "stock-api"      # 起别名
+/sessions load stock-api                    # 用别名加载
+```
+
+不需要手动操心，hook 负责自动创建和更新。
+
+---
+
+## 层 4：Instincts — 自动学习行为模式
+
+位置：`~/.claude/homunculus/instincts/personal/`
+
+ECC continuous-learning-v2 hook 在后台观察操作，自动提取模式：
+- 你纠正 Claude → 学到 instinct
+- 你反复用某种模式 → 学到 instinct
+- instinct 有置信度分数（0.3 → 0.9 逐步提升）
+
+日常操作：
+```bash
+/instinct-status                    # 查看已学习的 instinct
+/instinct-export                    # 导出给队友
+/instinct-import                    # 导入其他项目的
+/promote                            # 项目 instinct → 全局
+```
+
+手动告诉 Claude 记住偏好：
+```
+"记住：这个项目用 pnpm 而不是 npm"
+"记住：Billo 项目的所有 API 都要加 correlation-id"
+```
+
+---
+
+## 层 5：项目 CLAUDE.md vs Auto Memory
+
+| | 项目 CLAUDE.md | Auto Memory |
+|---|---|---|
+| 位置 | 项目根目录（git 跟踪） | ~/.claude/projects/（本地） |
+| 团队共享 | 是（提交到 git） | 否（个人） |
+| 内容 | 项目规范、命令、架构说明 | 个人经验、调试记录、任务状态 |
+| 修改频率 | 低（稳定后很少改） | 高（每次会话可能更新） |
+
+---
+
+## 日常工作流
+
+### 开始新项目
+
+1. 创建项目 CLAUDE.md（团队共享的规范）
+2. Auto Memory 自动创建 memory/ 目录
+3. 首次会话后 MEMORY.md 开始积累
+4. 遇到项目特有模式 → 写入 topic file
+
+### 继续昨天的工作
+
+1. 打开 Claude Code → 自动加载 MEMORY.md + 最近 session
+2. Claude 通过 Active Session State 知道你做到哪了
+3. 继续工作
+4. 完成后更新 MEMORY.md 状态
+
+### 切换项目
+
+1. cd 到另一个项目
+2. Claude 自动加载那个项目的 CLAUDE.md + MEMORY.md
+3. 上下文完全切换，不会混淆
+
+### 发现通用模式
+
+1. 在项目 A 发现好用模式
+2. "记住：所有 API 都要用 Result pattern"
+3. instinct 保存到项目级
+4. 在项目 B 也验证了 → `/promote` 提升为全局
+
+### Debug 经验保存
+
+```
+你："把这次 debug 经验保存到 memory"
+Claude → 写入 memory/debugging.md
+Claude → 更新 MEMORY.md 索引
+下次遇到类似问题 → Claude 自动读到这个经验
+```
+
+---
+
+## Related
+
+- [[Everything Claude Code 多服务编排详解]]
+- [[Everything Claude Code 用法速查]]
+- [[Everything Claude Code 完整指南]]
+
+## Source
+
+- [Claude Code 官方文档](https://code.claude.com/docs/en/how-claude-code-works)
+- [Claude Code Task Management](https://claudefa.st/blog/guide/development/task-management)
+- ECC hooks: session-start.js, session-end.js, observe.sh
+- ECC skills: continuous-learning-v2, strategic-compact