tags: [code-intelligence, contracts, codegraph, structure, intent, semantic-search, graph, dar-find] related:

• 032_pre-index-your-codebase.md
• 011_nlp_first_codebase.md
• 012_code_for_machines.md supersedes: ~ status: current —

033 — Structure Is Not Intent: Two Layers Every Code Intelligence System Needs

The Problem

You can build a complete call graph of your codebase without understanding what any function is for.

A tool like CodeGraph parses every file, extracts every symbol, traces every call — and at the end, it can tell you that saveOrder calls normalizeOrder which depends on PriceCalculator and TaxEngine. That’s a structurally accurate description. It says nothing about when you should reuse normalizeOrder, what pipeline it belongs to, or whether it’s the right function for a given task.

Conversely, you can write a semantic contract block for every function — @does, @reuse-when, @role, @complexity — and at the end, the AI can find the right function for any described need. But it can’t tell you what else changes if you edit it. It has intent without structure.

These are two different problems, and most code intelligence systems solve only one of them.

What Structure Gives You

Structure comes from static analysis — AST parsing, import tracing, type hierarchy resolution. It answers:

• Where: file path, line number, qualified name
• What calls what: callers, callees, dependency chains
• What extends what: class hierarchies, interface implementations
• What breaks if: impact radius before an edit

Structure is cheap to produce — tree-sitter parses a file in milliseconds, no model required. It is also objective: the call graph is either correct or it isn’t. Two tools parsing the same file will agree on the structure.

What structure cannot tell you:

• Whether normalizeOrder is the right function to reach for when you need to process an API payload
• That this function is @complexity: simple and safe to reuse without LLM review
• That it belongs to the order-creation pipeline at step 2
• When a human or AI would choose this function over a similar one

Structure gives you where things are and how they connect. It doesn’t give you why you’d use them.

What Intent Gives You

Intent comes from semantic annotations — contracts written by humans or AI that describe purpose, not mechanics. It answers:

• What it does: one active-verb sentence naming inputs and outputs (@does)
• When to reuse it: a plain English condition (@reuse-when)
• What kind of thing it is: @role from a closed vocabulary (transformer, validator, query, mutation…)
• How complex: @complexity — routes the agent to reuse-as-is, verify, or generate new code
• Workflow position: @pipeline + @step — tells the agent this function is step 2 of 5 in a workflow, not a standalone utility

Intent is more expensive to produce — it requires reading and understanding the implementation. But it’s durable: a good @reuse-when stays accurate across refactors as long as the function’s purpose doesn’t change.

What intent cannot tell you:

• What calls this function in the current codebase
• Whether removing it will break six other things
• Where exactly it lives without a symbol lookup

Intent gives you why you’d use something and when. It doesn’t give you where it is or what touches it.

The Gap Each System Leaves

A pure structure system (CodeGraph alone) answers the first three columns. An agent using it can navigate your codebase efficiently — but it still has to read function bodies to decide which symbol is right for the job.

A pure intent system (dar find alone) answers the last four columns. An agent using it can find the right function in one query — but it doesn’t know the blast radius before editing, or what pipeline context surrounds the match.

The missing half in each case is exactly what the other provides.

The Combined Workflow

When both layers exist, the agent workflow changes:

Without either layer:

Task → explore directories → read files → grep for patterns
     → read more files → find function → read callers
     → assess impact → begin work
(26–52 tool calls)

With structure only:

Task → codegraph_search("normalize") → codegraph_context()
     → codegraph_impact() → begin work
(3–6 tool calls, but agent still reads bodies to choose the right symbol)

With intent only:

Task → dar find "normalize order payload" → match found
     → read contract → begin work
(1–3 tool calls, but agent has no impact radius before editing)

With both layers:

Task → dar find "normalize order payload" → top match: normalizeOrder
     → codegraph_impact("normalizeOrder") → 3 callers, 1 pipeline
     → begin work with full picture
(2–4 tool calls, full semantic + structural context)

The intent layer routes the agent to the right symbol. The structure layer tells it what changes. Neither step requires reading file bodies.

Building Both Layers in Practice

Structure: Install CodeGraph (npx @colbymchenry/codegraph), run codegraph init -i in each project. The index builds in minutes, updates on file change. No ongoing cost.

Intent: Write @contract blocks as a byproduct of writing or editing code. The key fields are @does, @reuse-when, @role, @complexity. A TF-IDF indexer (dar find) searches them. The cost is one annotation per function, written once.

The graph bridge: Your contracts already carry @used-by and @depends-on fields. These are the same edges CodeGraph builds from static analysis — but annotated with intent, not just presence. A dar graph command that walks these edges gives you intent-aware impact analysis: not just “what calls this” but “what calls this and what role does each caller play.”

Practical Takeaway

Code intelligence systems split along a clean axis: structure tells you where things are and how they connect; intent tells you why you’d use them and when.

Most projects have neither. Most AI-assisted projects have one — usually structure, because it’s automatable. The intent layer requires writing, which is why it gets skipped.

But the intent layer is where the agent makes decisions — which function to reach for, whether to reuse or generate, where in the pipeline a new step belongs. Without it, the agent is navigating accurately through a map with no labels.

Build both. The structure layer is a one-time setup. The intent layer is a byproduct of writing code. Together, they make every session start with a complete picture instead of an empty one.