【claude code实践】使用 Claude Code 创建项目：从空目录到第一个可运行应用

使用 Claude Code 创建项目：从空目录到第一个可运行应用

引言：为什么现在需要理解它

在日常的日常开发中，我们常常面临一个“冷启动”的痛点：当你想要验证一个新想法、学习一个新框架，或者快速搭建一个微服务时，你通常需要经历一系列繁琐的初始化步骤。这包括创建目录、初始化 Git、配置 package.json 或 requirements.txt、配置 Linter、编写基础的样板代码（Boilerplate），最后才是编写核心业务逻辑。

尽管市场上已经存在诸如脚手架工具（CLI）、IDE 代码片段以及各类网页端 AI 聊天助手，但开发者的核心工作流依然是碎片化的：在浏览器中向 AI 提问、复制代码、切换到编辑器粘贴、在终端中运行调试、发现报错、再复制报错返回浏览器。

Anthropic 推出的 Claude Code（一种基于命令行的 AI 开发者工具）尝试打破这种碎片化。理解 Claude Code 的意义，不仅在于它能帮我们少打几行命令，更在于它展示了一种新的开发范式——将 AI 能力直接内嵌于终端，使其具备理解本地项目上下文、执行系统命令、读写文件并自主进行调试的能力。本文将从一个“空目录”的创建开始，带你深入理解 Claude Code 的本质与工作方式。

一、Claude Code 是什么

一句话定义： Claude Code 是一个直接运行在本地终端（Terminal）的命令行 AI 盲盒/Agent 工具，它允许开发者通过自然语言交互，直接对本地代码库进行分析、编辑、测试和命令执行。

从本质上讲，它不是一个简单的代码补全插件（如 GitHub Copilot），也不是一个独立的网页聊天窗口（如 ChatGPT Web）。

• 它不是什么： 它不是一个全自动的“无人工厂”。你不能指望给它一句话，它就能无瑕地交付一个百万级并发的电商系统。它依然需要开发者的引导、审查和控制。
• 与传统 AI 助手的区别： 传统的 Web AI 助手是“被动接受文本”的，它对你的本地文件系统、环境变量、依赖包状态一无所知。而 Claude Code 是一个具备工具调用能力（Tool Use/Function Calling）的 Agent。它可以“亲手”去读写你本地的文件，并在你的授权下运行测试命令，根据错误日志自行修正代码。

二、从空目录开始理解它

为什么我们要强调“从空目录开始”？因为空目录是观察一个 AI Agent 行为逻辑的绝佳实验场。在一个成熟的、拥有数万行代码的项目中，AI 的行为往往受到既有上下文的极强约束；而在一个空目录里，它必须凭空建立起项目的骨架。

在这个场景下，终端成为了人机协同的唯一入口。传统开发中，终端是“死”的，它只接受确定性的 Shell 命令（如 mkdir, npm init）。但在 Claude Code 介入后，终端变成了“活”的会话界面。

当你站在一个空目录面前，你向 Claude Code 下达指令，它面临的第一个任务不是写代码，而是“决策”。它需要判断应该使用什么技术栈、需要创建哪些基础设施文件。通过在终端实时观察它的每一步操作（创建文件、写入内容、执行初始化安装），开发者能够最直观地理解 AI 是如何将一个模糊的自然语言目标，拆解为具体的研发步骤的。

三、它解决了什么问题

在传统的项目从零到一的开发流中，开发者面临着多处效率断层。Claude Code 主要在以下三个维度重构了工作流：

1. 消除“上下文切换”的认知损耗

• 传统痛点： 开发者在 IDE、终端、浏览器搜索、AI 网页端之间频繁切换。这种“复制-粘贴-运行-报错-再复制”的循环占用了大量精力。
• 如何介入： Claude Code 将“环境”与“大脑”合二为一。它在终端中既是执行者，也是思考者。
• 改变了什么： 开发者只需留在终端，通过对话指挥 AI 读写文件、运行命令，减少了中断思考的次数。
• 限制： 对于复杂的图形界面（UI）调试或重度依赖视觉反馈的调整，纯终端交互仍不够直观。

2. 自动化结构化的样板配置

