QWAN - Quality Without a Name

Give your smurf a bad name

Sat, 07 Feb 2026 00:00:00 +0000

Choosing good names is one of the hardest parts of our job as software developers. It’s also a crucial part: names have a big impact on how well others (and our future selves!) will be able to understand the code and change it.

“Choose a bad name to trigger better naming” is a heuristic we often use when programming, but it also works for prose, the ordinary language people use in speaking or writing.

Heuristic: choose a bad name to trigger better naming

In earlier times, Willem would choose swear words for names. It lightens the mood, when working alone, but is not conducive for group work. Calling it “smurf” is another option, making it obvious it needs a better name.

Any name that is obviously off will do, urging the reader to replace it with something meaningful. Calling an object a …Manager would be a bad name for us, but many developers are used to Manager classes in their code. …Smurf works better.

Using a bad name can also help to detach ourselves from vague, misleading initial names. If our domain talks about locations, we are tempted to start out with a “Location” domain object. This becomes an attractor for anything location related: a location can be an organizational unit with employees joining and leaving over time, or a place where specific services are offered, or a unit of financial processing. While these different faces of “Location” overlap, they are not the same thing.

Once we start calling something a “Location”, it becomes hard to keep our minds open for alternative perspectives. Calling it a “Smurf” can help.

Managing coupling through Hexagonal Architecture

Tue, 03 Feb 2026 00:00:00 +0000

We wrote in our previous post on coupling: without coupling there is no working software, but how do we keep coupling manageable? In this post, we will look at Hexagonal Architecture from a coupling perspective. Hexagonal Architecture is about decoupling domain logic from frameworks and the outside world - but what does decoupling actually mean?

Hexagonal Architecture recap

Hexagonal Architecture, also known as Ports & Adapters, is a software architecture pattern that provides guidance in structuring a component or application and managing dependencies inside the component.

It applies the Dependency Inversion Principle at the component level: it puts the domain logic at the center, without any dependencies on databases, web, APIs. A set of interactions with the outside world with the same intent is represented by a Port. The outside world interacts with the domain logic via Adapters that map the outside world to the domain model and the other way around.

Ports can be driving (incoming) or driven (outgoing). For driven ports, adapters implement interfaces that are part of the domain model, visualized by the green thick lines in the picture below. Libraries and frameworks reside on the outside.

See our earlier posts to learn more (or book a course 😁)

Hexagonal Architecture in practice

We have applied Hexagonal Architecture in many projects. It has also been embraced by the Domain Driven Design community as the default way of structuring services.

In practice, it results in domain code that is easier to understand, because it is not cluttered with technical details like database or API mappings. We’ve decoupled different concerns in the code.

We have noticed something else as well. Sometimes we need to add a new feature and we find ourselves making changes across the component, touching domain logic, the database schema, the database adapter, the API and the API adapter. If this happens, it does not really feel decoupled. It actually looks more like the Shotgun Surgery code smell - having to make many small changes across the code base - or does it?

The coupling & cohesion heuristic we tend to follow is:

If things need to change together, put them close to each other.

So should we put parts of the API, the database mapping and the domain logic closely together because they sometimes change together? It depends…

Different sources of change

It turns out there are multiple sources of change, each having a different impact and each having its own rate of change:

APIs and database schemas tend to be more stable - especially if other services or external parties depend on our APIs or if substantial amounts of data need to be migrated when the schema changes.
Frameworks and libraries evolve at their own pace, usually at a slower pace. Once in a while we need to deal with impactful major version upgrades.
Domain logic has its own pace of changes. We want to be able to refactor and evolve the domain model as we gain new insights.

Applying Hexagonal Architecture means isolating the API, the database and the domain. The trade-off we make is accepting that some (feature) changes will cross the different parts. Hexagonal Architecture optimizes for parts that change at different rates: we are organizing for shearing layers of change - allowing different rates of change with limited friction.

Shearing Layers of change come from (building) architecture and provides a useful perspective on organizing code based on the stability or volatility of its parts.

The concept was coined by the architect Frank Duffy, and it was elaborated in the wonderful book How Buildings Learn by Stewart Brand.

