Setting Up Your Workspace

Setting Up Your Workspace

Once Claude Code is running, the next thing to do is set it up for your actual projects. This page covers the two things that matter most: the CLAUDE.md instruction file and the settings that control how Claude Code behaves.

---

What Is CLAUDE.md?

CLAUDE.md is a README for your AI assistant.

When you start Claude Code inside a project folder, it automatically reads the CLAUDE.md file in that folder. Whatever you put in there shapes how Claude Code behaves for that entire project — what it knows about your code, what conventions to follow, what to avoid.

Without it, Claude Code starts every session blank. It doesn’t know what your project is, what language you’re using, what your conventions are, or what’s off-limits. You’ll end up re-explaining context every time.

With it, Claude Code walks in already briefed.

Think of it like onboarding a contractor. Without a brief, they’d wander around asking basic questions. With a good brief, they know exactly what the project is, how things work, and what not to touch.

---

Starter CLAUDE.md Template

Create a file called CLAUDE.md in the root of any project you work in frequently. Copy and adapt this:

# Project: [Your Project Name]

## What This Is
[One or two sentences describing what this project does.]

Example: A Python script that scrapes job listings from three sites
and sends a daily email digest.

## Tech Stack
- Language: Python 3.12
- Key libraries: requests, BeautifulSoup, smtplib
- Database: SQLite (jobs.db)
- Config: .env file for email credentials

## How to Run
```
python main.py            # Run the full pipeline
python test_scraper.py    # Test scraping only
```

## File Structure
- main.py — Entry point, runs the full pipeline
- scraper.py — Handles all scraping logic
- emailer.py — Formats and sends the digest
- jobs.db — SQLite database (do not commit)

## Conventions
- Use snake_case for variables and functions
- Error handling: log errors and continue, never crash silently
- Keep functions small — one job per function
- Comment any logic that isn't obvious

## Things to Never Do
- Never commit .env or jobs.db
- Never hardcode credentials
- Don't modify the database schema without discussing it first

You don’t need every section on day one. Start with the basics — project description and tech stack — and add more as you notice Claude Code making assumptions you have to correct.

!!! tip “The test for a good CLAUDE.md” After writing it, imagine a competent developer reading it on their first day. Would they know enough to start working without asking questions? If yes, your CLAUDE.md is good.

---

Where CLAUDE.md Files Live

There are two levels:

Global — applies to every Claude Code session, everywhere:

~/.claude/CLAUDE.md

Project-level — applies only when you’re inside that project folder:

your-project/CLAUDE.md

or

your-project/.claude/CLAUDE.md

Project-level rules override global ones. This lets you set general preferences globally (like your preferred coding style or how you like explanations formatted) and project-specific rules in each project.

Example global CLAUDE.md:

# Global Rules

## Communication Style
- Keep responses concise — I don't need long explanations unless I ask
- When something is ambiguous, ask one clarifying question before proceeding
- If you're about to do something irreversible, confirm first

## Code Preferences
- Python 3.12+
- snake_case everywhere
- No clever one-liners — prefer readable code

## Always
- Warn me before deleting or overwriting anything
- Use .env files for secrets, never hardcode them

---

The Memory System

CLAUDE.md handles your instructions. The memory system handles what Claude Code learns over time.

As you work, Claude Code can save notes about your projects, your preferences, and your feedback. These get stored in memory files that persist across sessions.

Memory lives at:

~/.claude/projects/<project-hash>/memory/

You don’t need to manage this manually. Claude Code builds it up as you work. But you can influence what gets saved by being explicit:

> Remember that I prefer async functions in this project — don't
  suggest synchronous versions.

> Note for future sessions: the database password is in .env as
  DB_PASSWORD, not DATABASE_PASSWORD.

Memory types that get stored:

Type	What It Captures
user	Your preferences, skill level, working style
feedback	Corrections you’ve made, things to avoid
project	Current status, decisions made, goals
reference	Where to find things (docs, credentials, resources)

!!! info “Memory vs. CLAUDE.md” Use CLAUDE.md for stable facts about a project: the tech stack, conventions, file structure. Memory is for things that evolve: current status, what you’ve decided, preferences Claude has learned over time. Both work together.

---

Settings and Configuration

Claude Code’s behavior is controlled through settings files.

Where settings live:

File	Scope	What to put here
~/.claude/settings.json	Global	Default model, effort level, broad defaults
<project>/.claude/settings.json	Project	Project-specific overrides
<project>/.claude/settings.local.json	Local only (gitignored)	Personal overrides, never committed

Key settings for new users:

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [],
    "deny": ["Bash(rm *)"]
  }
}

Most of the time you don’t need to edit settings files directly — Claude Code’s defaults are sensible. The main thing you might want to set early:

Blocking dangerous commands. If you want Claude Code to never be able to delete files without confirmation, you can block rm commands at the settings level. This is a safety net.

{
  "permissions": {
    "deny": [
      "Bash(rm *)",
      "Bash(git push --force)"
    ]
  }
}

---

A Minimal Setup to Get Started

You don’t need to configure everything on day one. Here’s what actually matters early:

1. Create a global CLAUDE.md at ~/.claude/CLAUDE.md with your general preferences — how you like responses, your preferred coding style, any global don’ts.

2. Create a project CLAUDE.md in any project you’re actively working in. Keep it to two or three sections: what the project is, what stack it uses, what to avoid.

3. Leave settings alone unless you have a specific reason to change them. The defaults work well.

The rest — memory types, settings overrides, complex permission rules — can wait until you’re running into specific problems. Claude Code is useful right away without any of it.

!!! example “Start here” Create ~/.claude/CLAUDE.md with a single rule that matters to you right now. Maybe it’s “always confirm before deleting files” or “explain what you’re doing in plain English.” One rule is enough to start. Add more as you notice things you want Claude Code to do differently.