What Should I Put in CLAUDE.md for Better Autonomous Claude Code Sessions?

Mar 23, 2026

Problem

My autonomous Claude Code sessions kept going off the rails. I would start a 5-minute task, and 20 minutes later Claude had refactored half the repository, created files in the wrong locations, and used naming conventions from a different project.

Here’s what happened during one session:

User: Add a loading spinner to the dashboard component

[Claude proceeds to:]
1. Create 3 new utility files in src/utils/
2. Refactor the entire state management in src/store/
3. Add tests to tests/ folder (but project uses __tests__/)
4. Rename 4 existing components for "consistency"
5. Never actually adds the spinner

I watched in frustration as Claude made incorrect inferences about my project. It guessed file locations wrong. It applied patterns from its training data instead of my existing codebase. Each decision cascaded into more wrong decisions.

What Happened?

I searched for solutions and found a Reddit thread about CLAUDE.md best practices. The core issue became clear: Claude performs inference when it lacks explicit context.

During autonomous sessions, this leads to:

Drift: Claude gradually deviates from project conventions
Over-refactoring: Claude modifies files it shouldn’t touch
Time waste: Simple tasks balloon because Claude infers incorrectly
Inconsistency: Different sessions produce different patterns

One comment hit home:

“What you put in CLAUDE.md matters more than any flag for long autonomous runs. File naming conventions, known bad patterns, which files own what - if CC has to infer that, it will, and it’ll be wrong.”

Another user explained:

“Explicit file-path patterns in your CLAUDE.md. Listing exactly which files and dirs Claude is allowed to touch stops the ‘decided to refactor half the repo’ problem that derails autonomous sessions more than any flag combination.”

The Solution

I restructured my CLAUDE.md with three essential sections:

1. Working Relationship

Define how I want Claude to communicate:

# Working Relationship

- Be concise. Avoid long-winded explanations.
- I don't like sycophancy. Challenge my assumptions.
- If creating a `git commit` do not add yourself as a co-author.
- Never use emojis in code.

These preferences apply universally across all projects. They prevent Claude from wasting tokens on unnecessary politeness.

2. File-Path Boundaries

Explicitly declare which directories Claude can modify:

## Allowed Files

- src/components/ (React components)
- src/utils/ (Utility functions)
- src/hooks/ (Custom hooks)
- tests/ (Test files)

## Restricted Files

- node_modules/ (Never modify)
- dist/ (Build output - never modify)
- .env* (Secrets - never expose or modify)
- src/legacy/ (Legacy code - refactor only with explicit approval)

This stopped the “refactor half the repo” problem immediately.

3. Project Conventions

Document patterns Claude must follow:

## Coding Style

### Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate:

```javascript
// WRONG
function updateUser(user, name) {
  user.name = name
  return user
}

// CORRECT
function updateUser(user, name) {
  return { ...user, name }
}

File Organization

MANY SMALL FILES > FEW LARGE FILES:

200-400 lines typical, 800 max
Extract utilities from large components
Organize by feature, not by type

### 4. Architecture Decisions

Record key decisions Claude must respect:

```markdown title="CLAUDE.md"
## Architecture Decisions

### State Management
- Use Zustand for global state (NOT Redux)
- Use React Query for server state
- Local state with useState for UI-only state

### Known Bad Patterns (AVOID)
- Do NOT use useEffect for data fetching (use React Query)
- Do NOT use inline styles (use Tailwind classes)
- Do NOT create new files in src/pages/ (use src/routes/)

The 50% Rule

A Reddit user shared a principle that changed my approach:

“Judiciously put only relevant things in CLAUDE.md. Things that are at least 50% always relevant.”

I went through my CLAUDE.md and removed everything that didn’t meet this threshold:

Removed:

Specific API endpoint URLs (changes too often)
Database connection strings (belongs in .env)
Team member names (irrelevant to Claude)
Sprint schedules (not useful for code generation)

Kept:

Naming conventions (always relevant)
File size limits (always relevant)
Error handling patterns (always relevant)
Testing requirements (always relevant)

The result: Claude now follows my instructions without needing constant correction.

Testing the Changes

I ran the same “add loading spinner” task after updating CLAUDE.md:

User: Add a loading spinner to the dashboard component

[Claude proceeds to:]
1. Check src/components/ for existing spinners
2. Find Spinner component already exists
3. Add loading state to Dashboard component
4. Import and use existing Spinner
5. Add test in tests/components/Dashboard.test.tsx
6. Task complete - 3 minutes

No unnecessary refactoring. No wrong file locations. No incorrect patterns.

Why This Matters

CLAUDE.md is the single most effective tool for autonomous session quality because:

Persistence: It survives across all sessions (no re-explanation needed)
Eliminates inference errors: Claude has explicit rules instead of guessing
Prevents scope creep: File boundaries stop over-reaching changes
Encodes institutional knowledge: New team members get the same experience

I also learned to document anti-patterns. Knowing what NOT to do is as important as what TO do:

## Anti-Patterns (NEVER DO)

- Never use `any` type in TypeScript
- Never skip error handling in async functions
- Never hardcode API URLs (use environment variables)
- Never create files over 800 lines

Summary

For better autonomous Claude Code sessions, put three things in your CLAUDE.md:

Project conventions and architecture decisions - so Claude follows your patterns
Explicit file-path patterns - so Claude only modifies what it should
Personal preferences that are 50%+ always relevant - so Claude communicates your way

Start with a minimal file and iterate. Watch where Claude drifts, then add explicit rules for those areas. Within a few sessions, you’ll have a CLAUDE.md that keeps autonomous tasks on track.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion: Must-have settings for Claude Code

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!