DEV Community: Edgar Nahama Alochi

The Role of Clear Documentation in Team Velocity

Edgar Nahama Alochi — Sat, 01 Aug 2026 06:07:50 +0000

Most teams treat documentation like a speed bump.

They are wrong.

Documentation is engine oil.

When a team says “we don't have time to document,” what they are really saying is:

“We prefer to finance our progress with high-interest technical debt.”

Velocity is not about how fast you can type.

It is about how rarely you stop, stare at a function, and wonder what the developer who wrote it six months ago was trying to accomplish.

Documentation is not paperwork.

It is the preservation of intent.

The Speed Trap

There is a persistent myth in engineering:

“The code is the documentation.”

This is partially true.

Code explains what the system does. It is the ultimate source of truth for implementation.

But code is silent about why it does it that way.

Code tells you the implementation.

Documentation tells you the trade-offs.

When the why disappears, velocity disappears with it.

Every time a new engineer joins the team — or an old engineer returns to a forgotten module — they must perform digital archaeology. They dig through commit history, Slack threads, and half-remembered conversations trying to reconstruct the missing context.

This is not speed.

It is friction disguised as progress.

Why Velocity Actually Stalls

Velocity rarely dies because engineers type slowly.

Velocity dies because of uncertainty.

It shows up in predictable ways.

The Tribal Knowledge Tax

Critical information exists only in the heads of three senior engineers.

To move forward, you must interrupt them.

Your progress comes at the cost of their focus. The team slows down while pretending to move faster.

The Regression Loop

You see a line of code that looks redundant.

You remove it.

Two days later production breaks because that “redundant” line was quietly preventing an edge case discovered during a 2022 incident.

Documentation would have saved you two days and a few grey hairs.

The Decision Re-Run

The team spends three hours debating an architectural decision.

Six months later, the exact same meeting happens again.

No one remembers why the first decision was made.

So the debate starts from zero.

Again.

Documentation shrinks the time-to-understanding.

If a system takes ten minutes to understand instead of two hours, the team does not just move faster.

It moves confidently.

What to Document (And What to Ignore)

Most documentation fails because it documents the wrong things.

It explains syntax instead of decisions.

Useful documentation follows three simple rules.

1. Context Over Syntax

Do not explain that a loop iterates over an array.

Engineers already know that.

Explain why the system uses an array instead of a stream, or why a synchronous call was chosen over an asynchronous one.

The value of documentation is not repeating the code.

It is explaining the reasoning behind it.

2. Record Decisions (ADRs)

Architectural Decision Records are one of the highest leverage tools in engineering teams.

Every significant design decision should answer three questions:

What did we choose?
What alternatives did we consider?
Why did we reject them?

Without this, every new engineer eventually believes they have discovered a brilliant idea.

Often it is simply the same idea the team rejected two years ago.

3. The README Is a Map

A good README should get a new engineer from:

git clone

to a running, tested environment in five minutes.

If onboarding takes an hour, the documentation is broken.

If it takes two days, the architecture probably is too.

The Discipline of the Grown Engineer

Writing good documentation feels like a chore.

That is because it forces clarity.

You can hide confusion inside complicated code.

You cannot hide it inside a clear sentence.

If you cannot explain the intent of your system in writing, there is a good chance you do not fully understand it yet.

Documentation is not busywork.

It is an act of empathy for:

your future self
your teammates
the engineer who will inherit the system three years from now

(Who, statistically speaking, might also be you.)

The Uncomfortable Conclusion

Velocity is a function of clarity.

If your team claims to be moving fast but:

the architecture is a mystery
onboarding feels like a two-week hazing ritual
and every change requires consulting the “one person who knows the system”

then the team is not fast.

It is fragile.

Real velocity is sustainable.

It comes from a shared, written understanding of the system — one that survives beyond any individual developer.

Stop thinking of documentation as extra work.

Documentation is the work.

Everything else is just typing.

Designing for Change, Not Control

Edgar Nahama Alochi — Fri, 31 Jul 2026 17:21:11 +0000

There is a quiet lie we tell ourselves when we design systems.

We call it structure. We call it governance. We call it standards, frameworks, alignment. But beneath all those respectable words is a single desire: control.

I understand the temptation. I have felt it myself. When you are responsible for a system, a product, a team, or an organisation, you want predictability. You want to believe that if you think hard enough and design carefully enough, you can eliminate surprises. You want the future to behave.

It never does.

Architecture, whether technical or organisational, is temporal. A decision that is correct today can become a liability tomorrow. What solves a constraint at one stage often becomes the bottleneck at the next. That is not failure. That is the nature of growth.

The problem begins when we design as though today’s constraints will last forever.

Control is a snapshot. It captures the present and freezes it. But the world is not static. Markets move. Teams change. Customers evolve. Technology ages. Even our own understanding matures. Designing for control assumes stability. Designing for change assumes movement.

And movement is the more honest assumption.

When I design systems now, I do not ask, “How do I make this perfect?” I ask, “How will this need to evolve?” The first question leads to rigidity. The second leads to resilience.

Perfection is brittle. Resilience bends.

There is a particular kind of comfort that comes from tightly coupling everything. When components depend deeply on each other, when processes are heavily standardised, when decisions must pass through a single authority, things appear orderly. It feels safe. But that safety is deceptive. It works beautifully until the first significant change arrives. Then the cost of altering one part ripples through the entire structure.

Loose coupling, on the other hand, can feel untidy. It requires trust. It requires clarity at the boundaries rather than micromanagement at the centre. But when change inevitably comes, the system absorbs it rather than shattering under it.

Designing for change also demands humility. It means admitting that we do not fully understand the future. It means recognising that our current models are provisional. I have seen teams spend months polishing a grand design, only to discover that real users behave in ways no whiteboard session predicted. Feedback is not an interruption to design. It is design.

The deeper lesson is human. Systems do not change themselves. People change them. If the people inside a system do not understand it, cannot question it, or are afraid to adjust it, then no amount of architectural elegance will save it. Real adaptability comes from shared understanding, not from tighter control mechanisms.

There is a difference between clarity and control. Clarity defines purpose, principles, and constraints. Control dictates every action. The former enables autonomy. The latter suffocates it.

When I think about architecture over time, I see phases. Early on, we optimise for speed. Later, we optimise for stability. Eventually, we must optimise for adaptability. The mistake is assuming one optimisation strategy works forever. It does not. Every stage of growth creates new pressures. The structures that enabled momentum in one phase can quietly inhibit it in the next.

The irony is that designing for change often results in calmer systems. When flexibility is built in, emergencies decrease. When experimentation is safe, innovation becomes routine rather than disruptive. When failure is expected and contained, it does not escalate into catastrophe.

