Claude Code 实战教程：用自然语言编写一个简单项目

快下班的时候，我在终端里敲下 /init，开启了 Claude Code 的新项目会话。三分钟后，我盯着屏幕上的代码，后背有点发凉。

我给了它一句话：“帮我写一个命令行工具，可以扫描当前目录下所有 Markdown 文件，提取标题层级，生成一个可跳转的文档索引页面。”

Claude Code 先向我抛了三四个澄清问题，要不要支持嵌套目录？索引页要不要样式？链接是用相对路径还是绝对路径？然后直接规划了目录结构，生成了主程序、递归扫描逻辑、Markdown 解析器、HTML 模板，甚至写了个简单的 CSS。

我看了一眼生成的代码，逻辑比我手写还清晰，注释恰到好处，边界情况处理得比我考虑得还周到。我突然意识到，这不是简单的代码补全，不是那种你写一半、AI帮忙续下一行的工具，这是你把需求讲清楚，它从头到尾帮你把事情干完的东西。

这就是我在这篇文章里想和你聊的核心：Claude Code 不是一个工具，它是一种新的工作方式。而学会这种工作方式，关键不在技术，在思维。

你以为你在写代码，其实你该“谈需求”

大多数人在试用 Claude Code 的时候，脑子里还是那套“手写代码”的习惯，想着怎么用 Python 写循环，怎么处理文件读写，怎么把字符串切割成数组。

但我踩了几次坑之后发现，这套思维在用 Claude Code 的时候反而是累赘。

去年十月我接了一个小活，给一家律所做文档自动化：把合同模板里的占位符自动替换成真实数据，生成最终合约。我本能地开始想数据结构，怎么设计字段映射，写多少行代码去处理不同格式的占位符。然后我意识到，我完全可以用 Claude Code 试试换种方式工作。

我把需求描述得像在和同事开会一样：“我有一个 Excel 表格，里面是客户信息字段；我还有一个 docx 的合同模板，里面用 {{字段名}} 标记占位符。帮我写一个程序读取 Excel、匹配模板里的占位符、替换后生成新的合同文件，保存到指定输出目录。”

Claude Code 直接回复了它的理解，然后着手生成代码结构。它自己会考虑依赖库，它选了 openpyxl 读 Excel、python-docx 处理 Word 文档，然后完整地给出了整个工具的主流程，包括异常处理和操作日志输出。

整个过程我做的，是把脑子里模糊的需求翻译成自然语言指令，而不是把自然语言指令翻译成代码。这个区别看起来很小，但它是使用 Claude Code 的“分水岭”。

核心结论就是一句话：Claude Code 最高效的用法，不是让你写得更快，而是让你从“写代码”这个层级解放出来，站到更高的地方，思考需求本身。

一个真实“翻车”案例：需求说得越细，代码越差

但我也踩过一个巨大的坑，这个坑几乎让我差点放弃工具。

第一次用 Claude Code 写一个小型的 CMS 管理系统时，我用了“程序员的思维”去描述需求。我告诉它：“在后端的 /api/articles 路由下加一个 GET 接口，查询 MongoDB 里 articles 集合，用 mongoose 的 .find() 方法，支持分页参数 page 和 limit，响应格式是 { code, data, msg } 这种标准结构。”

我觉得我描述得很精确、很专业、无可挑剔。

结果生成出来的代码有三四十行，写得没什么大毛病，但把我的参数校验逻辑放错了地方，而且没有考虑 page 超出范围的情况。更诡异的是，它为了匹配我描述的“标准结构”，生成了一个死板的封装函数，连错误码都是硬编码的。

后来我复盘这个问题，发现症结在于：我写的是实现细节，没有写业务需求。

当我说“用 mongoose 的 .find()”的时候，我限定了它的实现路径，但没告诉它边界条件、业务状态和信息模型。Claude Code 只能在我给定的技术限定内完成任务，而在那个限定里，它没有业务上下文。

我重新开了一个会话，换了一种方式描述：“我需要一个文章列表接口，用户可以传入页码和每页条数。列表的字段包括标题、作者、创建时间、摘要。如果页码超过实际页数，返回空列表而不是报错。”

这回 Claude Code 做的第一件事不是写代码，而是向我确认：从哪个模型拿数据？字段映射是怎样的？是不是还要包含总数？

我这时候才反应过来，一个好用的 AI 编程助手，不是让你把伪代码变成真代码。它是让你把 意图 讲清楚，它自己处理实现。

这是我被实践证明过的判断：过于技术化的需求描述，反而是你对 Claude Code 限制最大的负担。你写得越像人话，它写得越好。

关键认知转变：别再当“编码员”，开始当“需求工程师”

这个转变不是听一节课就能完成的。它必须在你真实地用了一段时间、经历了“怎么总是生成垃圾代码”的挫败之后，才会慢慢发生。

我自己大概过了三周左右，才开始下意识地用“需求描述”的思维去和 Claude Code 对话。现在的日常模式是这样的：

我甚至养成了一个习惯：在打开 Claude Code 之前，先用自然语言写一份需求文档。这份文档不是给 AI 看的，是帮我自己理清思路的。 从痛点是什么、到用户想达成什么结果、再到可能的异常情况，写完后，我几乎不需要再加任何技术术语，直接把这段话喂给 Claude Code，出来的代码质量远高于我直接写技术指令时的产出。

这不是猜测，是我反复对比验证过的体验。

用一个简单的实战案例来走一遍全流程

接下来用一个真实的小项目把上面的思路串起来。我会尽量少贴代码，因为我觉得你读代码已经读够了，我写的是我是怎么和 AI 协作的。

