Can an Agent Understand a Real Spring Boot Codebase?

So far, my agent has been working in a repository with two Java files.

Calculator.java and GreetingService.java were useful for testing tools because I knew exactly what the model should find. They were also far too simple to tell me whether the setup would be useful for actual development.

Now I move to a real project.

MyFinancesAPI is a Spring Boot application I've built as a personal project. It has controllers, services, repositories, entities, API models, authentication, configuration, shared abstractions, tests, and enough existing code that the model can't simply treat the project as one large prompt.

The stack remains the same:

MyFinancesAPI
      ↓
Aider 0.86.2
      ↓
Ollama
      ↓
Ministral 3 8B

I've already defined how the agent should discover context, which project rules it should follow, and what it's allowed to do.

Now I want to know:

Can this small local model actually understand the structure of a real Spring Boot application?

First, connect it without touching the code

I start Aider from the project root:

aider \
  --model ollama_chat/ministral-3:8b \
  --no-auto-commits \
  --no-dirty-commits

Aider detected the Git repository:

Aider v0.86.2
Model: ollama_chat/ministral-3:8b with whole edit format
Git repo: .git with 102 files
Repo-map: using 4096 tokens, auto refresh

This is already a very different environment from the previous test.

Instead of two tiny classes the model now gets a map of:

102 tracked files

I keep the first test read-only:

Do not modify any files.

Tell me the name of the Git repository/project you are currently working in,
and briefly state what repository context you currently have available.
Do not infer application architecture yet.

Aider scanned all 102 files.

Ministral recognized the project as a Spring Boot personal-finances application and identified concepts such as authentication, users, accounts, categories, transactions, validation, and error handling.

So the first connection worked:

Real repository
      ↓
Aider repo map
      ↓
Ollama
      ↓
Ministral
      ↓
Repository-aware response

But the response also gave me an immediate warning.

The model understands more than I asked, and invents more too

I explicitly said:

Do not infer application architecture yet.

Ministral did it anyway.

Then it introduced something completely unrelated:

If you want to make changes to make the greeting more casual...

There was no greeting task.

The model then referenced an authentication controller, and Aider asked whether it should add the file to the chat.

I reject the request.

No application source changed.

The agent clearly sees meaningful information about the real application. It also has trouble staying inside the question.

The permission boundaries from the previous experiments have already earned their place.

A repository map is orientation, not proof

The first interaction used about:

9.3k input tokens
177 output tokens

Aider's repository map gives Ministral a compressed view of a 102-file project without loading every source file.

This is useful, but seeing the map doesn't mean understanding the implementation.

A repository map is a little like looking at a city map. I can see areas such as:

Accounts
Transactions
Authentication
Core
Exceptions
Utilities
Tests

I can start forming an idea of where things live.

I still don't know what happens inside every building.

For this test, I'm interested in whether the agent can orient itself and decide where it should look next. Detailed source-level reasoning will come later.

How quickly does context grow?

Before testing whether Ministral can select context independently, I try the opposite approach: I progressively provide more project evidence myself.

I start with AGENTS.md, then add build metadata, application configuration, and representative source and test files.

The input grows quickly:

Stage	Approx. input tokens
Initial instruction validation	6.8k
Build metadata added	11k
Application configuration added	12k
Representative source/tests added	17k
Final correction pass	19k

The additional context does improve the model's understanding. With actual project evidence available, it becomes easier to distinguish project structure and conventions from generic Spring Boot assumptions.

But there's an obvious cost.

I went from about 6.8k to 19k input tokens while trying to understand one project.

I also noticed a tendency for the model to ask for increasingly broad context—configuration, resources, migrations, tests, and other areas that weren't necessarily needed for the immediate question.

It's easy to fall into this pattern:

Unsure?
   ↓
Load more files
   ↓
More context
   ↓
Ask again

It can work, but it doesn't scale particularly well.

For a local model, larger context means more work for limited hardware. With a paid remote model, unnecessary context can also translate directly into higher token usage and cost.

More importantly, loading more files myself doesn't answer the question I actually care about.

If I choose all the useful context, I'm doing part of the agent's job for it.

So I start over.

Can AGENTS.md and the repository map be enough?

I open a fresh Aider session so the previous 19k-token conversation doesn't influence the result.

I add only:

/add AGENTS.md

Then I ask:

Do not modify any files.

