Claude Code提示技巧：用上下文工程打造可落地的AI开发Agent-平芜编程栈

任何一个长期使用 Claude Code 的人都会经历一个阶段：安装很顺利，跑通 demo 很顺利，但真正丢一个“正经需求”进去时，结果却常常离谱——改错文件、漏掉约束、把不该动的代码重写一遍。问题很可能不在模型能力，而在提示方式。

Claude Code 不是 ChatGPT 那种“一次问答”工具，而是一个长期驻留在终端里、能反复读写文件、执行命令的 Agent。它的工作方式决定了：决定输出质量的不是单条提示词的措辞，而是你为它准备的上下文体系——项目记忆、任务边界、验收标准、权限范围。这套东西，恰恰是 Anthropic 工程师在日常使用中最看重、也最容易被新手忽略的部分。

这篇文章会拆解 Claude Code 的提示技巧：从 CLAUDE.md 项目记忆、Plan 模式、上下文压缩，到 Skills 与 hooks 的工程化配置，并给出一套可以直接复制的示例。读完你至少能解决一个问题：让 Claude Code 在你的真实项目里，少犯低级错误，多产出可落地的代码。

1. 为什么提示技巧在 Claude Code 里成了新议题

很多人把“提示技巧”理解成“怎么把一句话说得更清楚”，这放在聊天模型上基本成立，放在 Agent 上就差得很远。

在 Claude Code 这类工具出现之前，我们与大模型的交互是一次性的：你提一个问题，它给一个回答。你说得不清楚，它下次可能就答不准，但不会产生破坏性后果。Agent 不一样，它可以读取你的源码、修改文件、执行测试、运行命令，而且一旦方向错误，它会带着错误的方向持续执行下去，直到你喊停。这是两种完全不同的风险模型。

因此，Agent 场景下的提示工程，核心目标是另一件事：把模型放进一个“信息完整、边界明确、可验证”的工作环境里。它不再是写一句漂亮的话，而是设计上下文结构，管理模型能看到什么、能做什么、按什么标准交付。这也是为什么 Anthropic 工程师会反复强调 CLAUDE.md、权限配置、Plan 模式这些“看似和提示词无关”的东西——因为它们共同决定了模型每次决策时的信息质量和行动范围。

另一个容易被忽略的事实是：同一个模型，在不同上下文结构下产出质量差异极大。把项目约定写在每次对话里，和写在 CLAUDE.md 中让模型自动加载，效果完全不同。前者会消耗大量上下文 token，而且每次新会话都要重新交代一遍；后者则让模型在启动时就自带完整背景，把宝贵的上下文预算留给真正的任务处理。

所以这篇文章讲的提示技巧，本质上是“面向 Agent 的上下文工程方法”。下面先补一个概念基础。

2. Claude Code 核心概念：先搞清楚 Agent 的工作方式

2.1 什么是 Claude Code

Claude Code 是 Anthropic 推出的终端 Agent 工具，可以把它理解为“住在你项目目录里的 AI 开发协作者”。它以命令行方式运行，通过自然语言接收任务，然后自主地读取文件、搜索代码、调用工具、执行命令，最终给出改动或建议。

与直接调用 Claude API 或打开网页端聊天相比，Claude Code 最本质的差异是具备工具调用能力。它不是一个“回答你问题”的模型，而是一个“替你做事情”的执行者。这意味着它可以根据需要动态决定下一步动作：先读哪些文件、运行什么命令、修改哪段代码。

2.2 一次会话的工作链路

一次典型的 Claude Code 会话是这样工作的：

用户进入项目目录，启动 Claude Code。
模型自动加载项目级的 CLAUDE.md、用户目录的全局 CLAUDE.md，以及会话开始时用户输入的指令。
模型根据当前目标选择工具：读文件、搜索代码、运行测试、执行命令。
每完成一步，模型会把结果带回上下文，再决定下一步。
会话结束，所有工作成果体现在文件系统和 git diff 里。

