vault: add Claude Code 新项目开发最佳实践 (2026 调研) + 3 zettels + MOC links

2026-06-27 06:29:31 +02:00
parent 99acb0c288
commit 791c1066f3
5 changed files with 290 additions and 1 deletions
--- a/Resources/Claude-Code/Claude
+++ b/Resources/Claude-Code/Claude
@@ -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. 相关基础

--- a/Resources/Claude-Code/Claude
+++ b/Resources/Claude-Code/Claude
@@ -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 是目录树拼接加载而非覆盖]]