Teaching AI How to Work on Deriva

Context, DDD, SOLID and the problem of making AI understand an existing codebase.

How architecture became a way to control AI-assisted development.

---

🇺🇸 English

The hard part was never getting the AI to write code.
The hard part was getting it to understand where that code belongs.

🎮 The problem I didn't expect

When I started developing Deriva with AI, I expected the biggest challenge to be technical.

Maybe getting the ship movement right. Maybe making the weapons feel good. Maybe dealing with physics, aiming, combat or all the little systems that make a game actually behave like a game.

But something else became a problem much earlier:
getting the AI to understand the project itself.

An AI can be incredibly good at solving a problem presented in isolation. Give it a requirement, show it some code and ask for a feature — and very often you get something that works.

The problem starts when that feature has to live inside a growing system.

At that point, "make it work" is no longer enough.

The real questions become:

• Where should this logic live?
• Which existing abstraction should be used?
• Which interface or contract does this behavior belong to?
• What should actually be changed?

Without enough context, the AI tends to choose the fastest path to a working answer. And in a small prototype, that's often perfectly fine.

In a real project, however, that shortcut can become technical debt almost immediately.

💥 When "working code" becomes a problem

During the development of Deriva, I repeatedly found myself experimenting with the same systems.

Ship movement.
Navigation.
Aiming.
Weapons.
Combat behavior.
Energy systems.
Different rules and variations for how all of these things should behave.

I wanted to be able to change a mechanic, test it, decide that it wasn't quite right, change it again, and keep experimenting.

But imagine doing that while every new request potentially causes the AI to modify unrelated files, duplicate existing logic or attach new behavior to whatever class happens to be convenient.

Eventually, even a simple change becomes dangerous.

You fix one thing and something three systems away suddenly stops behaving correctly.

That's when I realized that I didn't just need the AI to understand what I wanted to build.

I needed it to understand how Deriva is built.

🧠 So I taught the AI the architecture

My solution was to make the architecture itself part of the AI's context.

Instead of treating the project as a huge collection of source files, I started organizing the knowledge about the project into explicit documentation, references and specialized instructions.

I developed specialized skills and sub-agents focused on DDD and SOLID principles.

Each relevant domain and project area has its own context. The goal is that, before touching the code, the agent can determine:

• what already exists;
• what the responsibilities of that area are;
• which interfaces and contracts are involved;
• which files are responsible for the behavior;
• and where a new implementation should actually go.

This may sound like a small change, but it completely changes the way I interact with the AI.

Instead of saying:

"Go through the project and figure out how to implement this."

I can provide an environment in which the project itself already explains how it should be navigated.

The architecture becomes a kind of map.

🗺️ Turning the codebase into a map

One of the ideas I wanted to explore was reducing the amount of unnecessary exploration the AI had to perform.

An AI doesn't necessarily need to inspect hundreds of files to modify one behavior. It needs to know which path to follow to reach the relevant part of the system.

That's where the documentation, references, domains and specialized agents became useful.

Instead of thinking about the project as:

hundreds of files
        ↓
search everything
        ↓
guess where the logic belongs
        ↓
make a change

I wanted the process to look more like:

feature request
        ↓
identify the domain
        ↓
follow the domain context
        ↓
identify the responsible contract
        ↓
modify the appropriate implementation

The goal wasn't to make the AI "smarter".

The goal was to give it better information before it starts making decisions.

🏗️ DDD and SOLID became practical tools

I wasn't applying DDD and SOLID simply because they are popular software engineering concepts.

In this project, they also became a way of giving the AI boundaries.

If a system has clear responsibilities, explicit contracts and well-defined domains, there is less ambiguity about where a new behavior should be placed.

That distinction became especially valuable when working with AI.

A loosely organized codebase gives the AI many possible places to put new logic.

A well-defined architecture narrows those possibilities.

In other words:

architecture doesn't just organize the code. It also constrains the possible ways the AI can change the code.

🔧 The result in practice

This allowed me to separate features into more independent domains and services.

When I needed to change a rule or replace a behavior, the agent could usually work inside a relatively small portion of the project instead of spreading the change across unrelated areas.

When introducing a new feature, the intention became to extend existing interfaces and contracts instead of modifying whatever code happened to be nearby.

And this became particularly useful for gameplay.

Game development involves a lot of experimentation.

I might change the navigation model today, rethink aiming tomorrow, adjust weapon behavior a few hours later, and then completely change how a combat mechanic works.

That's normal during development.

The important part is being able to experiment without turning every experiment into a chain reaction throughout the project.

Good architecture gave me room to experiment.

🔄 But there is still a problem

