On this page#
Before you install anything#
To use Claude Code effectively, define the repository’s operating rules before installing the agent: identify the commands that prove a change is correct, the files it must not touch, the architectural boundaries it must preserve, and the rollback path. Installation comes afterward because an agent without constraints merely produces plausible changes faster.
Claude Code is an agentic coding tool that works from your terminal, reads a codebase, edits files, and runs commands. That capability is useful only when the repository gives it an unambiguous definition of “done.”
Before typing a prompt, write down four things:
- Verification: the exact test, lint, type-check, and build commands required for acceptance.
- Boundaries: generated files, migrations, public APIs, security-sensitive code, and unrelated modules that must remain untouched.
- Conventions: where new code belongs and which existing patterns should be copied.
- Recovery: how you will inspect, isolate, and revert the agent’s changes.
The order matters because Claude Code discovers implementation details from the repository, but it cannot infer your unwritten invariants. A passing test suite may still permit an unacceptable schema change, dependency addition, or public API break.
Do not start by collecting prompts. Prompts are temporary instructions; repository rules are durable controls. The official Claude Code documentation explains the product’s capabilities, while your repository must define the local constraints under which those capabilities are safe.
Photo by Boris K. on Pexels.
The steps#
Use this sequence: establish a clean baseline, map the repository, encode constraints, define verification, restrict the first task, and review the resulting diff. Each step prevents a different failure mode, and skipping ahead converts missing context into unnecessary edits, misleading confidence, or a change that cannot be reviewed cleanly.
-
Start from a clean, named branch — this prevents agent changes from becoming mixed with unfinished human work.
Confirm that every existing modification is understood before Claude Code touches the repository. If the starting state is ambiguous, the final diff cannot tell you what the agent actually changed.
-
Map the repository before requesting implementation — this prevents correct-looking code from landing in the wrong layer.
Locate the entry points, package boundaries, tests, generated outputs, configuration files, and nearby implementations. Ask Claude Code to explain the relevant path first, but verify that explanation against the files it cites.
-
Write repository instructions — this prevents the same constraints from being restated imperfectly in every prompt.
A repository instruction file should contain operational facts, not a miniature engineering handbook. Include commands, non-negotiable boundaries, and conventions that materially affect edits. The official overview is the authority for what Claude Code does; your checked-in instructions are the authority for how it may operate here.
-
Define the acceptance commands — this prevents “the code looks right” from replacing executable evidence.
Specify the smallest relevant test first and the broader validation required before completion. If a command is slow, say so; do not silently omit it and let the agent assume a narrow check is sufficient.
-
Choose a bounded first task — this prevents an unfamiliar agent from turning a local change into a repository-wide rewrite.
Good first tasks have a visible input, a visible output, an existing test surface, and no required architectural redesign. Avoid migrations, authentication changes, dependency upgrades, and sweeping refactors.
-
Require a plan and explicit scope — this prevents premature editing.
Ask for the files likely to change, the invariant each change preserves, and the verification commands that will run. Reject a plan that uses phrases such as “clean up related code” without naming the related code.
-
Review the diff, not the summary — this prevents a persuasive explanation from hiding unnecessary changes.
Claude Code’s summary is navigation, not evidence. Inspect every changed file, then run the repository’s own checks. The product can execute commands as part of its workflow, as described in the Claude Code documentation, but command execution does not remove your responsibility to assess the change.
A working configuration#
Use a short CLAUDE.md that states executable rules rather than preferences. The following is a complete starting point for an npm repository; replace command names only when your repository uses different scripts. Every line either establishes scope, defines an invariant, or creates a verifiable completion condition.
<!-- Identifies this file as operational policy, not general documentation. -->
# Repository operating rules
<!-- Stops the agent from editing before it understands the relevant code path. -->
Read the relevant implementation and tests before proposing changes.
<!-- Makes narrow diffs the default and blocks opportunistic cleanup. -->
Change only files required for the requested task.
<!-- Protects externally consumed behavior unless the task explicitly authorizes a break. -->
Preserve public APIs and existing behavior unless the request says otherwise.
<!-- Prevents generated artifacts from being edited instead of their sources. -->
Do not edit generated files; find and change the source that produces them.
<!-- Prevents silent expansion of the dependency and supply-chain surface. -->
Do not add or upgrade dependencies without explicit approval.
<!-- Directs new work toward established repository patterns. -->
Follow the nearest existing implementation and test conventions.
<!-- Makes uncertainty visible before it becomes an architectural decision. -->
If two implementations are plausible, stop and explain the tradeoff before editing.
<!-- Requires the narrowest useful feedback loop during implementation. -->
Run the most targeted relevant test after each behavioral change.
<!-- Defines the repository-wide acceptance commands. -->
Before completion, run `npm test`, `npm run lint`, and `npm run typecheck`.
<!-- Prevents omitted or failed checks from disappearing behind a success summary. -->
Report every command run, its result, and any check that could not be completed.
<!-- Forces the final response to expose the actual scope of the change. -->
Summarize changed files, preserved invariants, and remaining risks.This file is intentionally repetitive about scope and proof. Agents are more reliable when rules describe observable actions: “run this command,” “do not edit this class of file,” and “stop under this condition.” Words such as “careful,” “clean,” and “production-ready” sound strict but impose no testable boundary.
Keep tool-specific instructions small. If the file becomes a substitute for missing repository documentation, engineers will stop maintaining it and the agent will receive stale guidance. For a more complete reusable operating layer, the PairFoundry Agent Operating Kit packages this constraint-first approach; the other available workflows are listed in the PairFoundry packs overview.
Photo by Al Nahian on Pexels.
What to skip#
Skip any setup step that adds ceremony without improving scope control, verification, or recovery. Most Claude Code tutorials overinvest in prompt collections, elaborate personas, and broad automation. Those additions create the appearance of maturity while leaving the important questions—what may change, how correctness is proven, and who reviews the diff—unanswered.
| Common tutorial step | Why to skip it | |---|---| | Installing many integrations immediately | Each integration expands what the agent can access before you know what it needs. | | Copying a giant global instruction file | Generic rules conflict with repository-specific conventions and become hard to audit. | | Building a prompt library first | Reusable prompts cannot compensate for missing tests or undocumented invariants. | | Asking the agent to “learn the whole codebase” | The request has no completion boundary and loads irrelevant context. | | Enabling broad autonomous execution | Autonomy magnifies unclear acceptance criteria; it does not repair them. | | Starting with a large refactor | A wide diff makes incorrect assumptions expensive to identify and reverse. | | Accepting generated tests as sole proof | Tests written alongside an implementation can encode the same mistaken assumption. |
Also skip cosmetic configuration until a real task demonstrates a need for it. A status display, alias, or custom workflow may reduce friction later, but none of them makes an unsafe task safe.
The official documentation should remain your reference for supported Claude Code behavior. Repository policy should not invent tool features or depend on undocumented tricks. If your team still needs the foundations before adopting a packaged workflow, use PairFoundry’s free foundations track and the broader agent setup guides.
First real task#
Make the first real task a small bug fix with an existing reproduction and test surface. The goal is not to demonstrate how much Claude Code can change; it is to validate your operating rules under realistic conditions while keeping the diff easy to understand, verify, and reverse.
A strong first request looks like this:
Investigate the failing behavior described below. Do not edit files yet.
First:
1. Identify the execution path and relevant tests.
2. State the invariant that is being violated.
3. Propose the smallest fix and list the files it would change.
4. Name the targeted and repository-wide verification commands.
5. Stop for approval before implementation.
Failure: [paste the reproduction, error, or failing test here]After approving the plan, authorize only the proposed scope. Require the targeted test, then the full acceptance commands from CLAUDE.md. If the investigation reveals that the task requires a migration, public API change, new dependency, or unrelated cleanup, stop and redefine the task instead of stretching the original approval.
That pause is not wasted time. It is the control that separates assisted engineering from uncontrolled code generation.
Photo by Jakub Zerdzicki on Pexels.
Related reading#
- Installing Claude Code: a working configuration, explained line by line
- Claude Code tutorial — the setup that survives a real repo
FAQ#
Should Claude Code be allowed to run every repository command?#
No. Allow the commands needed to inspect and verify the scoped task, while treating deployment, credential access, destructive database operations, publishing, and irreversible generation as separate approvals. The relevant boundary is impact, not convenience.
How is this different from following the official Claude Code setup?#
The official Claude Code documentation explains how the tool works and which capabilities it supports. This workflow defines the repository-side contract the official setup cannot supply: local invariants, acceptance commands, prohibited changes, review scope, and recovery discipline.
What usually goes wrong when a team shares one CLAUDE.md?#
The file becomes either vague or enormous. Keep shared rules limited to stable repository facts, review changes to it like code, and remove instructions that no longer match the build or architecture. Personal preferences should not masquerade as team policy.
How do I recover when Claude Code changes too much?#
Stop the session, inspect the diff, preserve any independently useful change, and revert the rest through your normal version-control workflow. Do not ask the agent to repair an undefined scope repeatedly; return to a clean baseline and issue a narrower task with explicit file and behavior boundaries.
When should I not use Claude Code?#
Do not delegate a change whose success criteria you cannot state or verify. Security-critical decisions, irreversible production operations, poorly understood migrations, and architectural changes without an accountable human owner require clarification first, not a more elaborate prompt.