Claude Code 环境跑通：第一次有效对话

装完 Claude Code 聊了几句，感觉跟网页聊天差不多？先跑通一个小脚本------CSV 空值统计，20 分钟够。

我让他做一个具体任务：「读当前目录下某个 CSV，统计每列空值个数，打印成表格。」

他试了一下。二十分钟后回我：「确实不一样------它直接改了文件，还跑命令。但第一次它把 CSV 路径写死了，我纠正了两轮才跑通。」

这就对了。有效对话 的标准不是聊得开心，是：你描述任务 → Claude Code 产出可运行结果 → 你审核后能放进工作流。

本篇只做一件事：从零到第一次有效对话。成本、proxy、Key 轮转放第 04 篇；Prompt 技巧放第 05 篇。

---

开始前准备什么

项	要求
系统	Windows 10/11、macOS 或 Linux
终端	PowerShell、bash 或 zsh 均可
Git	已安装，会用 clone / commit
Node.js	18+（后面 Lab 和 MCP 会用到，建议现在装好）
API	Anthropic API Key（公司发的或自己的测试 Key）

我不建议在生产项目目录第一次就试。单独建一个练习目录，例如：

mkdir cc-practice && cd cc-practice
git init

---

安装 Claude Code

安装方式以 官方文档 为准。常见路径：

macOS / Linux（npm 全局）：

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

Windows：

同样可以用 npm 全局安装。若 claude 命令找不到，检查 Node 安装路径是否进了 PATH。公司机器有时需要 IT 帮忙加环境变量------别硬扛，先报工单。

配置 API Key：

export ANTHROPIC_API_KEY="sk-ant-..."

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Key 不要 写进代码、不要 commit 到 Git。后面会在 .gitignore 和 CLAUDE.md 里写清楚。

验证能否连通：

cd cc-practice
claude

出现对话界面即安装成功。若报 401 或 authentication error，九成是 Key 没生效------重开终端再 export 一次。

---

第一次有效对话：CSV 空值统计

你要达成的结果

终端运行某个脚本（Python 或 Node 都行），输出类似：

column_name,null_count
user_id,0
email,12
phone,847

你怎么跟 Claude Code 说

别只说「写个脚本」。用稍完整的任务描述（这就是后面第 05 篇 Prompt 的预习）：

在当前目录创建一个脚本 count_nulls.py：
- 读取同目录下的 sample.csv（UTF-8）
- 统计每一列的空值个数（空字符串、纯空格也算空）
- 打印两列：column_name, null_count
- 不要硬编码绝对路径
- 写完告诉我怎么运行

先在目录里放一个最小的 sample.csv：

user_id,email,phone
1,alice@example.com,
2,,13800138000
3,bob@example.com,13900139000

我踩过的坑（你可以少踩一次）

坑 1：Agent 模式一次改太多文件

第一次我让 Claude Code「顺便加单元测试、加 README、加 requirements.txt」，结果目录里冒出五个文件，其中两个 import 路径不对。

修正： 第一次任务只要一个脚本 + 能跑。测试和文档第二轮再说。

坑 2：路径写死

初稿里出现过 path = "C:\\Users\\xxx\\sample.csv"。换台机器就挂。

修正： 明确写「不要硬编码绝对路径」，用相对路径或 pathlib / __dirname。

坑 3：在错误对话里硬修

AI 已经认定 CSV 分隔符是分号，改了两轮还在逗号/分号之间绕。

修正： 开新对话 ，重新 @ sample.csv，第一句话写：「分隔符是逗号，不是分号。」别在污染了的上下文里死磕------这点后面 M4 会专门讲「对话卫生」。

---

对话模式 vs Agent 模式（现在知道个大概就行）

模式	什么时候用
对话	问问题、解释代码、小改动、探索
Agent	明确的多文件任务、要自动跑命令、要改多个地方

第一次练习用 Agent 也可以，但任务描述要小。我的习惯是：探索用对话，「帮我把这个目录下 X 做完」用 Agent，并在描述里写清「只改哪些文件」。

---

必做：.gitignore 和 CLAUDE.md

有效对话跑通后，立刻加两个文件。不是形式主义------是防止第二次就把 .env 提交上去。

.gitignore：

.env
*.pem
credentials/
secrets/
__pycache__/
node_modules/

CLAUDE.md（项目根）：

## 项目说明
Claude Code 练习项目，用于《AI 协作研发手记》实验。

## 安全约定
- 禁止读取或上传：.env、credentials/、secrets/
- 生成 SQL 默认只读；写操作必须人工确认
- 不得将本仓库代码粘贴到 Claude Code 以外的公网服务

## 编码约定
- Python 3.10+
- 脚本使用相对路径
- 改动前先说明要改哪些文件

Claude Code 启动时会读 CLAUDE.md。团队项目里，这个文件走 Git PR 合并，别各写各的------第 22 篇会展开。

初始化并提交：

git add .
git commit -m "chore: init practice project with CLAUDE.md"

---

环境检查清单（自己勾）

复制下面清单，装完一项勾一项：

• claude --version 有输出
• ANTHROPIC_API_KEY 已设置（echo $env:ANTHROPIC_API_KEY 非空，PowerShell）
• 练习目录已 git init
• CSV 脚本本地运行成功
• .gitignore 含 .env
• CLAUDE.md 含安全约定
• 知道 API 401 时先查 Key 而非重装
• 知道「任务太大 → 拆小」和「上下文乱了 → 重开对话」

八项全勾，M2 环境这一关算过。

---

小结

1. 有效对话 = 可运行产出 + 你审核过，不是聊得久。
2. 第一次任务选小脚本，别一上来全栈。
3. 立刻加 .gitignore 和 CLAUDE.md，比事后补救省事。
4. 出错时：小错续聊；假设错了重开；改乱文件 git checkout。

---

下一篇

第 04 篇《环境踩坑：proxy、Key 轮转、成本与配额》 ------ 公司内网、团队共享 Key、Token 怎么省，以及 CLAUDE.md 安全约定在团队里怎么落地。

如果你环境已经稳了，可以并行开始读 第 05 篇 Prompt 基本功；但 proxy 和配额的问题，迟早会碰到，别跳过 04。

---