Buildings have different layers that change at different rates. The building site is quite stable and often survives a building, the structure is expensive to change so it only changes once in a while. Services like heating wear out, and change every 7-15 years, while stuff (chairs, tables, etc) moves around frequently.

Layers should allow for other layers to change at their own rate.

Hexagonal Architecture optimizes for parts that have different rates of change and it allows the parts to evolve with limited friction

Making trade-offs

Deciding what to put close together and what to separate for facilitating different rates of change involves making trade-offs. Optimizing for each part to evolve at its own pace comes at the cost of new features needing a series of (small) changes.

We are usually willing to pay this price, because it enables us to be much more in control of changes:

Framework and library updates affect a much smaller part of our system, reducing risks.
We can more freely refactor domain logic to reflect our current understanding, without continuously needing to migrate data.
If a feature requires changes across the component, we can do these changes in baby steps, with working software at any point in time. If we think a bit about the ordering of the baby steps, we can even deploy each change to production without impact.

Working in baby steps while keeping the code working at all time is key here. Mechanisms like dependency inversion, domain-oriented interfaces, the ability to test different concerns independently using domain logic tests, adapter integration tests, and component end-to-end tests help a lot.

Hexagonal Architecture and (de)coupling

Hexagonal Architecture separates concerns that have different rates of change. APIs, adapters, databases, domain logic are still coupled, but they do not need to change all at the same time. The coupling is made explicit through interfaces and adapters.

The pattern comes with trade-offs: being in control of changes and the ability to do changes in baby steps come at the cost of some changes being more work.

Hexagonal Architecture was introduced over 30 years ago. There is a more recent insight that rather than creating a single big hexagon for a component or application, we’d rather split the component into smaller, more focused hexagons, to reduce complexity and impact of changes, but this is worth a post of its own.

References

We have written a series of posts about Hexagonal Architecture
How Buildings Learn - What happens after they’re built by Stewart Brand; there is also a BBC series of 6 episodes
Paul Dyson wrote three posts about Shearing Layers in software delivery
Mark Dalgarno explores Shearing Layers in Shearing layers in Organisational Transformation — half an idea
Chad Fowler is writing a series of posts on regenerative software, using the idea of Shearing Layers (or pace layering as it is called in his posts)

How does the human stay in the loop, while developing on their phone?

Mon, 02 Feb 2026 00:00:00 +0000

Working with LLMs to create prototype webapps from my phone can be very satisfying. There are limitations, though. Having only a tiny terminal window with a coding agent can feel like painting my living room through the letterbox. Code scrolls by quickly, and I look at a few lines at a time, which makes me lose sight of the whole. So after some prototyping, I have to find time and space to sit with a microprint, to see the forest and the trees.

I decided to port the microprint library made with Stephan Eggermont to the web framework that we use - Phoenix LiveView. Now the microprints live inside the web application, as we are building it. This helps us make better decisions about where we need to refactor, where we need more tests, where we need to learn more etc. This way we can keep an eye on the code as it develops. Iterative work and short feedback cycles remain valuable, if not more so, with AI Augmented development.

“What am I seeing here?”

This is a microprint, a shrunken view on a source file, living right in a web application we are working on. Mobile first. It shows the ten most recently changed files, and I can tap on a microprint to see details. This not only enables me to stay close to the code, it draws me in.

I can contract the source code view, to see several at once on my phone. This gives me an overview of what is going on. In this case stylesheet changes and I was working on the microprint itself.

Stephan and I ain’t afraid of no legacy code. But we’d rather keep our code well factored. This makes it easier for us to reason about. We don’t believe you can review quality in, if you do it line-by-line. For things we develop beyond prototypes we invest heavily in static analysis, custom visualisations like these, and automated tests.

The forest and the trees

I already had the web frontends in our development environment set up in a Virtual Machine, accessible on my phone through a private network. This meant that, after some initial setup from a laptop, I could work with a coding agent on developing this tool.

Having build this, partially while out and about on my phone, I like that I can see the forest (the ten most recent files), and the trees (individual source files). Since this is in the browser, we can re-use libraries to do source code highlighting, and hook into the runtime under Phoenix LiveView to process source code, detect change files etc.

A nice touch I found to be able to select a part of the microprint, and have the source view scroll to the corresponding part. It also works the other way around - I can scroll in the source, and the highlight in the microprint moves with it. Forests are fractal, after all.

