03# Claude Code实战：终端里的逻辑引擎

上一篇我们用 Cursor 搭好了前端页面，Vue3 组件跑起来了，界面能交互了。接下来要让数据流动起来，后端 API 是连接前端和数据库的桥梁。这次我们换个工具：Claude Code，一个运行在终端里的 AI 编程助手。如果你习惯了 GUI 编辑器，可能会觉得在黑框框里写代码有点奇怪，但试过之后你会发现，终端的简洁反而让注意力更集中。

为什么选择 Claude Code 而不是继续用 Cursor？因为后端开发更依赖命令行操作：运行服务器、执行数据库迁移、测试 API。Claude Code 天然集成在终端里，这些操作可以无缝衔接。而且，Claude Code 的 AGENTS.md 配置文件让 AI 能记住整个项目的状态，你不用每次对话都重复解释。

环境准备

先安装 Claude Code。打开终端，运行：

bash 复制代码

npm install -g @anthropic-ai/claude-code

安装完成后，认证你的账户：

bash 复制代码

claude auth login

这会打开浏览器，用你的 Anthropic 账户登录。完成后，终端会显示认证成功。

验证安装：

bash 复制代码

claude --version

看到版本号就说明没问题了。如果安装失败，先检查 Node.js 版本，Claude Code 需要 18 或更高。运行 node -v 查看版本。如果版本太低，用 nvm 升级：

bash 复制代码

nvm install 18
nvm use 18

认证失败？确保你的 Anthropic 账户有 API 访问权限。可以在 console.anthropic.com 检查。

现在进入你的项目目录：

bash 复制代码

cd task-manager

启动 Claude Code：

bash 复制代码

claude

你会看到一个简洁的界面，等待你输入指令。这里没有花哨的按钮，一切通过对话完成。

核心配置详解

Claude Code 的核心是 AGENTS.md 文件。在项目根目录创建它：

bash 复制代码

touch AGENTS.md

这个文件告诉 Claude Code 关于你项目的上下文。Claude Code 每次启动都会加载它，相当于给 AI 一个项目简报。你可以把技术栈、编码规范、架构决策都写进去。这样，AI 生成的代码会自动符合你的项目风格。

写入基础信息：

markdown 复制代码

# 项目说明
这是一个任务管理 Web 应用，前端 Vue3，后端 Node.js，数据库 SQLite（开发）/ PostgreSQL（生产）。

## 技术栈
- 后端：Express.js + TypeScript
- 数据库：SQLite（开发环境）
- 测试：Jest + Supertest

## 开发规范
- 使用 TypeScript 严格模式
- API 路由遵循 RESTful 设计
- 错误处理统一格式

AGENTS.md 的妙处在于，Claude Code 每次启动都会读取它。你不用反复解释项目背景，它已经知道了。

接下来配置模型路由。Claude Code 允许你为不同复杂度的任务选择不同模型。在终端设置环境变量：

bash 复制代码

export ANTHROPIC_MODEL=claude-sonnet-4-20250514
export ANTHROPIC_SMALL_FAST_MODEL=claude-3-5-haiku-20241022

Sonnet 用于主要开发，Haiku 用于快速查询和简单编辑。这样既能保证质量，又能节省 token。

实际使用中，我通常这样分配：生成新代码、重构复杂逻辑用 Sonnet；读取文件、搜索代码、运行命令用 Haiku。如果你不确定，可以先用 Haiku，如果结果不满意再切换到 Sonnet。

工具权限也需要配置。Claude Code 默认会请求文件读写和命令执行权限。你可以在 AGENTS.md 中明确允许：

markdown 复制代码

## 工具权限
- 允许读写项目目录内所有文件
- 允许运行 npm 和 node 命令
- 允许执行数据库迁移脚本

如果你需要连接外部工具，比如数据库 GUI 或 API 测试工具，可以配置 MCP 服务器。在项目根目录创建 .mcp.json：

json 复制代码

{
  "servers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/tasks.db"]
    }
  }
}

这样 Claude Code 就能直接查询数据库，帮你调试查询语句。

实战演练

现在用 Claude Code 搭建后端 API。首先创建项目结构：

bash 复制代码

claude "创建 Express 服务器，TypeScript 配置，基本项目结构"

Claude Code 会生成 src/index.ts、tsconfig.json、package.json 等文件。检查生成的代码，确保符合你的预期。看看 TypeScript 配置是否严格，Express 中间件是否齐全，端口设置是否合理。如果有不满意的地方，直接告诉 Claude Code 修改：

bash 复制代码

claude "将端口改为 3001，并添加 CORS 中间件"

接下来定义任务模型。在 AGENTS.md 中补充数据库 schema：

markdown 复制代码

## 数据库 Schema
tasks 表：
- id: INTEGER PRIMARY KEY
- title: TEXT NOT NULL
- description: TEXT
- status: TEXT DEFAULT 'todo' (todo, in-progress, done)
- created_at: DATETIME DEFAULT CURRENT_TIMESTAMP
- updated_at: DATETIME

