AGENTS.md vs Knowledge Graph

AGENTS.md should carry human-authored rules; a code knowledge graph should carry generated repository relationships; task-local context should carry the current objective and evidence. These layers are complementary. A reliable coding agent context design keeps their authority, refresh cycle, and audit trail separate instead of treating any one layer as complete project memory.

This division answers a practical problem for teams using Qoder CLI or another coding agent: where should a fact live, who should maintain it, and what must be rechecked before an edit? The answer depends less on file format than on whether the information is policy, observed structure, or a temporary task decision.

Quick Verdict

Use AGENTS.md for stable instructions that people intend the agent to follow. Use a code knowledge graph for refreshable observations derived from source, tests, and project artifacts. Put issue scope, acceptance criteria, selected files, and current hypotheses in a task packet that expires when the work ends.

Layer	Best content	Update mechanism	Authority	Typical failure
AGENTS.md	Commands, conventions, ownership, restrictions, review rules	Human review and commit	Team policy, subject to instruction precedence	Stale, vague, conflicting, or oversized prose
Code knowledge graph	Symbols, imports, calls, implementations, tests, owners, rationale links	Rebuild or incremental refresh	Indexed evidence for a repository snapshot	Missing, stale, or incorrectly inferred edges
Task-local context	Objective, allowed scope, evidence packet, decisions, open questions	Created and revised during one task	Current task contract	Hidden assumptions or conclusions that outlive their evidence

The comparison is therefore not “text file versus database.” It is human intent versus generated structure versus temporary working state. The companion 1M Context vs Knowledge Graph guide explains how these layers interact with model capacity and retrieval.

What AGENTS.md Is Best For

The open AGENTS.md specification defines a plain Markdown instruction file with no required fields. It can document build commands, testing steps, code conventions, repository orientation, and other guidance. The closest applicable file wins when scoped instructions conflict, while explicit user prompts take precedence.

That makes AGENTS.md a good operating contract. Useful entries include:

• authoritative build, format, test, and release commands;
• package ownership and escalation paths;
• generated-file rules and the location of their source templates;
• compatibility, security, and review requirements;
• links to maintained architecture decisions;
• boundaries on files, tools, data, and external systems;
• the evidence required before a task is considered complete.

Write rules as actions that a reviewer can verify. “Run the contract suite after changing the public schema” is stronger than “be careful with compatibility.” “Do not edit generated clients; change the schema and rerun the generator” identifies both the prohibition and the approved path.

Qoder CLI documents AGENTS.md as part of its static memory system. Its current memory guide describes user, project, local, and focused-rule scopes, along with /init and /memory for initializing and inspecting memory. That is a Qoder memory feature, not proof that the file contains current repository relationships.

Keep the root file concise. Import or link to approved architecture and testing documents instead of pasting a codebase manual into every session. Secrets, transient logs, speculative debugging notes, and full source dumps do not belong in shared instructions.

What Code Knowledge Graphs Are Best For

A code knowledge graph is useful when the question is relational: what calls this handler, which modules depend on a schema, what tests cover a symbol, or which decision record explains a boundary?

The graph can represent packages, files, symbols, APIs, schemas, tests, owners, and documents as nodes. Typed edges can represent imports, calls, implementations, generation, coverage, ownership, or rationale. A traversal can then select a candidate impact path before the model opens current source.

This pattern has peer-reviewed support. RepoGraph was evaluated as a repository-level navigation layer across multiple software-engineering systems. CodexGraph uses a graph database and model-generated graph queries for structure-aware repository retrieval. Those studies establish code graphs as a credible context architecture; they do not prove that every graph implementation is accurate or that graphs always outperform lexical or semantic retrieval.

Graphify documents a related provenance boundary. Its Tree-sitter pass labels deterministic structural observations as EXTRACTED, while semantic relationships can be marked INFERRED or AMBIGUOUS with confidence. Its GRAPH_REPORT.md and graph.json outputs can guide discovery, but an inferred edge remains a hypothesis until source or runtime evidence confirms it.

A graph is therefore an evidence index, not a new source of truth. It should identify the repository revision it describes, expose the origin of important nodes and edges, and send the agent back to raw files and tests for high-impact decisions.

How Task Context Fits Between Them

Task-local context connects stable rules to repository evidence for one bounded piece of work.

A useful task packet contains:

• the issue, desired outcome, and acceptance criteria;
• the base commit, repository scope, and allowed write paths;
• relevant instruction files and architecture decisions;
• selected source files, tests, and graph paths;
• known risks, assumptions, and unresolved questions;
• the responsible owner for security, API, data, or deployment decisions;
• the commands that will verify completion.