New partner - Sensus

Wed, 28 Jan 2026 00:00:00 +0000

“You deserve to understand your software!” This is what came out as tag line for Sensus’ Architecture Review service. After Stephan Eggermont’s The state of LLM Agentic Flows went viral on LinkedIn, it was high time to describe the kind of thing they do for clients in more detail.

Especially now that Sensus’ is a QWAN partner. Marc suggested to invite Sensus, as a partner, after Stephan Eggermont has done a lot of work with me on QWAN Tracker and more visual collaboration tools. I’ve learnt a lot about moldable development through Stephan, and his view on architecture, code and the role AI augmentation in this is very complimentary to ours.

Having active visuals like this, where you can zoom in, zoom out, click through to see details is very valuable to determine next steps for a software system. Sensus makes these for code, as well as for data. To us they may be interchangeable, to stakeholders a picture tells more than a thousand data points.

On coupling and cohesion

Fri, 23 Jan 2026 00:00:00 +0000

Coupling and cohesion are old ideas, but they are still relevant today - vintage concepts that have aged well. Recent posts by Martin Dilger and Eberhard Wolff triggered us to reflect on these concepts and explore a bit based on things we have seen in practice.

Coupling and cohesion

Coupling and cohesion are vintage concepts from the late 60s, introduced by Larry Constantine as part of Structured Design. These concepts are independent of programming paradigm or approach - whether it is procedural, OO, functional, low code. Different paradigms and languages do offer different constructs to manage coupling and cohesion.

So what do we mean by coupling? We like the idea of connascence, which was coined by Meilir Page-Jones in his work on object-oriented design. He introduced this term based on the insight that coupling and cohesion are highly related - you could say are two sides of the same coin.

Two software components are connascent (coupled) if:

a change in one would require the other to be modified to maintain the overall correctness of the system

or

for some change, both would be required to change to maintain the overall correctness of the system

Roughly speaking, we want to put things that change together close to each other in a component or module, and separate things that change independently. In this way our components/modules become highly cohesive (closely coupled) while their dependencies with other parts are loosely coupled.

Coupling is not binary. There are different dimensions to coupling and it comes in degrees. The connascence model from Meilir Page-Jones introduces three dimensions, which helps to make conscious decisions on how and when to decouple. We will share more on connascence in a future blog post.

Coupling in context

We often suffer from existing coupling, especially if it is implicit or not-obvious. So we should try to decouple as much as possible in code we write and maintain? We cannot just “decouple everything”. Coupling is to some degree essential to make software work.

Without coupling, we don’t have working software.

The above definition of coupling mentions change. Coupling can be troublesome but only for things that change. If a module is very stable, we will not be affected much by any coupling it has.

So coupling is related to change and rates of change for different parts of our systems. Knowing the volatility or stability of the different parts can help to decide what to decouple. Changes come from the business domains, like changes in functionality, scale, performance, but also from technology, like major framework updates or libraries going unsupported. Although we know change will happen, anticipating specific changes is hard. Over time we usually see what parts become more stable.

It is not about just decoupling everything, but about making architecture and design decisions that help us manage coupling in our context. Some examples:

make more volatile modules depend on more stable modules and not the other way around;
make interfaces between modules small and focused, so that consuming modules are not sensitive to changes they don’t care about;
wrap external dependencies, including frameworks and libraries, in (thin) adapters with your desired interface, to stop framework changes rippling through your systems;
apply Hexagonal Architecture, to manage coupling between domain models, data models and interfaces to other modules and parties in a highly controlled way;
apply shearing layers of change (or pace layering) - something worth a blog post of its own.

Look ma no coupling!

We see developers often claiming that they have decoupled two parts. We already mentioned coupling is not binary. So there is some nuance to claims like that.

Martin Dilger recently wrote a post I Still Feel the Urge to Reuse Code (Even Though I Know It’s Wrong), which is a good read on managing coupling.

Let’s take a look at the example in Martin’s post: he describes that a module needs data from another module. Instead of sharing the table (which would introduce strong coupling between the modules), he decided to let the module have its own copy of the data. The copy only contains the attributes that are used by the module: id and title.

