Context Engineering for Claude Code in a Large Multi-Product Codebase

The first time we pointed Claude Code at our monorepo, it tried to read every file. All of them. Every single one across 8 products. The context window filled with package.json files, test fixtures, compiled CSS, and migration scripts from 2024 that nobody remembers writing. By the time it got to the actual code I needed help with, the model was confused about which product we were even working on. It suggested Next.js patterns in a Go service. I stared at my screen for a solid minute before I realized what happened. Classic.

That's when context engineering stopped being optional. (In hindsight, I probably should've figured this out sooner — but I was too busy shipping to read the docs properly.)

This tutorial walks through how we structure CLAUDE.md files, skill definitions, and ignore patterns to keep Claude Code effective across VDL's 8-product codebase. Not theory — real files, real hierarchy, real tradeoffs. By the end, you'll have a context engineering setup that scales past the "one small project" stage.

What We're Building

A context engineering system for Claude Code that:

Loads product-specific rules automatically based on working directory
Excludes irrelevant files before they waste token budget
Provides reusable skills for common multi-step operations
Scales across multiple products without manual context management

You'll set up a CLAUDE.md hierarchy, configure ignore patterns, and create your first skill file. The patterns work for monorepos, multi-repo setups, and anything in between.

Prerequisites

Before starting:

Claude Code CLI installed and authenticated
A codebase with at least 2 distinct products or services — if you've only got one small project, this is overkill. Come back when you've shipped product #2.
Basic familiarity with YAML and markdown — config files live in both
10 minutes to read the Claude Code documentation on CLAUDE.md. Just that section. The rest can wait.

Optional: JustAnalytics for tracking how often you hit context limits — useful data for tuning. If you're building AI-powered calling features alongside your codebase, VeloCalls integrates well with Claude Code workflows for voice automation.

Step 1: Create the Root CLAUDE.md

Every context engineering setup starts at the root. This file loads for every Claude Code session in your codebase.

Create CLAUDE.md in your repository root:

# Codebase Context

This is a multi-product SaaS studio. 8 active products share infrastructure.

## Products (active)
- clickzprotect/ — bot detection, Go + Next.js
- justanalytics/ — observability platform, TypeScript
- justemails/ — email hosting, Go + React
- justbrowser/ — antidetect browser, Rust + TypeScript
- velocards/ — crypto spending cards, Next.js
- velocalls/ — AI calling platform, Python + Next.js
- devos/ — AI agents marketplace, TypeScript
- vdl-main/ — parent studio site, Next.js

## Shared Infrastructure
- Database: Postgres on Railway
- CDN: Cloudflare
- Monitoring: JustAnalytics (yes, we eat our own cooking)

## Global Rules
- NEVER suggest changes to shared/ without explicit approval
- ALWAYS use the product's existing patterns before suggesting new ones
- Check the product's local CLAUDE.md for specific constraints

Why this matters: Without a root CLAUDE.md, Claude Code treats your multi-product codebase like one giant project. It'll suggest React patterns in your Go code. It'll import from the wrong product's shared utilities. The root file establishes boundaries.

Keep this file under 3,000 tokens. We tried a 10,000-token root file once. Ambitious. Dumb. The model started skipping sections, and we spent an hour debugging why our "NEVER modify shared/" rule wasn't being followed. Turns out the model just... stopped reading at some point. Not worth it.

Step 2: Add Product-Specific CLAUDE.md Files

Each product gets its own context file. Claude Code concatenates these — root first, then the most specific match for your working directory.

clickzprotect/CLAUDE.md:

# ClickzProtect Context

Bot detection platform. $99/mo flat pricing, unlimited clicks.

## Stack
- Backend: Go 1.22, Chi router
- Frontend: Next.js 14, App Router
- Detection: JA4+ TLS fingerprinting

## Conventions
- Tests in *_test.go files, same directory as source
- API handlers in /api/handlers/
- Detection logic in /internal/detection/ — be careful here

## Never
- Never log full request bodies (PII risk)
- Never bypass the rate limiter in detection endpoints
- Never hardcode bot signatures — they live in /data/signatures.yaml

justemails/CLAUDE.md:

# JustEmails Context

Email hosting + transactional API. $49/year flat.

