INSIGHT 26: Static Surfaces Are Agent Affordances

The agent does not only read code as syntax. It reads the repository through surfaces: names, imports, types, declarations, examples, generated clients, accessible members, package exports, schemas, tests, docs, and static diagnostics. These surfaces tell the agent what exists and what is valid.

This is the most concrete code-pattern insight in the research. If a behavior is hidden behind raw strings, reflection, dynamic registration, implicit framework convention, or tribal docs, the agent must infer it. If the behavior is represented as a typed symbol, generated method, exported interface, visible declaration, or failing diagnostic, the agent can search it, import it, autocomplete it, and repair against it.

That is why generated SDKs matter. The point is not "SDKs are nicer." The point is that SDKs turn remote API contracts into local static affordances. The agent sees method names, request shapes, response shapes, errors, mocks, and examples instead of guessing URLs and JSON fields.

Plot-ready data lives in presentations/write-code-ai-agents-love/research/data/names_types_apis.csv.

Source map

CrossCodeEval: repository APIs are not optional context

CrossCodeEval is one of the clearest sources for "the current file is not enough." It constructs cross-file code completion examples from real repositories in Python, Java, TypeScript, and C#. The completion target often depends on identifiers, imports, definitions, and usages outside the current file.

The important annotation result is that almost all references contain names requiring cross-file information, while only a tiny fraction are predictable from the current file alone. This directly supports the claim that APIs, names, and imports are repository context, not decoration.

CrossCodeEval data copied from the paper

CrossCodeEval retrieval data copied from the paper

Cross-file context location data copied from the paper

Source trace: R62, paper-text/crosscodeeval-2310.11248.txt.

Chart sketch: retrieved API context improves exact match

Inference: stable file names, coherent directories, explicit imports, and meaningful API names help retrieval systems because relevant context is often nearby or name-related. This is not a claim that all files should be colocated. It is a claim that recoverable locality and naming consistency matter.

Chunking: small functions are not the same as good context

The chunking paper is useful because it blocks a lazy conclusion. It is tempting to say "agents love small functions." The evidence is more specific. Function-sized chunks were not Pareto-optimal in the reported RAG code-completion experiments. Sliding windows, cAST, and declaration-aware chunks performed better because they preserve surrounding declarations and context.

Chunking data copied from the paper

Additional data from the paper:

Source trace: R49, paper-text/chunking-rag-code-completion-2605.04763.txt.

Chart sketch: function chunks are not the winner

Inference: the codebase rule is not "make every function tiny." The rule is "make coherent neighborhoods recoverable." An agent often needs imports, types, declarations, nearby examples, callers, callees, and tests. A function body alone may hide the affordances that make the function valid.

Names are retrieval metadata

The naming papers make identifiers feel less like style and more like infrastructure. Code models use names as semantic handles. If names are stable and truthful, they guide retrieval and intent understanding. If names are misleading, inconsistent, or obfuscated, they become false signals.

Naming-affects-LLMs data copied from the paper

Other paper findings to preserve:

Source trace: R65, paper-text/naming-affects-llms-code-analysis-2307.12488.txt.

When Names Disappear data copied from the paper

Source trace: R66, paper-text/when-names-disappear-2510.03178.txt.

Chart sketch: names disappearing hurts semantic tasks

Inference for codebase design:

• Use one domain noun for one domain concept.
• Keep route names, schema names, DB names, UI names, and test names aligned where possible.
• Name exported functions after intent, not implementation accidents.
• Avoid "almost right" names. A misleading name is a false retrieval edge.
• Treat renames as API migrations, not cosmetics, when agents rely on them for retrieval.

Types and generated clients turn hidden contracts into local facts

Type-Constrained Code Generation shows that type information does much more than prevent parser errors. In generated TypeScript, syntax errors are a minority; type errors dominate compile failures. Type constraints substantially reduce compiler errors and improve pass@1, especially for repair tasks.

This is the strongest direct support for generated SDKs and typed API clients. A generated client is not only a wrapper around fetch. It is a local type surface that says which endpoint exists, what the request looks like, what the response contains, which fields are optional, and which errors may exist.

Type-Constrained Code Generation data copied from the paper

Source trace: R43, paper-text/type-constrained-codegen-2504.09246.txt.

CatCoder data copied from the paper

Source trace: R63, paper-text/catcoder-2406.03283.txt.

Chart sketch: type constraints attack the dominant compile failure