这条链路里，上下文是逐步累积的。会话越长，上下文越拥挤，早期的信息会被压缩甚至遗忘。这就是为什么“上下文管理”是 Agent 提示技巧中的重要一环，而不是一个可有可无的优化项。

2.3 CLAUDE.md、Skills、hooks、MCP 四个概念

这四个机制经常被混为一谈，放一起对比会清楚很多：

机制	作用	一句话理解
CLAUDE.md	项目记忆文件，启动时自动加载	告诉模型“这个项目长什么样、有什么约定”
Skills	可复用的指令包，按需加载	告诉模型“遇到这类任务时，按这套流程做”
hooks	工具调用前后触发的命令	告诉模型“每次改动后，自动跑一遍 lint”
MCP	连接外部数据与服务的协议	让模型能读数据库、查文档、调企业系统

新手最容易混淆的是 CLAUDE.md 和 Skills。可以这样理解：CLAUDE.md 是“静态背景”，相当于给模型一本入职手册；Skills 是“动态技能”，相当于给模型一套操作 SOP。手册在入职时读完，SOP 在遇到对应任务时才翻出来。

2.4 Claude Code 与传统 IDE 插件、Codex 的区别

社区里经常有人问：Claude Code 和 Codex 到底怎么选。从现有材料来看，两者形态相似，都属于终端 Agent 工具，真正的差别在生态侧重点：Claude Code 围绕 Anthropic 模型体系，强调项目记忆、hooks 自动化、Skills 复用体系；Codex 则更贴近 OpenAI 的模型与代码生成生态。选择上，如果你已经重度使用 Claude 模型，且需要模型长期参与一个项目的迭代，Claude Code 的项目记忆机制会是明显加分项；如果团队整体技术栈和模型生态都绑定在 OpenAI 一侧，Codex 可能更顺滑。具体选型还需要在你们的真实代码库上跑一周验证，不要只凭宣传做决定。

3. 环境准备与安装

3.1 前置条件

安装 Claude Code 的常规要求是：

Node.js 环境，建议使用较新的 LTS 版本。
npm 包管理器，或你熟悉的 Node 包管理器。
一个可以正常访问 Anthropic 服务的网络环境。
Anthropic 账号，并按官方流程完成登录授权。

关于 Node.js 的具体版本，不同时期的 Claude Code 对版本要求会有差异，具体以官方说明为准，本文不写死版本号。如果你本机已经装了其他基于 Node.js 的工具，直接复用环境即可，一般不需要额外配置。

3.2 安装步骤

主流安装方式是使用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成后，先确认版本能正常打印：

claude --version

然后进入项目目录启动会话：

cd /path/to/your/project claude

首次启动会要求登录授权。按终端里的提示完成浏览器授权，登录成功后即可开始对话。如果你的终端环境比较特殊，无法自动打开浏览器，也可以复制终端输出中的授权链接到浏览器手动完成。

3.3 在 VS Code 中使用

Claude Code 提供了桌面客户端，也有对应的编辑器集成方式。一个常见做法是：

安装官方桌面客户端，或 VS Code 中的 Claude Code 扩展。
在 VS Code 中打开项目文件夹。
启动 Claude Code 终端面板，或通过扩展面板直接开启会话。

如果你在 Windows PowerShell 环境下遇到安装报错，通常要先看三件事：npm 版本是否过旧、当前用户是否对全局 node_modules 有写权限、PowerShell 执行策略是否限制了脚本运行。把完整报错信息贴到搜索引擎，往往能直接找到对应的解决步骤，而不是盲目重装。

3.4 关于接入其他模型

社区存在把 Claude Code 接入本地模型（如通过 Ollama）或第三方模型服务的尝试，常见做法是借助 cc-switch 之类的工具或自定义网关。这种方案可行，但有几个现实问题需要提前知道。

首先是模型路由。第三方网关需要自行维护模型路由标识，如果配置不对，会直接报类似“doesn't look like an anthropic model: expected a gateway model route reference”的错误。其次是能力差异，非官方模型的工具调用和指令遵循能力，可能与 Claude 模型有差距，同一个提示词在官方模型和转发模型上的表现往往不一致。最后是稳定性，网关故障、接口限流、字段适配都会成为新的排查点。