Control, by contrast, creates fragility. The tighter we grip, the more dramatic the break when something slips through.

This does not mean abandoning discipline. Designing for change is not the same as chaos. It requires clear interfaces, explicit assumptions, measurable outcomes, and thoughtful boundaries. It demands observability so that when the system shifts, we can see it. It demands modularity so that change in one area does not infect the whole. It demands continuous reflection so that decisions are revisited rather than fossilised.

In practice, this means making decisions that are reversible where possible. It means favouring principles over prescriptions. It means documenting intent, not just implementation. It means building teams capable of evolving the system rather than depending on a single architect to guard it.

Most importantly, it means letting go of the illusion that control equals competence.

Competence is the ability to adapt.

When I look back at systems I am proud of, they share a common trait. They survived change. They were not flawless. They were not static. They evolved without collapsing. The decisions within them were not perfect, but they were adjustable.

That is the standard I aim for now. Not control, but capacity. Not rigidity, but resilience. Not permanence, but progression.

The tide will always come in. The only real question is whether what we have built can endure its arrival and reshape itself when it does.

Design for that.

How to write technical posts that survive AI noise

Edgar Nahama Alochi — Wed, 29 Jul 2026 23:08:29 +0000

There is a new kind of content pollution on the internet.

It is clean looking.
It is fast.
It is confident.
It is usually correct in the same way instant noodles are usually a meal.

You have seen it.

Twenty posts explaining distributed systems with suspiciously identical examples.
Thirty threads about performance that all end with the same advice about caching.
A flood of technical content that sounds useful until you try to build anything from it and realize you were given a polished summary of someone else’s summary of someone else’s blog post from 2018.

This is the AI noise era.

Which is not the same thing as saying AI is bad.
It is not.
It is useful.
It is fast.
It can help good writers think better and move faster.

But it has changed the publishing environment in one important way.

Average content is now almost free.

That means the old strategy of writing a technically correct post with generic advice is no longer enough. If your post can be recreated in six seconds by a prompt and a decent model, your post is competing in a commodity market. Commodity markets are not kind to authors.

So the question is not how to write more posts.

The question is how to write technical posts that still matter when everyone can publish instantly.

The answer is depth.
But not the fake kind.

Real depth.

The kind that comes from contact with reality.

The first rule is simple

Write from experience before you write from explanation.

Most technical posts fail because they start with the concept and never arrive at the problem.

They explain what a thing is.
They list benefits.
They define terms.
They sound educational.
They leave the reader unchanged.

People do not remember definitions.
They remember tension.

A post survives AI noise when it begins with something the model cannot fake well on its own.
A real incident.
A painful trade off.
A mistake that cost time.
A decision that looked smart and later failed in production.
A problem that refused to behave the way the docs promised.

This does not mean every post needs a war story.

It means every post needs friction.

If you are writing about retries, do not begin with a textbook explanation of retries.

Begin with the duplicate payout incident.
Begin with the customer who got charged twice.
Begin with the queue that politely melted your downstream service because you retried immediately and at scale.
Now the reader cares.

AI can summarize concepts.
It struggles to replace earned judgment.

That is your advantage.
Use it.

Write for people who have to make decisions

A lot of technical writing is written for imaginary readers who have infinite time, full context, and no budget pressure.

That reader does not exist.

Real readers are trying to decide something.

Should we adopt this tool.
Should we refactor this service.
Should we split the database.
Should we introduce a queue.
Should we keep the monolith another year.
Should we trust this benchmark.
Should we hire for this skill.

If your post does not help someone make a decision, it will be skimmed, bookmarked, and forgotten. Which is a very polite way of saying ignored forever.

Strong technical posts are decision support documents disguised as articles.

They help the reader answer questions like these.

What problem is this actually good at solving.
What does it cost to run in the real world.
What breaks first.
What team maturity is required.
What signs tell me I am too early.
What signs tell me I am already late.

This is where experience shows.

A junior writer often explains what is possible.
A seasoned writer explains what is advisable.

That second one survives.

Stop writing encyclopedias

One of the easiest ways to sound intelligent and be useless is to write the complete guide.

The complete guide is often just a long apology for not making choices.

It includes everything.
It excludes judgment.
It is impossible to disagree with because it refuses to commit.

In an AI heavy internet, completeness is no longer a moat.
Machines are very good at exhaustive overviews.

What they are worse at is useful reduction.

Readers do not need more information.
They need better compression.

Write narrower.
Cut harder.
Choose a point of view.

Not this.

This article explains everything about observability.

Write this.

If your team has fewer than ten engineers, start observability with latency, error rate, and one business metric before buying a dashboard that requires its own onboarding ceremony.

That sentence has blood pressure.
It has a user.
It has constraints.
It has a recommendation.
Someone can disagree with it.
Good.
Now you are writing.

A post that survives AI noise usually has a spine.
It stands for something.

Originality is not being weird

Many people hear originality and immediately produce chaos.

No.
That is not originality.
That is just caffeine with formatting.

Original technical writing is usually familiar truth described with sharper honesty.

You do not need a revolutionary theory.
You need a real observation stated clearly.

For example.

Most teams do not have a scaling problem. They have a coordination problem wearing a scaling costume.

That is not a new law of physics.
But it is useful.
It is pointed.
It reflects reality many engineers have seen and few say out loud.

Originality often comes from pattern recognition.

After enough years, you notice that the same failure keeps returning in different clothes.
Different stack.
Same mistake.
Different logo.
Same organizational issue.
Different tooling.
Same missing ownership.

Write that pattern down.

That is the work.

AI can recombine language.
It cannot easily replace years of noticing.

Be specific where it matters and abstract where it helps

This is a craft skill and it changes everything.

Weak technical posts stay abstract for too long.
Strong ones move between concrete detail and general principle at the right moments.

If you stay abstract, the post feels airy.
If you stay too concrete, the post becomes a diary entry no one else can use.

You want both.

Show the concrete case.
Then extract the principle.
Then show where the principle breaks.

Example rhythm.

We moved retries into the worker and accidentally multiplied load during provider degradation.

The principle is that resilience mechanisms can increase failure pressure if they are not bounded.

The practical fix was backoff, jitter, idempotency keys, and a hard retry budget tied to business value.

Now the reader gets story, lesson, and implementation direction in one pass.

That survives because it teaches more than facts.
It teaches thinking.

Explain trade offs like an adult

AI generated technical content often has a familiar smell.
Everything is beneficial.
Every tool is powerful.
Every pattern improves scalability, reliability, developer experience, and perhaps your posture.

Real systems do not work like that.

