How to setup Claude Code: the order matters more than the settings

On this page#

• Before you install anything
• The steps
• A working configuration
• Scope
• Repository invariants
• Required workflow
• Stop conditions
• What to skip
• First real task
• FAQ

Before you install anything#

The right way to set up Claude Code is to define repository rules first, install the terminal agent second, verify its permissions third, and only then give it real work. That order matters because an agent that starts without boundaries can make valid-looking changes that violate your repository’s actual invariants.

Claude Code is Anthropic’s terminal-based coding agent. It can inspect a repository, edit files, and run commands, but installation alone does not teach it what your codebase considers correct.

Before opening the agent, write down four things:

• The commands that prove a change is valid.
• The directories it may modify.
• The files it must never touch.
• The architectural rules that are not obvious from the code.

These are repository invariants: conditions that must remain true after every change. Examples include “database migrations are append-only,” “generated files are never edited directly,” or “all public API changes require a compatibility test.”

Do not begin by tuning prompts, aliases, hooks, or model settings. Those are optimization layers. If Claude Code does not know the repository’s invariants, faster execution only produces mistakes faster.

The official Claude Code documentation explains the product and its supported setup surface. Your job is to add the project-specific operating contract that official documentation cannot know.

Photo by Boris K. on Pexels.

The steps#

Use this sequence for a reliable Claude Code terminal setup. Each step removes a different failure mode, so skipping ahead creates ambiguity: when something goes wrong, you will not know whether the cause is installation, permissions, missing context, or the task itself.

1. Write the repository contract before launching Claude Code.
   This prevents the agent from inferring critical rules from incomplete code context.

2. Confirm the repository is already in a recoverable state.
   This prevents pre-existing edits from being mixed with agent-generated changes.

3. Install Claude Code using the current official instructions.
   This prevents stale third-party commands from becoming part of your team’s setup documentation; use the maintained flow in the official docs.

4. Start it from the repository root.
   This prevents the agent from operating with the wrong directory as its project boundary.

5. Review the initial permission behavior before approving commands.
   This prevents convenience approvals from silently becoming broader execution authority.

6. Ask for inspection before modification.
   This prevents Claude Code from committing to a solution before it has found the relevant constraints, tests, and neighboring implementations.

7. Run one bounded task and inspect the diff.
   This prevents a broad first assignment from hiding whether the setup actually works.

8. Promote repeated corrections into repository instructions.
   This prevents the same failure from being solved repeatedly in chat instead of once in durable configuration.

Keep the recovery boundary simple: a clean working tree, a dedicated branch when appropriate, and a diff you can understand. Git is the rollback mechanism; chat history is not.

For teams standardizing more than one agent, the PairFoundry Agent Operating Kit provides a reusable operating layer. The goal is not Claude-specific prompt decoration. It is consistent repository control across Claude Code, Codex, Cursor, and similar agents.

A working configuration#

Start with one small CLAUDE.md file at the repository root. This is better than an elaborate settings stack because it keeps the important rules visible, reviewable, and versioned beside the code. Replace every bracketed value; do not preserve a command or path that is untrue for your repository.

# Repository operating rules
<!-- Gives Claude Code a durable project-level contract. -->