## Stack
- Backend: Go 1.22, custom SMTP server
- Frontend: React + Vite
- Transactional: REST API at /api/v1/send

## Conventions
- SMTP code in /internal/smtp/ — modify with extreme caution
- React components use CSS modules, not Tailwind
- Email templates in /templates/ with .mjml extension

## Never
- Never commit .env files (real email credentials)
- Never modify /internal/smtp/auth.go without review

These files are surgical. They tell Claude Code what this specific product uses, what's dangerous, and where things live. The model spends less time guessing and more time being useful.

I'll be honest: I spent three hours — three actual hours of my life I'm not getting back — debugging a JustEmails issue before realizing Claude Code was suggesting Next.js patterns because it didn't know we use React + Vite there. That's when the product-specific CLAUDE.md files became mandatory. Not because I read a best-practices guide. Because I was annoyed.

Step 3: Configure Ignore Patterns

Context engineering isn't just about what to include. It's about what to exclude.

Create .claudeignore in your repo root:

# Build artifacts
**/dist/
**/build/
**/.next/
**/node_modules/

# Test fixtures and mocks
**/__fixtures__/
**/test-data/
**/*.snap

# Generated code
**/generated/
**/*.gen.go
**/*.gen.ts

# Large data files
**/*.sql.gz
**/migrations/*.down.sql

# Product-specific exclusions
velocards/contracts/   # Solidity — different tooling
justbrowser/engine/    # Rust internals — use rust-analyzer instead

The .claudeignore file works like .gitignore but for Claude Code's context loading. Every file matched here is invisible to the model. This is where you reclaim token budget.

We cut our average context usage by 40% just by ignoring node_modules, build outputs, and test fixtures. Forty percent. Those files were eating thousands of tokens and providing zero value. And honestly, the model doesn't need to see your compiled CSS. It really doesn't. I don't care what some blog post says about "giving the AI full context" — that's cargo cult thinking. For browser automation projects, JustBrowser has its own context patterns worth studying.

Step 4: Create Your First Skill File

Skills are reusable workflows. Instead of explaining the same multi-step process every session, you define it once.

Create .claude/skills/deploy.md:

# Skill: Deploy

Deploys the current product to Railway staging or production.

## Usage
"deploy to staging" or "deploy to production"

## Steps

1. Check for uncommitted changes — abort if dirty
2. Run the product's test suite — abort if failures
3. Build the production bundle
4. Push to the appropriate Railway environment
5. Wait for health check (timeout: 120s)
6. Report deployment URL

## Product-Specific Commands

- **clickzprotect**: `make deploy-staging` or `make deploy-prod`
- **justemails**: `railway up --environment staging`
- **justanalytics**: `pnpm deploy:staging`

## Rollback

If deployment fails, run the product's rollback command. Don't guess — check the product's Makefile or package.json.

Skills turn repetitive explanations into callable knowledge. Instead of typing "run tests, then build, then deploy to Railway, but use the staging environment, and wait for the health check..." you just say "deploy to staging."

We have skills for: deploy sequences, database migrations, creating new API endpoints, running the full test matrix, and generating product boilerplate. Anything you explain more than twice becomes a skill. For crypto-related projects like VeloCards, we maintain specialized skills for smart contract interactions.

(Side note: writing good skill files is harder than it looks. My first few were either too vague to be useful or so specific they broke when anything changed. Still figuring this out.)

Step 5: Test Your Context Engineering

Create a simple test to verify the hierarchy works:

cd clickzprotect
claude "What framework does this product use for the frontend?"

Expected answer: Next.js 14 with App Router (from clickzprotect/CLAUDE.md).

Now test from the root:

cd ..
claude "What are the 8 active products?"

Expected answer: The list from your root CLAUDE.md.

If the model gets these wrong, your hierarchy isn't loading. Check file locations and names. CLAUDE.md is case-sensitive on Linux.

We keep a context-test.sh script that asks 5 questions and verifies the answers. Run it after any CLAUDE.md changes. Catches regressions before they waste your time. Is this overkill? Maybe. But I've been burned enough times that I don't trust my own memory to catch these things.

Common Errors and How to Fix Them

Error: Model suggests patterns from the wrong product

Your product-specific CLAUDE.md isn't loading. Check: Are you in the right directory? Is the filename exactly CLAUDE.md (not claude.md or CLAUDE.MD)? Is there a syntax error in the file?

Error: Context window fills up with irrelevant files

Your .claudeignore isn't aggressive enough. Add more exclusions. Start broad (ignore all of node_modules), then carve out exceptions if needed. Err on the side of ignoring too much — you can always include specific files manually.

Error: Skills don't trigger consistently

Skills need clear trigger phrases in the Usage section. "deploy to staging" works better than "deploy the current product to the staging environment on Railway." Shorter triggers, more reliable activation.

Error: CLAUDE.md changes don't take effect

Claude Code caches context between sessions. Start a fresh session with claude --new or explicitly reload with claude /refresh. We got burned by this during a debugging session — spent 20 minutes wondering why our new rules weren't applying. Embarrassing? Yes. Did I immediately add it to our onboarding doc? Also yes.

Next Steps

You've got the foundation. Here's where to go from here:

Add CI/CD integration — generate CLAUDE.md sections automatically from your existing documentation. We parse README files and extract the "Stack" and "Conventions" sections.
Create product-specific skills — the deploy skill works globally, but each product has unique workflows. JustEmails needs an MJML compile step. ClickzProtect needs signature validation. Encode these as skills.
Monitor context usage — track how often you hit limits and which products are worst. JustAnalytics can log this if you instrument your wrapper script.

If you're building multi-agent systems on top of Claude Code, check out our subagents tutorial. Context engineering becomes even more critical when you're spawning multiple agents — each one needs lean, focused context.

For cross-product bot protection, ClickzProtect handles the detection layer at $99/mo flat, unlimited clicks. For transactional emails triggered by your AI workflows, JustEmails at $49/year flat covers unlimited domains. And if you're running AI agent pipelines in production, DevOS coordinates the agent-as-employee model we use internally — though fair warning, it's still in development with a waitlist.

Here's the thing about context engineering: it's not glamorous. Nobody brags about their .claudeignore file at conferences. Nobody posts "just spent 2 hours tuning my ignore patterns" to Twitter. But the difference between a useful AI coding assistant and a confused one often comes down to whether the model saw the right 50 files or the wrong 5,000. That's it. That's the whole trick.

Frequently Asked Questions

What's the difference between context engineering and prompt engineering?

Prompt engineering focuses on how you phrase instructions. Context engineering focuses on what information the model sees before it even starts reading your prompt. In Claude Code, that means which files get loaded, which directories get ignored, and how your CLAUDE.md hierarchy primes the agent. Bad context engineering wastes 80% of your token budget on irrelevant code. Good context engineering means the model sees exactly what it needs and nothing else.

How big can a CLAUDE.md file be before it hurts performance?

We've tested CLAUDE.md files from 500 tokens to 12,000 tokens. Sweet spot is 2,000-4,000 tokens for the root file. Beyond 6,000, you start seeing the model skip sections or forget earlier constraints. If you need more, split into a hierarchy — root CLAUDE.md with high-level rules, product-specific CLAUDE.md files in subdirectories. Claude Code walks up the tree and concatenates them. You get layered context without bloat.

Should every project have a CLAUDE.md file?

If Claude Code touches it, yes. The file costs nothing when you're not using the agent, and it saves massive debugging time when you are. Even a 10-line CLAUDE.md that says "this is a Next.js app, use App Router patterns, tests live in tests" prevents half the dumb mistakes. We add one to every repo in the first commit. Non-negotiable.

How do skill files differ from CLAUDE.md instructions?

CLAUDE.md is passive context — it loads automatically based on your working directory. Skill files are active tools — the model invokes them when it needs specialized behavior. Think of CLAUDE.md as background knowledge and skills as callable functions. We use skills for repetitive workflows: deploy sequences, database migrations, test-and-commit cycles. The skill encapsulates the multi-step process so the model doesn't reinvent it every time.

Follow the Studio

Velocity Digital Labs is a multi-product studio building 8 active SaaS products with a 1-founder + 1-manager structure. Bootstrapped, cap-table-honest. No VC platform-play — just shipping.

See the products → · Browse all VDL blog posts