This reduces the ‘exposure’ of one module to the other and makes the interface between them small and explicit - only the id and title attributes. This reduces accidental coupling.

Why would accidental coupling be a problem? The module is not actually using the other data right?

Well, when we change the source module, it is often not obvious how much coupling there is. We need to inspect other modules to find out if and how these are coupled, which increases the effort and risk of the change.

Giving a dependent module its own copy of the data also makes the module less dependent on the availability of the source module.

The example also shows that such a decoupling move involves making trade-offs. To keeping a separate copy of the data, you needs a synchronisation mechanism and the data is eventually consistent. This is not good or bad, but it is important to keep these trade-offs in mind and make deliberate decisions about them.

If we’re nitpicky, we could say the example does not remove coupling, but reduces it. The dependent module still depends on the id and title attributes. If these would change, the module should be updated as well. However, we expect id and title to be pretty stable, so this is low-impact coupling we don’t need to worry about.

Decouple by duplicating code?

We sometimes notice some backlash against heuristics like Once and Only Once and Don’t Repeat Yourself (DRY), which focus on removing duplication. Removing duplication by introducing some abstraction would create inconvenient coupling - an entangled abstraction that has multiple reasons to change. The counter-proposal is to keep code duplicated so that the ‘duplicates’ can change independently.

This looks like a misinterpretation of the heuristics (or maybe seeing them as hard rules rather than heuristics) combined with prematurely introducing abstractions.

Duplicate code is often a hint there might be an abstraction missing. If we create an abstraction but it turns out we need to change it for different reasons, we probably have entangled different concerns that should not be together. Think of the Single Responsibility Principle - a class or module should have only one reason to change.

If we decide to keep the duplicates and it turns out they change independently, then they are by definition not coupled (using the definition above).

We think considering “what changes together” is more helpful here than focusing on removing literal duplication.

Event based architecture = decoupling?

Another form of decoupling of services we often hear mentioned, is replacing a direct, synchronous call between services by an asynchronous event bus, making them “decoupled”. This does not come for free, but is a trade-off (as always).

Again, decoupling is not binary, but a multi-dimensional scale. Some aspects of coupling are indeed reduced or removed:

coupling in time;
the availability of the dependent service does not depend on the other’s availability.

There are still other forms of coupling that remain:

Dependence on the event format - events are in fact a public API of the producing service, just like a REST API. This form of coupling is well-manageable, e.g. through contact testing, API versioning, API deprecation agreements.
Dependence on event semantics - how should the events be interpreted? This coupling is more subtle and can lead to duplicated, coupled logic in both services. If the producing logic source changes, you will probably need to update the consuming service as well.

Can we reduce the semantics coupling, e.g. by sending thick events that contain full objects? This increases the interface surface and makes the consuming service dependent on a broader set of data. This can introduce accidental coupling if not all the data is used.

Deliberate (de)coupling

We might sound somewhat critical of decoupling attempts, but we’re not saying decoupling does not work or using events is a bad idea. We find it important to realize what forms of coupling we try to reduce, what coupling remains, how are we going to manage that coupling, and what trade-offs are we willing to make in the process.

Step away from the prompt to sustain your pace

Sun, 18 Jan 2026 00:00:00 +0000

Stepping away from the keyboard (or your phone) is one of those practices that work regardless of how you produce software. Sustainable pace is solidly in the category of things we should do, regardless of how we produce work.

Sustainable pace was on my list of practices to re-evaluate last year. In a sense, now more than when I read the eXtreme Programming book, it is more a pattern than a practice. It very much depends on the context - who am I working with, what is fluent for me, what needs practice? What is fluent for others? Is the work that comes out of my flow state making their life more difficult?

Whenever we increase the amount of new information we process, we need breaks. I’m learning to play the guitar. The first time I practised, I was exhausted after five minutes. Now I can play a bit longer. And still, practising in smaller intervals works better for me than practising all day. After a while, things fall in to place, magically, without thinking about them consciously.

You need that fresh perspective. Stepping away from your software, letting it rest for a couple of days. Going out for walks. Singing in a pub choir. Connecting with other people. My desk remains one of my favourite places in the world. As does the sofa, for writing. But going out and not doing “one more thing” is important. Not only for the quality of the work, but also for the quality of your life.