![Close-up of server racks in a data center highlighting modern technology infrastructure. — illustrating how to setup cla](/blog/how-to-setup-claude-code-2.jpg)
*Photo by panumas nikhomkhai on [Pexels](https://www.pexels.com/photo/data-center-server-racks-with-active-equipment-37730212/).*

## Scope
<!-- Defines where edits are allowed and where extra approval is required. -->

- Work only inside `[allowed directories]`.
<!-- Replace this with real paths, such as `src/` and `tests/`. -->

- Do not modify `[protected files or directories]` without explicit approval.
<!-- Include generated output, lockfiles, migrations, or deployment files when applicable. -->

- Never read, print, copy, or modify secrets or local credential files.
<!-- A prompt rule is not a substitute for OS-level access control, but the rule must still be explicit. -->

## Repository invariants
<!-- Records constraints that cannot be inferred safely from syntax alone. -->

- `[Invariant one]`.
<!-- Example shape: public interfaces remain backward-compatible. -->

- `[Invariant two]`.
<!-- Example shape: generated files are changed only through their generator. -->

- `[Invariant three]`.
<!-- Example shape: database migrations are append-only. -->


![Man standing at a whiteboard planning UX design concepts in a modern office setting. — illustrating how to setup claude ](/blog/how-to-setup-claude-code-3.jpg)
*Photo by Christina Morillo on [Pexels](https://www.pexels.com/photo/man-wearing-blue-dress-shirt-facing-whiteboard-1181343/).*

## Required workflow
<!-- Forces inspection and verification to happen in a predictable order. -->

1. Read the relevant implementation, tests, and nearby conventions before editing.
<!-- Prevents a solution based on filenames or assumptions alone. -->

2. State the proposed change and the files likely to be affected.
<!-- Creates a checkpoint before repository state changes. -->

3. Make the smallest change that satisfies the task.
<!-- Limits unrelated cleanup and reduces review surface. -->

4. Run `[format command]`.
<!-- Replace with the repository's exact formatter command. -->

5. Run `[test command]`.
<!-- Use the narrowest meaningful test first. -->

6. Run `[typecheck or build command]`.
<!-- Remove this line if the repository has no such validation step. -->

7. Summarize changed files, validation results, and remaining risks.
<!-- Makes incomplete verification visible instead of implied. -->

## Stop conditions
<!-- Defines when the agent must ask instead of guessing. -->

- Stop if the requested change conflicts with an invariant.
- Stop if validation requires credentials, external state, or destructive operations.
- Stop if the task would modify files outside the declared scope.
- Stop if the correct behavior cannot be established from code, tests, or the task.

This file is intentionally plain. It separates scope, invariants, workflow, and stop conditions—the four controls that matter before convenience settings.

Do not put generic advice such as “write clean code” in it. Claude Code cannot verify that instruction consistently. Give it observable rules: exact paths, exact commands, explicit prohibitions, and clear conditions for stopping.

Treat CLAUDE.md like code. Review changes to it, remove obsolete rules, and keep commands aligned with the repository. The Claude Code overview explains the agent’s capabilities; your configuration should explain how those capabilities may be used here.

What to skip#

Skip setup work that adds ceremony without reducing a concrete repository risk. A useful configuration changes what the agent may do, what it must verify, or when it must stop. Everything else has to justify its maintenance cost.

| Common tutorial step | Why to skip it initially | |---|---| | A giant global instruction file | Rules from one repository leak into unrelated work. | | Dozens of shell aliases | They hide the actual invocation and make team debugging harder. | | Automatic approval of broad commands | Speed is not worth losing the review boundary. | | Hooks before the basic workflow works | They add another failure layer before the core setup is understood. | | Persona-heavy prompting | A role description does not replace paths, commands, and invariants. | | Copying another repository’s rules | Plausible but false instructions are worse than missing instructions. | | Asking the agent to redesign the project first | The first task becomes too broad to validate the setup. |

Also skip exhaustive configuration on day one. Begin with the smallest contract that prevents known damage, then add a rule when a real correction should become durable.

If your team is not ready for a packaged operating system, use the free PairFoundry foundations track. For a comparison of the available implementation packages, see the PairFoundry packs overview. Related setup guidance lives in the agent setup hub.

First real task#

The first real task should be small, representative, and fully verifiable: one narrow bug fix with an existing reproduction or one localized change with established tests. Do not choose repository-wide refactoring, dependency migration, authentication work, or an incident fix as the setup trial.

Use a request shaped like this:

Inspect the relevant implementation and tests for [specific behavior].
Do not edit anything yet.

First, explain:
1. the current behavior,
2. the repository rules that constrain the change,
3. the smallest proposed fix,
4. the files and validation commands involved.

Wait for approval before modifying files.

After approving the plan, require the agent to make the smallest patch, run the configured checks, and report any validation it could not complete. Then review the diff as if it came from a teammate: look for unnecessary files, weakened tests, speculative abstractions, and changes outside the requested behavior.

A successful first task does not prove that Claude Code can generate code. It proves that your setup creates a controlled loop:

1. Inspect.
2. Propose.
3. Approve.
4. Modify.
5. Validate.
6. Review.

If that loop fails, fix the contract before increasing autonomy.

Related reading#

• Claude Code guide — what to do before you type a single prompt
• Claude Code configuration in fifteen minutes, and what to skip

FAQ#

Should Claude Code use the same instructions in every repository?#

No. Global rules should remain minimal because repositories have different commands, boundaries, and failure costs. Put project-specific invariants in the repository-level configuration, where the team can review them alongside code.

How is this different from following the official setup?#

The official documentation tells you how Claude Code works and how to install it. It cannot define your protected paths, validation commands, compatibility promises, or stop conditions. This setup adds that missing repository-specific control layer without replacing the official docs.

What usually goes wrong when a team shares one configuration?#

The file becomes a dumping ground for preferences, stale commands, and rules that apply only to one developer’s environment. Keep only team-valid instructions, make commands repository-native, and review configuration changes with the same care as build or CI changes.

How do I roll back when Claude Code makes the wrong change?#

Stop the session’s modification loop, inspect the diff, and revert only the agent-created changes using your normal version-control workflow. Do not ask the agent to “undo everything” without reviewing scope; unrelated pre-existing work may be present.

When should I not use Claude Code for a task?#

Do not use it when the work requires secrets it should not access, destructive production operations, unresolved product decisions, or changes whose correctness cannot be verified. An agent is useful when the task has inspectable context, explicit boundaries, and a meaningful validation path.