Claude Code configuration in fifteen minutes, and what to skip

On this page#

• Before you install anything
• The steps
• A working configuration
• Scope
• Invariants
• Workflow
• Verification
• Handoff
• What to skip
• First real task
• FAQ

Before you install anything#

Configure the repository before the agent, because installation only makes Claude Code available; it does not define safe behavior. The correct order is to identify invariants, establish a clean rollback point, encode repository instructions, narrow permissions, and only then give the agent a bounded task.

Claude Code is an agentic coding tool: it can inspect a repository, edit files, and run permitted commands from the terminal. Anthropic’s Claude Code overview explains the product mechanics; your repository must supply the operational boundaries that the product cannot infer.

Write down three things first:

• Repository invariants: behavior that must remain true, such as compatibility, public API shape, generated-file rules, or migration constraints.
• Verification commands: the smallest commands that prove a change is acceptable.
• Forbidden actions: operations whose convenience does not justify their blast radius.

Do this in repository-owned files, not personal notes. If a second engineer cannot discover the rules from a fresh checkout, the configuration is incomplete.

A clean working tree matters for the same reason. The useful rollback unit is a small, attributable diff. Starting with unrelated changes makes review harder and gives both the agent and the next engineer an ambiguous baseline.

Photo by Boris K. on Pexels.

The steps#

Use the following sequence. Each step removes one specific failure mode, and none requires a sprawling agent framework. The goal of claude code configuration is not maximum autonomy; it is a narrow, inspectable path from request to verified diff.

1. Start from a clean branch and inspect git status — this prevents pre-existing work from being mistaken for agent output.

2. Write repository instructions in CLAUDE.md — this prevents important constraints from living only in prompts, shell history, or one engineer’s memory.

3. Name the allowed change surface — this prevents a local task from turning into an unsolicited refactor across unrelated directories.

4. Specify exact verification commands — this prevents “looks correct” from replacing the repository’s actual acceptance checks.

5. Create project-level permission rules — this prevents one developer’s permissive local setup from silently becoming the team standard.

6. Allow read operations and narrowly scoped verification commands — this keeps normal inspection fast without granting broad shell authority.

7. Deny secrets, destructive Git operations, deployment, and publication — this stops high-impact actions even when a prompt is vague or mistaken.

8. Run one small maintenance task and review the diff manually — this exposes missing instructions before the configuration is used on consequential work.

Keep the configuration in version control so changes receive ordinary review. Anthropic’s official Claude Code documentation is the authority for supported configuration syntax; your repository remains the authority for what Claude Code may do inside it.

For a fuller repository policy, review checklist, and handoff structure, the PairFoundry Agent Operating Kit is the direct next step. The important principle is ownership: configuration should travel with the code whose behavior it governs.

A working configuration#

Use two project files: CLAUDE.md for operational instructions and .claude/settings.json for enforceable permissions. Instructions tell the agent what correct work looks like; permissions constrain what it can access or execute. Treating either file as a substitute for the other is a configuration error.

CLAUDE.md#

# Repository operating rules


