Foundations

Everything is Context

Claude is only as useful as what it knows about you. Context is just files.

The idea

Claude starts every conversation knowing nothing about you. It doesn’t know your file structure, your preferences, how you name things, or what you’re working on. It’s an assistant with amnesia.

The fix is simple: give it context. And since Claude Code works with files on your computer, context is just… files. Markdown files, mostly.

The more Claude knows about your world, the less you repeat yourself.

CLAUDE.md

CLAUDE.md is the most important file in your setup. It’s a plain text file that Claude reads automatically at the start of every session. Think of it as a briefing document. What would you tell a smart assistant on their first day?

# My Notes

## Structure
- `Journal/` - Daily entries, named YYYY-MM-DD.md
- `Projects/` - One folder per project with a plan.md
- `Reference/` - Saved articles and research

## Preferences
- I write in markdown
- Keep filenames lowercase with dashes
- When I say "today's note" I mean the journal entry for today

## Important
- Never delete files, only move them
- Ask before reorganizing anything

Now Claude knows where things go and what not to touch.

Where it goes

Claude looks for CLAUDE.md in several places:

  • ~/.claude/CLAUDE.md - Global, applies everywhere
  • ./CLAUDE.md - In a specific folder, for that project
  • ./.claude/CLAUDE.md - Same, alternative location
  • ./CLAUDE.local.md - Local overrides you don’t want to commit to git

All are merged together, with more specific files taking precedence. Your global file might say “use bun instead of npm” while a project file adds the specific commands and folder structure.

For developers, there’s also .claude/rules/*.md, scoped rules that only apply to specific file paths. Useful in larger projects where different parts of the codebase have different conventions.

What to put in it

Be specific. “Put journal entries in Journal/” is better than “keep things organized.” Include actual paths. If there’s a folder Claude should know about, tell it the exact location.

State your preferences: how do you name files? What should Claude ask about before doing? What should it never touch?

And keep it updated. When you change how you work, update the file.

For developers

If you’re working on code, CLAUDE.md becomes your project’s operating manual:

# Project: My App

## Tech Stack
- Astro 5 with React islands
- TypeScript (strict mode)
- Tailwind CSS v4

## Conventions
- Use `bun` instead of npm
- Components go in `src/components/`
- Tests live next to the code they test

## Commands
- `bun dev` - Start dev server
- `bun test` - Run tests
- `bun build:prod` - Production build

Claude uses your package manager, follows your file structure, runs the right commands. No reminding.

How context works (and fades)

Claude has a context window, roughly 200,000 tokens by default. That sounds like a lot, but long conversations fill it up. When it does:

  • Older parts of the conversation get summarized
  • Details from earlier may be compressed
  • Claude might “forget” things you discussed

This is why CLAUDE.md matters so much. Information there is always loaded - it doesn’t fade. Recent conversation has high priority. Old conversation gets compressed.

Signs you’re hitting limits:

  • Claude asks questions you already answered
  • Suggestions conflict with earlier decisions
  • Claude seems to have lost the thread

What to do:

  • Put important things in CLAUDE.md, they survive compression
  • Be explicit about file paths instead of “check the notes”
  • Start fresh sessions when conversations get too long

The key insight

Claude doesn’t have perfect memory. It has weighted attention. Recent and explicit information wins over old implicit information. That’s why CLAUDE.md works - it’s always loaded fresh.

Everything is just files

What makes Claude Code different from chat-based AI: it works with your actual files. Your real files, on your computer. Not copies, not uploads. It reads them, writes them, searches across them.

You probably have years of notes sitting in folders you never open. Project plans, journal entries, research you saved and forgot about. Give Claude access to all of it and your notes stop being static - they become context. Not the context window kind from the section above, but the plain meaning: available information that makes Claude’s answers better.

The more files you have, the more useful this gets. And because it’s all plain text - markdown - there’s no lock-in. Stop using Claude tomorrow, your files are still your files.

The best tool I’ve found for maintaining this is Obsidian.

Why Obsidian works

Obsidian is a note-taking app where your notes are just files on your computer. No proprietary format, no cloud lock-in. Just a folder of markdown files.

Works great with Claude:

  • Your vault is a folder and Claude can read everything in it
  • CLAUDE.md in the vault tells Claude how it’s organized
  • Claude can read and write to your notes directly

A simple vault structure:

my-notes/
├── CLAUDE.md
├── Home.md              # Dashboard
├── Projects/            # Project plans
├── Journal/             # Daily entries
└── Ideas/               # Loose thoughts

Add a CLAUDE.md that explains the structure and Claude can search your notes, create new ones, process brain dumps, connect ideas across files.

What you can do

Search your notes: “Find all my notes that mention vacation planning.”

Create from templates: “Create a new project folder for ‘Kitchen Renovation’ with a plan.md.”

Process brain dumps: “Go through today’s journal entry and pull out any tasks.”

Connect to code: Plans live in Obsidian. Code lives in separate repos. They reference each other. Your project plan links to the repo, your repo’s CLAUDE.md links back to the plan.

You don’t need Obsidian

Any folder of markdown files works. Obsidian just happens to be a great editor for them, with wikilinks, graph view, and mobile sync. Same idea though: a well-organized folder of text files plus a CLAUDE.md that explains how they’re organized.

When in doubt, just ask

Don’t overthink your CLAUDE.md. If you’re unsure what to include, just start a conversation. Ask “what do you know about this project?” or “what would help you work here?” and iterate from there.

Chat is a great interface when you don’t know what you want yet.

Official Documentation