Deciding to move forward with a prototype or scrap it is better mulled over away from the keyboard. That code that didn’t look quite right? Let it rest for a couple of days, write it again. Use TDD as if you meant it while waiting for your pair to show up. Bask in the glow of focused, well tested code. And then merge it with the parts that came out of the coding agent that were good enough. Spike and Stabilise goes great when you’ve got a fresh perspective.

Step away from the prompt, and come back while your subconscious does work. Especially with iterative tools like Claude Code, you can make good progress if you know what you are doing, and pressing ‘Yes’ on the next question and waiting for the result is addictive. It will also lead you into trouble when you are not paying attention.

Afterword

This post has been a long time coming. I saw people in spring last year complaining of informational overload, and a kind of mental whiplash. “What just happened?”. And not being able to stop was a common theme on the Claude Code Reddit. (I am not on there at the moment, I cut back on social media). And I wrote this post, because I need to remind myself of this. I got hooked on programming early, and burnt out early, in secondary school. I have occasionally learnt how to manage my energy better.

We need better tools, certainly. But as they say on Reddit: Touch grass. A clear head will get you the situational awareness you need.

There is no neutral position

Tue, 06 Jan 2026 00:00:00 +0000

In any complex systems, there is no neutral position. We cannot take a neutral stance in a complex system like a team, group, organisation, or with a partner.When I am part of a system, I will have influence on this system, whether I intend it or not. Even if I try to place myself ‘outside’ the system, or stand on the sidelines, or “just watch”, I’m still part of the system. “Standing on the sideline” will influence the others, usually with unintended consequences.

Doing nothing is doing something

As I wrote in The subtle art of non-intervention, not acting can also be an intervention. So deciding to do nothing will have consequences, whether we intend it or not.

As a consultant or facilitator, I might think I’m standing on the sidelines, observing the team, now and then prodding them to bring about change. In practice I become part of this system. I need to be part of a system to have influence. So I’m in, even if I’m pretending to be standing on the outside. So when I think I’m “just observing”, I am already changing the system dynamics.

We have impact on a (complex) system by engaging with it, and only by engaging. We will become a part of that whole, for some time. Being too much on the sideline means we will not have lasting impact.

Influence is reciprocal

The system will also influence me! The influencing is mutual. Gerald M. Weinberg wrote about this in Secrets of Consulting, as “Prescott’s Pickle Principle” - consultants are like cucumbers in a jar of organizational brine ;)

Cucumbers get more pickled than brine gets cucumbered. A small system that tries to change a big system through long and continued contact is more likely to be changed itself.

“Change is for other people” we sometimes joke as consultants, pretending we’re independent and it’s just the organization that needs to change. But we know that change is as much for us consultants as well.

The system touches us. Whatever is happening, it will affect us. We will feel this. It can be exhausting (drowning in other people’s problems), but if you learn to regulate this, it can provide a lot of information.

To close, two more quotes (cited by Abeba Birhane in her In defence of uncertainty presentation):

Objectivity is a subject’s delusion that observing can be done without him. Invoking objectivity is abrogating responsibility — hence its popularity.
– Heinz von Foerster

Without the observer, there is nothing.
– Humberto Maturana

Can an "agent" document your development process?

Mon, 05 Jan 2026 00:00:00 +0000

One of the questions on my Stochastic to Deterministic post, and the meta post on LinkedIn about what was left out, boiled down to: “can’t you ask the coding agent to document the process”? (The actual question was more detailed, read on to find out).

Yes, that is possible. I didn’t publish it immediately, because the order of the writing and the graphics suggests a much more up-front documentation process than how it works. For instance, the size and order of the images suggests a flow that is not as it feels like when working on QWAN Tracker.

Legibility

One reason for this, is that the process is not entirely legible for the agent. Admittedly, more of my process is now in written form, or can be derived from it, but what precedes the prompts in the agent, and what happens around it, is invisible to the agent. That means that you get documentation for the part of the process that is in writing.

Some examples of things that are not (yet) legible: The walking, the day dreams (hammock driven development), the chats with Claude desktop sketching ideas and code without running it, and iterating on that before committing to actually generating and running code, adding tests, copying and modifying stored prompts from other projects, generating more stored prompts.

