DEV Community: Odilon HUGONNOT

Claude Code's 17 Official Skills: the Rule vs the Practice

Odilon HUGONNOT — Wed, 22 Jul 2026 09:00:03 +0000

Anthropic's docs are clear: a SKILL.md should be under 500 lines. Their own docx skill is 590. I read all 17 of Anthropic's official skills, frontmatter by frontmatter, while building my own marketplace alongside. Every time, the same gap: the docs say one thing, the corpus does another. And the corpus is the one that's right.

Here's what actually comes out when you read the code instead of the docs.

The description is 90% of the skill

A skill is useless if it doesn't trigger at the right moment. And what decides triggering isn't the body of the SKILL.md, it's its description in the frontmatter. Claude reads the list of available skills (just name + description) and picks. So all of the "when to use it" must live in the description, not the body.

The counter-intuitive part, which Anthropic repeats in its own skill-creator: Claude under-triggers skills far more than it over-triggers them. It only consults a skill for a task it can't handle trivially. "Read this PDF" will never fire the PDF skill, even with a perfect description. Hence an explicit instruction: write descriptions that are a little pushy.

You see it in the code: the xlsx skill says "Use this skill any time a spreadsheet file is the primary input or output", pptx says "any time a .pptx is involved in any way". No shyness. You push triggering, you don't hold it back.

The 500-line rule nobody follows

"Keep the SKILL.md under 500 lines" is one of the most quoted rules. In practice, docx is 590 lines, and the docs themselves add "feel free to go longer if needed". The others range from 32 to 404. The truth: 500 is a target, not a law.

The real principle behind it isn't length, it's the context budget. The SKILL.md body loads on every trigger. If it's big because it holds the essentials, fine, go over. If it's big because it drags along detail that could live elsewhere, that's the fault. Size alone isn't the sin.

Progressive disclosure: mostly scripts, rarely references

The central skill pattern is staged loading: metadata (name + description) always in context, the body loaded on trigger, and resources (scripts/, references/) only on demand. A script can even execute without being loaded into context.

Except that in the corpus, 11 skills out of 17 are a single SKILL.md, with no subfolder at all. Splitting isn't the norm, it's the exception you reach for when the domain warrants it. And when you do split, it's mostly scripts/: pdf, docx, xlsx, pptx are first and foremost script boxes for deterministic operations. The references/ (docs loaded on demand) appear on only two skills. The lesson: pull the deterministic stuff into executable code long before you pull prose into a side file.

The "NOT for" Anthropic never writes

Writing my own skills, I systematically added a "NOT for X" clause to the description, to avoid false triggers. Reading the official ones, surprise: they almost never do it. Their descriptions list inclusions ("this includes…"), not exclusions.

The reason fits in one word: their domains don't overlap. The PDF skill and the Excel skill can't be confused, so no exclusion is needed, and they'd rather maximize triggering. My case is different: my skills touch each other (reviewing a diff, shipping a feature, wrapping up a branch are adjacent). The "NOT for" lets me disambiguate between my own skills. So it isn't a universal rule, it's a response to overlap. If your skills don't compete, don't add it: you'd only reduce your triggering, the worst flaw of all.

How they actually optimize a description

The most instructive part of the official skill-creator is that they don't guess a good description, they measure it. The protocol, unrolled:

20 eval queries: 8-10 that should trigger, 8-10 that shouldn't. Realistic and messy, the way a real user would type (file paths, personal context, typos, lowercase).
The negatives are near-misses, not obvious ones. "Write a fibonacci function" as a negative for a PDF skill tests nothing. Good negatives share keywords with the skill but need something else.
Each query run 3 times for a reliable trigger rate, then an improvement loop over 5 iterations.
You pick the description by its score on a held-out test set (60% train, 40% test), so you don't overfit the queries you already know.

It's an eval pipeline, not a finger in the air. Most people write a description by feel and move on. Anthropic treats it as the product.

At a glance: the assumption vs the practice

The gap, row by row, across the 17 official skills:

The common assumption

What the official corpus does

A SKILL.md is under 500 lines

docx is 590, and the docs add "go longer if needed"

The description just says when to use the skill

It must be pushy: the real risk is under-triggering

You split into references/ and scripts/ (progressive disclosure)

11 of 17 skills are a single file; when you split, mostly scripts/

You restrict the description ("NOT for") to avoid false triggers

Almost never written: distinct domains, they maximize triggering

A good description is written by feel

It's measured: 20 queries, each run 3 times, a 5-iteration loop, scored on a held-out test set

What to remember

The real lesson isn't in the list of rules, it's in the gap. The docs give clean heuristics; the corpus shows how competent people bend them when the ground demands it. Reading the 17 skills teaches more than reading the doc page, because you see the real trade-offs: going past 500 lines when the content deserves it, skipping the split two-thirds of the time, pushing triggering rather than restricting it.

If you keep one thing: the risk isn't that your skill triggers too much, it's that it doesn't trigger at all. Write the description to be found.

🧩 My skills, installable

I built a marketplace of Claude Code skills from my real workflow, applying these patterns. Browse and install them on the Skills page, including a skill-builder skill that condenses these principles. To frame an agent, see also the CLAUDE.md contexts.

Frequently asked questions

How many lines should a SKILL.md be?

Aim for under 500, but it's not a law: the official docx skill is 590. What matters is that the body doesn't drag detail that should live in a script or a reference file. Go over if the essential content warrants it, then add pointers to side files.

Why doesn't my skill trigger?

Almost always the description. Claude under-triggers by default and only consults a skill for a non-trivial task. Make the description more inclusive and "pushy" ("use this skill whenever… even if the user doesn't say…"), with real trigger phrases. And test: a one-step task will never trigger a skill, and that's normal.

Do I need references/ and scripts/ folders?

Not by default: 11 of the 17 official skills are a single SKILL.md. You split when the domain is heavy, and then mostly into scripts/ for deterministic work (file manipulation, validation). references/ only earns its place for large multi-variant domains.

Skill, CLAUDE.md or hook?

Skill = a capability triggered by its description when the situation calls for it. CLAUDE.md = context always loaded for a specific project. Hook = deterministic automation on an event, enforced by the harness, not the model. If it's "always do X", it's a hook or a CLAUDE.md, not a skill.

Event Sourcing and CQRS: A Practical Guide for Developers

Odilon HUGONNOT — Tue, 21 Jul 2026 09:00:07 +0000

The accountant walks up to your desk. "This account shows 150 dollars. Why?" You open the database, you look at the balance column. It says 150. That's all it can say. The twenty operations that led to that number? Overwritten, one by one, on every UPDATE. You can't answer.

That's the problem Event Sourcing solves. And CQRS is the companion that makes it usable day to day. These two words sound scary, we associate them with Kafka, microservices and unicorn architectures. The reality is simpler, and more useful. This guide lays out the mental model, says when these patterns are worth it (and when they're not), then traces a concrete implementation path in Go with PostgreSQL.

Event Sourcing in one sentence

Instead of storing the current state of a piece of data, you store every event that led to that state. The current state is recomputed by replaying the events in order.

A bank account is no longer a balance = 150 row. It's a list: Credited(200), Debited(70), Credited(20). The balance is the result of a computation, not a stored value. You've lost nothing, because you never overwrite anything. You only ever append.

// CRUD: you store the result. The history is overwritten.
account := Account{Balance: 150}

// Event Sourcing: you store the facts. The balance is recomputed.
events := []Event{Credited{200}, Debited{70}, Credited{20}}
balance := replay(events) // 150, rebuilt from the start

An event is a past fact, immutable, named in the past tense: OrderPlaced, PaymentConfirmed, AccountDebited. Once written, it never changes. That single decision shapes everything else.

CQRS in one sentence

You separate write operations (the commands, which change state) from read operations (the queries, which read state). Two paths, two models.

CQRS and Event Sourcing are two independent patterns. You can do CQRS without Event Sourcing, and the other way around. But in production they almost always go together: the write side produces events, and the read side serves from views computed off those events. The write model protects the business rules, the read model is optimized to be read fast.

The three real wins

You don't adopt Event Sourcing to look modern. You adopt it for three concrete things, and if none of them speaks to you, move on.

A free, immutable audit log. Every change is a timestamped event you never overwrite. In fintech, in healthcare, anywhere a regulator can ask "who did what, when", this is the argument that justifies everything else.
Temporal queries. "What was the balance last Tuesday at 2pm?" becomes trivial: you replay the events up to that date. With a CRUD table, that question is impossible to answer.
Rebuilding. A corrupted projection, a bug in a read view? You throw it away and recompute it from the events. The source of truth is intact by construction.

When NOT to use Event Sourcing

This is the section tutorials forget. Event Sourcing has a real cost: more code, a different mental model, a team to train. For most applications, a plain old CRUD with an audit table is more than enough.

Avoid Event Sourcing if your domain is a simple form that saves rows, if history doesn't interest you, if nobody will ever ask you "and before?", or if the team is discovering the topic on a project already under pressure. The pattern shines on domains where the history IS the data: accounts, payments, inventory, bookings, complex business workflows. Elsewhere, it adds friction without paying off.

The complete mental model

Three building blocks are enough to understand everything. Once they're clear, the rest is just implementation.

The aggregate is the guardian of business consistency. It's the one that says "no" when an operation is invalid (an account doesn't go below zero, an already-shipped order can't be cancelled). In Event Sourcing, the aggregate has no directly persisted state: its state is the result of replaying all its events from the beginning.

