Claude Code Project Setup: Configure Any Repo

Setting up Claude Code for a real project

Installing Claude Code takes 30 seconds. Configuring it for your specific project is where the productivity gains actually come from. Without project-specific configuration, Claude Code treats every repository the same: it doesn't know your conventions, your architecture, or your constraints.

This guide covers the four layers of project setup: instructions, memory, safety, and settings.

Layer 1: CLAUDE.md for project instructions

The most important file in your Claude Code setup. Create CLAUDE.md in your project root:

# Project Instructions

## Architecture
- Next.js 14 app router
- Database: PostgreSQL via Prisma
- Auth: NextAuth.js with Google provider
- Styling: Tailwind CSS

## Conventions
- Use server components by default
- API routes in app/api/
- Database queries go through lib/db.ts
- All components in src/components/

## Rules
- Never modify .env files
- Always run tests before suggesting changes are complete
- Use TypeScript strict mode

Claude reads this automatically at the start of every session. Every instruction here replaces a conversation you'd otherwise have to repeat.

For a deeper dive, see our full guide on CLAUDE.md configuration.

Scoped instructions

You can have multiple CLAUDE.md files at different levels:

CLAUDE.md              # Project-wide (root)
src/CLAUDE.md          # Frontend-specific
api/CLAUDE.md          # API-specific
.claude/CLAUDE.md      # System-level (higher priority)

Claude merges them by directory: closer to the file being edited wins. Use this for monorepos or projects with distinct subsystems.

Layer 2: Memory for persistent context

Claude Code forgets everything between sessions. Memory files fix this.

Create .claude/memory.md:

# Memory

## Current
- Working on: user authentication refactor
- Blocked: waiting for API key from Stripe team
- Last session: finished database migration, tests passing

## Decisions
- Using JWT tokens instead of sessions (performance requirement)
- PostgreSQL over MongoDB (relational data dominates)

## Known Issues
- Flaky test in auth.test.ts: race condition, low priority

Read this at session start. Update it at session end. This gives Claude continuity across sessions without consuming permanent context.

For the full architecture, see our guide on Claude Code memory systems.

Layer 3: Hooks for automated safety

Hooks run shell scripts at specific lifecycle points. They enforce rules without relying on Claude to remember them.

Create .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/guard-bash.sh"
        }]
      }
    ]
  }
}

Essential hooks for any project:

Hook	Purpose	When it runs
guard-bash.sh	Block destructive commands (rm -rf, git push --force)	Before any bash command
backup-before-write.sh	Backup files before Claude modifies them	Before any file write
log-changes.sh	Log every file modification to an audit trail	After any file write

Hooks are deterministic. They run every time, regardless of what Claude "remembers." This is infrastructure-level safety that instructions alone can't provide.

Full guide: Claude Code hooks.

Layer 4: Settings for tool permissions

Control what Claude can and can't do in your project.

.claude/settings.json (project-level):

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm:*)",
      "Bash(git:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)"
    ]
  }
}

This is a security boundary. Even if Claude decides to run a destructive command, the permission system blocks it.

Quick start template

Here's a minimal but functional setup you can copy into any project:

your-project/
├── CLAUDE.md              # Project instructions
├── .claude/
│   ├── settings.json      # Hooks + model config
│   ├── memory.md          # Session persistence
│   ├── hooks/
│   │   └── guard-bash.sh  # Block dangerous commands
│   └── commands/
│       └── start.md       # Session start workflow
├── Task Board.md          # Current priorities
└── Daily Notes/           # Session history

This gives you: persistent instructions, session memory, safety hooks, and a daily workflow. Five files that transform how Claude Code works with your project.

Project-specific tips

For monorepos

Use scoped CLAUDE.md files per package. Add directory context:

# CLAUDE.md (root)
This is a monorepo. Packages:
- packages/api: Express backend
- packages/web: Next.js frontend
- packages/shared: Shared types and utilities

When working on one package, don't modify others without asking.

For legacy codebases

Be explicit about what NOT to touch:

# Rules
- The auth/ directory uses a legacy pattern. Do not refactor it.
- config.legacy.js is load-bearing. Never modify.
- Tests in __tests__/integration/ are flaky. Don't mark them as failures.

For team projects

Add .claude/ to your .gitignore for personal settings, but commit CLAUDE.md and hook scripts:

# Personal Claude settings
.claude/settings.local.json
.claude/memory.md

# Shared (commit these)
# CLAUDE.md
# .claude/settings.json
# .claude/hooks/

The full system

Individual configuration layers are useful. A complete system that integrates all four layers, with slash commands for workflows, skills for domain knowledge, and agents for specialized tasks, is transformational.

Claudify provides this out of the box: 21 commands, 9 agents, 1,727 skills, 9 automated hooks, and a 6-layer memory system. npx create-claudify installs everything in one command.

Get Claudify: Production-grade Claude Code setup. Installed in seconds.