hjdave/everything-claude-code-zh
1
0
Fork 0
mirror of https://github.com/sweetwisdom/everything-claude-code-zh.git synced 2026-03-21 22:10:09 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
392231bfbf9db67f9ec98794b2b8b87829a01604
everything-claude-code-zh/the-longform-guide.md

15 KiB
Raw Blame History

Claude Code 终极长篇指南 (The Longform Guide)

Header: The Longform Guide to Everything Claude Code

前提条件：本指南建立在 Claude Code 终极速查指南 (The Shorthand Guide) 之上。如果你尚未配置技能（Skills）、钩子（Hooks）、子智能体（Subagents）、MCP 和插件（Plugins），请先阅读该指南。

Reference to Shorthand Guide 速查指南 - 请先阅读

在速查指南中，我介绍了基础配置：技能与命令、钩子、子智能体、MCP、插件以及构成高效 Claude Code 工作流骨架的配置模式。那是设置指南和基础架构。

本长篇指南将深入探讨区分“高效会话”与“低效浪费”的关键技术。如果你还没读过速查指南，请先回去完成配置。接下来的内容假定你已经配置好并运行着技能、智能体、钩子和 MCP。

本指南的主题包括：Token 经济学、记忆持久化、验证模式、并行化策略以及构建可复用工作流的复利效应。这些是我在 10 个月以上的日常使用中精炼出的模式，它们决定了你是会在第一个小时内就陷入上下文腐烂（Context Rot），还是能够维持数小时的高效会话。

速查和长篇指南中涵盖的所有内容都可以在 GitHub 上找到：github.com/affaan-m/everything-claude-code

技巧与诀窍 (Tips and Tricks)

某些 MCP 是可替代的，替换后可释放上下文窗口

对于版本控制（GitHub）、数据库（Supabase）、部署（Vercel、Railway）等 MCP —— 绝大多数平台都已经拥有强大的 CLI，MCP 本质上只是对其进行的封装。MCP 虽然是个不错的封装层，但它是以牺牲上下文窗口为代价的。

为了让 CLI 像 MCP 一样工作，但又不实际使用 MCP（从而避免上下文窗口减小），可以考虑将这些功能捆绑到技能（Skills）和命令（Commands）中。剥离 MCP 暴露的易用工具，并将其转化为命令。

示例：不要一直加载 GitHub MCP，而是创建一个 /gh-pr 命令，该命令封装了带有你偏好选项的 gh pr create。不要让 Supabase MCP 消耗上下文，而是创建直接使用 Supabase CLI 的技能。

通过延迟加载（Lazy Loading），上下文窗口的问题基本得到了解决。但 Token 使用量和成本并不能以同样的方式解决。CLI + 技能的方法仍然是一种 Token 优化手段。

重要内容 (IMPORTANT STUFF)

上下文与记忆管理 (Context and Memory Management)

为了在跨会话中共享记忆，最佳方案是使用一个技能或命令来总结和检查进度，然后将其保存到 .claude 文件夹中的 .tmp 文件中，并在会话结束前不断追加内容。第二天，它可以将该文件作为上下文并从你中断的地方继续。为每个会话创建一个新文件，以免旧的上下文污染新的工作。

Session Storage File Tree 会话存储示例 -> https://github.com/affaan-m/everything-claude-code/tree/main/examples/sessions

Claude 会创建一个总结当前状态的文件。查看它，如果需要则要求修改，然后开启新会话。对于新对话，只需提供该文件路径。当你达到上下文限制并需要继续复杂工作时，这特别有用。这些文件应包含：

  • 哪些方法有效（有证据可验证）
  • 尝试过但无效的方法
  • 尚未尝试的方法以及剩余工作

战略性清理上下文：

一旦你设定了计划并清理了上下文（现在 Claude Code 的计划模式（Plan Mode）中是默认选项），你就可以根据计划进行工作。当你积累了大量与执行不再相关的探索性上下文时，这非常有用。对于战略性压缩（Strategic Compacting），请禁用自动压缩（Auto Compact）。手动按逻辑间隔进行压缩，或者创建一个为你执行压缩的技能。

进阶：动态系统提示词注入 (Dynamic System Prompt Injection)

我学到的一个模式：不要只把所有内容放在 CLAUDE.md（用户作用域）或 .claude/rules/（项目作用域）中（这些会在每个会话加载），而是使用 CLI 标志动态注入上下文。

claude --system-prompt "$(cat memory.md)"

这让你能更精确地控制何时加载哪些上下文。系统提示词（System Prompt）内容的优先级高于用户消息，而用户消息的优先级高于工具结果。

实践设置：

# 日常开发
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'

# PR 审查模式
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'