The command is an intent ("debit this account by 70"). It goes through the aggregate, which validates, and which produces one or more events if it's allowed, or an error if it isn't. Never both.

The projection is a view computed from the events. "The balance of every account" is a projection. "The list of pending orders" is another. These are what your queries read, and you can throw them away and recompute them at will.

The implementation path, and where to dig deeper

I've written a series of articles that take each block in hand, with real, tested Go code. Here's the order that makes sense for learning, from the mental model to production.

The starting point: understanding why writes must be serialized per aggregate while reads can be massively parallel, in concurrency vs parallelism in Go applied to Event Sourcing. It's also the article that defines the concepts with no prerequisites.
The aggregate: the Transition() function that replays events, and the Clone() trap Go makes you forget (slices share their backing array and silently corrupt old states), in CQRS in Go: the aggregate, Transition() and Clone().
The command handler: the Handle(ctx, state, cmd) (Events, error) signature that makes business logic testable without mocks or a database, in side-effect-free command handlers.
Storage: why PostgreSQL is enough as an event store, with an append-only table and optimistic locking via UNIQUE(aggregate_id, version), in PostgreSQL as an event store.
Multiple aggregates cooperating: event choreography over a central orchestrator, and sagas, in sagas and event choreography.
Reliability against duplicates: the idempotency key for retries and double-clicks, then the four idempotency layers of a complete CQRS system, in the basics of idempotency then commands, projections and outbox.
The advanced case: how to return a synchronous result to the HTTP client in an asynchronous system, and keep a consistent audit log, in the pubsub bridge and atomic audit.

The minimal stack that's enough

The biggest trap in Event Sourcing isn't the concept, it's over-engineering. You get sold Kafka, EventStoreDB, a distributed message bus and three brokers before you even have a single aggregate that works.

For 90% of projects, PostgreSQL alone does all the work. An append-only table for events, a UNIQUE constraint to handle concurrency, polling or LISTEN/NOTIFY for projections. Snapshots and an outbox to a broker only arrive when a real volume or integration problem demands them, not before. Start small. You'll add infrastructure the day the pain is real.

What to remember

Event Sourcing and CQRS aren't an architecture you adopt wholesale because it's fashionable. They're tools for a specific problem: when the history of your data matters as much as its current state. If a regulator, an accountant or a production bug might one day ask you "and before?", they're worth their cost.

The right first step isn't to re-architect everything. It's to take a single aggregate that matters (an account, an order, a wallet), model it as events on a PostgreSQL table, and see what changes. The rest follows, block by block.

Frequently asked questions

What's the difference between Event Sourcing and CQRS?

Event Sourcing describes how you store data: a sequence of immutable events rather than the current state. CQRS describes how you organize code: one path to write (commands), another to read (queries). They're two independent patterns, but in production you almost always combine them, because one feeds the other.

Do you need Kafka or EventStoreDB for Event Sourcing?

No. For the vast majority of projects, PostgreSQL is enough: an append-only table, a uniqueness constraint for concurrency, polling or LISTEN/NOTIFY for projections. Kafka and dedicated event stores answer specific volume or integration needs, not a prerequisite of the pattern.

Isn't Event Sourcing too complex for my project?

Often, yes. If your domain is a simple CRUD with no need for history, a classic audit table is enough and costs far less. Event Sourcing is worth its cost when the history is the data: accounts, payments, inventory, bookings, or any domain where "who did what, when" is a real question.

Where do you start concretely?

With a single aggregate that matters, modeled as events on a PostgreSQL table. Understand replay and the aggregate first, then the command handler, then storage, then idempotency. The linked article series follows exactly that order, with tested Go code.

What Science Actually Says About CVs (and 3 HR Myths to Drop)

Odilon HUGONNOT — Mon, 20 Jul 2026 09:00:03 +0000

My CV had just been redone — clean, two columns, badges, a QR code. I thought it looked great. And that's exactly when the doubt creeps in: great for whom? For me, who built it, or for the recruiter who'll scan it in seven seconds between two meetings?

I'd followed the usual advice, the kind you read on every HR blog. "75% of CVs are rejected by bots before a human sees them." "CVs with numbers get 40% more callbacks." Sentences I'd swallowed without ever clicking the source. So before patting myself on the back, I wanted to know one simple thing: what does science actually say about CVs, and what's just folklore copied from blog to blog?

I pointed AI at it. Not to write my CV — I'd already done that (36 iterations with Claude, the story is here). To dig out the real studies, demand primary sources, and flush out the invented numbers. Three research agents in parallel, one non-negotiable rule: no statistic without a verifiable source, and anything that smells like a myth, you flag it. What came back made me throw out half of what I thought I knew.

The myths I almost optimized for

The worst thing about bad advice is when it's precise. A round number, a source that sounds serious, and boom, you build your CV around it. Three examples you've definitely read, and they're all hot air.

"75% of CVs are rejected by the ATS before a human." False. The line traces back to a 2012 sales pitch by Preptel, a CV-optimization company that shut down in 2013. No study, no methodology, no published data. Ever. The reality, measured by surveying recruiters about their own tools: ATS systems rank and file applications, they almost never auto-reject. The only hard filters are knockout questions the recruiter sets by hand (work authorization, location, required certification). The automatic 75% wall doesn't exist.

Optimizing your CV against a rejecting robot means preparing for a fight that isn't happening. The real reader is still a busy human.

"Numbers get you 40% more callbacks." A ghost citation. The supposed source (TalentWorks) is a dead domain, and the original "40%" didn't even mean callbacks: it referred to meeting 40% of a job's requirements. The figure got laundered from blog to blog until it became a truth nobody checked. To be clear, I'm not saying numbers are useless — quite the opposite (more on that below). I'm saying the precise multiplier is invented.

"Recruiters read in an F-pattern." The famous F-pattern comes from a 2006 Nielsen Norman Group study on reading web pages, not CVs. The CV extrapolation was made by blogs, never by a study on recruiters. NN/g itself lists five reading patterns and notes the F is "rarely a perfect F." What stays true is that the top and the left draw attention. But "your recruiter reads in an F," nobody has shown that on a CV.

The common thread across these three myths: a clean number, a fuzzy authority, and zero link to a study. The reflex that saves you is to ask for the primary source. Nine times out of ten, it doesn't exist.

What's actually proven

The good news is there's real science underneath. Less sexy, more nuanced, but usable. Here's what holds up, with the honest level of evidence next to it.

Writing quality has a measured causal effect. This is the strongest evidence of the lot: a controlled experiment by van Inwegen, Munyikwa and Horton (2023) on roughly 480,000 jobseekers shows that receiving writing assistance raised the probability of being hired by 8%. Not the polish — the clarity. Writing better helps the employer assess your ability, not just guess it. A real randomized trial, large sample. If you keep one thing: sweat the sentence.