然后让 Claude Code 创建数据库迁移：

bash 复制代码

claude "根据 AGENTS.md 中的 schema 创建 SQLite 迁移文件，添加 tasks 表"

它会生成一个 SQL 文件，并更新 package.json 中的 scripts。运行迁移：

bash 复制代码

npm run db:migrate

现在实现任务 CRUD API。在 AGENTS.md 中添加 API 设计：

markdown 复制代码

## API 设计
- GET /api/tasks - 获取所有任务
- GET /api/tasks/:id - 获取单个任务
- POST /api/tasks - 创建任务
- PUT /api/tasks/:id - 更新任务
- DELETE /api/tasks/:id - 删除任务

让 Claude Code 生成路由：

bash 复制代码

claude "创建 Express 路由，实现 AGENTS.md 中的 API 设计，使用 TypeScript 类型"

它会生成 src/routes/tasks.ts，包含完整的 CRUD 逻辑。检查代码，确保错误处理得当。看看路由是否使用了 async/await，错误响应格式是否统一（比如 { error: string }）。如果发现问题，让 Claude Code 重构：

bash 复制代码

claude "重构路由，添加统一的错误处理中间件，确保所有路由使用 async/await"

接着实现数据库交互。让 Claude Code 创建数据访问层：

bash 复制代码

claude "创建 src/db/tasks.ts，封装 SQLite 查询，提供 createTask、getAllTasks 等函数"

现在更新路由，使用数据访问层。在 AGENTS.md 中说明：

markdown 复制代码

## 当前任务
路由文件已生成，但使用了模拟数据。请更新 src/routes/tasks.ts，使用 src/db/tasks.ts 中的真实查询。

然后运行：

bash 复制代码

claude "根据 AGENTS.md 的指示，更新路由文件，连接真实数据库"

Claude Code 会修改路由，引入数据库查询。启动服务器测试：

bash 复制代码

npm run dev

用 curl 或 Postman 测试各个端点。如果遇到问题，直接问 Claude Code：

bash 复制代码

claude "运行 npm test 时出现 SQLite 错误，帮我诊断"

它会分析错误，提出修复方案。

最后添加 API 测试。让 Claude Code 生成测试文件：

bash 复制代码

claude "为任务 API 创建 Jest 测试，使用 Supertest 测试各个端点，包含正常和错误场景"

它会生成 tests/tasks.test.ts，覆盖主要用例。运行测试：

bash 复制代码

npm test

测试通过后，你的后端 API 就完成了。

踩坑记录

问题1：权限被拒绝 Claude Code 尝试写入文件时，有时会遇到权限错误。解决方法是在 AGENTS.md 中明确声明权限，或者手动设置文件权限：

bash 复制代码

chmod -R 755 src/

问题2：模型选择不当 用 Haiku 生成复杂业务逻辑，代码质量会下降。记住：Haiku 用于简单编辑和查询，Sonnet 用于主要开发。

问题3：数据库连接失败 如果 Claude Code 无法连接数据库，检查 .mcp.json 配置，确保路径正确。SQLite 文件必须存在，可以先手动创建：

bash 复制代码

mkdir -p data && touch data/tasks.db

问题4：TypeScript 类型错误 Claude Code 有时会生成类型不匹配的代码。在 AGENTS.md 中强调：

markdown 复制代码

## 严格要求
- 所有函数必须有明确的 TypeScript 类型
- 禁止使用 any 类型
- 使用接口定义数据结构

然后让它重新生成相关代码。

问题5：测试覆盖率不足 默认生成的测试可能遗漏边界情况。在 AGENTS.md 中指定：

markdown 复制代码

## 测试要求
- 覆盖所有 CRUD 操作
- 测试错误场景（404、400、500）
- 测试数据库约束

问题6：依赖冲突 Claude Code 生成的代码可能引入了版本冲突的依赖。如果 npm install 报错，先检查 package.json 中的版本号。可以尝试删除 node_modules 和 package-lock.json，重新安装：

bash 复制代码

rm -rf node_modules package-lock.json
npm install

如果问题依然存在，让 Claude Code 诊断：

bash 复制代码

claude "npm install 出现依赖冲突，帮我解决"

它会分析依赖树，提出解决方案。

本篇小结

Claude Code 是一个强大的终端工具，适合喜欢命令行的开发者。它的核心是 AGENTS.md，让 AI 理解你的项目上下文。模型路由让你平衡速度和质量。与 Cursor 不同，Claude Code 没有图形界面，但通过对话完成所有任务，效率很高。

配置清单：

安装：npm install -g @anthropic-ai/claude-code
认证：claude auth login
项目配置：AGENTS.md
模型路由：设置环境变量
工具连接：.mcp.json

速查表：

启动：claude
执行指令：直接输入自然语言描述
查看文件：cat 或让 Claude Code 读取
运行命令：npm run dev 等

下一篇我们换到 Codex CLI，用 OpenAI 的编程代理给项目补测试和质量保障。