# 研究/探索模式
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

进阶：记忆持久化钩子 (Memory Persistence Hooks)

大多数人不知道这些有助于记忆的钩子：

  • PreCompact 钩子：在上下文压缩发生之前，将重要状态保存到文件。
  • Stop 钩子 (会话结束)：在会话结束时，将学到的内容持久化到文件。
  • SessionStart 钩子：在新会话开始时，自动加载之前的上下文。

我构建了这些钩子，它们位于仓库中的 github.com/affaan-m/everything-claude-code/tree/main/hooks/memory-persistence。

持续学习 / 记忆 (Continuous Learning / Memory)

如果你不得不重复多次相同的提示词，而 Claude 遇到了相同的问题或给出了你听过的回答 —— 那么这些模式必须被追加到技能（Skills）中。

问题： 浪费 Token、浪费上下文、浪费时间。

解决方案： 当 Claude Code 发现非琐碎的事项 —— 调试技术、权宜之计、某些特定于项目的模式 —— 它会将这些知识保存为新技能。下次出现类似问题时，该技能会自动加载。

我构建了一个执行此操作的持续学习技能：github.com/affaan-m/everything-claude-code/tree/main/skills/continuous-learning。

为什么使用 Stop 钩子（而不是 UserPromptSubmit）：

核心设计决策是使用 Stop 钩子 而不是 UserPromptSubmit。UserPromptSubmit 在每条消息上运行，会给每个提示词增加延迟。Stop 在会话结束时运行一次 —— 轻量级，不会在会话期间拖慢你的速度。

Token 优化 (Token Optimization)

首要策略：子智能体架构 (Subagent Architecture)

优化你使用的工具，并设计子智能体架构，以便委派足以完成任务的最便宜模型。

模型选择快速参考：

Model Selection Table 各种常见任务中子智能体的假设设置及其选择理由

任务类型 模型 理由
探索/搜索 Haiku 快速、廉价，足以寻找文件
简单编辑 Haiku 单文件修改，指令明确
多文件实现 Sonnet 编码的最佳平衡点
复杂架构 Opus 需要深度推理
PR 审查 Sonnet 理解上下文，捕捉细微差别
安全分析 Opus 无法承担遗漏漏洞的代价
编写文档 Haiku 结构简单
调试复杂 Bug Opus 需要在大脑中构建整个系统

90% 的编码任务默认使用 Sonnet。当第一次尝试失败、任务涉及 5 个以上文件、需要架构决策或属于安全关键代码时，升级到 Opus。

价格参考：

Claude Model Pricing 来源：https://platform.claude.com/docs/en/about-claude/pricing

工具特定优化：

将 grep 替换为 mgrep —— 与传统的 grep 或 ripgrep 相比，平均可减少约 50% 的 Token：

mgrep Benchmark 在我们进行的 50 项任务基准测试中，在判断质量相似或更好的情况下，mgrep + Claude Code 使用的 Token 比基于 grep 的工作流少约 2 倍。来源：https://github.com/mixedbread-ai/mgrep

模块化代码库的益处：

保持代码库更加模块化，主文件行数保持在几百行而不是几千行，这有助于优化 Token 成本并提高任务一次性成功的概率。

验证循环与评测 (Verification Loops and Evals)

基准测试工作流：

对比在有和没有技能的情况下要求相同任务，并检查输出差异：

派生（Fork）对话，在其中一个没有技能的工作区启动新工作树（Worktree），最后拉取一个 diff，查看记录了什么。

评测模式类型：

  • 基于检查点的评测 (Checkpoint-Based Evals)：设置明确的检查点，根据定义的标准进行验证，在继续之前进行修复。
  • 持续评测 (Continuous Evals)：每隔 N 分钟或在重大更改后运行，全量测试套件 + Lint。

核心指标：

pass@k: k 次尝试中至少有一次成功
        k=1: 70%  k=3: 91%  k=5: 97%

pass^k: 所有 k 次尝试必须全部成功
        k=1: 70%  k=3: 34%  k=5: 17%

当你只需要它工作时，使用 pass@k。当一致性至关重要时，使用 pass^k。

并行化 (PARALLELIZATION)

在多 Claude 终端设置中派生（Fork）对话时，请确保派生出的动作与原始对话的范围界定明确。在代码更改方面，尽量减少重叠。

我偏好的模式：

主聊天用于代码更改，派生聊天用于关于代码库及其当前状态的问题，或对外部服务的研究。

关于终端数量：

Boris on Parallel Terminals Boris (Anthropic) 谈论运行多个 Claude 实例

Boris 对并行化有一些建议。他建议诸如在本地运行 5 个 Claude 实例并在上游运行 5 个。我不建议随意设置终端数量。增加终端应该是出于真正的必要。

