CLAUDE.md vs Knowledge Graph

Choosing CLAUDE.md vs knowledge graph is the wrong decision frame. CLAUDE.md is best for instructions the agent should follow. Solution documents are best for reusable explanations of validated fixes. A code knowledge graph is best for traversing current structural relationships. They overlap at the edges, but they do not have the same job, authority, or lifecycle.

The practical design question is which layer should answer a given prompt—and how the agent should react when two layers disagree.

Quick Verdict

Use the smallest authoritative layer that matches the question.

The practical CLAUDE.md vs knowledge graph verdict is therefore additive: keep policy in instructions, validated reasoning in solution documents, and current relationships in a revision-aware structural layer.

Agent question	Best first layer	Why
“Which test command must I run?”	CLAUDE.md	It is an explicit repository instruction.
“Why did we avoid this retry strategy?”	Reviewed solution document	It preserves evidence and engineering reasoning.
“Which handlers call this service on this commit?”	Proposed external code graph	It can traverse revision-aware structural links.
“Is this claim safe enough to change code?”	Source code and tests	They remain the final verification boundary.

CLAUDE.md and solution documents are prose. A code graph is generated structure. Neither format makes a claim correct by itself. Authority should come from source, scope, revision, and review status.

The broader structural model is explained in Knowledge Graph for AI Coding Assistants; implementation-level graph governance is covered in Compound Engineering Knowledge Graph.

What CLAUDE.md Is Best For

CLAUDE.md is the right place for concise guidance that should influence work across many sessions: build and test commands, repository conventions, architectural boundaries, security requirements, and pointers to narrower documentation.

Anthropic documents a hierarchy of memory and instruction files for Claude Code. Project instructions can live in CLAUDE.md or .claude/CLAUDE.md, and more specific files can apply at lower directory levels. These instructions are loaded into context; imports can organize them but do not make the imported content free. [ANTHROPIC-MEMORY-20260724]

That behavior gives CLAUDE.md high reach and a real context cost. It should say “Always run the migration compatibility test before modifying schemas,” not contain the history of every past migration. Anthropic's current guidance recommends concise instruction files and suggests keeping each file under roughly 200 lines. [ANTHROPIC-MEMORY-20260724]

Treat instructions as policy. Give them owners, review repository-wide changes carefully, and avoid facts that can be derived more reliably from the current code. An instruction that names a path likely to move should link to a stable concept or verification command instead.

This makes CLAUDE.md one input to coding agent memory, not the whole system.

What Solution Docs Are Best For

Solution documents preserve reasoning that would be expensive to reconstruct. They can describe symptoms, failed approaches, root cause, the validated fix, affected components, tests, and invalidation conditions. This is the durable part of coding agent memory that turns one investigation into a reusable engineering record.

The current Compound Engineering ce-compound skill selects one durable learning and writes it under solutions/; its fuller path can use session history as evidence. The separate ce-compound-refresh workflow is designed to maintain stale and overlapping solution documents. [CE-COMPOUND-20260724] [CE-REFRESH-20260724]

In the current plan–work–review–compound sequence, solution-document persistence belongs to the compounding step. A search such as Claude md vs knowledge graph Reddit often mixes personal preference, generic memory advice, and several different products; this comparison instead keeps documented instruction behavior separate from the proposed graph layer.

This makes solution docs more selective than transcripts and more explanatory than instructions. They should not tell every session what to do. They should become relevant when the current task matches the recorded problem class.

The critical fields are scope and status. A solution must say which versions and components it covers, whether it was reproduced on the current revision, who reviewed it, and what would make it obsolete. Without those fields, confident prose can outlive the system it describes.

What Code Knowledge Graphs Are Best For

A code knowledge graph is best for questions that require traversal or filtering across many structural facts: callers, implementations, dependencies, routes, tests, ownership boundaries, and links from code to reviewed documents.

