On this page#
- Before you install anything
- The steps
- A working configuration
- Objective
- Repository map
- Invariants
- Required workflow
- Required checks
- Stop conditions
- What to skip
- First real task
- FAQ
Before you install anything#
The correct order is: define repository invariants, identify trusted verification commands, set permission boundaries, and only then install Claude Code. Installation is reversible; an agent making plausible but invalid changes is not. Setup should begin with the repository’s rules, not with the tool’s defaults.
Claude Code is an agentic coding tool that can inspect a codebase, edit files, and run commands from a terminal; the official Claude Code overview explains the product boundary. That capability is useful precisely because it is broad—and dangerous when the repository contract is implicit.
Before installation, write down four things:
- Invariants: behavior, interfaces, generated files, security boundaries, and architectural constraints that must not change.
- Verification: the exact commands that prove formatting, types, tests, and builds still pass.
- Scope: directories the agent may edit and areas requiring explicit approval.
- Recovery: how to inspect the diff, discard a bad patch, and return to a known-good commit.
Do this in the repository, not in a private prompt library. Team-visible instructions are reviewable and versioned; personal instructions silently produce different behavior for different engineers.
The key artifact is CLAUDE.md: a repository instruction file that gives Claude Code persistent project context. The official Claude Code documentation should remain the source of truth for where instructions are loaded and how configuration works. Your file should describe the repository contract, not attempt to teach the agent general software engineering.
If your team has not yet defined those contracts, stop here. Work through the PairFoundry foundations track before adding more autonomy. An agent cannot reliably follow rules the team itself has never made explicit.
Photo by Boris K. on Pexels.
The steps#
Use the following sequence because every step removes a specific failure mode before the agent receives broader access. Do not begin with plugins, elaborate prompts, or automation. A small setup with enforceable checks is safer and more useful than a sophisticated setup built on undocumented assumptions.
-
Make the working tree clean — this prevents pre-existing edits from being mistaken for agent output.
Commit, stash, or otherwise account for every current change. The first agent-generated diff must have a clear boundary.
-
Create a disposable branch — this prevents an unsuccessful task from contaminating normal development.
The branch is not the safety mechanism by itself; it is the place where review, comparison, and rollback stay cheap.
-
Read the official installation instructions — this prevents copying a stale command from a third-party tutorial.
Install Claude Code using the current method in the official documentation, then complete the documented authentication flow. Do not pin an invented version or preserve an old installer merely because it once worked.
-
Add a repository-level
CLAUDE.md— this prevents critical rules from existing only in chat history.Keep it short enough to review. Include commands, boundaries, invariants, and a definition of done.
-
Run each verification command yourself — this prevents encoding checks that are already broken or incomplete.
A command that fails before the agent starts cannot distinguish a regression from baseline noise.
-
Start with approval required for consequential commands — this prevents convenience from becoming accidental authority.
File reads are not equivalent to dependency installation, migrations, credential access, deployment, or destructive Git operations. Treat those categories differently.
-
Give the agent one bounded task — this prevents setup validation from turning into an uncontrolled refactor.
Ask for a plan first, inspect the proposed scope, and authorize implementation only after the plan matches the repository contract.
For a reusable operating model beyond one repository, the PairFoundry Agent Operating Kit provides a structured next step. The setup below remains deliberately repository-native so it works even when no additional pack is present.
A working configuration#
Use CLAUDE.md as the minimum viable configuration: it is visible in review, travels with the repository, and can state rules in the same place developers encounter them. Paste this file at the repository root, replace every angle-bracket placeholder, and delete any line that does not truthfully apply.
# Repository instructions
*Photo by Jakub Zerdzicki on [Pexels](https://www.pexels.com/photo/close-up-of-programmer-typing-code-on-laptop-36496927/).*
## Objective
Make the smallest change that satisfies the requested behavior.
Do not refactor unrelated code or change public interfaces without approval.
## Repository map
- Application code: `<path>`
- Tests: `<path>`
- Documentation: `<path>`
- Generated files: `<paths, or "none">`
*Photo by Daniil Komov on [Pexels](https://www.pexels.com/photo/laptop-with-coding-software-and-coffee-mug-34803973/).*
## Invariants
- Preserve `<public API, data contract, or required behavior>`.
- Do not edit `<generated or protected paths>` directly.
- Do not add dependencies, migrations, or external services without approval.
- Never read, print, modify, or commit secrets and local environment files.
## Required workflow
1. Inspect relevant code and tests before proposing changes.
2. State the intended files, assumptions, and risks.
3. Implement the smallest coherent patch.
4. Run the required checks below.
5. Summarize the diff, checks run, failures, and remaining risks.
## Required checks
- Format: `<command>`
- Static analysis: `<command>`
- Tests: `<command>`
- Build: `<command>`
## Stop conditions
Stop and ask before destructive commands, dependency changes, migrations,
deployment, broad rewrites, or changes outside the requested scope.
If a required check fails before your change, report the baseline failure;
do not weaken, skip, or delete the check.Here is what each section controls:
| Section | Meaning | Failure it prevents |
|---|---|---|
| Objective | Sets the optimization target | Unrequested cleanup and diff expansion |
| Repository map | Names authoritative locations | Editing generated or irrelevant files |
| Invariants | Defines non-negotiable boundaries | Locally valid but system-invalid changes |
| Required workflow | Makes planning and reporting explicit | Silent assumptions and unverifiable work |
| Required checks | Defines acceptance mechanically | “Looks correct” replacing verification |
| Stop conditions | Reserves decisions for a human | Irreversible or high-impact actions |
The configuration is intentionally plain. Claude Code’s documented behavior and configuration surface may evolve, so check the official overview when adding tool-specific settings. Repository rules should remain stable even if the surrounding agent changes.
What to skip#
Skip any setup step that adds ceremony without strengthening scope, verification, or recovery. Most weak tutorials optimize for an impressive first session. A real repository needs predictable diffs and visible boundaries, so several popular recommendations are actively counterproductive.
- Do not paste a giant universal prompt. Generic style advice competes with repository-specific constraints and becomes impossible to audit.
- Do not grant blanket command approval. Repeated prompts are inconvenient, but unrestricted package installation, migrations, deployment, and destructive commands are the wrong fix.
- Do not document commands you have not run. A fictional verification pipeline creates false confidence.
- Do not ask the agent to “understand the whole repo.” Give it the smallest relevant surface and let evidence expand that surface.
- Do not install integrations before the basic loop works. More tools increase authority and failure modes; they do not repair unclear instructions.
- Do not treat generated output as proof. A clean explanation is not a passing test suite, and a passing unit test is not proof that an invariant survived.
- Do not hide team rules in personal configuration. If a rule changes repository behavior, it belongs under version control.
The PairFoundry packs overview is useful when you want a broader operating system, but extra material should follow a sound repository loop—not substitute for one. Related setup guidance lives in the agent setup hub.
First real task#
Your first task should be a small, already-understood defect with an existing or easily specified acceptance test. Avoid greenfield architecture, dependency upgrades, migrations, and sweeping cleanup. The goal is to validate the operating loop: inspection, plan, bounded edit, checks, diff review, and rollback.
Use a prompt shaped like this:
Investigate <specific defect> in <bounded area>.
Before editing:
1. Read CLAUDE.md and the relevant implementation and tests.
2. Explain the likely cause with file-level evidence.
3. Propose the smallest patch and list the files you expect to change.
4. Identify which required checks you will run.
5. Stop for approval.
Do not change dependencies, public interfaces, migrations, generated files,
or unrelated code.After approving the plan, require the agent to implement the patch and report:
- Files changed and why.
- Verification commands actually run.
- Exact failures or skipped checks.
- Assumptions that remain unproven.
- Any scope discovered beyond the original task.
Then inspect the diff yourself. The official Claude Code documentation explains the tool; it does not remove your responsibility to decide whether the repository’s invariants were preserved.
Related reading#
- Codex CLI install in fifteen minutes, and what to skip
- Npm install anthropic-AI/Claude Code — the setup that survives a real repo
FAQ#
How is this different from following the official Claude Code setup?#
The official material explains installation, authentication, features, and supported configuration. This tutorial adds a repository operating contract: clean starting state, explicit invariants, trusted checks, stop conditions, and a bounded first task. Those are team engineering decisions, so official product documentation cannot infer them for your codebase.
Should every repository use the same CLAUDE.md?#
No. Reuse the structure, not the rules. Commands, protected paths, public contracts, and approval boundaries must match the repository in front of you. Copying another project’s configuration without validating every line is worse than starting small because it creates authoritative-looking fiction.
What usually breaks when a team shares this setup?#
The common failure is divergence between written instructions and actual workflow. Commands change, generated paths move, or one engineer relies on private configuration. Review CLAUDE.md like production code: keep it versioned, update it with repository changes, and reject rules that cannot be verified.
How do I recover when Claude Code makes the wrong changes?#
Stop the session’s implementation work, inspect the complete diff, and preserve any useful evidence before reverting the patch through your normal Git workflow. Do not ask the agent to repair an expanding chain of speculative edits. Return to a known-good state, narrow the task, and restart with explicit constraints.
When should I not use Claude Code on a repository task?#
Do not use it when you cannot define safe scope, verify the result, or recover from a bad change. Avoid granting it unsupervised control over secrets, production systems, destructive data operations, ambiguous migrations, or decisions whose correctness depends on unavailable organizational context.