Two pages, for an experienced profile, is defensible. A ResumeGo simulation (2018) saw recruiters prefer two-page CVs over one-page ones, especially for managerial profiles. Take it with a grain of salt (study funded by a CV-writing service, and it's a simulation, not real hiring), but it lines up with the industry consensus: one page under ten years of experience, two beyond, three almost always penalized outside academia, medicine and law.

The photo isn't neutral. A study in Management Science (Ruffle & Shtudiner, 2015, 5,312 CVs sent) shows the photo introduces a measurable attractiveness and gender bias that can backfire on you. In the US and UK, omitting it is the norm and cuts discrimination risk. Verdict: no photo is a defensible choice, not negligence.

Vocabulary matters more than the "robot." Harvard's Hidden Workers study (2021), on 8,000+ workers, shows the real problem isn't auto-rejection, it's vocabulary mismatch: if you don't use the words from the posting, the recruiter searching their database doesn't find you. So yes, mirroring the job's language is worth it. Not to clear a fictional wall — to be findable and readable by the human who scans.

And the seven-second scan? The number comes from a TheLadders eye-tracking study, small (30 recruiters), commercial, never replicated. Treat it as a rhetorical image, not a measurement. But the idea behind it holds: the first second decides, and the top of the CV must instantly say "good profile." That part is solid.

The one real technical trap: columns

Where the ATS myth deflates, a very real problem takes its place: parsing. When an ATS reads your CV, it turns it into structured text, line by line, left to right. Give it two columns, and it reads across: your job title on the left blends with a skill from the right column, and the output becomes mush.

Practical tests on five ATS platforms (Workday, Greenhouse, Lever, iCIMS, Taleo) confirm it, with numbers: on a two-column layout, Taleo flat-out lost an entire job and returned an empty skills list. The CSS-styled skill "chips"? Either ignored or shattered into orphan tokens. The QR code? An image, so invisible to the parser. In short, everything that makes my CV pretty to a human eye makes it risky for a machine.

My two-column CV is gorgeous for a human and treacherous for a parser. Both are true at the same time.

The fix isn't to butcher the design, it's to keep two versions. The pretty two-column PDF for what you actually do with a freelance CV: send it directly, link it from your site, hand it over in person. And a single-column version, no chips, standard section headings, "Jan 2021" dates, for the corporate portals with an ATS. Free 30-second test: copy-paste your CV into a plain-text editor. If the columns scramble, the ATS sees the same mess.

The radar: scoring a CV on what actually matters

Once the folklore was set aside, eight criteria with real evidence behind them remained. I turned them into a grid and scored myself with it. No-mercy verdict on my own CV:

Criterion (evidence-backed)

Score

Why

Quantified impact

9/10

Almost every line carries a number (99.9% uptime, integration complexity −80%, response time ÷4).

Seniority & scope

8/10

Dev → Lead → Architect progression visible, explicit architecture decisions. Missing 1-2 "chose X over Y" trade-offs.

Writing & clarity

8.5/10

Action verbs, precise prose. The best-proven axis (the +8% trial).

Human readability / design

9/10

Good-looking, clear hierarchy, scannable in seconds.

ATS compatibility (parsing)

4.5/10

The flip side of the design: two columns + chips + QR break parsing. No flat version.

Hierarchy / top of CV

6.5/10

Experience starts on page 2. The strongest role sits below the fold.

Length / concision

6/10

Three pages. The seniority consensus caps at two.

Proof / portfolio (GitHub, projects)

8.5/10

Annotated projects with stack and substance, GitHub and portfolio linked. A real reason to click.

Overall: 7.5/10. The content is top-tier: quantified, senior, proven. The only two real weaknesses are mechanical, not substantive: ATS parsing caused by the design, and the length that top-loads badly. Exactly the kind of diagnosis you can't make on your own, because you confuse "I like my CV" with "my CV does the job."

What it actually changed

Three levers, in order of impact, and none touches the content (which is good):

A flat ATS version. Not instead of the pretty PDF: in addition. The two-column PDF for direct sending and the site, a single-column version for corporate portals. It's only a priority if you target big companies with an ATS. For freelance use where you share the link yourself, the human design stays the right call.

Go to two pages and lift the experience up. Compact the last page (merge old education, trim interests) and start the first role on page 1. The recruiter must read "Backend Architect, fintech" in the first seconds, not a wall of profile text.

Two substantive tweaks. Add a real architecture trade-off ("modular monolith over microservices because...") and, when the number exists, a business impact in euros or users. That's what moves you from "senior" to "architect" in a hiring manager's eyes.

Conclusion

The real value of AI in this story isn't that it wrote my CV. It's that it did the dirty work nobody does: trace every piece of advice back to its primary source and find that half of them are ghost citations. The CV-advice industry largely runs on folklore repeated with confidence, because nobody clicks the link.

And the lesson that outlives the CV: I'd spent time optimizing my CV against a rejecting robot — a robot that doesn't exist. Meanwhile the real reader, the busy human who decides in a few seconds, was there the whole time. That's often the scam of "best practices": they make you please the wrong judge.

The Ideal Cart: 5 Design Patterns That Earn Their Keep (and 2 Refused)

Odilon HUGONNOT — Sun, 19 Jul 2026 09:00:03 +0000

It all starts with a review question. I was reworking my notes on the Design Patterns book, the Gang of Four one, with examples that all came from the same universe: an online shop. Shipping fees for Strategy, the order for State, stock for Observer. And the question landed: "so what would the ideal cart be? One class that uses all the patterns?"

Excellent question. Wrong direction. And the answer deserves more than a paragraph, because it contains roughly everything I know about design.

The trap: the ultimate Cart class

The starting intuition is healthy: if all five examples come from the same shop, why not assemble everything? The trap is the word "class". A Cart class stacking Strategy, Decorator, State, Observer and a Facade "to show off" is exactly what the 1994 book calls pattern fever, and it warns against it as early as page 31: a pattern should only be applied when the flexibility it brings is actually needed.

The ideal cart is not a class. It is a small architecture where each pattern holds the exact post where it earns its keep. And the hiring criterion fits in one question, the most useful one in the book: what is going to change?

Five hires, five nameable problems

So I built the full checkout flow, starting from zero and introducing each pattern only when a real request demanded it. Here is the hiring log:

Shipping fees vary → Strategy. Standard post, express, store pickup: three calculations for the same question, "how much?". One ShippingFee interface, one class per carrier. Adding a new carrier tomorrow: one class, zero modification elsewhere.

interface ShippingFee {
    public function compute(Cart $c): float;
}
class StandardPost implements ShippingFee {
    public function compute(Cart $c): float { return 4.99; }
}

The promo stacks → Decorator. "Free shipping over €50" is not a property of the carriers, it is a wrapper around them. Same interface as what it wraps: to the rest of the code, a decorated carrier is a carrier.

class FreeShippingOver implements ShippingFee {
    public function __construct(private ShippingFee $base, private float $threshold) {}
    public function compute(Cart $c): float {
        return $c->total() >= $this->threshold ? 0.0 : $this->base->compute($c);
    }
}

The order has life stages → State. "Cancel" does not mean the same thing in the cart (empty it), paid (refund) or shipped (carrier return). Instead of an if/elseif on the status duplicated in every method, the order carries a state object it swaps at each stage, and cancel() delegates. Zero ifs, forever.

Paying must trigger the unknown → Observer. Email, stock, accounting, and the SMS marketing will ask for next month. The pay() method must not know that list: it announces, and subscribers react. A list of callbacks and one loop: that is the whole pattern, and it is the same one as your addEventListener.

The controller wants one button → Facade. A Checkout object receives the shipping strategy (possibly decorated) and the event bus, and exposes one placeOrder() method. The code receiving the POST knows only it.

The detail that changes everything: where decisions live

The most important piece of the ideal cart is none of the five patterns. It is the assembly:

// The ONLY place in the program that knows the concrete classes.
$checkout = new Checkout(
    new FreeShippingOver(new StandardPost(), 50),   // a Decorator around a Strategy
    $events,
);

Every concrete choice is made at the root, at assembly time. Checkout receives interfaces: it does not know whether shipping is decorated, nor who subscribed to the events. If you have read my Clean Architecture notes, you recognize the dependency rule: the two books, written twenty-three years apart, converge on exactly the same move.

And the second lesson is my favorite: the most central class is the dumbest. The Cart itself uses no pattern. It adds up lines. The patterns live around it, at the places that change, never at the center.

The two refusals (as important as the hires)

Along the way, two patterns applied and were turned down. A Singleton (Cart::getInstance(), "to access the cart from anywhere"): a global variable in disguise, untestable, and root injection already covers the need. A Command with an undo/redo history, "just in case": nobody asked to cancel step by step, and a pattern installed for an imaginary need is complexity paid upfront.

A good design shows in its absent patterns as much as its present ones. The list of what your code refuses to do says more than the list of what it can do; it is the same idea as language progress by subtraction, one floor down.

The result, playable

None of this stayed a drawing. The shop actually runs, and I turned it into the 13th guided project of the learning section: "The pattern shop" (in French), where the checkout gets built step by step, with the real AI prompts, the first drafts that crack, two predictions to make before reading, and a final challenge (a second promo, stacked on the first, without modifying a single existing class).

Every button in the demo goes through a pattern, and an event log at the bottom shows the Observer subscribers waking up when you pay. If you just want the skeleton, it is also in the book notes, as a boxed aside.

Conclusion

What stays with me from this exercise is not the code, it is the order of operations. Not once did I ask "which pattern should I put here?". I listed the shop's likely requests, and each pattern arrived as the answer to one precise request, with a problem name attached. The two times a pattern showed up without a problem to solve, it was sent home.

Maybe that is the real definition of the ideal cart: not the one containing the most patterns, but the one where every pattern can answer the question "what are you here for?" without stammering.

Big O for the Impatient: Why Your Loop Is Slow (and When It Matters)

Odilon HUGONNOT — Sat, 18 Jul 2026 09:00:04 +0000

The page loads in 80 ms locally. In prod, on the real database, it takes 9 seconds and freezes the tab. The code did not change. The data did: 60 test rows locally, 14,000 in production.

The culprit was a ten-line loop, perfectly readable, hunting duplicates in a list. It had no bug. It just had the wrong shape. And understanding that shape is all Big O is about. No math, promise: just enough to read your own code and know which part will explode as the data grows.

Big O measures a shape, not a speed

First intuition to break: O(...) does not tell you "this takes 3 milliseconds". It tells you how the time reacts when you double the data. It is a curve shape, not a stopwatch. Three families cover the overwhelming majority of the job:

O(1) — constant. Data size changes nothing. Reading array[5000] is as fast as array[5].
O(n) — linear. Twice the data, twice the time. A loop that walks everything.
O(n²) — quadratic. Twice the data, four times the time. The killer class, and the one my loop had.

Three growth curves: O(1) flat, O(n) straight, O(n²) exploding amount of data (n) → time → O(1) O(n) O(n²) at small scale, all three look alike then O(n²) breaks away

The trap: on 60 test rows, all three curves are glued together. It is at production scale that O(n²) breaks away.

That is why my bug was invisible locally: at n = 60, O(n) does 60 operations and O(n²) does 3,600. The difference is microseconds, nobody sees it. At n = 14,000, O(n) does 14,000 operations, O(n²) does 196 million. That, you feel.

The loop that breaks away

The offending code, stripped to the bone: for each element, I rescan the whole list to see if it appears twice.

// ✗ O(n²): a loop INSIDE a loop
const dupes = [];
for (const a of list) {
    for (const b of list) {        // ← the rescan that costs
        if (a.id === b.id && a !== b) dupes.push(a);
    }
}

The same trap hides in a sneakier shape, the one that got me for years: includes() inside a loop. It looks like a single loop, but includes hides a second one.

// ✗ disguised O(n²): each includes() rescans the whole array
const seen = [];
for (const item of list) {
    if (seen.includes(item.id)) continue;   // includes = O(n), in a loop = O(n²)
    seen.push(item.id);
}

The fix is one word: Set. A Set (or an object, or a Map) is a hash table: checking membership with .has() is O(1), whatever the size. The double loop collapses into a single one.

// ✓ O(n): the Set answers in O(1), one pass is enough
const seen = new Set();
const dupes = [];
for (const item of list) {
    if (seen.has(item.id)) dupes.push(item);   // O(1)
    seen.add(item.id);
}

My 9 seconds dropped to 40 milliseconds. No clever optimization, no cache: just the right curve shape.

Why the Set is magic: array versus linked list

To see where that O(1) comes from, you have to open the hood of data structures. It all rests on one question: where do the elements live in memory? Memory is one long row of numbered cells.

An array stores its elements in cells glued next to each other. Since it knows the start address, it instantly computes where the 5000th lives: read in O(1). The flip side: inserting at the front forces everything else to shift over by one, so O(n). That is exactly what unshift() does in JavaScript, where push() (append at the end) is free.

A linked list does the opposite: its elements are scattered anywhere, and each holds the address of the next, like a treasure hunt. Inserting shifts nothing (O(1)), but reading the 5000th forces you to follow the arrows one by one from the start (O(n)). You will almost never write one by hand: in PHP it is SplDoublyLinkedList, in Python collections.deque, in Go container/list, and in JavaScript… you code it yourself.

A hash table (the Set, the Map, Python's dict, PHP's array) plays in another league: a function turns the key directly into a memory position. No walking, no shifting: read, write, test membership, all in O(1). That is why swapping an array.includes() for a Set.has() turns a quadratic curve into a linear one.

The hidden O(n) behind an innocent line

The real skill is not reciting these classes, it is spotting them in your own code, often tucked behind innocent syntax:

array.unshift(x) and a mid-array array.splice(i, 0, x): O(n), everything shifts.
array.includes(x) or array.indexOf(x) inside a loop: O(n²). A Set or a Map brings it back to O(n).
An SQL query WHERE email = ? with no index on the column: the database does a full scan, O(n) over millions of rows. The index is its version of binary search, O(log n).
A .find() inside a .map() to "join" two lists: again a loop in a loop. Index one of the two lists into a Map first.

Conclusion

Nobody will ask you to rewrite a hash table, your language ships one. That is not what Big O is for. It is for reading a loop and seeing its future: this one will hold at a million elements, that one will freeze the page. It is a reading skill, not a writing one.

And the irony is that AI changes nothing here, quite the opposite. An assistant happily produces an O(n²) loop that passes every test on 50 rows and dies in prod. Recognizing the curve shape in generated code is something you cannot delegate. If the topic clicks, I wrote a whole reading note on Grokking Algorithms, the book that finally reconciled me with algorithms without a single formal proof.

Programming Language Progress Is Subtraction

Odilon HUGONNOT — Fri, 17 Jul 2026 09:00:03 +0000

While re-reading Clean Architecture for my library notes, one sentence stopped me cold. Robert Martin defines the three programming paradigms, and he defines them backwards from every brochure ever printed:

"Each of the paradigms removes capabilities from the programmer. None of them adds new capabilities." (Clean Architecture, ch. 3)

Read it again. Seventy years of language progress, and the three greatest leaps forward are prohibitions. Nobody ever gave you anything. They confiscated your dangerous toys, one by one, and every confiscation made your code more predictable. Once you see the pattern, you see it everywhere, all the way into the languages of 2026. And it raises a dizzying question: what is left to take away?

1968: the first confiscation

The structured paradigm was born from a Dijkstra letter that became legend, "Go To Statement Considered Harmful". The goto was absolute freedom: jump anywhere in the program, anytime. And that was precisely the problem. Code riddled with gotos cannot be read, only investigated. You cannot reason about a block if anyone can land in it from anywhere.

The solution was not to add a feature. It was to ban the wild jump. What you are left with, if, while, for, is the tamed goto: control transfer that announces where it comes from and where it goes. You use the structured paradigm every day without knowing it, the way you speak in prose.

The next two paradigms follow the same pattern, and that is Martin's actual discovery:

object-oriented (Dahl & Nygaard, 1966) removes wild indirect jumps. In C, you could call "whatever code's address happens to be in this variable", with zero guarantee the address was any good. OO replaces that with the method: an indirect call whose target the compiler guarantees. Polymorphism is the function pointer, tamed;
functional (Church, 1936, before computers even existed) removes assignment: once created, a value never changes. And if nothing changes, whole families of bugs (shared state, concurrency) vanish with it.

Three paradigms, three removals, all discovered between 1958 and 1968. Martin draws a bet from it: there is nothing left to remove, there will be no fourth paradigm.

Timeline of removals: every language leap takes a capability away 1968 · Structured removes goto → code reads top to bottom 1966 · Object-oriented removes the wild indirect jump → compiler-guaranteed calls 1936 · Functional removes assignment → a value never changes again "there will be no fourth paradigm" (Martin, 2017) 2015 · Rust (ownership) removes shared mutation → data races no longer compile 2018 · Structured concurrency removes the wild spawn → no task outlives its block

The confiscation timeline. In green, Martin's three paradigms. In red, the two removals that contradict his bet: one already existed, the other arrived a year later.

The lost bet (and why that's good news)

The bet is printed in Clean Architecture, published in September 2017. And the spicy part: it was already losing when the book came out. One of the two counterexamples had existed for two years.

Rust (1.0 in May 2015) removed shared mutation: it is forbidden to have two places in the code mutating the same data at the same time. That is neither OO's removal (you can still make indirect calls) nor functional's (you can still mutate, just never two at once). The compiler rejects the program, and the entire category of data races disappears at compile time.

Structured concurrency, for its part, arrived one year after the book, and removed the wild spawn: it is forbidden to launch a background task that outlives the block that created it. Nathaniel J. Smith's founding essay (2018) is titled "Go Statement Considered Harmful", a deliberate echo of Dijkstra, because it is exactly the same crime: control flying off to who-knows-where, for who-knows-how-long. The unsupervised spawn is the goto of concurrency.

Martin was talking about sequential code, and on that narrow ground his inventory is probably complete. But his mechanics of progress, remove to make predictable, keeps producing. Right on the principle, wrong on the prophecy. That is the best kind of mistake: the one that confirms the theory while breaking the prediction.

Go, or the art of keeping only the marrow

If subtraction drives progress, then the most instructive language of the era is not the most powerful one, it is the most stubborn refuser. Rob Pike, Go's co-creator, summed up the language's philosophy in a 2012 talk whose title is the whole program: "Less is exponentially more".

Look at what Go refused: classes, inheritance, exceptions, operator overloading, annotations, and for ten years, generics. The list of absences caused screaming. But look at what it kept from OO: one single thing, the interface, that is, the compiler-guaranteed indirect call. And it even purified it: in Go, a type satisfies an interface automatically, without declaring it. Business code defines its interface at home, and the database package does not even know it exists.

// the business package declares its need, at home
type Saver interface {
    Save(invoice Invoice) error
}

// the mysql package imports NOTHING from the business code.
// It has a Save method: it satisfies the interface, period.
func (s *Store) Save(invoice Invoice) error { ... }

That is Clean Architecture's dependency inversion, no longer as a technique you apply but as the language's natural state. Go threw away OO's packaging and kept the only piece that mattered. Seventy years of OOP distilled into a mechanism that fits in ten lines of spec. If you want a closer look at that triage, I wrote up Learning Go in the library.

Those who removed more, and what it cost them

Go is not the end of the road. Other languages pushed subtraction further, and their trajectories draw the real limit of the exercise.

Zig removes hidden control flow. Its manifesto fits in one line: no exceptions, no overloading, no invisible allocation. You read a line, you know what it executes, all of what it executes. An error is a value the compiler forces you to handle, where Go still lets you write _ = err while whistling.

Elm removes undeclared effects: a function can neither mutate nor do sneaky I/O, everything goes through the return type. The famous, measurable result: no runtime exceptions in production. Probably the biggest reliability win ever bought by removal. And yet Elm remains a stagnating niche language: too pure, tiny ecosystem, the market ruled.

Erlang removes shared memory between tasks, since 1986: isolated processes passing messages, crashes that stay local. The whole industry spent thirty years rediscovering what its creators had figured out for telephone switches.

The emerging pattern: the first removals were free, nobody mourns the goto. The next ones cost. Rust buys the absence of data races at the price of a brutal learning curve. Elm buys the absence of crashes at the price of isolation. Go is probably a sociological local optimum: its real product is not purity, it is "any dev on the team reads anyone's code". Remove more, and you often lose that. The Pareto curve bends.

An Esperanto of programming?

Hence the question rattling in my head since that re-read: could an AI design the terminal language? The one that synthesizes every winning removal and keeps the essential unit bricks, the marrow and nothing else: mandatory errors-as-values, effects visible in signatures, native structured concurrency, zero hidden control flow. An Esperanto of programming: minimal, regular, no exceptions, no historical quirks.

The Esperanto analogy is tempting, and it teaches mostly through its failure. Esperanto is objectively simpler than every language it meant to replace. Regular grammar, zero irregular verbs, learnable ten times faster. It lost anyway, because a language does not win on intrinsic qualities: it wins on its ecosystem. You learn English for the people who already speak it, not for its grammar. Replace "people" with "libraries, tutorials, job offers, Stack Overflow answers" and you have exactly the gravity that keeps PHP, Java and JavaScript in orbit decades after "better" languages appeared.

But there is one parameter Esperanto never had: the primary speaker is changing. A growing share of code is written by AI, and for an AI, the cost calculation flips. Rust's brutal learning curve costs a model nothing. The library ecosystem weighs less when the generator can rewrite the missing brick. And every additional prohibition becomes a windfall: a language that rejects more programs at compile time is a better harness for generated code, every removal turns a class of plausible bugs into immediate compile errors. The removals "too expensive for humans" become profitable when the machine does the writing.

My honest forecast: the single universal language will not come, because domains pull in opposite directions (SQL removed the loop, shaders removed recursion, both were right, and neither can replace the other). What does seem plausible is a target language designed for the generated-code era, assembling the all-time best of subtractions. Not the Esperanto everyone speaks; the Latin machines would write to each other, checkable by the most intransigent compiler ever built. And we would review it, because by construction it would be boring to read. That is a compliment.

Conclusion

The thing this re-read changed in how I evaluate a tool: stop asking what it enables, ask what it forbids. The feature list is marketing; the prohibition list is engineering. A framework that can do anything protects you from nothing.

And the final irony deserves savoring: we are building the most powerful code generators in history, AIs capable of producing anything, and the best thing we can hand them is a language that refuses almost everything. Seventy years of progress by subtraction, only to understand that the most precious gift a language can give a programmer, human or not, is a compiler saying "no".

Claude Code Hooks: Real Examples (PostToolUse, Stop, PreToolUse)

Odilon HUGONNOT — Thu, 16 Jul 2026 09:00:02 +0000

For the tenth time today, I type "don't forget to run gofmt" to Claude Code. Then "run the tests before you stop." Then "don't touch the .env." The day I wired up three hooks, those three sentences vanished from my vocabulary — the machine applies them itself, every time, without me thinking about it.

Claude Code hooks are poorly documented when it comes to real examples: the docs list the events, not the configs you actually use day to day. Here are mine, ready to copy, with the traps I hit along the way — including the Stop hook infinite loop, the classic one.

A hook is a script wired to an event

A hook is a shell command Claude Code runs automatically at a specific point in its cycle. It receives JSON on stdin (the tool name, its arguments, the directory…) and can let it through, block it, or inject context. The configuration lives in settings.json (global, project, or local).

A tool call lifecycle: PreToolUse before the tool, PostToolUse after, Stop at the end of the turn PreToolUseblock / allow Tool PostToolUseformat / lint Stopend of turn

The hook points around a tool call. (+ UserPromptSubmit, Notification, SubagentStop.)

The most useful events:

Event

Fires…

Typical use

PreToolUse

before a tool call

block a command, validate

PostToolUse

after a tool call

format, lint, test

Stop

when Claude wants to stop

force a final check

UserPromptSubmit

on every message you send

inject context

Notification

when Claude is waiting

desktop notification

PostToolUse: auto-format after every edit

The life-changing hook. As soon as Claude writes or edits a file, format it. Never again a diff polluted by indentation. The matcher targets the Edit and Write tools:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path'); [ \"${f##*.}\" = go ] && gofmt -w \"$f\"; true"
          }
        ]
      }
    ]
  }
}