In this article, the graph is a proposed external layer. It is not part of CLAUDE.md, Claude Code auto memory, or the official Compound Engineering plugin. Graphify can be evaluated as one possible implementation, but no first-party Compound Engineering–Graphify integration is claimed.

Each graph fact should identify the indexed commit, source artifact, extraction method, and access scope. An edge saying CheckoutHandler CALLS PaymentService is useful only if the agent can tell which revision produced it and can open the source. Generated edges are candidates for retrieval, not instructions.

Graphs are weaker at intent and causality. A call edge does not explain why a boundary exists, why a workaround was chosen, or whether a maintainer approves changing it. Those explanations belong in reviewed prose. Dynamic dispatch and runtime configuration can also make graph extraction incomplete.

How the Three Layers Work Together

Suppose an agent must change an idempotency rule.

1. CLAUDE.md supplies the non-negotiable rules: required tests, forbidden direct database writes, and the command for validating migrations.
2. A relevant solution document explains the previous duplicate-settlement incident, the failed approaches, and the assumption that justified the current rule.
3. A proposed external code graph retrieves the handlers, service methods, storage paths, and tests connected to the rule on the indexed revision.
4. The agent opens the returned code and runs the required tests before accepting any graph or prose claim.
5. After review, the team updates the layer whose knowledge changed: instructions for a new standing rule, the solution doc for revised reasoning, or the graph index for a new revision.

The retrieval order is not fixed. A policy question starts with instructions. A recurring failure starts with solutions. A blast-radius question starts with structure. The final action still returns to source evidence.

This layering also creates a useful conflict signal. If CLAUDE.md forbids a pattern that the solution doc recommends, stop and ask for review. If the graph contradicts a path named in prose, verify the current branch before deciding which artifact is stale.

Limits and Trade-Offs

Every layer can create context waste. Large instruction files load guidance that may be irrelevant. Too many solution documents create noisy retrieval and duplicate explanations. An over-connected graph returns a broad neighborhood instead of a bounded evidence set.

Govern them differently:

• audit CLAUDE.md for reach, clarity, and instruction conflicts;
• refresh solution documents for overlap, scope, and expiry;
• monitor graph ingestion for revision lag, extraction errors, permission leaks, and low-value edges.

Do not use one global confidence score to hide these differences. A human instruction can be authoritative but outdated. A graph edge can be mechanically reproducible but incomplete. A solution document can be well reasoned but scoped to an older release.

Measure the combined system on controlled repository tasks. Record whether the agent retrieved the right evidence, how much irrelevant context it opened, which claims required correction, and whether reviewers could trace the result to source. Avoid universal token-savings claims.

FAQ

Can one layer override another?

Only through an explicit authority rule. Current source code and tests verify behavior; reviewed repository instructions define working policy; scoped solution records explain prior decisions; generated graph facts support navigation. When layers conflict, the agent should surface the conflict and request the responsible owner's review rather than silently selecting the most confident wording.

Who audits generated graph facts?

The platform team should monitor extraction and freshness, while subsystem owners validate samples and high-impact paths. Security, authorization, migration, billing, and deletion flows deserve stricter checks. Every returned fact should expose enough provenance for a developer to reproduce it against source.

How should teams version context layers?

Version prose in the repository when possible. Record the commit or release scope in solution documents. Stamp graph indexes and query responses with their source revision. If a task targets a different branch, qualify or reject facts that cannot be reproduced there.

What does CLAUDE.md do in Claude Code?

It supplies persistent instructions that Claude Code reads as context according to the documented user, project, and directory hierarchy. [ANTHROPIC-MEMORY-20260724] It is not a database of every fact about the codebase and should remain concise.

Conclusion

The useful answer to CLAUDE.md vs knowledge graph is division of labor. Put stable rules in concise instructions. Put validated reasoning in owned solution documents. Use a proposed external graph for revision-aware structural retrieval, then verify its output against code and tests.

When each layer exposes its authority, provenance, and expiry, the agent can select context instead of accumulating it. That is a stronger foundation than asking one artifact to behave like all three.