diff --git a/4 - Resources/Claude-Code/Claude Code 多Agent编排 MOC.md b/4 - Resources/Claude-Code/Claude Code 多Agent编排 MOC.md index 20f960a..a60d6cf 100644 --- a/4 - Resources/Claude-Code/Claude Code 多Agent编排 MOC.md +++ b/4 - Resources/Claude-Code/Claude Code 多Agent编排 MOC.md @@ -7,7 +7,7 @@ tags: [moc, claude-code, orchestration, multi-agent, index] # Claude Code 多Agent编排 MOC > 这个主题的总入口。把"原生原语 → 官方实践 → ECC 落地 → 实战模式 → 自治循环 → 底层原理"串成一张图。 -> 最近更新:2026-06-18(新增 orch-* 家族、官方最佳实践、dynamic workflows)。 +> 最近更新:2026-06-27(新增「新项目开发最佳实践 2026 调研」+ 四阶段工作流 / 验证循环 / CLAUDE.md 加载机制三篇 zettel)。 --- @@ -30,6 +30,7 @@ tags: [moc, claude-code, orchestration, multi-agent, index] ## 1. 原生原语与官方实践(Anthropic / Claude Code 官方) +- [[Claude Code 新项目开发最佳实践 (2026 调研)]] —— **新项目四支柱**:Explore→Plan→Implement→Commit、Memory、Subagent、Workflow(经 deep-research 对抗式校验,标注时效与证伪项) - [[Claude Code 官方多Agent编排最佳实践 (2026)]] —— 三原语对比、orchestrator-worker 七原则、3-5 规模、成本(4x/15x token)、eval - [[Claude Code Agent Teams 官方多Agent编排]] —— lead + 队友、共享任务列表、互相通信 - [[Claude Code Dynamic Workflows 最佳实践与实例]] —— pipeline/parallel、质量模式、Vue 新闻信 / deep-research / Bun 移植实例 @@ -62,6 +63,9 @@ tags: [moc, claude-code, orchestration, multi-agent, index] - [[20260414230719 Agent 工具 worktree 隔离是 Windows 原生并行的关键]] —— 会话内并行隔离 - [[20260319120200 MCP数量与上下文窗口的反比关系]] —— 工具数量与上下文权衡 - [[20260308213200 Everything Claude Code Token 优化]] —— 子 agent 用 haiku 省成本 +- [[20260627062503 Explore-Plan-Implement-Commit 四阶段工作流]] —— 先看再想后写最后交 +- [[20260627062504 自给自足验证循环配合 TDD]] —— 客观验证信号驱动自我迭代 +- [[20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖]] —— 分层放置规则的底层机制 ## 6. 相关基础 diff --git a/4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md b/4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md new file mode 100644 index 0000000..f6e8fce --- /dev/null +++ b/4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md @@ -0,0 +1,182 @@ +--- +created: "2026-06-27" +type: resource +tags: [claude-code, best-practices, new-project, memory, subagent, workflow, hooks, research, verified] +source: "deep-research 工作流 · Anthropic 官方文档与工程博客 + 社区实践 · 2026-06-27" +--- + +# Claude Code 新项目开发最佳实践 (2026 调研) + +> 一次 deep-research 工作流(103 个 agent / 5 阶段 / 98 条声明 → 25 条对抗式校验 → 23 条确认、2 条证伪)的结构化产物。 +> 聚焦**如何用 Claude Code 高效开启一个新项目**,覆盖四大支柱:启动工作流、Memory、Subagent 编排、Workflow 编排。 +> 所有结论以 **Anthropic 一手文档/工程博客**为主,标注校验票数与置信度。时效:**2025–2026 现行**。 +> 总入口见 → [[Claude Code 多Agent编排 MOC]]。 + +--- + +## 一图速览:四大支柱 + +``` +启动工作流 Explore → Plan → Implement → Commit + /init + 自给自足验证循环(配 TDD) +Memory CLAUDE.md 四作用域(树状拼接加载) + Auto memory(v2.1.59+) +Subagent 独立上下文/工具 · 内置 Explore/Plan/general-purpose · orchestrator-worker · 一任务一代理 +Workflow Hooks 确定性自动化 · 子代理并行开发 · 多代理选型边界(广度优先才用) +``` + +--- + +## 支柱一:启动新项目的工作流(置信度:高 · 票 2-0/2-0/3-0) + +官方推荐**四阶段循环**,不要一上来就让 Claude 写代码: + +1. **探索 Explore** —— 先进 **plan mode(只读)**,让 Claude 读代码 / PRD、收集上下文,**不改任何文件**。 +2. **规划 Plan** —— 生成详细实现计划;计划可按 **Ctrl+G 在编辑器中直接编辑**后再确认。 +3. **实现 Implement** —— 退出 plan mode,**对照计划写代码 + 测试**。 +4. **提交 Commit** —— 让 Claude 写描述性 commit message 并开 PR。 + +配套关键动作: +- **新仓库先跑 `/init`**:自动检测构建系统 / 测试框架 / 代码模式,生成起始 `CLAUDE.md`,作为后续打磨基础。 +- **先 `git init` 再开第一次会话**:git 作为回滚安全网(社区实践 · Builder.io)。 +- **搭建「自给自足验证循环」(self-sufficient loop)**:让 Claude 能自动跑 `build / test / lint` 并据结果自我纠正。**配合 TDD(先写测试、再写实现)效果尤其好** —— 测试给了 Claude 明确的 GREEN 目标。 + +原子笔记:[[20260627062503 Explore-Plan-Implement-Commit 四阶段工作流]]、[[20260627062504 自给自足验证循环配合 TDD]] + +来源:[best-practices](https://code.claude.com/docs/en/best-practices) · [Anthropic 团队用例 PDF](https://www-cdn.anthropic.com/58284b19e702b49db9302d5b6f135ad8871e7658.pdf) · [Builder.io](https://www.builder.io/blog/setting-up-claude-code-project) + +--- + +## 支柱二:Memory 机制(置信度:高 · 票全 3-0) + +### 2.1 CLAUDE.md 的四个作用域(从宽到窄,按加载顺序) + +| 作用域 | 位置 | 用途 | +|---|---|---| +| Managed policy | 组织级 | 企业统一策略 | +| **User** | `~/.claude/CLAUDE.md` | 跨所有项目的个人偏好(`~/.claude/rules/` 在这层) | +| **Project** | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | **入 git,团队共享** | +| Local | `./CLAUDE.local.md` | 个人专属,**应加入 `.gitignore`** | + +### 2.2 加载机制(关键,易被忽视) +- 沿目录树**向上遍历发现**; +- **祖先目录文件启动时全量加载**,**子目录嵌套 CLAUDE.md 在读取该目录时按需加载**; +- 所有文件是**拼接(append)而非覆盖**; +- monorepo 父目录会自动拉取; +- 支持 `@path/to/import` 导入其它文件。 + +原子笔记:[[20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖]] + +### 2.3 写法规范 +- **单文件 < 200 行** —— 越长越耗上下文、越降低遵循度。 +- **过大就拆到 `.claude/rules/`**:用带 `paths` frontmatter 的 path-scoped rules,按文件类型 / 子目录按需加载。 +- **记什么**:工作流、工具用法、期望;**针对性指令防复发错误**(如指定"如何运行 pytest""避免不必要的 cd")。Anthropic 数据基础设施团队头号建议就是"写详尽的 CLAUDE.md"。 +- **持续打磨**:基于实际使用迭代,不是写一次就完。 + +### 2.4 两套互补记忆系统 +- **手写 CLAUDE.md** = 你给的指令与规则。 +- **Auto memory** = Claude 从纠正与偏好中**自动学习写入**。默认开启(需 **v2.1.59+**),存于 `~/.claude/projects//memory/`;其 `MEMORY.md` 的**前 200 行或前 25KB**(先到为准)在每次会话开始加载。 + +> 与库内既有笔记互补:[[20260308223000 Claude Code Memory 日常最佳实践]](5 层 memory 全景 + MEMORY.md 索引模板)。 + +来源:[memory 文档](https://code.claude.com/docs/en/memory) · best-practices · [Advanced Patterns PDF](https://resources.anthropic.com/hubfs/Claude%20Code%20Advanced%20Patterns_%20Subagents,%20MCP,%20and%20Scaling%20to%20Real%20Codebases.pdf) + +--- + +## 支柱三:Subagent / Agent 编排(置信度:高 · 票全 3-0) + +### 3.1 子代理是什么、怎么配 +- 在**独立上下文窗口 + 独立工具集**运行,适合"读大量文件 / 专门聚焦"而**不污染主对话**。 +- 定义为带 **YAML frontmatter 的 Markdown**: + - `.claude/agents/`(项目级,优先级高,**建议入版本控制**) + - `~/.claude/agents/`(用户级,跨项目) + - 同名时**项目级优先**;**仅 `name` / `description` 必填**。 +- **须显式调用**:如"用 subagent 审查这段代码的安全问题"。 + +### 3.2 内置子代理(开箱即用) +- **Explore** —— 用 Haiku 跑只读代码搜索 / 探索(快且便宜)。 +- **Plan** —— plan mode 下做只读调研收集上下文。 +- **general-purpose** —— 全工具,处理"探索 + 修改"的复杂多步任务。 +- ⚠️ **Explore 和 Plan 会跳过 CLAUDE.md 与父会话 git 状态**以保持快;其余子代理两者都加载。 + +### 3.3 编排范式:orchestrator-worker(协调者-工作者) +- **一任务一代理**:把复杂工作流拆成多个专门子代理,而非单一 prompt 包办 —— 改善调试与输出质量。 +- **独立调研可并行 spawn**:多子代理同时探索不同方面,主代理再综合 —— 研究路径互不依赖时最佳。 +- **委派 prompt 要写明**:显式目标、边界、输出格式、工具用法("不要研究 X,那是另一个 subagent 的工作"),避免任务重叠。 +- **实证**:Anthropic 内部多代理研究系统(Opus 4 主 + Sonnet 4 子)较单代理 Opus 4 **提升 90.2%**(自报内部评测,约 15x token)。 + +### 3.4 何时用子代理 vs 留主对话 + +| 用子代理 | 留主对话 | +|---|---| +| 产生大量无需保留的冗长输出 | 需频繁来回迭代 | +| 需强制工具限制 | 多阶段共享大量上下文 | +| 工作自包含、可返回摘要 | 快速 targeted 改动 / 延迟敏感 | + +> 深入既有笔记:[[Claude Code 官方多Agent编排最佳实践 (2026)]]、[[20260618073140 编排即排序门控与委派]]、[[20260320100100 上下文腐烂与全新窗口隔离]]、[[20260308213200 Everything Claude Code Token 优化]]。 + +来源:[sub-agents](https://code.claude.com/docs/en/sub-agents) · [multi-agent-research-system](https://www.anthropic.com/engineering/multi-agent-research-system) · Advanced Patterns PDF + +--- + +## 支柱四:Workflow 编排(置信度:高 · 票全 3-0) + +- **Hooks = 确定性自动化**:在生命周期特定节点自动执行 shell 命令,由 harness **确定性执行**(不靠模型自觉)。典型: + - `PostToolUse(Edit|Write)` → 改动后自动跑 lint / format / test + - `PreToolUse` / `Stop` → 提交前 lint / 最终检查 +- **子代理实现并行开发**:如一个子代理搭后端 API,主代理同时构建前端。 +- **专门化生成案例**:Anthropic 营销 team-of-one 用两个子代理(一个写 headline、一个写 description),几分钟生成数百条广告。 + +### ⚠️ 选型边界(重要) +**多代理系统不适合大多数编码任务**,也**不适合"需共享同一上下文 / 代理间强依赖"**的场景。它最适合:**广度优先、可大规模并行、方向相互独立**的工作。并行多代理约消耗 **15x token**,要权衡成本。 + +> 深入既有笔记:[[20260319120100 Hook驱动优于提示词驱动]]、[[Claude Code Dynamic Workflows 最佳实践与实例]](pipeline vs parallel)、[[20260319120200 MCP数量与上下文窗口的反比关系]]。 + +来源:[hooks](https://code.claude.com/docs/en/hooks) · [enabling-claude-code-autonomously](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously) · sub-agents + +--- + +## ⚠️ 两条被证伪的流言(勿采纳) + +| 流言 | 票数 | 说明 | +|---|---|---| +| "为敏感数据应把 Claude Code **经 MCP 服务器路由**以获更强访问控制" | 0-3 否决 | 无依据 | +| "安全工程团队**独自写了整个 monorepo 50% 的自定义 slash command**" | 1-2 否决 | 数据不可靠 | + +## 证据较薄弱、值得后续单独深挖 + +- **自定义 slash command** 官方编写规范(`.claude/commands/` 结构、参数、与 hooks / 子代理组合)。 +- **MCP** 在新项目中的推荐集成模式与安全边界。 +- **Pipeline(顺序)vs Parallel(并行)** 取舍标准与 `plan→implement→test` 多阶段串接模板。 +- **Hooks 完整事件矩阵**与 TDD 验证循环的最佳组合配置。 + +--- + +## 时效性与可信度声明 + +- 全部高置信结论来自 Anthropic 一手文档与工程博客(code.claude.com/docs、anthropic.com/engineering、官方 PDF),**2025–2026 现行**。 +- 版本相关:Auto memory 依赖 **v2.1.59+**;子代理优先级 / 内置代理行为引用 **v2.1.178 / v2.1.187**。这些版本号与默认行为**可能随版本更新而变,落地前以当前安装版文档为准**。 +- `90.2%` 提升与"数百广告 / 分钟"均为 Anthropic **自报内部评测 / 客户自述**,非独立第三方基准。 + +--- + +## 一手来源清单 + +| URL | 类型 | 覆盖支柱 | +|---|---|---| +| https://code.claude.com/docs/en/best-practices | primary | 工作流 / Memory / Subagent | +| https://code.claude.com/docs/en/memory | primary | Memory | +| https://code.claude.com/docs/en/sub-agents | primary | Subagent | +| https://code.claude.com/docs/en/hooks | primary | Workflow | +| https://www.anthropic.com/engineering/multi-agent-research-system | primary | Subagent 编排 | +| https://www.anthropic.com/research/building-effective-agents | primary | Agent 设计 | +| https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously | primary | Workflow | +| https://www-cdn.anthropic.com/58284b19e702b49db9302d5b6f135ad8871e7658.pdf | primary | 团队用例 | +| https://resources.anthropic.com/hubfs/Claude%20Code%20Advanced%20Patterns... | primary | Subagent/MCP/Scaling | + +--- + +## Related + +- [[Claude Code 多Agent编排 MOC]] —— 总入口 +- [[20260308223000 Claude Code Memory 日常最佳实践]] —— 5 层 memory 实操 +- [[Everything Claude Code 完整指南]]、[[Everything Claude Code 方法论与最佳实践]] +- 原子笔记:[[20260627062503 Explore-Plan-Implement-Commit 四阶段工作流]]、[[20260627062504 自给自足验证循环配合 TDD]]、[[20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖]] diff --git a/6 - Zettelkasten/20260627062503 Explore-Plan-Implement-Commit 四阶段工作流.md b/6 - Zettelkasten/20260627062503 Explore-Plan-Implement-Commit 四阶段工作流.md new file mode 100644 index 0000000..820250d --- /dev/null +++ b/6 - Zettelkasten/20260627062503 Explore-Plan-Implement-Commit 四阶段工作流.md @@ -0,0 +1,32 @@ +--- +created: "2026-06-27 06:25" +type: zettel +tags: [zettel, claude-code, workflow, plan-mode, best-practices] +source: "Anthropic best-practices 官方文档 (2026)" +--- + +# Explore-Plan-Implement-Commit 四阶段工作流 + +用 Claude Code 干活的官方推荐节奏是**先看、再想、后写、最后交**,而不是一上来就让它改代码。把"改动"推迟到上下文充分、计划成形之后,是质量的最大杠杆。 + +四阶段: + +1. **探索 Explore** —— 进 plan mode(只读),让它读代码 / 需求、建立上下文,**不碰任何文件**。 +2. **规划 Plan** —— 产出详细计划;计划可 `Ctrl+G` 在编辑器里直接改,再确认。 +3. **实现 Implement** —— 退出 plan mode,**对照计划写代码 + 测试**。 +4. **提交 Commit** —— 写描述性 commit,开 PR。 + +为什么有效:plan mode 的只读约束把"理解"和"修改"在物理上分开,避免模型在尚未看懂全局时就贸然动手;计划成为一份可人工审校、可当 prompt 传递的中间产物。这与"把计划当 prompt"和"阶段间隔离上下文"是同一思想的不同侧面。 + +--- + +## Related + +- [[20260320100300 Plans as Prompts设计模式]] —— 计划作为可传递的 prompt +- [[20260320100100 上下文腐烂与全新窗口隔离]] —— 为什么阶段间要隔离 +- [[20260627062504 自给自足验证循环配合 TDD]] —— Implement 阶段的自我纠正闭环 +- [[Claude Code 新项目开发最佳实践 (2026 调研)]] + +## Source + +- https://code.claude.com/docs/en/best-practices diff --git a/6 - Zettelkasten/20260627062504 自给自足验证循环配合 TDD.md b/6 - Zettelkasten/20260627062504 自给自足验证循环配合 TDD.md new file mode 100644 index 0000000..25b2eb9 --- /dev/null +++ b/6 - Zettelkasten/20260627062504 自给自足验证循环配合 TDD.md @@ -0,0 +1,33 @@ +--- +created: "2026-06-27 06:25" +type: zettel +tags: [zettel, claude-code, tdd, verification, agentic-loop, best-practices] +source: "Anthropic 团队用例 PDF + best-practices (2026)" +--- + +# 自给自足验证循环配合 TDD + +给 Claude 一个**它自己能跑、能读结果、能据此纠正**的验证手段(build / test / lint),它就能闭环自我迭代而不必每步等人。这个"自给自足循环"(self-sufficient loop)是 agentic 编码可靠性的核心。 + +关键在于**验证信号的客观性**:测试通过 / 失败是二值、确定、模型无法自我安慰的反馈。因此**先写测试再写实现(TDD)时效果尤其好** —— 测试先确立了一个明确的 GREEN 目标,模型的每次改动都有可证伪的对照,而不是"我觉得写完了"。 + +落地要点: +- 在 `CLAUDE.md` 写清"如何运行测试 / lint / build"(否则模型会反复猜错命令)。 +- 用 **Hooks**(`PostToolUse(Edit|Write)`)把验证变成**确定性自动触发**,不依赖模型自觉去跑。 +- 对照 RED→GREEN→REFACTOR:先让测试失败,再让模型实现到通过。 + +本质:把"目标回溯验证"内建进循环,胜过让模型做"正向任务检查"自评。 + +--- + +## Related + +- [[20260320100200 目标回溯验证vs正向任务检查]] —— 为什么客观验证优于自评 +- [[20260319120100 Hook驱动优于提示词驱动]] —— 用 hook 强制验证发生 +- [[20260627062503 Explore-Plan-Implement-Commit 四阶段工作流]] —— Implement 阶段嵌入此循环 +- [[Claude Code 新项目开发最佳实践 (2026 调研)]] + +## Source + +- https://www-cdn.anthropic.com/58284b19e702b49db9302d5b6f135ad8871e7658.pdf +- https://code.claude.com/docs/en/best-practices diff --git a/6 - Zettelkasten/20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖.md b/6 - Zettelkasten/20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖.md new file mode 100644 index 0000000..d1ea64b --- /dev/null +++ b/6 - Zettelkasten/20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖.md @@ -0,0 +1,38 @@ +--- +created: "2026-06-27 06:25" +type: zettel +tags: [zettel, claude-code, memory, claude-md, context] +source: "Anthropic memory 官方文档 (2026)" +--- + +# CLAUDE.md 是目录树拼接加载而非覆盖 + +多个 `CLAUDE.md` 不是"最近的那个赢",而是**沿目录树向上发现、全部拼接(append)**。理解这点才能正确分层放置规则。 + +机制: +- **向上遍历目录树发现**所有 `CLAUDE.md`。 +- **祖先目录的文件启动时全量加载**;**子目录的嵌套文件在读取该目录时才按需加载**。 +- 所有命中的文件**拼接而非覆盖** —— 个人(`~/.claude/CLAUDE.md`)、项目(`./CLAUDE.md`)、本地(`./CLAUDE.local.md`)叠加生效。 +- monorepo 父目录会自动拉取;支持 `@path/import` 引入其它文件。 + +推论(分层放置策略): +- **跨项目偏好** → `~/.claude/`(用户级)。 +- **团队共享的项目规范** → `./CLAUDE.md`(入 git)。 +- **个人临时覆盖** → `./CLAUDE.local.md`(入 `.gitignore`)。 +- **某子模块专属规则** → 放该子目录的 `CLAUDE.md`,只在进入时按需加载,**省主上下文**。 +- 单文件 **< 200 行**;过大拆到 `.claude/rules/` 的 path-scoped rules(带 `paths` frontmatter)。 + +因为是"拼接 + 全量加载祖先",所以越靠上、越大的文件,对每次会话的 token 成本越高 —— 这正是"保持简洁、按目录就近放置"的底层原因。 + +--- + +## Related + +- [[20260308223000 Claude Code Memory 日常最佳实践]] —— 5 层 memory 全景与 Auto memory +- [[20260319120200 MCP数量与上下文窗口的反比关系]] —— 同样是上下文预算权衡 +- [[Claude Code 新项目开发最佳实践 (2026 调研)]] + +## Source + +- https://code.claude.com/docs/en/memory +- https://code.claude.com/docs/en/best-practices