Claude Code /init Creates a CLAUDE.md. Here's Why That's Not Enough.

March 2026 | 10 min read

You ran /init. Claude Code scanned your repo, generated a CLAUDE.md, and you felt organized. The file had your project's language, framework, testing conventions. Maybe some notes about your directory structure. Good start.

A week passed. You noticed Claude kept asking about things the CLAUDE.md should have covered. You added more rules. Then more. The file grew to 200 lines, then 400. And still, every new session started cold. Claude read the file but didn't know you. It knew your linter config. It didn't know your business.

That's the gap this article maps. Not to criticize /init—it does exactly what it claims. The problem is what people assume it replaces.

What /init Actually Produces

Run /init in a project directory and Claude Code generates a CLAUDE.md file. The contents vary by project, but the pattern is consistent:

# Project Name

## Build & Test
- `npm run build` to compile
- `npm test` to run all tests
- `npm run lint` for style checks

## Code Style
- TypeScript with strict mode
- Prefer const over let
- Use async/await, not callbacks

## Project Structure
- src/ contains source files
- tests/ contains test files
- Config in root directory

That's a representative sample. The real output might include more detail about your specific framework or deployment process. But the shape is always the same: static observations about the current state of the codebase, expressed as rules and conventions.

This is useful. A developer joining your project benefits from these notes. Claude Code itself benefits—it won't suggest callback patterns in an async/await codebase. /init does its job.

The confusion starts when people treat this file as a memory system.

Six Things /init Doesn't Do

1. It doesn't update itself

CLAUDE.md is a snapshot. The moment /init writes it, entropy begins. You refactor from Express to Fastify. You migrate from Jest to Vitest. You add a monorepo structure. The CLAUDE.md still describes last month's architecture.

There's no watcher, no hook, no mechanism that detects drift between your codebase and the file that describes it. You either maintain it manually or it decays. Most people don't maintain it. So it decays.

A production memory system includes automated maintenance—context files that get verified against ground truth on a schedule, with stale facts flagged or corrected without human intervention.

2. It doesn't create domain routing

Suppose you operate across multiple domains. You manage a real estate database at work, run an SEO consultancy on the side, and maintain a personal knowledge vault. Each domain has its own vocabulary, its own contacts, its own rules of engagement.

When you say "leads" at 2pm, you mean something different than when you say "leads" at 9pm. /init has no concept of this. It writes one file for one project. There's no routing table, no keyword-to-domain mapping, no conditional context loading.

A production memory system uses domain routing: a _context.md file per domain, with a dispatcher that reads your prompt and loads the right context. You say "FUB" and the real estate context loads. You say "topical map" and the SEO context loads. The AI doesn't need you to specify which hat you're wearing.

3. It doesn't set up search

Your CLAUDE.md might reference other files. Maybe it says "see docs/architecture.md for system design." But Claude Code can't search your vault. It reads what you point it at. If you have 2,000 notes across 50 folders, Claude can't find the one about your client's billing preferences unless you tell it the exact path.

/init doesn't provision a search engine. No full-text search across your knowledge base. No semantic search that finds conceptually related notes. No content indexing that lets the AI locate information the way you'd locate it—by meaning, not filename.

A production memory system layers multiple search methods: regex/glob for exact matches, semantic vector search for conceptual queries, content-aware search that understands your vault's structure, and a session archive with full-text indexing across every conversation you've ever had with the AI.

4. It doesn't create hooks

Every Claude Code session begins the same way: Claude reads CLAUDE.md if it exists, then waits for input. There's no pre-session hook that loads today's calendar. No post-session hook that archives the conversation transcript. No trigger that alerts you via Telegram when a CRM record changes.

/init doesn't create any automation layer. The AI is reactive. It responds when prompted, forgets when the session ends.

A production memory system includes hooks and skills—slash commands that execute multi-step operations, session archival that captures every interaction into a searchable ledger, and event-driven triggers that let the AI act on schedules and external signals. The AI doesn't wait for you to remember what needs doing. It already knows.

5. It doesn't provision infrastructure

Close your laptop and Claude Code stops. There's no server, no background process, no always-on capability. /init is a local operation for a local tool. It assumes you're at your machine, in your terminal, actively working.

But AI memory that only exists when you're present isn't memory. It's a conversation partner with office hours. Your CRM data changes at 3am when a lead fills out a form. Your competitor publishes a blog post on Saturday morning. Your team mentions you in Slack while you're driving.

A production memory system can include a VPS—a server that runs your AI infrastructure 24/7. Scheduled tasks execute without your laptop open. Monitoring scripts watch external systems. Alerts fire to your phone. The system works while you sleep.

