G
Graphify
graphify.homes
Sign in
AGENTS.md vs graph

AGENTS.md vs a codebase knowledge graph

AGENTS.md and a codebase knowledge graph solve different persistence problems. AGENTS.md records instructions and conventions; a graph records relationships among code, docs, and project knowledge. Reliable coding agents use both: rules guide behavior, while the graph helps the agent navigate the repository.

Published Updated

Graphify outputs
graph.html
graph.json
GRAPH_REPORT.md

Graphify stores inspectable artifacts so codebase knowledge can be reviewed by humans and reused by AI coding assistants.

Instruction cards feeding project rules into a persistent code knowledge graph

AGENTS.md

Instructions

Best for commands, constraints, conventions, review criteria, and instructions about tools.

Knowledge graph

Relationships

Best for symbol dependencies, call paths, subsystem communities, document links, and architecture evidence.

Together

Behavior + navigation

The instruction file tells the agent what to do and how; the graph tells it where project knowledge is connected.

What is AGENTS.md for?

AGENTS.md is a versioned instruction file for coding agents. It should contain the commands, constraints, style requirements, test expectations, and repository-specific working rules that every agent needs before making changes.

  • Document install, build, test, lint, and release commands.
  • State protected paths, review requirements, and forbidden operations.
  • Describe when a graph, MCP server, or other project tool should be used.

What does a codebase knowledge graph store?

A codebase knowledge graph stores nodes and edges: files, functions, classes, imports, calls, documents, and the relationships among them. It is a navigation layer for repository structure, not a replacement for source code or developer instructions.

  • Edges can show imports, calls, references, rationale, and document relationships.
  • Communities group related code and context into subsystem-level views.
  • Confidence labels distinguish extracted facts from inferred relationships.

Why can AGENTS.md become too large?

AGENTS.md works best as a concise operating contract. When teams paste architecture essays, file inventories, and historical detail into it, the agent spends context on prose that could be queried more precisely from source and graph artifacts.

  • Keep durable rules in the file.
  • Move structural facts into graph.json or documentation.
  • Link to the authoritative artifact instead of duplicating its content.

Which questions belong in the graph instead of AGENTS.md?

Use the graph for questions about dependency paths, callers, blast radius, subsystem boundaries, document relationships, and architecture clusters. These answers change with the code and are expensive to maintain by hand in a text file.

  • Which services call this handler?
  • What modules depend on this package?
  • Which design note explains this subsystem?
  • What else changes when this interface moves?

How should the two layers link together?

Add a short graph-query policy to AGENTS.md and let the graph hold the project structure. The policy should name the artifact, explain when to use it, and require source verification for uncertain edges.

  • Name graphify-out/graph.json and GRAPH_REPORT.md explicitly.
  • Use MCP or graph query commands when available.
  • Require a refresh after large repository changes.

Can a knowledge graph replace AGENTS.md?

No. A graph can show that two modules are connected, but it cannot decide that a team forbids schema changes without a migration or that generated files must not be edited. Those are policy statements and belong in AGENTS.md.

  • Use AGENTS.md for decisions and constraints.
  • Use the graph for evidence and navigation.
  • Use source files for exact implementation.
Working commands

How do the setup commands fit together?

Separate policy from structure

Markdown
# AGENTS.md
## Repository rules
- Run tests before reporting completion.
- Use graphify-out/graph.json for dependency and call-path questions.
- Verify INFERRED or AMBIGUOUS graph edges against source.

## Source of truth
- Behavior: source code and tests
- Structure: graphify-out/graph.json
- Architecture summary: graphify-out/GRAPH_REPORT.md
FAQ

Frequently asked questions

Should AGENTS.md contain architecture details?

Keep only the stable architecture rules an agent needs before reading the graph. Changeable relationships belong in graph artifacts or documentation.

Is a graph better than CLAUDE.md?

Neither replaces the other. CLAUDE.md-style files and AGENTS.md carry instructions; code graphs carry structural evidence.

How often should the graph be updated?

Update after major refactors, directory moves, dependency changes, and before architecture reviews. Active repositories can use watch mode or a Git hook.

Can multiple agents share the same graph?

Yes. The artifacts live with the project and can be read by different assistants or exposed through MCP, provided each agent gets the appropriate usage instructions.

Key takeaways

What should you remember?

  • AGENTS.md defines behavior; the graph supplies project relationships.
  • Keep AGENTS.md short and point it to graph.json instead of duplicating architecture prose.
  • Require source verification for inferred edges and refresh the graph after large changes.
Sources

Where can you verify the details?

AGENTS.mdPurpose and conventions for repository-level agent instructions.Graphify documentationGraph extraction, semantic context, communities, and querying.Graphify GitHub repositoryArtifact formats, edge confidence labels, and refresh workflows.

Related Graphify guides

Continue through the Graphify topic cluster with pages that explain assistant context, architecture review, documentation, and graph-based codebase understanding.

Codex codebase context without rereading the repository

Give Codex persistent codebase context with graph artifacts, concise AGENTS.md rules, and MCP tools so repository questions use structure, not repeated scans.

AI coding assistant context that persists

Graphify creates persistent AI coding assistant context from code, docs, PDFs, diagrams, screenshots, and transcripts.

Persistent codebase memory for Claude Code

Give Claude Code durable codebase memory: build a Graphify graph, keep GRAPH_REPORT.md and graph.json in the project, and refresh them as the code changes.

Turn this concept into a real project graph

Start from the use cases page or upload a project ZIP to build a graph that your team can inspect and reuse.

See use casesBuild a graph