1. 项目概述Claude Code 到底是什么先直说结论Claude Code 是 Anthropic 官方推出的命令行 AI 编程工具跑在终端里用自然语言跟它对话就能完成读代码、改代码、跑命令、提 PR 这一整套开发动作。它不是 IDE 插件也不是聊天网页而是一个真正住在你终端里的“结对程序员”。我第一次用的时候最大的感受是“这玩意居然能自己翻我的代码库”。你不需要把文件贴给它只需要给它一个项目路径它就能自己遍历目录、读文件、理解模块之间的关系然后按你的要求改代码。这种体验跟之前在网页对话框里粘贴代码完全不是一回事。这个项目属于“7D-AI系列”里的一环核心就是 Claude Code 的命令体系。很多人刚开始接触这个工具最大的门槛不是“怎么安装”而是“装完之后不知道跟它说什么、怎么让它干活”。命令集就是解决这个问题的——你不需要背一堆复杂的参数而是要知道几个核心命令怎么组合使用就能让它在实际项目里跑起来。这篇内容适合谁两类人。第一类是已经装了 Claude Code但觉得“也就那样”的开发者你缺的其实是正确使用命令的方法论。第二类是还没装但在观望的人看完你会知道这东西到底能帮你干什么值不值得折腾。2. 基础命令体系先跟 Claude Code 搭上话2.1 进入会话的方式claude 还是 claude -pClaude Code 有两种基本使用模式对应两个命令入口。# 交互式会话进入一个 REPL 式的对话界面 claude # 一次性执行直接在命令里带上你的需求 claude -p 看看 src/ 目录下有哪些 TODO 注释交互式会话适合长时间待在项目里干活Claude 会保持对话上下文你可以一步步交代任务上一句说“帮我找到登录逻辑”下一句说“把那个函数改成异步”它都记得上下文。一次性执行模式适合脚本化调用或者你只是想快速问个问题不想开个会话。实测下来-p 模式在 CI 流程里特别有用比如提交前自动检查代码规范或者定时巡检项目里的技术债。输出默认是纯文本如果想拿到结构化结果可以加上 --output-format json后面再细说。2.2 启动参数让 Claude 用你习惯的方式干活启动参数不是摆设它们直接影响 Claude 的行为边界和输出质量。我经常用到的这么几个# 指定工作目录 claude --cwd /path/to/project # 设置输出的编码类型处理注释或字符串时很有用 claude --output-format text # 允许读取更多类型的文件 claude --permission-mode acceptEdits # 启动时不读取 CLAUDE.md claude --no-user-input--output-format有 text、json、stream-json 三种可选做自动化集成的时候强烈建议用 stream-json每一行都是一个 JSON 对象解析起来非常干净。--permission-mode这个参数控制的是 Claude 在文件写入、命令执行上的权限策略。acceptEdits 模式会在改文件前自动确认配合交互会话很顺畅。如果你是单次任务并且对改的内容完全信任可以用 bypassPermissions不推荐真出问题你会哭。2.3 三类对话模式kebab-case / JSON / 业务逻辑很多人不知道 Claude Code 的对话其实有三种形态理解这个区分能帮你更精准地提需求。第一种是普通自然语言对话kebab-case 风格。比如“为这个函数补充单元测试”、“把这两处硬编码替换成常量”。这种适合描述意图Claude 会结合上下文自行发挥实现方式。第二种是结构化 JSON 输入。交互会话里你可以直接贴一段 JSON告诉它“用户信息字段是这个结构我需要校验逻辑”或者更极端一点——直接用特定 schema 约束它生成的结果格式。实测下来当需求涉及多字段、多条件判断时给它结构化输入比长篇大论的自然语言靠谱得多。第三种是纯业务逻辑描述。这个最考验提示词功力。你不需要告诉它怎么实现只要把业务场景描述清楚“用户登录后需要跳转到上一次浏览的商品页但如果是从订单页跳过去的要回到订单确认页。”Claude Code 的代码理解能力足够支撑它从这种描述里反推出完整的实现方案。3. Slash 命令把常用操作变成一条斜杠的事3.1 内置命令一览/init、/compact、/model 这些到底干嘛的Claude Code 内置了一批斜杠命令用 / 开头。这些命令解决的是高频操作不用每次打字解释。先列我实际用过的这几个。/init是个新手一定要知道命令。它会扫描整个项目分析代码结构、依赖关系、技术栈然后在项目根目录生成一份 CLAUDE.md 文件。这份文件就是 Claude 的项目说明书里面写清楚了这个项目是什么、怎么跑、有哪些约定。之后再启动会话Claude 会默认带着这份说明书来理解项目。/compact是上下文压缩命令。对话时间长了历史消息会占用大量上下文窗口Claude 的“记忆力”会被稀释。敲一下 /compact它会将之前的对话摘要成一个精简版本释放上下文空间然后用摘要继续往下干活。/model让你在当前会话里切换模型。Claude Code 底层用的是 Claude 系列模型不同模型的推理能力和速度有差异日常小改动用轻量模型就够大工程重构再切到最强模型。/clear清空当前会话历史重新开始。注意它不只是清屏是把上下文彻底重置适合换任务的时候使用。/agents进入子代理模式这个后面单独讲。/permissions查看和修改当前会话里 Claude 的权限设置可以临时放开或收紧。3.2 自定义 Slash 命令把项目里的重复劳动做成斜杠指令内置命令只是开胃菜真正提升效率的是自定义命令。Claude Code 允许你在项目的.claude/commands/目录下放 Markdown 文件每个文件就是一个斜杠命令。举个例子我们的项目经常需要在启动前检查环境配置于是我建了一个.claude/commands/check-env.md内容大概是请检查当前项目的环境配置 1. 读取 .env.example 文件对照 .env 里的实际配置 2. 检查是否缺少必填项 3. 如果发现差异列出具体字段名和缺失原因之后每次只要在会话里敲/check-env它就自动执行这套检查流程。同样的思路我们做了/deploy-check、/test-core、/docs-update一整套自定义命令团队成员直接共用新人上手成本大大降低。自定义命令里还可以写变量占位符比如$ARGUMENTS代表你在命令后输入的参数$1代表第一个参数配合 Bash 命令可以写出很灵活的组合操作。3.3 权限系统什么时候该给 Claude 放开手脚权限是团队协作里绕不开的话题。Claude Code 默认对文件修改和命令执行有一套审批机制每次要动文件或跑命令都要跟你确认。这在单人使用是安全网在多人协作时就是效率杀手。建议的做法是分场景设权限。日常开发用 acceptEdits跑测试用 allowDangerous只有在你明确知道要改什么文件、执行什么命令时才开 bypassPermissions。团队里如果要统一策略可以在 CLAUDE.md 里写清楚哪些操作默认允许、哪些必须人工确认Claude 会阅读并遵循这些约定。权限设置还可以在启动时通过--permission-mode指定或者会话中/permissions查看。别在任何不受信任的项目里放开权限一个恶意构建脚本就可能借 Claude 的手删掉你整个node_modules。4. 会话上下文Claude Code 的记忆管理秘术4.1 会话恢复--resume 和 --continue 的区别做过长任务的都知道上下文不丢有多重要。Claude Code 的所有交互会话都会自动保存你可以随时恢复。# 恢复上一次会话 claude --resume # 直接接续最近的会话不进入选择界面 claude --continue--resume 会进入一个会话选择界面列出历史会话的时间、主题摘要挑一个进去。--continue 则是无脑接续最近的会话。我用这两个的使用频率大概是 7:3日常连续开发用 --continue跨天回来想找之前的某个排查过程用 --resume。会话 ID 是哈希字符串不好记。但 /resume 命令在交互会话里能调出一个会话列表按时间倒序带摘要选起来舒服得多。建议在做复杂重构的时候一个任务开一个新会话配一个明确的首次需求描述之后恢复的时候一眼能找到。4.2 CLAUDE.md给 Claude 写的项目说明书CLAUDE.md 是这个工具的灵魂文件位置在项目根目录或者用户目录下。它的作用类似 README 的“给 AI 看的版本”告诉 Claude 这个项目该怎么理解。# 项目说明 ## 技术栈 - 后端Java 21 Spring Boot 3 - 前端React 18 TypeScript - 数据库PostgreSQL 15 ## 常用命令 - 启动开发环境docker-compose up -d - 运行测试./mvnw test - 代码规范./mvnw spotless:apply ## 关键约定 - 所有接口返回统一 Result 封装 - 数据库变更必须写 Flyway 迁移脚本 - 禁止在 Controller 里写业务逻辑写这个文件的前提是你得先想清楚这个项目的边界和约定。Claude 会在每次会话开始时读取它并且在整个会话中通过它理解代码。项目里 CLAUDE.md 写得越准确Claude 的代码修改就越贴合你的预期。有一种使用技巧是“渐进式维护”。每次 Claude 做了一轮修改但没完全贴合你的项目规范就把规范补进 CLAUDE.md下次它就记住了。“调教”的过程实际上就是把这个文件写细写准的过程。4.3 FileCatalog让 Claude 在 1 万行代码里快速定位FileCatalog 是 Claude Code 的一个文件索引机制对应命令claude --add-catalog或者交互会话里的/add-catalog。它解决的是大项目里 Claude 找文件效率低的问题。原理是给项目目录生成一份索引文件记录每个文件的作用、关键函数、模块依赖Claude 读这份索引就能快速定位相关代码不用从头翻目录树。这对单体大项目来说效果尤其明显跨模块引用时 Clude 不会迷路。索引文件需要维护项目结构大改后要重新生成。实测下来每跑完一次大重构就重建一次索引是性价比最高的做法。索引文件本身可以提交进 git团队共享同一份索引。4.4 上下文窗口告急理解 Token 上限与 /compact 的取舍上下文窗口限制是所有大模型工具的天花板。Claude Code 的上下文包含对话历史、CLAUDE.md、FileCatalog 索引、工具调用记录这些加起来很快会吃掉大量 Token。当你感觉 Claude 的回复开始“语无伦次”或者忘记刚开始交代的任务就该考虑 /compact 了。它把当前对话摘要成要点释放原有 Token 空间。但压缩本身是有损的细节越多的任务压缩后丢失的可能性越大。我的经验是复杂任务拆阶段每完成一个阶段就让它先做小结再开启新会话继续。小任务尽量在一个会话里一口气干完不多开线程。这个习惯比依赖 /compact 更靠谱。5. Agent 模式让 Claude 自己找到代码并修改5.1 Agent 模式的核心逻辑拆解、搜索、修改、验证Agent 模式是 Claude Code 的重头戏它让 Claude 不仅仅是“聊天”而是真正“动手干活”。在 Agent 模式下Claude 会主动调用搜索、读文件、编辑文件、运行命令这些工具自主完成一个完整任务。它的工作逻辑是四步循环拆解目标、搜索定位、修改代码、验证结果。比如你让它“优化订单超时取消逻辑”它会先分析涉及订单状态流转的位置找到定时任务或消息队列的实现文件重写核心逻辑然后运行测试看有没有破坏现有功能。这个过程里你不需要告诉它文件路径它会用 grep 搜索关键词、读文件理解结构、自己定位改动点。跟传统“你给我文件路径我改给你看”的模式完全不同这是 Agent 模式最核心的差异点。启动方式是会话里输入/agents或者用启动参数--agents。建议一开始给一个小任务让它自己折腾完再校准观察它的工作模式是否顺畅。5.2 子代理分工一个 Supervisor 带多个 Worker实际大型项目里一个 Agent 往往不够用。Claude Code 的子代理机制允许你同时调度多个 Agent分管不同的模块或任务。常见的用法是 Supervisor 模式一个主代理负责任务拆分和进度汇总调派多个专属代理去处理具体模块。比如重构一个订单系统可以让一个子代理负责数据库层改动另一个负责缓存层第三个处理消息队列最后由主代理统一 review 和合并。实现方式是在会话里交代多个子代理的职责Claude Code 会用 Tool 调用的方式调度它们。实际效果看三个以内的并发子代理效率最高超过三个协调成本会急剧上升。注意要限制子代理的权限边界同一个会话里给所有子代理开全权限是非常危险的操作。我们在实际使用中子代理默认只能改自己负责的目录需要跨目录操作必须上报主代理处理。5.3 批处理模式直接让 Claude 操作 Shell 执行任务在非交互场景下Claude Code 可以通过claude -p配合管道和 Shell 命令实现批处理。这使得它可以嵌入脚本、CI 流程或者定时任务。# 让 Claude 分析某个提交里的所有变更 git diff HEAD~1 HEAD | claude -p 逐段分析这个 diff指出潜在 bug # 让 Claude 自动修复代码格式 claude -p 运行项目里的代码格式化工具 --permission-mode acceptEdits批处理模式的核心逻辑是“单次请求无后续跟进”所以你需要在指令里把上下文给足。把 diff、日志、错误栈直接通过管道传给 Claude是最省事也最高效的集成方式。实测中最有用的场景是 CI 失败后的自动诊断。构建日志导入claude -p 分析这段 CI 失败日志定位可能的错误原因给出修复建议能省掉一大半手动排查时间。6. 输出模式与脚本集成让 Claude Code 长进你的流水线6.1 输出格式控制text / json / stream-json 怎么选Claude Code 支持三种输出格式text 纯文本、json 单次 JSON、stream-json 多次 JSON 流。这决定了你拿它做自动化时的解析方式。# 单次 JSON 输出 claude -p 列出项目里的所有 .md 文件 --output-format json # 流式 JSON 输出适合长任务 claude -p 分析这段代码的问题 --output-format stream-jsontext 适合人看json 适合脚本解析stream-json 适合边执行边解析的场景。stream-json 每一行都是一个 JSON 对象包含消息内容、工具调用、状态变更等字段你可以前一行处理完就开始流式渲染不用等全部执行完。我实际做的一个小工具是“自动生成变更日志”把 git log 导进来让 Claude 按约定格式输出 json再被脚本渲染成 Markdown 变更日志。这个链路完全自动化发布前端跑一次就出文档。6.2 非交互模式下传参完整参数表使用心得非交互模式下Claude Code 的参数组合能应对各种复杂的自动化需求。生产环境里我常用的几个参数# 最多读取 10 个文件适用于分析大项目 claude -p 查询这个项目的整体技术栈 --max-reads 10 # 设置较长的单次输出上限 claude -p 详细说明这个模块的设计思路 --max-output-tokens 8000 # 全权限模式适用于完全信任的脚本环境 claude -p 把代码格式化并提交 --permission-mode bypassPermissions --dangerously-skip-permissions--max-reads限制了 Claude 最多查看多少文件。当你知道项目很大不要给太小否则它会浅尝辄止。--max-output-tokens用于控制单次回答的长度上限写报告类需求建议调大。--dangerously-skip-permissions是双重保险开关配合--permission-mode bypassPermissions一起生效。在本地开发环境偶尔用用没关系但任何 CI 流水线里都得三思。6.3 通过 stdin/stdout 管道集成Claude Code 最灵活的集成方式是通过标准输入输出管道。这意味着任何能输出文本的程序都能把内容喂给 Claude拿回分析结果。# 用 Python 脚本采集代码再交给 Claude 分析 python collect_metrics.py | claude -p 分析这份指标数据找出性能瓶颈 # 日志分析 tail -100 app.log | claude -p 分析这些错误日志帮我归纳常见问题这种模式的精髓在于“让工具干它擅长的事”。Claude 擅长语义理解你的脚本擅长数据采集两者一拼就是一条轻量级自动化流水线。我们自己还做过一个“代码评审助手”把 merge request 的 diff 抓下来喂给 Claude 做静态审查输出风险点列表直接贴到评审评论里。6.4 环境变量配置API Key 与自定义配置Claude Code 的配置通过环境变量和 config 文件控制。最核心的两个# API Key必填 export ANTHROPIC_API_KEY你的key # 指定模型默认是最新型号 export ANTHROPIC_MODELclaude-sonnet-4-20250514配置还有一层优先级逻辑命令行参数 环境变量 配置文件。也就是说你可以在配置文件里写默认值在具体命令里用参数覆盖。模型选择上日常小任务用轻量模型跑得快大工程重构才上重型模型。Claude Code 里的/model命令能随时切换实际体验方便得很。7. 工程实践我拿 Claude Code 干了哪些正经事7.1 代码重构实战从“改个小点”到跨文件重构第一个高频场景是代码重构。传统做法得先全局搜索、梳理调用链、逐个文件替换、跑测试一套流程下来半天没了。用 Claude Code过程可以压缩到十几分钟。实测的一次重构项目里的支付模块用了过时的回调签名导致新需求难扩展。我给的指令是“找到支付回调的入口把回调签名从旧的 notifyUrl 模式改为新的回调事件模式保持兼容旧逻辑。”Claude Code 自己定位了 6 个相关文件改了核心接口和三个实现类保留了旧的兼容层最后跑了全部测试改完直接能跑。重点是要说清楚“要让什么到什么”而不是“改哪个文件的哪个函数”。Claude 自己能找到位置你给方向就行。7.2 技术债扫描让它读完整项目后列出 TODOClaude Code 在代码审查和技术债管理上同样好用。给它一个“扫描全项目 TODO/FIXME/临时方案”它能从所有源码文件中定位这些标记同时根据上下文判断哪些是低风险、哪些可能导致线上问题。这个能力本质上是“语义筛选”。普通 grep 只能告诉你哪里写了 TODOClaude 还能告诉你这个 TODO 背后的业务背景、影响范围、可能的修复方向。实际输出可以直接变成团队排期需求池。我们把 Claude 扫出来的问题贴到项目管理工具里标注严重级别和文件位置研发按优先级处理。这个流程我们每两周跑一次稳定且省力。7.3 新项目脚手架快速生成初版目录和代码从零开始一个新项目最耗时间的往往不是写业务代码而是把目录结构、配置文件、基础模块搭起来。Claude Code 在这方面极为高效。一句话指令“创建一个 Java Spring Boot 项目基于 Maven包含用户模块、订单模块、商品模块使用 PostgreSQL接口风格 RESTful包含统一异常处理和分页封装。”它就能生成可运行的项目骨架目录层级、pom 依赖、配置文件全都齐活。生成之后需要微调的通常是业务细节比如具体字段定义、接口路径命名、返回值结构。基础架构骨架完全可以自动化。这里建议生成完立刻跑一遍构建和基础测试确认它能跑通再开始加业务逻辑。8. 常见问题与排查技巧实录8.1 命令执行超时如何给长任务留出足够时间Claude Code 跑长任务时经常会遇到“执行超时”。默认的执行时限对大型重构任务往往不够。遇到这种问题先排查是不是上下文过长导致生成效率下降再考虑调大超时参数。具体做法交互会话里长任务建议拆成几个阶段执行触发 /compact 后再继续。非交互环境下调大--max-output-tokens给足输出缓冲。还有一种情况是权限确认拖慢了流程。每次写文件都要人为点确认任务一长就烦人。建议对自己完全熟悉的项目直接放开权限配合自动测试兜底效率能提升好几倍。8.2 权限不足报错权限配置优先级梳理终端里最烦的报错就是 Permission denied 之类的权限拦截。Claude Code 的权限体系分文件访问和命令执行两块报错的时候先分清是哪一类。文件访问的报错一般是“Claude needs permission to read X”命令执行是“Cannot run command Y”。前者通过 permission-mode 调整读写策略后者需要检查该命令是否在白名单内。CLAUDE.md 里通过 allowedTools 和 denyTools 显式声明许可范围。我用过一次场景是它要执行 docker 命令默认被拦。在配置里把 docker 相关命令加入白名单之后就顺畅了。原则是“最小权限 按需放行”不要一把梭全放。8.3 上下文过载识别信号与处理节奏Claude 开始重复你之前说过的话、忘记早期任务的细节、或者回答变得异常简短基本就是上下文快满了。处理节奏因人而异我的习惯是任务进行三分之一左右主动做一次小结让它把已经完成的部分压缩成摘要再往下走每完成一个关键节点开一个新会话继续下一阶段。这个习惯比等到出问题再 /compact 要稳妥得多。8.4 输出格式异常处理 markdown 被截断或 json 解析失败Claude Code 因为输出是从模型生成的偶尔会碰到内容截断、json 格式不完整这类问题。最常见的是长输出超限导致末尾被硬切。简单办法是拆分问题为多个小请求或者调大输出上限。JSON 解析失败大多是 Claude 在代码块里输出的注释、示例混进了实际 json 字段。用 stream-json 时多一步“过滤非 JSON 行”的防护逻辑解析前做一次容错清洗。实际上模型输出的稳定性已经很高了这些异常大概率出现在上下文过载或模型切换的瞬间。多关注上下文长度和模型状态问题自然少。8.5 功能建议几个值得尝试的进阶玩法最后说几个我试过确认好用的进阶功能。第一是让 Claude Code 写测试不只是单元测试还包括集成测试。给定业务场景描述它能生成覆盖正常路径、异常路径、边界条件的完整测试用例质量比大部分手写的要稳定。第二是把 Claude Code 接入闲聊式的架构评审。你描述一个新需求让它先读现有代码再评估改动影响面输出风险清单和备选方案。这个功能对技术方案预审很实用。第三是团队知识库构建。用 Claude Code 从老代码里提取业务逻辑文档输出到项目的 docs 目录新人上手时不用再看口水代码一行行啃。我个人的体会是Claude Code 最值得投入精力的方向是用好 CLAUDE.md 和自定义斜杠命令把团队规范沉淀进去让每个成员都能在统一语义下跟它协作。命令集不是用来背的是用来组合出属于你自己工作流的积木。这套东西越用越省力但前提是你愿意花时间把它调教成适合你项目的形态。