最近总有读者问我AI 编程工具到底选哪个能不能直接在真实项目里帮我改代码以前我一般推荐在 IDE 里装个 AI 插件后来实际用下来发现真正能把“读代码、改代码、跑命令、提提交”串成完整工作流的还得是 Claude Code 这类终端 Agent。这篇文章不打算只给你看 demo而是把安装、配置、核心概念、实战项目、常见报错、最佳实践完整过一遍。零基础读者按顺序操作大约 10-15 分钟就能完成第一次真实开发任务有经验的朋友可以直接跳到第四节看实战或跳到第七节查报错。本文会用到 Node.js、终端命令、少量 Python 示例代码所有命令都可以直接复制。文章默认你用的是 macOS 或 LinuxWindows 用户建议配合 WSL 2 或 Git Bash 使用整体步骤一致。1. Claude Code 是什么为什么值得学1.1 从终端进入的编程 AgentClaude Code 是 Anthropic 推出的一款运行在终端里的 AI 编程 Agent。简单理解它不是给你一个聊天窗口而是直接在你的项目目录中启动一个 AI“队友”这个队友可以读取项目文件、分析代码结构、修改代码、执行命令、跑测试、查日志、提交 Git。传统 AI 编程插件的使用方式通常是你复制代码到对话框AI 给出修改建议你再手动粘贴回去。Claude Code 的工作方式则是你告诉它“这个模块有 bug帮我定位并修复”它会自己打开文件、阅读上下文、修改代码然后运行命令验证结果。整个流程里AI 不再只是一个“建议生成器”而是一个能执行任务的 Agent。这种交互方式的核心价值在于AI 能通过终端看到你项目的真实状态而不是只看到你愿意复制给它的那一段代码。对于项目规模大、依赖关系复杂的工程来说这个区别非常关键。1.2 常见应用场景结合我在实际项目中的使用经验Claude Code 最适合处理以下几类场景快速原型一句话生成一个脚本、一个工具类、一个 API 接口。老项目改造接手别人代码时让 AI 先梳理项目结构、整理模块职责。写单元测试自动分析函数功能并生成测试用例。修复 bug给出错误日志让 AI 定位 root cause 并修复。Git 辅助生成 commit message、检查 diff、解决合并冲突。重构把大文件拆分、提取公共方法、消除重复代码。文档生成从源码自动生成 README、接口文档。我并不是说所有场景都能完全自动化但至少有一半的重复性劳动可以交给它而你需要做的是审核和决策。1.3 已经 2026 年了为什么还要专门学一次AI 编程工具淘汰速度很快但底层的 Agent 工作流已经被验证是有效的。Claude Code 代表了终端 Agent 这个方向的成熟形态有权限管理、有上下文压缩、有工具调用协议、有会话恢复能力。你现在花时间学它其实是在学一套 Agent 开发与使用的方法论而不是只学一个命令行工具。文章后续会出现的 Agent、Harness、Skill 这些词近两年在 AI 工程社区里越来越常见。它们不是包装出来的新概念而是把 AI 从“问答工具”推向“可执行系统”过程中必须理解的关键部分。2. 环境准备与安装2.1 安装前需要准备什么Claude Code 本质上是一个 Node.js 命令行程序所以环境准备比较轻量。你需要准备一个可以正常联网的终端。Node.js 18 或更高版本建议使用 LTS 版本。npm、yarn 或 pnpm 中的任意一个包管理器。Git用于项目版本管理和部分 Agent 操作。一个 Anthropic 账号通常通过 Claude 登录或使用 API Key。不同操作系统的注意事项macOS自带终端直接使用即可。Linux需要确保 npm 全局安装目录在 PATH 中。Windows建议安装 WSL 2然后在 WSL 里使用直接在 PowerShell 中也可以但某些权限弹窗和路径处理逻辑会有差异。先检查 Node.js 是否安装成功node -v npm -v如果终端提示找不到node说明 Node.js 没装好建议先去官网下载 LTS 版本或者用 nvm 管理版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端再执行node -v。2.2 安装 Claude Code安装方式有两种任选其一即可。方式一npm 全局安装适合大多数开发者。npm install -g anthropic-ai/claude-code安装完成后查看版本号验证是否成功claude --version如果提示command not found说明 npm 的全局安装目录没有加入 PATH。可以执行下面的命令查看全局安装路径npm config get prefix然后把这个目录下的bin目录加入 PATH。比如路径是/usr/local那么编辑 shell 配置文件export PATH/usr/local/bin:$PATH方式二官方安装脚本适合不想手动管理 npm 全局包的情况。curl -fsSL https://claude.ai/install.sh | bash脚本会自动安装并配置好环境变量。这种方式在有网络限制的环境下有可能失败如果遇到问题可以检查脚本输出也可以回到方式一。2.3 登录并完成首次启动安装完成之后在任意项目目录下输入claude第一次启动会进入登录引导。终端会生成一个登录链接自动在浏览器中打开或者在需要时手动复制到浏览器中访问。完成账号授权后终端会自动进入交互模式。如果没有自动弹出浏览器也可以手动执行登录命令claude /login如果你的使用方式是通过 API Key可以在启动前设置环境变量export ANTHROPIC_API_KEY你的API密钥 claude这里需要注意API Key 属于敏感信息不要直接写在项目代码或 shell 历史中建议使用.env文件或系统的密钥管理工具。2.4 在 VSCode 中配置 Claude Code很多读者习惯在 VSCode 里开发这里给出常见配置方式。方式一直接在 VSCode 内置终端中使用。打开 VSCode按Ctrl ~打开终端进入项目目录后输入claude即可。这种方式最稳定不依赖额外插件。方式二安装官方 Claude Code 扩展。在 VSCode 扩展市场搜索 “Claude Code”安装后左侧会出现对应面板可以查看会话历史、配置文件、权限规则等。不同版本的扩展名称可能略有差异安装时认准官方发布者即可。方式三设置 VSCode 默认终端。如果你习惯在某个特定 shell 中操作可以通过Ctrl Shift P搜索 “Terminal: Select Default Profile”选择 WSL、Git Bash 或 PowerShell。配置完成之后还需要注意权限模式。Claude Code 在执行工具调用时会询问你是否允许。这些授权记录可以放在项目根目录的.claude/settings.json中也可以使用 allowlist 和 denylist 规则。这部分我们放到最佳实践章节展开。3. 核心概念拆解Agent、Harness、Skill从标题和相关讨论中可以看到Claude Code 经常和 Agent、Harness、Skill 这些词同时出现。这些概念并不难但很多入门教程没有讲清楚导致大家看完还是一头雾水。下面我逐一拆解。3.1 Agent能感知并执行任务的智能体Agent智能体是当前 AI 应用的核心形态。和普通 ChatGPT 式对话不同Agent 不只是“生成文本”而是具备一定自主性的系统它能看到环境状态选择合适的工具执行动作并观察结果来调整下一步。在 Claude Code 中Agent 指的是那个由大模型驱动、能在你的终端里执行编程任务的“主体”。它具备以下能力读取项目文件、搜索代码片段。编辑文件并保留你的原始格式。执行终端命令比如安装依赖、运行测试。根据报错信息修改代码。主动检查代码改动是否符合要求。换句话说Claude Code 就是一个“有手有脚”的编程 Agent。你负责描述目标它负责拆解步骤并执行。3.2 HarnessAgent 的工程框架Harness 直译是“马具、套件”在 Agent 工程领域它指的是承载 Agent 运行的那一套工程框架。听起来抽象换个说法Agent 是一辆跑车Harness 就是它的底盘、方向盘、仪表盘和安全带。具体来说Harness 负责管理模型调用循环思考、行动、观察、再思考。工具注册与调用协议。上下文窗口的管理和压缩。权限控制与用户授权流程。会话状态、历史记录、日志。与外部系统的连接配置。Claude Code 本身可以被理解为一套面向编程场景的 Agent Harness。它规定了模型如何调用 Bash、Read、Write、Edit 等工具也规定了哪些动作必须经过用户确认哪些动作可以自动执行。社区里常见的 “DeepSeek Harness”、“Codex Harness” 等说法其实也是类似逻辑把不同模型接入到一套可执行的 Agent 框架中让模型能够操作真实环境。理解 Harness 后你会发现不同工具的差异点更多在于可扩展能力和权限模型而不只是“模型强不强”。3.3 Skill给 Agent 预置的专项技能Skill 可以理解为“技能包”。一个 Skill 通常是目录 指令文件的集合里面描述了某个专业任务的执行步骤、注意事项和示例。举个例子你可以写一个 “Code Review Skill”告诉 Agent审查代码时先看 diff再检查安全风险最后给出修改建议也可以写一个 “SQL 优化 Skill”让 Agent 在遇到慢查询时按索引、执行计划、数据分布的顺序排查。使用 Skill 的价值在于你不用在每次对话里重复输入一堆规范要求只要告诉 Agent 调用某个技能它就会自动加载对应的行为模式。对于团队来说这相当于把代码规范沉淀成了可执行的 Agent 行为标准。3.4 Harness 和 Agent 的区别一句话记住不少读者在评论区问过一个问题harness 和 agent 到底有什么区别我习惯用一句话总结Agent 是“执行任务的角色”Harness 是“让角色稳定发挥的舞台和规则”。 Agent 负责思考与决策Harness 负责让思考能安全、可控地转变成真实操作。实际使用 Claude Code 时你不需要写 Harness 代码但理解这个层次能帮你更好地配置权限、排查问题和设计团队规范。4. 基础使用跑通第一个实战任务4.1 启动与界面说明进入任意项目目录输入claude启动后你会看到交互式命令行界面。在这里你可以输入自然语言指令也可以输入以/开头的斜杠命令。常见斜杠命令如下命令作用/help查看帮助信息/status查看当前会话状态、上下文占用/config查看和修改 Claude Code 配置/model查看或切换模型/compact压缩当前会话上下文/clear清空会话历史开启新对话/cost查看会话 token 消耗/doctor健康检查排查安装和环境配置问题不同版本支持的命令略有差异遇到无法识别的情况可以用/help查看当前版本的实际命令列表。4.2 第一个任务用一句话生成文件处理脚本我们先用一个最简单的需求来体验完整流程写一个 Python 脚本把当前目录下的所有.log文件压缩成.tar.gz。启动claude后输入帮我写一个 Python 脚本把当前目录下所有 .log 文件打包成 logs_日期.tar.gz同时打印每个文件的大小。Claude Code 通常不会直接只丢代码给你而是会先分析需求然后创建或修改文件最后告诉你如何运行。你可以在提示词中强调“帮我创建脚本文件”这样它就会直接写入文件。如果它打算执行命令会在终端询问是否允许。你看到命令内容没问题输入y确认即可。也可以要求它进入允许列表这样后续相同命令不再询问。执行完成后查看项目目录通常会多出一个.py文件。我们手动检查一下ls -la4.3 让 Agent 修改现有代码Claude Code 的一个核心体验是能直接修改项目文件而不是给你一段代码让你自己粘贴。继续刚才的场景我们可以让 Agent 给脚本增加一个功能给刚才生成的脚本增加参数解析支持 --output 指定输出文件名--keep 保留原始 .log 文件默认压缩后删除原始文件。它会读懂现有代码然后修改对应部分。完成后我们可以要求它展示 diff用 git diff 展示这次改动了哪些内容。如果项目还没有初始化 Git可以让 Agent 先执行git init或者你手动执行git init git add . git diff --cached这里建议始终保持一个习惯无论 AI 改了多少代码最终都要通过 diff 亲眼确认一遍。AI 的代码并不天生安全你的审查才是安全保障。4.4 理解权限询问机制用过几次之后你会发现Claude Code 在执行一些敏感操作前会停下来问你比如执行删除文件命令。全局修改文件。安装第三方依赖。读取环境变量。这是 Harness 层权限控制的典型表现。你可以通过配置文件设置哪些操作允许直接执行哪些必须先询问。常见配置文件路径是用户级配置~/.claude/settings.json项目级配置项目根目录/.claude/settings.json示例配置{ permissions: { allow: [ Bash(npm test), Bash(python *.py) ], deny: [ Bash(rm -rf *) ] } }需要注意的是权限配置应当遵循最小授权原则。不要为了省事把所有操作都设为自动允许尤其是删除、覆盖、推送远端这类高风险操作。5. 实战进阶多文件项目、Git 协作与任务拆分这一节我们用一个真实的小项目串联几个关键能力创建多文件项目、写测试、让 Agent 自动执行命令、生成提交信息。5.1 实战目标做一个待办事项 CLI 工具我们计划用 Python 实现一个命令行待办事项工具支持以下命令python todo.py add 写周报 python todo.py list python todo.py done 1 python todo.py delete 1数据存储在本地todos.json文件中。先创建项目目录mkdir todo-cli cd todo-cli启动 Claude Codeclaude给它一条完整的需求描述在当前目录创建 todo-cli 项目。用 Python 实现一个命令行待办事项工具 1. add 内容 添加待办 2. list 列出所有待办未完成显示 [ ]已完成显示 [x] 3. done 编号 将指定待办标记为完成 4. delete 编号 删除指定待办 数据存储在 todos.json 中首次使用时自动创建文件。 添加、删除、完成操作都打印一行简洁的确认信息。 用面向函数的方式组织代码不要使用类。Claude Code 可能会直接生成todo.py文件。我们可以再让它补充一个测试文件为 todo.py 编写使用 pytest 的测试文件覆盖 add、list、done、delete 四种操作使用 tmp_path 临时目录保存测试数据。测试文件的代码思路如下这是常见的生成结果可以验证运行# 文件路径todo-cli/test_todo.py import json import pytest import todo def test_add(tmp_path, monkeypatch): data_file tmp_path / todos.json monkeypatch.setattr(todo, DATA_FILE, str(data_file)) todo.add(测试任务) data json.loads(data_file.read_text(encodingutf-8)) assert len(data) 1 assert data[0][content] 测试任务 assert data[0][done] is False如果你的项目还没有安装 pytest需要先执行pip install pytest然后运行测试python -m pytest test_todo.py -v5.2 让 Agent 执行测试并修复问题直接让 Claude Code 运行测试运行 pytest如果测试失败分析失败原因并修复代码。它会先执行命令看到失败结果后继续阅读代码、定位问题、修改实现再运行测试直到通过。这里体现的正是 Agent 和普通聊天工具的区别它能看到命令输出并根据输出决定下一步操作。整个过程是循环的思考 - 行动 - 观察 - 再思考。5.3 生成 Git 提交信息项目开发到一定阶段后需要提交代码。可以让 Claude Code 辅助生成提交信息git add -A然后回到 Claude Code 交互界面输入查看当前暂存区的 diff结合改动内容生成一份简洁的 Git 提交信息并直接帮我执行 commit。它通常会先展示建议的 commit message再执行提交。我们确认没有问题后允许即可。如果项目还没有初始化仓库可以先让它执行git init需要注意提交前建议检查一下是否包含敏感信息特别是.env、密钥文件、本地数据库文件等。可以在项目根目录添加.gitignore__pycache__/ *.pyc .env todos.json5.4 大任务拆分与会话管理一个常见误区是让 Claude Code 在一个会话里完成一个完整的大型项目。实际体验中超长上下文的会话效果会越来越差而且出问题后不容易定位。我建议把大任务拆成多个阶段例如第一个会话让 Agent 分析项目需求输出模块划分创建项目骨架。第二个会话实现核心功能模块。第三个会话补充测试和文档。第四个会话代码审查和性能优化。每个阶段结束时可以使用/compact压缩上下文或者直接/clear开启一个新会话。这样能有效避免上下文过载导致的“失忆”和错误操作。6. 接入第三方模型与自定义网关6.1 为什么需要第三方模型接入有些团队或读者没有直接使用官方 API 的额度或者希望通过内部网关统一管理模型调用也有社区开发者会把 Claude Code 指向 DeepSeek、通义、Kimi 等模型服务提供商。通过 Harness 的灵活性Claude Code 可以配置为请求自定义的 API 地址。这种做法带来的价值是你仍然可以使用 Claude Code 的 Agent 工作流、权限模型和终端交互体验但底层的模型由不同服务商提供有助于成本控制或满足特定的合规要求。6.2 通过环境变量配置接口地址不同版本的 Claude Code 对环境变量名称的支持略有差异。比较常见的做法是设置接口地址、密钥和模型名。以下是一个示例export ANTHROPIC_BASE_URLhttps://你的网关地址 export ANTHROPIC_AUTH_TOKEN你的网关Token export ANTHROPIC_MODELdeepseek-chat claude如果你的网关使用的是官方 API Key 格式也可以兼容设置为ANTHROPIC_API_KEY。这里有一个重要提醒由于 Claude Code 版本迭代很快不同版本会对应不同的模型列表和协议要求。在修改这些环境变量之前建议先查阅你所用版本与网关服务商的兼容性说明不要照抄网上的过时配置。6.3 常见模型名报错很多读者在接入第三方模型时遇到类似下面的报错deepseek-v4-pro is not a model this version of claude code recognizes.遇到这个提示意思是当前版本的 Claude Code 无法识别你配置的模型名称。可能的原因有两种你配置的模型名在第三方服务商中不存在或名称拼写有误。当前 Claude Code 版本的内置模型列表没有包含该名称需要检查网关映射或使用别名配置。解决思路如下在 Claude Code 中执行/model查看当前可以识别的模型列表。到网关服务商后台确认正确的模型 ID 和可用状态。检查环境变量中是否多了空格、引号等隐藏字符。如果网关支持“映射模式”把未知模型名映射到实际可用的模型 ID。确认 Claude Code 和网关服务商的协议版本兼容。不建议为了强行接入而随意修改模型名那样容易出现响应格式不兼容、工具调用识别失败等问题。6.4 接入第三方模型时的合规建议无论是直接使用官方接口还是接入第三方网关都要注意以下几点不要把 API Key 提交到 Git 仓库。确认服务商的调用协议和数据存储位置符合公司合规要求。生产环境变更接口地址前先在测试环境验证。对接入链路的日志做脱敏处理日志中不应出现完整密钥。7. 常见问题排查与高频命令速查7.1 常见问题处理问题现象常见原因解决思路安装后提示claude: command not foundnpm 全局安装目录不在 PATH 中执行npm config get prefix将 bin 目录加入 PATH首次登录页面无法打开浏览器弹窗被拦截或网络异常手动复制终端中的链接到浏览器或执行claude /login重新登录运行任务时网络超时网络不稳定、接口地址不通、网关响应慢检查网络确认ANTHROPIC_BASE_URL是否可达看到 “the agent execution provider did not respond in time”模型服务或网关响应超时缩小单次任务范围检查模型服务状态必要时切换模型或网关看到 “is not a model this version of claude code recognizes”模型名配置错误或版本不兼容执行/model查看列表修正模型 ID检查网关映射修改的文件不符合预期提示词不够具体Agent 没有 read 上下文明确要求先阅读相关文件再修改给出约束条件和验收标准上下文越长回答越差会话中积累了过多历史使用/compact压缩上下文或/clear开启新会话命令被拒绝执行权限配置限制了操作检查权限配置文件规范 allow 列表依赖版本冲突全局安装和项目安装混用使用npm ls -g anthropic-ai/claude-code检查全局版本7.2 高频命令速查非交互式模式claude -p 给这句话写一段单元测试继续上一次会话claude -c恢复指定会话claude --resume查看版本和健康状态claude --version claude /doctor启动后直接进入设置claude /config这些命令在实际工作中使用频率很高建议收藏备用。8. 最佳实践与工程建议8.1 先读后改给出明确的验收标准和 Agent 协作时最容易出问题的地方是提示词太含糊。建议采用“先读后改”的协作模式要求 Agent 在动手前先输出计划。例如可以这样写在修改代码之前先阅读 src/ 目录下所有相关文件输出你的理解和修改计划等我确认后再动手。这样一方面避免盲目修改另一方面也方便你检查 Agent 是否真正理解了代码上下文。8.2 维护 CLAUDE.md 项目记忆文件Claude Code 支持在项目根目录添加CLAUDE.md文件用来记录项目约定、目录结构、常见命令和注意事项。每次启动会话时Agent 会自动读取这份文件。一个示例# 项目约定 - 后端框架Python FastAPI - 包管理使用 uv - 测试命令uv run pytest - 数据库连接信息统一放在 .env不要硬编码 - 新接口必须补充 OpenAPI 文档注释团队项目中这份文件建议由熟悉项目的人维护并纳入代码评审流程。它能把团队规范直接注入到 Agent 的行为中减少重复说明。8.3 保持小步提交和代码审查习惯Claude Code 虽然能自动完成很多操作但它毕竟不是人无法理解业务上下文中的隐性要求。每次自动修改后都要审查 diff确认没有引入意料之外的行为。建议保持以下流程先在分支上工作避免直接修改主干。使用git diff查看每次改动。对自动化修改的代码做一次和同事 review 同等的检查。高风险操作删除数据、改表结构、推送远端要设置“必须询问”权限。8.4 权限最小化与敏感信息保护在settings.json中做权限配置时要遵循最小授权原则。合理的配置不是“允许所有命令”而是按需开放运行测试可以允许。安装依赖建议询问。删除文件必须询问。执行rm -rf默认拒绝。环境变量和密钥不应该出现在提示词中也不要写入会被 Git 追踪的文件。在提交代码之前用git status检查暂存内容。8.5 控制成本与上下文质量Claude Code 的 token 消耗速度比普通聊天要快因为它会频繁读取文件、执行命令、观察输出。如果不加控制一个复杂任务可能消耗大量 token。实用建议使用/cost定期查看消耗。尽量让一次会话聚焦一个任务。不需要的全部历史用/clear清掉。对大型仓库先用 Glob 或 Grep 定位相关文件而不是让 Agent 读全部源码。8.6 把重复流程沉淀为 Skill如果团队经常做同类任务比如“新增一个 CRUD 接口”“编写 Dockerfile”“做一次安全扫描”可以沉淀为 Skill 文件。这样新成员不需要反复描述流程Agent 也能稳定输出符合团队规范的结果。Skill 的核心是“标准化流程”明确输入和输出。固定执行步骤。列出必须检查的事项。提供示例和反例。对于团队来说这是一种把个人经验转化为组织资产的方式。9. 最后想说的跑通 Claude Code 的安装和基础使用真的不难。真正决定它能发挥多大价值的是你是否愿意改变原来“复制代码-粘贴-拿答案”的工作习惯改成“描述目标-审查执行-验证结果”的 Agent 协作模式。建议你今晚就找一个脚本小任务让 Claude Code 帮你生成、测试、提交完整走一遍。刚开始可以刻意限制它的权限每一步都观察它在做什么。用不了几次你就会形成自己的高效工作流。如果这篇文章对你有帮助可以先收藏备用。后续我再针对 Skill 编写、Harness 扩展、复杂项目实战分别展开欢迎保持关注。