The hook receives the call's JSON on stdin; jq extracts the file path. We only format if it's Go. The trailing ; true guarantees a 0 exit code — otherwise a formatting error would block Claude for nothing.

PreToolUse: block what shouldn't go through

PreToolUse can refuse a tool call before it runs. Two ways: an exit code of 2 (blocks and returns stderr to the model), or a finer JSON decision. Example: forbid any edit to .env, no matter how much the model insists.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *.env|*secrets*) echo 'Protected file' >&2; exit 2;; esac"
          }
        ]
      }
    ]
  }
}

Exit code 2 = block, and the stderr message is returned to Claude so it understands why. It's more reliable than an instruction in the prompt: a hook never "forgets" between two turns of context. Same defensive logic as a middleware that filters before the handler.

Stop: force completion without an infinite loop

Stop fires when Claude thinks it's done. You can send it back to work — for example if some files are untested. But careful: if the hook blocks the stop and Claude re-triggers a Stop, and the hook re-blocks… infinite loop. The protection is the stop_hook_active field in the received JSON:

#!/usr/bin/env bash
# stop-guard.sh — refuse to stop if tests fail, ONCE
input=$(cat)
# if we're already in a Stop re-run, let it through (anti-loop)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
if ! go test ./... >/dev/null 2>&1; then
  echo "Tests are failing — fix them before stopping." >&2
  exit 2
