How to Use Claude Code Effectively: CLAUDE.md, AGENTS.md, and Rules

August 2026 · Published by Amar Kumar

Claude Code works brilliantly in one session, then forgets everything the next day — or ignores instructions buried in a 400-line rules file. The fix is not more prompts. It is knowing what belongs in CLAUDE.md, what goes in .claude/rules, and how to wire verification so the agent actually stops when tests pass.

Claude Code is an agent, not a chatbot. It reads files, runs shell commands, and edits your repo autonomously. The difference between a frustrating session and one you can walk away from is project memory: what you put in CLAUDE.md, how you wire AGENTS.md, when to use .claude/rules/, and how you prompt with verification loops.

This guide is a practical setup reference — file templates, what belongs where, and workflow habits that actually stick.

The memory stack

Claude Code loads instructions at session start. Think of it as layers — broadest first, most specific last:

Key distinction: CLAUDE.md and rules are instructions you write. Auto memory is notes Claude writes from corrections. Skills are procedures that load on demand.

Run /context after starting a session to confirm what loaded. Run /memory to inspect auto memory.

What CLAUDE.md should contain

Target under 200 lines. Everything in root CLAUDE.md loads into every session and burns context. If removing a line wouldn't cause Claude to make mistakes, cut it.

Include

• Build and test commands — exact strings, not "run the tests"
• Project layout — where API handlers, migrations, and configs live
• Non-obvious conventions — things Claude can't infer from code alone
• Git workflow — branch naming, commit style, never push to main
• Verification command — the one check Claude should run before stopping
• Security boundaries — no prod credentials, ask before destructive ops

Exclude

• Generic advice ("write clean code")
• Full API docs (link to docs instead)
• File-by-file codebase tour (Claude can grep)
• Long tutorials (use a skill)
• Info that changes weekly (put in a path-scoped rule)

Starter template

# Project: acme-api

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Layout
- `src/api/handlers/` — HTTP route handlers
- `src/db/` — Drizzle schema and migrations
- `src/lib/` — shared utilities (no business logic)

## Code style
- TypeScript strict mode; no `any` without a comment
- 2-space indent

## Workflow
- Create a feature branch before edits
- Run `pnpm test && pnpm lint` before committing
- IMPORTANT: never commit `.env` or secrets

## Verification
After any change under `src/api/`, run:
`pnpm test src/api/`

Generate a first draft

cd your-repo
claude
# then inside Claude Code:
/init

/init scans your repo and proposes a starter CLAUDE.md. Refine from there — add only what Claude got wrong twice.

Use @path/to/file imports to pull in shared docs without duplicating:

@AGENTS.md

## Claude-specific
- Use plan mode for changes under `src/billing/`
- Run `pnpm test src/billing/` after billing edits

What AGENTS.md should contain

AGENTS.md is an open standard used by Cursor, Codex, Devin, and other agents. Claude Code does not read AGENTS.md automatically — it reads CLAUDE.md.

If your team already maintains AGENTS.md, don't duplicate. Bridge them:

Option A — import (recommended)

@AGENTS.md

## Claude Code
- Prefer plan mode for database migrations
- Use `claude -p` in CI for automated fix loops

Option B — symlink (macOS/Linux)

ln -s AGENTS.md CLAUDE.md

Option C — one-time import

Run /import inside Claude Code (v2.1.213+) to copy supported agent configs including AGENTS.md, .cursor/rules/, MCP servers, and skills.

What belongs in AGENTS.md

Write agent-agnostic instructions any coding agent should follow:

Keep Claude-only or Cursor-only quirks in CLAUDE.md or .cursor/rules/ — not in AGENTS.md.

Mirror with Cursor

