Project Setup

This page is the capstone, not the starting point. Read it after First-Time Setup, Daily Workflow, Using Skills, and Your First Hook.

The goal here is to turn the workflow the team already understands into a durable repo baseline.

Before you start

You are ready for this page if the team can already answer these questions:

• What does a good Claude Code session look like in this repo?
• Which verification commands matter?
• Which prompts or skills already work well enough to standardize?
• Which rules actually need enforcement instead of just documentation?

If those answers are still fuzzy, go back to the tutorials first.

Choose your bootstrap path

Both paths are valid:

The important decision is not which command is more advanced. The important decision is whether the team understands the baseline it is about to standardize.

Layer 1: Build the minimum baseline

Start with the smallest useful shared setup:

1. a tight CLAUDE.md
2. a shared .claude/settings.json
3. a short list of verification commands
4. clear separation between team-shared config and personal overrides

A tight CLAUDE.md

Keep it short enough that the team will actually maintain it.

# Project Working Rules

## Default workflow
- Explore before editing for multi-file or ambiguous work.
- For behavior changes: plan -> RED -> GREEN -> review.
- Keep diffs small and task-focused.

## Verification
- Targeted test: pnpm test -- <target>
- Lint: pnpm lint
- Typecheck: pnpm typecheck
- Full gate: pnpm lint && pnpm typecheck && pnpm test

## Repo notes
- Add the architectural facts Claude repeatedly needs in this codebase.

Shared settings

Commit .claude/settings.json for the team. Keep personal changes in .claude/settings.local.json.

Start small:

• set the model and permissions you are comfortable with
• pre-approve only the commands the team uses constantly
• deny obvious secret paths up front
• skip heavy hook automation until it is clearly justified

Layer 2: Add shared skills before heavy enforcement

Skills are usually the next thing worth standardizing because they capture a workflow pattern without blocking the session.

Good early candidates:

• a verification-first skill
• a repo-specific release flow
• a debugging checklist for a recurring failure mode

If the team cannot yet explain a skill in plain English, it is too early to commit it to the repo.

Layer 3: Add hooks only where they remove real risk

Hooks are useful, but they are not the first thing most teams need.

Start with one of these:

• one safety hook that blocks something obviously risky
• one feedback hook that adds formatting or a related verification step

Do not start with a giant event matrix. If the team is still learning the workflow, too many hooks will feel like random resistance instead of helpful guardrails.

For the full event reference, use Hooks & Events.

Layer 4: Review plugins, MCP, and agents intentionally

Open the interactive plugin manager first:

/plugin

The right flow is:

1. inspect what is already installed
2. confirm what the repo actually needs
3. add only the missing plugins that solve a real problem

If the repo needs external tools through MCP, keep the first server personal while you are learning, then move it to project scope only when the team genuinely needs the same integration.

Do the same with custom agents. Add a reviewer or specialist only when the team already understands the narrow job it should own.

Downloadable setup files

Use the individual downloads below if you only need one file, or grab the starter kit zip to get the complete .claude/ structure in one shot.

What “done” looks like

You are finished with project setup when the repo has:

• a clear CLAUDE.md
• a shared settings baseline the team understands
• one or two shared skills or rules that reinforce the workflow
• optional hooks only where they add real value

If you are deciding how to roll that baseline across a team, continue with Team Leader Setup.