fi
exit 0

The stop_hook_active guard is the detail that separates a useful hook from an agent stuck in a loop. Without it, a single red test turns your session into an endless loop. It's exactly the reflex of a cancellation context: plan the exit condition before you start the loop.

UserPromptSubmit: inject context automatically

This hook runs on every message you send, before Claude reads it. Whatever the hook writes to stdout is injected into the context. Handy to remind a project convention, the time, or the git state:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "echo \"Git branch: $(git branch --show-current 2>/dev/null)\"" }
        ]
      }
    ]
  }
}

Use sparingly: everything you inject costs tokens on every message. A short, useful reminder, not a dump.

The traps to know

A hook runs with your permissions. It's shell executed on your machine, no confirmation. Never write a hook that executes part of the received JSON without validating it — that's an injection door. Treat the model's output as untrusted input.

Exit code or JSON, not half of each. Exit 2 blocks, 0 lets through, the rest is non-blocking. For fine control (allow/deny with a structured reason), return JSON on stdout rather than juggling exit codes.

Performance matters. A slow PostToolUse hook runs after every edit. A gofmt is instant; running the whole test suite on every write is not. Keep the heavy stuff for Stop.

Conclusion

A hook isn't one more instruction in your prompt — it's a guarantee. The difference is huge: an instruction, the model can forget on the next turn as context fills up; a hook always runs, identically, because it's no longer the model deciding. Anything you catch yourself repeating to Claude is a candidate for a hook.

Start with the formatting PostToolUse — immediate win, zero risk. Add the Stop with its anti-loop guard when you want to lock in a final check. And keep in mind that you're wiring shell onto a model-driven loop: the rigor you put into your services, put it into your hooks.

Go Iterators (range-over-func): the yield contract and the traps

Odilon HUGONNOT — Wed, 15 Jul 2026 09:00:03 +0000

I wanted to turn a pagination helper into a "clean" iterator with Go 1.23's range syntax. Thirty seconds later: panic: range function continued iteration after function call returned false. The kind of message that says nothing until you understand the underlying contract. range-over-func iterators are elegant, but they shift part of the responsibility from the compiler to you — and that's where it breaks.

Here's how they actually work, and the three traps that turn a "clean" iterator into a production bug: the yield contract, cleanup on break, and the iter.Pull leak.

An iterator is a function that takes a yield

Since Go 1.23, you can range over a function. The iter package standardizes two signatures: iter.Seq[V] (one value) and iter.Seq2[K, V] (two, like key/value). An iterator is a function that receives a yield and calls it for each element:

// iter.Seq[int] = func(yield func(int) bool)
func Count(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := 0; i < n; i++ {
            if !yield(i) {
                return // the consumer stopped → we stop
            }
        }
    }
}

// caller side: the range syntax hides the whole mechanism
for i := range Count(3) {
    fmt.Println(i) // 0, 1, 2
}

When you write for i := range Count(3), the compiler turns your loop body into a yield closure that it passes to the iterator. Each yield(i) runs one iteration of your loop. The return value of yield is the key to everything: true = keep going, false = the consumer did a break or a return.

The yield contract: honor the false, always

This is the trap, the one behind my panic. When yield returns false, your iterator must stop immediately and never call yield again. If you keep going, the runtime panics to stop you from producing into a consumer that's no longer listening.

// ❌ ignores yield's return → panic on the consumer's first break
func Bad(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := 0; i < n; i++ {
            yield(i) // we NEVER look at the returned bool
        }
    }
}

// ✅ honors the contract
func Good(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := 0; i < n; i++ {
            if !yield(i) {
                return
            }
        }
    }
}

The rule is mechanical: every call to yield must be guarded by an if !yield(...) { return }. If you produce in several branches, each one must honor the contract. That's the price of the sugar syntax: the compiler can't check it for you, so it checks it at runtime — brutally.

Cleanup when the consumer breaks

An iterator that holds a resource — a file, a connection, a DB cursor — must release it even if the consumer stops halfway. And since a break on the caller side makes yield return false then exits your function, a simple defer inside the iterator is enough — as long as you write it:

func Lines(path string) iter.Seq[string] {
    return func(yield func(string) bool) {
        f, err := os.Open(path)
        if err != nil {
            return
        }
        defer f.Close() // ✅ runs even if the consumer breaks

        sc := bufio.NewScanner(f)
        for sc.Scan() {
            if !yield(sc.Text()) {
                return // defer f.Close() fires here too
            }
        }
    }
}

// the defer closes the file whether the loop finishes or stops at line 2
for line := range Lines("big.log") {
    if strings.Contains(line, "FATAL") {
        break
    }
}

The classic mistake is opening the resource outside the iterator function (when building the iter.Seq), where the defer no longer covers the break case. Open the resource inside the closure, close it with defer right after. Same cancellation discipline as not leaking a goroutine: plan the early exit from the design.

iter.Pull: pulling on demand, and never forgetting stop()

range is a "push" model: the iterator pushes values. Sometimes you want to "pull": advance two sequences in parallel, or consume one value at a time on a decision. iter.Pull converts a push iterator into two functions — next() and stop():

