I started with Github Copilot for my coding assistance, then moved on to Windsurf. Now, I use Claude Code.

Over the past weeks, I have been learning Claude Code. Here are my key takeaways, all while keeping token usage efficient.

Understanding CLAUDE.md’s Precedence Hierarchy

According Claude Code documentation, Claude Code processes CLAUDE.md based on defined precedence hierarchy.

Managed Policy Layer

  • CLAUDE.md that must be enforced organization-wide
  • location -> etc/claude-code/
  • Owner -> Security/DevOps
  • Shared? -> all machines
  • Overrideable? -> No

User Layer

  • Personal preferences you want everywhere
  • location -> ~/.claude/
  • Owner -> Individual engineer
  • Shared? -> personal only
  • Overrideable? -> By project layer

Project layer

  • Team-shared settings
  • location -> .claude/ in repo
  • Owner -> Repo/team owner
  • Shared? -> Via git
  • Overrideable? -> By local layer

Local Layer

  • Personal overrides for a specific project
  • location -> .claude/settings.local.json
  • Owner -> Individual engineer
  • Shared? -> No (gitignored)
  • Overrideable? -> Highest priority

Here is the table comparison:

LayerLocationOwnerShared?Overridable?
Managed policy/etc/claude-code/Security/DevOpsAll machinesNo
User~/.claude/Individual engineerPersonal onlyBy layers below
Project.claude/ in repoRepo/team ownerVia gitBy local
Local.claude/settings.local.jsonIndividual engineerNo (gitignored)Highest priority

CLAUDE.md precedence hierarchy

When Should You Create a CLAUDE.md for User Layer?

User level / layer CLAUDE.md reside in ~/.claude/CLAUDE.md, it loads at the start of every session automatically.

Based on my experience, I recommend to create user layer CLAUDE.md after a few chat conversations with Claude. Once you have had some interactions, ask Claude to generate user-scope CLAUDE.md. Since Claude reviews all chat history, it will produce more relevant CLAUDE.md tailored to you.

By default, when you ask “generate a user-level CLAUDE.md for me”, Claude Code will generate something generic based on your interactions.

However, we can explicitly ask to use Auto Memory to generate CLAUDE.md. Auto Memory is written by Claude automatically as we work.

Here are two example prompts to generate user layer CLAUDE.md using Auto Memory:

Read my auto memory across all projects, then generate a ~/.claude/CLAUDE.md
that captures my personal preferences, workflow patterns, and standing
instructions I should have in every session.

Karpathy’s 4 rules + Mnimiy’s 8 Rules for CLAUDE.md

I asked Claude Code to analyze and add relevant Karpathy’s 4 rules + Mnimiy’s 8 rules into the user layer CLAUDE.md.

According Mnimiy’s post:

In late January 2026, Andrej Karpathy posted a thread complaining about how Claude writes code. Three failure modes: silent wrong assumptions, over-complication, orthogonal damage to code it shouldn’t have touched.

Forrest Chang read the thread, packaged the complaints into 4 behavioral rules in a single CLAUDE.md file, and dropped it on GitHub.

The 4 rules work. Mistakes that used to happen ~40% of the time dropped to under 3% on tasks that played to their strengths.

8 more rules. 6 weeks of testing across 30 codebases. Mistake rate from 41% to 3%.

Here is the full 12-rule CLAUDE.md (copy-paste ready):

# CLAUDE.md - 12-rule template

These rules apply to every task in this project unless explicitly overridden.
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

## Rule 1 - Think Before Coding
State assumptions explicitly. If uncertain, ask rather than guess.
Present multiple interpretations when ambiguity exists.
Push back when a simpler approach exists.
Stop when confused. Name what's unclear.

## Rule 2 - Simplicity First
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
Test: would a senior engineer say this is overcomplicated? If yes, simplify.

## Rule 3 - Surgical Changes
Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Don't refactor what isn't broken. Match existing style.

## Rule 4 - Goal-Driven Execution
Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.

## Rule 5 - Use the model only for judgment calls
Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.

## Rule 6 - Token budgets are not advisory
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.

## Rule 7 - Surface conflicts, don't average them
If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.

## Rule 8 - Read before you write
Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

## Rule 9 - Tests verify intent, not just behavior
Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.

## Rule 10 - Checkpoint after every significant step
Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.

## Rule 11 - Match the codebase's conventions, even if you disagree
Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.

## Rule 12 - Fail loud
"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.

Organize rules with .claude/rules/

I use the .claude/rules/ directory to organize instructions into multiple files.

According to Claude Code documentation, this keeps instructions modular and easier for teams to maintain. Rules can also be scoped to specific file paths, so they only load into context when Claude works with matching files, reducing noise and saving context space.

# Example

# rules in project layer

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

# rules in user layer

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

Rules can be scoped to specific files using YAML frontmatter with the paths field.

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

AGENTS.md

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

Subagents

The subagents has its own context window. After completing its task, the subagent returns the result to the main Claude process without consuming Claude’s main session context window.

The easiest way to get started is to let Claude generate one for you. Run:

/agents

Hooks

Claude Code hooks can be very dangerous. it executes arbitrary shell commands on your system automatically

Hooks can be installed via plugins. So always audit your 3rd party Claude Code plugins and do not trust them blindly.

Plugins

Before installing plugins, check their instructions first. Verify that if they are secure and don’t consume excessive tokens. Inefficient instructions can lead to unnecessary token consumption.

For example, I’ve seen Claude Code author include unnecessary comments that can consume valuable tokens when loaded into the context window.

Built-in Plugins

Claude Code offers the user useful built-in plugins. Here are the built-in plugins that I use regularly

# to analyze security review for current code changes on the current branch
/security-review

# review codebase including old codes
/code-review

MCP

MCP tool definitions are deferred by default, so only tool names enter context until Claude uses a specific tool. Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on the context window.

Skills

Skills are folders containing instructions and resources that Claude Code’s main session or subagents use to handle tasks more accurately.

Skill definition lives in a SKILL.md file with a name and description in its frontmatter.

.claude/
├── skills/
│   ├── pr-description
│   │   ├── SKILL.md

Claude Code loads skill on demand based on their descriptions. So skill description is important.

Skills vs CLAUDE.md, Subagents, Hooks & MCP

  • CLAUDE.md loads into every conversation. Skill load on demand.
  • Subagents run in isolated execution contexts. Skill can be loaded by Subagents. The full skill content is injected, not just the description.
  • Hooks are event-driven (fire on file saves, tool calls). Skills are request-driven (activate based on what you’re asking).
  • MCP servers provide external tools and integrations, an entirely different category from Skills.

That’s all for now. I will continue updating this post with new insights as I discover them.