AI Engineering and Architecture

Codebase-aware engineering assistant

This is a worked concept for an engineering assistant that reasons about a codebase as a connected software system. It is a design exploration, not a description of a completed or shipped product.

Problem

Most code assistants retrieve text that looks relevant to a question. That is useful, but textual similarity alone does not explain how a system is put together. A change may depend on a type hierarchy, an interface contract, a service boundary, a runtime dependency, or an architectural convention that is not visible in the nearest text fragments.

The assistant should help an engineer find and understand those relationships before proposing a change.

Design goals

  • Preserve meaningful code structures instead of splitting files into arbitrary chunks.
  • Combine textual retrieval with symbols, references, dependencies, and repository structure.
  • Show the evidence used to form an answer and let the engineer correct the search path.
  • Prefer current code and documentation when older material no longer represents the system.
  • Support design and refactoring work without pretending that structural evidence proves runtime behavior.

System outline

Structural index

Language parsers build an index around modules, classes, functions, interfaces, and imports. Abstract syntax trees provide the basic boundaries. Language Server Protocol data adds symbol definitions, references, and type relationships where the language tooling supports them.

This structure gives the assistant better retrieval units and a graph of relationships that can be followed across files and packages.

Hybrid retrieval

A request is resolved through several complementary signals:

  1. Text and semantic search identify likely concepts and documentation.
  2. Symbol search identifies concrete implementation candidates.
  3. Dependency traversal expands from those candidates to callers, implementations, tests, configuration, and related services.
  4. Repository metadata supplies ownership, recency, and change history where available.

No single signal is treated as authoritative. The result is a set of candidate paths with an explanation of why each path may matter.

Temporal relevance

Software knowledge becomes stale. Search ranking should prefer the current implementation and recent documentation, while keeping older decisions available when they explain why the current structure exists. Recency is a ranking signal rather than an automatic reason to discard material.

Human verification

For broad or ambiguous questions, the assistant asks the engineer to confirm the likely subsystem, service, or symbol before it expands the search. This makes uncertainty visible and reduces the chance that a plausible but unrelated code path becomes the basis for a design recommendation.

Evaluation approach

The assistant should be evaluated on engineering tasks with observable evidence, not only on whether an answer sounds useful. Example checks include:

  • whether it identifies the files and symbols required for a change;
  • whether it follows important callers, implementations, and tests;
  • whether its explanation cites evidence that actually supports the conclusion;
  • whether it detects uncertainty or conflicting candidates;
  • whether a proposed change preserves relevant contracts and passes the project checks;
  • whether engineers can correct a mistaken search direction without restarting the task.

The evaluation set should include changes that cross module or service boundaries, because those are where text-only retrieval is most likely to miss important context.

Limitations

Static structure cannot fully describe runtime behavior, generated code, reflection, dynamic configuration, or undocumented operational dependencies. Language tooling also varies in quality across repositories. The assistant therefore needs explicit confidence limits and access to tests, traces, and runtime evidence when the task depends on behavior rather than code structure alone.

Next steps

The smallest useful prototype would support one language and one repository. It would combine AST-aware chunks, language-server references, text search, and a review step where an engineer selects the relevant subsystem. The first evaluation would compare that workflow with text-only retrieval on a small set of cross-file maintenance tasks.