Claude Code init: what --init actually generates and what to delete

When you run claude --init for the first time, Claude Code drops a bunch of files into your project. Most developers just hit Enter and move on. Big mistake.

Here's exactly what gets created, what each file does, and what you should actually keep.

What --init generates

claude --init
# Creates:
# .claude/
#   settings.json
#   commands/          (empty directory)
# CLAUDE.md           (in project root)

That's it. Three things. But the defaults in each file are where developers go wrong.

The generated CLAUDE.md

The default CLAUDE.md looks something like this:

# Project

## Build Commands
- `npm run build` - build the project
- `npm test` - run tests
- `npm start` - start dev server

## Code Style
- Use TypeScript
- Follow existing patterns

Problem: This is a generic template. Claude Code reads CLAUDE.md on every session startup. If your CLAUDE.md is generic, Claude gives you generic behavior.

What to put instead:

# MyProject

## Critical Context
- This is a Node.js API, NOT a frontend project
- Auth uses JWT in httpOnly cookies (NOT localStorage)
- Database: PostgreSQL via Prisma (NOT raw SQL)
- All routes require validation via Zod schemas

## Never Do These
- Never use console.log in production code (use logger.info)
- Never commit .env files
- Never bypass TypeScript errors with `any`
- Never write tests that hit the real database

## Build & Test
- `npm run dev` - dev server with hot reload
- `npm test` - unit tests (mocked DB)
- `npm run test:e2e` - e2e tests (needs Docker)
- `npm run db:migrate` - run pending migrations

## Architecture
- /src/routes/ - Express route handlers
- /src/services/ - Business logic
- /src/models/ - Prisma models
- /src/middleware/ - Auth, validation, logging

The difference: Claude now has real constraints it will actually follow.

The generated settings.json

{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Almost empty. Here's a production-ready version:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(curl * | sh)",
      "Bash(wget * | sh)"
    ]
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.simplylouie.com"
  }
}

The allow list lets Claude run safe read-only commands without asking. The deny list prevents the scary stuff.

The ANTHROPIC_BASE_URL line is optional but solves the rate limit problem — more on that below.

The commands/ directory

Empty by default. This is where custom slash commands live.

.claude/commands/
  review.md
  deploy.md
  test.md

Each file becomes a /review, /deploy, /test command. Minimal example:

# review.md
Review the staged changes in this PR:
1. Check for security issues
2. Check for missing error handling
3. Check for test coverage gaps
4. Suggest specific improvements

Focus on: $ARGUMENTS

Now /review auth module runs a focused security review of your auth code.

What to delete after --init

Delete: The generic CLAUDE.md content. Replace it with your actual project constraints.

Keep: The file structure (CLAUDE.md in root, .claude/settings.json).

Add: Everything Claude needs to behave correctly in YOUR project specifically.

The init script I use instead

After running --init, I run this setup script:

#!/bin/bash
# claude-setup.sh — run once per project

# 1. Create project-specific CLAUDE.md
cat > CLAUDE.md << 'EOF'
# $(basename $PWD)

## Stack
[FILL IN: language, framework, database]

## Critical Rules
[FILL IN: things Claude must never do in this codebase]

## Commands
[FILL IN: actual build/test/deploy commands]

## Architecture  
[FILL IN: folder structure and what each folder does]
EOF

# 2. Create settings.json with safe defaults
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git diff *)", "Bash(git status)"],
    "deny": ["Bash(git push *)", "Bash(rm -rf *)", "Bash(curl * | sh)"]
  }
}
EOF

# 3. Create a review command
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
Review these changes for: security issues, missing error handling, test gaps.
Focus on: $ARGUMENTS
EOF

echo "Claude Code initialized. Now fill in CLAUDE.md with your actual project context."

The blank [FILL IN] sections force you to actually think about what Claude needs to know. A filled CLAUDE.md takes 10 minutes but saves hours of Claude doing the wrong thing.

The rate limit problem with default init

Default --init leaves ANTHROPIC_BASE_URL unset. This means you're hitting Anthropic's shared API directly. On long sessions, you'll see:

Error: 529 - Overloaded

The fix is one line in settings.json:

"env": {
  "ANTHROPIC_BASE_URL": "https://api.simplylouie.com"
}

This routes through SimplyLouie's API (simplylouie.com) — same Claude models, no rate limit interruptions, $2/month instead of usage-based billing.

Quick reference: --init output

File	Default state	What to do
CLAUDE.md	Generic template	Replace with real project context
.claude/settings.json	Empty permissions	Add allow/deny rules + ANTHROPIC_BASE_URL
.claude/commands/	Empty directory	Add /review, /deploy, /test commands

TL;DR

claude --init creates the right structure but wrong content. Spend 10 minutes after init to:

1. Replace generic CLAUDE.md with your actual project constraints
2. Add allow/deny permission rules to settings.json
3. Create at least one custom slash command

Your future sessions will be dramatically more focused.

---

Running Claude Code without rate limits? Set ANTHROPIC_BASE_URL in your settings.json to point at SimplyLouie — $2/month, same models, no overloaded errors.