Claude Code使用心得：怎么让AI帮你写复杂项目SmartInspector从0到89个commit，Claud

Claude Code使用心得：怎么让AI帮你写复杂项目

SmartInspector 从 0 到 89 个 commit，47 个 Python 文件、6800 行代码。其中 Claude Code 承担了大约 70% 的编码工作。

但不是所有环节都适合交给 AI。本文复盘哪些地方 AI 帮了大忙，哪些地方是我在给 AI 擦屁股。

一个前提：你要对项目的架构有清晰认知

很多人觉得用 AI 写代码就是"告诉它我要什么，它给我生成"。这对小脚本管用，对复杂项目不行。

SmartInspector 在动手之前，我先花了两天画架构图、写技术方案。4 层改造方案（采集层、Agent 编排层、SDK 层、基础设施层），每个模块的输入输出、接口定义、错误处理策略都写清楚了。

这些文档后来成了给 Claude Code 的 prompt 上下文。事实证明，架构越清晰，AI 的输出质量越高。

Claude Code 有一个 CLAUDE.md 文件机制——项目根目录放一个，每次对话自动加载。我的 CLAUDE.md 里写了项目结构、编码规范、测试命令、已知的坑。这样它每次启动都知道自己在哪里、该遵守什么规则。

适合交给 AI 的场景

1. 新模块从零搭建

SmartInspector 的工具层（grep/glob/read）是从头写的。Claude Code 对标 Claude Code 的工具设计，实现了类似的功能：

# 一个典型的 Claude Code 任务描述：
# "参考 /path/to/claude-code-source 中的 search.py，
#  实现一个 GlobTool，支持 glob 模式、.gitignore 排除、
#  按修改时间排序，返回相对路径"

一次对话就生成了完整的实现 + 测试。后来这个模块又迭代了 8 次（Issue #4 的优化），每次都是给 CC 一个具体的优化点，它自己改代码、跑测试、提交 commit。

为什么适合：模块边界清晰，输入输出明确，参考实现存在。AI 在这种"有参照物的实现"场景下表现极好。

2. 重复性的模式化代码

比如 Agent 的定义。SmartInspector 有 4 个 Agent（collector、analyzer、attributor、reporter），它们的骨架代码高度相似——初始化 LLM、定义 prompt、处理 state 输入输出。

写第一个 Agent 的时候我手写的，后面 3 个直接让 Claude Code "参照 collector agent 的结构，实现 analyzer agent"。结构一致，prompt 不同，一次搞定。

3. 测试用例生成

89 个 commit 里，大约有 15 个是纯测试。这类工作非常适合 AI：

给它一个函数签名和预期行为
它生成 5-10 个测试用例，覆盖正常路径、边界条件、异常输入
跑一下 pytest，失败的让它自己修

测试通过率大概在 85% 左右。剩下 15% 通常是 AI 对项目上下文理解不够（比如不知道某个函数在别的地方被 mock 了）。

不适合交给 AI 的场景

1. 跨模块的状态依赖问题

SmartInspector 有一个 Bug：WebSocket 采集的 block events 数据，在 collector 合并 SQL 查询结果时被覆盖了。

# collector.py 第 79 行
# Bug：直接赋值覆盖了 WS 传来的 events
self.events = query_result['events']  # ← 应该是合并

这个问题跨越了 WebSocket 层 → Collector 层 → 数据流三个模块。Claude Code 能看到代码，但它不理解运行时的数据流向——WS 什么时候发数据、collector 什么时候接收、合并应该怎么处理。

我给 CC 描述了 3 次，它改了 3 次，都没修对。最后我自己花了 20 分钟定位并修复。

教训：涉及运行时状态、时序、多模块交互的 Bug，AI 很难搞定。它擅长的是"给定明确的输入输出，实现逻辑"，而不是"理解一个复杂的运行时系统然后找到隐含的问题"。

2. 需求变更后的架构调整

项目中期，我把意图路由从"固定关键词匹配"改成了"LLM few-shot 分类"。这意味着 Agent 的调度方式变了，State 的结构要调整，prompt 要重写。

这种涉及全局架构的变更，AI 会倾向于在局部修改，而不是从全局视角重新设计。结果就是改了一堆地方，但整体结构变得不一致。

最后还是我自己画了新的数据流图，然后让 CC 按图施工。

3. 和硬件/系统强相关的调试

Perfetto Trace 的采集涉及 adb 命令、trace 文件格式、SQL 查询语法。这些知识 Claude Code 的训练数据里有，但不够精确。