这意味着在你把这类方案引入日常开发前，务必在测试项目上验证一遍核心任务链路：读文件、改代码、跑测试、输出 git diff。不要拿生产环境当试验场。本文后续的提示技巧，都以官方模型和官方接口为前提。若使用网关转发，需要自行补充适配。

3.5 基础配置项

Claude Code 在项目目录下会读取.claude目录中的配置文件，常用的是settings.json。它控制权限、hooks 等行为，本身也是提示体系的一环。后续示例会给出一个可直接复制的版本。

4. Anthropic 工程师风格的提示技巧

这一节是文章核心。我把它拆成六个可执行的方法，每个都会说明“为什么有效”和“怎么落地”。

4.1 用 CLAUDE.md 做项目长期记忆

问题：模型没有持久记忆。你上周告诉它的项目约定，下周一开会话它就忘了。

方案：把项目的关键信息固化到 CLAUDE.md 文件中。Claude Code 在启动会话时会按层级自动加载它，相当于模型的“项目入职手册”。实际项目中，我建议 CLAUDE.md 至少包含四块内容：

项目技术栈与目录结构。
常用命令（启动、测试、构建）。
编码约定（命名、分层、错误处理）。
禁止触碰的边界（比如某些目录不能改）。

这样做的收益是：你不需要在每条指令里重复背景，模型自己就知道“这个项目用 Spring Boot，数据库操作必须走 Service 层”。长期下来，省下的 token 和沟通成本非常可观。

4.2 一条指令只聚焦一个目标

问题：把“改接口 + 修 bug + 加测试 + 重构”全塞进一条指令，模型会在多目标之间摇摆，最后每条都做不完整。

方案：把大任务拆成多个小任务，逐个下发。你可以先让模型“只做问题定位，不要修改代码”，再基于定位结果“给出最小修改方案”，确认后再执行修改。这类分阶段推进方式，比一次性下大指令更容易拿到可控结果。

这一点非常关键。Agent 的每一步行动都会消耗上下文，目标越分散，上下文越容易被无关探索占满。一次只做一件事，是保证输出质量最直接的手段。

4.3 先写验收标准，再写实现要求

问题：你说“优化性能”，模型可能去改架构、换算法，结果测完性能没变化，代码却被改得面目全非。

方案：在指令里先写“什么样的结果算完成”，例如：

接口 p95 响应时间从 800ms 降到 400ms 以内。
所有现有测试必须通过。
不修改数据库表结构。
不引入新的第三方依赖。

验收标准本质上是给模型画了一个“完成边界”。有了它，模型才知道什么时候该停，才不会为了“显得努力”而过度修改。越是模糊的需求，越容易触发大范围改动。

4.4 善用 Plan 模式，先规划后动手

问题：模型直接改代码，改完你发现方向错了，浪费一次完整执行链路。

方案：在复杂任务上，先让 Claude Code 进入 Plan 模式，只输出实现方案，不直接修改文件。你审阅方案、纠正方向后，再切换执行模式让它真正动手。这相当于在“想”和“做”之间加了一道人工确认关卡。

对于涉及多个文件、数据库变更、核心业务逻辑的任务，这一步能省下大量返工时间。团队协作时，这份“方案”还可以直接贴到 PR 描述里，让评审者提前看到意图。

4.5 控制上下文长度，及时压缩

问题：会话越长，模型越容易忘记早期信息，甚至开始把无关的旧代码当成“当前状态”。

方案：合理使用会话管理命令，比如/compact压缩当前上下文，/clear开启全新会话。决策原则是：

一个任务完成后，如果下一个任务和它无关，就开新会话。
会话中如果模型开始复述旧内容、行为变得迟钝，先压缩上下文。
长期需要的信息，不放会话里，放 CLAUDE.md 里。

