Code Search

Search is the agent's primary orientation tool. Three retrieval strategies run against the same index and are fused into a single ranked result set, because each fails in ways the others do not.

Retrieval strategies#

Structural queries#

Structural search matches against syntax trees rather than text, which makes it possible to express queries that regular expressions cannot. A pattern describes a shape with holes; the matcher binds the holes and returns the bindings.

# every exported async function whose body never awaits
(function
  export: true
  async: true
  body: !(contains await))

# calls into the payment client that skip the idempotency argument
(call
  callee: payments.$METHOD
  args: !(contains idempotencyKey))

The second pattern is representative of why structural search matters. It expresses a real safety invariant — every payment call must carry an idempotency key — as a query that can be run across a repository and, subsequently, enforced as a policy in review.

Fusion and ranking#

Results from the three strategies are merged using reciprocal rank fusion, then re-scored against signals that are specific to code rather than to documents.

• Definition over reference — the place a symbol is defined outranks the hundred places it is used.
• Source over test — unless the query is explicitly about testing, in which case the weighting inverts.
• Proximity to the working set — files already open in the current task are boosted, since relevance is usually local.
• Recency of change — code modified recently is more likely to be the subject of the current request.
• Ownership — files owned by the same team as the current working set are mildly boosted in large monorepos.