Some of that can be retrieved from the chat history, but it is less explicit than the process encoded in the ‘plan iterations’, ‘prepare iteration’, ‘start iteration’ and ‘check iteration’ stored prompts.

The agent documents the written process, not the thinking, so context must be explicitly added.

(quoted, as suggested by qwen3-thinking, see bonus content below)

My actual process, as I see it at the moment

So the average process, as I perceive it, is mull over a problem, than at some point have a chat with a model on my phone to sketch out an idea. Sometimes that leads to a scaffold with code, other times a text file with a rough description of what it should do. Then I go over to a coding agent (Claude code in my case). I think if I need more stored prompts. Sometimes I ‘just’ scaffold a new site using the Phoenix LiveView scaffolding tools, and then let the coding agent do a small bit of work to merge the files I had generated, or quickly generate code based on the initial description. This is very much like the ‘spike solution’ of eXtreme Programming. I want to see the idea running, and play around with it.

Then I decide if I want to continue. At that point I might pull in stored prompts from another project that is close enough. I will tell the coding agent that I added stored prompts from another project, and how I think they should be adapted to this prototype. This is also often the point I will add tests for what is there, and then work test-first from then on. Or, occasionally, if the code is too messy, start over test-first, with the stored prompts I have to work in iterations. The iterations process is more accurate, but relatively slow.

I am learning to sometimes stop shortly after that, for personal tools. Having gotten the 80% of the value that is 20% of the time, it is not always valuable to do the remaining 900% of work for the remaining 20% of the value.

Reasons to be careful

Another reason to be careful is, that as Simon Wardley indicated, the agent is probably about 60% right, and 40% wrong, and it is up to you to figure out what are the right and the wrong bits. I think maybe with the recent versions of Claude Code and the Opus 4.5 model, it is more, but you can never be sure.

I probably should have published it with these caveats, suggestion of more structured process and possible errors, and let the readers decide for themselves. As a colleague pointed out, practices are still evolving. It is worth sharing what works, what doesn’t, and what results come out.

Generated diagrams

Looking back, I asked Claude Code for diagrams of the process. The stored prompts are plenty of text, and a picture tells a thousand words. So browse the pdf of the iteration workflow or read the markdown, with the diagrams in text.

On LinkedIn, I intentionally posted the last image, containing the json files and the markdown generated from it. The data is saying a lot about the process, and I could quickly see that it was accurate.

Original question for this post

The original question was from Hugh Greene:

Can you get the LLMs to generate “blog post fodder” commentary on what they’re doing, and what did/didn’t work, as you go?!?

my response, three weeks ago:

I should try that again. I have used that in the past to improve stored prompts, or create new ones. I did start this morning with having Claude Code generate a document explaining ‘our’ process. But you’d have to read that bottom to top, otherwise the reader might think we execute precise specifications from the beginning. It had strong vibes’ of Royce’s paper, with feedback loops that readers would ignore, because of how the document flows. That is where the image in the post comes from.

What do you think?

Bonus content - the prompt and response used to improve this post

There was a TODO at the bottom of the post, to add an image, plus Hugh Greene’s question and my initial response on LinkedIn. I run qwen3-thinking transparently in my writing environment, locally. it will take the last part of the text as a prompt, and write it’s answer, by default, in the text below the question.

I haven’t done much with language models to support my writing yet, so I though you might find this interesting.

The text above is now different of course, as I incorporated some of the recommendations. Not all. Notice in the bold text that qwen got the order of Pareto wrong. That was because I wrote it down in the wrong order. In that sense this is a bit like some cases of TDD or double entry bookkeeping: seeing the same mistake twice, but worded differently makes it obvious.

I was thinking of making a YouTube short about this process, but as Matteo Vaccari said, posts only have value when they are in front of the reader. Same goes for videos, and I don’t have time for that now.

Question and answer

Does the text above the TODO answer the question in the first begin_quote? Is this text clear to an audience of senior developers and engineering managers? What can be added, removed or reworded to improve quality?

Yes, the text answers the question. It clearly states:

“I should try that again… I have used that in the past to improve stored prompts… had Claude Code generate a document explaining ‘our’ process.”

Clarity for senior devs/engineering managers:

✅ Strong on practicality (agent’s 60% accuracy, “spike solutions”, value/effort trade-offs).
✅ Uses relevant terms (spike solution, Wardley mapping, stored prompts).
❌ “80% of work that is 20% of time” is confusing → rewrite as: “80% of the work delivers 20% of the value” (classic Pareto).

(I have fixed this now, so won’t work for YouTube)

Key fixes:

Replace:

“Having done the 80% of work that is 20% of the time…”
With:
“I often stop at 80% of the work—which delivers 20% of the value—since the final 20% consumes 900% of effort.”
Remove “TODO add meta image” (out of scope for audience).
Tighten:

“mull over a problem” → “refine problem statements”
“fledgling micro-product” → “prototype”

Why this works:

Addresses their pain points: agent limitations, documentation friction, value-focused delivery.
Shows operational maturity (self-critique, caveats, process refinement).
No fluff; every sentence ties to a concrete practice (stored prompts, test-first, Wardley’s 60% rule).

Final tweak: Add one line to crystallize the core insight:

“The agent documents the *written process, not the thinking—so context must be explicitly added.”*

(This directly answers the “how” and “why” behind the meta-post.)

Announcing QWAN Tracker

Fri, 19 Dec 2025 00:00:00 +0000

QWAN Tracker is task tracker for small, fast moving teams. For people who do the work, by people who do the work. It lets you quickly jot down things you think need doing as you are working, so you can stay focused on the task at hand. Keyboard navigation, and live sync so your partners stay in the loop.

I don’t build web applications for myself usually. But QWAN tracker is both fun and useful - for me, and then for me and Stephan Eggermont. I like tools to be responsive, and get out of the way. This doesn’t have to be for everyone. If it works for me, there might be more people who like it. Who knows.

This is an early release, see below for details. Stephan and I have been using this for two weeks, to steer our work, and we are enjoying it. We hope you might too.

X: If you aren’t embarrassed to by your first release, you left it too late. Me: Only do this when you are able to iterate.

Target audience

individuals who have moved their todos back to a text file, because all the online trackers got enshittified or disappeared
small teams who move fast and faster, and care about getting the details right, but don’t want to describe the details in detail ;-)
12 people who want to give us feedback and influence direction.

This is an early release.

Non Goals

Estimation. Tasks move one at a time, if they are too big, break them down or use another medium for the conversation.
Enterprise management reporting (this is necessary sometimes, but not in the context of small teams of indie developers for instance, there are other tools for that).

Options

Things that we might build, but don’t commit to

API so that you can hook up your favorite language model to brainstorm with, or your coding agent to pick up tasks.
Renaming boards
Renaming, adding and removing columns
Change categories - code smells and refactorings don’t work for everything ;-)
Board dashboard, so you can collect all your boards (this will probably be a paid option, we are thinking of ways to sell boards in an affordable way and with as little commitment as possible)
Ways to link to and from other mediums (e.g. opportunity solution trees, event storms, user story maps ).
Digital Sovereignty Edition. Self hosting for data privacy, formerly known as Enterprise Edition. Probably comes with some kind of DevOps capability assessment beforehand. Only latest version supported.

You can’t always build what you want,

So sometimes, you build what you need. I didn’t plan to build yet another task tracker. But once it was there, before I knew it, I had four boards live. So maybe you find this something useful. Main reason for building this is that we want a multi player version of Refactoring Cards (contact us if you want early access for the single player / co-located pair version).

QWAN tracker helps me and Stephan Eggermont stay on track - thanks for helping me get this out of the door. We have many ideas, and every time we finish something, we have even more. Initially, as you will see in this version, you will be greeted by draft code smells and refactoring cards. Press ‘d’ to delete cards. Press ‘?’ to see the help and what keyboard commands you can use.

The 4 plus 1 Rules of Simple Design

Fri, 12 Dec 2025 00:00:00 +0000

We strive for simple code. It is something we pay attention to in the Refactoring step of the Test Driven Development cycle. But what is “simple”? How do we stay away from discussions about taste or “simplicity is in the eye of the beholder?”.

In his original eXtreme Programming Explained book, Kent Beck introduced the Rules of Simple design, a heuristic consisting of a set of 4 ordered rules that focus on what “simple” means for the design of code.

