Claude Code 不只是一个生成代码的聊天工具。要把它用于 Python 项目，关键在于掌握一套可检查、可回退的工作流：完成安装后先让它理解项目，再用计划模式拆解任务，审查代码差异，最后通过测试和日志定位问题。
这篇文章以一个小型 Python 项目为例，梳理使用 Claude Code 时最值得掌握的几个环节。示例命令可以直接改造成你自己的项目流程。
从一个可验证的 Python 项目开始
让 AI 修改代码之前，项目最好已经具备最小的可运行入口和测试。这样每次修改都有明确反馈，避免只凭肉眼判断结果是否正确。
下面创建一个简单的字符串统计模块。假设当前目录名为 word-counter：
mkdir -p word-counter/tests
cd word-counter
python -m venv .venv
source .venv/bin/activate
cat > counter.py <<'PY'
def count_words(text: str) -> int:
"""Return the number of whitespace-separated words."""
return len(text.split())
PY
cat > tests/test_counter.py <<'PY'
from counter import count_words
def test_count_words_ignores_repeated_whitespace():
assert count_words("Claude Code Python") == 3
def test_count_words_returns_zero_for_empty_text():
assert count_words("") == 0
PY
python -m pytest
如果环境中尚未安装 pytest，可以运行：
python -m pip install pytest
这个例子故意保持简单。真实项目中可以把运行方式、测试命令、配置文件位置和已知限制告诉 Claude Code，使它在后续操作中少做假设。
计划模式适合处理什么任务
当需求包含多个文件、边界条件或测试要求时，可以先让 Claude Code 只制定方案。一个可实践的提示如下：
请先阅读当前 Python 项目的目录结构、README 和现有测试。
目标：为 count_words 增加按标点分隔的处理，并补充边界条件测试。
请进入计划模式，只输出：
1. 需要修改的文件
2. 每个文件的修改原因
3. 需要新增或调整的测试
4. 可能的兼容性风险
暂时不要编辑文件。
计划模式的价值不在于计划本身写得多长，而在于把“要改什么”与“为什么改”提前暴露出来。审查计划时，可以重点确认：
- 是否准确找到了真正的入口文件，而不是只修改了示例代码。
- 是否包含现有测试，而不是只增加一条理想路径测试。
- 是否考虑空字符串、连续空格、换行和标点等边界输入。
- 是否会改变已有调用方依赖的返回值或异常行为。
如果方案范围合理，再让 Claude Code 执行修改。对于一个很小的变更，也可以明确要求它先说明计划，再等待确认。
Diff 审查比“看起来能用”更可靠
AI 修改完成后，不要直接接受结果。先查看工作区状态和差异：
git status --short
git diff -- counter.py tests/test_counter.py
可以把审查要求直接交给 Claude Code：
请审查当前工作区的 git diff。
重点检查：
- 是否修改了与需求无关的文件
- 是否引入了不必要的依赖
- 是否改变了公开函数的行为
- 测试是否覆盖正常输入和边界输入
请按“问题、影响、建议”列出发现，不要直接修复。
审查时要把关注点放在行为上，而不只是代码风格。比如，某个实现可能通过了基本测试，却错误地把带连字符的词拆开，或者把标点当成独立单词。Diff 能帮助你确认改动范围，测试则帮助你确认运行结果，两者缺一不可。
用测试和复现步骤调试 Python
调试时，模糊地说“这段代码有 bug”通常不如提供一个稳定复现。可以使用下面的提示结构：
请调试当前 Python 项目中的 count_words。
复现输入："hello,world"
期望结果：2
当前结果：1
请先解释可能的原因，再提出最小修改方案。
要求：
- 不要删除现有测试
- 为这个 bug 增加回归测试
- 修改后运行 pytest
- 最后总结实际修改的文件和测试结果
如果 Claude Code 给出多个可能原因，可以要求它逐一验证，而不是一次性大改：
请先添加一个能够稳定复现该问题的测试，然后只做必要修改。
完成后运行：python -m pytest -q
如果测试失败，请保留失败输出并继续分析，不要绕过测试。
一种可改造的修复实现如下。这里的标点集合只是示例，实际项目应根据产品规则决定哪些字符算作分隔符：
import re
def count_words(text: str) -> int:
"""Count non-empty tokens separated by whitespace or punctuation."""
tokens = re.split(r"[\s,.;:!?]+", text.strip())
return sum(bool(token) for token in tokens)
改动后至少执行：
python -m pytest -q
python -m compileall -q .
pytest 用来验证行为，compileall 可以快速发现语法错误。它们不能替代代码审查，也不能证明所有业务场景都正确，但能构成一个很小而有效的反馈闭环。
一份可复用的检查清单
使用 Claude Code 编写或调试 Python 时，可以在提交前检查以下内容：
- 已确认 Claude Code 能访问正确的项目目录。
- 复杂任务先经过计划模式，修改范围得到确认。
- 已查看
git diff，没有无关文件或意外格式化。 - 新行为有对应测试，bug 有回归测试。
- 测试、静态检查或编译检查都实际运行过。
- 对依赖、异常行为、输入边界和安全影响做过人工判断。
- 没有因为测试暂时失败就删除测试或放宽断言。
Claude Code 可以加快阅读、修改和定位问题的速度，但最终质量仍取决于输入是否可复现、改动是否可审查、结果是否经过验证。把“计划、Diff、测试”固定成习惯，比单纯追求一次生成正确代码更稳健。