Setting Up Claude Code for a New Project Markdown source

---
title: "Setting Up Claude Code for a New Project"
description: "How to configure CLAUDE.md, hooks, permissions, memory, and agent-browser for productive agentic coding from day one."
kind: guide
maturity: budding
confidence: high
origin: ai-drafted
author: "Agent"
directedBy: "krow"
tags: [agentic-coding, patterns, reference]
published: 2026-03-20
modified: 2026-05-31
wordCount: 1176
readingTime: 6
series: "agentic-coding"
series_order: 5
prerequisites: [researching-codebases-with-agents]
related: [agentic-coding-context-management, claude-md-patterns]
url: https://krowdev.com/guide/setting-up-claude-code/
---
## Agent Context

- Canonical: https://krowdev.com/guide/setting-up-claude-code/
- Markdown: https://krowdev.com/guide/setting-up-claude-code.md
- Full corpus: https://krowdev.com/llms-full.txt
- Kind: guide
- Maturity: budding
- Confidence: high
- Origin: ai-drafted
- Author: Agent
- Directed by: krow
- Published: 2026-03-20
- Modified: 2026-05-31
- Words: 1176 (6 min read)
- Tags: agentic-coding, patterns, reference
- Series: agentic-coding (#5)
- Prerequisites: researching-codebases-with-agents
- Related: agentic-coding-context-management, claude-md-patterns
- Content map:
  - h2: Why Setup Matters
  - h2: CLAUDE.md — Your Project Constitution
  - h3: Minimal Starter Template
  - h2: Stack
  - h2: Key Paths
  - h2: Build & Test
  - h2: Conventions
  - h2: Boundaries
  - h2: First-Prompt Strategy
  - h3: Good First Prompts
  - h3: Bad First Prompts
  - h2: Memory System
  - h3: What to Store in Memory
  - h3: What NOT to Store
  - h3: Real Example: krowdev Memory Structure
  - h2: Hooks
  - h2: Permissions
  - h2: agent-browser for Visual Review
  - h2: Setup Checklist for a New Project
  - h2: Sources
- Crawl policy: same canonical content is exposed through HTML, Markdown, and llms-full; no crawler-specific content gate.

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](/guide/agentic-coding-getting-started/), [CLAUDE.md Patterns](/guide/claude-md-patterns/), and [Context Management](/guide/agentic-coding-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

```yaml title="CLAUDE.md"
# 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](/guide/claude-md-patterns/). 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

```text
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.

```text
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

```text
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.

```text
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

```text
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.

:::analogy
Think of CLAUDE.md as a `.bashrc` — it runs on every session. Memory is more like a notebook — Claude checks it when context suggests it might be relevant.
:::

## Hooks

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

```json title=".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)

:::caution
Hooks run in your shell. A broken hook blocks Claude Code. Keep them simple and fast. Test hooks manually before adding them.
:::

## 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:

```bash
npm i -g agent-browser
agent-browser install
```

The workflow:

```bash
# 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
```

:::tip
Never rely on code inspection alone for visual changes. A CSS change that looks correct in the source can produce layout breaks, color contrast issues, or overflow problems that only show up in a real browser. agent-browser catches these.
:::

## 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](https://code.claude.com/docs/en/overview)
- Anthropic, [Claude Code: Settings & permissions](https://code.claude.com/docs/en/settings)
- Anthropic, [Claude Code: Memory](https://code.claude.com/docs/en/memory)