How We Use Claude Code to Maintain a Nuxt 4 + Rust Monorepo

Our Stack and Why Claude Code Fits

At Open Soft, our main product is a website built as a monorepo: a Nuxt 4 frontend with TypeScript and a Rust/Axum backend API backed by PostgreSQL. The codebase spans two languages, two build systems, shared data contracts, database migrations, i18n files for 10 languages, and deployment infrastructure. Changes frequently touch both sides of the stack simultaneously.

We adopted Claude Code in mid-2025 and it has become our most-used development tool. Not because it writes code for us — but because it reasons about our entire codebase in ways that no other tool can. When you tell Claude Code “add a published_at field to articles,” it reads the Rust migration, updates the SQL queries in the handler, modifies the TypeScript types in the frontend, adjusts the Nuxt page component, updates all 10 locale files, and runs the build to verify. That cross-stack awareness is what makes it indispensable for monorepo development.

CLAUDE.md: Teaching the Agent Your Conventions

The foundation of effective Claude Code usage is the CLAUDE.md file. This is a project-level instruction file that Claude Code reads at the start of every session. Think of it as onboarding documentation, but for your AI agent.

Our CLAUDE.md includes:

• Commit conventions: Every commit must start with TASK-XXX: and use imperative mood
• Architecture overview: Monorepo structure, which directories contain what
• Code style rules: TypeScript strict mode, no any, Composition API only, <script setup> syntax
• i18n rules: All 10 locales must stay in sync, keys sorted alphabetically, plain English keys
• Security rules: No secrets in commits, parameterized SQL, explicit CORS origins
• Development commands: npm run dev, cargo run, make fixtures, etc.

Claude Code follows these conventions consistently. When it generates a commit message, it uses the TASK-XXX: prefix. When it adds a translation key, it adds it to all 10 locale files in alphabetical order. When it writes SQL, it uses parameterized queries. This eliminates an entire category of code review feedback — convention violations.

# Example CLAUDE.md excerpt
## i18n Rules
All 10 locales MUST be kept in sync. When adding a translation key:
1. Key format: Use plain English text as the key
2. Alphabetical order: Keys in every locale file MUST be sorted A-Z
3. All locales required: en, ru, id, zh, ja, ko, fr, de, es, ar

We also maintain per-directory CLAUDE.md files for the backend (/server/CLAUDE.md) and fixtures (/server/fixtures/CLAUDE.md), providing context-specific instructions that activate when Claude Code works in those directories.

Multi-File Refactoring: The Killer Use Case

The workflow that saves us the most time is cross-stack refactoring. Here is a real example from our project.

Task: Add SEO fields (meta_title, meta_description, focus_keyword, robots_meta) to the articles system.

Without Claude Code, this change requires:

1. Write a SQL migration adding 4 columns
2. Update the Rust Article model struct
3. Update the Rust CreateArticle and UpdateArticle DTOs
4. Update all SQL queries in the articles handler (SELECT, INSERT, UPDATE)
5. Update the TypeScript Article type in the frontend
6. Update the admin editor form to include the new fields
7. Update the blog post page to render meta tags
8. Update the sitemap generation logic
9. Update all fixture files with the new fields
10. Run migrations, rebuild, test

With Claude Code, we type one command:

Add SEO fields (meta_title, meta_description, focus_keyword, robots_meta) to articles.
Write the migration, update the Rust model and handler, update the frontend types
and admin editor, add meta tags to the blog page, and update fixtures.

Claude Code executes this as a single agentic loop:

• Reads the existing migration files to understand the schema
• Reads the Rust model to understand the current struct
• Reads the handler to find all SQL queries
• Reads the frontend types and components
• Makes all changes across 12+ files
• Runs cargo check to verify the Rust code compiles
• Runs npm run build to verify the frontend builds
• Fixes any errors and iterates until both pass

The entire process takes about 5 minutes, compared to 45-60 minutes doing it manually. More importantly, it catches cross-reference bugs that humans miss — like forgetting to add the new column to the UPDATE query or missing a fixture file.

Migration Writing

Database migrations are particularly well-suited to Claude Code because they require understanding the current schema, the desired end state, and the safe transformation path between them.

When we ask Claude Code to write a migration, it:

1. Reads all existing migration files to understand the current schema
2. Reads the Rust models to understand the target state
3. Writes the migration SQL with proper ALTER TABLE statements
4. Adds IF NOT EXISTS guards for idempotency where appropriate
5. Creates a corresponding “down” migration if we use reversible migrations
6. Updates the Rust models and handlers to use the new schema

Example prompt:

Add a locations table with id (UUID), slug, city_name, country, description,
meta_title, meta_description, latitude, longitude. Create the migration,
Rust model, handler with CRUD endpoints, and add the routes.

Claude Code produces a complete, working feature: migration file, model with serde derives, handler with all CRUD operations using parameterized sqlx queries, route registration in main.rs, and proper error handling throughout.

Test Generation

We use Claude Code extensively for generating test fixtures and SQL seed data. Our fixture files contain realistic, long-form content (1500+ word articles) with proper SEO metadata, and writing these by hand is tedious and error-prone.

The workflow:

1. Describe the articles we need (topic, angle, technical depth)
2. Claude Code generates the SQL INSERT statements with full Markdown content
3. It follows our UUID conventions (d0000000-... for articles, a0000000-... for categories)
4. It adds ON CONFLICT (slug) DO NOTHING for idempotency
5. It links articles to tags via the article_tags junction table

For Rust unit tests, Claude Code reads the implementation, identifies edge cases, and generates test functions with descriptive names. It understands our testing patterns (using sqlx::test for database tests, tokio::test for async tests) and follows them consistently.