项目目标： 写一个 CLI 小工具，输入一个 GitHub 仓库地址，自动生成 README 项目概况，包括仓库信息、技术栈、目录结构说明、最近更新记录和贡献者头像。

第一步：需求澄清，让 AI 跟你“开会”

我在终端里敲下了这句话：

> “帮我写一个命令行工具，用户输入一个 GitHub 仓库的完整地址，工具读取 API 获取基本信息、技术栈判断、目录结构、最近 5 条 commit 信息和贡献者信息，并在当前目录生成一个结构完整的 README_OVERVIEW.md。如果用户没有配置 GitHub Token，提示用户需要 TOKEN 才能访问 API。”

Claude Code 的回复不是代码，是一串澄清：

• 技术栈的判断规则是什么，按文件后缀占比？还是检测 package.json/requirements.txt/go.mod 这类配置？
• commit 信息是展示 hash + message 还是只展示 message？
• 贡献者头像图片是否要下载到本地，还是直接引用 URL？
• 需要生成中文还是英文的 README？

你看，这个过程就是一场微型的软件设计讨论。AI 在问我一些我本来可能没有想清楚的问题。我把它的问题回答了之后，代码才出来。

第二步：看它“做设计”，而不是只看它写的代码

接下来的两三分钟里，它规划了整个工具的代码结构。它生成了 main.ts、fetchRepo.ts、analyzeStack.ts、generateDoc.ts、types.ts 和一个模板文件。它自己定义清楚了模块之间的职责和接口。

我没有关心它到底用的 axios 还是 node-fetch，我只检查了依赖、确认了生成的 README 模板是否符合预期。

第三步，也是最关键的一步：验收。

我用一个实际的仓库地址跑了一遍，发现生成的 README 里“最近更新”的内容是按时间倒序排列的，格式全对；但贡献者头像 URL 在用默认尺寸时，生成的 Markdown 图片长得太大了，影响阅读体验。

我告诉它：“贡献者头像太大了，在 Markdown 里加上控制宽度的 HTML 属性，缩小到 40px 左右。”

Claude Code 自己理解了需求，不是去改图片 URL，而是在 generateDoc.ts 里把头像那一块的 Markdown 改成了 HTML <img> 标签，并添加了 width="40" 属性。它知道 Markdown 默认不支持图片尺寸控制，所以自动切换到了 HTML 解决方案，这种场景理解能力，是我认为 Claude Code 区别于一般的代码补全工具最本质的地方。

整个过程从我启动会话到生成可用的工具，不超过 30 分钟。相同功能，让我手写，至少一个下午。

协作中你必须建立的新“编程规范”

用了 Claude Code 半年之后，我发现日常工作中要加一些新规范。这些规范不是代码规范，而是协作规范。

1. 一条指令只做一个完整的功能模块。 不要在一句话里让它同时写后端接口、数据库操作和前端组件。拆开，一个个来。
2. 每个功能模块结束，让它自己总结改了什么。 我的习惯是加一句“总结一下这次你做了哪些改动”，这能帮我确认它的理解对不对，也让后续会话有清晰的上下文。
3. 代码生成后，必须先跑一遍测试加代码审查。 AI 会写出能运行的代码，但不一定是最优的方案。它有时候会引入不必要的依赖，或者过度抽取抽象层。保持审查习惯，是对代码质量的底线保障。
4. 对于安全敏感的操作，显式设置规避要求。 比如涉及密码处理、Token 存储、用户隐私数据时的硬编码风险，必须在指令里说清楚“不要硬编码任何密钥，从环境变量读取”。

这些不是官方文档告诉我的，是我在好几个实际项目里试着用、试着犯错之后总结出来的东西。

但它不是万能的，什么时候你要自己上

用了一年多，我很清楚 Claude Code 的短板在哪。这些地方我绝不会放给它自己处理：

• 核心架构决策。 你不能指望它帮你判断是用微服务还是单体架构、用 SQL 还是 NoSQL。它能实现你决定的方案，但决策层的东西要你自己想，这是你不可被替代的部分。
• 跨多个业务域的复杂逻辑耦合。 当业务规则重叠、需要权衡时，AI 倾向于生成“两端不靠”的妥协方案，而妥协方案通常是技术上正确、但业务上没用的。
• 从零到一的全新功能设计。 这里的“设计”不是 UI，而是，用户在什么场景下用、触发什么流程、看到什么反馈。这部分没有固定模式，需要产品判断，仅靠需求描述很难让 AI 做出高质量方案。

我个人的经验法则是这样的：当我自己还没想清楚一个功能“为什么要这么做”的时候，连需求描述都写不清晰，那 Claude Code 也没办法出手。 反之，一旦我把业务逻辑画清楚了，它可以替代我大部分的底层编码工作。

你接下来可以做的三件事

如果你看到这里，应该已经明白，Claude Code 的价值不在于“多快能写完”，而在于你让自己去处理更贵的事情，设计、判断、权衡、沟通。

如果你决定试试，这是我给你的建议行动路径：

第一步，先用一个你熟悉的、但低价值的小需求开始。 比如写一个文件批量重命名工具、或者做一个简单的数据分析脚本。目的是练习“写需求”的节奏，而不是挑战高难度项目。

第二步，集中精力改变你的提问题方式。 把技术指令降下来，把业务需求升上去。花三天时间做这个刻意练习，你会突然体会到那种“顺畅感”。

第三步，盘点你自己的日常工作里，哪些拉低效率的重复编码值得交给 Claude Code。 把时间空出来，去做那些只有你能做的决策、设计和沟通工作。

工具一直都在变，但有一个东西是确定的：未来最稀缺的开发者，不是写得最快的，而是最清楚“要做什么”和“为什么做”的那个人。Claude Code 能帮你写代码，但它更需要的是一个能想清楚需求的你。