Based on our experience, we have added a fifth rule to make the heuristic more context-aware. Willem came up with the fifth one a while back, and posted it on a social media platform. This lead to a lively discussion. One could consider that rule 5 is a special case, or an acceptance criterion of rule 2. What do you make of that? We’d appreciate your feedback.

We’ve found the added emphasis on the readers and later editors of the code useful over the years.

The four rules of Simple Design

The Rules of Simple design state that the design of our code should satisfy these rules, in order of priority:

passes all tests
reveals intention
contains no duplication 
has fewest elements

Passes all tests — we only refactor on green tests, so if a test is failing, we first fix it.

Reveals intention — our code is not just a solution for now, but also a means of communication with other developers (including future you). Being understandable is key to sustainable delivery. We want our code to express all intentions explicitly, by using the constructs that our programming languages offers us (classes, methods, functions, types, variables). Often, we only really understand our problem once we have written the solution, so refactoring is essential for putting everything we learned in the code.

Contains no duplication —duplication means that the same concept is expressed in multiple places. This introduces coupling between these parts - if we change one, the others should be changed as well. Especially if the coupling is implicit, it will introduce defects sooner or later. This rule is not about literal duplication, but about (implicit, hidden) coupling. Make sure that every relevant concept has a single place in the code.

Has fewest elements — once the tests are passing, we have expressed all relevant intentions and there is no duplication, we try to minimize the elements — classes, functions, methods, types.

Something special about rule 2 & 3

At first sight, revealing intention and no duplication look like two different things, but they are actually two sides of the same coin. This is captured by the Once And Only Once (OAOO) principle from Extreme Programming.

Once And Only Once means that every relevant concept needs to have its place in the code (at least once) and that the concept should not be duplicated; it should be expressed in a single place (only once).

This not only helps make code explicitly communicate its intent, but also makes it predictable.,Everyone knows where to find things and we can be sure that this is the only place where to look. It helps in deciding what to put where and what to find where.

The fifth rule

Having worked with many different teams and developers of different background and experience levels, we have added a fifth rule:

5. the code should be at an abstraction level the whole team can understand

We have worked in multiple teams where a few highly experienced developers wrote dense, highly abstract code. This is not a bad thing per se, but in those cases the more junior developers did not have the experience level to work with the resulting code. This is particularly relevant when external developers join the team for a limited time period. The code they leave behind should be manageable by the rest of the team.

Willem was confronted with this, when working in a team, where in order to ship, the code had to be significantly less abstract than what he was used to. Getting an appreciation from a teammate on a tiny abstraction with documentation was great, and also a bit confusing. Somebody noticed, and it was just the right abstraction, revealing intent to everyone.

There is a strong relation here with Richard Gabriel’s notion of habitable software, from his book Patterns of Software (PDF):

What are some of the things that contribute to uninhabitable programs? Over-use of abstraction and inappropriate compression come to mind.

The discourse that follows this quote is worth (re-)reading. As sense of ownership of a program’s code and design can be directly correlated to how comfortable everyone involved finds it to work with.

So what do you think. 5th rule, or rule 2a?

QWAN - Quality Without a Name

Give your smurf a bad name

Further reading

Managing coupling through Hexagonal Architecture

Hexagonal Architecture recap

Hexagonal Architecture in practice

Different sources of change

Making trade-offs

Hexagonal Architecture and (de)coupling

References

How does the human stay in the loop, while developing on their phone?

“What am I seeing here?”

The forest and the trees

New partner - Sensus

On coupling and cohesion

Coupling and cohesion

Coupling in context

Look ma no coupling!

Decouple by duplicating code?

Event based architecture = decoupling?

Deliberate (de)coupling

Further reading

Step away from the prompt to sustain your pace

Further reading

Afterword

There is no neutral position

Doing nothing is doing something

Influence is reciprocal

Can an "agent" document your development process?

Legibility

My actual process, as I see it at the moment

Reasons to be careful

Generated diagrams

Original question for this post

Bonus content - the prompt and response used to improve this post

Question and answer

Announcing QWAN Tracker

Target audience

Non Goals

Options

You can’t always build what you want,

The 4 plus 1 Rules of Simple Design

The four rules of Simple Design

Something special about rule 2 & 3

The fifth rule

Further reading