next, stop := iter.Pull(Count(1000))
defer stop() // ✅ MANDATORY — otherwise a leak

for {
    v, ok := next()
    if !ok {
        break
    }
    if v == 42 {
        break // early stop: stop() (via defer) releases the iterator
    }
}

iter.Pull runs the iterator in a dedicated goroutine. If you don't consume to the end and you don't call stop(), that goroutine stays blocked forever: a pure goroutine leak. The reflex is invariable: next, stop := iter.Pull(...) immediately followed by defer stop(). No exception.

When NOT to write an iterator

The hype pushes you to turn everything into an iter.Seq. That's a mistake. A range-over-func has a cost: indirect function calls, closures, inlining limits the compiler doesn't always cross. For a small collection already in memory, a slice is simpler and faster.

// ❌ pointless: the data fits in memory, the iterator only adds overhead
func Names() iter.Seq[string] { /* ... */ }

// ✅ return a slice: simpler to call, to test, to compose
func Names() []string { return []string{"a", "b", "c"} }

Iterators shine at what a slice does badly: lazy sequences (computed on demand), infinite ones (a counter, a stream), expensive ones (API pagination, reading a big file line by line), or composed ones (chained filters and maps without materializing the intermediates). If none of these apply, return a slice. It's the Go spirit of simplicity by default: the cleverest feature isn't always the right one.

Conclusion

range-over-func iterators are a real addition to the language, but they introduce a contract the compiler only enforces at runtime: honor yield's false, close resources inside the closure, call stop() on an iter.Pull. Three rules, three traps. Once internalized, they become automatic.

The question to ask before writing one isn't "can I?" but "is the sequence lazy, infinite, expensive or composed?". If yes, the iterator is elegant and justified. If not, you're adding complexity and overhead to return a slice — and a slice never panics.

Learning to Code With AI Without Your Brain Checking Out (2026)

Odilon HUGONNOT — Tue, 14 Jul 2026 09:00:01 +0000

In a 2024 study, a student finishes their programming exercise. They succeeded: 95% of the task done, the code runs. In the interview right after, they admit: "Honestly, I really don't understand code at all." They had just produced it. With AI, they finished everything, and learned nothing.

That sentence captures the most insidious trap of our era. AI makes writing code so frictionless that you can sail through an entire learning experience without your brain encoding a single thing. You feel like you're learning, you produce, and nothing sticks. I built an entire course section (Learn with AI) around this problem, and the deeper I dig into the literature, the more I see how underestimated it is. Here is what the neuroscience actually says, and how to learn to code in the age of AI without getting fooled.

Cognitive debt, or why you remember nothing

In 2025, Nataliya Kosmyna's team at the MIT Media Lab wired electrodes to the skulls of 54 students while they wrote essays. Three groups: brain only, search engine, and ChatGPT. The result is brutal. In the AI group, 83% of participants could not quote a single sentence of what they had just written. Not vaguely: nothing at all. The EEG showed collapsed brain connectivity, and the lowest sense of authorship over their own text.

Researchers call this cognitive debt, by analogy with technical debt. When you outsource your thinking to a machine, you save time now and pay later in the form of knowledge that never formed. The mechanism is simple and unforgiving: long-term memory is built through the effort of retrieval. If information arrives pre-chewed and no effort goes into producing it, the hippocampus consolidates nothing into the neocortex. The code passed before your eyes, never into your head.

The counterintuitive rule of learning: the smoother it feels in the moment, the less it stays afterward. Felt ease is not learning, it's just ease.

The illusion of competence

The second danger is sneakier, because it disguises itself as success. In 2024, a study titled The Widening Gap watched 21 novices solve a problem with GitHub Copilot. Completion rate: 95%, versus 65% in a comparable study without AI. On paper, a triumph. Except nine of the ten struggling students would never have finished without AI, and believed they understood the solution far more than they did.

This is the illusion of competence. Your brain confuses "I recognize this code, it looks right" with "I can produce this code." Recognizing is infinitely easier than generating, and AI constantly puts you in recognition mode. You read a solution, it seems obvious, you nod, you move on. The feeling of mastery is real. The mastery is not. And since you feel competent, you never feel the need to actually practice.

Why it's worse for beginners

The study's title, the widening gap, is no accident. AI does not benefit everyone the same way. Already-solid developers use it to produce what they already knew they wanted, and crucially they reject bad suggestions. Researchers call this negative expertise: knowing what not to do, spotting a smelly suggestion at a glance.

Beginners lack that filter. They accept Copilot's suggestions 34% of the time, versus 24% for the more comfortable ones, including when they are wrong. They dive into debugging dead ends, drifting further from the solution, convinced the AI must be right. The result: AI accelerates the strong and drowns the weak. The gap between those who already knew how to reason and the rest widens instead of closing.

The lesson is harsh but clear: AI is an amplifier, not an equalizer. It multiplies what you already know how to do. If you can judge code, it makes you formidable. If you can't yet, it gives you the illusion that learning is no longer worth the trouble.

The 4 mechanisms to actually learn

The good news is that the remedies are known, measured, and old. The science of learning calls them desirable difficulties (Robert Bjork): deliberate frictions that make learning harder in the moment and far more durable afterward. Four matter most when learning to code with AI.

Two learning paths: delegating to AI leads to fast forgetting, while active retrieval and effort lead to durable memory. Delegate to AI Actually learn AI writes the code you read, it looks clear You try first you retrieve from memory You copy, it works zero mental effort Effort, sometimes failure desirable difficulty Nothing encoded forgotten in 24h Memory consolidated it sticks

Same time spent, opposite outcomes. The friction on the right is the price of memory.

1. Active retrieval

Pulling a piece of information from your own memory strengthens it far more than rereading it. It's the best-established effect in all of cognitive psychology. Concretely: before asking the AI, try to answer yourself. Before running a snippet, predict what it will print. Close the tab and rewrite the function from memory. Every time you force your brain to produce instead of recognize, you carve it in.

2. Spaced repetition

A concept reviewed once is forgotten. Reviewed three times at growing intervals, it settles for good. The counterintuitive part: you must let forgetting begin before reviewing. Reviewing while it's all still fresh does nothing; reviewing as it fades is where consolidation happens. Revisiting a notion the next day, then three days later, then a week, beats any cramming.

3. The generation effect

Attempting to solve a problem before seeing the solution improves retention, even when the attempt fails. It's Manu Kapur's productive failure. The failed effort primes the brain to encode the explanation that follows. This is the exact opposite of what AI does, serving you the solution before you've had time to struggle with it. Flip the reflex: struggle for five minutes, then ask.

4. Negative expertise

Learn to say no to the AI's code. The core skill in the age of LLMs is no longer writing code, it's judging what you're handed. Read each suggestion asking "do I accept this, and why?". Hunt for the security flaw, the side effect, the forgotten edge case. Remember that a significant share of generated code contains vulnerabilities. The reviewer's reflex is what separates whoever drives the AI from whoever gets driven by it.

How I build my courses around this

This is exactly the philosophy of Coding with AI and the applied projects: AI cranks out code fast, you read it slowly, you send back precise instructions. Each project shows the real prompts, the shaky first draft, then the review that hardens security, accessibility and contrast. We don't teach delegation, we teach critique. That's negative expertise turned into a habit.

But rereading the research, I saw my own blind spots. My quizzes fire right after the lesson: that tests working memory, not durable memory. My examples often show the solution before the effort. I had no real spaced repetition. So I'm adding: a "predict before you run" in the editor, free-recall questions where you re-explain in your own words, the return of older notions across later lessons, and a teach-back after each exchange with the AI. In short, I'm deliberately injecting the frictions my own courses, too smooth, had sanded away.

Conclusion

The irony of all this is that the tool meant to democratize learning to code can widen the gap between those who already know how to think and those still learning. AI won't turn you into a developer in your place, any more than a calculator makes you a mathematician. It amplifies a reasoning that must already exist.

The real question was never "can AI write this code?". Of course it can. The question is: "after reading it, could I rewrite it alone?". As long as the answer is no, you haven't learned anything, you've only borrowed. And debt, one day, comes due.

I Rebuilt My Courses on the Science of Learning (2026)

Odilon HUGONNOT — Mon, 13 Jul 2026 09:00:01 +0000

I had already built the courses. Interactive, with a live code editor, quizzes, diagrams, bilingual. I was rather proud of them. Then I read an MIT EEG study on cognitive debt, and another on the widening gap between learners in the age of AI. They made me uneasy, because they described a trap my own courses might be falling into: giving the illusion of learning while anchoring nothing for the long term.

So I reworked everything. Here is what I changed, why, and how I rolled it out across 109 lessons without spending three months on it. It's a retrospective that's as pedagogical as it is technical. (For the science itself, I cover it in a dedicated article.)

The problem my courses couldn't see

My lessons were smooth. You read a clear explanation, watched a working example, ticked a multiple-choice quiz, moved on. Pleasant. And that's exactly the trap: the science of learning is clear, felt fluency is not learning. The easier it feels in the moment, the less it stays.

My quizzes came right after the theory: they tested working memory, not durable memory. My editors showed the solution before the learner had made the effort to find it. My multiple-choice was recognition (pick the right answer), not production (write it from memory). And nothing brought notions back over time. In short, I was sanding away every friction, when the good frictions are precisely what carves things in.

Five mechanisms, five desirable difficulties

