What the Claude Code /init Command Actually Does (And What It Doesn't)

You run claude /init on a new project, Claude scans the repo for a few seconds, and a CLAUDE.md file appears. It looks thorough — build commands, directory structure, detected conventions. It feels like Claude now "knows" your codebase. What actually happened is subtler, and the difference matters more than most developers realize when they start relying on it for day-to-day work.

What /init actually does

The /init command is a one-shot codebase scan. Claude reads your config files, directory structure, toolchain configs, and any existing documentation, then writes a structured Markdown document — CLAUDE.md — that it will automatically load at the start of every session in that directory.

claude /init scans:
  → package.json, tsconfig.json, pyproject.toml, Cargo.toml
  → directory structure and source layout
  → ESLint, Prettier, lint-staged configs
  → README files and any existing CLAUDE.md
  → common entrypoints and test runner config

Output: a CLAUDE.md markdown file dropped in your repo root

The resulting file becomes part of Claude's system prompt. Every new conversation in that directory opens with this context already loaded. That is genuinely useful for reducing the boilerplate of explaining your stack every time.

What CLAUDE.md typically contains

After /init, a well-generated CLAUDE.md covers the practical mechanics of working in your repo:

Typical CLAUDE.md sections after /init:
  → Build commands (npm run build, make, cargo build)
  → Test commands (jest, pytest, cargo test)
  → Project structure overview (src/, lib/, services/)
  → Detected conventions (naming, imports, formatting)
  → Toolchain notes (Node version, Python env, etc.)

This is valuable. Instead of spending the first message of every session explaining that the project uses pytest instead of unittest, or that imports must use the @/ alias, that knowledge is loaded automatically. For a solo developer on a small project, this can feel like real codebase awareness.

What /init cannot do

/init reads static files. It surfaces what is explicit in configs and directory layouts. It cannot infer what is implicit in how your system actually runs: runtime behavior is invisible to a static scan.

What /init cannot capture:
  → Runtime behavior and execution paths
  → Inter-service dependencies and data flows
  → Database schema relationships
  → Infrastructure topology
  → Which services own which data
  → Why architectural decisions were made
  → Cross-repo dependencies

If you ask Claude "what happens when the payment service fails during checkout?" after running /init, you are asking a question that CLAUDE.md cannot answer. The file describes your build commands. It does not describe your distributed execution paths. This is the core gap that context rot exploits — the moment your codebase evolves, the document starts lying.

CLAUDE.md is a document, not an index

This distinction is easy to miss because CLAUDE.md feels dynamic — it was generated by AI, it describes your specific project, it loads automatically. But it is a static markdown document committed to your repository. It has the same lifespan problem as any documentation: written once, trusted forever, gradually wrong.

A semantic index, by contrast, is a live, queryable representation of your codebase. When a file changes, the index updates. When a new service is added, embeddings are generated for it. When a developer asks "what does the notification service depend on?" — a semantic index can answer that from current code, not from a document written on the day /init was run.

The staleness curve

In a team setting, CLAUDE.md degrades faster than you expect. Teams ship continuously. New services appear, old ones are renamed, conventions shift, build tooling changes. The document generated by /init on day one is partially outdated within weeks:

CLAUDE.md lifecycle in practice:
  Day 1:   /init generates accurate snapshot
  Week 2:  New service added, CLAUDE.md not updated
  Month 1: Major refactor, file paths now wrong
  Month 3: New developer joins, reads stale CLAUDE.md
  Month 6: Document contradicts the actual codebase

This is not a knock on /init — it is a knock on documentation as a category. Any file you write once and commit to a repo will drift. The question is how much you rely on it when it does. This is the same problem unpacked in why codebase documentation is always out of date.

Who /init is actually useful for

/init works well for individual developers on projects they own and maintain. If you are the only person touching the codebase, you can update CLAUDE.md as conventions change. If you are working alone on a greenfield service, the generated document stays accurate for longer because you control every change.

It starts breaking down the moment you add team members, scale the codebase beyond a few services, or stop treating the document as living documentation that needs active maintenance. At that point, the file becomes a source of confident-sounding wrong answers — which is arguably worse than no context at all.

The team problem

CLAUDE.md is per-repo. That seems fine until you realize that different developers on the same team may be using different versions of the file — or that nobody updated it after the codebase restructure last quarter. There is no enforcement mechanism, no freshness signal, and no automatic reconciliation between what the document says and what the code actually is.

On a ten-person team, you effectively have ten developers whose AI sessions are grounded in the same static document, all of which is aging. When Claude gives a confident but wrong answer about your architecture, the first question to ask is whether CLAUDE.md still reflects reality.

What a managed semantic layer changes

Kognita works differently from CLAUDE.md at a structural level. Instead of a document written once and committed, Kognita maintains a continuously updated semantic index of your codebase — embeddings that update as code changes, behavioral relationships that reflect current service interactions, and a queryable layer that serves the whole team from a single consistent ground truth.

There is no document to maintain. There is no staleness problem because the index re-runs as your codebase changes. Every developer, product manager, and engineering lead on your team queries the same current representation — not their local version of a markdown file that may or may not have been updated since Q3. This is the difference between documentation and infrastructure: one requires humans to keep it accurate, the other does it automatically.

Final take

The /init command is a useful starting point — a quick way to give Claude some project-specific grounding so you stop repeating yourself at the start of every session. Run it on a new project, update it when major conventions change, and you will get genuine value from it for a solo workflow.

But CLAUDE.md is documentation, and documentation has a known failure mode: it ages. As your codebase grows, as your team scales, as services multiply and patterns shift, a static markdown file cannot keep up with the semantic complexity of what you have actually built. The moment your team starts trusting CLAUDE.md as a source of architectural truth rather than a convenience shortcut, the staleness problem starts costing real time.

/init gets Claude oriented in your project. A semantic index keeps it accurate as your project evolves.