\documentclass[a4paper]{article}

% Basic packages
\usepackage[fontset=fandol]{ctex}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage[margin=2.5cm]{geometry}
\usepackage[most]{tcolorbox}
\usepackage{etoolbox}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{float}
\usepackage{tikz}
\usepackage{enumitem}

% Highlight boxes
\newtcolorbox{knowledgebox}[1]{
    enhanced, colback=blue!5!white, colframe=blue!75!black, colbacktitle=blue!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, attach boxed title to top left={yshift=-2mm, xshift=2mm},
    boxrule=1pt, sharp corners
}

\newtcolorbox{importantbox}[1]{
    enhanced, colback=yellow!10!white, colframe=yellow!80!black, colbacktitle=yellow!80!black,
    coltitle=black, fonttitle=\bfseries, title=#1, sharp corners
}

\newtcolorbox{warningbox}[1]{
    enhanced, colback=red!5!white, colframe=red!75!black, colbacktitle=red!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, sharp corners
}

% Listings — default to bash for this article
\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    stringstyle=\color{red!60!black},
    commentstyle=\color{green!60!black},
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray},
    captionpos=b,
    extendedchars=false
}

% Front-page metadata
\newcommand{\notetitle}{Claude Code 最佳实践：从"能用"到"真的好用"}
\newcommand{\noteauthors}{基于公开课程资料整理}
\newcommand{\notedate}{2026 年 3 月 23 日}
\newcommand{\articleauthor}{Mr Panda (PandaTalk8)}
\newcommand{\articlepublishdate}{2026 年 3 月 23 日}
\newcommand{\articleurl}{https://x.com/PandaTalk8/status/2035975664730575325}


% Footer with repo info
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyfoot[C]{\thepage}
\fancyfoot[R]{\footnotesize\color{gray}\href{\repourl}{AI Course Notes}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

\begin{document}

\begin{titlepage}
\centering
{\Large 文章笔记\par}
\vspace{1.2cm}
{\huge\bfseries \notetitle\par}
\vspace{0.8cm}
{\large \noteauthors\par}
\vspace{0.3cm}
{\large \notedate\par}
\vfill
\begin{tcolorbox}[width=0.9\textwidth, colback=black!2!white, colframe=black!60, sharp corners]
\textbf{原文作者}：\articleauthor\par
\textbf{发布日期}：\articlepublishdate\par
\textbf{来源平台}：X (Twitter) 长文\par
\textbf{原文链接}：\href{\articleurl}{\nolinkurl{\articleurl}}\par
\textbf{项目主页}：\href{\repourl}{\nolinkurl{\repourl}}\par
\end{tcolorbox}
\end{titlepage}

\tableofcontents
\newpage

%% ====================================================================
%%  正文
%% ====================================================================

\section{CLAUDE.md：一切的起点}

\begin{knowledgebox}{什么是 CLAUDE.md？}
\texttt{CLAUDE.md} 是 Claude Code 在每次对话开始时\textbf{自动读取}的指令文件，相当于给 AI 助手写的 onboarding 文档——你希望它知道什么，就写什么。不写或随便写几行的后果是：每次对话都要从头解释项目结构、编码规范和技术栈。
\end{knowledgebox}

\subsection{好的 CLAUDE.md 三原则}

\begin{importantbox}{CLAUDE.md 写作原则}
\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{写代码里读不出来的东西。}项目的"为什么"比"是什么"更重要。不需要解释 React 怎么用，但要说明"选 Tailwind 是因为团队统一规范"。
  \item \textbf{控制在 200 行以内。}官方文档明确提到，CLAUDE.md 太长会导致 Claude 忽略规则。用 Markdown 标题和列表保持可扫描性。
  \item \textbf{不放频繁变化的内容。}详细的 API 文档、逐文件描述不适合放在里面，放链接就好。
\end{enumerate}
\end{importantbox}

\subsection{四级层级与规则拆分}

Claude Code 支持四级 \texttt{CLAUDE.md}，按优先级从高到低：

\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{企业级}：由组织管理员统一设定
  \item \textbf{用户全局}：\texttt{\textasciitilde/.claude/CLAUDE.md}
  \item \textbf{项目级}：项目根目录下的 \texttt{CLAUDE.md}
  \item \textbf{目录级}：子目录中的 \texttt{CLAUDE.md}
\end{enumerate}

当项目变大后，可以把规则拆到 \texttt{.claude/rules/} 目录下，并用 YAML frontmatter 将规则限定到特定文件模式，这样该规则仅在 Claude 访问匹配的文件时才会加载，节省上下文空间。

\subsection{本章小结}

\texttt{CLAUDE.md} 是 Claude Code 最被低估也最值得投入的功能。写好一次，每次对话都受益。核心是：写决策理由，不写代码细节；保持精简；善用层级和规则拆分。

%% ====================================================================
\section{提示词工程：指令的质量决定产出的质量}

\subsection{好指令的三要素}

\begin{importantbox}{目标 + 约束 + 上下文}
\begin{itemize}[leftmargin=1.5em]
  \item \textbf{目标}：明确要做什么（"在表格上方加搜索框"）
  \item \textbf{约束}：限定实现方式（"走后端 API，debounce 300ms"）
  \item \textbf{上下文}：引用具体文件、样式规范、现有组件
\end{itemize}
差的指令："给用户列表加个搜索功能"。好的指令减少了歧义，Claude 不需要猜你要前端还是后端搜索。
\end{importantbox}

\subsection{四个官方推荐技巧}

\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{用 \texttt{@} 引用具体文件}——\texttt{@src/auth/login.ts} 比"那个认证相关的代码"精确得多，还可以指定行号范围 \texttt{@src/auth/login.ts\#5-30}。
  \item \textbf{贴截图和图片}——调试 UI 问题时，\texttt{Ctrl+V} 粘贴"现在长这样"和"我想要这样"的截图，比文字描述有效十倍。
  \item \textbf{给验证标准}——给 Claude 一个可以自我验证的标准（测试用例、截图、预期输出），它就能自己检查工作质量，减少来回修改。
  \item \textbf{明确"不要做"的事}——Claude 有时会过度热心，你让它修 bug，它顺手把周围代码也重构了。明确说"只改这个函数，不要动其他代码"。
\end{enumerate}

\begin{knowledgebox}{模糊指令也有用武之地}
探索性任务用模糊指令反而更好，比如"这个文件有什么可以改进的地方？"、"帮我理解一下这个模块的架构"。但到了实现阶段，要切回精确模式。
\end{knowledgebox}

\subsection{本章小结}

好的提示词 = 目标 + 约束 + 上下文 + 验证标准。探索时用模糊指令，实现时用精确指令。

%% ====================================================================
\section{Plan Mode：先想清楚再动手}

\begin{knowledgebox}{Plan Mode 是什么？}
在 Plan Mode 下，Claude Code 只能读取文件和搜索代码，不能做任何修改。它会探索代码库、分析需求，然后给出一个详细的实现计划。进入方式包括：在提示词中说明"先给我一个计划"、使用 \texttt{Shift+Tab} 切换模式，或在 \texttt{CLAUDE.md} 中配置默认行为。
\end{knowledgebox}

\subsection{Plan Mode 的正确工作流}

\begin{importantbox}{官方推荐四步流程：探索→规划→实现→验证}
\begin{enumerate}[leftmargin=1.5em]
  \item 让 Claude 生成初始计划
  \item 按 \texttt{Ctrl+G} 在编辑器中打开并编辑计划——删掉不同意的部分，补充自己的想法
  \item 切回正常模式（\texttt{Shift+Tab}），让 Claude 按修改后的计划执行
  \item 执行完毕后验证结果（跑测试、检查输出）
\end{enumerate}
\textbf{关键认知}：改一个计划只需要一句话，改已经写好的代码要花十倍的时间。
\end{importantbox}

\subsection{何时不需要 Plan Mode}

判断标准很简单：如果任务的实现方式只有一种（改变量名、修 typo、加一行日志），直接做。如果有多种选择，先规划。

\subsection{本章小结}

Plan Mode 是复杂任务的必经之路。先规划再动手，可以大幅减少返工。核心操作是 \texttt{Ctrl+G} 编辑计划。

%% ====================================================================
\section{上下文管理：最容易被忽视的关键}

Claude Code 的上下文窗口最大可达 1M token，但它不是无限的，且上下文质量直接决定输出质量。

\subsection{上下文里都装了什么}

\begin{itemize}[leftmargin=1.5em]
  \item 对话历史
  \item Claude 读取的所有文件内容
  \item 命令执行的输出
  \item \texttt{CLAUDE.md} 文件（每次都加载）
  \item Memory 文件（前 200 行）
  \item 加载的 Skill 和 MCP 工具定义
\end{itemize}

\subsection{五个实用策略}

\begin{importantbox}{上下文管理五板斧}
\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{\texttt{/clear}}——一件事做完就清。不要在同一个对话里又修 bug 又加功能又重构。
  \item \textbf{\texttt{/compact}}——手动压缩上下文。更好的用法是给压缩加焦点：\texttt{/compact 专注于 API 改动和测试结果}。
  \item \textbf{\texttt{/context}}——查看上下文使用情况，发现哪些 MCP server 占了大量空间。
  \item \textbf{用子 Agent 隔离噪声}——跑测试、分析日志等产生大量输出的操作交给子 Agent，主对话保持干净。
  \item \textbf{在 CLAUDE.md 里写压缩保留指令}——告诉 Claude 压缩时必须保留什么关键信息。
\end{enumerate}
\end{importantbox}

\begin{warningbox}{Memory 的适用边界}
Memory 适合存：偏好、项目约定、历史决策。\\
Memory 不适合存：代码细节、Git 历史、临时状态——这些从代码和 Git 里获取更准确。\\
\texttt{CLAUDE.md} 是团队共享的规范；Memory 是个人的记忆。
\end{warningbox}

\subsection{本章小结}

上下文是稀缺资源。\texttt{/clear} 保持对话聚焦，\texttt{/compact} 延长对话寿命，子 Agent 隔离噪声输出。

%% ====================================================================
\section{子 Agent：Claude Code 的分身术}

\begin{knowledgebox}{子 Agent 机制}
子 Agent 是独立的 AI 进程，每个有自己的上下文窗口，不会污染主对话。内置三种类型：
\begin{itemize}[leftmargin=1.5em]
  \item \textbf{Explore}：只读，快速搜索代码库，适合找文件、找定义
  \item \textbf{Plan}：只读，研究分析，用于 Plan Mode 下的代码分析
  \item \textbf{General}：完整能力，适合复杂的多步骤任务
\end{itemize}
\end{knowledgebox}

\subsection{核心价值：隔离上下文}

当你让 Claude 跑测试、分析日志、搜索大量文件时，海量输出会塞满上下文窗口。用子 Agent 来做这些事，输出留在子 Agent 的上下文里，只有摘要返回给你。

按 \texttt{Ctrl+B} 可以把子 Agent 放到后台运行——适合跑测试套件、大范围代码搜索、不紧急的代码审查。

\subsection{自定义子 Agent}

在 \texttt{.claude/agents/} 目录下创建自定义 Agent 的 Markdown 文件，然后在对话中用 \texttt{@"agent-name (agent)"} 调用。可以为特定场景（如 code review）定制专属 Agent。

\subsection{本章小结}

子 Agent 的核心价值是上下文隔离。把高噪声操作（测试、日志分析、大范围搜索）交给子 Agent，保持主对话干净高效。

%% ====================================================================
\section{权限与安全：在效率和安全之间找平衡}

\subsection{五种权限模式}

Claude Code 提供五种权限模式，用 \texttt{Shift+Tab} 在对话中循环切换，从全自动到完全手动确认，覆盖不同的安全需求场景。

\subsection{权限规则配置}

在 \texttt{.claude/settings.json} 里精细控制每种工具的权限。

\begin{importantbox}{权限优先级：deny > ask > allow}
可以大胆地 allow 常用命令，同时用 deny 保护敏感文件。比如 \texttt{.env} 文件无论如何都不应该被编辑。
\end{importantbox}

设置文件也有多级层次：团队共享规则放 \texttt{.claude/settings.json}，个人偏好放 \texttt{\textasciitilde/.claude/settings.json}，敏感配置放 \texttt{.claude/settings.local.json}（加到 \texttt{.gitignore}）。

\subsection{Hooks：让规则变成铁律}

\begin{warningbox}{CLAUDE.md 是"建议"，Hooks 是"铁律"}
\texttt{CLAUDE.md} 里的指令 Claude 大部分时候会遵守，但偶尔会忘。Hooks 是在特定生命周期事件上自动触发的 shell 命令，无论如何都会执行。配置在 \texttt{settings.json} 里。
\end{warningbox}

Hooks 的关键事件类型包括编辑文件前/后、执行命令前/后、上下文压缩后等。Hook 命令返回 \texttt{exit code 0} 表示允许，\texttt{exit code 2} 表示阻止，因此可以写任意复杂的判断逻辑。

实用场景举例：

\begin{itemize}[leftmargin=1.5em]
  \item \textbf{自动格式化}：每次编辑后运行 Prettier
  \item \textbf{保护关键文件}：阻止修改生产配置
  \item \textbf{压缩后重注入}：对话被压缩后自动重新注入关键指令，解决"长对话压缩丢信息"的痛点
\end{itemize}

Hook 有四种类型：\texttt{command}（shell 命令）、\texttt{http}（POST 请求）、\texttt{prompt}（单次 LLM 判断）、\texttt{agent}（启动子 Agent 验证）。

\subsection{本章小结}

权限管理的核心是分层：deny 保护底线，allow 提升效率。Hooks 把 CLAUDE.md 中的"建议"变成可执行的"铁律"，是保障代码安全的最后一道防线。

%% ====================================================================
\section{Git 工作流与 Worktree}

\subsection{Worktree：隔离的工作空间}

\begin{knowledgebox}{Git Worktree 的价值}
Worktree 会在 \texttt{.claude/worktrees/} 下创建一个独立的 Git 分支副本。Claude 在里面怎么折腾都不影响主分支。退出时：没有改动则自动清理，有改动则提示保留或删除。对探索性任务特别有用——不确定某个重构方案能不能行？开个 worktree 试试，不行就扔掉，零风险。
\end{knowledgebox}

\subsection{Git 铁律}

\begin{warningbox}{四条不可违反的 Git 规则}
\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{永远不要让 Claude Code 自动 push}——它可以 commit，但 push 必须由你确认。一旦 push 到远端，回退成本就大了。
  \item \textbf{频繁 commit}——做完一个小功能就 commit。用 \texttt{/rewind} 回退的前提是有 commit 记录。
  \item \textbf{警惕破坏性操作}——\texttt{git reset --hard}、\texttt{git push --force}、\texttt{rm -rf} 没有 undo，可以在权限规则里直接 deny。
  \item \textbf{从 PR 恢复上下文}——自动加载 PR 的改动和讨论作为上下文，适合 code review 或继续别人的工作。
\end{enumerate}
\end{warningbox}

\subsection{本章小结}

Worktree 提供了零风险的实验环境。Git 操作的核心原则是：频繁 commit、禁止自动 push、deny 破坏性命令。

%% ====================================================================
\section{高级功能：Extended Thinking 与 MCP}

\subsection{Extended Thinking}

对于复杂问题，可以开启 Extended Thinking 模式让 Claude 在回答前花更多时间推理。

\begin{importantbox}{何时使用 Extended Thinking}
\textbf{适合}：复杂架构决策、棘手的多因素 debug、多步骤重构方案、多方案利弊权衡。\\
\textbf{不需要}：简单代码修改、格式化/重命名、已经很明确的 bug 修复。\\
\textbf{小技巧}：在提示词里写 \texttt{ultrathink} 可以强制触发最高推理深度。
\end{importantbox}

\subsection{MCP Server}

MCP（Model Context Protocol）让 Claude Code 能和外部工具通信——GitHub、数据库、Slack、Notion 等。配置在项目根目录的 \texttt{.mcp.json} 里。

\begin{warningbox}{MCP 的上下文开销}
每个 MCP server 会额外消耗 100--500+ token 的工具定义。用 \texttt{/mcp} 命令查看每个 server 的开销，禁用不用的 server。\textbf{不要贪多}——常用的 2--3 个就够了，装太多反而影响代码分析质量。
\end{warningbox}

\subsection{IDE 集成}

Claude Code 不仅可以在终端使用，还有 VS Code 扩展和 JetBrains 插件：

\begin{itemize}[leftmargin=1.5em]
  \item \textbf{VS Code}：并排 diff 视图、\texttt{Option+K} 快速引用文件、多标签对话、\texttt{Cmd+Shift+Esc} 新建对话
  \item \textbf{JetBrains}：IntelliJ/PyCharm/WebStorm 等均支持，在 Plugins 市场搜索安装
\end{itemize}

\subsection{本章小结}

Extended Thinking 适合复杂推理任务。MCP 扩展了 Claude 的能力边界，但要注意上下文开销。IDE 集成让工作流更顺滑。

%% ====================================================================
\section{代码审查与常见陷阱}

\subsection{三个常见问题}

\begin{warningbox}{Claude Code 代码的典型问题}
\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{过度工程}——你要一个简单工具函数，它给你搞出完整的抽象层（泛型+接口+工厂模式）。\textbf{解法}：在 CLAUDE.md 写"优先用简单方案"，或在指令里明确"不需要抽象"。
  \item \textbf{幻觉 API}——使用不存在的 API 或过时的语法，尤其是小众库的新版本。\textbf{解法}：跑测试，指令里包含验证标准。
  \item \textbf{改动范围膨胀}——你让它改一个函数，它把整个文件都重构了。\textbf{解法}：明确说"只改 X，不要动其他代码"，或用 \texttt{/freeze} 限制编辑范围。
\end{enumerate}
\end{warningbox}

\subsection{Writer/Reviewer 模式}

官方推荐的高级模式：用两个独立会话分别扮演"写代码"和"审查代码"的角色。两个会话有独立上下文，Reviewer 不受 Writer 思路影响，能发现 Writer 的盲点。

\subsection{不要用 Claude Code 做的事}

\begin{warningbox}{四条红线}
\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{不要让它做你完全不了解的事}——你无法审查你不懂的东西。
  \item \textbf{不要在没有版本控制的环境下用}——没有 Git 就没有回退能力，等于裸奔。
  \item \textbf{不要一口气扔一个巨大的任务}——拆成小步骤，每步确认后再做下一步。
  \item \textbf{不要指望一次就完美}——迭代是正常的，用 \texttt{/rewind} 回退，用精确反馈描述"哪里不对"。
\end{enumerate}
\end{warningbox}

\subsection{本章小结}

信任但要验证。用 CLAUDE.md 约束过度工程，用测试拦截幻觉 API，用明确指令控制改动范围。Writer/Reviewer 双会话模式适合重要功能开发。

%% ====================================================================
\section{快捷键与命令速查}

\begin{table}[H]
\centering
\caption{最常用的快捷键}
\begin{tabular}{ll}
\toprule
\textbf{快捷键} & \textbf{功能} \\
\midrule
\texttt{Shift+Tab} & 切换权限模式 / 切换 Plan Mode \\
\texttt{Ctrl+G} & 在编辑器中打开并编辑计划 \\
\texttt{Ctrl+B} & 将子 Agent 放到后台运行 \\
\texttt{Ctrl+V} & 粘贴图片到对话 \\
\texttt{Option+K / Alt+K} & (VS Code) 快速插入 @文件引用 \\
\texttt{Cmd+Shift+Esc} & (VS Code) 打开新对话标签 \\
\bottomrule
\end{tabular}
\end{table}

\begin{table}[H]
\centering
\caption{最常用的斜杠命令}
\begin{tabular}{ll}
\toprule
\textbf{命令} & \textbf{功能} \\
\midrule
\texttt{/clear} & 清空上下文，保留 CLAUDE.md \\
\texttt{/compact} & 压缩上下文，可加焦点参数 \\
\texttt{/context} & 查看上下文使用情况 \\
\texttt{/memory} & 查看和管理 Memory \\
\texttt{/mcp} & 查看 MCP server 及其开销 \\
\texttt{/init} & 自动分析代码库生成 CLAUDE.md 初稿 \\
\texttt{/rewind} & 回退到任意 checkpoint \\
\texttt{/freeze} & 限制编辑范围到指定目录 \\
\bottomrule
\end{tabular}
\end{table}

%% ====================================================================
\section{总结与延伸}

原文作者 Mr Panda 在大半年的 Claude Code 实战中提炼出一套清晰的使用哲学：

\begin{importantbox}{Claude Code 核心使用哲学}
它是一个极其能干的协作者，但不是自动驾驶。方向盘始终在你手里。工具的价值，永远取决于使用它的人。
\end{importantbox}

按重要性排序的六条建议：

\begin{enumerate}[leftmargin=1.5em]
  \item \textbf{写好 CLAUDE.md}——一次投入，每次对话都受益
  \item \textbf{给精确的指令}——目标 + 约束 + 验证标准
  \item \textbf{用 Plan Mode}——复杂任务先规划再动手
  \item \textbf{管理上下文}——\texttt{/clear}、\texttt{/compact}、子 Agent
  \item \textbf{控制权限}——deny 危险操作，allow 常用命令
  \item \textbf{频繁 commit}——保留回退能力
\end{enumerate}

\subsection{拓展阅读}

\begin{itemize}[leftmargin=1.5em]
  \item Claude Code 官方文档：\url{https://docs.anthropic.com/en/docs/claude-code}
  \item Model Context Protocol 规范：\url{https://modelcontextprotocol.io}
  \item 原文链接：\url{https://x.com/PandaTalk8/status/2035975664730575325}
\end{itemize}

\end{document}
