AI-aided coding is popular. Almost all developers know the feeling when tokens or premium requests run out towards the end of the month. Still lots of devs blindly use their AI agent without much optimisation in mind. We can do better and will see here how to optimise a code base for an AI agent and how much this can save in time and tokens.

Agent Experience is the New Dev Experience

In the previous years code bases were optimised for humans. Good READMEs, nice scripts, a clear structure, verification tests for the code design, etc. Now we have a second actor with AI agents that start to contribute and dominate already in most cases. Agents do not complain much about code bases usually. That means it is on you to optimise it for them. You can still ask an agent what it needs to do its work in an ideal way. Optimising for agent experience will save tokens and time, but it will also improve the quality of your changes and make sure the code base follows a defined structure.

Adding an Entity as a concrete Use Case

In my Java Spring Boot demo project we will add a new entity in an optimised way.

In that skill folder we have got references and a script alongside the SKILL.md file. The details of the skill can be found on GitHub. Notably the skill creates a spec file and then uses that in scaffold-entity.sh. The script generates multiple files for the entity:

| # | Layer          | File                                |
|---|----------------|-------------------------------------|
| 1 | Domain         | `<Entity>.java`                     |
| 2 | Domain         | `<Entity>Repository.java`           |
| 3 | Application    | `Create<Entity>UseCase.java`        |
| 4 | Application    | `Get<Entity>UseCase.java`           |
| 5 | Application    | `GetAll<Plural>UseCase.java`        |
| 6 | Application    | `Delete<Entity>UseCase.java`        |
| 7 | Application    | `Create<Entity>Command.java`        |
| 8 | Application    | `<Entity>NotFoundException.java`    |
| 9 | API            | `<Entity>Controller.java`           |
| 10| Infrastructure | `<Entity>Entity.java`               |
| 11| Infrastructure | `<Entity>RepositoryAdapter.java`    |
| 12| Infrastructure | `Jpa<Entity>Repository.java`        |
| 13| Test           | `Create<Entity>UseCaseTest.java`    |
| 14| Test           | `<Entity>ControllerTest.java`       |

Like that you receive the complete hexagonal structure for an entity with its basic CRUD operations. Some tests are also introduced.

Compared to a prompt-only approach this is cheaper and faster. The potential savings are summarised in the table below:

You can see that we save 85%-90% in tokens and around the same in time. In addition we make sure that the script creates the same structure every time. A review and a few edits are of course necessary. Let us see in the next section how to further optimise for agent experience.

Further Optimisations for AI Coding Agents to Explore

This is only one way to optimise your coding agent’s behaviour there are many more aspect. Those I list below.

• Keep a project manifest or architecture summary — One concise file that tells the agent where things live, what depends on what, and what the conventions are. Without it, every conversation starts with the agent reading half your codebase just to get oriented.
• Write scoped instruction files per directory or layer — Use applyTo patterns so the agent only loads the rules that matter for the file it’s editing. No need to feed it the entire rulebook when it’s just touching one corner of the project.
• Create prompt files for things you keep asking for — If you’ve explained the same task twice, it should be a .prompt.md you invoke with one line. The agent doesn’t need to rediscover the pattern every time, and you don’t need to re-type the instructions.
• Batch independent reads, sequence dependent ones — When the agent needs to understand context, let it read multiple files in parallel rather than one by one. But if step B depends on step A’s result, don’t let it guess — make that dependency explicit in your instructions. This alone can cut exploration time in half.
• Make the agent run tests before it’s done — Add a rule that every change ends with a test run. You’d be surprised how many issues this catches automatically. It’s cheaper to fail fast in the same conversation than to debug a broken build in the next one.
• Be specific in what you ask for — “Add a getByStatus method to the Order repository” costs a fraction of “make orders filterable by status.” The more precise the request, the less the agent needs to explore, guess, and over-engineer.
• Use a structured change request template — Three to five lines: what, where, constraints, tests needed. It removes ambiguity completely. The agent stops asking questions and starts working immediately.
• Record gotchas and decisions somewhere the agent can find them — When you hit a tooling quirk or make a design decision that isn’t obvious from the code, write it down in repo memory. Otherwise the agent will rediscover it the hard way every single time, and you’ll pay for that investigation in tokens.
• Designate a golden reference implementation — Pick one well-tested vertical slice and treat it as the canonical example. The agent copies from working code instead of interpreting prose rules, which means fewer deviations and more consistency across the board.
• Add architecture tests and static analysis to the build — ArchUnit, ESLint, Checkstyle — whatever fits your stack. Convention violations become build errors, not suggestions the agent might overlook. The feedback loop is instant and doesn’t depend on anyone reading instructions carefully.

Using a coding agent should not just be done blindly, but always with optimisation techniques in mind. Try out different aspects to optimise your coding agent. The good thing is that you can also ask the agent to optimise itself. Make it a habit to regularly update your project for your agent if needed. Agent experience is the new dev experience!

The post Agent Experience Optimisation in Large Code Bases – Skill vs. Prompt only appeared first on Ronnie Schaniel.

Even in the age of AI coding bugs inevitably happen. Some say AI is causing more bugs than we had before. Anyway, also for debugging we can receive some help from AI. That is why I created an Agent Skill for debugging.

The Debug Agent Skill

Our debug skill should take a stack trace or error description as input. Based on that and the project at hand, it should form hypotheses and create tests to reproduce the issue in the code. Skills are an independent, shareable and modular way to customise coding assistants. They are meant for repeatable tasks and they are not only instructions but can also involve more context and scripts.

Today we create a skill in a full stack project that consists of a Java Spring Boot backend and a Angular frontend. The two are connected through an API. We create a debug folder in our skills folder and also place the skill file in there:

skills/debug/SKILL.md

How does the skill file look like?

---
name: debug
description: Analyze pasted stack traces from any environment, form 2-3 concrete hypotheses, visualize likely failure paths, and reproduce the bug with a failing test before fixing code.
---

# Skill: Debug from Stack Trace

## Purpose

Use this skill when a user pastes a stack trace, error log, or production failure excerpt and wants help debugging the issue in this repository.

This skill is optimized for cases where:

- the failure happened in another environment
- only logs or stack traces are available
- the root cause is uncertain
- the bug should be reproduced with a test before changing code

## Core workflow

Follow this sequence strictly:

**Hard stop rule:** if there is no clear stack trace, no concrete error, or the failure mode is still ambiguous, the very first response must stay in diagnosis mode. That means: summarize what is known, state what is unknown, present 2-3 ranked hypotheses, and ask how to continue or what additional evidence is available. Do not edit code, do not write tests, and do not propose a fix until the uncertainty has been reduced enough to justify a reproduction path.

1. **Parse the stack trace**
   - Extract the exception type, message, top application frames, and repeated patterns.
   - Distinguish framework noise from application frames.
   - Identify the most relevant user-code entry points first.
   - If there is no stack trace, then do not guess blindly. Instead, state what is known vs unknown and what minimal additional evidence would reduce uncertainty.
   - If there is a vague symptom but no clear failure signal, do the same: remain in diagnosis mode first.
   - Build some hypotheses as described in step 2 (without the stack trace evidence if needed), clearly label them as speculative, and ask how to continue before doing anything else.
   - You also do not need to run tests if there is no clear evidence that the bug is in the application code. In that case, give bounded debugging guidance or ask for more information.

2. **Build 2-3 hypotheses**
   - Produce 2 or 3 plausible causes only.
   - This step is mandatory before any implementation work whenever the issue is not already clear from evidence.
   - For each hypothesis include:
     - why it matches the trace
     - which files/classes likely participate
     - what evidence would confirm or disprove it
   - Rank them from most likely to least likely.

3. **Show a diagram**
   - Render a Mermaid flowchart of the likely failing path.
   - The diagram should show:
     - triggering API/use case entry point
     - intermediate collaborators
     - the suspected failing branch or null/missing state
     - the thrown exception
  - The file needs to be created in the root of the project such that I can view it.

