第一个 Claude Code 任务：装好就跑通，一条命令的事

---

我有个小脚本，report.py，每周一跑一次——读一个销售 CSV，算出每个区域的总额，打印到终端。功能也没啥问题，就是每次老板问"能不能导出 JSON"，我都说"下周加上"。

这个"下周"已经持续了三个月。

今天终于决定动手了，但不想自己写。我把这个活了三个月的需求丢给了 Claude Code。

---

第一步：安装（30 秒）

打开终端：

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

装完之后启动：

claude

第一次运行会询问你是否要认证，确认后自动弹出浏览器，登录 Anthropic 账号（Claude Pro/Max 订阅，也可以用 API Key）。认证完成切回终端，就进入 Claude Code 的交互界面了。

如果你用 API 而非订阅，在启动前设好环境变量：

export ANTHROPIC_API_KEY=sk-ant-xxxx

装完确认一下：

$ claude --version
2.1.x

一行命令，一次登录。如果 Node 环境有问题，也可以用 Homebrew：brew install --cask claude-code。npm 方式（npm install -g @anthropic-ai/claude-code）仍然可用，但官方已推荐原生安装脚本。

不管用哪种方式，都别加 sudo。权限问题排查起来很痛苦。后面的安装排障文章会细讲。

---

第二步：让它看懂我的项目

进到项目目录，启动 Claude Code：

cd ~/projects/sales-tools
claude

启动后 Claude Code 做的第一件事是扫描目录：

• Reading project structure...
  - report.py (main script)
  - data/ (CSV files)
  - README.md
  - No CLAUDE.md found, no .claude/ config

它在找 CLAUDE.md 和 .claude/ 配置目录。这是一个空项目，什么都没有。没关系，Claude Code 会直接读代码。

我的 report.py 是这样的——一个标准的单文件脚本：

import csv
import sys
from collections import defaultdict

def load_sales(filepath):
    with open(filepath, 'r') as f:
        return list(csv.DictReader(f))

def summarize(rows):
    regions = defaultdict(float)
    for r in rows:
        regions[r['region']] += float(r['amount'])
    return regions

def main():
    if len(sys.argv) < 2:
        print("Usage: python report.py <csv_file>")
        sys.exit(1)

    filepath = sys.argv[1]
    rows = load_sales(filepath)
    summary = summarize(rows)

    for region, total in summary.items():
        print(f"{region}: ${total:,.2f}")

if __name__ == '__main__':
    main()

---

第三步：把需求丢给它

在 Claude Code 的交互界面里，我输入：

给 report.py 加一个 --json 选项。当传了 --json 时，输出改为 JSON 格式，
长这样：
{
  "regions": [{"name": "East", "total": 12345.67}, ...],
  "total": 98765.43
}

要求：
- 用 argparse 替代现在的 sys.argv 手动解析
- JSON 输出要格式化（indent=2）
- 不影响现有的纯文本输出行为
- 写对应的测试

Claude Code 开始干活。它不是一次性输出所有代码让你复制，而是一步一步来：

• Reading report.py (126 lines)
• Analyzing current argument parsing: manual sys.argv
• Deciding approach: replace sys.argv with argparse, add --json flag

→ Step 1: Rewrite argument parsing with argparse
  [~] report.py — add argparse, parse --json flag

→ Step 2: Add JSON output function
  [+] report.py — json_output() function in summarize block

→ Step 3: Wire up --json flag to output format
  [~] report.py — condition output format on args.json

→ Step 4: Create test file
  [+] test_report.py — test text output, test JSON output,
    test missing arguments, test with sample CSV

→ Running tests:
  $ python -m pytest test_report.py -v
  test_text_output PASSED
  test_json_output PASSED
  test_missing_args PASSED
  test_with_sample_csv PASSED

  4 passed in 0.23s

四个测试全过了，零次失败。然后它在终端里实际跑了一遍：

$ python report.py data/sales_2026_05.csv
East: $45,230.00
West: $32,100.50
North: $28,900.00
South: $19,450.75