Code Review with Claude Code

Before opening a merge request, we run Claude Code as a reviewer:

Review all changes on this branch for bugs, security issues, performance
problems, and consistency with our CLAUDE.md conventions.

Claude Code:

• Runs git diff main...HEAD to see all changes
• Analyzes each file for potential issues
• Checks for SQL injection (non-parameterized queries)
• Verifies i18n keys are present in all 10 locales
• Checks for .unwrap() calls in Rust production code
• Verifies error handling follows our patterns
• Reports findings with file paths and line numbers

This catches about 30% of the issues that would otherwise be found in human code review, letting our human reviewers focus on architecture and business logic.

Hooks: Automating Quality Gates

Claude Code supports hooks — scripts that run automatically before or after certain actions. We use hooks to enforce quality:

Pre-commit hook: Runs cargo fmt --check and cargo clippy before Claude Code creates a commit. If either fails, Claude Code fixes the issues and retries.

Post-edit hook: After Claude Code modifies any file in /i18n/locales/, a hook runs a script that verifies all 10 locale files have identical key sets. If keys are missing, Claude Code adds them.

Hooks transform Claude Code from a suggestion engine into a quality-enforcing agent. It cannot accidentally commit unformatted code or incomplete translations because the hooks catch it.

MCP Servers: Extending Claude Code’s Capabilities

Model Context Protocol (MCP) servers let you give Claude Code access to external tools. We run two custom MCP servers:

1. Database MCP server: Lets Claude Code query our development PostgreSQL directly. When debugging a data issue, Claude Code can run SELECT queries to inspect the actual database state, understand the problem, and write the fix — all in one loop.

2. Deployment status MCP server: Connects to our CI/CD pipeline. Claude Code can check if the latest deployment succeeded, read build logs, and diagnose failures without us switching to the CI dashboard.

MCP servers are simple JSON-RPC services. Implementing one takes about 100 lines of code. The leverage is enormous — every MCP server adds a new capability that Claude Code can use autonomously within its agent loop.

Tips for Large Codebases with 1M Context

Claude Code’s 1M token context window is its most powerful feature for monorepo work. Here is how we maximize it:

Let Claude Code explore. Do not try to pre-select which files to show. Describe what you want and let Claude Code use its tools (Grep, Glob, Read) to find the relevant code. It is better at finding cross-references than you might expect.

Use CLAUDE.md for stable context. Information that does not change between sessions — architecture, conventions, commands — goes in CLAUDE.md so Claude Code does not waste context re-discovering it.

Break mega-tasks into phases. Even with 1M tokens, a task like “refactor the entire authentication system” benefits from phasing: first analyze and plan, then implement module by module, then test.

Trust the agentic loop. When Claude Code makes a change, runs the build, sees an error, and fixes it — that loop is the feature. Do not interrupt it mid-cycle. Let it converge.

Pitfalls and Workarounds

Pitfall: Claude Code over-engineers. Sometimes it adds abstractions or patterns that are not needed. Workaround: Add “KISS — Keep it simple. Avoid over-engineering.” to your CLAUDE.md. We did, and it helped.

Pitfall: Stale context in long sessions. After many edits, Claude Code’s understanding of the current file state can drift. Workaround: Start a new session for each major task. Sessions are cheap.

Pitfall: Non-deterministic output. The same prompt can produce different code on different runs. Workaround: Use specific, detailed prompts. “Add a published_at column as TIMESTAMPTZ NOT NULL DEFAULT NOW()” is better than “add a timestamp field.”

Pitfall: Test data quality. AI-generated test data can be internally inconsistent. Workaround: Always review generated fixtures and run the full test suite. Use ON CONFLICT guards for idempotency.

Pitfall: Aggressive file changes. Claude Code sometimes modifies files you did not ask it to touch. Workaround: Review the diff carefully before accepting. Use git diff after every agentic session.

FAQ

How much does Claude Code cost for daily use?

For our team of 4 developers, we spend approximately $200-300/month on Claude Code API usage across all projects. The Max plan at $20/month per developer is a more predictable alternative that covers most use cases with its 5x usage allocation.

Does Claude Code work offline?

No. Claude Code requires an internet connection to communicate with Anthropic’s API. All code processing happens server-side. Your code is sent to Anthropic’s servers for processing — review their data retention policies for your compliance requirements.

Can Claude Code break our build?

Yes, but it catches most issues itself. Claude Code runs your build commands as part of its agentic loop. If cargo check fails, it reads the error and fixes it. In our experience, about 90% of builds succeed on the first pass, and 99% succeed after Claude Code’s self-correction loop.

How do you handle secrets and environment variables?

Claude Code respects .gitignore and can be configured to exclude sensitive files. We never store secrets in our repository. Our .env files are gitignored, and we use .env.example to document required variables without values.

Is Claude Code suitable for solo developers?

Absolutely. In some ways it is even more valuable for solo developers, because it serves as a second pair of eyes for code review, a knowledge base for remembering project conventions, and a force multiplier for tedious tasks like writing migrations and fixtures.

Conclusion

Claude Code is not a magic wand that writes your application for you. It is a force multiplier that excels at cross-stack reasoning, convention enforcement, and tedious multi-file changes. The combination of CLAUDE.md for persistent project knowledge, hooks for quality enforcement, and MCP servers for external tool access makes it the most capable AI development tool we have used for monorepo work.

The key insight after 9 months of daily use: Claude Code is most valuable not for writing new code, but for maintaining existing code — refactoring, migrating, testing, and reviewing. These are the tasks that consume 70% of a developer’s time and benefit most from an agent that understands your entire codebase.