What is a repo boundary in CLAUDE.md?

A repo boundary tells the agent where source files live, what is generated, what is owned by another system, and what should not be changed during normal tasks.

Should CLAUDE.md mention dirty git status?

Yes. Shared worktrees need rules like do not revert unrelated changes and stage only task-related files.

Can this reduce accidental refactors?

Yes. Clear boundaries make it easier for the agent to keep edits scoped to the requested behavior.

Agent instruction guide

CLAUDE.md Repo Boundaries and Rules

Write CLAUDE.md rules that tell agents which files to edit, which files to avoid, and how to handle dirty worktrees safely.

Direct answer

CLAUDE.md should make repo boundaries explicit: which folders are source, generated, docs, infra, or deploy output; which files should not be edited; how to handle dirty worktrees; and what verification is required before final. Boundary rules prevent agents from making broad unrelated changes just to satisfy a narrow task.

Open CLAUDE.md Reviewer

When to use this

The repo has generated output, vendored files, migrations, or deploy artifacts.
Agents keep touching unrelated files.
Multiple people or agents work in the same worktree.

Steps

Name source folders, generated folders, docs folders, and deploy output.
List files or directories that require extra care.
Add dirty-worktree rules.
Define the expected edit scope for normal tasks.
Run the reviewer and tighten any vague boundaries.

Example review focus

CLAUDE.md excerpt

# CLAUDE.md

## Project
Next.js static export.

## Rules
- Follow existing patterns.
- Be safe with files.

What to fix

Replace vague safety language with concrete boundaries: source lives in `src/`, static files in `public/`, export output in `out/`, and generated build artifacts should not be manually edited. Add `do not revert unrelated user changes` and `stage only files related to the task`.

Common mistakes

Do not say be careful when you can name the exact file boundary.
Do not let generated output and source files look equally editable.
Do not forget dirty-worktree rules for shared workspaces.

FAQ

What is a repo boundary in CLAUDE.md?: A repo boundary tells the agent where source files live, what is generated, what is owned by another system, and what should not be changed during normal tasks.
Should CLAUDE.md mention dirty git status?: Yes. Shared worktrees need rules like do not revert unrelated changes and stage only task-related files.
Can this reduce accidental refactors?: Yes. Clear boundaries make it easier for the agent to keep edits scoped to the requested behavior.

Related CLAUDE.md guides

Review CLAUDE.md for Token Waste

Find vague, repeated, or unused CLAUDE.md instructions that cost tokens every Claude Code turn without improving behavior.

CLAUDE.md Missing Commands Checklist

Check whether a CLAUDE.md includes the build, test, lint, dev server, deploy, and verification commands an agent needs before editing.

Review CLAUDE.md Before Converting to AGENTS.md

Clean a CLAUDE.md first, then convert it into AGENTS.md, Cursor rules, GitHub Copilot instructions, or Windsurf rules.

What Should Go in a CLAUDE.md File

Decide what belongs in CLAUDE.md and what belongs in the README, a path-scoped rule, or a skill. One test per line, applied to a real file.

Claude Code Is Not Following CLAUDE.md — How to Fix It

Diagnose why Claude Code ignores your CLAUDE.md: the file never loaded, the rule is vague, two files contradict, or the rule needs a hook instead.

CLAUDE.md vs .claude/rules vs Skills — Which File Owns What

Route each instruction to the right file: always-loaded CLAUDE.md, path-scoped .claude/rules/, or on-demand skills. One question decides it.

CLAUDE.md Best Practices Checklist — Audit Your File Against 8 Rules

Run your CLAUDE.md through eight checks: size, specificity, exact commands, anti-patterns, structure, contradictions, enforcement, and staleness.

Desk gear for long writing sessions

A few things that help if you write docs, tickets, and specs on a laptop all day.

Dock

Anker 5-in-1 USB-C Hub

One cable turns a laptop into a desk setup. Drives a 4K display, charges at up to 85W, and adds three data ports.

4K HDMI output
85W max power delivery
1x USB-C + 2x USB-A, 5Gbps each
MacBook Pro, MacBook Air, Dell

Check price on Amazon →Monitor · I use this

Dell 27" S2725QC 4K

The monitor I write and review documents on. 163 PPI keeps small text sharp, and USB-C carries video and power on one cable.

3840x2160 IPS, 163 PPI
120Hz, 4ms, FreeSync Premium
99% sRGB
USB-C, HDMI, DisplayPort

Check price on Amazon →Laptop

Apple MacBook Neo 13" (A18 Pro)

The cheapest way into an Apple-silicon machine that runs local models. Fanless, and the Liquid Retina panel holds small text at a full day of reading.

A18 Pro chip, built for Apple Intelligence
8GB unified memory, 256GB SSD
13-inch Liquid Retina display
1080p FaceTime HD camera

Check price on Amazon →

Amazon affiliate links. We earn a commission on qualifying purchases at no extra cost to you.