• 传统痛点： 初始化项目时，配置 TypeScript、Babel、Docker、Webpack 或各种环境变量通常是重复且乏味的，且容易因版本不兼容而踩坑。
• 如何介入： 识别意图后，AI 可以直接调用系统工具创建标准配置文件，并自动通过包管理器（如 npm, pip）安装正确版本的依赖。
• 改变了什么： 将“配置环境”的时间缩短至几秒钟，使开发者能直接跳入核心业务逻辑。
• 限制： 如果遇到极度小众或企业内部私有的脚手架，AI 在没有外部文档的情况下可能会生成错误的配置。

3. 闭环的“执行-报错-修正”调优流

• 传统痛点： 写完初始代码后，运行报错。开发者需要自己看堆栈信息，思考原因，再去修改。
• 如何介入： Claude Code 拥有运行本地命令的权限。当它生成完代码后，可以直接执行 npm run test 或 python main.py。如果控制台报错，它会捕捉该报错，并作为新的输入自动进行代码修复。
• 改变了什么： 形成了一个局部的自动化闭环，AI 自己编写、自己验证、自己修 Bug。
• 限制： 如果测试命令陷入死循环，或者报错信息涉及复杂的外部网络依赖，AI 可能会反复尝试并消耗大量的 Token 成本。

四、它的基本工作方式

Claude Code 的核心运行机制基于 ReAct（Reasoning and Acting） 架构。它不仅仅是在单向地“生成文本”，而是在进行“思考 -> 行动 -> 观察”的循环。

[用户输入: 创建一个 API 导入导出功能]
       │
       ▼
┌────────────────────────────────────────┐
│               1. 思考 (Reasoning)       │
│  "我需要创建哪些文件？使用什么路由？"   │
└────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────┐
│               2. 行动 (Acting)          │
│  调用工具: write_file("server.js")     │
└────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────┐
│               3. 观察 (Observing)       │
│  系统反馈: 文件写入成功 / 编译错误      │
└────────────────────────────────────────┘
       │
       ▲（循环直到任务完成）
       │
[向用户交付可运行的应用]

1. 上下文构建（Context Engineering）

当你在某个目录下启动 Claude Code 时，它首先会扫描当前目录的结构（文件列表、package.json 等），将其作为基础上下文。在空目录场景下，它的初始上下文为空。

2. 任务拆解与工具调用（Tool Calling）

收到用户的复合指令（如“帮我建立一个带有健康检查接口的 Express 应用”）后，大模型不会试图一次性吐出所有代码。它会将其拆解为多个子任务，并选择对应的工具：

• view_folder: 查看目录结构。
• write_file: 创建并写入新文件。
• run_command: 在本地 Shell 中执行命令（如 npm init -y）。

3. 自动化授权边界

为了防止 AI 执行危险操作，Claude Code 在执行写文件或运行命令等敏感操作时，通常会向开发者抛出确认提示（Y/N）。这种设计确保了虽然 AI 在“自主”操作，但控制权始终在人手里。

五、一个典型使用流程

让我们通过一个具体的实例，来看看如何使用 Claude Code 从零开始在空目录中构建一个带有点赞计数的后端 API 服务。

1. 初始化进入

在一座完全空的目录中，我们在终端键入启动命令：

mkdir fast-api-demo && cd fast-api-demo
claude

2. 开发者提出任务

在 Claude Code 的交互提示符中，我们输入：

“我想用 Node.js 和 Express 创建一个简单的 API 服务。包含一个 /counter 接口，支持 GET（获取当前计数）和 POST（计数加一）。请帮我初始化项目并实现它，最后确保它能跑起来。”

3. 工具读取与项目初始化

Claude 识别出当前目录为空。它决定首先初始化项目。

• AI 行为： 自动调用 run_command 执行 npm init -y。
• AI 行为： 自动执行 npm install express。
  (终端会打印出安装进度，并提示用户是否允许执行这些命令。)

4. 代码编写

依赖安装完成后，Claude 决定创建核心文件。

• AI 行为： 调用 write_file 创建 server.js，并写入如下代码：

const express = require('express');
const app = express();
const PORT = 3000;

let count = 0;

app.use(express.json());

app.get('/counter', (req, res) => {
    res.json({ count });
});

app.post('/counter', (req, res) => {
    count++;
    res.json({ success: true, newCount: count });
});

app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

5. 运行验证与自我修正

创建完成后，Claude 会主动提议测试这个应用。

• AI 行为： 提议执行 node server.js 来启动服务。
• AI 行为：（进阶）它可能会建立一个临时的测试脚本或使用 curl 命令去请求 http://localhost:3000/counter，验证返回值是否为 { "count": 0 }。
• 如果遇到端口占用的错误，Claude 会在控制台捕捉到 EADDRINUSE 异常，随后它会主动提议：“检测到 3000 端口被占用，我将把端口修改为 3001”，并自动调用修改文件的工具。