This content changes too quickly for root instructions and is too intentional to derive from a graph. A graph may show that three consumers depend on an API, but it cannot decide which consumer is in scope for today’s migration. AGENTS.md may require backward compatibility, but it cannot determine whether the proposed adapter satisfies the current issue.

Treat task hypotheses as temporary. If a finding becomes a durable design decision, review it into an architecture decision record. If it becomes a stable workflow rule, review it into AGENTS.md. If it describes current structure, refresh the index. Do not append every result to an ever-growing “memory” file.

This separation also improves handoffs. A planning agent can return a compact evidence packet with file and relationship references. An implementation agent can verify those references in its current worktree. A reviewer can distinguish inherited policy, generated observations, and task-specific judgment rather than receiving an undifferentiated summary.

Layered Context Design for Qoder CLI

Qoder CLI can serve as the working agent while the three layers retain separate ownership.

1. Load human rules. Maintain concise project guidance in AGENTS.md and focused Qoder rule scopes. Use /memory to confirm which instructions are available when nested rules matter.
2. Pin the task. Record the base commit, objective, acceptance criteria, allowed paths, and required reviewers.
3. Select structural evidence. Use current source search and, where justified, an independently maintained code graph to locate callers, dependencies, tests, and related documents.
4. Verify before planning. Open the raw files behind important results. Mark dynamic registration, runtime configuration, external consumers, and inferred graph edges as uncertain.
5. Build an evidence packet. Pass exact paths, symbols, relationship paths, constraints, and expected verification to the agent or Subagent performing the work.
6. Test and reconcile. Run the required checks, inspect the diff, resolve contradictions, and update the layer whose content actually changed.

Qoder CLI does not need to own the graph for this design to work. The graph can come from Graphify or another approved external system, while Qoder CLI reads the selected evidence and performs the task. Do not attribute Graphify extraction, graph traversal, or graph freshness to Qoder.

The forthcoming Qoder CLI context-engineering guide owns the detailed workflow. The Qoder CLI large-codebase guide explains why rule files alone become insufficient as dependency paths widen.

Limits and Trade-Offs

Every layer can drift, and adding layers increases maintenance rather than removing it.

AGENTS.md can contradict a nested rule, import an obsolete document, or become too broad to guide a specific change. A graph can omit dynamic behavior, misresolve a call, preserve an old generated client, or infer a relationship that the source does not support. A task packet can carry a confident but incorrect conclusion from one worker to the next.

Use a separate audit for each failure mode:

1. Instruction audit: confirm owners, scope, precedence, commands, and linked documents.
2. Graph audit: record the commit, extractor version, provenance type, unresolved edges, and refresh event.
3. Task audit: confirm objective, allowed changes, evidence locations, assumptions, tests, and decision owner.
4. Source audit: check high-impact paths against the current worktree and runtime configuration.
5. Outcome audit: review the diff, test results, external contracts, and residual risks.

Avoid conflict by assigning each fact one primary home. A test command belongs in instructions; a call edge belongs in the graph; a temporary migration exception belongs in the task packet. Other layers may link to that fact, but should not maintain competing copies.

The graph may be unnecessary for a small repository or a known single-file change. A detailed task packet may be unnecessary for a harmless spelling fix. Layering should follow risk and repeated discovery cost, not a universal template.

FAQ

Can teams use both without conflict?

Yes, if authority is explicit. Let AGENTS.md define policy and tell the agent when to consult structural evidence. Let the graph describe a named repository snapshot. Let the task packet choose the current scope. When they disagree, verify source state and route policy changes through the human owner instead of asking the model to invent a winner.

Who owns generated context quality?

The team operating the index owns its freshness, coverage, provenance, and failure handling. Package owners should review important structural paths; platform teams can maintain extraction and refresh automation; task owners must verify high-impact results. The graph vendor or model cannot absorb repository accountability.

How should context layers be audited?

Audit them independently and together. Review instructions like code, validate graph samples against source, and require task handoffs to cite paths, symbols, commits, tests, and unresolved assumptions. Then run representative repository tasks to measure missed dependencies, unsupported relationships, reviewer corrections, and regressions.

Conclusion

AGENTS.md vs knowledge graph is a boundary question, not a winner-take-all comparison. Human-maintained instructions state how work should proceed. Generated graphs expose how repository entities appear to relate at a specific revision. Task-local context defines what the team is trying to accomplish now.

Use all three when repository risk and repeated discovery justify them. Keep their owners and refresh cycles separate, preserve provenance, and verify high-impact claims against current source and tests. A context layer is trustworthy only when a reviewer can identify where its claim came from, when it was refreshed, and who is accountable for acting on it.