LLM Best Practices

How to set up Claude Code on a new repository

4 min read

View markdown source

Overview

Claude Code is at its best when the repo gives it durable context. This guide installs Claude Code on a fresh project, writes the three anchor files it needs (CLAUDE.md, TODO.md, optionally SESSION_LOG.md), wires the hooks that keep automation honest, and lands the first PR through the brief-then-verify loop from claude-code.

Prerequisites

  • Node 22 and npm on the path. Claude Code runs on Node.
  • A Git repository, local or remote. The anchor files live in source control.
  • gh CLI authenticated, if you want CC to open PRs directly. gh auth status should print “Logged in”.
  • A working build command (npm run build, npm test, or equivalent) that exits non-zero on failure.

Steps

1. Install Claude Code

npm install -g @anthropic-ai/claude-code
claude --version

Authenticate on first run. claude opens the login flow; pick the Anthropic Console or Pro account that owns the API budget.

2. Write CLAUDE.md at the repo root

CLAUDE.md is the file CC reads first on every session. Keep it under 300 lines. Put the mission, the schema (if any), the voice rules, the folder map, and the “how to add a page” or “how to add a feature” walk-through.

# CLAUDE.md
 
## Mission
<One paragraph: what this repo is, who it serves, what it deploys to.>
 
## Voice rules
- Lead with the rule.
- No em-dashes; use periods or commas.
- Concrete examples over abstractions.
 
## Folder structure
<tree>
 
## How to add a <thing>
1. ...

See claude-code for the full anchor file pattern.

3. Set up TODO.md

TODO.md is the live backlog. Use checkboxes; CC checks them off as work ships.

# TODO
 
## Active
- [ ] Wire CI to run lint on PRs.
- [ ] Add `/about` page.
 
## Backlog
- [ ] Migrate the blog from Hugo.

Commit both files. CC reads them on session start; humans read them in PRs.

4. Configure hooks in .claude/settings.json

Hooks let the harness run commands at specific lifecycle points. The most useful one is a SessionStart hook that prints the current build and test status so CC opens with the truth.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "git status --short && npm test --silent 2>&1 | tail -20" }
        ]
      }
    ]
  }
}

Commit .claude/settings.json so every contributor gets the same start state. Keep secrets in .claude/settings.local.json and gitignore that path.

5. Land the first PR through the brief-then-verify loop

Write a brief in a chat session. Include mission, file paths, phased steps, acceptance criteria, and explicit non-goals. Paste it into claude running in the repo. CC executes phase by phase; verify each phase by running the verification command in the brief.

## Acceptance criteria
- [ ] `npm run build` exits 0.
- [ ] `npm test` exits 0.
- [ ] New page renders at /foo.
- [ ] CHANGELOG.md updated.

When the brief is done, CC opens a PR with gh pr create. Review the diff, merge, move on. See claude-code-workflow for the day-two patterns.

Verify it worked

Three checks confirm the setup is sound.

# 1. The CLI is installed and authenticated.
claude --version
claude /help
 
# 2. The anchor files are tracked.
git ls-files CLAUDE.md TODO.md .claude/settings.json
 
# 3. The first PR is open or merged.
gh pr list --author "@me"

If claude /help prints the help text and git ls-files lists all three files, you are done.

Common errors

  • claude exits with “command not found”. The global npm bin is not on PATH. Add $(npm config get prefix)/bin to your shell PATH.
  • The SessionStart hook hangs the session. The hook command runs synchronously; replace any long-running command with a fast status check.
  • CC ignores CLAUDE.md. The file is not at the repo root, or it exceeds the model’s context budget. Move it to the root and trim it below 300 lines.
  • CC opens PRs against the wrong branch. Set the default branch in the brief, or run gh repo edit --default-branch main once.
  • Secrets leak into .claude/settings.json. Move them to .claude/settings.local.json and add that file to .gitignore.

Graph View

Backlinks