On this page#
- Before you install anything
- The steps
- A working configuration
- Scope
- Repository map
- Protected boundaries
- Commands
- Implementation rules
- Completion contract
- What to skip
- First real task
- FAQ
Before you install anything#
Getting started with Claude Code in a real repository is mostly an exercise in defining boundaries. First document the repository’s invariants, identify the authoritative validation commands, and protect sensitive or generated files. Then install Claude Code, start it from the repository root, and give it one small, reversible task with an explicit acceptance test.
That order matters because an agent can produce locally plausible code while violating constraints that live outside the edited file. A passing type check does not prove that a migration is safe, an API remains compatible, or generated code stayed untouched.
Claude Code is an agentic coding tool that can inspect a codebase, edit files, and run commands; the official Claude Code overview explains that operating model. Its ability to act across the repository is precisely why repository instructions must come before prompting technique.
Before installation, write down four things:
- Invariants: behavior that must not change, including public interfaces and data assumptions.
- Validation: the exact commands that establish correctness.
- Ownership boundaries: files the agent may edit and files it must leave alone.
- Recovery: how you will inspect and discard an unwanted patch without losing unrelated work.
If those facts exist only in a senior engineer’s head, Claude Code cannot reliably infer them. Fixing that gap helps both the agent and the team.
Photo by Boris K. on Pexels.
The steps#
The reliable setup is short: establish a clean baseline, install from the official path, start at the correct scope, add repository instructions, and verify the workflow with a bounded change. Each step prevents a different class of failure; skipping one usually converts a setup problem into a misleading code-review problem.
-
Record the baseline — this prevents pre-existing failures from being blamed on the agent.
Check the working tree and run the smallest authoritative validation command before changing anything. You need to know which modifications and failures already exist. Do not discard unrelated local work merely to create an artificial clean state. -
Install and authenticate using the official instructions — this prevents stale third-party setup advice from becoming infrastructure.
Follow the current installation and authentication flow in the Claude Code documentation. Do not copy an installer, permission model, or environment workaround from an undated tutorial. -
Launch Claude Code from the repository root — this prevents accidental scope and context errors.
The root should contain the instructions and validation entry points that define the project. Starting from a nested package can hide repository-wide constraints; starting above the repository can expose irrelevant neighboring files. -
Create a concise
CLAUDE.md— this prevents repeated prompting and inconsistent repository behavior.
Treat this file as operational policy, not product documentation. Include commands, boundaries, architecture constraints, and completion criteria that apply to most tasks. -
Run one reversible task and inspect the diff — this prevents false confidence from a successful installation.
Authentication proves that the tool launches. It does not prove that Claude Code understands your repository, chooses the right checks, or respects ownership boundaries.
For broader setup patterns beyond a single repository, use the PairFoundry agent setup hub.
A working configuration#
A useful CLAUDE.md tells Claude Code how to make and verify changes without pretending to describe the entire system. Keep it specific enough to constrain behavior and short enough to remain current. The following file is intentionally conservative: replace bracketed placeholders, remove irrelevant lines, and commit the result only after team review.
# Repository operating instructions
*Photo by Daniil Komov on [Pexels](https://www.pexels.com/photo/laptop-with-coding-software-and-coffee-mug-34803973/).*
## Scope
- Work only inside this repository.
- Make the smallest change that satisfies the request.
- Do not modify unrelated files or reformat untouched code.
- Do not change public interfaces unless the task explicitly requires it.
## Repository map
- Application code: `[path]`
- Tests: `[path]`
- Configuration: `[path]`
- Generated files: `[path]`
- Database migrations: `[path]`
*Photo by panumas nikhomkhai on [Pexels](https://www.pexels.com/photo/data-center-server-racks-with-active-equipment-37730212/).*
## Protected boundaries
- Do not edit generated files directly.
- Do not read, print, copy, or commit secrets.
- Do not modify lockfiles unless dependency changes are explicitly requested.
- Do not create or alter migrations without explicit approval.
- Do not weaken tests, types, lint rules, or security checks to make validation pass.
## Commands
- Install dependencies: `[command]`
- Run the focused test: `[command]`
- Run the relevant test suite: `[command]`
- Run type checks: `[command]`
- Run lint checks: `[command]`
- Build the affected target: `[command]`
## Implementation rules
- Follow patterns already used in the nearest relevant module.
- Prefer existing utilities over introducing new abstractions.
- Preserve backward compatibility unless the task says otherwise.
- Add or update tests for changed behavior.
- Ask before adding a dependency or expanding task scope.
## Completion contract
Before reporting completion:
- Inspect the final diff.
- Run the narrowest relevant checks.
- Report which checks ran and their results.
- Identify checks that could not run and explain why.
- Summarize changed files and any remaining risk.Each section has one job:
| Section | What it prevents | |---|---| | Scope | Opportunistic refactors and silent API changes | | Repository map | Guessing which files are authoritative or generated | | Protected boundaries | High-impact edits that require human judgment | | Commands | Invented validation and the wrong test target | | Implementation rules | New abstractions that ignore local conventions | | Completion contract | “Done” claims without evidence |
CLAUDE.md is context, not enforcement. A sentence saying “do not read secrets” does not replace file permissions, command approval, isolated credentials, or review. The official overview describes what Claude Code can do; your repository still needs controls appropriate to that capability.
Teams that want a fuller operating layer—task framing, boundaries, review, and handoff—can use the PairFoundry Agent Operating Kit. The distinction matters: a repository file supplies local instructions, while an operating system defines how humans supervise agent work.
What to skip#
Skip setup steps that add ceremony without improving scope, verification, or recovery. Most getting-started tutorials over-optimize the first conversation and under-specify the repository contract. That is backwards: a polished prompt cannot compensate for missing commands, undocumented invariants, or permissions that allow unnecessary access.
Do not spend time on:
- A giant universal prompt. Repository-specific rules outperform a reusable wall of prose because the important constraints are local.
- An exhaustive architecture essay in
CLAUDE.md. Link to stable documentation when necessary; keep operational rules close to the work. - Broad permission approval for convenience. Approve the smallest capability needed for the task. Convenience is not a security model.
- Tool integrations before the basic loop works. First prove that inspect, edit, validate, and review behave correctly.
- Generated rule files nobody owns. Stale instructions are worse than absent instructions because they look authoritative.
- A toy “add a comment” trial. It tests file editing, not repository understanding.
- Running every check after every edit. Use focused checks during iteration and the required wider checks before completion.
- Automatic commits or pushes on the first task. Inspect the patch and validation evidence before widening the blast radius.
The official Claude Code documentation should remain authoritative for installation and product controls. Your CLAUDE.md should remain authoritative for repository behavior. Mixing those responsibilities produces brittle instructions.
If your team is not ready for a packaged workflow, the PairFoundry foundations track is the better next step. The available implementation options are also collected on the PairFoundry packs overview.
First real task#
The first task should be a small, existing defect with a reproducible failure, a narrow file surface, and an objective acceptance test. Ask Claude Code to investigate before editing, name protected boundaries, require the focused validation command, and request a final diff summary. Do not begin with a migration, dependency upgrade, or cross-cutting refactor.
A strong first prompt looks like this:
Investigate `[reproducible failure]`.
Before editing, explain the likely cause and list the files you expect to touch.
Keep the change limited to `[allowed scope]`.
Do not modify `[protected paths or interfaces]`.
Add or update a regression test.
Run `[focused validation command]`.
Then inspect the diff and report:
- the root cause;
- the files changed;
- validation performed and its result;
- any remaining risk.
Stop and ask before expanding the scope or adding a dependency.This task exercises the complete loop described by the Claude Code overview: repository inspection, planning, editing, command execution, and review. Success means the patch is understandable, constrained, and independently verifiable—not merely that Claude Code produced code.
Related reading#
- How to set up Claude Code in fifteen minutes, and what to skip
- How to setup Claude Code: the order matters more than the settings
FAQ#
How is this different from the official Claude Code setup?#
The official documentation should define installation, authentication, capabilities, and product controls. This setup adds the repository operating contract that official documentation cannot know: local invariants, protected files, authoritative commands, approval boundaries, and the evidence required before declaring work complete.
Should every repository share the same CLAUDE.md?#
No. Share a small organizational baseline for universal rules, then keep repository-specific commands and boundaries in each repository. Copying one large file everywhere creates misleading instructions when architectures, test entry points, generated files, and release risks differ.
What usually goes wrong when a team adopts Claude Code?#
The common failure is inconsistent supervision: each engineer supplies different context, grants different scope, and accepts different completion evidence. Commit the stable repository rules, review changes to those rules, and keep task-specific constraints in the prompt rather than continuously inflating CLAUDE.md.
How do I recover when Claude Code changes the wrong files?#
Stop the task, inspect the diff, and revert only the agent’s unwanted changes using your normal version-control workflow. Preserve unrelated work. Then tighten the missing boundary in the task prompt or CLAUDE.md before retrying with a smaller scope.
When should I not use Claude Code for a task?#
Do not delegate a task when you cannot state its acceptance criteria, safely expose the required context, or review the result. High-impact migrations, credential handling, production operations, and ambiguous architectural decisions require explicit human control; an agent can assist with analysis without owning execution.