This approach doesn't magically solve everything.

Having skills, sub-agents, documentation, DDD and SOLID principles does not mean the AI will always make the correct architectural decision.

I still need to tell it which tools to use.
I still need to reinforce the project's rules.
And I still need to make sure that a new request is being handled inside the boundaries that were established.

In practice, the challenge returns with almost every new prompt.

The better the structure becomes, the easier it is to guide the AI — but guidance is still necessary.

💡 The biggest lesson

This was probably one of the most important things I learned while building Deriva.

Developing with AI isn't simply about asking:

"Can you build this feature?"

It's about designing an environment where the AI can answer that question without destroying the structure that already exists.

That changes the role of architecture.

Architecture is no longer just a way for humans to understand a software project.

In an AI-assisted workflow, it can also become a way of communicating constraints, responsibilities and intent to the AI.

---

🧩 My takeaway

Developing with AI is not just about knowing how to ask for code. It's about knowing how to control the context in which the AI works.

The better the AI understands the structure of the project, the less it has to guess.

And the less it has to guess, the more freedom I have to focus on what actually matters: building the game.

That was one of the most interesting lessons I took from developing Deriva.

---

🇧🇷 Português

A parte difícil nunca foi fazer a IA escrever código.
A parte difícil foi fazer a IA entender onde aquele código deveria estar.

🎮 O problema que eu não esperava

Quando comecei a desenvolver o Deriva com IA, eu esperava que o maior desafio fosse técnico.

Talvez acertar a movimentação das naves. Talvez fazer as armas terem uma sensação boa durante o combate. Talvez lidar com física, mira, combate ou todos aqueles pequenos sistemas que fazem um jogo realmente se comportar como um jogo.

Mas outro problema apareceu muito antes:
fazer a IA entender o próprio projeto.

Uma IA pode ser extremamente boa em resolver um problema apresentado de forma isolada. Você fornece um requisito, mostra algum código e pede uma funcionalidade — e frequentemente recebe algo que funciona.

O problema começa quando essa funcionalidade precisa existir dentro de um sistema que está crescendo.

Nesse momento, "fazer funcionar" deixa de ser suficiente.

As perguntas realmente importantes passam a ser:

• Onde essa lógica deveria ficar?
• Qual abstração existente deveria ser utilizada?
• A qual interface ou contrato esse comportamento pertence?
• O que realmente precisa ser alterado?

Sem contexto suficiente, a IA tende a escolher o caminho mais rápido para chegar a uma resposta funcional.

Em um protótipo pequeno, isso muitas vezes é perfeitamente aceitável.

Em um projeto real, porém, esse atalho pode rapidamente virar dívida técnica.

💥 Quando "código funcionando" vira um problema

Durante o desenvolvimento do Deriva, eu estava constantemente experimentando com os mesmos sistemas.

Movimentação das naves.
Navegação.
Mira.
Armas.
Comportamento de combate.
Sistemas de energia.
Diferentes regras e variações para o funcionamento de tudo isso.

Eu queria poder alterar uma mecânica, testar, perceber que não estava boa, alterá-la novamente e continuar experimentando.

Mas imagine fazer isso enquanto cada nova solicitação pode fazer a IA modificar arquivos que não têm relação com o problema, duplicar lógica ou simplesmente adicionar um novo comportamento à classe que parecia mais conveniente.

Em algum momento, até uma alteração simples começa a se tornar arriscada.

Você corrige uma coisa e, de repente, algo que estava funcionando em outro sistema começa a apresentar problemas.

Foi então que percebi que eu não precisava apenas que a IA entendesse o que eu queria construir.

Eu precisava que ela entendesse como o Deriva foi construído.

🧠 Então eu ensinei a arquitetura para a IA

Minha solução foi transformar a própria arquitetura em parte do contexto da IA.

Em vez de tratar o projeto como uma enorme coleção de arquivos, comecei a organizar o conhecimento sobre o projeto em documentação explícita, referências e instruções especializadas.

Desenvolvi skills e sub-agentes especializados em DDD e princípios SOLID.

Cada domínio e área relevante do projeto possui seu próprio contexto. A ideia é que, antes de alterar o código, o agente consiga determinar:

• o que já existe;
• quais são as responsabilidades daquela área;
• quais interfaces e contratos estão envolvidos;
• quais arquivos são responsáveis pelo comportamento;
• e onde uma nova implementação realmente deveria ficar.

Isso pode parecer uma pequena mudança, mas muda completamente a forma como interajo com a IA.

Em vez de dizer:

"Percorra o projeto e descubra como implementar isso."

Posso fornecer um ambiente no qual o próprio projeto já explica como deve ser navegado.