6. It doesn't create safety gates

Give Claude Code write access to your CRM API and it will write to your CRM. There's nothing in /init that creates guardrails around destructive operations. No dry-run modes. No confirmation requirements for bulk actions. No distinction between "read this data" and "modify this record that represents a $40,000 deal."

/init doesn't think about risk because /init doesn't think about operations. It describes a codebase. It doesn't govern a system.

A production memory system includes explicit safety constraints: write-blocked domains that require manual approval, batch operation thresholds that pause for confirmation, and audit trails that log every autonomous action. The AI knows what it's allowed to touch and what requires a human in the loop.

The Full Stack: What a Production Memory System Actually Requires

Count the components in a system that gives AI genuine persistent memory:

/init covers one row. Partially. A CLAUDE.md with build commands and style rules is a context file that covers a single domain (your codebase) without any of the surrounding infrastructure that makes it useful long-term.

Thirteen of these fourteen components don't exist after running /init. You're operating at roughly 7% of what's possible.

The Decay Timeline

Here's what typically happens after someone runs /init and considers the job done:

Week 1: Everything works. Claude Code reads your CLAUDE.md, follows the conventions, produces good output. You feel like you've solved AI memory.

Week 3: You've refactored two modules. The CLAUDE.md still describes the old structure. Claude suggests patterns you've deprecated. You manually update the file. Takes 20 minutes. You do it once.

Week 6: The file is 30% outdated. You've stopped updating it because the overhead doesn't feel worth it. Claude's suggestions are hit-or-miss. You compensate by giving longer prompts with more context. Each session starts with three paragraphs of setup.

Week 10: You're effectively back where you started. The CLAUDE.md exists but Claude's behavior suggests it's not reading it carefully, or the instructions have drifted far enough from reality that following them produces worse output than ignoring them. You paste context manually. You re-explain your workflow. You wonder why this felt so promising in week one.

This isn't a failure of discipline. Manually maintaining a static config file against an evolving system is a chore that scales linearly with complexity. Nobody sticks with it. The people who solve this problem automate it.

What People Actually Need

The /init user who searches "Claude Code memory not working" three months later needs a different category of solution. Not a better CLAUDE.md. A system that treats memory as infrastructure rather than a file.

That means context files per domain that load conditionally. Search that spans your entire knowledge base. A session ledger that means last Tuesday's conversation is retrievable, not gone. Hooks that inject today's state before you type your first prompt. Safety constraints that prevent the AI from corrupting data during autonomous operations.

It also means the CLAUDE.md gets better. In a production system, the context file isn't 30 lines of build commands. It's the operating manual for how the AI works with you specifically—your voice preferences, your correction history, your domain vocabulary, your hard constraints. The file /init generates is a skeleton. The file a production system uses has muscle, nervous system, and immune response.

When /init Is Enough

Fair to name the cases where this doesn't apply:

• Single-project, single-developer, short-lived work. You're building a weekend project. The codebase fits in your head. Claude Code with a basic CLAUDE.md is plenty.
• Code-only use. You use Claude exclusively for coding assistance and nothing else. No business context, no multi-domain operations, no CRM integrations. A style guide is genuinely all you need.
• Experimentation phase. You're still figuring out whether Claude Code fits your workflow. /init is the right first step. Run it. Use it. Notice the edges. Then decide if the edges matter.

If you manage clients, operate across multiple business domains, or need the AI to carry context longer than a single coding session—/init was always the starting line, not the finish.

Frequently Asked Questions

What does Claude Code /init actually do?

It scans your project directory and generates a CLAUDE.md file containing basic project rules and conventions—build commands, code style preferences, directory structure notes. The file is read by Claude Code at the start of each session. It takes about 30 seconds and produces a reasonable starting point for single-project coding assistance.

Is a CLAUDE.md file the same as AI memory?

No. A CLAUDE.md is a static configuration file. It doesn't update itself, can't search your other files, doesn't persist between sessions beyond its own contents, and has no mechanism for routing context based on what you're working on. AI memory requires search infrastructure, session persistence, context routing, automated maintenance, and safety constraints. A CLAUDE.md is one component of a fourteen-part system.

What's the difference between /init and a professional AI setup?

/init gives you one file in one project directory. A professional setup gives you a vault architecture with domain-specific context files, a search engine spanning your entire knowledge base, a session archive with full-text search across every past conversation, hooks that inject context automatically, skills that execute multi-step operations, safety gates that prevent destructive autonomous actions, and optionally a VPS that keeps the system running when your laptop is closed.