跳到主要内容
工程Mar 28, 2026

我们如何使用Claude Code维护Nuxt 4 + Rust单体仓库

OS
Open Soft Team

Engineering Team

我们的技术栈以及为什么Claude Code适合

在Open Soft，我们的主要产品是一个作为单体仓库构建的网站：使用TypeScript的Nuxt 4前端和由PostgreSQL支持的Rust/Axum后端API。代码库跨越两种语言、两个构建系统、共享数据契约、数据库迁移、10种语言的i18n文件和部署基础设施。更改经常同时触及技术栈的两端。

我们在2025年中期采用了Claude Code，它已成为我们最常用的开发工具。不是因为它为我们编写代码 — 而是因为它以其他工具无法做到的方式推理我们的整个代码库。当您告诉Claude Code“给articles添加published_at字段“时，它读取Rust迁移，更新处理器中的SQL查询，修改前端的TypeScript类型，调整Nuxt页面组件，更新所有10个语言文件，并运行构建进行验证。这种跨栈意识使它在单体仓库开发中不可或缺。

CLAUDE.md：教代理您的约定

有效使用Claude Code的基础是CLAUDE.md文件。这是一个项目级指令文件，Claude Code在每次会话开始时读取。可以把它看作入职文档，但面向您的AI代理。

我们的CLAUDE.md包括：

  • 提交约定： 每次提交必须以TASK-XXX:开头并使用祈使语气
  • 架构概述： 单体仓库结构，哪个目录包含什么
  • 代码风格规则： TypeScript严格模式，禁止any，仅Composition API，<script setup>语法
  • i18n规则： 所有10个语言必须保持同步，键按字母排序，纯英文键
  • 安全规则： 提交中不能有密钥，参数化SQL，显式CORS源
  • 开发命令： npm run dev、cargo run、make fixtures等

Claude Code始终如一地遵循这些约定。当它生成提交消息时，使用TASK-XXX:前缀。当它添加翻译键时，按字母顺序将其添加到所有10个语言文件中。当它编写SQL时，使用参数化查询。这消除了整个类别的代码审查反馈 — 约定违规。

# CLAUDE.md摘录示例
## i18n规则
所有10个语言必须保持同步。添加翻译键时：
1. 键格式：使用纯英文文本作为键
2. 字母顺序：每个语言文件中的键必须按A-Z排序
3. 所有语言必需：en、ru、id、zh、ja、ko、fr、de、es、ar

我们还为后端（/server/CLAUDE.md）和fixture（/server/fixtures/CLAUDE.md）维护每目录的CLAUDE.md文件，提供Claude Code在这些目录中工作时激活的上下文特定指令。

多文件重构：杀手级用例

为我们节省最多时间的工作流是跨栈重构。以下是我们项目中的真实示例。

任务： 给articles系统添加SEO字段（meta_title、meta_description、focus_keyword、robots_meta）。

没有Claude Code，这个更改需要：

  1. 编写添加4列的SQL迁移
  2. 更新Rust Article模型结构体
  3. 更新Rust CreateArticle和UpdateArticle DTO
  4. 更新articles处理器中的所有SQL查询（SELECT、INSERT、UPDATE）
  5. 更新前端的TypeScript Article类型
  6. 更新管理员编辑器表单以包含新字段
  7. 更新博客文章页面以渲染meta标签
  8. 更新站点地图生成逻辑
  9. 更新所有fixture文件的新字段
  10. 运行迁移、重建、测试

使用Claude Code，我们输入一个命令：

给articles添加SEO字段（meta_title、meta_description、focus_keyword、robots_meta）。
编写迁移，更新Rust模型和处理器，更新前端类型
和管理员编辑器，给博客页面添加meta标签，并更新fixture。

Claude Code作为单个代理循环执行：

  • 读取现有迁移文件以理解模式
  • 读取Rust模型以理解当前结构体
  • 读取处理器以找到所有SQL查询
  • 读取前端类型和组件
  • 在12+个文件中进行所有更改
  • 运行cargo check验证Rust代码编译
  • 运行npm run build验证前端构建
  • 修复错误并迭代直到两者都通过

整个过程大约需要5分钟，而手动操作需要45-60分钟。更重要的是，它捕获了人类遗漏的交叉引用bug — 比如忘记将新列添加到UPDATE查询或遗漏fixture文件。

迁移编写

数据库迁移特别适合Claude Code，因为它们需要理解当前模式、期望的最终状态以及两者之间的安全转换路径。

当我们要求Claude Code编写迁移时，它：

  1. 读取所有现有迁移文件以理解当前模式
  2. 读取Rust模型以理解目标状态
  3. 编写带有正确ALTER TABLE语句的迁移SQL
  4. 在适当的地方添加IF NOT EXISTS保护以确保幂等性
  5. 如果我们使用可逆迁移，创建相应的“回滚“迁移
  6. 更新Rust模型和处理器以使用新模式

测试生成

我们广泛使用Claude Code来生成测试fixture和SQL种子数据。我们的fixture文件包含真实的长篇内容（1500+字的文章）和适当的SEO元数据，手动编写这些内容既乏味又容易出错。