你的目标应该是：如何以最小可行数量的并行化完成尽可能多的工作。

用于并行实例的 Git 工作树 (Worktrees)：

# 为并行工作创建工作树
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-refactor refactor-branch

# 每个工作树获得自己的 Claude 实例
cd ../project-feature-a && claude

如果你开始扩展实例，并且有多个 Claude 实例在相互重叠的代码上工作，那么必须使用 git 工作树，并为每个实例制定非常明确的计划。使用 /rename <name here> 为你所有的聊天命名。

Two Terminal Setup 启动设置：左侧终端用于编码，右侧终端用于提问 —— 使用 /rename 和 /fork

级联法 (The Cascade Method)：

运行多个 Claude Code 实例时，采用“级联”模式进行组织：

  • 在右侧的新标签页中开启新任务
  • 从左向右扫视，从旧到新
  • 同时关注最多 3-4 个任务

基础工作 (GROUNDWORK)

双实例启动模式 (The Two-Instance Kickoff Pattern)：

为了管理我自己的工作流，我喜欢在一个空仓库中启动 2 个开启的 Claude 实例。

实例 1：脚手架智能体 (Scaffolding Agent)

  • 搭建脚手架和基础工作
  • 创建项目结构
  • 设置配置（CLAUDE.md、rules、agents）

实例 2：深度研究智能体 (Deep Research Agent)

  • 连接你所有的服务、进行网页搜索
  • 创建详细的 PRD
  • 创建架构 Mermaid 图表
  • 汇总带有实际文档片段的参考资料

llms.txt 模式：

如果可用，你可以在许多文档参考资料中找到 llms.txt，只需在到达其文档页面后执行 /llms.txt 即可。这会为你提供一个干净的、针对 LLM 优化的文档版本。

哲学：构建可复用的模式

来自 @omarsar0：“早期，我花时间构建可复用的工作流/模式。构建过程很乏味，但随着模型和智能体控制能力的提高，这产生了巨大的复利效应。”

值得投入的内容：

  • 子智能体 (Subagents)
  • 技能 (Skills)
  • 命令 (Commands)
  • 规划模式 (Planning patterns)
  • MCP 工具
  • 上下文工程模式 (Context engineering patterns)

智能体与子智能体的最佳实践

子智能体上下文问题：

子智能体存在的意义在于通过返回总结（Summaries）而不是倾倒（Dumping）所有内容来节省上下文。但编排者（Orchestrator）拥有子智能体所缺乏的语义上下文。子智能体只知道字面上的查询，不知道请求背后的“目的”。

迭代检索模式 (Iterative Retrieval Pattern)：

  1. 编排者评估子智能体的每一次返回
  2. 在接受之前提出追问
  3. 子智能体回到源头，获取答案，返回
  4. 循环直到满足要求（最多 3 个周期）

关键： 传递客观上下文，而不只是查询。

带有顺序阶段的编排者：

阶段 1: 研究 (使用 Explore 智能体) → research-summary.md
阶段 2: 规划 (使用 Planner 智能体) → plan.md
阶段 3: 实现 (使用 TDD-Guide 智能体) → 代码更改
阶段 4: 审查 (使用 Code-Reviewer 智能体) → review-comments.md
阶段 5: 验证 (必要时使用 Build-Error-Resolver) → 完成或返回循环

核心规则：

  1. 每个智能体接收一个明确的输入，并产生一个明确的输出
  2. 输出成为下一阶段的输入
  3. 绝不跳过阶段
  4. 在智能体切换之间使用 /clear
  5. 将中间输出存储在文件中

有趣的内容 / 非关键但有趣的技巧

自定义状态栏 (Custom Status Line)

你可以使用 /statusline 进行设置 —— 随后 Claude 会说你目前还没有设置，但可以为你配置并询问你想要在其中加入什么。

另请参阅：https://github.com/sirmalloc/ccstatusline

语音转录

通过语音与 Claude Code 对话。对许多人来说，这比打字更快。

  • Mac 上的 superwhisper, MacWhisper
  • 即使有转录错误，Claude 也能理解意图

终端别名 (Terminal Aliases)

alias c='claude'
alias gb='github'
alias co='code'
alias q='cd ~/Desktop/projects'

里程碑

25k+ GitHub Stars 一周内获得 25,000+ GitHub Stars

资源 (Resources)

智能体编排：

自进化记忆：

系统提示词参考：

官方：

  • Anthropic Academy: anthropic.skilljar.com

参考资料 (References)

两个指南中涵盖的所有内容都可以在 GitHub 上的 everything-claude-code 找到

Reference in New Issue View Git Blame Copy Permalink