记住一个原则：会话是短时记忆，CLAUDE.md 是长期记忆。别把短时记忆当长期记忆用。如果你发现同一个大功能反复偏移需求，大概率是会话上下文里混入了太多历史噪音。

4.6 把重复任务封装成 Skills

问题：团队每周都要让 Claude Code 做“新增一个带分页的 REST 接口”，但每次都要从头敲一遍同样风格的提示。

方案：把这类高频任务写成 Skills——一段结构化的指令模板，放在 Claude Code 能识别的配置目录中。模型在遇到匹配任务时，会读取 Skill 里的流程来执行。把重复任务的执行流程、检查清单、输出规范固定下来，本质上是在做“团队的 Agent 私有化最佳实践”。

一个合格的 Skill 应包含：触发条件、执行步骤、输出格式、质量检查清单。这样即使不熟悉项目的人，也能通过复用 Skill 获得风格一致的代码产出。

5. 完整示例：搭建一套可复用的 Claude Code 配置

下面以一个真实的 Java Spring Boot 项目为例，展示从配置到提示词的一整套流程。

5.1 项目级 CLAUDE.md 示例

假设项目根目录为auth-service，创建CLAUDE.md：

# CLAUDE.md ## 项目概况 - 技术栈：Java 17 + Spring Boot 3.x + MyBatis-Plus + PostgreSQL - 构建工具：Maven - 本地服务端口：8080 ## 常用命令 - 启动：mvn spring-boot:run - 单元测试：mvn test -Dtest=类名 - 全量测试：mvn test - 打包：mvn clean package ## 编码约定 - Controller 只做参数校验和路由转发，不写业务逻辑 - 业务逻辑统一放入 Service 层 - 数据库操作必须经过 Mapper 层，禁止在 Service 中拼接 SQL - 错误码统一从 ErrorCode 枚举获取，禁止硬编码错误字符串 - 新增接口必须补充接口文档注释 ## 禁止事项 - 不要改动 src/main/resources/db/migration 下的历史迁移脚本 - 不要修改 application-prod.yml 中的数据库连接配置 - 不要删除 pom.xml 中任何已有的依赖

这份文件的真正价值在于：每次新会话启动，模型都会自动知道项目边界。你后续下指令时，不需要再解释项目结构。团队可以把这份文件纳入 code review，它本身就是一份活文档。

5.2 settings.json 权限与 hooks 示例

在项目.claude/settings.json中配置权限和白名单命令：

{ "permissions": { "allow": [ "Bash(mvn test)", "Bash(npm run lint)", "Bash(git status)", "Bash(git diff)", "Read(project/docs/**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force)", "Write(database/*)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npm run lint -- --fix" } ] } ] } }

权限配置的目的不是限制模型，而是减少事故。让模型只执行白名单命令，能避免它因为“自主性过强”而做出危险操作。Hooks 配置的效果是：模型每次修改完文件，自动触发 lint 修复。这是一个非常实用的工程化手段，相当于把团队代码规范内嵌到 Agent 的工作流中。

5.3 高质量提示词：一个对比示例

假设任务：修复登录接口在密码错误时返回 HTTP 500 的问题。

低质量提示：

帮我修一下登录接口的 bug。

这种提示的问题很明显：模型不知道项目结构，不知道期望行为，也不知道“修完”怎么验证。它会先花时间探索代码，然后凭猜测动手。

更好的提示：

项目：auth-service（Java / Spring Boot） 问题：POST /api/login 在账号或密码错误时返回 HTTP 500，期望返回 401。 请按以下步骤处理： 1. 先定位 LoginController -> LoginService -> 异常处理链路； 2. 判断异常是由业务逻辑主动抛出，还是被全局异常处理器捕获； 3. 给出最小修复方案，不涉及其他功能； 4. 补充一个针对错误密码场景的单元测试； 5. 运行 mvn test -Dtest=LoginServiceTest，展示测试结果。 约束： - 不修改数据库表结构； - 不修改接口返回字段名； - 不更改全局异常处理器的其他逻辑； - 完成后用 git diff 展示改动摘要。