$ python report.py data/sales_2026_05.csv --json
{
  "regions": [
    {"name": "East", "total": 45230.00},
    {"name": "West", "total": 32100.50},
    {"name": "North", "total": 28900.00},
    {"name": "South", "total": 19450.75}
  ],
  "total": 125681.25
}

---

第四步：生成 commit

跑通之后，我说：“帮我提交”。

Claude Code 先分析了变更：

$ git diff --stat
 report.py      | 24 +++++++++++++++++---
 test_report.py | 38 ++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 4 deletions(-)

然后生成了 commit message：

feat: add --json output option to report.py

Replace manual sys.argv parsing with argparse. Add --json flag
that outputs region summaries and total as formatted JSON.

Includes test coverage for text output, JSON output, and CLI
error handling.

我扫了一眼，没问题。确认后，Claude Code 执行了 git commit。

一个在我 todo list 里躺了三个月的需求，从打开终端到提交，六分钟。

---

实际生成的代码

最终的 report.py。Claude Code 重构了参数解析，加入 JSON 输出，干净利落：

import csv
import json
import argparse
from collections import defaultdict

def load_sales(filepath):
    with open(filepath, 'r') as f:
        return list(csv.DictReader(f))

def summarize(rows):
    regions = defaultdict(float)
    for r in rows:
        regions[r['region']] += float(r['amount'])
    return regions

def format_text(summary):
    for region, total in summary.items():
        print(f"{region}: ${total:,.2f}")

def format_json(summary):
    regions = [{"name": k, "total": v} for k, v in summary.items()]
    total = sum(v for v in summary.values())
    output = {"regions": regions, "total": round(total, 2)}
    print(json.dumps(output, indent=2))

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('file', help='CSV file to process')
    parser.add_argument('--json', action='store_true',
                        help='Output as JSON')
    args = parser.parse_args()

    rows = load_sales(args.file)
    summary = summarize(rows)

    if args.json:
        format_json(summary)
    else:
        format_text(summary)

if __name__ == '__main__':
    main()

改动点：

• sys.argv 手动解析换成了 argparse
• 文本输出拆成 format_text，JSON 输出抽成 format_json
• --json flag 干净切换输出格式
• 参数缺失时 argparse 自己处理错误提示，不用手写

不是"能用就行"。变量命名（format_text/format_json 对称）、纯函数拆分、argparse 的 help 文本都像一个人认真写过。这就是项目级上下文带来的好处——它看到了代码风格，然后在同一个风格里编程。

---

这个过程中 Claude Code 实际做了什么

整个过程中，Claude Code 用了这些工具：

步骤	用的工具	实际做了什么
了解项目	Grep, Glob, Read	扫描目录树，读取 report.py 源码
理解需求	推理	判断应该用 argparse 重构参数解析，而非简单追加代码
写代码	Edit, Write	改 report.py，新建 test_report.py
跑测试	Bash	python -m pytest，4 个用例一次过
验证	Bash	实际执行脚本，确认 --json 和默认输出都正确
提交	Bash	git diff 看变更 → 生成 commit message → git commit

能读代码、能写、能测、能提交。这不是补全工具，是 Agent。

---

踩到的坑

1. 第一次启动有点慢

Claude Code 启动时会扫描整个目录结构，而且它不受 .gitignore 限制——即使 node_modules 在 .gitignore 里，Grep 和 Glob 照样能扫进去。要排除目录，在项目根目录创建一个 .claudeignore 文件（语法跟 .gitignore 一样），或者在 .claude/settings.json 中配置 ignorePatterns：

{
  "ignorePatterns": ["node_modules", ".venv", "dist", "__pycache__"]
}

2. 别用 sudo 装任何东西

不管是 npm、brew 还是安装脚本，都不要加 sudo。权限乱了排查起来很痛苦。如果 Node 环境报权限错误，用 nvm 或 volta 管理 Node 版本。

3. 让 AI 自己修

如果测试挂了，Claude Code 会把错误输出贴给你，然后自己修。别急着插手——先看它能不能自己修好。很多时候它跑测试→报错→改代码→重跑，整个过程你只需要看着。

---

下一篇

既然 Claude Code 这么顺手，下次我用同样的需求丢给 Codex。看看沙箱执行的体验跟本地执行差别多大。