Robert Bjork calls them desirable difficulties: deliberate efforts that make learning harder in the moment and far more durable afterward. I implemented five, each wired into the right moment of a lesson.

The five mechanisms added to lessons: predict before running, free recall, re-explain after the AI, accept or reject journal, and spaced review. 1. Predict before running 2. Free recall from memory 3. Re-explain after the AI 4. Accept / reject AI code 5. Review spaced repetition

Each mechanism targets a precise moment: predict, produce, re-explain, judge, then come back.

1. Predict before running. Before running a snippet, the preview is blurred and the learner must write what they think it will print. That's the generation effect: attempting before seeing primes the brain to encode, even when you're wrong.

2. Free recall. At the end of a lesson, a question you answer from memory, without looking, then self-assess honestly. Retrieving information carves it in far more than rereading it.

3. Re-explaining after the AI. After each box where the learner queries an AI, we ask them to re-explain in their own words. That closes the loop: checking you understood the answer, not just read it.

4. The accept / reject journal. We show a snippet produced by the AI, sometimes subtly flawed, sometimes fine. The learner decides and justifies, then compares with a senior dev's take. That's negative expertise: learning to say no to generated code.

5. Spaced review. Self-assessed notions return in a review hub, re-surfaced at growing intervals, right when you were about to forget them.

A spaced-repetition hub with no backend

The biggest piece is the fifth. Real spaced repetition needs to remember each notion's state: when it was seen, its interval, its next due date. With no database and no user account, I put it all in the browser's localStorage.

The key was freezing a data contract: each review card is self-contained. When the learner self-assesses, we store not only the verdict, but the question and answer in both languages, the link to the lesson, and the scheduling state. The hub can then replay the card outside its original lesson, entirely client-side. The accepted trade-off: history stays on the device. For a free, no-signup path, that's the right compromise.

Industrializing across 109 lessons with agents

Adding these blocks by hand across 109 lessons, in two languages, writing content specific to each topic, was weeks of work. I first validated the components on one pilot lesson, then orchestrated the rest with AI agents: one agent per lesson, each reading the pilot lesson as a reference, applying a relevance rubric, and writing content adapted to the topic.

The golden rule: don't slap all five mechanisms everywhere by reflex. Free recall almost always; a "predict" only if there's a runnable editor; a re-explanation only if there's an AI box; a journal only if a judgeable snippet exists within scope. Two excellent components beat four lukewarm ones.

The result surprised me with its contextual accuracy. On a Git lesson, the journal doesn't judge "code" but a command or a commit. On a SQL lesson, it flags a DELETE without a WHERE. On PHP, a concatenated query vulnerable to injection. Each agent adapted the snippet to the exact topic of its lesson. The irony wasn't lost on me: I used AI to industrialize courses that teach, precisely, not to delegate to it blindly.

What the tests caught

I verified everything in production with automated tests that really interact with the site: the prediction unlocking the preview, the answer revealing itself, the verdict persisting after a reload, French / English parity, zero console errors. In total, more than 230 green tests across all the courses.

And they caught real traps, all of the same sneaky kind: a hidden attribute overridden by a display: flex, so a zone showing up too early. A detail invisible when reading the code, obvious in a test. An accessibility audit also revealed an unlabeled editor and contrasts that were too weak, fixed right away. The meta lesson: behavior tests say nothing about whether a color is readable. You also have to look.

Conclusion

The hardest part wasn't writing the components' code. It was accepting that my courses, which I thought were good, were too comfortable to actually teach. Perceived quality and real effectiveness are two different things, and only the second one counts.

There remains the real question, the one no test settles: will people come back to review? Spaced repetition is only worth it if you return. That's why the final brick isn't an algorithm, but a simple "to review" badge reminding you that a notion is waiting. The best learning engine is useless if you forget to start it.

Go Middleware Best Practices in Production (2026)

Odilon HUGONNOT — Sun, 12 Jul 2026 09:00:02 +0000

The service had run for six months without a hiccup. Then one morning: 2% of requests returning a 500 — no log, no trace, no panic surfaced. The kind of bug that never reproduces locally. Half a day later, the cause: a panic in a handler, caught by a recover middleware… placed inside the logging middleware. The recover swallowed the panic after the logger had already written its line — but before the request ID was set. The result: a ghost 500, invisible in the dashboards.

A Go middleware is ten trivial lines. A chain of middleware in production is where the real problems hide: ordering, panic recovery, timeouts, ResponseWriter wrapping, context propagation. Here's what 14 years of running APIs taught me about the middleware that holds up — and the kind that falls over.

A middleware is just a function that wraps another

No magic, no framework required. A Go middleware is a function that takes an http.Handler and returns another. The canonical pattern, the one everything else follows:

type Middleware func(http.Handler) http.Handler

func Logger(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        slog.Info("request",
            "method", r.Method,
            "path", r.URL.Path,
            "dur", time.Since(start),
        )
    })
}

Everything before next.ServeHTTP runs on the way in (on the request). Everything after runs on the way out (on the response). That's the onion model: the request travels through each layer toward the handler, and the response climbs back out in reverse.

The request descends through each middleware to the handler; the response climbs back out in reverse request response Recover (panic) Request ID + Tracing Logger Timeout (context) Auth + Rate limit Handler

The onion model: declaration order = traversal order.

To chain them without nesting by hand (A(B(C(handler))) gets unreadable fast), a small helper does the job:

func Chain(h http.Handler, mw ...Middleware) http.Handler {
    // apply in reverse so mw[0] becomes the outermost layer
    for i := len(mw) - 1; i >= 0; i-- {
        h = mw[i](h)
    }
    return h
}

// usage: Recover is the outermost layer, it wraps everything else
handler := Chain(mux,
    Recover,
    RequestID,
    Logger,
    Timeout(5*time.Second),
    Auth,
)

Note the loop direction: we apply mw from last to first so that mw[0] stays the outermost layer. Get the direction wrong and the whole order inverts — which is exactly the first trap.

Order isn't cosmetic, it's functional

The most-asked question about Go middleware in production: what order do I declare them in? The answer isn't a style convention, it's a matter of correctness. Three non-negotiable rules:

1. Recover must be the outermost layer. If it sits inside the logger, a panic in the logger itself isn't caught. If it sits inside request ID, the emergency 500 won't carry the correlation ID. Recover wraps everything.

2. Request ID before the logger. Otherwise your log line has no ID to correlate with the rest of the trace. Obvious when written down — yet it's the most common inversion I see in review.

3. Auth and rate-limit closest to the handler, but after observability. You want to log and trace even rejected requests (a spike of 401s or 429s is a signal). If auth sits above the logger, your rejections are invisible.

// ❌ BAD: recover inside, rejections invisible, ID missing from the 500
handler := Chain(mux, Logger, Auth, Recover, RequestID)

// ✅ GOOD: recover outside, ID then log, auth near the handler
handler := Chain(mux, Recover, RequestID, Logger, Timeout(5*time.Second), Auth, RateLimit)

The rule of thumb: from most defensive to most domain-specific. What protects the server (recover) on top, what identifies and observes (ID, log, trace) next, what filters (timeout, auth, rate-limit) just before the business logic.

Recover: the middleware that keeps the whole process alive

In Go, an unrecovered panic in a handler goroutine doesn't just kill the request — depending on the version and HTTP runtime, it can take down the whole server. The standard net/http server recovers per-request panics by default, but it turns them into a silent dropped connection with no usable application log. An explicit Recover is therefore essential:

func Recover(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                slog.Error("panic recovered",
                    "err", err,
                    "path", r.URL.Path,
                    "stack", string(debug.Stack()),
                )
                w.WriteHeader(http.StatusInternalServerError)
                _, _ = w.Write([]byte(`{"error":"internal"}`))
            }
        }()
        next.ServeHTTP(w, r)
    })
}

Two real traps here. First: never re-panic inside the defer, or you end up with an unrecovered panic during recovery. Second, subtler: if a downstream middleware has already written a status code before the panic, your w.WriteHeader(500) will emit a superfluous response.WriteHeader call warning and be ignored. The client receives a truncated response. Handling that case is exactly why you need to know whether the response has already started — which brings us to wrapping.

Wrapping http.ResponseWriter without breaking Flush or Hijack

To log the status code or the response size, you have to intercept calls to WriteHeader and Write. The naive solution: a wrapper that remembers the code.

type statusRecorder struct {
    http.ResponseWriter
    status  int
    written int
}

