Setting Up Claude Code for a Project

A quarter of an hour of setup decides how useful Claude Code is in a project. After it, Claude knows your conventions, may run the commands it actually needs, and behaves the same for everyone on the team. This module walks the steps in the order that makes sense.

Start with project memory

Begin with /init . Claude looks over the codebase — package manifest, existing documentation, directory layout — and writes a CLAUDE.md holding the stack, the important commands, and the conventions it found. If the file already exists, /init suggests improvements rather than overwriting it. Commit it afterwards so everyone starts from the same place.

Short and concrete beats long and complete. Under 200 lines per file is the guideline; longer files cost more context and are followed less reliably. Every line should earn its keep in almost every session — anything that only applies to one corner of the project belongs in a path-scoped rule under .claude/rules/ . What pays off most: the stack with versions, the commands for install, test, build, and lint, naming conventions nobody would guess, and the pitfalls a new colleague is guaranteed to hit.

# Project: Payment Service

## Stack

- Node.js 20, TypeScript 5, PostgreSQL 15
- Express for API, Prisma for ORM, Jest for tests

## Commands

- `npm run dev` — start with hot reload
- `npm test` — run test suite
- `npm run migrate` — apply pending migrations
- `npm run lint` — ESLint + Prettier check

## Conventions

- All monetary values stored as integers (cents)
- Use `Result<T, E>` pattern for error handling, never throw in service layer
- Database columns: snake_case; TypeScript: camelCase

Setting permissions

By default Claude Code asks before it writes files or runs shell commands. For day-to-day work you pre-approve the operations that come up constantly anyway — everything else keeps its prompt.

The permission manager opens with /permissions ; it shows the rules by scope and lets you add allow, ask, and deny rules. A pattern like Bash(git *) clears a whole family of commands, Bash(npx jest *) just one tool. File access can be narrowed to paths the same way.

Where a rule lives decides who it applies to: .claude/settings.json goes into the repository and covers the team, while .claude/settings.local.json stays with you via .gitignore :

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Read(**/*)",
      "Write(src/**/*)",
      "Edit(src/**/*)"
    ]
  }
}

Anything that can turn dangerous — a production deploy, say — you leave on the prompt. Skills that Claude should never start on its own get disable-model-invocation: true ; they then remain yours to invoke.

When a task needs files outside the project root — a neighbouring library, a shared types package — extend the working directories with --add-dir at launch or /add-dir mid-session. Each path has to exist as a directory, and the grant covers file access only: the .claude/ configuration from that other tree is not loaded along with it.

# Start a session with read/edit access in two sibling directories
claude --add-dir ../shared-types --add-dir ../design-tokens

If the extension should hold beyond a single session, list the paths as permissions.additionalDirectories in .claude/settings.json . --add-dir is exactly the same grant, just temporary.

Security — restricting marketplaces

Where plugins may come from is bounded by blockedMarketplaces . An entry blocks either a domain through hostPattern or a repository path through pathPattern :

{
  "blockedMarketplaces": [
    { "hostPattern": "*.untrusted-domain.io" },
    { "pathPattern": "acme/corp-plugins" }
  ]
}

This is enforced at the policy layer: local settings cannot undo it. For enterprise rollouts it sits in managed settings, alongside related switches such as strictKnownMarketplaces and disableSideloadFlags .

If you write a plugin manifest yourself, monitors and themes now belong under experimental rather than at the top level of plugin.json . The old form still works, but claude plugin validate already warns — a future release will require the nested spelling.

Settings, layers, and updates

Five layers, top to bottom: managed sits at the top and cannot be overridden by anything, not even command line arguments; below it come the command line arguments themselves, then local ( .claude/settings.local.json ), then project ( .claude/settings.json ), and last user ( ~/.claude/settings.json ). So the local file beats the project’s, not the other way round — which is exactly what makes it the place for personal exceptions.

How Claude Code updates itself depends on how it was installed. The native installer pulls new versions in the background on its own; Homebrew and WinGet installations only do so once you set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE — the upgrade then runs in the background and you are prompted to restart. Which channel it follows is set by autoUpdatesChannel : "latest" is the default, "stable" deliberately lags a little. To switch it off entirely there is DISABLE_UPDATES , which really does block every path including a manual claude update ; the milder DISABLE_AUTOUPDATER only suppresses the notices.

Beyond permissions, the settings worth knowing are env for variables that should be present in every session, agent for a different default agent, and claudeMdExcludes to keep other teams’ memory files out of a monorepo. Model and effort level are set here too:

{
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

Finally the split: .claude/settings.local.json belongs in .gitignore , everything shared belongs in the repository — CLAUDE.md , .claude/settings.json , .claude/rules/ , .claude/skills/ and, if you work with them, .claude/agents/ . That way everyone gets the same project instructions, while personal settings and auto memory stay on each machine.