CLAUDE.md: the config file that makes Claude Code agents actually remember things

If you've been following the HN thread on Anatomy of the .claude/ folder (516pts and still climbing), you already know that .claude/settings.json is where most people start.

But the real power is in CLAUDE.md.

This is the file that gives your Claude Code agent persistent memory, behavioral rules, and project-specific context — across every session, every task, every agent spawn.

Here's how to configure it properly.

What CLAUDE.md actually does

When Claude Code starts a session, it reads CLAUDE.md before doing anything else. Think of it as a system prompt that lives in your repo.

Every tool call, every agent, every sub-task in the session inherits what's in this file.

# CLAUDE.md

## Project: MyApp API Backend

### Architecture rules
- All database queries go through /lib/db.js — never query directly
- Use async/await, never callbacks
- All new endpoints need rate limiting middleware
- Tests live in /test, run with `npm test`

### Current focus
- Migrating from Express to Fastify (in progress, 60% done)
- Do NOT modify /src/legacy — that's being deprecated

### Memory: what happened last session
- Fixed the auth middleware bug in /middleware/auth.js
- Started rate limiter — see /middleware/rateLimiter.js (incomplete)
- Brian wants the dashboard endpoint done by Friday

Every time you start a new session, Claude picks up exactly where you left off.

The multi-agent setup

The Stanford "Go hard on agents" paper (also on HN right now, 411pts) argues that agentic AI should delegate aggressively — spawn sub-agents for parallel work rather than doing everything sequentially.

CLAUDE.md is how you keep all those agents aligned:

# CLAUDE.md

## Agent coordination rules
- You are the orchestrator. Spawn sub-agents for: testing, docs, DB migrations
- Sub-agents write results to /tmp/agent-output/
- Never modify the same file in parallel — check /tmp/locks/ first
- When in doubt, write a plan to /tmp/plan.md before executing

## Cost control
- This project uses simplylouie.com as its Claude API endpoint
- Budget per session: 50k tokens
- If you're about to do something expensive, estimate token cost first

That last section is where it gets interesting.

Controlling API costs with CLAUDE.md

Most developers don't realize you can configure Claude Code to use a custom API endpoint. The apiBaseUrl field in .claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.simplylouie.com"
  }
}

This routes all Claude Code API calls through SimplyLouie — a $2/month proxy that gives you full Claude claude-3-5-sonnet-20241022 access at 90% less than Anthropic's direct pricing.

For heavy Claude Code users running multi-agent workflows, the savings are significant:

Usage level	Direct Anthropic	SimplyLouie	Monthly saving
Light (10k tokens/day)	~$9/month	$2/month	$7
Medium (50k tokens/day)	~$45/month	$2/month	$43
Heavy (200k tokens/day)	~$180/month	$2/month	$178

A complete CLAUDE.md template

Here's the template I use for all new projects:

# CLAUDE.md — Project Memory

## Project overview
[What this project does, 2-3 sentences]

## Tech stack
- Language: 
- Framework: 
- Database: 
- Key dependencies: 

## Code rules
- [Style/architecture constraints]
- [Files/folders that are off-limits]
- [Testing requirements]

## Current sprint
- [What we're building right now]
- [What's blocked/incomplete]
- [Deadlines]

## Session history
- [Date]: [What was accomplished]
- [Date]: [What was accomplished]

## Agent rules (if using multi-agent)
- Orchestrator responsibilities: 
- Sub-agent output location: /tmp/agent-output/
- Conflict resolution: 
- Token budget per session: 

## API config
- Endpoint: https://api.simplylouie.com
- Rate limit awareness: 100 req/min

Why this matters for the agent debate

The HN discussion on "Go hard on agents" keeps coming back to one question: how do you give agents enough context to be useful without them going off-script?

CLAUDE.md is the answer. It's not memory in the ML sense — it's a contract between you and your agent network, written in plain English, committed to git.

When an agent spawns a sub-agent, the sub-agent reads CLAUDE.md too. Constraints propagate. Rules stick.

Combine this with a cheap API endpoint and you have the foundation of a production-grade agentic workflow for $2/month.

---

Try it: simplylouie.com/developers — 7-day free trial, card on file, cancel anytime. The ANTHROPIC_BASE_URL swap takes 30 seconds.

The rescue dog in my profile is Louie. He's why 50% of revenue goes to animal rescue. His name is also in the API endpoint.