![A female engineer works on code in a contemporary office setting, showcasing software development. — illustrating claude](/blog/claude-code-configuration-2.jpg)
*Photo by ThisIsEngineering on [Pexels](https://www.pexels.com/photo/female-software-engineer-coding-on-computer-3861951/).*

## Scope
- Make only the change requested.
- Do not refactor adjacent code unless the requested change requires it.
- Do not edit generated files directly.
- Stop and explain if repository instructions conflict.

## Invariants
- Preserve existing public interfaces unless the task explicitly changes them.
- Preserve backward compatibility.
- Do not weaken validation, authorization, or error handling.
- Do not add dependencies without explicit approval.


![Close-up of colorful programming code on a blurred computer monitor. — illustrating claude code configuration](/blog/claude-code-configuration-3.jpg)
*Photo by Al Nahian on [Pexels](https://www.pexels.com/photo/computer-program-on-computer-screen-7325498/).*

## Workflow
1. Read the relevant implementation and tests before editing.
2. State the intended change surface.
3. Make the smallest coherent patch.
4. Run the narrowest relevant verification command.
5. Review the final diff for unrelated changes.

## Verification
- Run the repository's documented formatter.
- Run tests covering the changed behavior.
- Run broader checks only when the change crosses module boundaries.
- Report commands that could not be run; never claim they passed.

## Handoff
- Summarize behavior changed.
- List files changed.
- List verification commands and outcomes.
- Call out assumptions, residual risk, and follow-up work.

Every section has one job:

| Section | What it prevents | |---|---| | Scope | Opportunistic cleanup and uncontrolled expansion | | Invariants | Locally plausible changes that violate repository contracts | | Workflow | Editing before understanding and oversized patches | | Verification | Unsupported claims of correctness | | Handoff | A diff that the next engineer cannot safely continue |

Replace generic verification bullets with exact repository commands once the team has agreed on them. Do not invent commands merely to make the file look complete.

.claude/settings.json#

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Bash(git push:*)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

The logic is deliberately conservative:

• Read, Glob, and Grep allow repository discovery.
• git status and git diff allow inspection without publication.
• .env rules keep common secret-bearing files outside the readable surface.
• git push, destructive reset, and recursive deletion remain unavailable.

Add formatter or test commands only after confirming their exact repository form in the official configuration documentation. Do not grant unrestricted shell access because one verification command is inconvenient to express narrowly.

What to skip#

Skip any setup step that adds ceremony without improving constraints, verification, or handoff. Most configuration tutorials optimize for an impressive first demonstration. A production repository needs predictable diffs and recoverable mistakes, not a long list of integrations enabled before anyone knows why they are needed.

Do not spend the first fifteen minutes on:

• A global instruction manifesto. Repository rules belong with the repository. Global preferences should be rare and non-semantic.
• Unrestricted shell approval. It converts a bounded coding tool into a broad workstation operator.
• Every available integration. Add one only when a real task requires it and its authority is understood.
• Elaborate role prompts. “Act as a senior engineer” does not encode an invariant or verify a change.
• Multiple nested instruction files immediately. Begin with one clear project policy; split it only when directory-specific rules genuinely differ.
• Premature hooks and automation. A hook that runs the wrong command reliably is still wrong.
• A giant list of style rules already enforced by tooling. Point to the formatter and run it.
• Automatic commits or pushes. Review is a boundary, not administrative friction.
• Copying another repository’s configuration unchanged. Permissions and invariants are repository-specific.

If the repository is not ready for a packaged operating model, use the free PairFoundry foundations track. The broader PairFoundry packs overview is useful when the missing piece extends beyond agent setup.

First real task#

Choose a small, existing defect with a clear expected result, relevant tests, and no deployment requirement. The first task should validate the configuration itself: whether Claude Code finds the right instructions, stays inside scope, runs the permitted checks, and produces a handoff another engineer can verify.

Good first tasks include:

• Add a regression test for a known edge case, then make the smallest fix.
• Correct a deterministic validation error with an established test location.
• Update one internal API call after a repository-local interface change.
• Remove a dead branch when existing tests already cover surrounding behavior.

Avoid migrations, authentication changes, dependency upgrades, broad refactors, and production incidents. Those tasks combine too many risks to reveal whether the configuration is working.

Before accepting the result, inspect git diff, rerun the stated verification yourself, and compare the handoff against the actual files. If the agent crossed scope, missed an invariant, or requested excessive permission, fix the repository configuration before writing a cleverer prompt.

For more setup-specific material, use the PairFoundry agent setup hub.

Related reading#

• How to build an MCP server in fifteen minutes, and what to skip
• How to run Claude Code in terminal in fifteen minutes, and what to skip

FAQ#

How narrow should team permissions be?#

Start with repository reading, search, diff inspection, and the exact commands needed to verify ordinary changes. A permission should exist because a recurring task requires it, not because it might be convenient later. Keep publishing, deployment, secret access, destructive Git operations, and broad deletion outside the default project policy.

How is this different from following the official setup?#

The official documentation explains supported features and configuration mechanics. This setup makes repository decisions the center of the process: invariants, change boundaries, verification, rollback, and handoff. Use Anthropic’s Claude Code overview for product behavior, then encode your team’s narrower operating rules locally.

What usually breaks when a second engineer takes over?#

Personal permissions, undocumented commands, and assumptions hidden in the original prompt break first. The second engineer may receive different approvals or interpret the task differently. Version-controlled instructions, exact verification commands, and a required handoff make the workflow transferable instead of dependent on one person’s terminal state.

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

Stop the task, inspect the diff, and revert only the attributable agent changes using your normal reviewed Git workflow. Do not reach reflexively for destructive reset commands. Then correct the missing scope rule, invariant, or permission boundary before retrying from a clean working state.

When should I not use this setup?#

Do not start with an agent when the expected behavior is unknown, the repository has no credible verification path, or the task requires uncontrolled access to secrets or production systems. Resolve those operational gaps first. An agent cannot compensate for an acceptance criterion that the team itself has not defined.