Claude Code 上手指南：在终端里让 AI 帮你写项目

Claude Code 是 Anthropic 推出的命令行编程助手。它运行在你的终端里，能读取项目文件、修改代码、执行命令，像一个坐在你旁边的程序员。本文从安装讲起，最后带你用它做一个命令行待办工具。

一、Claude Code 是什么

和网页版聊天不同，Claude Code 直接工作在你的项目目录里：

能看代码：它会自己搜索、读取项目中的文件，不需要你手动复制粘贴。
能改代码：直接编辑或新建文件，修改前会展示改动内容。
能跑命令：运行测试、安装依赖、执行 git 等，并根据输出继续调整。
听你指挥：涉及修改文件和执行命令的操作，默认会先征求你的同意。

它适合做的事情包括：给现有项目加功能、修 bug、解释陌生代码库、写测试、重构、写脚本等。

二、安装与登录

方式一：官方安装脚本（推荐）

macOS、Linux（以及 Windows 的 WSL）下，在终端执行：

curl -fsSL https://claude.ai/install.sh | bash

这种 native 安装方式不依赖 Node.js，并且会自动更新。

方式二：通过 npm 安装

如果你已经装好了 Node.js，也可以用 npm 全局安装：

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

注意不要用 sudo npm install -g，容易引起权限问题。如果提示权限不足，建议改用官方安装脚本，或调整 npm 的全局安装目录。

安装完成后，检查是否成功：

claude --version
claude --help

三、第一次使用：进入项目、生成 CLAUDE.md

进入你的项目目录，然后运行 claude：

cd ~/projects/my-app
claude

第一次在某个目录启动时，它会询问你是否信任这个文件夹。确认后就进入交互界面，直接用中文打字提问即可，例如：

这个项目是做什么的？主要的目录结构是怎样的？

用 /init 生成 CLAUDE.md

在会话里输入 /init，Claude 会分析项目，并在根目录生成一个 CLAUDE.md 文件。这个文件相当于项目的“说明书”，每次启动会话时都会自动读入，内容通常包括：

项目简介和技术栈；
常用命令（如何安装、构建、测试）；
代码风格和约定。

你可以手动编辑它，补充团队约定，比如：

# 项目约定
- 使用 Python 3.11，依赖用 uv 管理
- 运行测试：uv run pytest
- 所有函数都要写类型注解
- 提交信息用中文，格式：类型: 简述

提示CLAUDE.md 建议提交到 git，团队成员共享同一套约定。写得越具体，Claude 越少“自作主张”。

其他启动方式

claude "解释一下 src/main.py 的作用"   # 带着第一个问题启动
claude -c                              # 继续当前目录最近一次对话
claude -r                              # 从历史会话中挑选一个恢复
claude -p "列出所有 TODO 注释"          # 非交互模式，输出结果后退出

四、常用命令、快捷键与权限机制

斜杠命令

在输入框里输入 / 会弹出命令列表。最常用的几个：

命令	作用
`/help`	查看帮助和可用命令
`/init`	分析项目并生成 CLAUDE.md
`/clear`	清空当前对话，开始新任务
`/compact`	把之前的对话压缩成摘要，释放上下文空间
`/model`	切换使用的模型
`/resume`	恢复之前的会话
`/permissions`	查看和管理权限规则

/clear 和 /compact 的区别：前者彻底忘掉之前的对话，后者保留要点。换一个不相关的任务时用 /clear；同一个任务聊得很长时用 /compact。

Shift+Tab：切换工作模式

按 Shift+Tab 可以在几种模式之间循环切换，当前模式会显示在输入框下方：

默认模式：修改文件、执行命令前都会询问你。
自动接受编辑：文件修改不再逐个确认，适合你已经信任它的方案时使用。
计划模式（Plan Mode）：Claude 只读代码、做分析，给出实施计划，但不会改任何文件。你确认计划后它才开始动手。

也可以在启动时直接指定：

claude --permission-mode plan

提示不同版本中可切换的模式可能略有差异，以界面底部的提示为准。复杂任务强烈建议先进计划模式。

Esc：随时打断

发现 Claude 方向不对时，按 Esc 立即中断它当前的操作，然后直接告诉它该怎么改。不用等它做完再返工。

权限确认

当 Claude 要编辑文件或执行 shell 命令时，会弹出确认提示，一般有这几种选择：允许这一次、在本项目中以后都允许同类操作、拒绝（并可以告诉它你想怎么做）。

注意命令行参数 --dangerously-skip-permissions 会跳过所有权限检查，官方建议只在无法访问外网的隔离沙箱中使用。日常开发不要开。对于 rm、git push、改数据库这类操作，务必看清楚再点允许。

五、实战：做一个命令行待办工具

下面用 Python 做一个极简的待办清单工具 todo，演示完整流程。你也可以换成自己熟悉的语言。

建目录、初始化 git

mkdir todo-cli && cd todo-cli
git init
claude

按 Shift+Tab 切到计划模式，把需求说清楚

我想用 Python 写一个命令行待办工具，只用标准库。需求：
1. python todo.py add "买牛奶" 添加任务
2. python todo.py list 列出所有任务，显示编号和是否完成
3. python todo.py done 2 标记第 2 条完成
4. python todo.py remove 2 删除第 2 条
数据保存在当前目录的 todos.json。编号不存在时给出友好提示。
先给我一个实现计划，包括文件结构和测试方案，不要写代码。
审阅计划：看它打算怎么组织代码、怎么测试。有不同意见就直接提，例如：

测试用 unittest，不要引入 pytest。JSON 读写单独放一个函数，方便测试时替换文件路径。
确认后开始实现：退出计划模式，让它按计划写代码。每次要创建文件时会请求确认，你可以看一眼再允许。
让它自己验证

运行测试，再实际执行一遍 add、list、done、remove 这几个命令，确认输出正常。

如果测试失败，它会读报错信息并自己修改，直到通过。
提交代码

帮我检查一下改动，然后用一句简洁的提交信息 git commit。
继续迭代：一次只加一个功能。

给任务加一个可选的截止日期：add "交报告" --due 2026-10-01，list 时过期的任务标红。先读一下现有代码，说说你打算怎么改。

做完之后，你可以再运行一次 /init，让它把项目的用法和测试命令写进 CLAUDE.md，下次打开时它就知道怎么跑测试了。

六、用好 Claude Code 的几个习惯

1. 小步提交 git

每完成一个可用的小功能就 commit 一次。AI 改错了，git diff 一看就清楚，git checkout 或 git restore 就能回退。不要让它一口气改几十个文件后再检查。

2. 需求写清楚

对比两种说法：

模糊：“优化一下登录功能”
清楚：“登录失败时现在只返回 500，改成：密码错误返回 401 和提示文字，用户不存在也返回 401（不要暴露用户是否存在）。改完补上对应的测试。”

说明现状、期望结果、约束条件、如何验证，效果会好很多。

3. 先读代码，再动手

在已有项目里改东西时，先让它理解相关代码：

先阅读 src/auth/ 目录，理解现在的登录流程，讲给我听。暂时不要修改任何文件。

确认它理解正确后再让它改，能避免“另起炉灶”或破坏已有逻辑。

4. 给它验证手段

告诉它怎么跑测试、怎么启动项目、预期输出是什么。能自己验证的 AI，产出质量明显更高。

5. 及时清理上下文

一个任务做完就 /clear 再开始下一个。对话越长，无关信息越多，它越容易跑偏。

注意AI 写的代码仍然需要你审查，尤其是涉及安全、数据删除、付费接口调用的部分。把它当成能干但需要 review 的同事，而不是免检的黑盒。