对比两组提示可以发现，高质量的提示并没有使用更复杂的词汇，而是补齐了背景信息、执行步骤、验证方式和约束条件。这四部分缺一不可。

5.4 在终端中运行

启动会话后，直接把上面的高质量提示粘贴给 Claude Code：

cd /path/to/auth-service claude

然后粘贴提示词。模型会按照 1 到 5 的步骤推进。你可以在它每完成一步后介入确认，也可以等它全部完成后统一用git diff审查改动。初次使用时，建议每两步检查一次，逐步建立对模型行为的信任感。

6. 运行效果与验证方式

6.1 如何判断任务完成

Claude Code 任务是否成功，不能只看“模型说完成了”，而要看三个客观信号：

git diff 合理：改动范围是否与任务描述匹配，是否出现了预期外的文件变更。
测试通过：任务中涉及的测试命令是否有绿色输出。
行为符合验收标准：回到业务层面验证，比如错误密码场景确实返回 401。

git diff --stat

这个命令可以快速查看本次会话改动了哪些文件。如果发现模型改了不该动的文件（比如 pom.xml、application-prod.yml），立即回滚相关文件：

git checkout -- <文件路径>

6.2 验证过程中的常见现象

模型声称测试通过，但实际测试命令没有输出。原因通常是模型只做了解释性回答，没有真正执行终端命令。此时要明确要求“请实际运行 mvn test 并把输出贴出来”。
模型修改了多个文件，但逻辑上互相矛盾。原因是长会话中上下文被旧内容干扰。处理方式是压缩上下文或开启新会话，然后把已改动的文件作为新的上下文再继续。
模型在修改后没有运行 lint 或测试。原因是提示词没有写清楚验收步骤。把“运行测试、贴出输出”写进步骤列表即可解决。

判断是否成功，本质上是在验证提示词是否闭环：输入信息是否足够、执行边界是否清晰、验收标准是否可量化。如果验证失败，优先优化提示词结构，而不是立刻怀疑工具不好用。

6.3 一次完整会话的预期输出

以 5.3 的登录接口修复任务为例，成功时会话中会出现以下关键节点：

Claude Code 开始处理任务 → 读取 LoginController.java、LoginService.java → 定位 GlobalExceptionHandler 中异常处理逻辑 → 给出修复方案，修改对应 Service 或异常处理代码 → 新增或更新单元测试 → 运行 mvn test -Dtest=LoginServiceTest → 展示测试结果与 git diff 摘要

如果你的会话里缺失了中间任何一个节点，比如没有运行测试就直接说“已完成”，可以通过追加指令要求补上。这也是验证提示词是否完整的信号。

7. 常见问题与排查思路

这里整理了社区使用 Claude Code 时最常见的几类问题。如果你也碰到了类似报错，可以按表格里的顺序排查。

问题现象	可能原因	排查方式	解决方案
启动或请求时提示 unable to connect to api.anthropic.com，status 403	网络无法访问 Anthropic 服务、登录凭证过期、本机代理规则异常	先检查网络连通性，再确认登录状态，最后检查系统代理配置	确认网络环境可访问官方接口；重新执行登录授权；检查并修正代理规则
提示 doesn't look like an anthropic model: expected a gateway model route reference	使用了第三方网关或中转服务，但模型路由标识配置不正确	检查网关配置中的模型名称、路由前缀	按网关文档配置正确的 Anthropic 模型路由，或改用官方模型路线
Windows PowerShell 下 npm 安装报错	权限不足、npm 版本过旧、执行策略限制脚本	查看完整报错堆栈；执行 node -v 和 npm -v 检查版本	以当前用户权限安装；升级 npm；检查 PowerShell 执行策略
终端显示中文乱码	终端代码页与 UTF-8 不一致，常见于 Windows	执行 chcp 查看当前代码页	切换到 UTF-8 代码页，或更换支持 UTF-8 的终端
模型执行了危险命令或改动超范围	权限配置未限制、提示词没有给边界	检查 settings.json 的 permissions 配置	在配置中 deny 危险命令；提示词中写明“禁止修改的文件/目录”
长会话后模型表现变差、遗忘早期需求	上下文过长，模型被旧内容干扰	观察模型是否开始复述旧代码或行为迟钝	使用 /compact 压缩上下文，或 /clear 开启新会话
配置了网关后，同一提示词在不同模型上效果差异大	非官方模型的工具调用能力与指令遵循能力不同	分别对比官方模型和网关模型的输出	以官方模型为基准完成开发；若必须用网关，降低任务复杂度并增加人工确认

