On this page#
- Before you install anything
- The steps
- A working configuration
- Objective
- Allowed scope
- Invariants
- Required workflow
- Prohibited actions
- Stop conditions
- What to skip
- First real task
- FAQ
Before you install anything#
The correct order is repository contract first, tool installation second, and prompts last. Claude Code can operate across files and invoke development tools, so an unclear repository boundary becomes an execution problem immediately. A polished prompt cannot compensate for missing invariants, unknown verification commands, or ambiguous ownership.
Claude Code is an agentic coding tool: it can inspect a codebase, reason about changes, edit files, and use tools from the terminal. That makes setup fundamentally different from configuring autocomplete.
Before installing it, write down five things:
- Scope: which directories the agent may change.
- Invariants: behavior that must remain true after every change.
- Verification: the exact commands that establish correctness.
- Prohibitions: generated files, secrets, migrations, or APIs it must not touch.
- Escalation: decisions that require a human answer.
This is the central rule of this Claude Code guide: configure the repository’s operating contract before configuring the agent. If your team cannot state what “safe” means without referring to a specific task, the repository is not ready for autonomous edits.
The official Claude Code documentation explains product capabilities and installation. Use it for the mechanics. Your repository still needs its own rules because official documentation cannot know your architectural boundaries, release process, or irreversible operations.
Photo by Boris K. on Pexels.
The steps#
Use this sequence because each step removes a specific failure mode before the agent receives more authority. Do not begin with extensions, hooks, or a large prompt library. Begin with boundaries, prove the verification path, and only then let Claude Code modify a narrowly defined part of the repository.
-
Record the clean starting state.
This prevents existing failures or unrelated local changes from being attributed to the agent. -
Identify repository-local instructions.
This prevents Claude Code from following generic conventions that conflict with the project’s actual build, test, or style rules. -
Write explicit invariants.
This prevents a locally plausible implementation from silently changing behavior elsewhere. -
Define the allowed edit surface.
This prevents a small request from expanding into opportunistic refactoring across unrelated modules. -
Name the authoritative verification commands.
This prevents “the code looks correct” from becoming the acceptance criterion. -
Separate reversible and irreversible actions.
This prevents routine implementation work from crossing into deployments, destructive migrations, credential changes, or history rewrites. -
Install Claude Code using the official path.
This prevents stale third-party instructions from becoming part of your development environment; follow the current official setup documentation. -
Start with inspection-only work.
This prevents early configuration mistakes from becoming code changes before you can see how the agent interprets the repository. -
Authorize one bounded edit.
This prevents the first task from becoming an uncontrolled test of every capability at once. -
Review the diff and verification evidence separately.
This prevents passing tests from hiding unnecessary changes, and a clean-looking diff from hiding untested behavior.
For a reusable version of this operating model, the PairFoundry Agent Operating Kit provides a structured starting point. The important part is not collecting more prompts; it is making scope, evidence, and stop conditions explicit.
A working configuration#
A useful configuration should be short enough to remain enforceable and specific enough to change behavior. Put the following in the repository’s CLAUDE.md, then replace every angle-bracketed placeholder. Do not paste architecture history or general coding advice into this file; include only rules that affect decisions.
# Repository operating contract
*Photo by Lukas Blazek on [Pexels](https://www.pexels.com/photo/person-encoding-in-laptop-574071/).*
## Objective
Make the smallest change that satisfies the requested behavior.
## Allowed scope
- Read the entire repository when needed for context.
- Edit only: <allowed directories or files>.
- Treat all other paths as read-only unless the user expands scope.
*Photo by Digital Buggu on [Pexels](https://www.pexels.com/photo/monitor-displaying-computer-application-374559/).*
## Invariants
- Preserve: <public behavior or compatibility guarantee>.
- Preserve: <data, security, or performance constraint>.
- Do not change public interfaces unless the task explicitly requires it.
## Required workflow
1. Inspect relevant code and repository instructions before editing.
2. State the proposed files and verification plan.
3. Make the smallest coherent change.
4. Run: `<format or lint command>`.
5. Run: `<focused test command>`.
6. Run: `<broader verification command>`.
7. Report changed files, verification results, and remaining uncertainty.
## Prohibited actions
- Do not modify generated files directly.
- Do not read, print, copy, or commit secrets.
- Do not install dependencies without explicit approval.
- Do not deploy, publish, migrate production data, or change credentials.
- Do not rewrite version-control history or discard unrelated local changes.
- Do not perform unrelated refactoring.
## Stop conditions
Stop and ask before proceeding when:
- The requested change conflicts with an invariant.
- The correct solution requires files outside the allowed scope.
- Verification cannot run or produces an unexplained failure.
- A command could delete data or create an external side effect.
- Repository instructions disagree with this file.Here is what each part controls:
| Line or block | Why it exists |
|---|---|
| Objective | Biases the agent toward minimal implementation instead of broad cleanup. |
| Allowed scope | Separates permission to inspect from permission to edit. |
| Invariants | Defines correctness beyond test completion. |
| Required workflow | Makes planning, implementation, and evidence distinct phases. |
| Verification commands | Replaces invented validation with repository-authoritative checks. |
| Prohibited actions | Blocks high-cost side effects that do not belong in routine coding work. |
| Stop conditions | Converts uncertainty into escalation instead of improvisation. |
CLAUDE.md should be committed and reviewed like code because it influences future changes. The official overview explains what Claude Code can do; this repository contract explains what it may do here.
If your repository has multiple components with different rules, do not inflate one root file into a manual. Keep shared constraints at the root and place component-specific instructions near the component, while ensuring they do not contradict the root contract.
What to skip#
Skip any setup step that adds ceremony without reducing a concrete failure mode. Most tutorials overinvest in prompt collections and underinvest in repository boundaries. That priority is wrong for production code: reusable instructions, deterministic checks, and explicit stop conditions matter more than clever wording.
Do not spend time on:
- A giant universal system prompt. Repository-specific constraints outperform generic advice.
- Persona instructions. Telling the agent to be a “senior engineer” does not define correctness.
- Every possible integration on day one. Each additional tool increases authority and failure surface.
- Global rules for repository-specific behavior. Shared preferences cannot safely encode one project’s invariants.
- Auto-approval of broad command categories. Convenience is not a reason to remove review from destructive or external actions.
- A complete architecture essay in
CLAUDE.md. Long context hides the few rules that must always be followed. - Generated test commands. The repository must name authoritative commands; the agent should not invent the acceptance process.
- Immediate multi-file refactoring. It provides poor diagnostic value because scope, reasoning, and verification all fail together.
- Treating a successful build as complete evidence. Compilation does not prove behavior, compatibility, or an acceptable diff.
If your team still needs the underlying workflow concepts, use the free PairFoundry foundations track. For broader packaged workflows, see the PairFoundry packs overview. More setup articles are collected in the agent setup hub.
First real task#
The first real task should be a genuine repository problem with a narrow surface, but the first pass should remain inspection-only. Ask Claude Code to locate the behavior, identify invariants, propose the smallest change, and name the existing verification path. Authorize edits only after that analysis matches the repository.
Use this prompt:
Investigate <real bug or bounded behavior change>.
Do not edit files yet.
Identify:
1. the execution path responsible for the behavior;
2. the smallest set of files likely to require changes;
3. the repository invariants that constrain the solution;
4. the existing tests that cover this path;
5. the exact verification commands;
6. any decision that requires human input.
Then propose the smallest implementation plan and stop for approval.Choose a task with an observable acceptance condition and existing nearby tests. Avoid dependency upgrades, cross-cutting refactors, migrations, security-sensitive changes, or deployments as the first assignment.
After approving the plan, request the implementation under the same scope. Require a final report containing the changed files, commands run, results, and unresolved uncertainty. That evidence structure aligns the agent with engineering review instead of conversational confidence.
Related reading#
- Claude Code configuration in fifteen minutes, and what to skip
- How to build an MCP server in fifteen minutes, and what to skip
FAQ#
How is this different from following the official Claude Code setup?#
The official documentation covers Claude Code itself; this guide defines the missing repository contract. Installation tells the tool how to run. Your CLAUDE.md, edit boundaries, verification commands, and stop conditions tell it how to work safely inside one real codebase. You need both, starting with the repository rules.
Should every team use the same CLAUDE.md?#
No. Teams should share a common structure, not identical constraints. Verification commands, protected paths, public interfaces, and escalation rules belong to the repository. A copied universal file creates false confidence because it looks standardized while omitting the project-specific conditions that determine whether a change is safe.
What is the biggest team collaboration failure?#
The biggest failure is leaving authority implicit. One engineer expects inspection-only behavior while another assumes the agent may edit, install dependencies, or run broad commands. Commit the operating contract, review changes to it, and make task-level scope explicit so expectations travel with the repository.
How do I recover when Claude Code makes the wrong change?#
Stop, inspect the diff, and separate the agent’s edits from pre-existing work before reverting anything. Do not discard unrelated local changes. Return to the last understood state using your normal version-control workflow, tighten the missing invariant or stop condition, then retry with a smaller authorized scope.
When should I not use Claude Code for the task?#
Do not delegate a task when nobody can state its acceptance condition, when verification is unavailable, or when the first required action is irreversible. Production migrations, credential changes, deployments, and ambiguous architectural rewrites need explicit human decisions before an agent is allowed to execute anything.