Using AGENTS.md and the repository context available to you, describe the
high-level structure of this project.

Identify:

1. The build system.
2. The main source and test locations.
3. The major application areas/packages.
4. The typical structure of a domain feature.
5. The important shared/core abstractions you can identify.
6. Where authentication/security functionality appears to live.
7. Where shared exception handling and utilities appear to live.
8. Which files you would inspect first if asked to modify Account behavior.

For item 8, explain briefly why each file would be relevant.

Distinguish between:
- information directly available from repository context;
- information you would need to inspect a file to confirm.

Do not request additional files.
Do not infer business behavior from class names.

This is closer to what I actually need from an agent.

I don't want to tell it which Account files matter.

I want it to tell me.

High-level orientation is surprisingly good

The clean-session result is encouraging.

Ministral correctly identified:

• Maven as the build system;
• the main source and test locations;
• the feature-oriented package structure;
• major areas such as auth, config, core, exceptions, and utils;
• the general structure of a feature;
• important shared abstractions;
• where security, exceptions, and utilities appear to live.

And it did this with about:

7.1k input tokens

The comparison is interesting:

Manually expanded project context
~19k input tokens

AGENTS.md + repository map
~7.1k input tokens

These aren't equivalent experiments—the 19k context contained much more actual source—but the difference shows why context selection matters.

For high-level orientation, I don't need to load everything.

So far:

Capability	Result
Recognize Spring Boot/Maven project	✅
Find source/test structure	✅
Identify major packages	✅
Recognize feature architecture	✅
Find shared/core areas	✅
Use AGENTS.md for orientation	✅
High-level context efficiency	✅

If the experiment ended here, I would probably be impressed.

But the most important part of the prompt is item 8.

Finding the right files is harder than describing the project

I asked which files the agent would inspect first to modify Account behavior.

This is where the quality drops.

I would expect a first-pass shortlist roughly like:

AccountController.java
AccountService.java
AccountRepository.java
Account.java
AccountModel.java
AccountServiceTest.java
AccountTest.java

Then the agent can follow shared abstractions only if the task requires them.

Ministral didn't select that set.

Most importantly, it omitted:

AccountService.java
AccountController.java
AccountServiceTest.java
AccountTest.java

Instead, it selected some shared abstractions and suggested that it would need to inspect whether Account had a dedicated service.

But Aider's repository map already knew that AccountService.java existed.

The model could describe the architecture correctly while still failing to choose some of the most obvious files needed for an actual change.

This is an important distinction:

Understand project shape ≠ Select correct task context

Plausible details are still dangerous

The clean-session test also exposes the evidence problem I saw during the initial connection.

Ministral made statements about security classes that went beyond what the repository map alone had established.

It also invented ReflectionUtils.

There is no ReflectionUtils.java in the repository structure I had already verified.

This is exactly the kind of hallucination that becomes difficult to notice in a real project.

A fake ReflectionUtils doesn't sound absurd. It sounds like a perfectly normal Java utility.

If I didn't know the project, I might assume the model had actually found it.

The model also referred to:

AccountModel.java (if it exists)

even though the repository context already indicated that it existed.

The problem isn't simply missing information. Ministral isn't always interpreting the information it already has consistently.

What does "understand the codebase" actually mean?

Before this test, the question sounded binary:

Can the agent understand my Spring Boot project?

The experiment gives me a more useful answer.

There are levels of understanding.

Level	Description
1	Recognize the project	✅
2	Understand high-level structure	✅
3	Recognize architectural patterns	✅
4	Select the right files for a task	⚠️
5	Reason accurately about implementation	❓

Aider + Ministral is doing reasonably well at the first three.

The fourth is already shaky.

And I haven't asked it to trace detailed Java behavior yet.

So, can it understand a real Spring Boot codebase?

At a high level, yes.

The local stack successfully moved beyond the two-file test repository. It recognized the application structure, major packages, feature organization, shared areas, testing structure, and build environment without loading the entire project into context.

The context measurements also showed something useful. I can manually grow the conversation from roughly 6.8k to 19k tokens and give the model increasingly detailed project knowledge, but that doesn't prove the agent can find the right information itself. With AGENTS.md and the repository map, high-level orientation required only about 7.1k input tokens.

The weak point is becoming clearer:

Orientation is working better than precise context selection.

The agent can find the neighborhood.

I'm not yet convinced it can reliably find the right house.