6. 开发者 Review

最终，Claude 会在终端提示任务完成，并给出使用说明。开发者可以随时在本地编辑器中打开该目录，审查所有被生成的代码。

六、它和传统方式的区别

为了更清晰地定位 Claude Code 的技术坐标，我们将它与传统的开发方式及现有的 AI 工具进行多维度对比：

七、适合与不适合的场景

虽然 Claude Code 表现出了极高的灵活性，但作为工程师，我们需要清晰地知道它的能力边界。

适合场景

• 新项目冷启动（Greenfield Projects）： 像本文标题所言，从空目录快速搭建原型。
• 编写单元测试： 让它扫描现有文件，自动创建测试目录并补充 Jest 或 Pytest 用例。
• 小范围的重构与技术升级： 例如“将这个文件的 CommonJS 语法全部转换为 ESM 语法”。
• 依赖包升级与报错排查： 本地运行编译失败时，交由它来分析 node_modules 冲突或配置错误。

不适合场景

• 大型复杂架构的设计决断： 例如“决定整个企业级应用应该采用微服务还是单体架构”，这需要复杂的商业与业务权衡，超出了代码级别 Agent 的核心能力。
• 涉及高危环境的操作： 严禁在连接了生产环境数据库或生产集群的终端下，赋予其自由执行命令的权限。
• 涉及核心安全合规的代码编写： 加密算法实现、金融支付核心对账逻辑等，不能完全交由 AI 自动编写且不加深度审计。

八、开发者应该如何使用它

引入 Claude Code 后，开发者的角色正在发生微妙的变化：从一个字一个字敲击代码的“打字员”，转变为一个设定边界、审查代码的“技术领队（Tech Lead）”。

为了更高效地与 Claude Code 协作，建议遵循以下实践：

1. 明确而微小的任务声明： 避免一次性下达“帮我写一个推特系统”这样宽泛的指令。应当将其拆解为：“首先帮我创建一个用户注册的本地接口，使用内存数组暂存数据”。
2. 严守 Review 职责（保持 Git 干净）： 在使用 Claude Code 前，务必确保当前项目的所有修改已提交（Git commit）。这样，当 AI 执行了不符合预期的文件修改时，你可以通过 git diff 清晰地看到它改了什么，并随时可以通过 git checkout . 进行一键回滚。
3. 配置合理的安全边界： 认真对待每一次 [Y/n] 的命令行授权提示。对于带有 rm -rf 或可能影响全局系统配置的命令，应予以拒绝或改为手动执行。

九、局限与风险

任何新技术都有其不完美的一面，Claude Code 同样存在以下局限性：

• 幻觉（Hallucination）风险： 它可能会调用一些根本不存在的 npm 包，或者误用某些框架废弃的 API。

• 缓解建议： 开启本地自动化测试，让编译器和测试用例去帮隐性幻觉“打假”。

• Token 消耗与成本： 随着项目文件增多，每次对话它需要读取的上下文越来越大，这会导致 Token 消耗极快。

• 缓解建议： 使用 .gitignore 或工具自带的忽略配置，避免让 AI 扫描庞大的 dist/ 或 node_modules/ 目录。

• 代码质量的随机性： AI 在不同时间段生成的代码风格可能存在不一致，有时优雅，有时冗余。

• 缓解建议： 在项目中配置严格的 ESLint 或 Prettier 规则，并让 AI 在提交前运行 Lint 工具进行格式化修剪。

十、总结：它真正改变的是什么

从一个空目录，到最终终端里跑起一个可以正常响应请求的 API 应用，Claude Code 改变的并不是“写代码”这件事情本身，而是改变了人机协同的摩擦力。

它不再把代码关在 AI 的沙盒里，而是让 AI 走入开发者最熟悉的本地战场——终端。它就像是你身边坐着的一位不知疲倦、手速极快的初级结对编程伙伴（Pair Programmer）。你负责出主意、把方向、看核心逻辑；它负责查文档、写样板、跑测试、改小错。

正确看待它的姿态应当是：不轻信，不排斥；积极用其加速重复劳动，留出更多的时间去思考真正具有业务价值的架构与算法设计。 终端的提示符还在闪烁，不妨现在就打开一个空目录，敲下你的第一条协同指令。