Before Changing an Unfamiliar Repository, Build a Working Model

Cleaning up AI-generated, legacy, or inherited code starts with establishing what the repository actually does before changing it. Otherwise, every "improvement" rests on a plausible architecture summary that may connect similar names, miss callers resolved by the IDE, or assume the wrong dependency implementation. Explyt acts as a code cleanup harness by building a working model from semantic search, JetBrains symbol relationships, the dependency code this project actually uses, and verified lessons retained in Memory Bank. An engineer can challenge that model at each step and use it to define a defensible scope before touching unfamiliar code.

You can think of that working picture as a lightweight project ontology: files, symbols, relationships, dependencies, and decisions connected around a concrete question. The term is a metaphor here.

Repository search is only the first pass

Suppose an outsourcing team has just inherited an AI-generated order-management service. Before it can clean up the inherited AI-built project, the team needs to understand one behavior at a time. The first task sounds small: explain how an order becomes eligible for manual review.

A coding agent can search for manual review, open likely files, and summarize what it sees. Modern agents may also use embeddings or language-server navigation. That is useful reconnaissance. It can still produce a pile of plausible fragments:

• a similarly named rule in an unused module;
• a test fixture containing the same phrase;
• an interface whose active implementation lives elsewhere;
• a call into a dependency that is absent from the repository;
• a comment describing behavior that changed months ago.

The problem is not a lack of text. The agent has to establish how the pieces relate in this project.

AgentLens shows how often that distinction matters in practice. Assumption-driven changes appeared in 13 of 32 trajectory reviews, including invented architecture and business rationale; documentation-heavy tasks also produced hallucinated repository structures, files, and endpoints. Repository evidence is therefore more than context for a fluent explanation: it is what keeps the agent's model of the project tied to symbols and code that actually exist.

Explyt can combine semantic search with exact IDE navigation. Semantic search uses the codebase index to locate candidates by meaning when you do not yet know the project vocabulary. Once a candidate appears, JetBrains indexes let the agent resolve definitions and usages as symbols rather than treating every matching string as evidence.

The two steps answer different questions. Semantic search asks, "Where might this concept live?" Symbol navigation checks, "What actually calls this declaration?"

Start with maps, then read the narrow sections that matter

Large files waste context when an agent reads them from top to bottom merely to discover what they contain. Explyt can ask the IDE for file structure first: classes, methods, fields, and their positions. The agent gets a map, chooses the relevant declaration, and reads that section with its surrounding code.

For the order service, it may begin with the module tree, inspect the structure of ReviewEligibilityService, and jump directly to evaluate(Order). That method delegates to RiskPolicy, so the next question is not which files mention RiskPolicy. It is which declarations implement it and where the selected symbol is used.

JetBrains Find Usages can return references to the resolved symbol, including calls that text search may miss or confuse with identically named methods. The agent can move through the graph:

entry point → service method → interface → implementations → callers → tests

This is still an investigation, not an automatic architecture diagram. Dynamic wiring, reflection, generated code, configuration, and runtime selection can hide relationships from static navigation. The agent should state those gaps and inspect runtime evidence with the debugger when static relationships are insufficient.

The repository boundary is often the wrong boundary

The active rule may call risk-engine-client, an internal library connected to the project as a JAR. Reading only repository files leaves a hole exactly where the behavior becomes interesting.

Explyt can inspect source attached to the connected dependency and decompile classes when source is unavailable. The agent reads the signatures and implementation available in the version this project uses. It does not have to fill the gap from documentation for the latest release or from the model's memory of a similar API.

That changes the explanation. Instead of writing, "The client probably returns a score that the service compares with a threshold," the agent can follow the actual method and report where the threshold is applied, what the return type contains, and which exception path returns an inconclusive result. The same dependency-level context matters when tracing a vulnerability across the project.

Decompiled code has limits. It may lose original names, comments, source layout, and some language-level constructs. Native code or remote services remain outside the IDE's view. The agent should separate what it observed in connected code from what it inferred about an external system.

Keep the facts worth carrying into the next session

A useful repository model should survive longer than one chat, but copying every discovery into permanent notes creates another noisy knowledge base.

Explyt's Memory Bank stores focused information that can be recalled across conversations. During repository study, the agent can preserve durable facts such as:

• manual review is decided in ReviewEligibilityService, while OrderController only exposes the result;
• RiskPolicy has multiple implementations, and configuration selects one by deployment mode;
• the connected client version uses a different response type from the current public documentation;
• a design decision or project-specific trap explains why the obvious refactoring is unsafe.

The memory should capture the lesson and its reason, not duplicate a symbol map that the IDE can rebuild. A verified decision about allowed change boundaries can later support the final review of agent-generated changes. Updating an existing note is more useful than creating competing versions. If the current code contradicts an old note, the note needs to be corrected.

Memory is curated context, not ground truth. It can become outdated, and an agent can save a mistaken conclusion if nobody verifies it. Project code, connected dependencies, runtime behavior, and current team documentation remain authoritative. Sensitive values and credentials do not belong in memory.

A team-lead-style repository study has checkpoints

The "AI team lead" metaphor is useful only if it changes the workflow. A confident architecture summary produced after one search is not enough.

A defensible study can proceed in checkpoints:

1. Ask a concrete product or engineering question, such as how manual-review eligibility is decided.
2. Use semantic search to find the project's vocabulary and likely entry points.
3. Inspect file structure before reading large files in full.
4. Resolve definitions and Find Usages through IDE indexes to connect the actual symbols.
5. Follow calls into attached or decompiled dependency code when behavior crosses the repository boundary.
6. Mark uncertainty around reflection, generated code, configuration, and runtime dispatch.
7. Verify important claims with focused tests, including tests grounded in a real execution, or debugger evidence where static structure is insufficient.
8. Save only durable, verified project lessons to Memory Bank for the next session.

The deliverable is not "I have read the repository." It is a traceable explanation: the entry point, the symbols followed, the dependency code inspected, the assumptions that remain, and the places a change would affect. When that understanding leads to a patch, reviewing the final agent-generated change checks the implementation against the task and indexed project facts.

Let the IDE supply the facts; let the model connect them

A senior engineer's understanding includes history, social context, production incidents, and judgment that no index can reconstruct. Explyt does not replace that experience. It gives the model a better way to earn project knowledge: broad discovery when terminology is unknown, narrow symbol-level navigation when precision matters, access to the dependency version in use, and curated memory between sessions.

The resulting loop looks like this:

question → semantic discovery → file map → resolved symbols and usages → connected dependency code → verified explanation → durable memory

As a code cleanup harness, Explyt turns repository study into the first verifiable step of making unfamiliar code maintainable. The team leaves with concrete artifacts for the next cleanup task: the resolved symbols behind a behavior, the dependency implementation in use, stated uncertainties, durable verified lessons, and a blast radius checked against the IDE. That evidence supports a defensible change scope instead of forcing each engineer to rediscover whether a fluent architecture summary is tied to the real project.

Install Explyt from JetBrains Marketplace and try this workflow on a pilot repository.