Setting Up on a Codebase

How to configure Claude Code for effective work on existing projects. Get your CLAUDE.md right, set up verification loops, and create team-wide conventions that compound over time.

The Setup Checklist

Before diving into a new codebase with Claude Code, follow this sequence. It takes about 15 minutes. The productivity difference over a week is hours.

Creating an Effective CLAUDE.md

The CLAUDE.md file is Claude's introduction to your codebase. It's loaded automatically at the start of every session, making it the highest-leverage configuration point you have. Instructions here get followed more reliably than anything you type in chat.

The Hierarchy

CLAUDE.md files stack in a hierarchy. More specific files override general ones:

What to Include

## Build Commands
npm run build      # Full production build
npm run dev        # Development server on port 3000
npm test           # Run test suite
npm test -- --watch  # Watch mode for TDD

## Key Locations
- Authentication: src/auth/ (not src/users/)
- API routes: src/routes/api/
- Database models: src/models/
- Shared utilities: src/lib/

## Gotchas
- The legacy API in /v1 is deprecated but still receives traffic
- Never import directly from src/internal/. Use the public API
- Tests require DATABASE_URL to be set (use .env.test)
- The CI uses Node 18, not 20

## Git Conventions
- Branch naming: feature/JIRA-123-description
- Use conventional commits (feat:, fix:, chore:)
- Rebase onto main before merging
- PRs require passing CI and one approval

What to Leave Out

Understanding the Codebase with Claude's Help

Before writing code, have Claude explore and map the terrain. This investment pays off every time you ask Claude to make changes.

Initial Exploration

Creating Documentation for Claude

If your codebase lacks documentation, create guidance documents that help Claude navigate:

Multi-Session Workflows

Complex tasks often span multiple sessions. Context resets, you close your laptop, or auto-compaction summarizes your history. Without preparation, you lose progress. Here's how to make work survive context boundaries.

Plan Files

For any task that might take multiple sessions, have Claude write the plan to a markdown file:

# plan.md - Authentication Migration

## Goal
Replace JWT-based auth with session-based auth

## Steps
1. [x] Create session store (src/lib/sessions.ts)
2. [x] Update login endpoint
3. [ ] Update middleware to check sessions
4. [ ] Migrate existing users
5. [ ] Remove JWT dependencies

## Current Status
Completed steps 1-2. Next: middleware update.

## Notes
- Session TTL: 24 hours
- Redis for session storage in production

Start each new session by pointing Claude at the plan file. The plan persists even when context doesn't.

Git Checkpoints

Commit working code before moving to the next step. If something goes wrong, you can revert to a known-good state:

# After completing each logical piece
git add -A && git commit -m "feat: complete session store implementation"

# If the next step goes wrong
git revert HEAD  # or reset to the working commit

Small, frequent commits create recovery points. If Claude tangles something, you lose minutes instead of hours.

Setting Up Verification

Give Claude ways to verify its own work. This feedback loop will 2-3x the quality of results.

Test Coverage

Configure Claude to run tests after changes. In your CLAUDE.md:

## After Code Changes
Always run: npm test -- --related
Before considering any PR complete: npm test

Linting & Formatting

Never rely on Claude to follow style guides. Use automated tools:

## Code Style
Run `npm run lint` before considering any change complete.
Format with `npm run format` after making changes.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "tool": "edit",
        "command": "npm run lint:fix && npm run format"
      }
    ]
  }
}

CI Integration

Reference your CI configuration so Claude knows what checks must pass:

## CI Requirements
All changes must pass the checks in .github/workflows/ci.yml:
- Linting (eslint)
- Type checking (tsc --noEmit)
- Tests (npm test)
- Build (npm run build)

Visual Verification

For UI work, give Claude a way to see its own output. By default, Claude can't view what it builds. A browser automation MCP server closes this loop.

Playwright MCP lets Claude take screenshots, navigate pages, and verify visual output matches expectations:

// .mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}

With visual verification enabled, Claude can iterate on UI work the way a human developer would: build, view, adjust, repeat.

Permission Configuration

Control what Claude can do. Match permission levels to the task and your risk tolerance.

The Autonomy Dial

Configuring Permissions

Your options for allowing tools:

• During session: When Claude asks permission, select "Always allow" for tools you trust
• Via /permissions command: Add specific tools interactively
• In .claude/settings.json: Configure once, check into git, share with team
• CLI flag: --allowedTools for session-specific permissions

Recommended Allowlist

A reasonable starting configuration for most projects:

{
  "permissions": {
    "allowedTools": [
      "Edit",
      "Write",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deniedTools": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  }
}

Team Conventions

For teams, create shared configuration that compounds your collective learning.

Shared CLAUDE.md

When Claude does something incorrectly, add it to CLAUDE.md so it knows not to repeat the mistake. This creates institutional memory:

## Team Standards
- All PRs require tests for new functionality
- Use conventional commits (feat:, fix:, chore:, docs:)
- Maximum function length: 50 lines
- No TODO comments (file issues instead)

## Past Mistakes to Avoid
- Don't use the deprecated UserService class. Use AuthService
- The Redis client must be imported from src/lib/redis, not redis package directly
- Tests in /e2e require the dev server running on port 3000

Shared Slash Commands

Create project-specific commands in .claude/commands/:

# .claude/commands/fix-issue.md
# Fix Issue $ARGUMENTS

1. Run `gh issue view $ARGUMENTS` to understand the issue
2. Search the codebase for relevant files
3. Implement the fix
4. Write tests if appropriate
5. Commit with a message referencing issue #$ARGUMENTS

Now anyone on the team can run /project:fix-issue 1234.

Shared MCP Configuration

Configure MCP servers in .mcp.json for team-wide access to tools:

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-postgres",
      "args": ["--connection-string", "$DATABASE_URL"]
    },
    "sentry": {
      "command": "mcp-sentry",
      "args": ["--token", "$SENTRY_TOKEN"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}

Instrumenting for Quality

Set up visibility into how AI-assisted development affects your codebase over time.

What to Monitor

Code Health Reviews

Steve Yegge recommends spending 30-40% of your time on code health. Schedule regular reviews:

The 40% Rule

Without active maintenance, AI-assisted codebases accumulate invisible technical debt that slows your agents down. Budget time for:

• Finding and filing issues for code smells
• Breaking up large files (>500 lines)
• Consolidating redundant systems
• Cleaning up debug cruft, old docs, build artifacts
• Refactoring before major expansions