vault: add Claude Code 新项目开发最佳实践 (2026 调研) + 3 zettels + MOC links
This commit is contained in:
Yaojia Wang
@@ -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. 相关基础
|
||||
|
||||
|
||||
182
4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md
Normal file
182
4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md
Normal file
@@ -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/<project>/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 是目录树拼接加载而非覆盖]]
|
||||
@@ -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
|
||||
33
6 - Zettelkasten/20260627062504 自给自足验证循环配合 TDD.md
Normal file
33
6 - Zettelkasten/20260627062504 自给自足验证循环配合 TDD.md
Normal file
@@ -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
|
||||
38
6 - Zettelkasten/20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖.md
Normal file
38
6 - Zettelkasten/20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user