---
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]]。
> 🛠 想要手把手、带真实命令和完整代码的步骤教程 → [[Claude Code 新项目实操教程 (贯穿示例)]]。

---

## 一图速览:四大支柱

```
启动工作流   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 是目录树拼接加载而非覆盖]]