The generated SDK inference:

This is why "rawdogging API calls" is a strong talk example. Raw calls hide the contract exactly where agents need visible constraints.

ToolGen and A3-CodGen: static tools and curated API candidates beat guessing

ToolGen teaches code models to trigger autocomplete-like tools at dependency points. Its reported improvements are not primarily about solving all logic. They are about reducing invalid dependency usage: undefined names, wrong members, missing APIs.

ToolGen data copied from the paper

Source trace: R51, paper-text/toolgen-autocomplete-repo-codegen-2401.06391.txt.

A3-CodGen adds a retrieval-selection warning. It identifies local function signatures, variables, fully qualified names, global functions, and installed libraries. But more global candidates can hurt.

A3-CodGen data copied from the paper

Source trace: R64, paper-text/a3-codgen-2312.05772.txt.

Inference: agents should be given a curated list of available APIs, not an unbounded pile of similar-looking snippets. This maps directly to generated SDKs, LSP symbol lookup, package export maps, and typed public interfaces.

How this becomes a codebase pattern

The phrase "static surfaces" should mean any repo artifact that makes valid behavior visible before runtime:

Generated SDK policy for agents

Generated SDKs help only if the repo makes the generation pipeline clear. Otherwise they can become another stale or hand-edited artifact.

Minimum policy:

API contract:
  source: openapi.yaml
  generator: pnpm generate-api
  output: src/generated/api
  edit_policy:
    - never hand-edit generated files
    - update schema or generator config instead
  ci:
    - run generator
    - fail if generated diff is not committed
  examples:
    - src/features/billing/example.ts
    - src/features/users/example.ts

This turns the SDK from "more code" into an agent affordance: the agent knows where the contract lives, how to update it, and what not to edit.

Where this connects to custom lint and monorepos

Static surfaces become more valuable when combined:

In a monorepo, this loop can be atomic. The schema, generated SDK, app code, tests, lint rules, docs, and infra change together. That is the strongest version of the user's monorepo flavor: not "everything in one repo" for its own sake, but all contract surfaces and verification surfaces versioned together.

What I should claim

I can make these claims confidently:

• Cross-file API context materially improves repository completion.
• Identifier names carry model-relevant semantic signal.
• Type constraints reduce a large class of invalid-code failures.
• Tool/autocomplete/static symbol assistance reduces dependency validity errors.
• Function-sized chunks are not automatically optimal retrieval units.
• Generated SDKs are a practical way to expose remote API contracts as local static surfaces.

What I should not claim

I should not claim types prove business correctness. Types constrain shape and API validity; tests and domain checks still matter.

I should not claim generated SDKs are always better if the schema is bad. A wrong schema produces wrong affordances. The contract pipeline must be owned and verified.

I should not claim names are a substitute for structure. Names are a signal. They work best when aligned with imports, types, tests, and examples.

I should not claim tiny functions are agent-friendly by default. The chunking paper points the other way: isolated function bodies can be a poor retrieval unit.

Blog visual candidates

1. CrossCodeEval exact-match chart: in-file vs retrieved vs reference-assisted.
2. Chunking chart: function vs declaration vs cAST vs sliding window.
3. Naming obfuscation chart: original vs obfuscated class summarization.
4. Type-error pie/bar: syntax 6% vs type checks 94%.
5. Raw fetch vs generated SDK comparison table.
6. Static-surface graph: schema -> SDK -> types -> app -> tests/lint -> CI -> agent repair loop.

References

• R43: Type-Constrained Code Generation, paper-text/type-constrained-codegen-2504.09246.txt
• R49: Chunking RAG Code Completion, paper-text/chunking-rag-code-completion-2605.04763.txt
• R51: ToolGen, paper-text/toolgen-autocomplete-repo-codegen-2401.06391.txt
• R62: CrossCodeEval, paper-text/crosscodeeval-2310.11248.txt
• R63: CatCoder, paper-text/catcoder-2406.03283.txt
• R64: A3-CodGen, paper-text/a3-codgen-2312.05772.txt
• R65: How Does Naming Affect LLMs on Code Analysis Tasks?, paper-text/naming-affects-llms-code-analysis-2307.12488.txt
• R66: When Names Disappear, paper-text/when-names-disappear-2510.03178.txt
• D25-D30: OpenAPI Generator, Kiota, Orval, Speakeasy, Stainless, FastAPI client generation docs