如果以上问题都没有覆盖到你的场景，最稳妥的排查路径是：完整复现报错 → 提取关键错误码 → 查官方文档或社区讨论 → 用最小项目复现验证。不要在生产项目里反复试错。

8. 工程化最佳实践与安全建议

8.1 把提示工程当成代码资产管理

CLAUDE.md、settings.json、Skills 指令模板，本质上是项目代码的一部分，应该进入版本控制，随项目一起评审和演进。建议在项目中建立docs/agent/目录，把提示词模板、配置说明、使用约定放进去。团队新成员加入时，不用从头探索“这个 Agent 项目该怎么配置”，看文档即可。

好的提示词不是一次写成的，而是在真实任务中持续迭代的。建议把“哪些提示有效、哪些提示失败”沉淀成团队经验，避免重复踩坑。

8.2 权限与安全边界

Claude Code 有执行命令的能力，这既是优势也是风险。在生产环境或敏感仓库中使用时，务必做到：

最小权限原则：只在 permissions 中放必要命令。
禁止危险命令：对 rm -rf、git push --force、数据库直连写入等操作一律 deny。
数据库操作必须加人工确认：涉及生产库变更时，不要直接让模型执行 DML/DDL，而应让模型生成 SQL 脚本，由人审阅后执行。
敏感信息隔离：不要在提示词中粘贴生产环境的密钥、密码或凭证，环境的读取应交由受控的配置中心或密钥管理服务。

8.3 版本与兼容性

Claude Code 迭代速度很快，配置格式和命令可能会随版本变化。建议：

在claude --version后记录当前版本。
升级后先跑一遍最小冒烟任务，验证 CLAUDE.md 加载和权限配置没有异常。
不要长期停留在旧版本，但也不要一有新版就立即切换生产环境。

如果你维护多个项目，建议每个项目单独保存一份.claude配置的版本记录，方便在升级后快速定位是哪部分配置不再兼容。

8.4 日志与可观测性

让 Agent 修改代码，必须有可观测的产物：

每次任务后审查 git diff。
关键配置变更保留提交记录。
如果接入了 CI/CD，对 Agent 生成的改动单独跑一遍完整流水线。

从工程视角看，Agent 不是“更聪明的结对程序员”，而是“需要更严格 review 流程的协作者”。它可以把重复劳动压缩到分钟级，但最终的质量责任仍然在人。

9. 总结与后续学习方向

Claude Code 提示技巧的核心，不是学会几句“魔法指令”，而是理解 Agent 的工作原理后，把上下文、边界、验收标准设计成一套可复用的工程配置。

这篇文章主要讲了六件事：用 CLAUDE.md 做项目记忆、一次聚焦一个目标、先写验收标准、用 Plan 模式控制方向、及时压缩上下文、用 Skills 沉淀高频任务，并给出了一份可以直接参考的配置示例和排查表。

你接下来可以这样做：

在个人项目里先建立一份 CLAUDE.md，把项目结构和常用命令写进去，用一周感受差异。
把一条你反复发给模型的长提示，改成“背景 + 步骤 + 验收 + 约束”四段式，对比效果。
找一个重复性任务，尝试封装成 Skill，让模型按模板执行。
再深入看官方文档中关于 hooks、MCP、子代理的用法。这些能力与提示技巧叠加，才是 Claude Code 更完整的生产力来源。

最后提醒一句：Claude Code 的能力边界取决于模型，但使用效果很大程度取决于你怎么为它准备上下文。把这个环节做好，比盲目追求新版本更值得投入。