What You Know

Module 3: What You Know

Claude starts every session fresh. It doesn’t remember yesterday. But your CLAUDE.md can.

The trick is reference files — documents that CLAUDE.md points to but doesn’t contain directly. This keeps your instructions file readable while giving Claude access to deep context when it needs it.

The Index Trick

Here’s the problem with putting everything in CLAUDE.md: it becomes a wall of text that’s hard to update, hard to read, and slow to load. You end up with either a bloated file or a superficial one.

Reference files solve this. Your CLAUDE.md becomes an index. The detail lives elsewhere, called up only when Claude needs it.

## Reference Files (read on demand)

| File | Contents |
|------|----------|
| `~/.claude/TOOLS.md` | All tools and services I use |
| `~/.claude/PLATFORMS.md` | Platforms and accounts |
| `~/.claude/LINKS.md` | Canonical URLs for all projects |

When Claude needs to reference a URL, it reads LINKS.md instead of guessing. When it needs to know what tools are available, it reads TOOLS.md instead of assuming. The reference files are the knowledge base. CLAUDE.md is the index.

This scales in a way a single file doesn’t. You can have a TOOLS.md with forty entries without cluttering your main instructions. You can add a new reference file for a new project area without touching the global config.

What Goes in Reference Files

Think in categories:

Tools and services — what you use, how you access it, any quirks or conventions. Especially useful if you have CLIs, APIs, or MCP servers that Claude should prefer over alternatives.

Canonical URLs — every project, every platform, every relevant link. Claude will hallucinate URLs if you don’t give it the real ones. A LINKS.md eliminates that failure mode.

Platforms and accounts — where you’re active, what you publish there, the relevant handles or IDs. Useful when you’re asking Claude to draft content for specific channels.

Contacts — email addresses, communication preferences, priority order. Useful for anything that involves sending or responding.

Project-Level Context

Reference files work at the project level too. A .claude/CLAUDE.md file in a specific repo can give Claude context about that codebase without touching your global config:

## This Project

- Astro static site deployed to VPS via rsync
- CSS uses custom properties defined in global.css
- No TypeScript — plain JS only
- Deploy with: ./deploy.sh
- Assets served from CDN, not local public/ folder

This is where you put the things that only apply here: the tech stack, the deployment process, the gotchas, the conventions. Project-level context is what stops Claude from suggesting TypeScript types in a JS-only codebase, or running a deploy process that doesn’t exist.

Start here: Create at least one reference file. ~/.claude/TOOLS.md is the easiest starting point — list the tools you use daily, then point to it from your CLAUDE.md.

Why This Compounds

Reference files pay off over time. Each one you create is context you never have to re-explain. A session that reads LINKS.md is a session where Claude doesn’t guess at URLs. One that reads TOOLS.md is a session where Claude reaches for the right tool without asking.

The more reference files you build, the less onboarding each session needs. Claude picks up where the last session left off — not because it remembers, but because the files remember for it.

---

This section evolves. Every time Claude lacks context that you had to provide manually, consider whether that context belongs in a reference file.