工作流：

  1. 描述我们需要的文章（主题、角度、技术深度）
  2. Claude Code生成带有完整Markdown内容的SQL INSERT语句
  3. 它遵循我们的UUID约定（d0000000-...用于文章，a0000000-...用于类别）
  4. 它添加ON CONFLICT (slug) DO NOTHING以确保幂等性
  5. 它通过article_tags关联表将文章链接到标签

使用Claude Code进行代码审查

在打开合并请求之前，我们运行Claude Code作为审查者：

审查此分支上的所有更改，检查bug、安全问题、性能问题
以及与我们CLAUDE.md约定的一致性。

Claude Code：

  • 运行git diff main...HEAD查看所有更改
  • 分析每个文件的潜在问题
  • 检查SQL注入（非参数化查询）
  • 验证i18n键在所有10个语言中存在
  • 检查Rust生产代码中的.unwrap()调用
  • 验证错误处理遵循我们的模式
  • 报告带有文件路径和行号的发现

这捕获了大约30%的问题，否则这些问题会在人工代码审查中被发现，让我们的人工审查者专注于架构和业务逻辑。

钩子：自动化质量关卡

Claude Code支持钩子 — 在某些操作之前或之后自动运行的脚本。我们使用钩子来强制质量：

预提交钩子： 在Claude Code创建提交之前运行cargo fmt --check和cargo clippy。如果任一失败，Claude Code修复问题并重试。

编辑后钩子： 在Claude Code修改/i18n/locales/中的任何文件后，钩子运行脚本验证所有10个语言文件具有相同的键集。如果缺少键，Claude Code添加它们。

MCP服务器：扩展Claude Code的能力

模型上下文协议（MCP）服务器让您可以给Claude Code访问外部工具。我们运行两个自定义MCP服务器：

  1. 数据库MCP服务器： 让Claude Code直接查询我们的开发PostgreSQL。调试数据问题时，Claude Code可以运行SELECT查询来检查实际数据库状态，理解问题，并编写修复 — 全在一个循环中。

  2. 部署状态MCP服务器： 连接到我们的CI/CD流水线。Claude Code可以检查最新部署是否成功，读取构建日志，并诊断故障，无需我们切换到CI仪表板。

1M上下文下大型代码库的技巧

Claude Code的1M token上下文窗口是其在单体仓库工作中最强大的功能。以下是我们如何最大化利用它：

让Claude Code探索。 不要试图预先选择要显示的文件。描述您想要什么，让Claude Code使用其工具（Grep、Glob、Read）找到相关代码。

使用CLAUDE.md作为稳定上下文。 会话之间不变的信息 — 架构、约定、命令 — 放入CLAUDE.md，这样Claude Code不会浪费上下文重新发现它。

将大任务分解为阶段。 即使有1M token，像“重构整个身份验证系统“这样的任务也受益于分阶段：首先分析和规划，然后逐模块实施，最后测试。

信任代理循环。 当Claude Code进行更改、运行构建、看到错误并修复它时 — 该循环就是功能。不要在中途打断。让它收敛。

陷阱和解决方法

陷阱：Claude Code过度工程化。 有时它添加不需要的抽象或模式。解决方法：在CLAUDE.md中添加“KISS — 保持简单。避免过度工程化。“

陷阱：长会话中的陈旧上下文。 多次编辑后，Claude Code对当前文件状态的理解可能偏移。解决方法：为每个主要任务启动新会话。

陷阱：非确定性输出。 相同的提示在不同运行中可能产生不同的代码。解决方法：使用具体、详细的提示。

陷阱：测试数据质量。 AI生成的测试数据可能内部不一致。解决方法：始终审查生成的fixture并运行完整测试套件。

陷阱：激进的文件更改。 Claude Code有时修改您没有要求它触碰的文件。解决方法：在接受之前仔细审查差异。

常见问题

Claude Code日常使用需要多少费用？

对于我们4名开发者的团队，我们每月在所有项目的Claude Code API使用上花费约200-300。每月20/开发者的Max计划是更可预测的替代方案。

Claude Code可以离线使用吗？

不能。Claude Code需要互联网连接与Anthropic的API通信。所有代码处理在服务器端进行。

Claude Code会破坏我们的构建吗？

可能，但它自己捕获大多数问题。Claude Code将您的构建命令作为其代理循环的一部分运行。如果cargo check失败，它读取错误并修复。根据我们的经验，约90%的构建在第一次通过，99%在Claude Code的自我纠正循环后通过。

你们如何处理密钥和环境变量？

Claude Code尊重.gitignore并可配置为排除敏感文件。我们从不在仓库中存储密钥。

Claude Code适合独立开发者吗？

当然。在某些方面它对独立开发者甚至更有价值，因为它作为代码审查的第二双眼睛、记住项目约定的知识库以及乏味任务的力量倍增器。

结论

Claude Code不是为您编写应用程序的魔杖。它是一个在跨栈推理、约定执行和乏味的多文件更改方面表现出色的力量倍增器。CLAUDE.md用于持久项目知识、钩子用于质量执行、MCP服务器用于外部工具访问的组合，使其成为我们在单体仓库工作中使用过的最有能力的AI开发工具。

9个月日常使用后的关键洞察：Claude Code最有价值的不是编写新代码，而是维护现有代码 — 重构、迁移、测试和审查。这些任务消耗了开发者70%的时间，最受益于理解整个代码库的代理。

标签
AIDevOpsNuxtRustTypeScript