Every technical decision creates winners and losers.
Every abstraction moves complexity somewhere.
Every convenience has a bill.
Usually monthly.

If you want your writing to survive, be the person who names the bill.

Do not just say event driven systems improve decoupling.

Say they also make debugging harder, make data consistency more social than technical, and require teams to care about contracts long after the launch excitement is gone.

Do not just say microservices improve scalability.

Say they can improve scaling for parts of the system while making ownership, testing, and incident response dramatically worse if your team structure is still operating like one monolith with more meetings.

This is what mature readers trust.

Not optimism.
Calibration.

A good technical post should feel like advice from someone who has paid for at least one bad decision.

Add the things AI usually leaves out

If you compare a lot of human technical writing with AI generated writing, one pattern appears quickly.

The machine often covers the what and the why.
It is much weaker on the when, the if, and the what happens next.

That gap is where your writing can become durable.

Include timing.

When should a team adopt this.
What stage is too early.
What symptoms suggest readiness.

Include prerequisites.

What must already be true for this approach to work.
Team skills.
Operational maturity.
Traffic patterns.
Business constraints.

Include failure modes.

How this goes wrong in practice.
What people underestimate.
What breaks during incidents.
What gets expensive quietly.

Include maintenance reality.

Who owns it in month nine.
How upgrades happen.
What knowledge becomes concentrated in one person and ruins everyone’s weekend when that person is offline.

Include reversibility.

Can the team back out.
How expensive is rollback.
What decisions become sticky.

These are not decorative details.
They are the difference between technical writing and technical marketing.

Your readers know the difference, even if they cannot always explain why one felt more trustworthy.

Use examples that reveal judgment, not just syntax

Code examples are good.
Tiny toy snippets with no context are often not.

There is a place for syntax teaching, but if the goal is a post that survives noise, examples should do more than compile.

They should expose design choices.

Instead of showing only how to implement a retry loop, show why you capped retries at a low number for non critical operations and used a dead letter queue for the rest.

Instead of showing only a cache wrapper, show how stale data tolerance changes by domain.
A product catalog can tolerate minutes.
A wallet balance cannot.
Now the reader learns architecture, not just code.

The most valuable examples are the ones that answer the hidden question in every engineer’s mind.

Yes, but how would you do this in a system that people actually use.

Write for that question.

Make your writing falsifiable

This sounds academic.
It is actually practical.

A lot of forgettable content survives only because it says nothing testable.
It is all vibes and verbs.

Robust technical writing makes claims that can be challenged.

For small teams, adding a service mesh before basic observability usually increases operational complexity faster than it increases reliability.

That is a claim.
People can debate it.
People can test it against experience.
People can add nuance.
That is healthy.

When your writing can be disagreed with, it has shape.
When it has shape, it gets remembered.

Do not hide behind endless caveats.
Yes, context matters.
It always matters.
You still have to say something.

The job is not to be impossible to criticize.
The job is to be useful enough to risk criticism.

Write like a human who has met other humans

There is a strange trend in technical writing where people remove all personality in order to sound serious.

This usually produces text that sounds like a compliance document explaining a toaster.

You do not need stand up comedy.
You do need a voice.

Humour helps because it compresses shared pain.

Everyone who has maintained a legacy system understands a line like this.

The code worked perfectly until we looked at it.

That line does work.
It creates rapport.
It signals experience.
It gives the reader a reason to continue.

Sarcasm helps too, in controlled doses.
The keyword is controlled.
You are seasoning a meal, not setting the kitchen on fire.

The goal is not to perform personality.
The goal is to sound like a competent person thinking clearly in public.

That tone survives because readers can feel the difference between a writer and a generator.

Structure matters more now than before

AI noise has trained readers to scan aggressively.

They are not rude.
They are adapting.

If your post has no shape, they will leave before your best point appears.

Give the reader a path.

Open with tension.
Name the problem.
State the claim.
Walk through reasoning.
Show examples.
Acknowledge trade offs.
End with a practical takeaway.

Good structure is not decoration.
It is respect.

It tells the reader you did the sorting before asking for their time.

A useful test is this.

If someone reads only your headings and first sentence of each section, do they still learn something meaningful.

If not, the post may be full of words and low on signal.

The strongest moat is lived specificity

There is a type of detail that instantly increases trust.

Not random detail.
Relevant detail.

We discovered the issue because checkout success rate dropped while API error rate looked normal, which meant the failure was happening in a dependency path our alerting did not treat as critical.

That sentence tells me the writer has been inside a real system.

It tells me they measure the right things.
It tells me they noticed a mismatch.
It tells me the lesson came from operations, not just reading.

This kind of specificity is hard to mass produce at scale.
Which is exactly why it works.

If you want durable writing, keep a notebook of incidents, decisions, and mistakes.
Not just outcomes.
Context too.

What you believed at the time.
What data you had.
What pressure existed.
What trade off you accepted.
What changed your mind.

That notebook becomes future articles.
More importantly, it becomes evidence.

Evidence beats volume.

Do not fight AI by pretending it does not exist

The winning move is not purity.
It is leverage.

Use AI for roughing out outlines.
Use it to challenge your blind spots.
Use it to generate counterarguments.
Use it to find gaps in your explanation.
Use it to clean phrasing after the thinking is done.

But do not outsource judgment.

If the model writes the core argument and you lightly edit it, you may publish faster.
You will also sound like everyone else publishing faster.

The right workflow for technical writing now is something like this.

Think from experience.
Draft from judgment.
Use tools for refinement.
Return with taste.
Cut aggressively.
Add reality.
Publish.

AI can increase your speed.
Only you can increase your signal.

A practical checklist before you publish

Read your draft and ask these questions.

Is there a real problem in the opening or did I start with generic explanation

Have I made at least one clear claim that someone could disagree with

Did I include trade offs or only benefits

Did I write for a decision maker or for an imaginary student of everything

Is there a section that could only come from direct experience

Did I include timing, prerequisites, and failure modes

Did I reduce the scope enough to be useful

Does the post sound like me or like a very polite documentation bot

If the answer to the last one hurts a little, good.
That means the test is working.

Final thought

AI noise is not the end of technical writing.

It is the end of lazy technical writing getting rewarded for existing.

Which is honestly fair.

The bar is different now.
Higher in some ways.
Better in others.

If average content is free, then judgment becomes premium.
If summaries are instant, then lived insight becomes scarce.
If everyone can publish, then the people who last will be the ones who can still say something real.

Write the post only you can write.

Not because it is precious.
Because it is useful.

And useful is still very hard to automate.

The Weekend Gold Rush and the Graveyard It Leaves Behind

Edgar Nahama Alochi — Wed, 29 Jul 2026 04:20:32 +0000

