AI AI Tools Guidebook
AI Tool Tutorials

Claude Code Project Setup — From Empty Repo to First Useful Run

How to point Claude Code at a real project and get it productive in 30 minutes.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

What this tutorial solves

Claude Code is powerful but the first run on a real codebase feels overwhelming — settings, permissions, CLAUDE.md, slash commands, MCP servers. Most people skip the setup, ask it to do something big, and bail when the diff is unreviewable. This setup gets you to a productive baseline in 30 minutes: enough scaffolding that the agent has context, enough guardrails that you can review every change, and one small successful task under your belt before you do anything bigger.

Who this is for

Developers trying Claude Code for the first time on a real project (not a toy repo), or anyone who installed it months ago, tried it once, and forgot it.

When to reach for it

Starting a new project, joining an existing codebase, or migrating from Cursor / Copilot to agentic AI. Also a good moment when you have a quiet afternoon and want to set up tooling properly instead of patching it later.

When this is NOT the right tool

One-off scripts where setup overhead is more than the task; codebases you should not touch with an agent (production-critical without good tests); teams without code review before merge; live secrets in plaintext anywhere the agent could read.

Before you start

  • Have a recent clean commit on the repo. The agent’s blast radius is whatever has changed since the last commit, so start at zero.
  • Install Node 20+ and confirm npm/pnpm works on the command line. Most installs are blocked by old toolchains, not Claude Code itself.
  • Pick the small first task ahead of time. A typed-fix, one new test, one rename — not “modernize the auth flow”.
  • Read your repo’s existing README so you can summarize it in CLAUDE.md without rewriting from scratch.

Step by step

  1. Install Claude Code: npm install -g @anthropic-ai/claude-code, or use the official installer for your OS. Verify with claude --version.
  2. Run it in your project root: claude. Authenticate the first time via the browser handshake.
  3. Create CLAUDE.md at the repo root: describe the project, the build / test / lint commands, conventions, and what NOT to touch. Keep under 500 lines; one to two screens is ideal.
  4. Set permissions in .claude/settings.json: allow common safe commands (npm run test, git status, pnpm typecheck), require approval for destructive ones (rm -rf, git push --force, npm publish). Default-ask for anything unrecognized.
  5. Pick one small task as your first run: a typed-fix, a test addition, or a small refactor. Ask for a plan first: “Plan the change. Do not write code yet.”
  6. Watch what Claude Code does. Stop it if it goes off-track — do not let bad runs accumulate. Cancel is cheap; recovery from a 40-file wrong diff is not.
  7. After each productive run, commit. Treat commits as your save points. Subsequent agent runs see the prior commit as the new baseline.

First-run exercise

  1. Pick one ugly utility function with no tests. Ask Claude Code: “Write tests for the current behavior of src/utils/formatDate.ts. Cover happy path plus 3 edge cases. Show diff first.”
  2. Review the proposed test file before approving the write. Run the tests; they should pass.
  3. Commit. Now ask for a small refactor of the same function and re-run the tests.
  4. If anything went sideways, note exactly which step. That note becomes a rule in CLAUDE.md.

Quality check

  • Diff against main after each agent step. The agent should be touching only files you expected.
  • Tests pass after every step. If not, revert before continuing — never compound on a broken state.
  • Verify the agent obeyed CLAUDE.md constraints. If it didn’t, your wording was probably vague; rewrite the rule with an example.
  • Read the commit message the agent suggests; rewrite it if it does not match your repo style.

How to reuse this workflow

  • Once your setup works, template it: copy .claude/settings.json and CLAUDE.md skeleton across new projects.
  • Save the planning prompt that worked best (“Plan only. List files, tests, and out-of-scope items.”). Reuse verbatim.
  • Build a habit: agent run -> diff -> tests -> commit -> repeat. Do not skip steps because “this one looks fine”.
  • Revisit .claude/settings.json every month — your sense of safe commands shifts as you build trust.

First day: install -> CLAUDE.md describing the build -> ask “Add a unit test for src/utils/formatDate.ts covering 3 cases” -> review the diff -> commit. Repeat with bigger tasks as you trust the setup. By day 5, you should be running multi-file changes confidently.

FAQ

  • Cursor vs Claude Code?: Cursor is IDE-native, Claude Code is terminal-native + agentic. Many developers use both — Cursor for quick edits, Claude Code for multi-step tasks. See Claude Code vs Cursor.
  • Will Claude Code break my code?: It can. Always run on a committed repo and review diffs before accepting.
  • What about MCP servers?: Optional; start without them. Add Playwright / database MCP servers later once the basic loop is comfortable.
  • Where do skills and slash commands live?: .claude/commands/ and .claude/skills/ in the repo, plus your user-level config at ~/.claude/.
  • How do I share the setup with a teammate?: Commit CLAUDE.md and .claude/settings.json. Each teammate runs claude in the repo and inherits both.

Common mistakes

  • Skipping CLAUDE.md. Claude Code will make wrong assumptions every run.
  • Granting unrestricted permissions on day 1. Disasters happen during the learning curve.
  • Running on a repo without git or with uncommitted changes. You lose the rollback path.
  • Letting the agent run for 30+ minutes without checking in. Long unsupervised runs accumulate errors.
  • Asking for a giant task before earning trust — start with one-file changes for the first week.
  • Auto-approving every command. Read each prompt for the first dozen tasks; the muscle memory is the safety.

Advanced tips

  • Use git worktrees for risky tasks — keep the main checkout clean while Claude Code experiments in a branch.
  • Add a /commit slash command in .claude/commands/ that does your typical commit message format.
  • For unfamiliar commands, ask Claude Code to “Explain what this command will do before running it” — costs nothing, saves accidents.
  • Add a /plan slash command that prepends “Plan only, do not write code” — saves typing on every planning prompt.

Output checklist

  • CLAUDE.md describes the project, build/test commands, and red-zone files.
  • Permissions in .claude/settings.json have explicit allow/ask rules.
  • Repo is clean (committed) before each agent run.
  • You have run at least one small successful task end-to-end.

Tags: #Claude #Tutorial #Claude Code #Workflow

Related Articles