Day 1 was a single-file task. Real work spans multiple files, modules, and directories. Today you'll learn to give Claude Code precise context with /add, write a CLAUDE.md that persists your project instructions, and refactor a module across every file that touches it.
Claude Code doesn't load your entire codebase into context at once — that would be expensive and slow. Instead, it builds understanding progressively:
/addFor most tasks, this automatic navigation is good enough. But for complex refactors or when Claude Code is reading the wrong files, you need explicit control.
In an interactive session, /add forces Claude Code to read specific files before you give it a task. Use this when:
# Start interactive session
claude
# Add specific files to context
/add src/auth/middleware.ts
/add src/auth/types.ts
/add src/routes/users.ts
# Now Claude Code has all three files in context
> Refactor the auth middleware to use the new JWT
validation approach shown in the new-auth branch.
Update all routes that use it.
# Add an entire directory
/add src/components/
# Add by glob
/add src/**/*.test.tsCLAUDE.md is the most important file you'll create today. It's a Markdown file at the root of your project that Claude Code reads automatically every time it starts in that directory.
Think of it as your project's README for Claude — not for humans, but for the AI. It tells Claude Code:
# Project: [Your Project Name]
## Commands
- Dev server: `npm run dev`
- Tests: `npm test`
- Test a single file: `npm test -- --grep "filename"`
- Build: `npm run build`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`
## Architecture
[2-3 sentence description of how the app is structured]
Example:
- React frontend in src/components
- Express API in src/api (REST, no GraphQL)
- PostgreSQL via Prisma ORM in src/db
- Auth is JWT-based, see src/auth/
## Coding Conventions
- All new components use functional components + hooks
- No class components
- Use TypeScript strict mode — no `any` types
- Error handling: always use the AppError class in
src/utils/errors.ts, not raw Error
- API responses: always use the ApiResponse wrapper
from src/utils/response.ts
## Important Context
- The UserModel.id field is a UUID, never auto-increment
- All timestamps are stored in UTC
- The "permissions" system is in src/auth/rbac.ts —
read it before touching any auth-related code
- DO NOT modify the legacy/ directory — it's being
phased out but still in production
## Testing
- We use Vitest, not Jest
- Test files live next to source files: foo.ts → foo.test.ts
- Run tests before submitting any changes
- Aim for >80% coverage on new codeThis is where Claude Code really earns its keep. Refactors that would take you 45 minutes of find-and-replace, test updates, and manual verification — done in minutes.
# Rename a function used across the codebase
claude "rename getUserById to findUserById everywhere
it's used, including in tests and type definitions"
# Update a data model
claude "the User model now has a 'displayName' field
instead of 'firstName' + 'lastName'. Update all
components, API handlers, and tests to use displayName"
# Change an API contract
claude "the /api/users endpoint now returns { data: [],
meta: { total, page } } instead of just []. Update
all callers and tests"
# Add consistent error handling
claude "add proper error handling to all async
functions in src/api/ that are currently missing
try/catch blocks. Use the AppError class from
src/utils/errors.ts"When you run a multi-file refactor, pay attention to the output. You'll see Claude Code:
If the tests fail, Claude Code will attempt to fix the failures before it considers the task done. This is the loop that saves you the most time.
git add -A && git commit -m "checkpoint before refactor". If something goes sideways, git checkout . gets you back instantly.Pick a real refactor from your project — or create one. The goal is to watch Claude Code navigate your codebase and make changes in the right order.
git add CLAUDE.md && git commit -m "add CLAUDE.md"claude/add to add the most relevant files to context (the module being refactored + 1-2 examples of how it's used).git diff. Check that the changes are consistent across all files./add gives you explicit control over what it reads first.Spend 15 minutes writing the most complete CLAUDE.md you can for your current project. Include the commands, architecture, conventions, and at least 3 "important context" notes — things a developer new to the codebase would get wrong. Then test it: close your terminal, open a new session, and ask Claude Code a question that requires this context. Did it answer correctly?