I have seen this movie before. Several times. The actors change. The soundtrack improves. The promises get louder. The ending stays the same.

Around 2000 it was this.

Everyone needs a website. Learn HTML in a weekend.

Suddenly the internet was full of blinking text, broken navigation, tables inside tables inside more tables, and a mysterious visitor counter at the bottom proudly displaying the number 7. Most of those sites died quietly. Some are still out there, fossilized in forgotten hosting accounts, whispering in Comic Sans.

Then 2008 arrived.

Mobile apps are printing money. Just learn iOS development.

Every developer with a MacBook became a visionary founder. To do lists. Flashlight apps. Another to do list but this one is social. The App Store filled up. So did the graveyard. Turns out shipping version one is easy. Maintaining version twelve while Apple changes everything and users demand perfection is not.

Then 2015.

Blockchain will change everything. Smart contracts. Decentralize the world.

Whitepapers were written. Tokens were minted. Conferences were attended. Most projects never launched. Many quietly shut down. The few that survived did so not because of hype, but because someone somewhere treated it like real engineering instead of a lottery ticket.

Now it is 2024.

AI will replace developers. Build a GPT wrapper this weekend. Launch an AI SaaS by Sunday. Retire by Wednesday.

Result?

Still loading.

The pattern is so predictable it should come with documentation.

First, a new technology emerges. It is genuinely powerful. It solves something real. It unlocks new capability.

Early adopters see opportunity. They experiment. They struggle. They learn the sharp edges. They build things that actually work.

Then the get rich quick crowd floods in.

Tutorials appear. Build X in 30 minutes. Ship your AI startup in a day. Passive income while you sleep.

Reality, as it always does, shows up uninvited.

Infrastructure costs are not passive. Hallucinations are not a feature. Latency is not just a vibe. Security matters. Data privacy matters. Customers do not care that you used the latest model if their invoice is wrong.

Then 90 percent fail. Not because the technology was useless. Because they skipped the fundamentals.

This is the part that is boring and therefore ignored.

What actually succeeds is deeply unfashionable.

People who understand the technology, not just the API.

People who solve a real problem instead of wrapping a model around a landing page.

People who build maintainable systems that survive version two.

People who think about cost before the first viral tweet.

People who apply engineering principles that worked before the hype cycle and will work long after it.

Clean architecture still matters.

Proper error handling still matters.

Cost management matters even more when your variable expense is a model that charges per token.

Security matters when your system is literally generating output from user input.

Testing matters. Monitoring matters. Observability matters. Especially when the output is probabilistic and your users expect determinism.

And perhaps most controversial of all, talking to customers still matters.

You cannot prompt engineer your way out of building something nobody wants.

I am not saying AI is not transformative. It is. It changes what is possible. It changes how we work. It changes the leverage a small team can have.

What it does not change is the physics of building durable systems.

After twenty years of watching waves come and go, here is the lesson.

New technology does not obsolete good engineering.

It makes it more important.

Because when the barrier to building drops, the barrier to competing drops with it. When anyone can launch in a weekend, the only thing that differentiates you is depth. Discipline. Taste. Restraint.

The gold rush is always loud.

The people who last are usually quiet.

So the question is simple.

Are you building for the long term.

Or are you building for the demo.

Chaos engineering essentials for small teams

Edgar Nahama Alochi — Tue, 28 Jul 2026 05:58:19 +0000

You do not need Netflix scale to deserve failure

Chaos engineering sounds like something only companies with thousands of microservices and a platform team the size of a small country should care about.

That is a myth.

Small teams break in quieter ways.

A background job silently retries forever.
A webhook endpoint times out and no one notices.
A database connection pool saturates under a traffic spike.
An external payment provider starts returning 502 and your system politely collapses.

Chaos engineering is not about drama.
It is about humility.

It is the discipline of admitting your system will fail and choosing to learn that on a Tuesday afternoon instead of during your biggest customer demo.

What chaos engineering actually is

It is not random destruction.
It is not breaking production for fun.
It is not deleting databases to prove you are brave.

Chaos engineering is controlled failure experimentation.

You form a hypothesis about how your system behaves under stress.
You introduce a small, reversible failure.
You observe.
You learn.
You improve.

That is it.

The goal is confidence.
Not coverage.
Not hero stories.
Confidence.

Why small teams need it more than big ones

Large companies have redundancy in people.

You probably do not.

If one senior engineer is on vacation and the system degrades in a weird way, you do not have a war room. You have Slack messages and mild panic.

Small teams usually have:

Limited observability.
Shared infrastructure.
One database doing everything.
A few critical integrations that must work.
Very little operational slack.

This is exactly the environment where hidden failure modes thrive.

Chaos engineering for small teams is less about sophistication and more about survival.

Essential principle one: start with failure modes, not tools

Before you install anything, answer this question.

How does this system actually die?

Not in theory.
In reality.

Make a simple list.

What happens if the database becomes slow.
What happens if Redis disappears.
What happens if Stripe times out.
What happens if DNS resolution fails.
What happens if one pod runs out of memory.
What happens if a background worker crashes mid job.

If you cannot answer these confidently, you have your starting point.

Chaos begins with thoughtfulness.

Essential principle two: write a steady state definition

You cannot detect degradation if you do not define normal.

What does healthy mean for your system?

It might be:

Ninety nine percent of requests complete under 300 milliseconds.
Error rate stays under one percent.
Checkout success rate stays above a defined threshold.
Background jobs do not accumulate beyond a certain depth.

Write this down.

Chaos engineering without a steady state definition is just creative vandalism.

Essential principle three: start small and reversible

You do not need a chaos platform.
You need discipline.

Examples a small team can run safely:

Introduce artificial latency in a single dependency.
Temporarily block outbound traffic to one third party service.
Kill one application instance.
Throttle CPU on a staging node.
Simulate a failed webhook response.

Do this in staging first.
Then do it in production with tight scope and clear rollback.

If your heart rate is too high while running the experiment, it is too large.

Essential principle four: observability is not optional

If you cannot see it, you cannot learn from it.

At minimum you need:

Request latency metrics.
Error rate metrics.
Basic logs with correlation IDs.
Health indicators for external dependencies.
Alerting tied to real user impact, not infrastructure noise.

Many small teams think they are not ready for chaos engineering.

In reality they are not ready for ignorance.

Even basic metrics change everything.

Essential principle five: automate the lessons

The point of running experiments is not to feel clever.

It is to harden the system.

After every experiment ask:

Did our alerts trigger.
Did we detect the issue quickly.
Did the system degrade gracefully.
Did users notice.
Did recovery require manual heroics.

If the answer includes the word hero, you have work to do.

