September 8, 2026 · How-to · EN

How to Prepare Your Repository for Claude Code in 2026

Prepare a repository for Claude Code with CLAUDE.md, portable AGENTS.md imports, scoped rules, shared settings, skills, hooks, permissions, and clean-session validation.

How to Prepare Your Repository for Claude Code in 2026

The common Claude Code setup starts with a long prompt.

The prompt explains the architecture. It repeats the test commands. It warns Claude not to touch migrations. Then the next session starts with none of it.

Here is the real problem: task prompts are temporary, but repository rules need to survive every session.

Claude Code now has a clear repository configuration model: CLAUDE.md for persistent instructions, .claude/rules/ for scoped guidance, project settings for shared permissions and hooks, and skills for reusable workflows. A reliable setup gives each kind of context one owner.

This guide follows Anthropic’s current documentation for memory and CLAUDE.md, the .claude directory, extensions, permissions, and hooks.

The short answer

Prepare the repository in this order:

1. Add a root CLAUDE.md with the context every Claude Code session needs.
2. If the repository already uses AGENTS.md, import it from CLAUDE.md instead of copying it.
3. Put path-specific instructions in .claude/rules/*.md or nested CLAUDE.md files.
4. Commit .claude/settings.json only for shared team configuration.
5. Put repeatable workflows in .claude/skills/.
6. Use permissions and hooks for rules that must be enforced.
7. Verify the setup in a clean session with /context and an evidence-based handoff.

A practical starting tree looks like this:

repository/
├── AGENTS.md                         # portable repository contract
├── CLAUDE.md                         # imports AGENTS.md + Claude-specific delta
├── docs/
│   ├── architecture.md
│   └── decisions/
├── scripts/
│   ├── validate.sh
│   └── check-migration.sh
└── .claude/
    ├── settings.json                 # shared permissions and hooks
    ├── settings.local.json           # personal overrides, not committed
    ├── rules/
    │   ├── frontend.md
    │   └── migrations.md
    └── skills/
        └── verify-change/
            └── SKILL.md

The setup is small. The boundaries are explicit. Every file has one job.

Correction: Claude Code reads CLAUDE.md, not AGENTS.md

Older versions of this guide said Claude Code reads AGENTS.md automatically. That was wrong.

Anthropic’s current documentation is explicit: Claude Code reads CLAUDE.md, not AGENTS.md. A repository can still keep AGENTS.md as the portable contract for Codex, Cursor, and other tools. Claude Code needs a bridge.

Create a root CLAUDE.md like this:

@AGENTS.md

## Claude Code

- Use plan mode before changing files under `src/billing/`.
- Use the `verify-change` skill before handoff.
- Run `/context` when instruction loading looks wrong.

The @AGENTS.md import loads the shared contract without duplicating it. The remaining section contains only the Claude-specific delta.

A symlink also works:

ln -s AGENTS.md CLAUDE.md

Use the import when the repository must work cleanly on Windows or needs Claude-specific additions. Use the symlink only when one identical file is enough and the team is comfortable with platform differences.

Do not maintain two copied instruction files. They will drift. One command changes in AGENTS.md, the stale copy survives in CLAUDE.md, and two agents receive different definitions of done.

For a cross-tool repository, use the AGENTS.md template as the portable base and keep CLAUDE.md thin.

What belongs in CLAUDE.md

CLAUDE.md should contain the facts Claude needs in almost every session.

Keep it concise. Anthropic recommends moving reference material out when the file grows beyond roughly 200 lines. Long context is not the same as useful context — the important commands become harder to find as the file turns into a documentation archive.

A strong root file answers six questions.

1. What does this repository do?

Use one sentence. Name the system boundary, not the company mission.

This service receives subscription events, calculates billing state, and publishes an immutable ledger entry.

2. Where should Claude start reading?

Point to entry points and authoritative documents.

## Read first

- `src/http/` owns request parsing and authentication.
- `src/billing/` owns billing decisions.
- `docs/architecture.md` describes event flow and retry behavior.
- `docs/decisions/` records accepted architectural decisions.

3. What are the ownership boundaries?

Name generated files, shared modules, and approval gates.

## Boundaries

- Do not edit `src/generated/`; regenerate it with `npm run generate`.
- Do not create or apply migrations without approval.
- Do not change authentication, billing, or secret handling outside the task scope.
- Stop when the requested change crosses a service contract not named in the task.

4. Which commands prove the change?

Do not write “run the tests.” Give Claude a deterministic command for each change type.

## Validation

- Application change: `npm test && npm run typecheck && npm run build`
- API contract change: `npm run test:contract`
- Database migration: `npm run migration:validate`, then request review
- Documentation-only change: `npm run lint:docs`

The script or CI job is the source of truth. CLAUDE.md points to it.

5. What must the handoff contain?

A green command is not a complete handoff.

## Handoff

Report:
- files changed;
- commands run and their results;
- checks not run;
- assumptions made;
- residual risks;
- one recommended next action.

The coding-agent handoff template turns this into a reusable protocol across Claude Code, Codex, and clean sessions.

6. Where does deeper context live?

Link to canonical documents. Do not paste them into CLAUDE.md.

## Sources of truth

- Architecture: `docs/architecture.md`
- API schema: `openapi/api.yaml`
- Database schema: `db/schema.sql`
- Accepted decisions: `docs/decisions/`
- Release process: `.claude/skills/release/SKILL.md`

This keeps the startup context small while preserving a path to deeper evidence.

Use scoped rules for local context

A monorepo does not need every frontend rule in every backend task.

Claude Code supports .claude/rules/*.md. Rules can be always-on or scoped with paths frontmatter so they load when Claude works with matching files.

---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# Frontend rules

- Reuse `src/design-system/` before adding a new primitive.
- Preserve keyboard navigation and visible focus states.
- Run `npm run test:components` and `npm run build` before handoff.

Use a separate migration rule:

---
paths:
  - "db/migrations/**"
  - "src/db/**"
---

# Migration rules

- Every schema change needs a rollback path.
- Never apply a migration outside a disposable database.
- Run `npm run migration:validate` and stop for review.

Nested CLAUDE.md files are useful when a subtree has its own durable operating contract. .claude/rules/ is useful when guidance follows file patterns or you want the configuration visible in one place.

Keep the root file repository-wide. Keep scoped files additive. Do not repeat the same validation command in four locations.

Commit shared settings, not personal exceptions

Claude Code reads settings from multiple scopes.

Use .claude/settings.json for project configuration the team should share: permissions, hooks, plugins, and required environment variables. Commit it so every clone receives the same baseline.

Use .claude/settings.local.json for personal exceptions and experiments. Keep it out of version control.

.claude/
├── settings.json          # shared and committed
└── settings.local.json    # personal and ignored

A shared settings file can make safe commands explicit:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run typecheck:*)",
      "Bash(npm run build:*)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Review the exact permission syntax against Anthropic’s permissions documentation before committing it. Broad wildcards remove useful friction. A repository should allow the checks agents need and preserve review around external writes, secrets, and destructive operations.

Instructions are guidance. Hooks are enforcement.

A sentence in CLAUDE.md changes what Claude tries to do. It does not create a security boundary.

Anthropic documents CLAUDE.md as context, not enforced configuration. If a rule must fire every time, put control in permissions or a hook.

A PreToolUse hook can inspect a proposed action before it runs. A PostToolUse hook can format or validate after a file change. A Stop hook can reject an incomplete handoff.

Use hooks for deterministic policy:

• block edits to generated files;
• reject destructive commands;
• run a formatter after edits;
• require a validation script before completion;
• log which instruction files loaded.

Keep the hook’s script in the repository. Test it directly. Make failure behavior explicit.

Hidden shell fragments inside settings are difficult to review. A small hook entry that calls scripts/check-agent-action.py gives humans and agents one implementation to inspect.

The distinction is simple: CLAUDE.md explains the rule; permissions and hooks enforce the rule.

Put repeatable workflows in skills

The old setup pattern used one .claude/commands.md file. That is not the current project structure.

Claude Code supports command files under .claude/commands/<name>.md, but skills are the more flexible home for reusable knowledge and multi-step workflows. A project skill lives at .claude/skills/<name>/SKILL.md.

.claude/
└── skills/
    └── verify-change/
        └── SKILL.md

---
name: verify-change
description: Verify a code change before handoff.
---

# Verify change

1. Inspect the diff and classify the changed surfaces.
2. Select commands from the repository validation matrix.
3. Run the narrow checks first, then the required aggregate checks.
4. Report commands, results, omissions, and residual risks.

Use a skill when the workflow requires judgment or reusable reference material. Use a hook when the event must always trigger. Use CLAUDE.md when the instruction must remain visible in every session.

That separation prevents one oversized startup file from becoming the repository’s second, stale CI system.

Auto memory is not the repository contract

Claude Code can keep auto memory across sessions. That helps it retain corrections and project-specific learnings.

Auto memory is Claude-written. CLAUDE.md is team-written. They solve different problems.

Do not rely on auto memory for build commands, security boundaries, or release policy. Those facts must be reviewable and version-controlled. Put them in repository files.

Use /memory to inspect memory locations. Use /context to check which instruction files loaded into the current session.

If a useful correction appears repeatedly, promote it into CLAUDE.md, a scoped rule, a skill, or an executable check. Personal memory should not become invisible team policy.

Test the setup in a clean session

Do not validate new repository instructions in the conversation that created them. That session already contains the missing context.

Start a clean Claude Code session. Run /context. Confirm the expected root and scoped files loaded.

Then ask Claude to do four things without editing:

1. summarize the repository’s purpose and architecture boundary;
2. identify the command required for one application change and one migration;
3. name the files it must not edit directly;
4. explain what evidence the final handoff must contain.

Give it one bounded task after those answers are correct.

Review the result against the repository contract, not against whether the patch looks plausible. Run the required commands independently. Confirm that omitted checks and residual risks are visible.

A prepared repository makes the correct next action obvious to a clean session. If Claude must guess, the missing fact still lives in a prompt, a person’s head, or an undocumented convention.

A seven-step migration from an old Claude Code setup

Many repositories still have an old AGENTS.md assumption, one giant instruction file, or a .claude/commands.md that no current workflow owns.

Fix the setup without rebuilding everything.

1. Establish the portable contract. Keep repository-wide truth in AGENTS.md when multiple coding tools need it.

2. Add the Claude bridge. Create CLAUDE.md with @AGENTS.md and only the Claude-specific delta.

3. Remove false startup claims. Search documentation for statements that Claude Code automatically reads AGENTS.md or .claude/commands.md.

4. Split local guidance. Move frontend, backend, migration, and documentation rules into scoped .claude/rules/*.md files.

5. Move procedures into skills. Convert repeated release, review, and deployment prompts into .claude/skills/<name>/SKILL.md.

6. Enforce hard boundaries. Put secret access, generated-file protection, external writes, and destructive actions behind permissions or hooks.

7. Run the clean-session gate. Use /context, a no-edit orientation prompt, one bounded task, and independent validation.

You do not need more prompt text. You need one durable contract, one Claude-specific bridge, and executable proof.

Quick checklist

Before the next Claude Code session:

• Root CLAUDE.md exists.
• A portable AGENTS.md is imported with @AGENTS.md when other tools use it.
• The root instructions name purpose, entry points, boundaries, validation, and handoff evidence.
• Path-specific guidance lives in .claude/rules/ or nested CLAUDE.md files.
• Shared project settings live in committed .claude/settings.json.
• Personal overrides live in .claude/settings.local.json and are ignored by Git.
• Repeatable workflows live in .claude/skills/.
• Hard safety rules use permissions or hooks, not prose alone.
• /context confirms the expected instruction files loaded.
• A clean session can identify the right validation command before editing.
• The final handoff reports evidence, omissions, and residual risks.

Use repository-harness to bootstrap the portable repository contract, validation structure, decision memory, and handoff rules around this Claude Code configuration.

Related pages

• AGENTS.md vs Cursor Rules — separate portable instructions from tool-specific configuration
• How to Write an AGENTS.md That Actually Works — build the shared repository contract
• Context Engineering for Coding Agents — place durable context in the correct layer
• Coding-Agent Handoff Template — require evidence that survives a clean session
• How to Manage Multiple Coding Agents in One Repository — coordinate Claude Code with Codex, Cursor, and other agents
• How to Audit a Repository for Agent-Readiness — score the full repository surface

FAQ

Does Claude Code read AGENTS.md automatically?

No. Claude Code reads CLAUDE.md, not AGENTS.md directly. If the repository uses AGENTS.md as its portable contract, create a root CLAUDE.md containing @AGENTS.md and add Claude-specific instructions below it. A symlink also works when cross-platform compatibility is not required.

What should go in CLAUDE.md?

Put concise, always-relevant repository instructions in CLAUDE.md: purpose, entry points, architecture boundaries, exact validation commands, generated-file rules, and review expectations. Move path-specific guidance into .claude/rules/ and repeatable procedures into skills.

Should a team commit .claude/settings.json?

Yes, when the file contains shared project permissions, hooks, plugins, or environment configuration. Keep personal exceptions in .claude/settings.local.json and out of version control.

Are CLAUDE.md safety instructions enforced?

No. Claude Code treats CLAUDE.md as context, not as an enforcement boundary. Use permission rules or a PreToolUse hook when an action must always be allowed, reviewed, or blocked.

Where should reusable Claude Code workflows live?

Use a project skill under .claude/skills/<name>/SKILL.md for reusable knowledge or multi-step workflows. Existing .claude/commands/<name>.md files still support slash-command workflows, but skills are the more flexible extension point.

How do I check which instructions Claude Code loaded?

Start a clean session and run /context. Confirm that the expected root and scoped CLAUDE.md or .claude/rules files appear, then ask Claude to identify the relevant validation command and boundaries before it edits anything.

Does Claude Code run the right tests automatically?

Not reliably unless the repository defines the commands. Put exact change-type validation in CLAUDE.md or imported repository documentation, make scripts or CI the source of truth, and require the final handoff to report commands, results, omissions, and residual risks.