如果你常年在IDE和网页AI之间来回搬运代码大概率有过一种很拧巴的感觉一边是强大的对话模型一边是真正要维护的工程目录两边中间隔着一层剪贴板。过去我习惯把代码复制给网页AI再把建议半行半行地粘回来遇到稍大的重构就是一场体力劳动。后来我改用终端里的编程助手——Claude Code模式彻底变了它直接在终端里启动能自己读目录、改文件、跑命令、盯测试结果我只需要说“哪里有问题、想改成什么样”。这篇手册把我从入门、配置到高级自动化沉淀下来的完整用法做一个梳理。它不是官方文档的复读而是我这几个月真实跑项目、踩坑之后留下的实践笔记。适合所有想在终端里把AI当“真同事”用的人无论是刚接触CLI的新人还是已经对Agent类工具有一定经验的开发者都能从中找到能直接落地的操作。1. 为什么把AI从浏览器搬进终端1.1 它更接近一个“能干活的人”网页AI解决的是“生成方案”Claude Code解决的是“执行方案”。它运行在本地终端里本质上是一个带着自然语言理解能力的命令行智能体能够串联完成文件读取、代码搜索、命令执行、结果阅读、再次修改这一整条闭环路径。你不需要把问题拆成一系列shell命令只需要用一句人话描述目标它会自己规划步骤。我刚开始使用时最不适应的一点就是它真的会动手改文件。第一次让它“修复一个类型错误”时它先定位到文件再用编辑工具改掉问题点然后运行测试验证整个过程我都没动键盘。这和“复制一段代码去网页里问”是完全不同的协作关系。1.2 最适合哪些场景高频场景我总结下来有这么几类探索历史遗留代码对不熟悉的工程让它解释模块结构、梳理调用链、标注可疑点。批量机械修改统一改命名、补缺失的导出、批量加日志这种工作人做容易漏AI适合兜底。补测试和文档生成单测骨架、补注释、写变更记录只需要喂给它模块入口。修复Bug描述现象让它从错误栈反查代码而不是自己逐文件翻。执行多步骤的工程任务比如“把某个功能从A模块迁移到B模块并保持对外接口不变”。不太适合的场景也有。涉及不可逆的大规模变更最好先让AI只生成计划人工确认后再执行涉及业务上“必须按特定规则”的改动如果规则没有写在文档里AI容易按常识处理翻车概率不低。1.3 和网页对话的差距在哪里我用一张表说明两者差别更直观一些能力网页AIClaude Code读取当前文件需要手动粘贴直接读取搜索整个工程代码不支持支持内容检索和文件遍历执行构建、测试命令只给文本建议可以执行并继续处理输出修改文件需要你手动应用直接落盘并可查看差异连续处理长任务上下文容易断会按步骤推进衔接中间结果感知git状态无能知道当前分支和变更文件选择它并不是说网页AI不再有用而是在“真正要写下代码”的时候终端这个形态天然离工作现场更近。2. 五步上手安装、登录与第一次对话2.1 第一步准备好终端环境Claude Code本质是一个Node命令行应用所以本机需要先有Node运行环境并确保npm命令可用。安装前在终端里确认一下node -v npm -v如果两条命令都能正常输出版本号说明环境就绪。Windows用户建议使用系统自带的现代终端而不是老的命令提示符窗口否则中文输出和快捷键都可能遇到一些小问题。2.2 第二步全局安装官方CLI包通过npm把CLI安装到全局环境命令如下npm install -g anthropic-ai/claude-code安装完成后验证是否成功claude --version能看到版本号就说明装好了。如果提示命令找不到多半是npm全局bin目录没有加入PATH重新打开终端窗口或者检查环境变量配置即可。2.3 第三步登录与授权第一次运行claude命令时它会引导你完成登录认证。这里需要你有一个可用的账号并按终端提示完成浏览器或验证码授权流程。认证通过后凭证会保存在本地配置目录后续使用不需要重复登录。有一点容易忽略这个工具的运行权限是你的身份凭证相当于把你的终端权限交给了AI。因此不要在无法信任的设备上直接登录也不要随意共享终端会话。2.4 第四步用三种方式启动会话日常使用中最常接触的是交互式会话claude进入后你会看到一个命令行对话界面可以连续输入指令它会逐步执行并回显结果。如果你只想执行一个一次性任务不需要留在交互界面可以用非交互模式claude -p 请解释当前目录的代码结构还能通过管道把内容喂给它cat main.py | claude -p 帮我校正这个脚本里的命名第三种是继续上一次会话。中断后重新进入时加--continue参数可以接着刚才的话题继续讨论claude --continue2.5 第五步第一条指令与基本交互第一次对话建议从轻量任务开始比如让它“先看看这个项目里有哪些模块”。它会列出目录结构和关键文件并解释项目用途。这时候你能直观感受到它读取数据的节奏。交互界面里还有一些常用操作按Esc中断当前正在执行的任务用/help查看内置命令用/compact压缩当前对话的上下文用/clear清空会话记录重新开始这些按键和指令会在后面长期使用建议刚上手时就记下来。3. 记忆系统CLAUDE.md就是给AI的工作交接文档3.1 三个层级的记忆存放位置用过一段时间你会发现AI虽然聪明但从零开始理解一个项目还是要消耗大量上下文。所以Claude Code引入了记忆文件机制用一个Markdown文件来告诉它“这个项目是什么、常用的命令是什么、有哪些约束”。这个文件是灵魂配置开局一定要写。记忆文件分三个层级全局记忆存放在~/.claude/CLAUDE.md对所有项目生效适合写个人偏好、通用工作习惯。项目记忆存放在项目根目录下的CLAUDE.md对整个仓库生效写项目说明、技术栈、命令。目录记忆存放在某个子目录下的CLAUDE.md只对这个子目录及以下层级生效适合写模块级说明。项目启动后它会自动加载这些文件作为“先验知识”相当于入职培训资料。你在对话开头完全不用解释“这是个什么项目”AI已经知道了。3.2 一个合格的CLAUDE.md应该长什么样写得太空没有价值写得太长浪费上下文。我提供一个经过多次调整后比较通用的模板# 项目说明 这是一个面向企业客户的订单管理后台提供订单录入、状态流转、报表导出三大核心能力。 ## 技术栈 - 语言Python 3.11 - 框架公司内部Web框架 - 数据库MySQL通过统一DAO层访问 ## 常用命令 - 启动开发服务python dev_server.py - 运行测试pytest --tbshort - 格式化代码black . ## 工程约定 - 业务逻辑统一放在 src/services不要在路由里写业务 - 异常处理统一使用 BizException - 数据库迁移脚本放在 migrations 目录禁止手工改 ## 禁区 - 不要修改 dist 目录下由构建工具生成的产物 - 不要向代码库提交任何包含密钥的文件关键是每一项都要有实际约束力要写那些“如果AI不知道就会犯错”的信息。比如“禁止手工改迁移脚本”这类规则正是AI最容易踩的不成文规定。3.3 记忆文件也要维护和版本控制CLAUDE.md不是写一次就完了。项目演进时命令变了、目录结构调整了都要同步更新。我习惯在每周迭代结束后顺手看一眼把已经过时的描述替换掉。版本控制方面我建议把CLAUDE.md提交进仓库。这样所有协作者共享同一份“AI交接文档”新成员拉取代码后AI也能立刻了解项目。只提醒一点里面千万不要写敏感信息因为它是会被加载进上下文的普通文件不是保险箱。另外要澄清一个误区CLAUDE.md不等于聊天记录。AI不能靠它回忆“上次会话里聊过的某个具体问题”它提供的是稳定的项目背景。真正需要长期保存的决策、结论应该落到文档或代码注释里而不是只放在对话历史中。4. 权限、settings与配置让AI有手脚又有规矩4.1 权限模式决定它能不能乱动Claude Code可以执行任何命令这既是强大之处也是风险点。它默认会为关键操作请求确认比如修改文件、执行shell命令。这个“唠叨”模式刚开始会觉得烦但非常重要。我建议的顺序是头一周先用默认审批模式感受一下它经常提出哪些请求再决定要不要放开。等建立了足够信任再通过配置文件把高频安全操作加入白名单。权限控制通常靠permissions字段完成支持精确匹配和规则匹配。举个例子{ permissions: { allow: [ Bash(npm run test), Bash(black .) ], deny: [ Bash(rm -rf *), Read(.env*) ] } }allow里的命令会自动执行不再询问deny里的则一律拒绝。这种方式比“全部同意”或“全部拒绝”都高效得多。4.2 settings.json的核心字段配置主要通过.claude/settings.json完成分为用户级~/.claude/settings.json和项目级项目根的.claude/settings.json。两者合并生效项目级优先于用户级。我常用的字段有permissions权限规则上面已经举例。hooks自动化钩子下一章重点说。env给会话注入环境变量。model指定希望使用的对话模型控制成本和速度。一个项目级配置示例{ model: claude-code-small, env: { APP_ENV: dev }, permissions: { defaultMode: acceptEdits } }注意配置字段在不同版本会有调整。遇到“某个配置不生效”的情况先检查是否为当前版本不支持的字段再怀疑写法问题。4.3 环境变量与敏感信息保护很多CLI工具都会读取.env文件Claude Code也一样。当它需要访问数据库或外部服务时你可以通过env字段显式传入而不是让它去读配置文件。敏感信息保护是我最看重的一条。在settings.json里我会把.env、密钥目录、证书文件通通加入deny规则{ permissions: { deny: [ Read(.env), Read(**/*.pem), Read(secrets/**) ] } }就算AI在某个任务里触发了读取也会被规则拦下减少敏感信息进入上下文的可能。4.4 多项目配置的继承与覆盖如果同时维护多个项目我通常把个人偏好写在用户级配置把项目特定约束写在项目级配置。用户级里定义“所有项目都适用”的规则项目级里补充只属于该项目的内容。实际运行时会叠加起来。命令行参数优先级最高可以临时覆盖配置里的一些行为。比如某次只想快速执行不想让配置文件里的权限限制挡住就在启动时显式声明。覆盖能力越强越要小心用完最好恢复默认。5. hooks在Claude行动的每个环节插一脚5.1 像Git hooks一样理解它Claude Code的hooks机制可以理解成“生命周期的监听器”。当AI执行到某个关键节点时会自动调用你配置的外部脚本。这属于高级自动化里最有价值、也最容易被低估的部分。先看它提供的几个主要时机事件名称触发时机典型用途UserPromptSubmit用户提交新消息时输入检查、风险提示PreToolUse工具执行前拦截危险命令、补参数PostToolUse工具执行后格式化、校验、清理Stop一轮任务结束时通知、记录、自动提交Notification需要提醒用户时推送消息到手机或桌面SubagentStop子代理结束时汇总子代理结果hooks的配置写在settings.json里每个事件可以配置一个或多个命令。5.2 实际跑通的例子修改代码后自动格式化我最早接触hooks就是为了解决“AI改完代码风格不统一”的问题。每次代码被修改后自动调用格式化工具就不需要事后专门清理。在.claude/settings.json里配置{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: black $CLAUDE_FILE_PATHS } ] } ] } }含义是当AI使用编辑类工具写文件后把被修改的文件路径传给black做格式化。matcher用来限定只对匹配的工具触发避免每次读文件都跑脚本浪费资源。5.3 用hooks做一个任务完成通知当任务跨窗口执行时我可能切到别的终端干别的等它跑完需要主动通知。Stop事件就可以帮上忙。配置如下{ hooks: { Stop: [ { hooks: [ { type: command, command: notify-send \Claude Code\ \任务完成可以回来看结果了\ } ] } ] } }Linux桌面环境用notify-sendmacOS可以换成osascript弹通知。配合长任务使用体验接近“有个同事干完活会喊你一声”。5.4 排查hooks不生效的问题hooks不触发是最常见的问题。我的排查顺序是先确认配置文件的路径对不对项目级应该放在.claude/settings.json不是CLAUDE.md。确认事件名称拼写是否准确官方版本差异会导致事件名不同。单独在终端运行一次hook命令排除脚本本身的语法错误。看日志CLI会在调试输出中打印hooks的执行情况加上全局参数可以打印出更详细的信息。调试过几轮就会发现绝大多数问题出在路径和权限上脚本本身反而很少出幺蛾子。6. 子代理一次会话里多个专岗助手并行6.1 为什么需要独立的子代理当任务变复杂比如“重构模块并补上测试同时做一次安全审查”把所有要求堆给主对话容易让主线任务被细碎问题干扰。子代理subagents就是为此设计的它可以在项目里定义一组带独立职责的专家代理主Claude在需要时按描述自动调用它们。每个子代理有自己的系统提示和职责边界因此它的上下文更干净判断更聚焦。这很像给团队里安排专门做测试、专门做大促活动页的人各管一摊。6.2 用Markdown定义一个代码审查代理子代理的定义放在.claude/agents/目录每个代理对应一个Markdown文件文件名就是代理名称。建一个code-reviewer.md--- name: code-reviewer description: 审查代码变更发现潜在的Bug、安全问题和不规范命名。适合在代码改动之后调用。 tools: Read, Grep, Glob, Bash --- 你是一名严格的代码审查专家。你会从以下维度审查代码变更 - 正确性是否存在边界情况未处理。 - 安全性是否存在注入、敏感信息泄露风险。 - 可读性命名是否清晰函数是否过长。 输出格式 1. 问题清单按严重程度排序。 2. 每条问题给出文件路径和建议改法。 3. 没有问题就明确说“没有发现严重问题”。配置里比较重要的是description主Claude靠它判断什么时候该调用这个子代理。描述写得越精准越能命中场景。6.3 主代理与子代理的协作方式在主对话中我通常这样使用子代理让主Claude完成重构后直接补充“调用code-reviewer检查刚才的改动”。也可以在主任务描述里就点明“完成后运行代码审查”它会在合适的时机自动拉起子代理。子代理结束后主Claude会收到摘要并整合到主流程中。任务被拆成一段段专业工作主线不会变乱。我在几个稍微大些的模块改造中试过子代理模式下的结果比单线程对话更可控问题发现率也更高。需要注意的一点是每个子代理都在消耗上下文和计算资源。一个会话里拉起太多子代理反而会拖慢速度。合理的做法是限制子代理的tools只给它必要的工具减少不必要的尝试。7. MCP为Claude装上接入外部系统的“USB口”7.1 模型上下文协议到底解决了什么MCPModel Context Protocol可以理解为AI与外部数据源、工具之间的标准通信协议。如果说Claude本身是大脑那么MCP就是外接接口让它可以读取公司内部数据库、调用自有API、操作专用工具。没有MCP时AI只能靠命令行和文件系统间接摸到数据有MCP之后它可以直接调用一个标准化的服务接口拿到结构化数据。类比一下过去你要让AI读一份数据库报告得先让它跑sql把结果导出成CSV再读取现在只需要一个MCP数据源服务AI直接查询结果即时可用。7.2 配置一个MCP服务器MCP服务通常在项目根目录的.mcp.json里配置。下面是一个本地数据服务的示例{ mcpServers: { issue-service: { command: node, args: [mcp-servers/issue-service.js], env: { API_BASE: http://localhost:7000 } } } }配置好并重启会话后AI就能看到这个服务暴露的工具列表并在合适的任务中调用。整个过程不需要写复杂的胶水代码服务端遵守MCP规范即可。7.3 一个比较稳妥的接入方向MCP的接入范围非常广文件系统、数据库、消息队列、监控系统都可以接。我的建议是从“只读数据源”开始比如让AI能够查询项目里的Issue列表、读取某个服务的实时监控指标。只读服务风险低又能立刻看到价值。等熟悉协议之后再考虑接入写操作比如通过MCP创建工单、发消息。写操作前最好在服务端做一层权限校验而不是完全信任AI的调用。毕竟再聪明的模型也可能在错误判断下发出一个不该发的写请求。MCP让AI手脚变长但长出来的手脚也需要缰绳。8. 实战复盘让Claude Code重构一个历史遗留模块8.1 任务背景我用一个模拟项目讲述一次比较完整的实战过程。某后台服务里有一个历史订单模块文件结构混乱一个入口文件积累了上千行循环import严重测试覆盖率不到两成。改造目标把这个模块按职责拆成多个小文件保持对外接口不变。8.2 我给出的第一段指令我没有在开始就让它直接动手而是先输入了下面这段话先不要修改任何文件。我需要你分析 src/legacy_order 这个目录 1. 梳理出模块的职责边界哪些逻辑是订单状态流转哪些是计算价格哪些是数据访问。 2. 找出明显的问题点比如重复工具函数、不合理的循环引用。 3. 给出一个迁移计划标注每个步骤的依赖关系。 这份计划我确认之前不要改代码。这个开头非常关键它把“AI当执行者”变成了“AI当参谋”。先产出计划确保方向一致后再动手。8.3 它的执行过程AI读取了目录下所有相关文件生成了结构分析。它指出价格计算逻辑散落在一个大函数里没有独立成模块状态流转依赖隐式字符串常量没有常亮定义。随后给出了三步拆分计划。我确认计划后切换指令按计划的第一步执行拆分价格计算逻辑。保持对外接口不变完成后运行测试并报告结果。紧接着它创建新文件、迁移函数、更新import、搜索旧引用逐一替换然后运行测试。第一次测试有两个用例失败原因是迁移时漏了一个默认参数。AI从报错栈反查到自己改动的逻辑补上了默认值再次运行后全量通过。8.4 中途遇到的几个麻烦第一个麻烦是高危命令被权限拦下。它想执行一个包含清理临时目录的命令被deny规则直接拒绝。解决办法是在allow列表里补充精确到具体目录的命令而不是粗暴地放开整个bash权限。第二个问题是上下文长度在任务中段开始报警。代码搜索和测试输出占据了大量上下文。我用/compact压缩历史并在后续步骤里让它“只输出摘要不要打印完整文件内容”顺利解决了。第三个问题是它差点动了一个不该动的公共函数签名。因为项目CLAUDE.md里写了“公共函数签名如需修改必须单独评审”规则生效它没有强行改只是把这个风险点标注出来交给了人工确认。这让我意识到CLAUDE.md里每一行规则都是给AI的一根边界线。8.5 这个案例给我的判断最终这个拆分任务在半天内完成。如果纯人工处理按我平时速度大概需要两三天起步。最值得肯定的不是它写代码多快而是整个过程从分析、计划、执行到反馈闭环了中间不需要我反复粘贴文件内容。当然也有局限。那些“只可意会”的领域知识比如某个模块为什么设计成那样、哪个历史决策不能动AI无法从代码里自动推断。这些信息必须由人写进CLAUDE.md或者由我在每个阶段显式告知。没有规则的项目里AI会按照通用最佳实践给你方案但未必符合你的实际情况。9. 高频问题排查与我的防呆习惯9.1 最常见的几个问题对照现象可能原因处理方式终端提示命令找不到安装未生效或PATH未更新重开终端确认npm全局目录在PATH中登录后马上退出会话网络无法连接官方服务端点检查本机网络连通情况确认服务可达后再重试AI不停询问权限默认审批模式未配置allow规则在settings.json中补充精确allow项配置文件没生效路径写错或字段名不匹配版本核对官方字段说明和配置路径上下文越用越卡对话历史过长使用/compact或在长任务中要求短输出hook始终不触发事件名或配置文件路径错误单独运行hook命令开启调试模式查看日志输出乱码终端不支持UTF-8切换终端编码为UTF-8重建会话修改前没问就动了代码permissions设置了acceptEdits如果不想这样改回询问模式或限制编辑工具9.2 我的防呆使用基线在给别人的团队做工具引入时我经常分享下面几条习惯都是在实战中沉淀出来而不是看文档得到的改动前先要计划。任何超过一个文件的任务先让它输出计划确认再执行。高频命令精确白名单而不是无脑全部允许。敏感文件永远deny。不管什么任务不给AI读密钥的机会。定期使用清理会话。上下文过载时不硬撑压缩或重建会话都行。版本控制是你的退路。让AI改代码之前确保分支干净出了事用git恢复能力兜底。最后再分享一个小技巧每次启动大任务前我会先输入“这份任务完成后请用一句话汇总改动范围和遗留风险”让它在结尾强制输出一个简短交接总结。这样即使会话断了我也能从最后几行字快速接上状态。这个小习惯省了我很多次翻历史记录的力气比任何复杂配置都管用。 
长河君 · 2026/10/16 12:34:30 · 阅读 1.2k 终端AI编程助手实践手册：从Claude Code到hooks与MCP的完整指南
如果你常年在IDE和网页AI之间来回搬运代码大概率有过一种很拧巴的感觉一边是强大的对话模型一边是真正要维护的工程目录两边中间隔着一层剪贴板。过去我习惯把代码复制给网页AI再把建议半行半行地粘回来遇到稍大的重构就是一场体力劳动。后来我改用终端里的编程助手——Claude Code模式彻底变了它直接在终端里启动能自己读目录、改文件、跑命令、盯测试结果我只需要说“哪里有问题、想改成什么样”。这篇手册把我从入门、配置到高级自动化沉淀下来的完整用法做一个梳理。它不是官方文档的复读而是我这几个月真实跑项目、踩坑之后留下的实践笔记。适合所有想在终端里把AI当“真同事”用的人无论是刚接触CLI的新人还是已经对Agent类工具有一定经验的开发者都能从中找到能直接落地的操作。1. 为什么把AI从浏览器搬进终端1.1 它更接近一个“能干活的人”网页AI解决的是“生成方案”Claude Code解决的是“执行方案”。它运行在本地终端里本质上是一个带着自然语言理解能力的命令行智能体能够串联完成文件读取、代码搜索、命令执行、结果阅读、再次修改这一整条闭环路径。你不需要把问题拆成一系列shell命令只需要用一句人话描述目标它会自己规划步骤。我刚开始使用时最不适应的一点就是它真的会动手改文件。第一次让它“修复一个类型错误”时它先定位到文件再用编辑工具改掉问题点然后运行测试验证整个过程我都没动键盘。这和“复制一段代码去网页里问”是完全不同的协作关系。1.2 最适合哪些场景高频场景我总结下来有这么几类探索历史遗留代码对不熟悉的工程让它解释模块结构、梳理调用链、标注可疑点。批量机械修改统一改命名、补缺失的导出、批量加日志这种工作人做容易漏AI适合兜底。补测试和文档生成单测骨架、补注释、写变更记录只需要喂给它模块入口。修复Bug描述现象让它从错误栈反查代码而不是自己逐文件翻。执行多步骤的工程任务比如“把某个功能从A模块迁移到B模块并保持对外接口不变”。不太适合的场景也有。涉及不可逆的大规模变更最好先让AI只生成计划人工确认后再执行涉及业务上“必须按特定规则”的改动如果规则没有写在文档里AI容易按常识处理翻车概率不低。1.3 和网页对话的差距在哪里我用一张表说明两者差别更直观一些能力网页AIClaude Code读取当前文件需要手动粘贴直接读取搜索整个工程代码不支持支持内容检索和文件遍历执行构建、测试命令只给文本建议可以执行并继续处理输出修改文件需要你手动应用直接落盘并可查看差异连续处理长任务上下文容易断会按步骤推进衔接中间结果感知git状态无能知道当前分支和变更文件选择它并不是说网页AI不再有用而是在“真正要写下代码”的时候终端这个形态天然离工作现场更近。2. 五步上手安装、登录与第一次对话2.1 第一步准备好终端环境Claude Code本质是一个Node命令行应用所以本机需要先有Node运行环境并确保npm命令可用。安装前在终端里确认一下node -v npm -v如果两条命令都能正常输出版本号说明环境就绪。Windows用户建议使用系统自带的现代终端而不是老的命令提示符窗口否则中文输出和快捷键都可能遇到一些小问题。2.2 第二步全局安装官方CLI包通过npm把CLI安装到全局环境命令如下npm install -g anthropic-ai/claude-code安装完成后验证是否成功claude --version能看到版本号就说明装好了。如果提示命令找不到多半是npm全局bin目录没有加入PATH重新打开终端窗口或者检查环境变量配置即可。2.3 第三步登录与授权第一次运行claude命令时它会引导你完成登录认证。这里需要你有一个可用的账号并按终端提示完成浏览器或验证码授权流程。认证通过后凭证会保存在本地配置目录后续使用不需要重复登录。有一点容易忽略这个工具的运行权限是你的身份凭证相当于把你的终端权限交给了AI。因此不要在无法信任的设备上直接登录也不要随意共享终端会话。2.4 第四步用三种方式启动会话日常使用中最常接触的是交互式会话claude进入后你会看到一个命令行对话界面可以连续输入指令它会逐步执行并回显结果。如果你只想执行一个一次性任务不需要留在交互界面可以用非交互模式claude -p 请解释当前目录的代码结构还能通过管道把内容喂给它cat main.py | claude -p 帮我校正这个脚本里的命名第三种是继续上一次会话。中断后重新进入时加--continue参数可以接着刚才的话题继续讨论claude --continue2.5 第五步第一条指令与基本交互第一次对话建议从轻量任务开始比如让它“先看看这个项目里有哪些模块”。它会列出目录结构和关键文件并解释项目用途。这时候你能直观感受到它读取数据的节奏。交互界面里还有一些常用操作按Esc中断当前正在执行的任务用/help查看内置命令用/compact压缩当前对话的上下文用/clear清空会话记录重新开始这些按键和指令会在后面长期使用建议刚上手时就记下来。3. 记忆系统CLAUDE.md就是给AI的工作交接文档3.1 三个层级的记忆存放位置用过一段时间你会发现AI虽然聪明但从零开始理解一个项目还是要消耗大量上下文。所以Claude Code引入了记忆文件机制用一个Markdown文件来告诉它“这个项目是什么、常用的命令是什么、有哪些约束”。这个文件是灵魂配置开局一定要写。记忆文件分三个层级全局记忆存放在~/.claude/CLAUDE.md对所有项目生效适合写个人偏好、通用工作习惯。项目记忆存放在项目根目录下的CLAUDE.md对整个仓库生效写项目说明、技术栈、命令。目录记忆存放在某个子目录下的CLAUDE.md只对这个子目录及以下层级生效适合写模块级说明。项目启动后它会自动加载这些文件作为“先验知识”相当于入职培训资料。你在对话开头完全不用解释“这是个什么项目”AI已经知道了。3.2 一个合格的CLAUDE.md应该长什么样写得太空没有价值写得太长浪费上下文。我提供一个经过多次调整后比较通用的模板# 项目说明 这是一个面向企业客户的订单管理后台提供订单录入、状态流转、报表导出三大核心能力。 ## 技术栈 - 语言Python 3.11 - 框架公司内部Web框架 - 数据库MySQL通过统一DAO层访问 ## 常用命令 - 启动开发服务python dev_server.py - 运行测试pytest --tbshort - 格式化代码black . ## 工程约定 - 业务逻辑统一放在 src/services不要在路由里写业务 - 异常处理统一使用 BizException - 数据库迁移脚本放在 migrations 目录禁止手工改 ## 禁区 - 不要修改 dist 目录下由构建工具生成的产物 - 不要向代码库提交任何包含密钥的文件关键是每一项都要有实际约束力要写那些“如果AI不知道就会犯错”的信息。比如“禁止手工改迁移脚本”这类规则正是AI最容易踩的不成文规定。3.3 记忆文件也要维护和版本控制CLAUDE.md不是写一次就完了。项目演进时命令变了、目录结构调整了都要同步更新。我习惯在每周迭代结束后顺手看一眼把已经过时的描述替换掉。版本控制方面我建议把CLAUDE.md提交进仓库。这样所有协作者共享同一份“AI交接文档”新成员拉取代码后AI也能立刻了解项目。只提醒一点里面千万不要写敏感信息因为它是会被加载进上下文的普通文件不是保险箱。另外要澄清一个误区CLAUDE.md不等于聊天记录。AI不能靠它回忆“上次会话里聊过的某个具体问题”它提供的是稳定的项目背景。真正需要长期保存的决策、结论应该落到文档或代码注释里而不是只放在对话历史中。4. 权限、settings与配置让AI有手脚又有规矩4.1 权限模式决定它能不能乱动Claude Code可以执行任何命令这既是强大之处也是风险点。它默认会为关键操作请求确认比如修改文件、执行shell命令。这个“唠叨”模式刚开始会觉得烦但非常重要。我建议的顺序是头一周先用默认审批模式感受一下它经常提出哪些请求再决定要不要放开。等建立了足够信任再通过配置文件把高频安全操作加入白名单。权限控制通常靠permissions字段完成支持精确匹配和规则匹配。举个例子{ permissions: { allow: [ Bash(npm run test), Bash(black .) ], deny: [ Bash(rm -rf *), Read(.env*) ] } }allow里的命令会自动执行不再询问deny里的则一律拒绝。这种方式比“全部同意”或“全部拒绝”都高效得多。4.2 settings.json的核心字段配置主要通过.claude/settings.json完成分为用户级~/.claude/settings.json和项目级项目根的.claude/settings.json。两者合并生效项目级优先于用户级。我常用的字段有permissions权限规则上面已经举例。hooks自动化钩子下一章重点说。env给会话注入环境变量。model指定希望使用的对话模型控制成本和速度。一个项目级配置示例{ model: claude-code-small, env: { APP_ENV: dev }, permissions: { defaultMode: acceptEdits } }注意配置字段在不同版本会有调整。遇到“某个配置不生效”的情况先检查是否为当前版本不支持的字段再怀疑写法问题。4.3 环境变量与敏感信息保护很多CLI工具都会读取.env文件Claude Code也一样。当它需要访问数据库或外部服务时你可以通过env字段显式传入而不是让它去读配置文件。敏感信息保护是我最看重的一条。在settings.json里我会把.env、密钥目录、证书文件通通加入deny规则{ permissions: { deny: [ Read(.env), Read(**/*.pem), Read(secrets/**) ] } }就算AI在某个任务里触发了读取也会被规则拦下减少敏感信息进入上下文的可能。4.4 多项目配置的继承与覆盖如果同时维护多个项目我通常把个人偏好写在用户级配置把项目特定约束写在项目级配置。用户级里定义“所有项目都适用”的规则项目级里补充只属于该项目的内容。实际运行时会叠加起来。命令行参数优先级最高可以临时覆盖配置里的一些行为。比如某次只想快速执行不想让配置文件里的权限限制挡住就在启动时显式声明。覆盖能力越强越要小心用完最好恢复默认。5. hooks在Claude行动的每个环节插一脚5.1 像Git hooks一样理解它Claude Code的hooks机制可以理解成“生命周期的监听器”。当AI执行到某个关键节点时会自动调用你配置的外部脚本。这属于高级自动化里最有价值、也最容易被低估的部分。先看它提供的几个主要时机事件名称触发时机典型用途UserPromptSubmit用户提交新消息时输入检查、风险提示PreToolUse工具执行前拦截危险命令、补参数PostToolUse工具执行后格式化、校验、清理Stop一轮任务结束时通知、记录、自动提交Notification需要提醒用户时推送消息到手机或桌面SubagentStop子代理结束时汇总子代理结果hooks的配置写在settings.json里每个事件可以配置一个或多个命令。5.2 实际跑通的例子修改代码后自动格式化我最早接触hooks就是为了解决“AI改完代码风格不统一”的问题。每次代码被修改后自动调用格式化工具就不需要事后专门清理。在.claude/settings.json里配置{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: black $CLAUDE_FILE_PATHS } ] } ] } }含义是当AI使用编辑类工具写文件后把被修改的文件路径传给black做格式化。matcher用来限定只对匹配的工具触发避免每次读文件都跑脚本浪费资源。5.3 用hooks做一个任务完成通知当任务跨窗口执行时我可能切到别的终端干别的等它跑完需要主动通知。Stop事件就可以帮上忙。配置如下{ hooks: { Stop: [ { hooks: [ { type: command, command: notify-send \Claude Code\ \任务完成可以回来看结果了\ } ] } ] } }Linux桌面环境用notify-sendmacOS可以换成osascript弹通知。配合长任务使用体验接近“有个同事干完活会喊你一声”。5.4 排查hooks不生效的问题hooks不触发是最常见的问题。我的排查顺序是先确认配置文件的路径对不对项目级应该放在.claude/settings.json不是CLAUDE.md。确认事件名称拼写是否准确官方版本差异会导致事件名不同。单独在终端运行一次hook命令排除脚本本身的语法错误。看日志CLI会在调试输出中打印hooks的执行情况加上全局参数可以打印出更详细的信息。调试过几轮就会发现绝大多数问题出在路径和权限上脚本本身反而很少出幺蛾子。6. 子代理一次会话里多个专岗助手并行6.1 为什么需要独立的子代理当任务变复杂比如“重构模块并补上测试同时做一次安全审查”把所有要求堆给主对话容易让主线任务被细碎问题干扰。子代理subagents就是为此设计的它可以在项目里定义一组带独立职责的专家代理主Claude在需要时按描述自动调用它们。每个子代理有自己的系统提示和职责边界因此它的上下文更干净判断更聚焦。这很像给团队里安排专门做测试、专门做大促活动页的人各管一摊。6.2 用Markdown定义一个代码审查代理子代理的定义放在.claude/agents/目录每个代理对应一个Markdown文件文件名就是代理名称。建一个code-reviewer.md--- name: code-reviewer description: 审查代码变更发现潜在的Bug、安全问题和不规范命名。适合在代码改动之后调用。 tools: Read, Grep, Glob, Bash --- 你是一名严格的代码审查专家。你会从以下维度审查代码变更 - 正确性是否存在边界情况未处理。 - 安全性是否存在注入、敏感信息泄露风险。 - 可读性命名是否清晰函数是否过长。 输出格式 1. 问题清单按严重程度排序。 2. 每条问题给出文件路径和建议改法。 3. 没有问题就明确说“没有发现严重问题”。配置里比较重要的是description主Claude靠它判断什么时候该调用这个子代理。描述写得越精准越能命中场景。6.3 主代理与子代理的协作方式在主对话中我通常这样使用子代理让主Claude完成重构后直接补充“调用code-reviewer检查刚才的改动”。也可以在主任务描述里就点明“完成后运行代码审查”它会在合适的时机自动拉起子代理。子代理结束后主Claude会收到摘要并整合到主流程中。任务被拆成一段段专业工作主线不会变乱。我在几个稍微大些的模块改造中试过子代理模式下的结果比单线程对话更可控问题发现率也更高。需要注意的一点是每个子代理都在消耗上下文和计算资源。一个会话里拉起太多子代理反而会拖慢速度。合理的做法是限制子代理的tools只给它必要的工具减少不必要的尝试。7. MCP为Claude装上接入外部系统的“USB口”7.1 模型上下文协议到底解决了什么MCPModel Context Protocol可以理解为AI与外部数据源、工具之间的标准通信协议。如果说Claude本身是大脑那么MCP就是外接接口让它可以读取公司内部数据库、调用自有API、操作专用工具。没有MCP时AI只能靠命令行和文件系统间接摸到数据有MCP之后它可以直接调用一个标准化的服务接口拿到结构化数据。类比一下过去你要让AI读一份数据库报告得先让它跑sql把结果导出成CSV再读取现在只需要一个MCP数据源服务AI直接查询结果即时可用。7.2 配置一个MCP服务器MCP服务通常在项目根目录的.mcp.json里配置。下面是一个本地数据服务的示例{ mcpServers: { issue-service: { command: node, args: [mcp-servers/issue-service.js], env: { API_BASE: http://localhost:7000 } } } }配置好并重启会话后AI就能看到这个服务暴露的工具列表并在合适的任务中调用。整个过程不需要写复杂的胶水代码服务端遵守MCP规范即可。7.3 一个比较稳妥的接入方向MCP的接入范围非常广文件系统、数据库、消息队列、监控系统都可以接。我的建议是从“只读数据源”开始比如让AI能够查询项目里的Issue列表、读取某个服务的实时监控指标。只读服务风险低又能立刻看到价值。等熟悉协议之后再考虑接入写操作比如通过MCP创建工单、发消息。写操作前最好在服务端做一层权限校验而不是完全信任AI的调用。毕竟再聪明的模型也可能在错误判断下发出一个不该发的写请求。MCP让AI手脚变长但长出来的手脚也需要缰绳。8. 实战复盘让Claude Code重构一个历史遗留模块8.1 任务背景我用一个模拟项目讲述一次比较完整的实战过程。某后台服务里有一个历史订单模块文件结构混乱一个入口文件积累了上千行循环import严重测试覆盖率不到两成。改造目标把这个模块按职责拆成多个小文件保持对外接口不变。8.2 我给出的第一段指令我没有在开始就让它直接动手而是先输入了下面这段话先不要修改任何文件。我需要你分析 src/legacy_order 这个目录 1. 梳理出模块的职责边界哪些逻辑是订单状态流转哪些是计算价格哪些是数据访问。 2. 找出明显的问题点比如重复工具函数、不合理的循环引用。 3. 给出一个迁移计划标注每个步骤的依赖关系。 这份计划我确认之前不要改代码。这个开头非常关键它把“AI当执行者”变成了“AI当参谋”。先产出计划确保方向一致后再动手。8.3 它的执行过程AI读取了目录下所有相关文件生成了结构分析。它指出价格计算逻辑散落在一个大函数里没有独立成模块状态流转依赖隐式字符串常量没有常亮定义。随后给出了三步拆分计划。我确认计划后切换指令按计划的第一步执行拆分价格计算逻辑。保持对外接口不变完成后运行测试并报告结果。紧接着它创建新文件、迁移函数、更新import、搜索旧引用逐一替换然后运行测试。第一次测试有两个用例失败原因是迁移时漏了一个默认参数。AI从报错栈反查到自己改动的逻辑补上了默认值再次运行后全量通过。8.4 中途遇到的几个麻烦第一个麻烦是高危命令被权限拦下。它想执行一个包含清理临时目录的命令被deny规则直接拒绝。解决办法是在allow列表里补充精确到具体目录的命令而不是粗暴地放开整个bash权限。第二个问题是上下文长度在任务中段开始报警。代码搜索和测试输出占据了大量上下文。我用/compact压缩历史并在后续步骤里让它“只输出摘要不要打印完整文件内容”顺利解决了。第三个问题是它差点动了一个不该动的公共函数签名。因为项目CLAUDE.md里写了“公共函数签名如需修改必须单独评审”规则生效它没有强行改只是把这个风险点标注出来交给了人工确认。这让我意识到CLAUDE.md里每一行规则都是给AI的一根边界线。8.5 这个案例给我的判断最终这个拆分任务在半天内完成。如果纯人工处理按我平时速度大概需要两三天起步。最值得肯定的不是它写代码多快而是整个过程从分析、计划、执行到反馈闭环了中间不需要我反复粘贴文件内容。当然也有局限。那些“只可意会”的领域知识比如某个模块为什么设计成那样、哪个历史决策不能动AI无法从代码里自动推断。这些信息必须由人写进CLAUDE.md或者由我在每个阶段显式告知。没有规则的项目里AI会按照通用最佳实践给你方案但未必符合你的实际情况。9. 高频问题排查与我的防呆习惯9.1 最常见的几个问题对照现象可能原因处理方式终端提示命令找不到安装未生效或PATH未更新重开终端确认npm全局目录在PATH中登录后马上退出会话网络无法连接官方服务端点检查本机网络连通情况确认服务可达后再重试AI不停询问权限默认审批模式未配置allow规则在settings.json中补充精确allow项配置文件没生效路径写错或字段名不匹配版本核对官方字段说明和配置路径上下文越用越卡对话历史过长使用/compact或在长任务中要求短输出hook始终不触发事件名或配置文件路径错误单独运行hook命令开启调试模式查看日志输出乱码终端不支持UTF-8切换终端编码为UTF-8重建会话修改前没问就动了代码permissions设置了acceptEdits如果不想这样改回询问模式或限制编辑工具9.2 我的防呆使用基线在给别人的团队做工具引入时我经常分享下面几条习惯都是在实战中沉淀出来而不是看文档得到的改动前先要计划。任何超过一个文件的任务先让它输出计划确认再执行。高频命令精确白名单而不是无脑全部允许。敏感文件永远deny。不管什么任务不给AI读密钥的机会。定期使用清理会话。上下文过载时不硬撑压缩或重建会话都行。版本控制是你的退路。让AI改代码之前确保分支干净出了事用git恢复能力兜底。最后再分享一个小技巧每次启动大任务前我会先输入“这份任务完成后请用一句话汇总改动范围和遗留风险”让它在结尾强制输出一个简短交接总结。这样即使会话断了我也能从最后几行字快速接上状态。这个小习惯省了我很多次翻历史记录的力气比任何复杂配置都管用。