Add timeouts.
Add circuit breakers.
Add retries with backoff.
Add idempotency.
Add clearer alerts.
Add runbooks.

Small teams win by building systems that fail predictably.

Essential principle six: design for graceful degradation

Perfection is unrealistic.
Grace is achievable.

If a recommendation service fails, the product page should still load.
If an analytics endpoint times out, the checkout must still complete.
If one payment provider fails, another should take over.
If email delivery fails, the core transaction should still succeed.

This is architectural thinking.
Chaos engineering simply reveals where you forgot it.

Essential principle seven: avoid chaos theater

There is a trap here.

You can make chaos engineering look impressive.

Fancy dashboards.
Dramatic experiments.
Big internal presentations.

None of that matters if your system still collapses under simple pressure.

For small teams, chaos engineering should feel boring.

Routine.
Predictable.
Methodical.

If it feels theatrical, you are optimizing for attention.

A practical starter plan for small teams

Here is a calm, realistic roadmap.

Month one.
Define steady state.
Add missing metrics.
Identify top five failure modes.

Month two.
Run one controlled experiment in staging.
Improve alerts and logging.
Document findings.

Month three.
Run one small scoped production experiment.
Fix the weakest resilience gap discovered.
Write a runbook.

Repeat quarterly.

You do not need to be aggressive.
You need to be consistent.

The uncomfortable truth

Your system is already chaotic.

You just have not observed it under stress yet.

Hardware fails.
Networks partition.
Cloud providers degrade.
External APIs rate limit.
Human operators make mistakes.

Chaos engineering is not introducing instability.

It is introducing honesty.

Final thought

Small teams often optimize for speed.

Ship fast.
Fix later.
Trust that things will hold.

Chaos engineering is how you ship fast without gambling.

It gives you confidence that when reality pushes back, your system bends instead of shatters.

You do not need scale to practice resilience.

You need maturity.

And maturity begins with the courage to ask one simple question.

What happens if this breaks.

Then actually finding out.

When to refactor vs rewrite

Edgar Nahama Alochi — Mon, 27 Jul 2026 19:56:55 +0000

A decision tree for grown engineers

Every engineering team eventually faces the same dramatic sentence.

We should just rewrite this.

It is usually said after a bug, a missed deadline, or a moment of emotional exhaustion while reading a file that appears to have been written during a power outage.

Rewriting feels clean. Refactoring feels responsible.

One sounds heroic. The other sounds like laundry.

But this decision is not about emotion. It is about risk, economics, and time.

Let us walk through it like adults.

First question

Does the system work

Not beautifully. Not elegantly. Not in a way that makes you proud.

Does it work.

If the system is stable, generating value, and customers depend on it daily, you are not staring at a technical problem. You are staring at a revenue engine.

Rewriting revenue engines is not bravery. It is surgery.

Refactor when the system works but hurts.

Rewrite when the system fundamentally cannot meet current or future requirements.

If it works and you just dislike the style, close the tab and drink water.

Second question

Is the problem structural or local

Local problems are ugly functions, confusing modules, long files, poor naming, duplicated logic.

Structural problems are incorrect domain models, broken abstractions, wrong architectural boundaries, impossible scaling constraints.

Refactoring fixes local problems very well.

Rewriting is justified only when the architecture itself prevents progress.

If you can improve it piece by piece without stopping delivery, refactor.

If every small change creates chaos because the foundations are wrong, then you may need a rewrite.

Be honest here. Most problems are local.

Third question

Do you fully understand the current system

This is where most rewrite projects quietly die.

If the current system is confusing, that confusion often contains business rules that no one documented.

Legacy code is frequently a fossil record of production incidents.

When you rewrite without fully understanding the behavior, you do not create a cleaner system. You create a regression generator.

If the answer is no, you do not understand it deeply, your first step is not rewrite.

Your first step is to learn.

Refactor while learning. Add tests. Document behavior. Shrink uncertainty.

Rewrite only after you can explain the old system clearly to someone else.

Fourth question

Is delivery allowed to slow down

Rewrites consume focus. They create parallel universes. You maintain old and new simultaneously.

If your company cannot afford slower feature delivery for months, rewriting is fantasy.

Refactoring allows incremental progress. You improve while shipping.

If the business needs momentum, refactor.

If the business is intentionally investing in a platform reset, and everyone understands the cost, then rewrite can be strategic.

But it must be a business decision, not a developer mood swing.

Fifth question

Are tests strong enough to protect you

Refactoring relies on safety nets.

If you do not have meaningful tests, refactoring feels dangerous and rewriting feels tempting.

But here is the uncomfortable truth.

Rewriting without tests is gambling at a higher table.

If you cannot confidently change the system today, you will not magically become confident rebuilding it from scratch.

Invest in tests first.

The decision becomes clearer once safety exists.

Sixth question

Is the pain growing or stable

Some code is ugly but stable. It does its job quietly.

Other systems become slower, harder to change, and more fragile every quarter.

If the cost of change is compounding, you are facing architectural debt.

In that case, continuing to patch may be more expensive than starting fresh.

If the cost is flat and predictable, refactoring over time is usually sufficient.

Measure change cost. Do not guess.

The practical decision tree

Here is the simplified version.

Does it work and generate value
Yes
Then prefer refactor

Does the architecture block critical future goals
Yes
Consider rewrite

Do you deeply understand current behavior
No
Learn and refactor first

Can the business tolerate slower delivery
No
Refactor

Are tests strong
No
Strengthen them before anything dramatic

Is change cost compounding
Yes
Rewrite might be strategic

Notice something.

Rewrite appears only after several gates.

That is intentional.

The emotional trap

Rewriting feels productive because it removes friction instantly.

You open a new folder. The files are clean. The abstractions are pure. You feel like an architect instead of a mechanic.

But software is not a painting. It is an evolving system embedded in reality.

The old code survived production traffic. It contains scar tissue that protects you from repeating mistakes.

Refactoring respects that history.

Rewriting erases it.

Sometimes erasing is necessary. Often it is ego.

A healthier pattern

Instead of thinking refactor or rewrite, think in layers.

Stabilize the existing system with tests.

Extract boundaries slowly.

Replace modules behind interfaces.

Strangle old components with new ones.

Over time, the system becomes new without a dramatic rewrite event.

The business never feels a reset. The engineers never freeze progress.

This is less cinematic. It is also less catastrophic.

The uncomfortable conclusion

Most teams do not need rewrites.

They need discipline.

They need tests, clearer boundaries, smaller pull requests, and patience.

Rewrites are rare strategic moves.

Refactoring is daily engineering.

If you find yourself wanting to rewrite, ask one final question.

