knowledge-base/4 - Resources/Claude-Code/Claude Code 新项目开发最佳实践 (2026 调研).md

created, type, tags, source

created	type	tags	source
2026-06-27	resource	claude-code best-practices new-project memory subagent workflow hooks research verified	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 · Anthropic 团队用例 PDF · Builder.io

---

支柱二: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 文档 · best-practices · Advanced Patterns 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 · 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 · enabling-claude-code-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 是目录树拼接加载而非覆盖