比如一个 SQL 语法问题：

-- Perfetto TraceProcessor 报错：
-- syntax error at MODE() WITHIN GROUP
-- 因为 TraceProcessor 用的 SQLite 版本不支持窗口函数

这种特定版本的兼容性问题，AI 无法从代码本身推断出来，只能通过实际运行才能发现。

Prompt 怎么写效果最好

原则 1：给参照物，不给抽象描述

❌ "实现一个 glob 搜索工具"

✅ "参考 /path/to/claude-code/src/search.ts 中的 glob 实现，用 Python 重新实现。使用 pathlib.glob，排除 .gitignore 中的路径，返回相对路径"

有具体参照物时，AI 的输出质量和你的预期差距最小。

原则 2：一次只改一个模块

❌ "优化工具层的性能和可靠性"

✅ "给 GlobTool 添加 .gitignore 排除功能。要求：读取项目根目录的 .gitignore 文件，用 pathspec 库匹配，在 glob 结果中过滤掉匹配的路径"

一个明确的指令 > 一个模糊的愿景。Claude Code 在处理单点任务时成功率超过 90%，但如果你让它"全面优化"，它会到处改一通，改好改坏混在一起。

原则 3：让它自己验证

# 每个任务描述的末尾加上：
# "修改完成后运行 python3 -m pytest tests/ -v，
#  如果有测试失败，修复后重新运行，直到全部通过再 commit"

这能帮你省掉大量"AI 改了代码但引入了新 Bug"的问题。当然前提是项目有足够的测试覆盖。

原则 4：保持上下文连贯

Claude Code 的 --continue 参数可以延续上一次对话。对于迭代开发，这比每次重新描述上下文高效得多。

Issue #4 的 10 个优化点，我就是用 --continue 让 CC 在一次长对话里逐个完成的。它记住了自己之前的修改，后面的优化不会和前面的冲突。

一个真实的工作流

SmartInspector 的 Issue #4（工具层优化）是个好例子，展示了一个完整的 AI 辅助开发流程：

1. 我写 Issue，列出 10 个优化点和具体的修改方案（约 2000 字）
2. 启动 Claude Code，让它读 Issue
3. CC 逐个实施优化：
   - 读代码 → 理解现状
   - 实施修改
   - 运行测试
   - 通过 → commit，不通过 → 修复 → 再测 → commit
4. 大约 40 分钟后，9 个 commit，24 个测试全部通过
5. 我 review 代码，push 到远程

从写 Issue 到代码合入，不到 1 小时。如果纯手写，估计需要 3-4 小时。

成本和效率

SmartInspector 项目中，Claude Code 的使用成本：

指标	数值
总对话次数	~30 次
平均每次对话时长	15-40 分钟
成功率（一次通过）	~75%
需要手动修复的比例	~25%
估计节省时间	60-70%

Token 成本方面，使用 Claude Sonnet，一次典型的优化对话大约消耗 50-100K tokens。对于 API 定价来说，一天跑几次完全在可接受范围内。

几条实用建议

先写文档再写代码。把架构、接口、数据流写清楚，AI 按文档施工比自己从零推理效果好得多。
CLAUDE.md 是你的项目说明书。项目结构、编码规范、测试命令、已知问题，全写进去。每次对话自动加载，省去大量重复描述。
测试先行。有测试，AI 才能自己验证修改是否正确。没有测试的项目，AI 改了什么你都不确定。
小步提交。让 AI 每完成一个小改动就 commit。这样即使后面的修改出问题，也能快速回退到上一个已知状态。
学会读 AI 的代码。AI 写的代码不一定是你习惯的风格，但它通常是正确的。不要因为"看着不顺眼"就重写，先跑测试，通过了再考虑风格问题。
知道什么时候该收回控制权。当 AI 连续两次都没搞定一个问题，手动处理通常更快。

写在最后

Claude Code 不是万能的。它不会帮你做架构决策，不会帮你排查复杂的运行时 Bug，不会理解你的业务上下文。

但它是一个极其高效的代码工人——给它明确的指令和清晰的上下文，它能稳定地产出高质量代码。把重复性、模式化的编码工作交给它，把精力放在架构设计和问题诊断上，这才是 AI 辅助开发的正确姿势。

SmartInspector 的 89 个 commit 里，AI 写了大约 70% 的代码。但剩下的 30%——架构设计、Bug 排查、需求决策——才是决定项目质量的关键。

下一篇预告：用 AI 重构代码的正确姿势 —— SmartInspector 的 4 层改造方案是怎么落地的