Am I solving a structural constraint
Or am I trying to escape complexity I have not yet understood

The answer determines whether you are being an engineer

Or just emotionally refactoring your feelings.

NASA's Rule of 10: The rules of programing that put flying metal in orbit

Edgar Nahama Alochi — Sun, 26 Jul 2026 14:00:28 +0000

The NASA Ten Rules of Programming

My interpretation of these rules with Golang examples.

NASA did not write these rules to win arguments on the internet.
They wrote them because software failed in ways that were expensive frightening and sometimes irreversible.

The rules are short. Almost annoyingly so.
That is intentional.

Each rule is a reminder that complexity is not free and that computers are fast but humans are fragile.

They helped put flying metals in orbit and manage Voyager 1, the most distant human made object.

Let’s walk through all ten using Go not because Go is perfect but because it makes these ideas painfully obvious.

Rule 1

Restrict all code to very simple control flow

If your logic requires a mental stack trace to understand it will fail at the worst possible moment.

Go helps here by being boring on purpose.

Bad

func process(x int) int {
    if x > 0 {
        for x < 100 {
            if x%2 == 0 {
                if x%3 == 0 {
                    x += 7
                } else {
                    x += 3
                }
            } else {
                break
            }
        }
    }
    return x
}

Good

func process(x int) int {
    if x <= 0 {
        return x
    }

    for x < 100 {
        if x%2 != 0 {
            return x
        }
        x = nextValue(x)
    }

    return x
}

func nextValue(x int) int {
    if x%3 == 0 {
        return x + 7
    }
    return x + 3
}

Simple flow is not about fewer lines.
It is about fewer thoughts.

Rule 2

Give all loops a fixed upper bound

Unbounded loops are promises you cannot keep.

They say trust me this will eventually stop.
NASA does not trust that. Neither should you.

Bad

for {
    data := read()
    if data == nil {
        break
    }
    process(data)
}

Better

for i := 0; i < maxReads; i++ {
    data := read()
    if data == nil {
        return
    }
    process(data)
}

Even when reading streams you can still impose limits.
Timeouts retries counters budgets.

Infinite loops belong in theory not production.

Rule 3

Avoid heap memory allocation after initialization

This rule scares people because it sounds extreme.

What it really says is do not allocate memory unpredictably while running critical logic.

In Go you do not control the heap but you can control when and how you allocate.

Bad

func handle(req Request) {
    buf := make([]byte, req.Size)
    process(buf)
}

Better

type Handler struct {
    buf []byte
}

func NewHandler(maxSize int) *Handler {
    return &Handler{
        buf: make([]byte, maxSize),
    }
}

func (h *Handler) Handle(req Request) {
    process(h.buf[:req.Size])
}

This is not about micro optimization.
It is about predictability.

The garbage collector is helpful.
It is not magic.

Rule 4

Restrict functions to a single purpose

If a function does more than one thing it lies about its name.

Bad

func SaveUser(u User) error {
    validate(u)
    db.Save(u)
    log.Printf("saved user %s", u.ID)
    sendEmail(u)
    return nil
}

Better

func SaveUser(u User) error {
    if err := validate(u); err != nil {
        return err
    }
    return db.Save(u)
}

Side effects should be explicit and separate.

Small functions fail smaller.

Rule 5

Use a minimum of two runtime assertions per function

This rule is about defending assumptions.

In Go assertions usually look like early checks.

Bad

func divide(a b int) int {
    return a / b
}

Better

func divide(a b int) (int error) {
    if b == 0 {
        return 0 errors.New("division by zero")
    }
    return a / b nil
}

Assertions are kindness to future readers.
Especially future you at 2am.

Rule 6

Declare data objects at the smallest possible scope

The longer a variable lives the more places it can hurt you.

Bad

var result int

func compute(a b int) int {
    result = a + b
    return result
}

Better

func compute(a b int) int {
    result := a + b
    return result
}

Short lifetimes mean fewer ghosts in the system.

Rule 7

Check the return value of all non void functions

This is the rule Go takes personally.

Ignoring errors is lying to yourself.

Bad

file _ := os.Open("data.txt")

Better

file err := os.Open("data.txt")
if err != nil {
    return err
}

Errors are information.
Discarding them does not make them go away.

Rule 8

Limit pointer use

Pointers increase the number of possible states your program can be in.

Go uses pointers but discourages pointer gymnastics.

Bad

func update(u *User) {
    u.Name = strings.ToUpper(u.Name)
}

Better

func update(u User) User {
    u.Name = strings.ToUpper(u.Name)
    return u
}

Use pointers when you must not because you can.

Rule 9

Compile with all warnings enabled and treat them as errors

Go does not have warnings.
It simply refuses to compile nonsense.

Unused variables unused imports unreachable code.
All dead on arrival.

That is a feature not a limitation.

If your language allows warnings treat them like failures.
Your future stability depends on it.

Rule 10

Use static analysis tools

Humans miss patterns.
Machines do not get tired.

In Go this means tools like

go vet
staticcheck
race detector

Example

go test -race ./...

These tools are not optional extras.
They are part of the engineering system.

NASA trusted them with spacecraft.
You can trust them with your backend.

The quiet lesson behind the rules

The NASA rules are not about cleverness.
They are about humility.

They assume that you will forget.
That you will misread.
That you will be interrupted.

They are written for humans under pressure.

Go as a language aligns with this philosophy almost accidentally.
Simple syntax explicit errors limited abstraction boring defaults.

The rules remind us that reliability is not achieved by brilliance.
It is achieved by restraint.

And restraint scales better than genius ever will.

A Small, Annoying Reminder About MySQL, Next.js, and Reality

Edgar Nahama Alochi — Sat, 25 Jul 2026 20:01:24 +0000

Today's reminder that MySQL will happily let you believe you're doing everything "right" right up until it doesn't.

I was wiring up a perfectly ordinary paginated query in a Next.js service. Nothing exotic. Prepared statements, placeholders, clean parameter handling. The kind of code you write on autopilot because you've written it a hundred times before.

And then MySQL reminded me again that it is not PostgreSQL.

The offending query looked harmless:

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT ? OFFSET ?

The parameters were validated. Integers only. Floored. Bounded. Safe. Sensible.

And still: runtime error.

The cause, as always, is not obvious until you already know it:

MySQL does not support placeholders forLIMIT and OFFSET in prepared statements.

Not partially. Not "sometimes." Just no.

This is one of those behaviors that lives in the uncanny valley between "documented" and "constantly forgotten." Every time I switch contexts PostgreSQL to MySQL, ORM generated queries to raw SQL I relearn this the hard way.

The fix is simple, but mildly infuriating.

Instead of placeholders, you must interpolate the integers directly:

const limitInt = Math.floor(limitNum);
const offsetInt = Math.floor(offset);

const dataQuery = `
  SELECT *
  FROM writings
  ${whereClause}
  ORDER BY created_at DESC
  LIMIT ${limitInt} OFFSET ${offsetInt}
`;

And yes, this is safe because:

limitNum andoffsetare validated
Values are clamped and floored
They cannot contain user controlled strings
Only WHERE clause values remain parameterized

The resulting query is exactly what MySQL expects:

text

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT 6 OFFSET 0

Instead of the version MySQL silently refuses to support:

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT ? OFFSET ?

This is not a Next.js problem.
It is not a driver bug.
It is not a configuration issue.

It is simply one of those MySQL constraints that leaks through abstraction layers and reminds you that SQL dialects are not interchangeable, no matter how much tooling tries to pretend they are.

The frustrating part isn't the workaround.
The frustrating part is that this failure happens after you've already done the "right" things:

Prepared statements
Parameterized queries
Defensive validation
Boring, careful code

And yet, you still have to break the pattern carefully, deliberately to satisfy the database.

The takeaway is not "don't use MySQL."
The takeaway is simpler, and more annoying:

Always remember which database you are talking to.

Because the moment you assume uniform behavior across SQL engines, reality will correct you usually in production.

Fixed.
Again.

Understanding Next.js Page Caching (with a real example)

Edgar Nahama Alochi — Wed, 22 Jul 2026 23:12:10 +0000

Caching can be a tricky topic, especially when pages don’t update the way you expect.
I recently ran into an interesting issue while working on the /writing page of my site. Whenever I added or updated articles, the changes did not show immediately. Oddly enough, the individual article pages updated as expected, but the listing page stayed stale.

After some digging, I realized this was not a bug. It was Next.js doing exactly what it is supposed to.

How Next.js caching works

Next.js (App Router) handles HTML caching at the edge in production. For statically prerendered pages, it sets Cache-Control: s-maxage=31536000, which is one year. This header tells CDNs and edge caches that they can serve the page without re-fetching for a long time. Browser cache headers such as no-cache do not override this because s-maxage takes priority for shared caches.

This explains why the listing page showed stale content while individual article pages, which are either dynamic or use revalidation, updated immediately.

How to control caching

Next.js provides a clean way to manage page freshness.

First, set revalidation for a page. In the page file, for example app/writing/page.tsx, add:

export const revalidate = 60; // seconds

The page is served from cache for 60 seconds. After 60 seconds, the next visitor triggers background regeneration. Visitors continue to get a fast response while the page updates.

For instant updates after saving content, use on-demand revalidation:

import { revalidatePath } from 'next/cache';
revalidatePath('/writing');

Call this in your article save logic, whether that is a CMS, API route, or webhook, to invalidate the cached page immediately.

Key lessons from my experience

Edge caching is powerful, but it can make pages seem stale if revalidation is not configured. Browser cache clearing or changing Nginx headers does not affect HTML caching for statically prerendered pages. The correct place to control page freshness is in the Next.js route itself, not the server or CDN alone.

By adding a single line of code to the route, I now get the perfect balance: fast cached pages that still update reliably when I add or edit content.

References

Next.js ISR and Self-hosting

Next.js Caching and Revalidation

Next.js Config and Headers

Making Next.js Behave: Practical Notes on Performance, Architecture, and Not Shooting Yourself

Edgar Nahama Alochi — Wed, 22 Jul 2026 06:33:08 +0000

Next.js is fast by default.
It is also very easy to make slow by accident.

Most performance problems I see in Next apps are not about React being slow or Vercel being expensive. They come from unclear boundaries, duplicated work, and letting “temporary” decisions live forever.

These are notes on how to keep a Next.js codebase fast to build, predictable to run, and pleasant to work in.

Start by making the codebase legible

Before touching performance tools, make the project understandable.

If a new developer cannot tell where hooks live, where API logic lives, or where page copy lives within a few minutes, you will pay for that confusion forever.

A boring structure wins.

Keep one place for hooks.
One place for shared UI components.
One place for content and metadata.
Thin pages that mostly wire things together.

app/
  dashboard/
  solutions/
  foo/
  bar/
components/
hooks/
lib/

This does not make the app faster at runtime. It makes humans faster. That compounds.

DRY is about removing decisions, not saving lines

Duplicated logic forces the reader to make choices.

Which metadata file is correct.
Which SEO description was updated.
Which API client variation should I use.

Centralize anything that changes together.

export function buildMetadata(input: MetadataInput): Metadata {
  return {
    title: input.title,
    description: input.description,
    openGraph: { ... },
    twitter: { ... },
  };
}

When every page uses the same builder, you stop worrying about consistency. You trust the system again.

Trust is performance.

Prefer server components until proven otherwise

Client components are easy. They are also expensive.

Every client component ships JavaScript, runs hydration, and increases build and bundle cost. Use them only when you actually need interactivity.

If a component does not use state, effects, or browser APIs, keep it on the server.

export default async function Page() {
  const data = await getData();
  return <View data={data} />;
}

No use client. No hydration. Less work.

You can always move logic client side later. Moving it back is harder.

Cache aggressively, but intentionally

Next gives you caching for free, but only if you let it.

Use fetch with caching semantics instead of rolling your own.

await fetch(url, { next: { revalidate: 60 } });

Avoid wrapping everything in dynamic just because something broke once. That turns your app into an expensive SPA with extra steps.

If something must be dynamic, isolate it. Do not poison the whole page.

Keep API clients dumb

Your API client should not know about routing, auth state, or UI behavior. It should send requests and return data.

Once we added a server proxy, the client became simpler instead of more complex.

await fetch('/api/backend/payments', {
  credentials: 'include',
});

No tokens.
No headers.
No branching logic.

The server handles auth. The client just asks for data.

This improves security and reduces mental load.

Never store tokens in localStorage

It is convenient.
It is also unsafe.

LocalStorage is readable by any injected script. There is no mitigation once it is compromised.

If you care about security, use httpOnly cookies and move auth to the server.

cookies().set('access_token', token, {
  httpOnly: true,
  secure: true,
});

Yes, it requires more setup. Yes, it is worth it.

Reduce build work by deleting code

Most build optimizations come from removing work, not adding tools.

Things that slow builds quietly:
Duplicated imports
Large client components
Overused dynamic rendering
Unused dependencies
Copy pasted config

Before reaching for caching layers, ask what the compiler is doing repeatedly that it should not be doing at all.

Treat DX issues as real bugs

If a fresh clone does not boot cleanly, that is a bug.
If formatting changes every commit, that is a bug.
If Node versions drift, that is a bug.