A arquitetura passa a funcionar como um tipo de mapa.

🗺️ Transformando o código em um mapa

Uma das ideias que quis explorar foi reduzir a quantidade de exploração desnecessária que a IA precisava fazer.

Uma IA não necessariamente precisa analisar centenas de arquivos para alterar um único comportamento. Ela precisa saber qual caminho seguir para chegar à parte relevante do sistema.

É aí que entram a documentação, as referências, os domínios e os agentes especializados.

Em vez de pensar no projeto desta maneira:

centenas de arquivos
        ↓
procurar em tudo
        ↓
tentar descobrir onde a lógica pertence
        ↓
fazer a alteração

Eu queria que o processo se parecesse mais com isto:

solicitação de funcionalidade
        ↓
identificar o domínio
        ↓
seguir o contexto daquele domínio
        ↓
identificar o contrato responsável
        ↓
alterar a implementação apropriada

O objetivo não era tornar a IA "mais inteligente".

O objetivo era fornecer informação melhor antes que ela começasse a tomar decisões.

🏗️ DDD e SOLID passaram a ter uma função prática

Eu não estava aplicando DDD e SOLID apenas porque são conceitos conhecidos de engenharia de software.

Dentro desse projeto, eles também passaram a funcionar como uma forma de estabelecer limites para a IA.

Quando um sistema possui responsabilidades claras, contratos explícitos e domínios bem definidos, existe menos ambiguidade sobre onde um novo comportamento deveria ser colocado.

Essa diferença se tornou especialmente importante trabalhando com IA.

Um código pouco organizado oferece à IA muitos lugares possíveis para colocar uma nova lógica.

Uma arquitetura bem definida reduz essas possibilidades.

Em outras palavras:

a arquitetura não apenas organiza o código. Ela também limita as formas pelas quais a IA pode modificar esse código.

🔧 O resultado na prática

Isso me permitiu separar funcionalidades em domínios e serviços mais independentes.

Quando precisava alterar uma regra ou substituir um comportamento, o agente normalmente conseguia trabalhar em uma parte relativamente pequena do projeto, sem espalhar a mudança por áreas que não tinham relação com ela.

Ao introduzir uma nova funcionalidade, a intenção passou a ser estender interfaces e contratos existentes em vez de modificar qualquer código que estivesse por perto.

E isso se tornou especialmente útil durante o desenvolvimento da jogabilidade.

Desenvolvimento de jogos envolve muita experimentação.

Posso alterar o modelo de navegação hoje, repensar a mira amanhã, ajustar o comportamento das armas algumas horas depois e, então, mudar completamente a forma como uma mecânica de combate funciona.

Isso é normal durante o desenvolvimento.

O importante é conseguir experimentar sem transformar cada experimento em uma reação em cadeia pelo restante do projeto.

Uma boa arquitetura me deu espaço para experimentar.

🔄 Mas ainda existe um problema

Essa abordagem não resolve tudo magicamente.

Ter skills, sub-agentes, documentação, DDD e princípios SOLID não significa que a IA sempre tomará a decisão arquitetural correta.

Eu ainda preciso indicar quais ferramentas utilizar.
Ainda preciso reforçar as regras do projeto.
E ainda preciso verificar se uma nova solicitação está sendo tratada dentro dos limites estabelecidos.

Na prática, o desafio retorna praticamente a cada novo prompt.

Quanto melhor a estrutura se torna, mais fácil fica orientar a IA — mas a orientação ainda é necessária.

💡 A maior lição

Essa provavelmente foi uma das coisas mais importantes que aprendi durante o desenvolvimento do Deriva.

Desenvolver com IA não é simplesmente perguntar:

"Você pode construir essa funcionalidade?"

É criar um ambiente no qual a IA possa responder a essa pergunta sem destruir a estrutura que já existe.

Isso muda o papel da arquitetura.

Arquitetura não é mais apenas uma forma de ajudar seres humanos a entender um projeto de software.

Em um fluxo de desenvolvimento assistido por IA, ela também pode se tornar uma forma de comunicar restrições, responsabilidades e intenção para a própria IA.

---

🧩 Minha conclusão

Desenvolver com IA não é apenas saber pedir código. É saber controlar o contexto no qual a IA trabalha.

Quanto melhor a IA entende a estrutura do projeto, menos ela precisa adivinhar.

E quanto menos ela precisa adivinhar, mais liberdade eu tenho para me concentrar no que realmente importa: construir o jogo.

Essa foi uma das lições mais interessantes que tirei do desenvolvimento do Deriva.

---

Deriva — developed with AI, guided by architecture.