4. **Choose the smallest reproduction test**
   - Prefer the narrowest test that can reproduce the bug reliably.
   - In this project, use:
     - **JUnit 5 + Mockito** for application/use-case bugs
     - **`@WebMvcTest`** for controller/API behavior bugs
     - **integration-style test only when necessary** for cross-layer behavior that cannot be reproduced in isolation
   - Avoid `@SpringBootTest` unless there is no smaller realistic reproduction.

5. **Write the test first**
   - Add or update a test that reproduces the suspected issue.
   - The test must fail first.
   - State clearly why that failing test reproduces the bug.

6. **Only then fix the code**
   - After the failure is confirmed, implement the smallest safe fix.
   - Preserve architecture boundaries:
     - `api` → `application` → `domain` ← `infrastructure`
   - Do not introduce framework code into domain classes.

7. **Verify after the fix**
   - Re-run the reproduction test.
   - Re-run related tests if needed.
   - Summarize root cause, fix, and why the test now passes.

## Output format

When using this skill, structure the response like this:

If the issue is unclear or there is no clear stack trace, stop after sections 1 and 2 first, then ask for confirmation or more evidence before moving on.

### 1. Observations
- exception type
- important message
- most relevant application frames

### 2. Hypotheses
- Hypothesis 1
- Hypothesis 2
- Hypothesis 3 (optional)

### 3. Failure diagram
- Mermaid flowchart showing the likely failing path

### 4. Reproduction plan
- whether to use a unit, MVC, or integration test
- what exact scenario should fail first

### 5. Fix plan
- smallest likely code change after the test fails

## Hypothesis guidelines

Good hypotheses are:

- specific
- tied to concrete classes or methods
- falsifiable
- based on evidence from the trace

Avoid vague guesses like:

- "something is null somewhere"
- "configuration issue maybe"

Prefer concrete statements like:

- "`GetRaceUseCase.execute()` likely dereferences a missing repository result because the trace ends at `Optional.get()` and the API path is `GET /races/{id}`."

## Diagram template

Use a Mermaid flowchart similar to this:

```mermaid
flowchart TD
    A[HTTP request enters controller] --> B[Controller calls use case]
    B --> C[Use case queries repository]
    C --> D{Expected entity present?}
    D -- No --> E[Missing state / null / empty Optional]
    E --> F[Exception thrown]
    D -- Yes --> G[Normal response]
```

Adjust node labels to the concrete stack trace and code path.

## Test selection guidelines

### Use a unit test when

- the failure is inside a use case
- collaborators can be mocked
- the bug is a null, missing `Optional`, mapping error, or branch error

### Use a controller test when

- the failure depends on HTTP request handling
- status codes, JSON bodies, path variables, or request binding matter

### Use an integration test when

- multiple layers must collaborate to trigger the bug
- persistence or serialization is essential to reproduce it

## Project-specific rules

For this repository:

- application tests should use **JUnit 5 + Mockito**
- controller tests should use **`@WebMvcTest`**
- avoid `@SpringBootTest` for ordinary debugging work
- use domain repository interfaces as mocks, not JPA repositories
- keep use cases single-purpose with one public `execute(...)` method

## If the stack trace is incomplete

If the user provides only a partial trace, still proceed:

- identify the best visible application frame
- state what is known vs unknown
- give 2-3 bounded hypotheses
- suggest the minimal additional evidence that would reduce uncertainty

## Recommended default behavior

For this project, prefer the following order:

1. analyze pasted stack trace or available evidence
2. if the issue is unclear, stop and produce 2-3 hypotheses first
3. only after the failure path is credible, show Mermaid diagram
4. write failing reproduction test
5. fix code
6. verify the test passes

Do not skip the failing-test step unless the user explicitly asks to.
Do not skip the hypotheses-first step when the evidence is weak or ambiguous.

Let us see next, how we can use that skill.

Applying the Debug Skill on Different Problems

Easy Bug with Stack Trace

I’ve added a “java.util.NoSuchElementException: No value present” issue deliberately into our code. And triggered that issue. The resulting stack trace contains the following

There was an unexpected error (type=Internal Server Error, status=500).
No value present
java.util.NoSuchElementException: No value present
	at java.base/java.util.Optional.get(Optional.java:143)
	at com.ultratrail.application.GetRaceUseCase.execute(GetRaceUseCase.java:16)
	at com.ultratrail.api.RaceController.getRace(RaceController.java:46)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
	at java.base/java.lang.reflect.Method.invoke(Method.java:565)

We can now chat to Copilot and we see below that a skill was read and that skill is the debug one:

It generated a diagram that describes the issue. I believe this is important to review the issue easily. The diagram explains it in a way such that it only takes a few seconds. That helps to keep the understanding of the system alive and spot additional issues that could appear:

Then it continued by creating a test to reproduce the issue. This helps that the issue does not reappear in the future. It also fixed the issue because it is an easy fix:

Finally the view in our chat shows that the test was failing first. Then the fix (shown above) was applied and the rerun of the test also proved that the problem is fixed:

This ensures that we don’t have follow up issues and that the issue was reproduced and (most likely) correctly fixed. If we now would visit http://localhost:8080/api/races/12312 the result is “Race not found with id: 12312”.

Harder Issues where we Need Hypotheses

Now we try something harder that does not even have a stack trace:

Sometimes I have an issue on Production and the database is not responding with the results I would expect. Please help me. It's in the area of races. Sometimes it looks like there is just no connection to the DB.

How will CoPilot handle that?

We see that it helped telling in the SKILL.md that there should be no guesses. Thanks to those hypotheses listed we can deliver more evidence first before aimlessly trying to solve an unclear issue.

Consequences of Having a Debug Skill

For me mainly two aspects were important:

1. There’s a well defined debug procedure that allows to use AI.
2. But on the other hand, AI debugging should be kept inside some boundaries.

We all know that LLMs and coding agents try to always find a solution. I have seen coding agents iterating forever to find an issue. With above solution I wanted to prevent this endless loop of stupidly trying to solve and issue that might not even be in the context of the application. That is why the stopping condition is very important. The hypotheses and the collection of more evidence help to pinpoint the issue.

Developers will use AI to debug. That is guaranteed. I still believe that there should be a general understanding of issues. This helps to steer the agent better for further changes. That is why I also wanted a diagram as output. The diagram should explain the problem such that the develop understands in a few seconds what was happening.

The post A Debug Skill for Your Coding Agent appeared first on Ronnie Schaniel.

Agent skills are folders of instructions, scripts, and resources. Copilot can load the files when required to fulfil specialised tasks. Agentskills is an open standard and therefore should be a good choice for sharing. We will try it out and see how skills can be helpful in a Java Spring Boot project based on hexagonal architecture.

What Agent Skills do we need?

Our demo application is the same that we used in Hexagonal Architecture in Spring Boot Projects with AI. The theme is the one of Ultra Trail races. And the backend currently allows to manage races with their plans, segments, and accommodation. Alongside the Spring backend that offers the DB and the APIs we have a Angular frontend in the same repository.

In such a full-stack mono repo, I can think about the following agent skills:

1. Transforming the Java DTOs on the backend to TypeScript models on the frontend.
2. Generating a use case on the backend.
3. Implementation of a backend HTTP call to a third-party system based on an Open API definition.
4. Creating a e2e test based on the frontend and the backend mocks.
5. Retrieve the latest CI/CD log for failures and support in fixing.
6. Create API tests for the backend based on domain knowledge.

Let us explore the first idea in more detail and create a skill for model creation out of DTOs.

Creating the Agent Skills

Because a skill can involved scripts, we will make use of that. Under the .github folder in our repository we create a skills folder and add a first skill folder controller-data-to-ts-models. Now inside that folder we need a SKILL.md file with a defined structure:

---
name: controller-data-to-ts-models
description: Generate TypeScript model files from data contracts exposed by Spring controllers (@RequestBody and ResponseEntity<T>). Use this when asked to keep frontend models aligned with API controller contracts.
---

# Skill: Controller Data → TypeScript Models

## Purpose

Generate frontend TypeScript model files from the data contracts exposed by Spring controllers:

- request payload types from `@RequestBody`
- response payload types from `ResponseEntity<T>`

This keeps Angular models aligned with API contracts instead of generating from every domain class.

## Scope

The generator scans:

- `src/main/java/com/ultratrail/api/*Controller.java`

It resolves and emits models for referenced classes from:

- `src/main/java/com/ultratrail/application/*Command.java`
- `src/main/java/com/ultratrail/domain/*.java`

## Output

Generated files are written to:

- `frontend/src/app/models/*.model.ts`

If a model file already exists with the same name, it is overwritten.

## Run

From project root:

```bash
node .github/skills/controller-data-to-ts-models/generate-controller-ts-models.mjs
```

Or from any directory inside the repository:

```bash
node /absolute/path/to/repo/.github/skills/controller-data-to-ts-models/generate-controller-ts-models.mjs
```

## Mapping rules

- `String`, `LocalDate`, `LocalDateTime`, `Instant`, `UUID` → `string`
- `Integer`, `Long`, `Double`, `Float`, `BigDecimal` → `number`
- `Boolean` → `boolean`
- `List<T>`, `Set<T>`, `Collection<T>` → `T[]`
- Java nested enums (e.g., `Race.RaceStatus`) are emitted as TS union types.
- Field `id` is generated as optional (`id?: ...`).

## Notes

- The generator is intentionally contract-focused and does not modify existing handcrafted models.
- If you change controller request/response types, rerun the generator to refresh the generated files.

And alongside the standard file follows our script generate-controller-ts-models.mjs. Here just some extracts of it such that you get the basic understanding:

...

function listControllerFiles() {
  if (!fs.existsSync(apiDir)) return [];
  return fs
    .readdirSync(apiDir)
    .filter((file) => file.endsWith('Controller.java'))
    .map((file) => path.join(apiDir, file));
}

... 

function parseFields(content) {
  const fields = [];
  const fieldRegex = /private\s+([A-Za-z0-9_$.<>]+)\s+([A-Za-z0-9_]+)\s*;/g;
  let match;
  while ((match = fieldRegex.exec(content)) !== null) {
    fields.push({
      javaType: sanitizeType(match[1]),
      name: match[2],
    });
  }
  return fields;
}

This is the skill. And now we need to see how we can use it.

Make CoPilot use the new Agent Skill

First of all you need to make sure that CoPilot skills are enabled in your IDE. I’m taking vscode as an example and you can search for “skills” in the settings and tick the checkbox:

Then we are ready to go. Let us have a look at the AccommodationController.java where we find various endpoints using DTOs:

@GetMapping
public ResponseEntity<List<Accommodation>> getAccommodations(@PathVariable String raceId) {
    return ResponseEntity.ok(getAccommodationsByRaceUseCase.execute(raceId));
}

In this case here, the DTO would be Accommodation and it looks as follows:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Accommodation {
    private String id;
    private String raceId;
    private String name;
    private String location;
    private AccommodationType type;
    private LocalDate checkIn;
    private LocalDate checkOut;
    private Boolean breakfastIncluded;
    private BigDecimal pricePerNight;
    private BigDecimal distanceToStartKm;
    private BigDecimal distanceToFinishKm;
    private RoomType roomType;
    private Integer numberOfGuests;

    public enum AccommodationType {
        RACE_START, RACE_FINISH, FULL_STAY
    }

    public enum RoomType {
        SINGLE, DOUBLE
    }
}

Now over to Copilot:

I click “Allow” and the script’s skill starts to do its work and reports back after only a few seconds. In my case it updated all the models which is okay:

This gives us the following model in the frontend for the Accommodation interface:

export interface Accommodation {
  id?: string;
  raceId: string;
  name: string;
  location: string;
  type: AccommodationType;
  checkIn: string;
  checkOut: string;
  breakfastIncluded: boolean;
  pricePerNight: number;
  distanceToStartKm: number;
  distanceToFinishKm: number;
  roomType: RoomType;
  numberOfGuests: number;
}

export type AccommodationType = 'RACE_START' | 'RACE_FINISH' | 'FULL_STAY';
export type RoomType = 'SINGLE' | 'DOUBLE';

We see that the types were mapped correctly.

What are the Differences to Instructions, Prompts and Custom Agents?

Agent Skills are modular, on-demand, and portable AI capabilities containing specific instructions and tools, whereas custom instructions are persistent, general-purpose directives that apply to every interaction. In my experience agent skills are a great combination of well defined scripts and the power of an LLM. You have the determinism of a script that gives you more safety. Other than that, it’s also cheaper to execute the scripts than to really on AI to do the transformation. Prompts are on-demand commands executed by typing, e.g. /review, for a review prompt. They are made for repeatable one-shot functionalities.

If we would like to compare all of it, the following table can help:

Best is if you try out the various possibilities you have. And remember that you can always let AI itself create the skills, prompts, instructions and agents.

^{All my articles are written by myself. AI is used for some of the title images and in some cases to improve the wording and flow.}

The post Agent Skills for Hexagonal Architecture in Spring Boot appeared first on Ronnie Schaniel.

The advent of AI has revolutionised the way software engineers approach programming. While we can now leverage code generation in various ways, I firmly believe that structure remains essential! AI excels at recognising patterns and working consistently when given guidance. Moreover, the abstraction level has increased, allowing developers to focus more on business logic as well as overall architecture and less on implementation details. Given this, combining AI-generated code with hexagonal architecture should be an intriguing combination. In this article, we will delve into this concept in the context of a full-stack application, specifically focusing on an ultra-running theme (races longer than 42.2km or 26 miles).

The Application and its Hexagonal Structure

Our application is designed to manage races and related athlete information. The main view provides an overview of upcoming events, as depicted in the image below:

On the detail view of a specific race, users can edit attributes, add segments, and input other relevant details, as shown in the next screenshot:

Now, let’s take a more technical look at our application. At its core lies the principle of hexagonal, onion, or clean architecture, which dictates that everything revolves around the domain. In this context, infrastructural aspects such as storage and API exposure are dependent on the domain, rather than the other way around. Use cases complete the picture by describing what happens within the domain.

The following diagram provides a visual representation of our hexagonal structure, highlighting a single use case for the Race domain as an example:

In the next section, we’ll explore how AI coding agents can be informed about the desired structure and important details, enabling seamless integration with our application.

Defining Guardrails for AI with ArchUnit and Instruction Files

To ensure our architecture remains consistent, we’ll employ ArchUnit, a Java library designed to unit test architectural structures. This approach provides guardrails that help maintain the desired structure. Additionally, we’ll create instruction files for GitHub CoPilot to specify the preferred Java code style.

Describing the Application Architecture with ArchUnit

We will write tests in five areas to ensure our architecture is well-defined:

1. Dependency Allowance: Verifying the allowed dependencies between the domain, API, infrastructure, and application layers.
2. Boundary Checks: Additional checks for boundaries not covered by the initial architecture test (e.g., library usage).
3. Naming Conventions: Enforcing consistent naming conventions throughout the codebase.
4. Structural Rules for Classes: Validating class structure rules to maintain a cohesive architecture.
5. Circular Dependency Check: Ensuring that dependencies between application parts are respected and follow the desired design without circles.

Below is the most important check that ensures the dependencies rules between the different parts of the application are respected:

@ArchTest
static final ArchRule layerDependenciesAreRespected =
    layeredArchitecture()
        .consideringAllDependencies()
        .layer("Domain").definedBy("com.ultratrail.domain..")
        .layer("Application").definedBy("com.ultratrail.application..")
        .layer("API").definedBy("com.ultratrail.api..")
        .layer("Infrastructure").definedBy("com.ultratrail.infrastructure..")

        .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "API", "Infrastructure")
        .whereLayer("Application").mayOnlyBeAccessedByLayers("API")
        .whereLayer("Infrastructure").mayNotBeAccessedByAnyLayer()
        .whereLayer("API").mayNotBeAccessedByAnyLayer();