Pin your environment.

# .nvmrc
20

Commit generated files that tools expect.
Pick one package manager.
Make the happy path obvious.

The goal is that nothing surprising happens on day one.

Make failures explicit

If the backend is down, fail clearly.
If an image format is unsafe, opt into it intentionally.
If something is deprecated, address it early.

Silent failures turn into folklore. Loud failures turn into fixes.

The real optimization

A fast Next.js app is not one with the most tricks.
It is one that does the least unnecessary work.
For the browser.
For the server.
For the developer.

When the structure is clear, the build gets faster.
When the security model is clean, the code gets simpler.
When the project explains itself, people stop being afraid to change it.

That is when Next.js starts to feel boring again.

And boring is exactly what you want.

Open Source in the Age of AI: When Slop Floods the Swamp

Edgar Nahama Alochi — Tue, 21 Jul 2026 09:21:04 +0000

I like open source for the same reason I like well designed systems.
Clear inputs. Honest outputs. Humans in the loop.

Lately that loop feels clogged.

Over the last few weeks something strange has happened. Pull requests multiplied. Bug reports exploded. Security issues appeared out of thin air. Everything looked serious. Everything looked formatted. Everything looked wrong.

This is not enthusiasm.
This is industrial scale contribution theater.

We taught machines to talk. Some people decided that talking counts as contributing.

The Inbox as a Crime Scene

If you maintain a project today your inbox looks like a crime scene.

There are fingerprints everywhere. None of them match reality.

You open a pull request. It compiles on paper. It fails in practice.
You read a security report. It references functions that do not exist.
You scan the explanation. Confident tone. Wrong universe.

The tragedy is not that the code is bad. Bad code has always existed.
The tragedy is volume.

One thoughtful contribution costs minutes to review.
One careless AI generated contribution costs context. Attention. Energy.

Multiply that by a hundred. By a thousand.

This is not collaboration. This is a denial of service attack on human judgment.

The Slop Factory Model

Here is the new workflow.

Prompt the model
Generate something plausible
Submit it everywhere
Hope something sticks

No understanding required. No ownership. No follow up.

It is the software equivalent of throwing spaghetti at a wall and calling yourself a chef.

The machine does not care.
The submitter often does not either.
The maintainer pays the bill.

Open source was built on learning in public.
This is guessing in bulk.

When Everything Looks Like Work

AI slop is dangerous because it looks like effort.

There are tests. There are comments. There are long explanations written in a polite tone.
There is just one missing ingredient.

Reality.

The model does not know your codebase.
It does not know your constraints.
It does not know why that weird edge case exists.

It only knows how code usually looks.
And that is not enough.

A map of a city is not the city.
Generated code is not understanding.

The Maintainer as the Bottleneck

Here is the uncomfortable truth.

Open source does not scale on code.
It scales on trust.

Maintainers are not compute. They do not autoscale.
They get tired. They burn out. They leave.

When you flood a project with low quality contributions you are not helping.
You are converting goodwill into unpaid labor.

That is why some projects are closing pull requests.
Ending bug bounties.
Banning AI generated submissions outright.

Not because they hate tools.
Because they value their time.

Tools Are Not the Enemy

This is important.

AI is not the villain.
Misaligned incentives are.

Used well AI is a sharp knife.
Used badly it is a confetti cannon pointed at a codebase.

The difference is intent.

Did you read the code
Did you run it
Do you understand the change
Are you willing to maintain it

If the answer is no then the contribution is noise regardless of how it was produced.

What Open Source Actually Needs

Less volume.
More care.

Fewer drive by contributions.
More long term thinking.

AI that helps people understand systems instead of impersonating them.
Contribution guidelines that reward clarity not quantity.
Platforms that protect maintainers instead of optimizing for activity graphs.

Open source survives on meaning not motion.

A Quiet Ending

If we are not careful we will build a future where bots submit to bots and humans quietly walk away.

Not with anger.
With exhaustion.

The fix is not dramatic.
It is boring.
It is human.

Slow down.
Read before you write.
Understand before you submit.

Because open source was never about how much code you can generate.

It was about caring enough to make it right.

The Best Line of Code Is the One You Never Write

Edgar Nahama Alochi — Mon, 20 Jul 2026 22:47:37 +0000

The best line of code is the one you never write.
The second best is the one you delete.

This isn’t laziness. It’s restraint.

Every line of code is a liability: something to read, understand, test, debug, maintain, migrate, and eventually explain to someone who didn’t write it, often future you, who will be far less charitable. Less code doesn’t just mean fewer bugs. It means fewer assumptions, fewer hidden contracts, and fewer places for complexity to quietly rot.

Simple code beats clever code almost every time. Clever code impresses in the moment. Simple code survives. The goal isn’t to be smart. It’s to be clear. Code should explain itself without requiring interpretation or bravado.

Consider a small example.

Clever:

total := lo.SumBy(
    lo.Filter(orders, func(o Order) bool {
        return o.Paid && !o.Refunded
    }),
    func(o Order) float64 {
        return o.Amount * (1 - o.Discount)
    },
)

It works. It is concise. It is also doing filtering, business rules, and calculation in a single expression. Understanding it requires knowing the helper library, the order of operations, and the embedded business logic all at once.

Simple:

var total float64

for _, order := range orders {
    if !order.Paid || order.Refunded {
        continue
    }

    total += order.NetAmount()
}

More lines. Less code.

The intent is obvious. The loop reads top to bottom. The business rule has a name. There is a clear place to add logging, debugging, or a new condition without fear.

This is not accidental. Go’s design nudges you toward this style. It makes cleverness slightly uncomfortable and simplicity feel natural, because boring, readable code scales better than impressive code ever will.

The same principle applies at the system level. Well-designed systems outperform clever ones. Clever systems depend on sustained brilliance and discipline to keep functioning. Well-designed systems depend on structure, constraints, and unremarkable correctness. They do not need heroics to stay stable.

AI makes this lesson more urgent, not less. Modern tools are extremely good at generating code quickly and confidently. They will happily produce large, intricate solutions to problems that would have been better solved by a simpler model, a tighter constraint, or a deleted requirement. AI optimizes locally. Humans must optimize globally.

Without global understanding of the domain, the trade-offs, and the long-term cost, code generation turns into code inflation. The risk is not that AI writes bad code. It is that it writes reasonable-looking code that no one fully understands or truly owns.

Great engineers do not win by typing faster. They win by choosing simplicity over cleverness, design over tricks, and deletion over accumulation.

Deletion is a design skill.
Omission is an architectural decision.

In an era where code is cheap, clarity is expensive. That is where real engineering lives.

Write less. Delete more. Design simply.