AGENTS.md              ← shared team rules (committed)
CLAUDE.md              ← @AGENTS.md + Claude-specific notes
.cursor/rules/*.mdc    ← Cursor-specific (Tab, Composer hints)

Path-scoped rules in .claude/rules/

When CLAUDE.md grows past ~150 lines, split topic-specific instructions into .claude/rules/. One file per topic:

.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md
    ├── api-design.md
    ├── frontend/
    │   └── react.md
    └── backend/
        └── database.md

Rules without frontmatter load every session. Rules with paths load only when Claude reads matching files — saving context.

Path-scoped example

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.tsx"
---

# API rules

- All endpoints return `{ data, error }` envelope
- Validate input with Zod schemas in `src/api/schemas/`
- Add OpenAPI comments on every exported handler

When to use rules vs skills

Personal and user-level config

CLAUDE.local.md (project, gitignored)

Personal sandbox URLs, test accounts, local DB names. Add to .gitignore:

CLAUDE.local.md

~/.claude/CLAUDE.md (user, all projects)

# Personal preferences
- Prefer concise commit messages
- Always show git diff summary before committing

~/.claude/rules/ (user, all projects)

Same format as project rules. Loaded before project rules — project wins on conflict.

Essential settings.json

Project settings live in .claude/settings.json. Local overrides in .claude/settings.local.json (usually gitignored).

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Read(.env)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

CLAUDE.md = soft guidance. Settings permissions = hard enforcement. Use PreToolUse hooks when you need to block actions regardless of what Claude decides.

Session workflow that works

1. Explore → plan → implement

Press Shift+Tab for plan mode (or claude --permission-mode plan). Claude reads and plans without editing. Approve the plan, then implement. Skip planning for one-line fixes.

2. Give Claude a verification loop

Add rate limiting to POST /api/login.
Write a test that sends 11 requests and expects 429 on the 11th.
Run pnpm test src/api/login.test.ts and fix until green.

Without a check, you become the verification loop.

3. Scope prompts with @ files

@src/auth/session.ts fix the token refresh bug described in #842.
Match error handling in @src/auth/login.ts.

4. Use /doctor on bloated CLAUDE.md

Claude proposes cuts for content it can derive from the codebase. Treat CLAUDE.md like code — review when behavior drifts.

5. Headless CI with claude -p

claude -p "Fix the failing test in src/api/health.test.ts. Run pnpm test after."

Example repo layout

my-app/
├── AGENTS.md                 # Shared agent instructions (team)
├── CLAUDE.md                 # @AGENTS.md + Claude-specific
├── CLAUDE.local.md           # Personal (gitignored)
├── .gitignore
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── rules/
│   │   ├── testing.md
│   │   └── api-design.md
│   ├── skills/
│   │   └── release/SKILL.md
│   └── commands/review.md
├── src/billing/CLAUDE.md     # Loads when editing billing/
└── .cursor/rules/            # Cursor-only (optional)

Common mistakes

1. 500-line CLAUDE.md — Claude ignores buried rules. Split into path-scoped .claude/rules/.
2. Duplicating AGENTS.md in CLAUDE.md — use @AGENTS.md import instead.
3. No test command — Claude stops when code "looks done" instead of when tests pass.
4. Contradicting rules — Claude picks one arbitrarily.
5. Skills for static facts — belongs in CLAUDE.md or a rule, not a skill.
6. Two agents editing at once — Cursor and Claude Code on the same branch causes conflicts.
7. Never pruning — outdated instructions cause more harm than none.

FAQ

How long should CLAUDE.md be?

Under 200 lines. Move domain-specific content to path-scoped rules or skills.

Does Claude Code read AGENTS.md?

Not directly. Create CLAUDE.md with @AGENTS.md at the top, symlink, or run /import.

What's the difference between CLAUDE.md and .claude/rules/?

Root CLAUDE.md loads every session. Rules split instructions by topic; path-scoped rules load only when relevant files are read.

Should I commit CLAUDE.local.md?

No. Add it to .gitignore.

How do I check if instructions loaded?

Run /context in a Claude Code session.

CLAUDE.md vs auto memory?

You write CLAUDE.md. Claude writes auto memory from your corrections.

Related guides

• Claude Code vs Cursor vs Copilot: Which Should You Use?
• Skills vs MCP vs Subagents: When to Use Each
• How to Migrate Cursor Chat to Claude Code
• How to Build a Cursor-Like AI Coding Agent