> ## Content Index
> Fetch the complete content index at: https://madewithlove.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Three Codexes walk into a codebase: The fellowship of the god class
- URL: https://madewithlove.com/blog/three-codexes-walk-into-a-codebase-the-fellowship-of-the-god-class/
- Published: 2026-08-31T08:34:58.000Z
- Updated: 2026-08-31T08:34:58.000Z
- Description: Handing an AI your engineering conventions cleans up the code without fixing the architecture. A 5,000-line god class shrank to 500 lines across tidy domain files, and an independent reviewing agent still returned FAIL: authority never left the central object.
- Author: Brenden Cambier
- Tags: AI, AI Agents, Architecture, Claude, Refactoring, Technical debt

I did not plan to write a third one.

Nobody plans the third instalment. The third instalment just happens because the first two made enough money to create contractual obligations.

First, [three Cursors walked into a codebase](https://madewithlove.com/blog/three-cursors-walk-into-a-codebase/) and left it 80 per cent finished. Then [three Claudes walked into a codebase](https://madewithlove.com/blog/three-claudes-walk-into-a-codebase/) and accidentally promoted me to manager.

So naturally, three Codexes had to walk into one too.

I'm already dreading the unexpected, unneeded Matrix Resurrections of this instalment.

![Three Codexes walk into a codebase](https://madewithlove.com/blog/content/images/2026/08/image-1.png)

There was just one problem.

The third instalment became *Return of the King*.

Not because it was an epic conclusion to a beloved trilogy. Because it was three and a half hours long and apparently incapable of ending.

I could have published it like that. Or I could do what any responsible writer does after accidentally creating something too large to maintain.

Split it into smaller components and pretend that was the architecture all along.

So the third article in a trilogy became another trilogy.

Trilogyception.

This is part one.

And before three Codexes can walk into the codebase, we need to talk about the Claude that was already inside it.

Because I had made a mistake.

A fairly familiar one, actually.

**I had confused having good engineering principles with having an architecture.**

## It was supposed to send a notification

Like most technical disasters, this one began with the famous last words:

> “It should be a small application.”

I have solar panels, an electric car and a local IoT system measuring the energy consumption of my house. What I do not have is access to the EV charging pole.

Corporate policies of my wife's employer.

You'd almost think she works at Microsoft.

This felt like an important limitation.

The initial idea was therefore modest: read the local energy data, detect when the car was charging at an unfortunate moment, and send me a push notification.

Not revolutionary. Not autonomous. Barely even intelligent.

Essentially, I wanted my house to send me a polite message saying:

> “You are currently turning expensive electricity into slightly more convenient transportation.”

There was one additional complication.

Belgium has a capacity tariff because apparently buying electricity was not sufficiently exciting on its own. Part of the bill is influenced by my highest average consumption during ONE fifteen-minute window. Once I establish a high monthly peak, it stays with me for the rest of the month, quietly judging my past decisions like my mother-in-law.

The application therefore had to watch each fifteen-minute window and help keep consumption below the current monthly peak.

Still manageable.

Read the IoT data. Calculate the 15-minute window. Send a notification.

A small application.

Then I asked Claude.

Just as the small application was approaching the unusual software milestone known as finished, Claude informed me that the car had an API.

This changed everything.

I could not control the charging pole. But I could control the car.

![Samwise Gamgee: I can't carry it for you, but I can carry you](https://media.tenor.com/5Jhtk6qqAVMAAAAe/samwise-gamgee-i-cant-carry-it-for-you-but-i-can-carry-you.png)

Pause charging. Resume charging. Coordinate charging with solar production. Protect the monthly peak.

What began as a notification script had been given power beyond what its original requirements considered wise.

And just like that, scope creep entered the room, saw an unattended chair and began writing requirements.

The application would no longer merely tell me I was making a bad decision. It would prevent me from making one.

Which is how my notification script became responsible for controlling several kilowatts of electricity.

Meet Wattson.

![Wattson, the logo for the energy management application](https://madewithlove.com/blog/content/images/2026/08/image-2.png)

This is an important milestone in every software project: the moment a simple alert becomes an autonomous control system because someone discovered an API.

Usually that someone is a product manager.

This time it was Claude.

## Architecture is for large applications

I have a second brain containing my coding conventions, architectural principles and the accumulated opinions of someone who has reviewed enough codebases to develop strong feelings about dependency injection.

It describes how I structure domain logic. Where orchestration belongs. How infrastructure should interact with the domain. What state is allowed to live where.

The sort of material produced by years of building software, auditing companies and staring at God classes that contain enough business logic to qualify as independent economies.

I did not give any of this to Claude.

It was going to be a small application.

You may recognise this as the exact sentence normally spoken shortly before an application stops being small.

Claude got to work.

It added the IoT integration. The car API. The solar calculations. The forecasting. The peak-protection algorithm. The charging decisions. The polling. The orchestration. The state.

Everything went into `poller.py`.

Five thousand lines.

One file to fetch them all. One file to process them. One file to make every decision. And in the darkness tightly couple them.

![Sauron, the Dark Lord, from The Lord of the Rings](https://i.redd.it/7lkp7sxb7bqb1.jpg)

A god class.

This thing had omniscience, absolute power and undocumented side effects.

And that was when I experienced a rare moment of professional self-awareness.

I have been here before.

I had audited this system.

I had sat across from engineering teams and asked, in my calmest consultant voice, how one component came to own orchestration, infrastructure, algorithms and domain state. I had written concerns about unclear separation of responsibilities. I had explained how concentrated logic increases maintenance risk and makes the system difficult to test or change.

Now I was looking at the same architecture in my own repository.

Built under my supervision.

**Because I had decided architectural principles were unnecessary for a small application that autonomously controls several kilowatts of electricity.**

Now I am become customer, creator of [technical debt](https://madewithlove.com/blog/technical-debt-lost-its-excuse/).

Oppenheimer had the bomb. I had `poller.py`.

History will decide which one caused more uncomfortable architecture meetings.

The solution seemed obvious.

Claude had built the application without my engineering conventions, so I would give it my engineering conventions.

They were good conventions.

They had survived years of production software, technical audits and arguments about where business logic belongs. They described boundaries, domain ownership, state, infrastructure and most of the other things I normally complain about when someone else gets them wrong.

And Claude was a very capable model.

Surely those two things combined would be enough to discover a better architecture.

This assumption will become important shortly.

## The god class gets a promotion

I handed Claude [my architectural conventions](https://madewithlove.com/blog/onboard-the-ai-like-youd-onboard-a-developer/) and asked it to fix everything.

The fellowship was assembled.

“You have my domain models.”

“And my separation of concerns.”

![The Fellowship of the Ring, assembled](https://blogin.madewithlove.com/uploaded/50068d2527bc62e18817c/fellowship-of-the-ring-fellowship.png?gt=4d0098677826dc8e580ed239cc660ef4d4c9d6ef)

The axe was apparently a 4,000-line Markdown file containing my opinions about software engineering.

Off they went to destroy the god class.

Agents are wonderfully enthusiastic creatures. They never sigh. They never complain. And, perhaps most remarkably, they never ask who approved the original pull request.

They simply start extracting things.

Domain classes appeared. Responsibilities moved into separate files. Functions became shorter. Boundaries appeared where previously there had mostly been indentation.

`poller.py` got smaller.

The tests stayed green.

And every time Claude finished, I did what I had learned to do in the previous article. I reviewed the result, pointed out what was still wrong and sent my extremely fast, extremely patient junior back into the codebase.

Again.

And again.

And again.

This went on for roughly ten iterations.

And the annoying thing is: it worked.

The code genuinely got better.

Five-thousand-line files are surprisingly easy to improve when your starting architectural pattern is “everything, everywhere, all at once”.

Methods moved closer to the domain they belonged to. Infrastructure became easier to distinguish from business logic. Functions that previously required scrolling, coffee and a vague recollection of where you started became small enough to fit on a screen.

The repository became easier to navigate.

The code became easier to read.

Eventually, `poller.py` fell from approximately 5,000 lines to 500.

Claude proudly presented its homework.

Clean architecture. A successful refactor. Order had been restored.

The god class was destroyed.

And looking at the repository, I was inclined to agree.

There were domain objects. There were abstractions. There were boundaries.

This was the kind of repository tree you could screenshot, put into an architecture diagram and confidently show to someone before they had time to open any of the files.

Naturally, I asked another agent to review it.

Not because I distrusted Claude.

Because I could no longer understand the code.

![Meme: reviewing code you no longer understand](https://i.imgflip.com/ayz225.jpg)

There was too much of it, generated too quickly across too many files. Manually tracing every decision would have required the kind of uninterrupted afternoon that exists mainly in productivity books and the calendars of people without Slack.

So I started an [independent reviewing agent](https://madewithlove.com/blog/ai-code-review-tools/).

The reviewer returned FAIL with a P1 finding:

> Poller still owns the architecture. Responsibilities have been extracted into smaller components, but they remain tightly intertwined with Poller and much of the behaviour is still delegated through it. Orchestration, shared state and cross-domain decision-making remain concentrated in the central object. The code is cleaner, but Poller is still effectively a god class.

![Gandalf: You shall not pass](https://gifrific.com/wp-content/uploads/2017/11/you-shall-not-pass-gandalf-lotr.gif)

Claude had not removed the god class.

**It had given the god class departments.**

The logic had been distributed across files, but authority remained concentrated in the same place. The new classes looked independent in the repository tree. At runtime, they still reported directly to `Poller`, passed around its mutable state and called its private methods.

The code quality had improved enormously.

The architecture had barely moved.

This was not clean architecture.

This was a god facade.

The deity had stopped doing its own administration.

Which was considerably more annoying than Claude simply being bad at refactoring.

It wasn't.

The code was better. My conventions had done exactly what they were supposed to do.

They just hadn't answered the question I apparently expected them to answer.

**What should this particular system actually look like?**

And if that answer wasn't hiding in my coding conventions or somewhere inside `poller.py`, there was one increasingly uncomfortable question left.

**Where was the architecture supposed to come from?**

.

.

.

.

*Codex will return in...*

***Three Codexes Walk Into a Codebase: The Two Agents***