func (r *statusRecorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

func (r *statusRecorder) Write(b []byte) (int, error) {
    if r.status == 0 {
        r.status = http.StatusOK // implicit Write = 200
    }
    n, err := r.ResponseWriter.Write(b)
    r.written += n
    return n, err
}

It works… until the day you serve Server-Sent Events or streaming, and everything breaks. The classic wrapping trap: by embedding http.ResponseWriter in a struct, you lose the optional interfaces the original writer implemented — http.Flusher, http.Hijacker, http.Pusher. Your SSE handler type-asserts to http.Flusher, fails, and streaming never flushes again.

// ✅ Re-expose Flush so you don't break streaming behind the wrapper
func (r *statusRecorder) Flush() {
    if f, ok := r.ResponseWriter.(http.Flusher); ok {
        f.Flush()
    }
}

// same for Hijack if you serve WebSocket behind this middleware
func (r *statusRecorder) Hijack() (net.Conn, *bufio.ReadWriter, error) {
    if h, ok := r.ResponseWriter.(http.Hijacker); ok {
        return h.Hijack()
    }
    return nil, nil, fmt.Errorf("hijack not supported")
}

Since Go 1.20, http.ResponseController exists precisely to call Flush/SetWriteDeadline through nested wrappers without re-exposing each interface by hand. On a fresh codebase, use it. If you're maintaining an existing wrapper, re-expose at least Flush — it's the case that breaks most often in production.

Timeouts: cut the request before it overflows

A handler that calls a slow database or a third-party API with no timeout is a time bomb: under load, goroutines pile up, memory climbs, and the service ends up OOM-killed. The right reflex: a middleware that sets a deadline on the request context, propagated to every downstream call.

func Timeout(d time.Duration) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ctx, cancel := context.WithTimeout(r.Context(), d)
            defer cancel()
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

Careful: this middleware doesn't kill the handler, it signals cancellation via ctx.Done(). Your downstream code still has to honor the context — a db.QueryContext(ctx, ...), not a db.Query(...). A timeout on a context no one listens to is useless. It's the same discipline as avoiding goroutine leaks: if nothing listens to ctx.Done(), the goroutine stays blocked.

Avoid the stdlib http.TimeoutHandler for this specific need: it writes its own 503 response when the deadline expires, which conflicts with your status wrapper and your recover. A context timeout keeps you in control of the response.

Observability: request ID, structured logs, and the context trap

The request ID is the thread that ties a log line, a distributed trace, and a support ticket together. The middleware generates it (or reads it from the incoming header) and puts it in the context:

type ctxKey string

const requestIDKey ctxKey = "request_id"

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-ID")
        if id == "" {
            id = uuid.NewString()
        }
        ctx := context.WithValue(r.Context(), requestIDKey, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Two best practices many people miss. One: the context key must be a private type (type ctxKey string), never a bare string — otherwise two packages both using "request_id" clobber each other. That's exactly the spirit of type rigor in Go: make the mistake impossible to compile. Two: enrich the logger with the ID once, via a slog.Logger stored in the context, rather than threading the ID through every log call:

// in the Logger middleware, once you have the ID:
logger := slog.With("request_id", RequestIDFrom(r.Context()))
ctx := context.WithValue(r.Context(), loggerKey, logger)
next.ServeHTTP(w, r.WithContext(ctx))

// everywhere downstream:
LoggerFrom(r.Context()).Info("user created", "user_id", u.ID)

Rate-limiting follows the same middleware mechanics; if you're building a serious per-IP one with golang.org/x/time/rate, I covered the full implementation in this dedicated token-bucket article.

Conclusion

A middleware in isolation is a textbook exercise. A chain of middleware in production is a matter of order and contracts: who wraps whom, who sees the panic first, who sets the context the others will read. None of these decisions is aesthetic — each one changes how the service behaves under load or during an incident.

The test that doesn't lie: trigger a panic in a handler, in a simulated production run, and watch what lands in your logs. If you get a clean 500, with the request ID, the stack, and the correlated log line — your chain is sound. If you get a ghost 500 with no trace, you now know exactly which order to revisit.

Build an MCP Server in Go (for Claude Code)

Odilon HUGONNOT — Sat, 11 Jul 2026 09:00:03 +0000

Claude Code can read your repo, run your CLI, query your database — as long as you give it the entry point. That entry point is an MCP server (Model Context Protocol). The day I wanted Claude to query our internal billing API without me copy-pasting JSON responses by hand, I wrote a small MCP server. In Go, not Python — and in hindsight that was the right call, for one specific reason we'll get to.

The official Go SDK (github.com/modelcontextprotocol/go-sdk) matured in 2025. It's perfectly usable in production now, but the docs still center on the "hello world." Here's what actually matters once the server leaves your machine: the transport choice, typed tools, auth, and the design traps I walked straight into.

MCP in 30 seconds: a server that exposes tools to an LLM

MCP is a client-server protocol. The client (Claude Code, Claude Desktop, your own agent) connects to one or more servers, each exposing three things: tools (functions the model can call), resources (data it can read), and prompts (reusable templates). 90% of real-world use is tools.

Claude Code (MCP client) talks to your Go MCP server over stdio or HTTP; the server calls your API or database Claude Code MCP client MCP server in Go Your API DB, services… stdio / HTTP Go calls The model decides to call a "tool" → the server runs it → returns the result

The MCP server is the adapter between the LLM and your system.

The key point: you don't write a prompt. You declare tools with a name, a description and an input schema. The model reads those descriptions and decides on its own when to call them. The quality of your descriptions is your interface.

The minimal server with the official SDK

Three steps: create the server, register a tool with its typed handler, run it on a transport. The SDK infers the tool's JSON schema directly from your Go struct.

package main

import (
    "context"
    "log"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

// The tool input: the SDK derives the JSON schema exposed to the model from it.
type InvoiceArgs struct {
    ClientID string `json:"client_id" jsonschema:"the client account ID"`
    Year     int    `json:"year"      jsonschema:"fiscal year, e.g. 2026"`
}

func getInvoices(ctx context.Context, req *mcp.CallToolRequest, args InvoiceArgs) (*mcp.CallToolResult, any, error) {
    rows, err := billing.Lookup(ctx, args.ClientID, args.Year) // your real code
    if err != nil {
        return nil, nil, err
    }
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: rows.Markdown()}},
    }, nil, nil
}

func main() {
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "billing",
        Version: "v1.0.0",
    }, nil)

    mcp.AddTool(server, &mcp.Tool{
        Name:        "get_invoices",
        Description: "List a client's invoices for a given fiscal year.",
    }, getInvoices)

    // stdio transport: Claude Code launches this binary as a subprocess
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

On the Claude Code side, you declare this server in the MCP config (command + arguments). At startup, Claude launches the binary, negotiates the protocol, and discovers get_invoices. No prompt to write: the description is enough.

stdio or streamable HTTP: the choice that drives everything else

The SDK supports two transports, and this is the architecture decision. They don't serve the same use case:

stdio

streamable HTTP

Execution

local subprocess launched by the client

standalone network service

Clients

one, local

many, remote

Auth

inherited from the machine

your responsibility (token, mTLS…)

Typical use

personal tool, dev, CLI

team server, SaaS, shared prod

The simple rule: stdio for a tool only you use on your machine, HTTP as soon as it's shared. The classic trap is to prototype in stdio then want to expose it to the team without realizing you're moving from a "zero auth" model to a "network attack surface." The HTTP transport plugs in almost like a regular HTTP handler — which means all the middleware best practices (recover, timeout, auth, logs) apply:

handler := mcp.NewStreamableHTTPHandler(
    func(r *http.Request) *mcp.Server { return server },
    nil,
)
// wrap it with the same middleware as any API
http.ListenAndServe(":8080", Chain(handler, Recover, Auth, Logger))

Typed tools: let Go's types do the work

This is where Go beats Python for this particular job. The JSON schema exposed to the model is derived from your input struct. No hand-written schema, no drift between validation and docs:

// ❌ manual schema: drifts from the code, validates nothing
tool := &mcp.Tool{
    Name: "search",
    InputSchema: rawJSON(`{"type":"object","properties":{"q":{"type":"string"}}}`),
}

// ✅ typed struct: schema inferred, validation for free, one source of truth
type SearchArgs struct {
    Query string `json:"query" jsonschema:"full-text search query"`
    Limit int    `json:"limit" jsonschema:"max results, default 10"`
}

When the model sends arguments, the SDK validates them against the schema before calling your handler. A year sent as a string? Rejected before your code runs. It's exactly the Go philosophy of making invalid state impossible, applied at the boundary with the LLM — the least reliable layer of your system.

Auth and security: an MCP server is an attack surface

An MCP server runs code on a model's request, and that model is driven by a potentially adversarial prompt (prompt injection). Three rules I set for myself after the fact:

1. Least privilege per tool. Don't expose run_sql with write access "just in case." Expose get_invoices(client_id, year) — bounded, read-only. Each tool is a capability granted to the model — treat it like a public API route.

2. Over HTTP, auth is non-negotiable. A bearer token checked in a middleware before reaching the MCP server, like any API. An MCP server open on the network with no auth is self-service RCE.

3. The context is your cancellation thread. If the client disconnects, ctx is cancelled — propagate it down to your DB calls. An MCP handler that ignores ctx.Done() is a goroutine leak waiting to happen under load.

The design mistakes I made

Tools too granular. My first version exposed get_client, get_invoice, get_line_item separately. The model chained five calls where a single well-designed get_client_summary would do — and every call costs a round-trip and context tokens. Design your tools for the model's task, not for your database schema.

Responses too big. Returning 2,000 lines of raw JSON saturates the context window and makes the model (and the bill) pay for nothing. Summarize, paginate, return readable Markdown instead of a dump. A tool result isn't a REST response: it's reasoning material for a human-model.

Vague descriptions. "search" says nothing. "Full-text search across invoices, returns up to limit matches sorted by date" tells the model when and how to call it. Your descriptions are literally your tool's system prompt — treat them like copywriting.

Conclusion

Writing an MCP server in Go isn't writing AI — it's writing a clean, typed, secure API whose only client happens to be a model. Everything you already know about good Go services applies: strict types at the boundary, propagated context, middleware, least privilege. MCP just adds a new category of client, the most unpredictable of them all.

And that's exactly why Go wins here: facing a non-deterministic caller, you want the maximum number of guarantees at compile time. Python lets you write the server faster; Go lets you sleep at night when the model calls it in a way you never anticipated.