Setting Up Claude Code for a New Project

The first 10 minutes of a new project with Claude Code determine whether you get a productive collaborator or a confused autocomplete. This guide covers the setup that makes the difference — tested across krowdev (this site) and WebTerminal.

Background reading: Getting Started with Agentic Coding, CLAUDE.md Patterns, and Context Management — those three together explain why the setup steps below matter.

Why Setup Matters

Without project context, Claude Code:

• Guesses your stack (often wrong — Astro 4 instead of 6, React instead of Svelte)
• Creates files you don’t want
• Ignores your conventions
• Suggests dependencies you’ve already rejected
• Reinvents patterns you’ve already established

With proper setup, it reads your rules before every response.

CLAUDE.md — Your Project Constitution

CLAUDE.md in the project root is the single most important file for agentic coding. Claude Code reads it at the start of every conversation.

Minimal Starter Template

# Project Name

## Stack
- [list your tech stack explicitly, including versions]

## Key Paths
- `src/` — source code
- `tests/` — test files

## Build & Test
\`\`\`bash
npm run build
npm test
\`\`\`

## Conventions
- [your coding style rules]
- [what NOT to do]

## Boundaries
- [files/dirs that should never be modified]

That skeleton is enough to start. The full treatment — the four-section structure, why the NOT X pattern matters (“Svelte 5, NOT React”), the anti-patterns that quietly degrade a CLAUDE.md, and how it compounds across sessions — is its own guide: Writing an Effective CLAUDE.md. Don’t try to write the perfect file upfront; start with the skeleton above and add a rule every time Claude gets something wrong.

First-Prompt Strategy

The first prompt in a new session sets the tone. Here’s what works:

Good First Prompts

Read CLAUDE.md and the content in content/kb/. Then [your actual task].

Forcing a read of CLAUDE.md ensures Claude loads your rules. Adding “read the content” gives it context about what exists.

Read CLAUDE.md. Then run the tests to verify everything passes before we start.

This establishes a baseline — Claude knows the tests work, and you’ve confirmed the project is in a good state.

Bad First Prompts

Add a dark mode toggle to the site.

Without reading CLAUDE.md first, Claude might use React (not Svelte), use the wrong color scheme, or create a toggle that conflicts with the existing one.

Fix everything.

Too vague. Claude will make changes you don’t want. Be specific about what to fix.

Memory System

Claude Code has a persistent memory system at ~/.claude/projects/<path>/memory/. Memories survive across conversations.

What to Store in Memory

• User profile — your background, how you prefer explanations
• Feedback — corrections you’ve given (“don’t do X”, “always do Y”)
• Project state — architecture decisions, current entry count, feature status
• References — where to find things in external systems

What NOT to Store

• Code patterns — these are in the code itself
• Git history — git log is the source of truth
• Debugging solutions — the fix is in the code
• Anything in CLAUDE.md — don’t duplicate

Real Example: krowdev Memory Structure

memory/
  MEMORY.md              # Index file (pointers only)
  user_profile.md        # Physics/math background, new to web dev
  project_decisions.md   # Stack choices, blog name
  project_kb_architecture.md  # entry count, test count, feature list
  project_reader_mode.md      # Reader mode shipped, all 4 layers
  feedback_agent_browser.md   # Always use agent-browser for visual review

The MEMORY.md index is loaded at the start of every conversation. Individual memory files are read when relevant.

Hooks

Hooks are shell commands that run automatically in response to Claude Code events. Configure them in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "node -v && npm -v > /dev/null && echo 'OK'" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --check 2>/dev/null || true" }
        ]
      }
    ]
  }
}

Each event maps to an array of matcher groups; each group has an optional matcher (a tool-name regex) and a hooks array, and each hook is an object with "type": "command" and the command to run. The edited file’s path isn’t an environment variable — Claude Code passes the event payload as JSON on stdin, so a command reads .tool_input.file_path from it (here with jq).

Common uses:

• SessionStart — validate Node/npm are available, check prerequisites
• UserPromptSubmit — inject reminders before each response
• PostToolUse — run linting or formatting checks after file edits (use matcher to filter by tool)

Permissions

Claude Code’s permission system controls what tools it can use without asking. Three levels:

1. Ask every time (default) — Claude asks before every file edit, command, etc.
2. Allow for session — approve once, applies until conversation ends
3. Allow permanently — saved in settings, never asks again

For a new project, start with default permissions and promote commands you trust:

• npm run build — safe to always allow
• npx playwright test — safe to always allow
• File edits in src/ — usually safe for session
• git commit — keep on ask (you want to review)

agent-browser for Visual Review

For web projects, install agent-browser for visual verification:

npm i -g agent-browser
agent-browser install

The workflow:

# Build and preview
npm run build && npx astro preview --port 4322 &

# Open a page
agent-browser open http://localhost:4322/

# Take a screenshot and review
agent-browser screenshot /tmp/review.png

# Check mobile
agent-browser viewport 375 812
agent-browser screenshot /tmp/mobile.png

# Clean up
agent-browser close

Setup Checklist for a New Project

1. Create CLAUDE.md with stack, paths, build commands, and boundaries
2. Run your first prompt: “Read CLAUDE.md, then run the tests”
3. When Claude gets something wrong, add a rule to CLAUDE.md
4. After 2-3 sessions, create memory files for persistent context
5. Add hooks if you need automated checks
6. For web projects, set up agent-browser and add visual review to CLAUDE.md

The setup compounds. Each rule you add prevents a class of mistakes. After a few sessions, Claude Code becomes genuinely productive — it knows your stack, respects your boundaries, and follows your conventions.

Sources

• Anthropic, Claude Code overview
• Anthropic, Claude Code: Settings & permissions
• Anthropic, Claude Code: Memory