To begin, we define the packages for each layer: Domain, Application, API, and Infrastructure. This serves as the foundation for our architecture, allowing us to identify the distinct layers.
Next, we determine which layers may be accessed by others. For instance, the Domain layer should not access other layers directly, ensuring a clear separation of concerns. By defining these boundaries, we establish the guardrails that govern our application’s architecture.

For additional boundaries, we add another test:

@ArchTest
static final ArchRule domainMustBeFrameworkFree =
    noClasses().that().resideInAPackage("com.ultratrail.domain..")
        .should().dependOnClassesThat()
        .resideInAnyPackage(
                "org.springframework..",
                "jakarta.persistence..",
                "javax.persistence.."
        )
        .because("The domain layer must not depend on any framework.");

@ArchTest
static final ArchRule applicationMustNotUseJpa =
    noClasses().that().resideInAPackage("com.ultratrail.application..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("jakarta.persistence..", "javax.persistence..")
        .because("The application layer must not use JPA directly.");

@ArchTest
static final ArchRule applicationMustNotUseSpringMvc =
    noClasses().that().resideInAPackage("com.ultratrail.application..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("org.springframework.web..", "jakarta.servlet..")
        .because("The application layer must not depend on Spring MVC or Servlet API.");

@ArchTest
static final ArchRule apiMustNotUseJpa =
    noClasses().that().resideInAPackage("com.ultratrail.api..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("jakarta.persistence..", "javax.persistence..")
        .because("The API layer must not use JPA directly.");

A third test covers naming conventions, ensuring consistency and clarity in our codebase:

@ArchTest
static final ArchRule useCasesMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.application..")
        .and().areAnnotatedWith(org.springframework.stereotype.Service.class)
        .should().haveSimpleNameEndingWith("UseCase")
        .because("All @Service classes in the application layer must be named *UseCase.");

@ArchTest
static final ArchRule commandsMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.application..")
        .and().areNotAnnotatedWith(org.springframework.stereotype.Service.class)
        .and().areNotAssignableTo(RuntimeException.class)
        .and().areNotInterfaces()
        .should().haveSimpleNameEndingWith("Command")
        .because("Non-use-case, non-exception classes in the application layer must be named *Command.");

@ArchTest
static final ArchRule exceptionsMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.application..")
        .and().areAssignableTo(RuntimeException.class)
        .should().haveSimpleNameEndingWith("NotFoundException")
        .because("Domain exceptions in the application layer must be named *NotFoundException.");

@ArchTest
static final ArchRule controllersMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.api..")
        .and().areAnnotatedWith(org.springframework.web.bind.annotation.RestController.class)
        .should().haveSimpleNameEndingWith("Controller")
        .because("All REST controllers must be named *Controller.");

@ArchTest
static final ArchRule repositoryAdaptersMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.infrastructure..")
        .and().areAnnotatedWith(org.springframework.stereotype.Component.class)
        .and().areNotInterfaces()
        .should().haveSimpleNameEndingWith("RepositoryAdapter")
        .because("Infrastructure adapters must be named *RepositoryAdapter.");

@ArchTest
static final ArchRule jpaEntitiesMustBeNamedCorrectly =
    classes().that().resideInAPackage("com.ultratrail.infrastructure..")
        .and().areAnnotatedWith(jakarta.persistence.Entity.class)
        .should().haveSimpleNameEndingWith("Entity")
        .because("JPA entity classes must be named *Entity.");

Additionally, more structural rules are defined below to further refine our architectural design.

@ArchTest
static final ArchRule useCaseFieldsMustBeFinal =
    classes().that().resideInAPackage("com.ultratrail.application..")
        .and().haveSimpleNameEndingWith("UseCase")
        .should().haveOnlyFinalFields()
        .because("Use case classes must have only final (injected) fields — no mutable state.");

@ArchTest
static final ArchRule noFieldInjectionAnywhere =
    noFields().that().areDeclaredInClassesThat()
        .resideInAnyPackage(
                "com.ultratrail.domain..",
                "com.ultratrail.application..",
                "com.ultratrail.api..",
                "com.ultratrail.infrastructure.."
        )
        .should().beAnnotatedWith(org.springframework.beans.factory.annotation.Autowired.class)
        .because("Field injection with @Autowired is forbidden. Use constructor injection.");

@ArchTest
static final ArchRule controllersMustNotDependOnRepositories =
    noClasses().that().resideInAPackage("com.ultratrail.api..")
        .and().areAnnotatedWith(org.springframework.web.bind.annotation.RestController.class)
        .should().dependOnClassesThat()
        .haveSimpleNameEndingWith("Repository")
        .because("Controllers must not directly depend on repository interfaces — inject use cases instead.");

And finally, we ensure that no circular dependencies occur, guaranteeing the stability and maintainability of our architecture.

@ArchTest
static final ArchRule noCircularDependenciesBetweenLayers =
    slices().matching("com.ultratrail.(*)..").should().beFreeOfCycles()
        .because("There must be no circular dependencies between architecture layers.");

With these ArchUnit tests in place, our AI coding agents are provided with clear boundaries to operate within. Now, let’s explore further steering possibilities through instruction files.

Creating Instruction Files to Guide GitHub CoPilot

Instruction files play a crucial role in providing context and guidance for your AI coding agents. By placing these files in the .github/instructions directory, you can help your agent understand how to build, test, and validate changes.

Let’s begin by creating instructions for the core of our hexagonal architecture – the Domain. This will be defined in a domain.instructions.md file:

---
applyTo: "src/main/java/com/ultratrail/domain/**"
---

# Domain Layer Rules

You are generating code in the **domain layer** (`com.ultratrail.domain`).
This layer is the core of the hexagonal architecture and must remain 100 % framework-free.

## Strict Rules

### Allowed imports
- `java.*`
- `lombok.*`
- Other `com.ultratrail.domain.*` classes

### Forbidden imports – NEVER add these
- `org.springframework.*`
- `jakarta.persistence.*` / `javax.persistence.*`
- `com.ultratrail.application.*`
- `com.ultratrail.api.*`
- `com.ultratrail.infrastructure.*`

### Domain Entities
- Annotate every entity with `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor` (Lombok).
- All IDs are `String` (UUID format).
- Do **not** add `@Entity`, `@Table`, `@Column`, or any JPA annotation.
- Embed domain-specific enums as static nested enums inside the owning entity.
- Do not add Spring bean annotations (`@Service`, `@Component`, `@Repository`).
- No business logic methods that depend on external services.

### Repository Interfaces (Ports)
- Repository interfaces are pure Java interfaces — they define the port, not the implementation.
- Name them `<Entity>Repository` (e.g., `RaceRepository`).
- Only use domain types as parameter and return types.
- Common methods: `save`, `findById`, `findAll`, `delete`. Add domain-specific finders as needed.

## Example

```java
package com.ultratrail.domain;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Race {
    private String id;
    private String name;

    public enum RaceStatus { PLANNED, REGISTERED, COMPLETED, DNF, DNS }
}
```

```java
package com.ultratrail.domain;

import java.util.List;
import java.util.Optional;

public interface RaceRepository {
    Race save(Race race);
    Optional<Race> findById(String id);
    List<Race> findAll();
    void delete(String id);
}
```

The Application part is described in application.instructions.md:

---
applyTo: "src/main/java/com/ultratrail/application/**"
---

# Application Layer Rules

You are generating code in the **application layer** (`com.ultratrail.application`).
This layer orchestrates use cases and acts as the bridge between the API and the domain.

## Strict Rules

### Allowed imports
- `com.ultratrail.domain.*`
- `org.springframework.stereotype.Service` (use cases only)
- `lombok.*`
- `java.*`

### Forbidden imports – NEVER add these
- `com.ultratrail.api.*`
- `com.ultratrail.infrastructure.*`
- `jakarta.persistence.*` / `javax.persistence.*`
- `org.springframework.web.*`
- `jakarta.servlet.*`
- Any Spring MVC annotation (`@RestController`, `@RequestMapping`, etc.)

---

## Use Cases

- Each use case is a **single class with one public method** named `execute(...)`.
- Annotate with `@Service` and `@AllArgsConstructor` — no other Spring annotations.
- Use constructor injection only. Never use `@Autowired` on fields.
- Inject domain repository interfaces (ports), never JPA repositories.
- Generate new IDs with `UUID.randomUUID().toString()`.
- Naming: `<Verb><Entity>UseCase` (e.g., `CreateRaceUseCase`, `UpdateRaceStatusUseCase`).

```java
@Service
@AllArgsConstructor
public class CreateRaceUseCase {
    private final RaceRepository raceRepository;

    public Race execute(CreateRaceCommand command) {
        Race race = Race.builder()
                .id(UUID.randomUUID().toString())
                .name(command.getName())
                // ... map remaining fields
                .build();
        return raceRepository.save(race);
    }
}
```

---

## Commands

- Commands are plain data holders with **no business logic**.
- Annotate with `@Data`, `@NoArgsConstructor`, `@AllArgsConstructor` (Lombok).
- No validation annotations unless explicitly requested.
- Naming: `<Verb><Entity>Command` (e.g., `CreateRaceCommand`, `AddSegmentCommand`).

```java
@Data
@NoArgsConstructor
@AllArgsConstructor
public class CreateRaceCommand {
    private String name;
    private String location;
}
```

---

## Domain Exceptions

- Extend `RuntimeException`.
- Belong in this package (not in domain).
- Naming: `<Entity>NotFoundException` (e.g., `RaceNotFoundException`, `RacePlanNotFoundException`).

```java
public class RaceNotFoundException extends RuntimeException {
    public RaceNotFoundException(String id) {
        super("Race not found with id: " + id);
    }
}
```

Yet another important aspect is defined in infrastructure.instructions.md.

---
applyTo: "src/main/java/com/ultratrail/infrastructure/**"
---

# Infrastructure Layer Rules

You are generating code in the **infrastructure layer** (`com.ultratrail.infrastructure`).
This layer is the outbound adapter: it implements domain ports using Spring Data JPA.

## Strict Rules

### Allowed imports
- `com.ultratrail.domain.*` (to implement repository ports)
- `org.springframework.data.jpa.repository.*`
- `org.springframework.stereotype.Component`
- `jakarta.persistence.*`
- `lombok.*`
- `java.*`

### Forbidden imports – NEVER add these
- `com.ultratrail.api.*`
- `com.ultratrail.application.*`
- `org.springframework.stereotype.Service`
- `org.springframework.web.*`

---

## Repository Adapters

- Annotate with `@Component` and `@AllArgsConstructor`.
- Each adapter **implements exactly one domain repository interface**.
- Delegate every method to a Spring Data JPA repository.
- Convert between domain objects and JPA entities using `fromDomain()` and `toDomain()`.
- JPA entities must **never** appear in method signatures exposed to other layers.
- Naming: `<Entity>RepositoryAdapter` (e.g., `RaceRepositoryAdapter`).

```java
@Component
@AllArgsConstructor
public class RaceRepositoryAdapter implements RaceRepository {
    private final JpaRaceRepository jpaRaceRepository;

    @Override
    public Race save(Race race) {
        return jpaRaceRepository.save(RaceEntity.fromDomain(race)).toDomain();
    }

    @Override
    public Optional<Race> findById(String id) {
        return jpaRaceRepository.findById(id).map(RaceEntity::toDomain);
    }

    @Override
    public List<Race> findAll() {
        return jpaRaceRepository.findAll().stream()
                .map(RaceEntity::toDomain)
                .collect(Collectors.toList());
    }

    @Override
    public void delete(String id) {
        jpaRaceRepository.deleteById(id);
    }
}
```

---

## Spring Data JPA Repositories

- Interface extending `JpaRepository<Entity, String>`.
- Naming: `Jpa<Entity>Repository` (e.g., `JpaRaceRepository`).
- Only add custom query methods as needed.

```java
public interface JpaRaceRepository extends JpaRepository<RaceEntity, String> {
    List<RaceEntity> findByStatus(Race.RaceStatus status);
}
```

---

## JPA Entities

- Annotate with `@Entity`, `@Table`, `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`.
- Must include `fromDomain(Domain d)` static factory method and `toDomain()` instance method.
- JPA entities stay confined to this package — never returned from use cases or controllers.
- Naming: `<Entity>Entity` (e.g., `RaceEntity`).

```java
@Entity
@Table(name = "races")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class RaceEntity {
    @Id
    private String id;

    @Column(nullable = false)
    private String name;

    public static RaceEntity fromDomain(Race race) {
        return RaceEntity.builder()
                .id(race.getId())
                .name(race.getName())
                .build();
    }

    public Race toDomain() {
        return Race.builder()
                .id(this.id)
                .name(this.name)
                .build();
    }
}
```

The API exposes our functionality as RESTful HTTP endpoints, described in api.instructions.md.

---
applyTo: "src/main/java/com/ultratrail/api/**"
---

# API Layer Rules

You are generating code in the **API layer** (`com.ultratrail.api`).
This layer is the inbound adapter: it receives HTTP requests and delegates work to use cases.

## Strict Rules

### Allowed imports
- `com.ultratrail.application.*` (use cases and commands)
- `com.ultratrail.domain.*` (domain entities used only as response types)
- `org.springframework.web.*`
- `org.springframework.http.*`
- `lombok.AllArgsConstructor`
- `java.*`

### Forbidden imports – NEVER add these
- `com.ultratrail.infrastructure.*`
- `jakarta.persistence.*` / `javax.persistence.*`
- Any JPA repository interface
- `org.springframework.stereotype.Service`

---

## Controllers

- Annotate with `@RestController`, `@RequestMapping`, `@AllArgsConstructor`.
- Inject **only use cases** — never repositories, domain services, or infrastructure classes.
- Every HTTP method calls exactly one use case via `.execute(...)`.
- Return `ResponseEntity<T>` for every handler method.
- No business logic inside controllers. Mapping between HTTP and domain happens only by passing commands.
- Use `@PathVariable`, `@RequestBody`, `@RequestParam` for input binding.
- Naming: `<Entity>Controller` (e.g., `RaceController`, `RaceSegmentController`).

```java
@RestController
@RequestMapping("/races")
@AllArgsConstructor
public class RaceController {
    private final CreateRaceUseCase createRaceUseCase;
    private final GetRaceUseCase getRaceUseCase;
    private final DeleteRaceUseCase deleteRaceUseCase;

    @PostMapping
    public ResponseEntity<Race> createRace(@RequestBody CreateRaceCommand command) {
        return ResponseEntity.status(HttpStatus.CREATED).body(createRaceUseCase.execute(command));
    }

    @GetMapping("/{id}")
    public ResponseEntity<Race> getRace(@PathVariable String id) {
        return getRaceUseCase.execute(id)
                .map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.notFound().build());
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteRace(@PathVariable String id) {
        deleteRaceUseCase.execute(id);
        return ResponseEntity.noContent().build();
    }
}
```

---

## Controller Tests

Use `@WebMvcTest` with mocked use cases. Never load the full application context for controller tests.

```java
@WebMvcTest(RaceController.class)
class RaceControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean CreateRaceUseCase createRaceUseCase;
    // ...
}
```

Besides all the application layers, we also define a testing aspect, which is described in testing.instructions.md.

---
applyTo: "src/test/java/com/ultratrail/**"
---

# Testing Rules

You are generating test code for the Ultra Trail Manager project.
Follow these rules to ensure tests are focused, fast, and do not violate the hexagonal architecture.

---

## Use Case Tests (Application Layer)

- Use **plain JUnit 5 + Mockito** — no Spring context.
- Annotate with `@ExtendWith(MockitoExtension.class)`.
- Mock domain repository interfaces with `@Mock`. Never mock JPA repositories.
- Instantiate use cases manually via constructor.
- Naming: `<UseCaseClass>Test` (e.g., `CreateRaceUseCaseTest`).

```java
@ExtendWith(MockitoExtension.class)
class CreateRaceUseCaseTest {

    @Mock
    private RaceRepository raceRepository;

    private CreateRaceUseCase useCase;

    @BeforeEach
    void setUp() {
        useCase = new CreateRaceUseCase(raceRepository);
    }

    @Test
    void shouldCreateRaceWithPlannedStatus() {
        CreateRaceCommand command = new CreateRaceCommand("UTMB", "Chamonix");
        when(raceRepository.save(any(Race.class))).thenAnswer(inv -> inv.getArgument(0));

        Race result = useCase.execute(command);

        assertNotNull(result.getId());
        assertEquals(Race.RaceStatus.PLANNED, result.getStatus());
        verify(raceRepository).save(any(Race.class));
    }
}
```

---

## Controller Tests (API Layer)

- Use `@WebMvcTest(<Controller>.class)` — loads only the web layer.
- Mock all use cases with `@MockBean`.
- Inject `MockMvc` with `@Autowired`.
- Do **not** use `@SpringBootTest` for controller tests.

```java
@WebMvcTest(RaceController.class)
class RaceControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private CreateRaceUseCase createRaceUseCase;

    @Test
    void shouldReturnCreatedStatusOnPost() throws Exception {
        when(createRaceUseCase.execute(any())).thenReturn(Race.builder().id("1").build());

        mockMvc.perform(post("/races")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"name\":\"UTMB\"}"))
                .andExpect(status().isCreated());
    }
}
```

---

## Architecture Tests

- Use ArchUnit in `HexagonalArchitectureTest` to enforce all layer boundaries.
- These tests live in `src/test/java/com/ultratrail/architecture/`.
- Do **not** use `@SpringBootTest` here.
- Run as standard JUnit 5 tests (`@AnalyzeClasses` + `@ArchTest`).

---

## General Rules

- Do **not** use `@SpringBootTest` for unit tests. It loads the full application context and is too heavy.
- Test class must be in the same package as the class under test.
- One test class per production class.
- Test method names use `should<Behaviour>When<Condition>` format.

These files provide the necessary structure for our project, offering clear guidelines for our AI coding agents to work within.

Extending the Application

Now that we have our foundation in place, let’s put our ArchUnit tests and instruction files to the test. We’ve already established a solid structure with races, segments, and plans for each race. As we continue to grow our application, we’ll explore more features.

For instance, ultra races often take place far from home, spanning multiple days if the distance is significant, such as 100 miles or 160km. Planning accommodations as an athlete is crucial in these situations. Sometimes, the start and finish of a race can even be located in different areas.

To extend our application, I’ll send this prompt:

Extend the application by another feature. The feature is about accommodation. Each race needs accommodation possibilities that one can maintain in a CRUD manner. There could be a single accommodation for the duration of the race, and the days, before and after. But there could also be the case where an accommodation is taken before the race at the race start, and another one at the race finish location. Breakfast is an important option that should be made visible if available. Other than that the price and the distance to start or distance to the finish line are crucial. Another aspects is the number of guests. Sometimes you would like to travel with someone and need a double room. Sometimes a single room is enough and also cheaper.

How does CoPilot work? After submitting the prompt, CoPilot springs into action, analyzing the request and generating a list of potential next steps. In this case, it identifies six TODOs that can be explored further.

The AI agent then uses its existing knowledge to study these patterns and find ways to integrate them seamlessly:

CoPilot summarizes the changes by providing a report of all the passed tests, including the Hexagonal Architecture Test. This ensures that our codebase continues to adhere to the architecture we’ve established, ensuring stability and maintainability in the long run.

Finally, we can visually inspect our application to ensure everything is working as intended. For instance, let’s take a closer look at the Domain class:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Accommodation {
    private String id;
    private String raceId;
    private String name;
    private String location;
    private AccommodationType type;
    private LocalDate checkIn;
    private LocalDate checkOut;
    private Boolean breakfastIncluded;
    private BigDecimal pricePerNight;
    private BigDecimal distanceToStartKm;
    private BigDecimal distanceToFinishKm;
    private RoomType roomType;
    private Integer numberOfGuests;

    public enum AccommodationType {
        RACE_START, RACE_FINISH, FULL_STAY
    }

    public enum RoomType {
        SINGLE, DOUBLE
    }
}

I like the categorisation in RACE_START, RACE_FINISH, and FULL_STAY. Additionally, the frontend has been extended (by a separate prompt) to display accommodation options, providing users with a more comprehensive view of their stay arrangements.

And there you have it! By leveraging ArchUnit tests and instruction files, we were able to extend our application with a new feature in just 10 minutes, without compromising its underlying structure or architecture. This approach has proven to be highly effective in promoting maintainability, scalability, and extensibility for future features.

Summary

As software engineers we ask ourselves how much we should vibe code? Additionally, we wonder what an application would look like if it were extended solely by AI over an extended period?

I believe that an application seriously deteriorates in quality over time if only extended by AI in a naive way without much guardrails. Understanding the architecture is more crucial than ever. But once that is defined well and put into mechanisms to verify, the engineer can focus on what really matters: the business logic and new features.

By striking a balance between human oversight and AI-assisted development, we can create applications that are both maintainable and scalable – a true win-win for software engineers.

^{All my articles are written by myself. AI is used for some of the title images and in some cases to improve the wording and flow.}

The post Hexagonal Architecture in Spring Boot Projects with AI appeared first on Ronnie Schaniel.

AI coding assistants emerged in spring 2023. Since then, those who aren’t familiar with software engineering have predicted that the role of the software engineer would become obsolete. Three years on, we’re still here. While our daily work has undergone changes, so too must our calculations of costs and understanding of time.

The Cost and Time View before AI Coding Assistants

Let us first consider the traditional approach. When faced with a task, one, two, or many engineers would be assigned to implement it, depending on their Agile methodology. The design phase, whether lengthy or brief, would precede implementation. The engineer(s) involved would have an in-depth understanding of all details. Next, the development process would unfold, including reviewing written code, manually or automatically testing on integration environments, and deployment and release. In the event of detected issues, they would be addressed. Crucially, knowledge was embedded within the engineers participating in each phase, making subsequent changes more manageable.

Typically, developers focused on a single task at a time, aiming to minimize context switches due to their inherent cost. Team velocity was calculated by dividing delivered story points by capacity.

This is how I see software engineering without AI support:

• In Agile environments, the design phase is relatively brief. You might consider how a new user story fits into the overall system, but you wouldn’t typically document every detail of your planned implementation.
• The majority of work is invested in the implementation and maintenance phases. While some may argue for an even longer maintenance period.
• The review phase, which includes merge request reviews, relies heavily on the quality and clarity of the implementation. It tends to be shorter than the implementation phase itself.
• Testing encompasses both automated and manual acceptance testing, with the majority of testing ideally taking place during the implementation phase. The quality of the implementation has a significant impact on this process. In general, writing automated acceptance tests at the UI level requires some time.

From a cost or effort perspective, we observe the following:

• Developers typically focus on one task at a time, dedicating their attention to that specific project.
• On the cost side, there is the developer’s salary, as well as expenses for traditional tools and licenses.

Now, let us examine how this has evolved with the emergence of coding assistants.

The Current State of AI-Supported Software Engineering

We are having a look at the situation when AI coding assistants are used by the developers. The following picture illustrates the shifted distribution of phases:

• In this new scenario, the design phase typically becomes longer. This is because you need to provide more detailed specifications upfront for the AI agent to effectively implement the requirements.
• The most significant change occurs in the Implementation phase, which tends to be shortened. Writing code is relatively easy for coding assistants to handle.
• On the other hand, the review process becomes even more crucial and time-consuming. First, you must read the description of what the AI assistant did, followed by a review of the actual code itself.
• The testing phase itself might become slightly shorter, as automated acceptance tests can also be generated by AI. On the other hand you need to ensure that the right thing was implemented by the AI and acceptance criteria are met.
• Finally, I would argue that the maintenance phase is expanded relatively seen. As you haven’t been intimately involved in every detail yourself, finding bugs and understanding existing code can be more challenging. Moreover, AI often tends to create verbose code, making implementation more complicated than it needs to be – a situation that leads to more and harder-to-maintain code. For sure, also AI can be used to debug which again helps to keep the effort lower.

From a cost or effort perspective, we observe the following:

• Developers can now work on multiple tasks at a time, especially when utilizing the agentic mode of AI coding assistants. However, this comes with increased context switching, which has its own set of drawbacks.
• On the cost side, there is the developer’s salary, as well as traditional tools and licenses. Furthermore, expenses arise from the fee associated with using the coding assistant.

Consequences for Software Engineering

The Design Phase: More Important than Ever

In this new world of AI-assisted software engineering, the design phase becomes even more critical. Implicit knowledge that was previously shared through informal channels or coffee breaks now needs to be documented and provided as input for AI.

Implementation Phase

Developers are typically fast typists, but AI can generate code even faster. This results in a shortened implementation phase. Moreover, multiple agents can run in parallel, allowing developers to perform other tasks simultaneously. A developer can have a coding agent running in the background while checking emails, for instance.

However, this increased productivity also introduces the danger of complacency. Developers might become too reliant on AI-generated code and neglect the importance of reviewing and maintaining it. As such, the review phase assumes greater significance, requiring more time and expertise from engineers.

Review

When so much code is produced, review can become a bottleneck (also suggested in the 2025 DORA report). And if it is not done properly, it can lead to quality issues. What makes reviewing even more challenging, is that the code which was produced is not necessarily understandable by juniors or even some seniors. While being careful is also here more important than ever, using AI in the review process itself can also help.

Testing

Testing remains a vital aspect of software engineering. While some automated acceptance tests can be generated by AI, manual testing is still essential for ensuring the quality of the final product.

Maintenance Phase

Maintaining code is all about fixing problems, monitoring performance, and extending functionality. In this new world, I believe this phase requires more effort relative to the original process. Developers are less familiar with the generated code, which can lead to increased mental stress when switching between multiple instances of AI-generated code.

Cost Considerations

License and tool costs have always been a consideration in software engineering. The rise of AI-assisted coding tools like Copilot, Amazon Q, and others may introduce new expenses. As these subscriptions evolve, it’s crucial to factor them into the overall economic calculation of software development costs.

Limitations of AI-Assistance

While AI can certainly augment human capabilities, there are still cases where traditional expertise is essential. For instance, when dealing with complex bugs or system design issues, human intuition and experience are invaluable assets.

Velocity and Complexity

It’s possible that the increased productivity in the implementation phase will lead to higher throughput and more story points delivered per capacity. However, this might also introduce new complexities that require reevaluation of estimation methods. Only time and experience will tell how these changes play out.

Ultimately, as AI-assisted software engineering becomes more prevalent, it’s crucial that we have enough capable engineers on hand to design, review, and maintain the generated code properly. Otherwise, there may be bottlenecks and no overall efficiency gain can be achieved. In the same direction, supporting only one activity in the whole software development life cycle will lead to bottlenecks or inefficiencies. It is crucial to apply AI in every phase to support engineers.

Conclusion

Please note that these thoughts are based on a somewhat idealistic and simplistic model. As a software developer myself, I am aware that our daily work does not always align with this scenario. Nevertheless, our work has undergone changes, and our understanding of the job must adapt too. One thing is certain: we require competent engineers like always.

^{All my articles are written by myself. AI is used for some of the title images and in some cases to improve the wording and flow.}

The post The Cost and Time Model of AI-Assisted Software Engineering appeared first on Ronnie Schaniel.

Some developers are vibe-coding whole applications (if you believe them). Others are using AI coding assistants for a more intelligent autocomplete, to generate or edit some snippets, or just asking questions about code or other topics. And yet another group of software engineers are totally against AI coding assistants and rarely use them. Anyway, having your code reviewed by AI is usually not a bad idea. And gamifying that approach could motivate all of the above types.

The prompt

The goal for our review is to have an output considering different factors. Each factor should be rated from 1 to 10 in 0.5 increments. There should then be also actionable suggestion on how to improve the code. I have tried various variants and ended up with the following:

Assess the provided code based on the following criteria using a 1-10 scale:

Potential Bugs (1=high risk, 10=very low risk)
How likely is this code to introduce bugs or errors?

Tests (1=no tests, 10=comprehensive coverage)
Are there sufficient tests? Is the testing strategy robust?

Clarity (1=very unclear, 10=crystal clear)
How easy is it to understand the code's intent, logic, and structure through reading?

Consistency (1=very inconsistent, 10=fitting in perfectly)
How consistent is the added code. Are there new patterns in naming, design, style or is it very consistent with existing code?

Testability (1=very difficult to test, 10=highly testable)
Can the code be easily tested in isolation?

Design (1=poorly designed, 10=well-designed)
How well-architected is the code in terms of organization and modularity?

Security (1=high risk, 10=very low risk)
Are there potential security vulnerabilities?

Average Score: Calculate the average of the six criteria.

List the scores per category in a table with the average in the last row (always in the form of x/10). Provide the 2-5 most urgent suggestions to improve in a compact form. Ask the developer if more information about improvements are needed. You need to rate consistently throughout.

This delivered for me the best results. I wanted to have a brief summary with only a few suggestions in the beginning. This would allow me to revisit the mentioned code myself and ask for more details if needed. Of course you could even ask AI to do the improvements itself.

Review some bad code

I have tried the above prompt on some code and got the following compact response:

So here we have a lot of potential to improve.

Scoring well

After some improvements I can run the prompt again and I score now 8.3 on average, compared to the 4.6 before:

Is the code now very good and I don’t need a human review at all? Definitely not! Even you should review again if the changes were done by AI. But once pushed to the remote your peers will probably be more happy about the Merge Request that should now look more pleasant than before.

Make it reusable

Finally we would like to have the prompt always ready. That is why you can create a .github/copilot/prompts folder with a prompt file codeReviewAssessment.prompt.md. The file is started with the following block and contains the prompt below that:

---
name: codeReviewAssessment
description: Evaluate code quality across seven dimensions with consistent scoring and actionable feedback.
argument-hint: The selected code or codebase to review
---

This enables us to access the prompt by typing /codeReviewAssessment.

The post Gamify Software Engineering by letting AI rate your changes appeared first on Ronnie Schaniel.

The advent of General-Purpose Transformational (GPT) models, followed by coding assistants like GitHub Copilot, has revolutionized the software engineering landscape. However, many developers struggle to go beyond basic use cases. A bit of creativity is needed. To unleash the full potential of AI in your daily work, I’ve compiled a comprehensive list of 50 AI mini use cases that you can apply using general GPT or a coding assistant.

Before diving into these use cases, please keep two essential points in mind: first, ensure you have the necessary permissions to input information into the chat bot from a security perspective; and second, always review the output generated by the AI tool.

GPT Use Cases

This is for use cases outside of your integrated development environment (IDE). It contains simple things that you probably did manually in the past. The order is random.

1. Translate: use it to understand any text.
2. Test data generation: based on classes or examples.
3. Dashboard explanation: export a monitoring or analytics dashboard source. Paste it into the chat and ask it to describe the dashboard in natural language, including where the data comes from and how numbers are calculated.
4. Query parameter generation: paste a JSON and ask it for transforming into a query parameter string.
5. Test scenarios: generate test scenarios based on a feature description.
6. Drafting documents: draft documentation and manuals.
7. SQL queries: write or optimise SQL queries.
8. Write queries for your monitoring system, e.g. Splunk or Grafana.
9. Summarise feedback: textual user feedback and suggest improvement ideas.
10. Release notes: Generate release notes based on GIT commits.
11. Scripts: Write simple scripts.
12. Meeting notes: Summarise meeting notes and create a task/action list.
13. Data validation rules: Given a dataset schema, generate a set of data validation rules (e.g., 3-5 rules) to ensure the data meets certain criteria and is consistent with the schema.
14. Draft presentations: create a first version or an outline for a presentation.
15. Review architectures: describe how you plan to implement a feature on the architectural level to get feedback, descriptions or diagrams.
16. Generate checklists: create checklists for deployments, releases or other critical tasks.
17. Evaluate skills: explain your current skills and ask for an evaluation and list of gaps to guide your next learning steps.
18. Summarise technical articles: to learn about topics.
19. Quizzes: generate a quiz based on a technical article or documentation.
20. Interview preparation: ask for potential questions based on a job description.
21. Create survey or forms: generate questions and answer options. Also use it later to summarise replies.
22. Glossary: generate a list of terms that are not generally understandable.
23. Generate the agenda for a meeting: draft the meeting invitation.
24. Explain a dataset: take a dataset and explain the latest trends and highlights.
25. Vulnerability analysis: describe a setup or solution and ask for a threat modelling and potential vulnerabilities.

These were the general chat use cases. Some of them could also be done in the IDE directly of course. Anyway, in the next chapter you find use cases that are more typical to be directly executed by your AI coding assistant.

Coding Assistant Use Cases

The use cases below are all about using CoPilot and co. in a way to help you working.

1. User Story to code: copy a complete User Story description into the chat, use agent mode, and ask it to generate the code for the story.
2. Review code changes: at the end of implementing a change, ask the coding assistant to review your changes for security, clarity, potential bugs or other issues.
3. Visualise logic: open a class or module that contains lots of logic. Ask to generate a mermaid diagram definition (text based diagram).
4. Regex: ask to generate a regex based on a textual description or examples.
5. Generate specific values: generate UUIDs or other random data that you occasionally need.
6. Tests: ask to generate unit tests for a certain class or module.
7. TDD: generate the implementation based on tests.
8. Test coverage: ask which cases are not tested yet.
9. Error explanation: paste a stack trace of an error and ask for a fix.
10. Data transformation: transform data from one representation to another, e.g. JSON to TypeScript.
11. Document code: ask to generate a documentation based on code.
12. 3rd party library: get information about a third party library that you want to use.
13. Review accessibility: review html code for accessibility issues or make it compliant.
14. Technology migration: switch from one implementation version to another, e.g. Java 20 to 21, RestTemplate to WebClient.
15. Improve performance: ask about performance issues in the code and ways to improve.
16. Understand: explain code.
17. Port between languages: transform code from one language into another.
18. Generate commit messages: generate git commit messages based on the changes.
19. Overview: ask for a general overview of a project’s source code if it’s new to you to understand conventions, patterns and libraries used.
20. Refactoring to patterns: if you see a code smell and the possibility to refactor to a design pattern, use the coding assistant.
21. Generate performance tests: create performance tests, e.g. JMeter scripts, based on the APIs.
22. Optimise internal exceptions and error: draft text for internal errors and exception for your fellow engineers and your future self.
23. Generate API requests: create API requests in curl, postman, bruno or any other API tool.
24. README: generate READMEs based on the code.
25. Improvement and refactoring: ask for potential changes to your code.

These use cases are designed to help you unlock the full potential of GPT and coding assistants in your daily workflow. Whether you’re a seasoned software engineer or just starting out, these mini use cases will inspire you to find innovative solutions to common challenges.

The post 50 AI Mini Use Cases for Software Engineers: Boost Your Productivity with GPT and Coding Assistants appeared first on Ronnie Schaniel.

The release of ChatGPT in November 2022 sparked excitement about the possibilities of Generative AI. In just five days, it gained over a million users. As businesses began to explore how to leverage this technology, they quickly realized that using AI internally was crucial.

Fast-forward three years, and many companies have jumped on the Generative AI bandwagon, building their own GPT or LLM-based solutions. However, what I often see is that creators simply add an LLM with Retrieval Augmented Generation (RAG) to their data, hoping for the best. But does this approach truly deliver value? I have some doubts.

This sentiment is also confirmed by various studies, MITs “State of AI in Business 2025” reports that “Despite $30–40 billion in enterprise investment into GenA (…) 95% of organizations are getting zero return”. In this post we speak about software companies or companies that have at least their own IT department and are planning to build their own AI solutions.

The naive approach for Generative AI projects

Cost pressure is high in many tech companies. And so is the hype around AI. An easy strategy is therefore to just invest in AI. An LLMs capability can look impressive, but the main issues is that it doesn’t have access to company data out of the box. Retrieval augmented generation can help there and extend the LLMs context by data in files or on wiki pages. It’s also not super difficult to implement. So, many just start to RAGify everything they have. This is nice to have and the use cases around it are many, but:

• The data that is retrieved is often in bad quality and can be outdated.
• As the use cases are endless, end-users struggle to understand how to exactly use the new possibilities. I’ve got that wiki page no in a chat bot, nice, but what now? What should I do with it?
• Even if there is a chat bot available somewhere backed by RAG, it’s usually a standalone app. This requires users to switch context and leads to a fragmented tool landscape.
• The return on investment (ROI) of such solutions is not measured or not understood.
• Projects look fancy in the beginning because you get impressive answers very soon. But optimising the solution to reach production state is hard. Project teams often miss to have an evaluation pipeline and defined KPIs.
• Big use cases are tackled early on and take months to implement, delaying the benefits and in the worst case leading to a solution that is not usable at all.
• The core of the AI solution might be built within a few days. But integrating it into the existing system landscape, considering security, compliance, people training, data maintenance, and other factors can take months.

Still the pressure remain, we have to do something with AI! And in the next section I would like to highlight a few points that help you to make your project a success.

How to tackle Generative AI projects

I’m convinced that AI has benefits in it for most businesses. How do we make it a success? First of all, slow down! Don’t follow the latest trends daily, but have a robust AI strategy that is dynamic enough to adapt, but doesn’t lead to jumping always onto the latest technological advances in the field of AI. Because there’s just too much going on.

And then more importantly. Don’t take Generative AI and RAG as a technology and ask yourself what it can solve. That’s the wrong direction! Ask what problems do you have in your company and design a solution for it. And then ask what parts of the solution can be covered or improved by generative AI.

Also don’t forget how software was built in the last years. Don’t forget agile! Put the user, feedback and short iterations into the center.

Consider the following when you’re planning to build an AI solution in your organisation:

• Start with problems, not technology: Design a solution for specific company challenges, and then ask how AI can help.
• Use agile principles as in any other software product you have built in the last years.
• Don’t build standalone solutions, but make sure AI is integrated into the existing workflows.
• Educate and train the user. This starts even by making sure the AI strategy is understood by everyone and nobody has to fear for their jobs.
• As AI is non-deterministic, define KPIs that you need to achieve to make your solution useful. Iterate and improve.
• Define the ROI you want to see when you plan the solution. What is your business case? What can your colleagues do with the solution you’re building?
• Consider data management, security, compliance, and other non-functional requirements early!

Finally, you might put a generative AI solution into production that makes some work faster or better. Ask yourself what the time freed up by that, can be used for. If you make a process faster only to run into waiting times or have colleagues who can’t use their newly won time, you’ve failed too.

The post Make your Gen AI Project a Success appeared first on Ronnie Schaniel.