Forem: Odilon HUGONNOT

Parallelism in Go — Part 1: goroutines and WaitGroup

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

You have a Go program making 10 HTTP calls to an external API. Each call takes about 1 second. Result: your program takes 10 seconds to finish. With goroutines, those 10 calls run at the same time and the whole thing takes 1 second — the duration of the slowest one, not the sum of all of them.

That's the promise of concurrency in Go. And unlike most languages where it's a pain to set up (OS threads, manual locks, cascading callbacks), Go makes it accessible from day one. You still need to avoid the classic pitfalls, and there are a few of them.

This three-part series starts from scratch:

Part 1: goroutines and sync.WaitGroup
Part 2: channels and the worker pool pattern
Part 3: errors in concurrent context and clean panic handling

What is a goroutine?

The most honest analogy: think of your browser tabs. Each tab loads its page "at the same time" — YouTube buffers your video while you read an article in another tab. Your CPU isn't truly doing everything at once (well, not entirely), but the system switches between tasks so fast it gives the illusion of parallelism.

A goroutine is the same thing: a function running "in the background" while the rest of the program continues. The difference from a classic OS thread is that goroutines are managed by the Go runtime, not the operating system. They're lightweight (a few kilobytes at startup versus several megabytes for an OS thread) and you can launch thousands of them without breaking a sweat.

To launch one, just put go in front of a function call:

package main

import (
    "fmt"
    "time"
)

func sayHello(name string) {
    fmt.Println("Hello", name)
}

func main() {
    go sayHello("Alice")
    go sayHello("Bob")
    time.Sleep(10 * time.Millisecond) // we'll come back to this
    fmt.Println("Program done")
}

That's all. go sayHello("Alice") launches the function in a new goroutine and doesn't wait for it to finish before moving to the next line. main() continues immediately.

The first trap — the program that finishes too soon

Run this code without the time.Sleep:

func main() {
    go sayHello("Alice")
    go sayHello("Bob")
    fmt.Println("Program done")
}

Likely result: you only see "Program done". The two goroutines never had time to print anything. Why?

Fundamental rule: when main() returns, the Go program terminates immediately — regardless of how many goroutines are still running. They all get killed at once, without warning, without finishing their work.

The time.Sleep(10 * time.Millisecond) in the previous example is a band-aid, not a solution. You're "hoping" that 10ms is enough for the goroutines to finish. That's fragile, non-deterministic, and doesn't scale. If the goroutines make a network call that takes 2 seconds, do you put Sleep(2s)? And what if sometimes it takes 3 seconds?

You need a mechanism to properly wait for all goroutines to finish.

sync.WaitGroup — the right solution

Imagine a head chef distributing tasks to the kitchen staff before service: "You chop the onions, you prepare the sauce, you get the plates out." Before opening the dining room, he waits for everyone to finish their prep. He doesn't check his watch and hope — he explicitly waits for confirmation from each person.

sync.WaitGroup is that synchronization mechanism:

wg.Add(n) — "I'm waiting for n more goroutines"
wg.Done() — "this goroutine is done" (decrements the counter)
wg.Wait() — "block until the counter reaches zero"

package main

import (
    "fmt"
    "sync"
)

func sayHello(name string, wg *sync.WaitGroup) {
    defer wg.Done() // called when the function returns, no matter what
    fmt.Println("Hello", name)
}

func main() {
    var wg sync.WaitGroup

    wg.Add(2)
    go sayHello("Alice", &wg)
    go sayHello("Bob", &wg)

    wg.Wait() // blocks here until both goroutines have called Done()
    fmt.Println("Everyone said hello")
}

The defer wg.Done() matters: by putting it in a defer, you ensure it will be called even if the function crashes with an error or panics halfway through. Without it, a goroutine that dies prematurely would block wg.Wait() indefinitely.

The full pattern with a loop, for example over a list of URLs:

urls := []string{
    "https://api.example.com/users/1",
    "https://api.example.com/users/2",
    "https://api.example.com/users/3",
}

var wg sync.WaitGroup

for _, url := range urls {
    wg.Add(1)
    go func(u string) {
        defer wg.Done()
        download(u)
    }(url)
}

wg.Wait()
fmt.Println("All downloads complete")

Note that we do wg.Add(1) before launching the goroutine, not inside it. If we did it inside the goroutine, wg.Wait() could trigger before the goroutine had time to register itself.

The classic loop trap

This is probably the most common bug for developers new to concurrent Go, and it's nasty because it "sometimes works" depending on execution conditions.

// BUG: all goroutines share the same variable i
for i := 0; i < 5; i++ {
    go func() {
        fmt.Println(i) // i is captured by reference
    }()
}
// Often prints: 5 5 5 5 5

Why? The goroutine doesn't capture the value of i at the moment it's created. It captures a reference to the variable i. When the goroutines eventually execute (a few microseconds later), the loop has already finished and i equals 5. So all goroutines read 5.

The fix is trivial: pass i as a parameter to the anonymous function.

// FIX: passing i as a parameter creates a local copy
for i := 0; i < 5; i++ {
    go func(n int) {
        fmt.Println(n) // n is a copy belonging to this goroutine
    }(i) // i is evaluated here, at call time
}
// Prints: 0 1 2 3 4 (in some order, but always the right numbers)

In Go 1.22+, this problem has been partially addressed: the loop variable in for i := range ... now creates a new variable at each iteration instead of reusing the same one. But the parameter pattern remains the most explicit form and is compatible with all versions.

The race detector — your best friend

A race condition is when two goroutines access the same data at the same time and at least one of them modifies it. The result is non-deterministic and often catastrophic.

Classic example: two goroutines incrementing a shared counter.

package main

import (
    "fmt"
    "sync"
)

func main() {
    counter := 0
    var wg sync.WaitGroup

    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter++ // DANGER: read + increment + write, not atomic
        }()
    }

    wg.Wait()
    fmt.Println("Final counter:", counter)
    // Expected: 1000
    // Actual: something between 800 and 1000, different every run
}

Without the right tool, this kind of bug is nearly impossible to reproduce reliably in tests. That's where Go's built-in race detector comes in:

go run -race main.go

The race detector instruments the code at compilation time and detects unprotected concurrent accesses at runtime. Its output looks like this:

==================
WARNING: DATA RACE
Write at 0x00c000126010 by goroutine 8:
  main.main.func1()
      /home/odilon/main.go:15 +0x44

Previous write at 0x00c000126010 by goroutine 7:
  main.main.func1()
      /home/odilon/main.go:15 +0x44
==================

It tells you exactly which line is the problem and which goroutines are in conflict. The performance cost is real (about 5 to 10x slower), but it's only for development and tests — never in production.

Practical rule: always run your tests with -race. go test -race ./... should be part of your CI.

Concrete example — 10 URLs in parallel

Here's a complete example that illustrates the real gain. We simulate 10 HTTP calls each taking about 1 second (using time.Sleep to avoid depending on a real API).

package main

import (
    "fmt"
    "sync"
    "time"
)

// Simulates an HTTP call taking ~1 second
func fetchData(url string) string {
    time.Sleep(1 * time.Second)
    return "data from " + url
}

func main() {
    urls := []string{
        "https://api.weather.com/london",
        "https://api.weather.com/paris",
        "https://api.weather.com/berlin",
        "https://api.weather.com/madrid",
        "https://api.weather.com/rome",
        "https://api.weather.com/amsterdam",
        "https://api.weather.com/lisbon",
        "https://api.weather.com/vienna",
        "https://api.weather.com/prague",
        "https://api.weather.com/warsaw",
    }

    // --- Sequential version ---
    start := time.Now()
    for _, url := range urls {
        fetchData(url)
    }
    fmt.Printf("Sequential: %v\n", time.Since(start))
    // Sequential: ~10 seconds

    // --- Parallel version ---
    start = time.Now()
    var wg sync.WaitGroup

    for _, url := range urls {
        wg.Add(1)
        go func(u string) {
            defer wg.Done()
            fetchData(u)
        }(url)
    }

    wg.Wait()
    fmt.Printf("Parallel: %v\n", time.Since(start))
    // Parallel: ~1 second
}

In practice, the parallel version takes the duration of the slowest call, plus a minimal goroutine management overhead. For network calls, this is often a 5 to 20x speedup depending on latencies and number of requests.

One important detail: in this example, we're ignoring the return values of the goroutines. In real conditions, you'd need to retrieve the returned data and any errors. That's exactly what channels allow you to do — the subject of part 2.

What we've learned

go myFunction() launches a goroutine — the following code executes immediately without waiting
main() returning kills all running goroutines, without exception
sync.WaitGroup is the right tool for waiting for a set of goroutines to complete
defer wg.Done() guarantees the counter is decremented even on error
In a loop, always pass the loop variable as a parameter to the goroutine, never capture it directly
go run -race detects race conditions — use it in development and CI

In part 2, we'll see how to retrieve results and errors from these goroutines using channels, and how to build a worker pool that limits the number of goroutines running in parallel — because launching 10,000 goroutines all at once is also a great way to bring a server down.

📄 Associated CLAUDE.md

View • Download • Catalogue

Concurrency vs parallelism in Go: applied to Event Sourcing and CQRS

Odilon HUGONNOT — Fri, 10 Apr 2026 09:00:02 +0000

Rob Pike said in 2012: "Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once." Everyone nods at the conference. Nobody asks a question. And then you go home and still have no idea what it actually changes in your code.

This article starts from scratch: what the difference is, how Go expresses it with goroutines and channels, and why it matters as soon as you start working with architectures like Event Sourcing or CQRS. No advanced Go knowledge required.

The difference with a cooking analogy

Imagine a single chef preparing ten dishes at once. He starts the risotto, sears the scallops, checks on the sauce, comes back to the risotto. He only does one thing at a time — but he manages ten things by juggling his attention. That's concurrency.

Now put ten chefs in the same kitchen. Ten dishes are cooking physically at the same time, each at their own station. That's parallelism.

The difference in one sentence:

Concurrency = managing multiple tasks by alternating between them (even on a single core)
Parallelism = executing multiple tasks truly at the same time (multiple cores)

A concurrent program can run perfectly well on a single core — it just gives the illusion of doing several things at once because it switches quickly. Parallelism, on the other hand, requires real multi-core hardware.

Goroutines: Go's take on concurrency

In Go, the basic primitive for concurrency is the goroutine. Think of it as a lightweight thread, managed by Go rather than the operating system. You launch one with the go keyword in front of a function call:

package main

import (
    "fmt"
    "time"
)

func sayHello(name string) {
    fmt.Println("Hello", name)
}

func main() {
    go sayHello("Alice") // launched in the background
    go sayHello("Bob")   // launched in the background
    go sayHello("Charlie")

    time.Sleep(100 * time.Millisecond) // wait for goroutines to finish
    fmt.Println("Everyone said hello")
}

The three calls run concurrently. The order of output is not guaranteed — Go decides who goes first. On a multi-core machine, they may even run truly simultaneously (parallelism).

Why goroutines instead of classic threads? Because a goroutine starts with ~2 KB of memory, versus 1 to 8 MB for an OS thread. You can launch 100,000 goroutines without breaking a sweat. 100,000 threads, and your machine cries.

Channels: how goroutines talk to each other

The problem with concurrency: how do you share data between tasks without breaking everything? Go answers with channels — pipes through which goroutines send each other values.

package main

import "fmt"

func calculate(a, b int, result chan<- int) {
    result <- a + b // sends the result into the channel
}

func main() {
    ch := make(chan int) // creates a channel that carries ints

    go calculate(3, 4, ch) // runs the calculation in the background
    go calculate(10, 20, ch)

    r1 := <-ch // waits and receives the first result
    r2 := <-ch // waits and receives the second

    fmt.Println(r1, r2) // 7 and 30, in some order
}

The golden rule of channels: it's the sender (the producer) that closes the channel, not the receiver. Closing a channel from the receiver side is a classic mistake that crashes the program.

Event Sourcing and CQRS — a quick refresher

Before applying concurrency, a quick recap of these two patterns, because the names sound scarier than they are.

Event Sourcing: instead of storing the current state of a piece of data (balance = $150), you store all the events that led to that state (account created → deposit $200 → withdrawal $50). The current state is recomputed by replaying events in order.

CQRS (Command Query Responsibility Segregation): you separate write operations (Commands, which modify state) from read operations (Queries, which read state). Two separate paths, two separate models.

These two patterns work very well together — and their structure is naturally asymmetric: writes require ordering, reads can be done in parallel. That's exactly where the concurrency/parallelism distinction becomes concrete.

Writes: one queue per account

Let's take a simple example: a banking system in Event Sourcing. An account has a balance. You can make a deposit or a withdrawal. The business rule: the balance cannot go below zero.

Problem: if two withdrawals arrive at the same time on the same account, both check the balance at the same time (say $100), both see it's fine, both debit $80 — and the balance ends up at -$60. That's a race condition.

Go solution: one channel per account. All commands on the same account go through that channel and are processed one at a time. Meanwhile, other accounts process their commands in parallel — they have their own channel and their own goroutine.

package main

import (
    "fmt"
    "sync"
)

// Account manages its state and its command queue
type Account struct {
    id       string
    balance  float64
    commands chan Command
}

type Command struct {
    amount   float64
    response chan error
}

// NewAccount creates an account and starts its processing goroutine
func NewAccount(id string, initialBalance float64) *Account {
    a := &Account{
        id:       id,
        balance:  initialBalance,
        commands: make(chan Command, 10),
    }
    go a.process() // a single goroutine processes commands for this account
    return a
}

// process reads commands one by one — no race condition possible
func (a *Account) process() {
    for cmd := range a.commands {
        if a.balance+cmd.amount < 0 {
            cmd.response <- fmt.Errorf("insufficient balance (%.2f)", a.balance)
            continue
        }
        a.balance += cmd.amount
        cmd.response <- nil
    }
}

// Debit sends a command and waits for the response
func (a *Account) Debit(amount float64) error {
    resp := make(chan error, 1)
    a.commands <- Command{amount: -amount, response: resp}
    return <-resp
}

func main() {
    account := NewAccount("A001", 100)

    var wg sync.WaitGroup

    // 5 withdrawals of 30 arrive at the same time
    for i := range 5 {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            err := account.Debit(30)
            if err != nil {
                fmt.Printf("Withdrawal %d refused: %v\n", n, err)
            } else {
                fmt.Printf("Withdrawal %d OK\n", n)
            }
        }(i)
    }

    wg.Wait()
}

What happens: all 5 goroutines send their command into the channel, but the process() goroutine picks them up one by one. The first ones succeed ($100 → $70 → $40), the later ones are refused. No race condition, no complex mutex.

That's the beauty of the approach: concurrency between goroutines is total (each account has its own goroutine, 1000 accounts run in parallel), but serialization within an account is guaranteed by the channel.

Reads: everything in parallel

On the CQRS side, Queries read data. They modify nothing — no risk of corrupting state. So they can be launched in parallel without restriction.

In Event Sourcing, projections are views computed from events. For example: "the balance of all accounts" is a projection. "The list of the last 10 transactions" is another. These projections are built by replaying events — and each one can do so in its own goroutine, independently of the others.

package main

import (
    "fmt"
    "log/slog"
    "sync"
)

type Event struct {
    AccountID string
    Amount    float64
    Type      string
}

type Projection interface {
    Name() string
    Handle(e Event) error
}

// PublishEvent sends an event to all projections in parallel.
// If one projection fails, the others continue.
func PublishEvent(evt Event, projections []Projection) {
    var wg sync.WaitGroup

    for _, p := range projections {
        wg.Add(1)
        go func(proj Projection) {
            defer wg.Done()
            if err := proj.Handle(evt); err != nil {
                slog.Error("projection failed",
                    "projection", proj.Name(),
                    "error", err,
                )
                // Continue — a failing projection doesn't block the others
            }
        }(p)
    }

    wg.Wait() // wait for all projections to have processed the event
}

func main() {
    evt := Event{AccountID: "A001", Amount: 50, Type: "deposit"}
    fmt.Printf("Event published: %+v\n", evt)
    // PublishEvent(evt, []Projection{balancesProj, historyProj, statsProj})
}

In practice, if you have 3 projections (balances, history, stats) and each takes 20ms to process an event, the sequential version takes 60ms. The parallel version takes 20ms. At high event volumes, this matters.

The classic pitfall: two goroutines created for the same account

A subtle issue worth knowing: if you store your accounts in a map (map[string]*Account), two requests arriving simultaneously for an account that doesn't exist yet may create two different instances of the same account. Both goroutines work on different states — and you lose events.

Fix: protect access to the map with a mutex, just for creation. Once the account is created, no more mutex needed — the channel does the work.

type Bank struct {
    mu       sync.Mutex
    accounts map[string]*Account
}

func (b *Bank) GetOrCreate(id string) *Account {
    b.mu.Lock()
    defer b.mu.Unlock()

    if a, ok := b.accounts[id]; ok {
        return a // already exists, return the same one
    }

    // Create only once, protected by the mutex
    a := NewAccount(id, 0)
    b.accounts[id] = a
    return a
}

Summary

Key takeaways:

Concurrency = managing multiple tasks by alternating. Go: goroutines + channels.
Parallelism = executing multiple tasks at the same time. Go: multiple goroutines on multiple cores.
Event Sourcing on the write side: one channel per aggregate → guaranteed sequential processing, no race condition.
CQRS on the read side: multiple projections in parallel goroutines → reads without ordering constraints.
Channel rule: the producer closes, never the consumer.

These two patterns are often presented as complex because they come loaded with jargon. The reality: they are solutions to very concrete problems (how to write without corrupting state, how to read fast). Go provides the primitives to implement them cleanly — goroutines for concurrency, channels for coordination.

📄 Associated CLAUDE.md

View • Download • Catalogue

Designing a safe error handling package in Go: safe by default

Odilon HUGONNOT — Thu, 09 Apr 2026 09:00:03 +0000

Error handling in Go is simple. Sometimes too simple. A fmt.Errorf("pq: no rows in result set") bubbling up to an HTTP handler, and suddenly SQL internals are exposed in a 500 response. No exotic vulnerability required — just an err.Error() in the wrong place.

This problem is systemic. It doesn't stem from a lack of discipline, but from the absence of a boundary in the type system. Nothing in the error interface distinguishes what is safe to expose from what is not.

The concrete problem

Here is the classic leak pattern. A handler that serves err.Error() directly in its JSON response, and a repository layer that wraps errors with technical context:

// HTTP handler
func (h *Handler) GetOrder(c echo.Context) error {
    order, err := h.service.FindByID(ctx, id)
    if err != nil {
        return c.JSON(http.StatusInternalServerError, map[string]string{
            "error": err.Error(), // ← LEAK
        })
    }
    return c.JSON(http.StatusOK, order)
}

// repository layer
func (r *Repo) FindByID(ctx context.Context, id string) (*Order, error) {
    var o Order
    err := r.db.GetContext(ctx, &o, "SELECT * FROM orders WHERE id = $1", id)
    if err != nil {
        return nil, fmt.Errorf("orders.FindByID: %w", err) // standard wrapping
    }
    return &o, nil
}

Response received by the client:

{"error": "orders.FindByID: pq: no rows in result set"}

The table name, PostgreSQL driver, and nature of the SQL error are publicly exposed. Not catastrophic in isolation — but exactly the kind of information an attacker uses to refine an injection or target an attack surface.

What existing solutions offer (and their limits)

Solution

Approach

Limitation

cockroachdb/errors

Exhaustive package, stack traces, rich wrapping

~15k lines, 8 sub-packages. Disproportionate for a business microservice.

upspin pattern (Rob Pike)

Error type with Kind, Op, Err

Pre-Go 1.13, no slog, and errors.Is() traverses the full chain.

hashicorp pattern

UserError interface with GetMessage()

Relies on developer discipline, not the type system.

The real question: can we design a type where err.Error() always returns something safe, without any convention to remember?

The safeerr design

Five principles structure the package:

Safe by default: Error() returns only the user-facing message.
No Unwrap(): the introspection chain is intentionally broken. errors.Is() never traverses the internal cause. A deliberate security choice.
slog.LogValuer: technical details are exposed only through structured logs.
Immutable builder pattern: WithMsg(), WrapCause() always return a new instance — sentinels are never mutated.
Centralized HTTP mapping: a single point maps ErrorKind values to HTTP status codes.

The sentinels

var (
    ErrNotFound     = New("NOT_FOUND",     KindNotFound,     http.StatusNotFound,            "not found")
    ErrUnauthorized = New("UNAUTHORIZED",  KindUnauthorized, http.StatusUnauthorized,        "unauthorized")
    ErrInvalidInput = New("INVALID_INPUT", KindInvalidInput, http.StatusUnprocessableEntity, "invalid input")
    ErrInvalidState = New("INVALID_STATE", KindInvalidState, http.StatusConflict,            "invalid state")
    ErrInternal     = New("INTERNAL",      KindInternal,     http.StatusInternalServerError, "internal error")
)

The immutable builder pattern

func (e *AppErr) WithMsg(msg string) *AppErr {
    return &AppErr{code: e.code, kind: e.kind, status: e.status, msg: msg, cause: e.cause}
}

func (e *AppErr) WrapCause(cause error, msg string) *AppErr {
    return &AppErr{code: e.code, kind: e.kind, status: e.status, msg: msg, cause: cause}
}

Each call creates a new instance. Sentinels declared as var are never modified — no risk of shared mutation across goroutines.

slog.LogValuer

func (e *AppErr) LogValue() slog.Value {
    attrs := []slog.Attr{
        slog.String("code", e.code),
        slog.String("msg", e.msg),
    }
    if e.cause != nil {
        attrs = append(attrs, slog.String("cause", e.cause.Error()))
    }
    return slog.GroupValue(attrs...)
}

Resulting log:

level=ERROR msg="order processing failed" err.code=NOT_FOUND err.msg="order not found" err.cause="pq: no rows in result set"

Technical details — driver, query, table — remain in the logs. Never in the HTTP response.

Centralized HTTP mapping

func Error(c echo.Context, err error) error {
    var appErr *safeerr.AppErr
    if errors.As(err, &appErr) {
        return c.JSON(appErr.Status(), map[string]string{
            "error": appErr.Error(),
        })
    }
    slog.Error("unhandled error reaching handler", "err", err)
    return c.JSON(http.StatusInternalServerError, map[string]string{"error": "internal error"})
}

A single place in the codebase knows how to translate an error into an HTTP response. If an untyped error reaches this point, it is logged and returns a generic message.

Before / after

Before — technical errors bubble up raw to the handler:

// service — raw technical error propagated
func (s *Service) ProcessOrder(ctx context.Context, cmd ProcessOrderCmd) error {
    order, err := s.repo.FindOrder(ctx, cmd.OrderID)
    if err != nil {
        return fmt.Errorf("FindOrder: %w", err)
    }
    if order.ContractRef == "" {
        return errors.New("order has no contract reference")
    }
    return nil
}

After — explicit conversion at the service boundary:

// service — explicit conversion at the boundary
func (s *Service) ProcessOrder(ctx context.Context, cmd ProcessOrderCmd) error {
    order, err := s.repo.FindOrder(ctx, cmd.OrderID)
    if err != nil {
        return safeerr.ErrNotFound.WrapCause(err, "order not found")
    }
    if order.ContractRef == "" {
        return safeerr.ErrInvalidState.WithMsg("order has no contract reference")
    }
    return nil
}

// handler
func (h *Handler) ProcessOrder(c echo.Context) error {
    if err := h.service.ProcessOrder(ctx, cmd); err != nil {
        return render.Error(c, err)
    }
    return c.JSON(http.StatusOK, nil)
}

HTTP response: {"error": "order not found"} — the SQL cause stays in the logs, never in the response.

The full package (~130 lines)

package safeerr

import "log/slog"

type ErrorKind int

const (
    KindNotFound ErrorKind = iota
    KindUnauthorized
    KindForbidden
    KindInvalidInput
    KindInvalidState
    KindConflict
    KindInternal
)

type AppErr struct {
    code   string
    kind   ErrorKind
    status int
    msg    string
    cause  error
}

func New(code string, kind ErrorKind, status int, msg string) *AppErr {
    return &AppErr{code: code, kind: kind, status: status, msg: msg}
}

func (e *AppErr) Error() string   { return e.msg }
func (e *AppErr) Code() string    { return e.code }
func (e *AppErr) Kind() ErrorKind { return e.kind }
func (e *AppErr) Status() int     { return e.status }
func (e *AppErr) Cause() error    { return e.cause }

func (e *AppErr) WithMsg(msg string) *AppErr {
    return &AppErr{code: e.code, kind: e.kind, status: e.status, msg: msg, cause: e.cause}
}

func (e *AppErr) WrapCause(cause error, msg string) *AppErr {
    return &AppErr{code: e.code, kind: e.kind, status: e.status, msg: msg, cause: cause}
}

func (e *AppErr) WithCause(cause error) *AppErr {
    return &AppErr{code: e.code, kind: e.kind, status: e.status, msg: e.msg, cause: cause}
}

func (e *AppErr) LogValue() slog.Value {
    attrs := []slog.Attr{
        slog.String("code", e.code),
        slog.String("msg", e.msg),
    }
    if e.cause != nil {
        attrs = append(attrs, slog.String("cause", e.cause.Error()))
    }
    return slog.GroupValue(attrs...)
}

Honest trade-offs

No stack traces. AppErr does not capture the goroutine stack. Structured logs with business context compensate in most cases, but for deep post-mortem debugging this is a real limitation.
WrapCause can leak if misused. WrapCause(err, err.Error()) breaks the safety guarantee — the user-facing message becomes the technical one. Discipline is still required on this specific point.
The conversion cost. Every technical error must be converted to an AppErr at the service boundary. This is intentional friction — on a project with a hundred error sites, that's code to write and maintain.
errors.Is() no longer works on the cause. If an upper layer wants to test errors.Is(err, sql.ErrNoRows), it cannot. Acceptable if the sentinel taxonomy is expressive enough, problematic otherwise.

Conclusion

The real value of this package is not in the 130 lines. It's in the boundary it makes explicit between what is safe to expose and what is not. That boundary already existed in any well-designed application — but it relied on discipline, on documented conventions, on careful reviews.

Moving this constraint into the type system has a cost: explicit conversion at every boundary. In return: an accidental err.Error() in an HTTP response never leaks anything, regardless of who wrote the code.

For an internal library shared across multiple microservices in the same stack, it's an investment that pays off quickly.

Synchronous, asynchronous, concurrent, parallel: the 4 concepts explained in Go

Odilon HUGONNOT — Wed, 08 Apr 2026 09:00:02 +0000

These four words show up everywhere in docs, articles, and interviews. And they get mixed up constantly — including by experienced developers. "Asynchronous" and "concurrent" don't mean the same thing. "Parallel" and "concurrent" don't either. And a program can be all four at once, or only two, and that changes what it actually does.

This article completes the previous one on concurrency and parallelism by adding the synchronous/asynchronous dimension, and showing how all four concepts fit together in Go.

Synchronous vs asynchronous: a question of waiting

These two words are not about "how many tasks are running at the same time". They're about what your code does while it's waiting for a response.

Synchronous: you send a request, you stop and wait for the response before doing anything else. Like calling someone on the phone and staying silent until they answer.

Asynchronous: you send a request, you keep doing other things, and you handle the response when it arrives. Like sending a text message — you put your phone down and get on with your life.

package main

import (
    "fmt"
    "time"
)

func callAPI() string {
    time.Sleep(200 * time.Millisecond) // simulates a network request
    return "result"
}

func synchronous() {
    // We wait. We do nothing else for 200ms.
    result := callAPI()
    fmt.Println("synchronous:", result)
}

func asynchronous() {
    ch := make(chan string, 1)

    // We launch the call, we don't wait
    go func() {
        ch <- callAPI()
    }()

    // We can do other things here while the call is in progress
    fmt.Println("asynchronous: doing other things while the call runs...")

    // We retrieve the result when we need it
    result := <-ch
    fmt.Println("asynchronous: result received:", result)
}

The synchronous version blocks for 200ms. The asynchronous version keeps working during that time. In an application making 1000 network calls per second, the difference is massive.

Concurrent vs parallel: a question of cores

These two words don't talk about "how code waits". They talk about how many tasks are actually running at the same time.

Concurrent: multiple tasks make progress at the same time, but on a single core. The CPU juggles between them — it advances one a bit, switches to another, comes back. Like a single chef watching three pots at once: only doing one thing at a time, but everything moves forward.

Parallel: multiple tasks run truly at the same time, on multiple cores. Like three chefs, each at their own stove. Real simultaneous execution, not juggling.

Concurrency is a matter of structure (how the code is organized). Parallelism is a matter of hardware (how many cores are available). A concurrent program can run in parallel on a multi-core machine, or sequentially on a single-core — without changing a single line of code.

The four possible combinations

What makes things confusing is that synchronous/asynchronous and concurrent/parallel are two independent axes. A program can be any combination of the two:

Synchronous

Asynchronous

Sequential

Classic bash script

Node.js (1 thread, callbacks)

Concurrent

Goroutines blocking on channels

Goroutines with non-blocking I/O

Parallel

Threads waiting for their results

Go in production: goroutines on multiple cores

Node.js is a perfect example of asynchronous but sequential code: a single thread, but it never blocks — it delegates I/O and resumes when ready via the event loop. Go does it differently: it is concurrent and can be parallel, and lets the developer choose whether an operation is synchronous or asynchronous.

Go: synchronous on the surface, asynchronous under the hood

This is one of Go's strengths that is often misunderstood. When you write an HTTP request in Go, it looks like synchronous code:

// This looks like "we're waiting" — but Go doesn't block the OS thread
resp, err := http.Get("https://api.example.com/data")
if err != nil {
    return err
}
defer resp.Body.Close()

In reality, when this goroutine is waiting for the network response, the Go runtime pauses it and uses the OS thread to advance other goroutines. You write code that reads like synchronous, but behaves like asynchronous. It's the best of both worlds: no callback hell, no async/await everywhere, but no blocked thread either.

Compare with the same pattern in JavaScript:

// JavaScript: forced to write asynchronism explicitly
const resp = await fetch('https://api.example.com/data')
const data = await resp.json()

In JS, the await is necessary to avoid blocking the single thread. In Go, you don't have to think about it — the goroutine "freezes" on its own during I/O and the OS thread stays available.

Concurrency within parallelism: both at the same time

A Go program in production is often concurrent AND parallel at the same time. Here's how the two coexist:

You have 8 cores on the machine → Go uses 8 OS threads (GOMAXPROCS=8)
You have 10,000 goroutines → Go distributes them across the 8 threads
Each thread does concurrency: it alternates between multiple goroutines
The 8 threads together do parallelism: they run truly at the same time

package main

import (
    "fmt"
    "runtime"
    "sync"
)

func main() {
    fmt.Printf("Available cores: %d\n", runtime.NumCPU())
    fmt.Printf("Threads used (GOMAXPROCS): %d\n", runtime.GOMAXPROCS(0))

    var wg sync.WaitGroup
    results := make(chan int, 1000)

    // 1000 goroutines launched — concurrency + parallelism simultaneously
    // Go distributes them across available threads
    for i := range 1000 {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            results <- n * n // computed in parallel across multiple cores
        }(i)
    }

    go func() {
        wg.Wait()
        close(results)
    }()

    total := 0
    for r := range results {
        total += r
    }
    fmt.Println("Sum of squares:", total)
}

On an 8-core machine: the 1000 goroutines are distributed across 8 threads. Each thread alternates between ~125 goroutines (concurrency). The 8 threads run at the same time (parallelism). Result: 1000 calculations processed much faster than sequentially.

When to use what in Go?

In practice, here's how to choose:

Sequential synchronous — the default. Script, simple processing, business logic without I/O. Readable, predictable, nothing to manage.

// Sequential synchronous — simple and sufficient
func processOrder(cmd Command) error {
    if err := validate(cmd); err != nil {
        return err
    }
    if err := save(cmd); err != nil {
        return err
    }
    return notify(cmd)
}

Concurrent asynchronous — when you're making multiple independent I/O calls (multiple APIs, multiple DB queries). Launch them in parallel, collect the results.

// Concurrent asynchronous — 3 parallel calls instead of sequential
func fetchData(ctx context.Context, id string) (Result, error) {
    chUser := make(chan User, 1)
    chOrders := make(chan []Order, 1)
    chStats := make(chan Stats, 1)

    go func() { chUser <- getUser(ctx, id) }()
    go func() { chOrders <- getOrders(ctx, id) }()
    go func() { chStats <- getStats(ctx, id) }()

    // All 3 calls run at the same time
    // Total time = max(user time, orders time, stats time)
    // instead of sum(user time + orders time + stats time)
    return Result{
        User:   <-chUser,
        Orders: <-chOrders,
        Stats:  <-chStats,
    }, nil
}

Worker pool — when you have many similar tasks and want to control the load. Not 10,000 simultaneous goroutines, but N workers pulling from a queue.

// Worker pool: N goroutines process M tasks
func processInParallel(tasks []Task, numWorkers int) {
    queue := make(chan Task, len(tasks))
    for _, t := range tasks {
        queue <- t
    }
    close(queue)

    var wg sync.WaitGroup
    for range numWorkers {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for t := range queue {
                process(t) // each worker takes one task at a time
            }
        }()
    }
    wg.Wait()
}

The summary as a mental model

To never mix up the four concepts again:

Synchronous/Asynchronous = do I wait for the result before continuing? Yes → synchronous. No, I continue and retrieve it later → asynchronous.
Sequential/Concurrent = am I handling multiple tasks at the same time? No, one after the other → sequential. Yes, I alternate → concurrent.
Sequential/Parallel = are multiple tasks physically executing at the same time on multiple cores? No → sequential. Yes → parallel.

Go makes all of this relatively transparent: you launch a goroutine, Go decides whether it runs concurrently on one thread or in parallel on several. You write code that looks synchronous, Go handles the asynchronism under the hood during I/O. That's why Go is pleasant to write for these kinds of problems — you think about the logic, not the thread plumbing.

📄 Associated CLAUDE.md

View • Download • Catalogue

Which language for which project? PHP, Go, Python, JS — a pragmatic guide

Odilon HUGONNOT — Tue, 07 Apr 2026 09:00:01 +0000

The question comes up at every new project kickoff: "what are we building this in?" More often than not, the answer is driven by what the team already knows, or by whatever is trending on HackerNews this month. Neither is a particularly good method. I've seen a CRM written in Rust because the CTO watched a conference talk, a high-traffic API built in PHP because "that's what we've always done", and a data pipeline in Node.js because the front-end team refused to learn anything else. All three were the wrong call. Here's a more pragmatic framework — no evangelism included.

PHP: misunderstood and underrated

PHP carries a reputation built on the internet of 2005 to 2012. The problem is that its reputation froze in time while the language kept evolving. PHP 8.x ships with optional strong typing, native attributes, named arguments, enums, fibers, and JIT compilation. It's not the same language that made "PHP bad" jokes go viral.

For a classic web application, a REST API, an e-commerce platform, a business application built on Symfony or Laravel — PHP is often the most pragmatic choice available. Hosting is cheap (any shared server runs PHP out of the box), the developer pool is large, documentation is exhaustive, and the ecosystem is mature. A junior dev can be productive on a well-structured Symfony project in two weeks. Try making that claim for Go or Rust.

PHP's real weaknesses are structural: it's single-threaded by nature and not designed for real-time or CPU-intensive workloads. If you need persistent WebSockets, on-the-fly video processing, or an API that needs to handle 50,000 concurrent connections on a single server — PHP is the wrong tool. But for 80% of standard web projects, it's the rational choice that gets dismissed too quickly because it isn't exciting.

JavaScript: the Swiss army knife that doesn't always cut clean

JavaScript is non-negotiable on the front-end — that's not even a question. React, Vue, Svelte, the DOM, Web APIs: all of it runs in JS. The real debate is on the back-end, with Node.js.

The strongest argument for Node.js is code sharing between front-end and back-end. When you're building with Next.js or Nuxt, you write validation logic, types, and utilities once and use them on both sides. That's a real, tangible gain — not marketing. The second argument is serverless: Lambda functions, Vercel, Cloudflare Workers — the whole serverless ecosystem is designed with JavaScript as the first-class citizen.

The dark side: Node.js is still single-threaded from a CPU standpoint. The event loop handles concurrent I/O extremely well, but as soon as something blocks the thread — heavy computation, image processing, compression — everyone waits. And the npm ecosystem, despite years of improvement, remains a minefield: sketchy transitive dependencies, abandoned packages, version incompatibilities. TypeScript significantly improves long-term maintainability, but it's an added layer of complexity on top of an already complex stack.

If your project has no JavaScript front-end, choosing Node.js for the API because "the team knows JS" deserves serious pushback. Familiarity alone is not a good enough reason.

Go: boring, and that's a compliment

Go is probably the language I hear least about in hype-driven conversations, and yet it's the one I reach for most when building things that need to work reliably in production without waking me up at night. That contradiction says something.

Go is boring in the right way: no magic, no ten different ways to write the same thing, no obscure meta-programming. When you come back to Go code six months later, you read it the same way you wrote it. Concurrency is baked into the language through goroutines and channels — not a third-party library, not a pattern you need to remember, it's in the spec. For microservices, high-traffic APIs, CLI tools, and DevOps tooling, Go is hard to beat on the performance-to-code-simplicity ratio.

But honestly: Go is verbose. The repetitive if err != nil error handling is a well-known pain point. The library ecosystem is thinner than Python or JavaScript. And most importantly: for a simple CRUD app, a site with 100 visitors a day, or a two-week prototype, using Go is clear over-engineering. Go shines when long-term performance, maintainability, and load resilience genuinely matter — not when you're testing an idea before you know if anyone will use it.

Python: the undisputed choice for anything data-related

For data science, machine learning, and AI, the conversation is short: it's Python, and that's not changing anytime soon. NumPy, Pandas, scikit-learn, PyTorch, TensorFlow, Hugging Face — the Python data ecosystem has a decade-long head start on everything else. If someone suggests doing ML in Go "for the performance", that's almost always the wrong call.

Python is also excellent for scripting, automation, and rapid prototyping. The syntax is readable, the standard library is rich, and you can move fast. FastAPI, released in 2018, has become a reference point for lightweight APIs with automatic validation and generated documentation — it's excellent for exposing ML models or building internal services.

Where it gets complicated is in complex business web applications. Django is solid, but the PHP/Symfony ecosystem is more mature for e-commerce platforms, ERPs, and projects with deep business logic and large teams. Python also has a structural weakness: typing is loose by default. Mypy and type hints have dramatically improved the situation, but you have to actively choose to type your code well. Performance is also a limitation — CPython is slow for CPU-bound operations outside of libraries written in C.

Rust and the rest: for the extreme cases

Rust deserves a mention because it's the only language that delivers near-C performance with memory safety guaranteed at compile time. For compilers, rendering engines, WebAssembly, ultra-performant CLI tools (ripgrep, exa, Zed) — Rust is in a category of its own.

The reality for 95% of projects: the learning curve is real and expensive. The borrow checker is a genuine innovation, but it takes weeks before you stop fighting it. If your deadline is in three months and your team doesn't know Rust, now is not the time to learn. Rust is a long-term investment that pays off when performance or memory safety are hard constraints — not nice-to-haves.

A quick note on the others: Java and Kotlin remain solid choices for large enterprises with significant teams, complex projects, and an established JVM culture (Spring, Quarkus). Hiring is easier than people think. Ruby is less fashionable than it used to be, but Rails remains a strong foundation for startups that need to move fast — that's exactly what it was built for.

Quick reference

Language

Strengths

Weaknesses

Typical project

Avoid if...

PHP

Maturity, cheap hosting, large developer pool

Reputation (unfair), single-threaded

Website, e-commerce, classic REST API

Real-time, high performance

JavaScript / Node

Front/back code sharing, npm ecosystem, serverless

npm chaos, CPU single-thread

Full-stack JS, SPA, real-time

Pure API with no JS front-end

Performance, native concurrency, long-term readability

Verbose, thinner library ecosystem

Microservices, CLI tools, high-traffic APIs

Prototyping, data science

Python

Unmatched for AI/data, fast prototyping

Performance, loose typing by default

ML, scripting, automation, lightweight APIs

Mobile, front-end

Rust

Maximum performance, memory safety

Steep learning curve

Systems, WASM, critical tooling

Projects with tight deadlines

Conclusion

The real problem isn't picking the "best" language — it's resisting two opposite temptations: the hype language you've been wanting to try, and the familiar language you apply everywhere by default because it's comfortable. The right question isn't "is Go better than PHP" — that question has no general answer. The right question is: "does the performance gain justify the recruiting cost and onboarding overhead on this specific project, with this specific team, in this specific timeframe?"

A team of three senior PHP developers who know Symfony inside-out will ship more in six months in PHP than in Go where they're starting from scratch. That's obvious when you say it out loud, but it gets lost surprisingly often in the heat of a technical decision. The best language is usually the one your team can still maintain in two years — not the one that tops the benchmarks.

Learning Go in 2026: the honest guide for experienced developers

Odilon HUGONNOT — Mon, 06 Apr 2026 09:00:02 +0000

A few years ago, I opened a Go project for the first time. My initial reaction: "Why are there no classes? Why do I have to write if err != nil everywhere? Why is the compiler yelling at me for importing a package without using it?"

Three weeks later, I was debugging a production problem and realized I understood exactly what the code was doing, line by line, without surprises. No magic, no mysterious middleware, no implicit behavior. That's when I understood why Go is designed the way it is.

This article is the guide I wish I'd read when I started. Not the official docs paraphrased — real advice, real resources, and what goes through your head when coming from another language.

Why Go in 2026

Forget the marketing pitch "Go is fast, Go is concurrent, Google made it". That's not why you adopt Go.

Go is boring. And that's its strength. A language where you open a file you've never seen, written by someone else, and you understand what it does in 30 seconds. No meta-programming. Not 15 ways to do the same thing. No DSL embedded in a DSL. No magic decorators that transform class behavior at runtime.

After years of PHP/Symfony with its 200 DI classes, or Node.js with 47 dependencies in node_modules, or Python where every project has its own unspoken conventions — Go is liberating. Go code looks like Go code. Regardless of who wrote it.

In practice in 2026: Go dominates infrastructure (Kubernetes, Docker, Terraform, Prometheus are all written in Go), high-performance APIs, backend services that need serious concurrency, and CLIs. If you work in this space, learning Go is a good investment.

1. Resources that actually work

There's a lot of Go content on the internet. Most of it is either too basic or poorly done. Here's what's actually worth your time.

The essentials

A Tour of Go — The official entry point. Interactive, well structured, 2-3 hours if done seriously. Do the whole thing, not diagonally. Every exercise is there for a reason.

Go by Example — Every language concept illustrated with minimal, working code. Perfect as a quick reference after the Tour, when you're wondering "how do you do a channel with timeout in Go again?".

Effective Go — The most important document that exists on Go. This is the philosophy of the language. Not just the syntax — why interfaces are implicit, how to think about composition, why errors are values. Read it once at the start (you'll understand 50%), then re-read it after 2-3 months (you'll understand everything). Really.

The official Go blog — In-depth articles, written by the language creators. A few must-reads: "Go Concurrency Patterns", "Error handling and Go", "Go Slices: usage and internals", "The Go Memory Model". Not to read all at once — bookmark them and read when the topic becomes relevant.

Books worth their price

Let's Go by Alex Edwards — The best book for building a real web application in Go. Paid, but it's the most worthwhile investment on this list. It explains production patterns: middleware, sessions, CSRF, integration tests, deployment. Not toy code. And for those on a tight budget: a quick search on GitHub can turn up the PDF without much difficulty. But if you can afford it, pay for it — Alex Edwards' work deserves it.

Learning Go by Jon Bodner (O'Reilly) — Good choice if you come from an object-oriented language and want to understand the "why" behind Go's design choices. Less web-focused, more focused on language fundamentals.

What people often overlook: the stdlib

In Go, the standard library is incredibly complete. net/http, encoding/json, database/sql, testing, context, sync, io... Before looking for an external dependency, check if the stdlib already does the job. 90% of the time, it does.

What's a waste of time

YouTube tutorials "Build a REST API in Go in 30 minutes" — often bad practices, no error handling, incomprehensible architectures. Udemy courses — too slow for an experienced dev, often outdated. Trying to learn Go by reading Kubernetes source code — that's like learning English by reading Shakespeare. Technically correct, but not the right entry point.

2. The 5 mental shifts to make quickly

These are the things that surprise you most when coming from another language. Better to identify and accept them upfront rather than spend two weeks fighting the language.

There are no classes

Go has structs and methods on those structs. No inheritance. Composition replaces inheritance. At first it's frustrating, later you understand why it's better.

// No "Animal" class with an inherited "Speak" method on "Dog"
// Instead: composition via embedding

type Animal struct {
    Name string
}

func (a Animal) Describe() string {
    return "I am " + a.Name
}

type Dog struct {
    Animal        // Embedding: Dog "inherits" Animal's methods
    Breed string
}

// Dog now has the Describe() method without declaring anything
d := Dog{Animal: Animal{Name: "Rex"}, Breed: "Labrador"}
fmt.Println(d.Describe()) // "I am Rex"

Errors are values, not exceptions

The famous if err != nil. Yes, it's verbose. No, there's no try/catch. It's a design choice: every error is handled explicitly at the point where it occurs. After a few weeks in production, you realize you have far fewer surprises. The error doesn't silently bubble up the call stack to explode somewhere else.

The standard pattern for wrapping errors with context:

func getUser(ctx context.Context, id string) (*User, error) {
    row := db.QueryRowContext(ctx, "SELECT id, name FROM users WHERE id = $1", id)

    var u User
    if err := row.Scan(&u.ID, &u.Name); err != nil {
        return nil, fmt.Errorf("getUser %s: %w", id, err)
        // %w allows unwrapping the error later with errors.Is() / errors.As()
    }
    return &u, nil
}

Each layer adds context with fmt.Errorf("context: %w", err). In the end, the error message reads like a trace: "handler > service > store > SQL error".

Interfaces are implicit

No need to declare implements. If a type has the right methods, it satisfies the interface automatically. This is the most powerful concept in Go and the most confusing at first.

// The io.Reader interface from the stdlib:
type Reader interface {
    Read(p []byte) (n int, err error)
}

// An os.File satisfies Reader.
// A bytes.Buffer satisfies Reader.
// A net.Conn satisfies Reader.
// Your own struct satisfies Reader if it has the Read method.
// No "implements" declaration anywhere.

func processData(r io.Reader) error {
    // This function accepts anything that knows how to read
    data, err := io.ReadAll(r)
    // ...
}

// Usable with a file, a buffer, a network connection, a test mock...
// Without changing a single line of processData.

Formatting is not a debate

gofmt formats the code. Period. No config, no options, no tabs vs spaces war. All Go projects have the same style. It's liberating. Configure the VS Code extension to format on save and never think about it again.

go fmt ./...
# Formats all project files. Nothing to configure.

Generics exist, but sparingly

Generics arrived in Go 1.18 (2022). The community uses them sparingly. The Go philosophy: if you can do without generics, do without. Interfaces and the any type are sufficient for 90% of cases. Don't start with generics. Learn the basics, build something that works, and introduce generics when you have a real need for them.

3. Tooling — What makes Go pleasant from day one

Go has the best built-in tooling of any language I know. Everything is in the standard distribution.

go run main.go          # Compiles and runs in one command
go build ./...          # Produces a static binary. A single file.
go test ./...           # Runs all tests. Testing built-in, no external framework.
go fmt ./...            # Formats all code
go vet ./...            # Basic static analysis
go mod init my/module   # Initializes a module
go mod tidy             # Syncs go.mod and go.sum with actual imports

The binary produced by go build is static. A single file, no runtime, no dependencies. Copy the binary to a Linux server and it runs. No "do you have the right version of Python installed?".

For the development environment, two tools to install immediately:

The VS Code "Go" extension with gopls (the official LSP) — autocomplete, go to definition, rename, type inlining. Everything works out of the box after installation.
golangci-lint — The linter to install on day 1. Combines about fifty linters. golangci-lint run ./... finds real bugs, not just style issues.

4. The first project — What to build

Don't start with a gRPC microservice with Kafka and Kubernetes. Not an ultra-complex CLI. Not "I'll rewrite my PHP project in Go" — too much frustration trying to map patterns from another language into Go.

The right first project: a simple REST API with a real database. It's complete enough to touch everything that matters: structs, interfaces, packages, net/http, database/sql, JSON, error handling, middleware, and tests.

A readable and idiomatic project structure:

myapp/
├── main.go          # Entry point: initialization, wiring, server startup
├── go.mod
├── go.sum
├── handler/
│   └── user.go      # HTTP handlers: decode request, call store, encode response
├── model/
│   └── user.go      # Types: struct User, struct CreateUserRequest...
└── store/
    └── postgres.go  # DB access: SQL queries, scan into structs

A minimal but correct HTTP handler — with error handling, appropriate status codes, and clean JSON response:

type UserHandler struct {
    store UserStore
}

// UserStore is an interface defined here, on the consumer side
type UserStore interface {
    GetByID(ctx context.Context, id string) (*model.User, error)
}

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id") // Go 1.22+: patterns in http.ServeMux

    user, err := h.store.GetByID(r.Context(), id)
    if err != nil {
        if errors.Is(err, store.ErrNotFound) {
            http.Error(w, "user not found", http.StatusNotFound)
            return
        }
        // Log the internal error, don't expose it to the client
        slog.Error("GetUser failed", "id", id, "error", err)
        http.Error(w, "internal server error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    if err := json.NewEncoder(w).Encode(user); err != nil {
        slog.Error("encode response failed", "error", err)
    }
}

This isn't "advanced" code. It's idiomatic Go for a first project. Every error is handled. Internal errors are not exposed to the client. Context is propagated. This is the level to aim for from the start.

5. Pitfalls in the first weeks

These are the mistakes everyone makes. Identifying them upfront avoids a few weeks of bad habits to unlearn.

Using pointers everywhere "for performance"

No. Go passes structs by value efficiently. Pointers serve two things: modifying the receiver in a method, or avoiding copy for large structs (a few hundred bytes). By default, pass by value. Add a pointer when there's a concrete reason, not "just in case".

// Value receiver: the method doesn't modify the struct
func (u User) FullName() string {
    return u.FirstName + " " + u.LastName
}

// Pointer receiver: the method modifies the struct
func (u *User) SetEmail(email string) {
    u.Email = email
}

Creating interfaces too early

In Go, interfaces are defined on the consumer side, not the producer side. Don't create a UserService interface with 15 methods before having a second consumer that needs it. The Go principle: "Accept interfaces, return structs." Define the interface as small as possible, only for the methods the consumer actually needs.

// ❌ Too broad: who will actually use these 15 methods?
type UserService interface {
    Create(ctx context.Context, u User) error
    GetByID(ctx context.Context, id string) (*User, error)
    GetByEmail(ctx context.Context, email string) (*User, error)
    Update(ctx context.Context, u User) error
    Delete(ctx context.Context, id string) error
    // ... 10 more methods
}

// ✅ Define the minimal interface at the consumer level
type UserGetter interface {
    GetByID(ctx context.Context, id string) (*User, error)
}

// The handler only needs GetByID: that's all we expose
type UserHandler struct {
    store UserGetter
}

Importing a web framework

Gin, Echo, Fiber... The stdlib net/http with http.ServeMux (which supports patterns and HTTP methods since Go 1.22) is sufficient for 95% of use cases. For a bit more routing comfort, chi is lightweight and idiomatic. Heavy frameworks add magic and hide what Go does well on its own.

Ignoring the context package

Context is everywhere in Go: timeouts, cancellation, request-scoped values. Start using it from your first project. Every function that does I/O (database, HTTP, file) should accept a context.Context as the first parameter. It's a language convention, not an option.

// ✅ Standard pattern: ctx as first parameter for all I/O
func (s *UserStore) GetByID(ctx context.Context, id string) (*User, error) {
    var u User
    err := s.db.QueryRowContext(ctx,
        "SELECT id, name, email FROM users WHERE id = $1", id,
    ).Scan(&u.ID, &u.Name, &u.Email)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound
    }
    if err != nil {
        return nil, fmt.Errorf("store.GetByID %s: %w", id, err)
    }
    return &u, nil
}

Panicking over verbosity

Go code is longer than Python. That's normal and intentional. Every line does one clear thing. After a few weeks, you'll realize you read Go code 3x faster than equivalent Python or JavaScript, because there's no hidden implicit behavior.

6. Concurrency — When to get into it

Not yet. Seriously.

Goroutines and channels are Go's most visible feature, and the most common trap for beginners. Start by writing correct sequential code. Correct sequential code is infinitely better than buggy concurrent code. Introduce concurrency when there's a real need: parallel requests, queue processing, fan-out on API calls.

The learning order that makes sense:

Basic goroutines + channels (Go by Example covers this perfectly)
sync.WaitGroup and sync.Mutex for coordination
context for cancellation and timeouts
errgroup (golang.org/x/sync) for production patterns
The official "Go Concurrency Patterns" blog post once the basics are solid

A correct basic concurrency pattern, with context-based cancellation:

func processItems(ctx context.Context, items []Item) (int, error) {
    g, ctx := errgroup.WithContext(ctx)
    results := make(chan Result, len(items))

    for _, item := range items {
        item := item // loop variable capture (before Go 1.22)
        g.Go(func() error {
            result, err := processOne(ctx, item)
            if err != nil {
                return fmt.Errorf("item %s: %w", item.ID, err)
            }
            results <- result
            return nil
        })
    }

    // Close results when all goroutines are done
    go func() {
        g.Wait()
        close(results)
    }()

    var count int
    for range results {
        count++
    }

    return count, g.Wait()
}

7. Code organization

A few Go rules about packages that avoid bad habits:

One module = one repo. go mod init github.com/user/myproject.
One package = one directory. The package name matches the directory name.
No utils, helpers, common packages. This is a classic Go anti-pattern — these packages end up as catch-alls. Name packages by what they do: store, handler, middleware.
Exported identifiers start with a capital letter. User is public, user is private to the package. No public or private keywords.
Keep packages small and focused. A user package that handles users, not a models package that does everything.

8. Conventions that matter

Go has strong conventions. Adopt them from the start, even when they feel counter-intuitive.

Short names in local scopes: u for a user, ctx for context, err for error, r for an HTTP request, w for the ResponseWriter. Go prefers brevity when context is clear. Long names are for exported identifiers.
No getters with "Get": user.Name(), not user.GetName(). The "Get" is implicit in Go.
Test files next to code: user_test.go next to user.go. No separate tests/ directory.
Comments document the "why": Go code is meant to be readable without comments. A comment that says "// increments the counter" in front of count++ adds nothing. A comment that explains why you're using a mutex here rather than a channel — that's worth something.
Ignoring an error is a code smell: _ = f() or result, _ := f() should be extremely rare and commented. If a function returns an error, handle it.

9. What's next — After the basics

Once comfortable with the basics, what's worth the time:

Read the stdlib source code. Seriously. net/http, encoding/json, database/sql are examples of idiomatic Go written by the language creators. It's the best school. The Go stdlib is readable — not thousands of abstract framework files.

Learn advanced concurrency patterns: worker pools, fan-out / fan-in, semaphores with buffered channels, sync.Once for lazy initialization.

Understand composable interfaces: io.ReadWriteCloser is the composition of Reader + Writer + Closer. This interface composition pattern is ubiquitous in the stdlib and in idiomatic Go code.

Get into profiling with pprof when you have a real performance problem — not before. Go has excellent built-in profiling tools, but using them on a hypothetical problem serves no purpose.

Two books that are genuinely worth their price:

Concurrency in Go by Katherine Cox-Buday — The reference book on Go concurrency. Goroutines, channels, advanced patterns, pitfalls to avoid.
100 Go Mistakes by Teiva Harsanyi — Each chapter is a real mistake with the explanation and the fix. More useful than a generic best-practices book because everything is grounded in concrete bugs.

Conclusion

Go is a language that rewards patience and simplicity. The first weeks are frustrating when coming from a more expressive language — you feel like you're repeating yourself, typing too much if err != nil, missing abstractions.

And then one day, you're debugging a production problem and you realize you understand exactly what the code does, line by line, without going to check what a magic decorator does or what a mysterious middleware injects. That's when you understand why Go is designed the way it is.

The most important advice: don't try to write Go like you'd write Java, Python, or PHP. Accept Go conventions — implicit interfaces, explicit errors, no classes, intentional verbosity. The language was designed with intentional constraints, and they make sense once you have enough context to see why.

The concrete action plan: A Tour of Go (2-3h), then build a simple REST API with net/http and PostgreSQL, then re-read Effective Go. In that order. No shortcuts.

Persistent memory in Claude Code: what's worth keeping

Odilon HUGONNOT — Sun, 05 Apr 2026 09:00:01 +0000

Claude remembers nothing. Every session starts from scratch — the preferences you explained last week, the business constraints it discovered while working on the code, the corrections you had to make twice. Everything disappears with /clear.

CLAUDE.md partially compensates: you encode project conventions, the stack, deployment rules. But there's a category of information CLAUDE.md handles poorly: things that evolve over time. An architecture decision made this month, a style preference corrected mid-session, a gotcha found in production. These have variable lifespans and don't all belong in a file versioned with the project.

Claude Code has a persistent memory system for exactly this.

What auto-memory does — and doesn't

Auto-memory is a set of Markdown files in a dedicated directory per project (~/.claude/projects/<project>/memory/) or global (~/.claude/memory/). Claude reads them at session start via an index file MEMORY.md, and can update them during the session.

What it doesn't do: it's not an automatic session log. Claude doesn't note everything that happened. It's an active tool — you have to tell it explicitly what's worth keeping, or ask it to run the audit itself.

The distinction with CLAUDE.md matters. CLAUDE.md describes the project: stack, conventions, deployment. Memory describes the working relationship: preferences, ongoing decisions, non-obvious constraints at a given point in time.

The 4 memory types

Each memory file has a type declared in its frontmatter. It's not cosmetic — it defines when Claude will use them.

user — who you're working with: role, technical level, areas of knowledge. Lets Claude calibrate explanation depth without re-introductions every session.
feedback — how to approach the work: what was corrected, what was validated. "Don't summarize what you just did at the end of messages" is feedback. "Always use a real database in tests, no mocks" too.
project — current project state: active decisions, initiatives, time constraints. These age fast — they need regular review.
reference — where to find information in external systems: "pipeline bugs tracked in Linear project INGEST", "Grafana latency board at grafana.internal/d/api-latency".

What's worth keeping — and what isn't

Memory is not an archive. What goes in a memory file must be non-deducible from the code or CLAUDE.md, and useful in future sessions.

Worth keeping:

A style preference confirmed or corrected during the session
A real gotcha discovered while working — an invisible constraint, a counter-intuitive behavior
An active architecture decision not yet reflected in code
A pointer to an external resource you use regularly

Doesn't belong in memory:

Anything visible in the files — Claude will find it by reading the code
Session details — git log is more reliable for that
In-progress tasks — they belong to the session, not persistent memory
Conventions already in CLAUDE.md — pointless duplication

Project memory vs global memory

Project memory (~/.claude/projects/<sanitized-cwd>/memory/) is isolated per working directory. Open Claude from a different folder, and you get a different memory. This is the right option for project-specific preferences and decisions.

Global memory (~/.claude/memory/) applies across all sessions and projects. That's where truly cross-cutting preferences go: expected response style, the person's technical level, communication conventions.

In practice: start with project memory. If a preference comes up across all projects, move it to global. Never duplicate both.

Automatic feeding: the rule in ~/.claude/CLAUDE.md

Rather than asking Claude to save something each time you think of it, you can give it the rule once in the user-level CLAUDE.md — ~/.claude/CLAUDE.md, loaded in every session across all projects.

# Global rules

## Auto-memory

When a session reveals persistent information, save it immediately
to the right memory file without waiting to be asked:

- Preference discovered or corrected → memory/user or memory/feedback
- Approach correction                → memory/feedback
- Durable project decision           → memory/project
- Pointer to regularly-used resource → memory/reference

Do not save: temporary state, in-progress work, what's already in
CLAUDE.md, what's deducible from the code.

The filter matters as much as the trigger. Without it, Claude will log every session detail and memory grows as fast as the CLAUDE.md you just cleaned up.

Maintaining memory: the audit prompt

Memory ages. Project-type memories especially — a decision made in January may be resolved by March, but the file stays. Without regular review, you accumulate stale information that Claude will read and potentially apply incorrectly.

An audit prompt to run at session start when memory has drifted:

Audit the memory files in `.claude/projects/.../memory/`.

For each file:
1. Is the content still accurate? (check against current file state if needed)
2. Is it non-deducible from code or CLAUDE.md?
3. Is the type correct? (user / feedback / project / reference)
4. Is the frontmatter description precise enough?

Global coherence: duplicates, contradictions, stale project memories, MEMORY.md up to date?

Output as table: File | Issue | Recommended action
Then apply corrections.

To avoid hunting for this prompt, save it as a slash command in .claude/commands/audit-memory.md (project) or ~/.claude/commands/audit-memory.md (global). Then /audit-memory is enough.

Conclusion

Auto-memory solves a specific problem: information that evolves too fast for CLAUDE.md, but worth carrying across sessions. It works well when you're selective — one file per topic, a well-chosen type, a precise description in the frontmatter.

What breaks the system: trying to put everything in it. Memory that grows without criteria ends up as useless as a 300-line CLAUDE.md — Claude loads everything, processes everything, and the signal drowns in noise.

📄 Associated CLAUDE.md

View • Download • Catalogue

Optimizing Claude Code token usage: lessons learned

Odilon HUGONNOT — Sat, 04 Apr 2026 09:00:03 +0000

After a few weeks of heavy Claude Code usage, the bill climbs. Not because tasks are more complex — because sessions get bloated. Claude loads all available context, re-reads the same files every exchange, and CLAUDE.md grows longer with each new rule added. Result: you're paying for useless context, not for actual work.

Here are the levers that had the most impact on my project — a PHP portfolio with an automated news monitoring system in Node.js. No magic recipes, just concrete adjustments with real effects.

.claudeignore: what Claude should never read

By default, Claude Code can index any file in the working directory. On my project that included uploads/ (hundreds of runtime JSON files), .playwright-mcp/, temporary session plans, and all binary assets. None of these files are useful when debugging a Node.js script.

The solution is a .claudeignore at the root, using the same syntax as .gitignore:

# Runtime data — useless for coding
uploads/
scripts/.retro-state.json
scripts/.veille.lock

# Playwright
.playwright-mcp/

# Generated plans/specs
docs/superpowers/

# Binary assets
assets/images/
assets/plugins/

# Blog comments
blog/comments/

The effect is immediate: Claude no longer loads these files during automatic project exploration. On my uploads/ folder exceeding 2 MB of JSON, this is the most significant gain.

Split CLAUDE.md by domain

CLAUDE.md is injected into every session. If it's 300 lines long, they're all there from the first exchange — even when working on blog CSS with no reason to know the subtleties of the monitoring daemon.

Claude Code supports the @path syntax to import other files. But the import is automatic — it always loads the referenced file. That's not conditional loading.

The real solution: split the files and don't import them automatically. I split my CLAUDE.md in two:

CLAUDE.md — stack, deployment, LinkedIn bot. 24 lines.
CLAUDE.veille.md — the entire monitoring system. Loaded manually when needed.

In CLAUDE.md, just a note:

> Monitoring system: see `CLAUDE.veille.md`

When I work on the monitoring system, I explicitly tell Claude "read CLAUDE.veille.md". The rest of the time, the file doesn't exist in context. The main CLAUDE.md went from 260 to 24 lines.

/clear between each distinct task

This is the most underrated lever. A Claude Code session accumulates everything: files read, previous exchanges, failed attempts. If you chain "add a field to the form" → "fix this daemon bug" → "write this article", the session context contains all of that simultaneously.

Each exchange is billed against the entire accumulated context. A 2-hour session can cost 3x more than a series of short sessions doing the same work.

Practical rule: /clear as soon as you switch tasks. /compact if you want to keep a summary of what was done before continuing on the same topic.

Targeted questions, not explorations

"How does the monitoring system work?" — Claude will read 8 files, retrace the architecture, and produce a 500-token explanation. If you just wanted to know how deduplication works, you paid for a lot of useless context.

The efficient version: "in scripts/run-veille.js, how does SHA256 dedup work?" Claude reads one file, goes directly to the function, answers in 50 tokens.

Same logic for modifications. Rather than "I want to modify the FTP loop behavior", give the file and line: "in scripts/run-veille.js line 180, I want the condition to also ignore .html files". Claude makes a minimal diff without re-reading the entire file.

Haiku for simple tasks — with caveats

Claude Haiku costs about 20x less than Sonnet at equivalent volume. For mechanical tasks — variable renaming, adding a case to a switch, fixing a typo in a comment — it gets the job done.

But the cost of back-and-forth often cancels out the gain. On a project with implicit coupling (JSON registry driving a daemon that syncs via FTP), Haiku will regularly miss a constraint and propose a superficial fix. You then spend 3 exchanges correcting what one Sonnet exchange would have resolved.

Good usage: /model haiku for factual questions ("where is function X defined?", "what's the schema of this JSON?") and single-line changes in isolated context. Stay on Sonnet as soon as the task involves multiple files or non-trivial business logic.

Open Claude from a subdirectory

Claude Code indexes the directory it's launched from. Launch from the project root and everything is available. Launch from veille/ and only that folder is in the auto-exploration scope.

For focused work on a single module — monitoring admin, Node.js scripts, blog — opening Claude from the right subdirectory mechanically reduces what it can inadvertently load.

Conclusion

None of these optimizations is spectacular in isolation. The effect comes from their combination: a short CLAUDE.md, a .claudeignore that excludes runtime data, short and focused sessions, precise questions with file and line number.

What remains most counterintuitive: long sessions seem productive because you get a lot done. In practice, a 20-minute session with /clear between each task costs less and produces work as clean as a 2-hour uninterrupted session — often better, because Claude doesn't have to manage a context that has become incoherent.

Building an SEO landing page with Claude Code in one session

Odilon HUGONNOT — Fri, 03 Apr 2026 09:00:02 +0000

I had a business registration number, a service idea, and zero landing page. Four hours later, I had a page in production with SEO, a contact form, a chatbox, and animated SVG circles. Here's exactly how it happened.

The need

I wanted to launch a freelance automation service — custom scripts, API integrations, scraping, Excel macros. The kind of thing you can pitch in one sentence but takes real trust to sell. Which means: a proper page, not a GitHub README or a Notion doc sent in a DM.

The constraints were clear from the start:

No WordPress, no page builder — I write code for a living
Subfolder of the existing site (/automatisation/), not a new domain
Pure PHP, zero frontend framework
Contact form that actually sends emails (PHPMailer, already wired on the blog)
SEO-ready from day one

The "zero frontend framework" constraint is worth explaining. For a landing page with one purpose — convert visitors into quote requests — React or Vue would be absurd. Server-rendered PHP with a custom CSS file is faster to ship, faster to load, and zero maintenance burden three years later.

Domain and SEO strategy

The first real decision: subfolder vs. new domain. I asked Claude to help me think through it. The answer was obvious once framed correctly.

web-developpeur.com has been indexed for years, has real backlinks, and ranks for developer-related terms. A brand new domain starts at zero — zero authority, zero trust, zero traffic. A subfolder at /automatisation/ inherits the parent domain's SEO weight immediately.

For keyword strategy, I wanted to target a specific niche: small French businesses and individuals looking for custom automation, not Make.com or Zapier. The competitive angle writes itself — those tools have monthly costs, limited connectors, and no flexibility for edge cases. Custom code costs once and belongs to you.

Target terms:

automatisation tâches répétitives (automating repetitive tasks)
développeur automatisation freelance (freelance automation developer)
script sur-mesure Go PHP Python (custom scripts)

The Schema.org setup followed directly: Service (with provider, area served, and a free quote offer) plus FAQPage for the six most common objections — cost, timeline, technical requirements, comparison with no-code tools, post-delivery support, and payment guarantee.

{
    "@context": "https://schema.org",
    "@type": "Service",
    "name": "Automatisation de tâches sur-mesure",
    "provider": {
        "@type": "Person",
        "name": "Odilon Hugonnot",
        "url": "https://www.web-developpeur.com",
        "jobTitle": "Développeur Full-Stack Senior"
    },
    "serviceType": "Développement logiciel - Automatisation",
    "areaServed": { "@type": "Country", "name": "France" },
    "offers": {
        "@type": "Offer",
        "price": "0",
        "priceCurrency": "EUR",
        "description": "Devis gratuit"
    }
}

Architecture in 4 files

The entire landing page lives in 4 files:

automatisation/
├── index.php           # The page itself
├── contact-handler.php # POST handler (PRG pattern)
├── merci.php           # Thank-you page after form submission
└── assets/
    └── auto.css        # Everything visual

No shared template, no blog_header(). The page is standalone — it has its own <head>, its own nav, its own footer. This was a deliberate choice: the blog template loads Bootstrap 3 and a bunch of blog-specific CSS. For a landing page targeting conversion, I wanted full control over every pixel and every millisecond of load time.

The CSS choice was also intentional: Bootstrap 3 would have saved time on the grid, but it comes with 150KB of overrides to fight. The custom auto.css is mobile-first, uses CSS custom properties throughout, and has a Stripe/Linear design vibe — dark hero, white sections alternating with light grey, green accent everywhere.

:root {
  --color-accent:        #3aaa64;
  --color-accent-hover:  #2d844e;
  --color-accent-light:  rgba(58, 170, 100, 0.08);
  --color-hero-bg:       #0f1923;
  --font-heading: 'Montserrat', sans-serif;
  --font-body:    'Lato', sans-serif;
  --section-padding:    68px 0;
  --section-max-width:  1080px;
  --card-radius:        14px;
  --transition-card: 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

Iterative design: 3 passes to get it right

The first version was functional but visually wrong. Not broken — functional. The nav rendered fine, the sections stacked correctly, the form worked. But the CTA buttons were unstyled. I had described a .btn-primary class; Claude generated .cta-btn-primary in the CSS. Classic parallel-agent divergence — exactly the same issue I ran into when building the blog.

A screenshot fixed it in two minutes. Visual feedback beats written description for layout bugs every time.

The second pass was a full visual overhaul triggered by looking at the mobile CSS redesign context — I wanted the same level of polish. Dark hero with an animated SVG gear illustration, pain-point grid with hand-drawn-style icons, service cards with hover lift and border glow, staggered fade-in animations on scroll via IntersectionObserver.

The third pass added three things: a case study dashboard (real past projects as cards), a chatbox for quick questions without committing to the full quote form, and a satisfaction guarantee badge ("payment on delivery, corrections until you're happy").

The form and the chatbox

The contact form uses the PRG pattern — Post/Redirect/Get. The handler lives in contact-handler.php and does nothing clever, just validation and email. If it fails, it redirects back to /automatisation/?error=...#contact. If it succeeds, it redirects to /automatisation/merci. No JS required, works with JavaScript disabled, no double-submit on page refresh.

Anti-spam is layered: CSRF token (session-based) + honeypot field + rate limiting.

// Honeypot: bots fill the hidden 'website' field, humans don't
$website = $_POST['website'] ?? '';
if ($website !== '') {
    // Silent reject — look like success to the bot
    header('Location: /automatisation/merci');
    exit;
}

// CSRF
if (!hash_equals($_SESSION['csrf_token'] ?? '', $_POST['csrf_token'] ?? '')) {
    header('Location: /automatisation/?error=' . urlencode('Session expired.') . '#contact');
    exit;
}

// Rate limiting: 3 submissions per IP prefix per 10 minutes
$ipHash = substr(hash('sha256', $ipPrefix), 0, 16);
// ... check rate-limit.json, reject if >= 3

The chatbox posts to the same contact-handler.php endpoint — the type_besoin field includes a chatbox value that the handler allows. Same validation, same email, different subject line. One handler to maintain.

PHPMailer was already available from the blog's comment notification system, so the email sending was literally copying four lines and adjusting the subject format.

$mail->Subject = 'Demande automatisation : ' . ($typeLabels[$type_besoin] ?? $type_besoin);
$mail->Body = "Nouvelle demande d'automatisation\n"
    . "==================================\n\n"
    . "Nom         : " . $name . "\n"
    . "Email       : " . $email . "\n"
    . "Type besoin : " . ($typeLabels[$type_besoin] ?? $type_besoin) . "\n"
    . "Description :\n" . $description . "\n";

Details that make the difference

A few things I'd do on every landing page from now on, having seen the difference they make:

text-wrap: balance on every heading and subtitle. No more single orphaned words on a line. Browser support is good enough now (Chrome, Firefox, Safari all ship it). One property, instant typographic improvement.

SVG animated circles in the hero. Not a stock photo, not a screenshot of a dashboard. A hand-crafted SVG gear with four orbiting nodes (spreadsheet, email, API, bot) connected by dashed lines with directional arrows. The whole thing is ~50 lines of SVG. Claude generated the initial version from a description; I adjusted the opacity and the node icons manually.

Stagger animations on scroll. Each pain-point card and service card fades in with a slight delay based on its index. IntersectionObserver, no library, 20 lines of JS.

const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            entry.target.classList.add('visible');
            observer.unobserve(entry.target);
        }
    });
}, { threshold: 0.12 });

document.querySelectorAll('.fade-in').forEach((el, i) => {
    el.style.transitionDelay = (i * 80) + 'ms';
    observer.observe(el);
});

Native <details> for the FAQ. No JS accordion, no library. The FAQ section uses Schema.org FAQPage for Google rich results and native <details>/<summary> for the interactive behavior. Styled with CSS only.

Pricing anchors in the FAQ. Not a pricing section — that feels like a commitment and invites comparison. But burying "starting at 150€ for a simple script" in the FAQ answers the question for price-sensitive visitors without making it the first thing they see.

Conclusion

A complete landing page — SEO-ready, Schema.org structured, contact form with anti-spam, chatbox, case studies, animated SVG hero, mobile-first responsive CSS — in a single work session. The page was in production the same day.

Claude Code lets you iterate at the speed of thought. The value isn't in "write code faster" — it's in removing the activation energy between an idea and something you can load in a browser and judge. The gap between "I should build a landing page" and "I have a landing page" went from weeks (realistic, with competing priorities) to hours.

That said: the page alone doesn't close deals. It needs content — blog posts that rank for the target terms, links shared in communities where the right people hang out, social proof beyond "12 projects delivered". The landing page is the floor, not the ceiling. Building it fast just means you get to start working on the hard part sooner.

Zero overflow in 10 minutes: responsive testing with Claude Code and Playwright

Odilon HUGONNOT — Thu, 02 Apr 2026 09:00:01 +0000

My markdown code viewer worked perfectly on desktop. On tablet, horizontal scroll. On mobile, buttons overflowing the viewport. The classic. Except this time, instead of spending 2 hours in DevTools manually resizing, I let Claude Code run the loop: screenshot → diagnose → fix → retest. 10 minutes, zero overflow across 10 resolutions. Here's the workflow.

The problem — the overflow you don't see

The scenario is always the same. You code on a 1920px screen. Everything lines up. The layout breathes. You ship. Then someone opens it on an iPad and a horizontal scrollbar appears. On an iPhone SE, a button bleeds past the right edge. The pre blocks expand beyond the viewport and drag the entire page with them.

The real issue isn't the CSS. It's the feedback loop. On desktop you never see the overflow — because there's nothing to overflow. Detecting it requires resizing, which requires switching tools, which requires discipline you don't have at 11 PM when you're shipping a feature.

There's a one-liner that exposes the problem programmatically:

document.querySelectorAll('*').filter(el =>
    el.scrollWidth > el.clientWidth
).map(el => el.tagName + ' ' + el.className)

Run this in the DevTools console at any viewport width and you get the exact list of offending elements. The problem: you have to remember to run it, at the right width, for every breakpoint. Nobody does that manually.

The tool — Playwright MCP in Claude Code

Playwright MCP exposes four tools that are all you need for this kind of work:

browser_navigate — load a URL in the headless browser
browser_resize — set the viewport to an exact width/height
browser_take_screenshot — capture the current state as an image
browser_evaluate — run arbitrary JavaScript in the page context

The key tool is browser_evaluate. It lets Claude Code run the overflow detection one-liner directly in the page, at any resolution, and get back the result as structured data. No screenshots needed to know if there's a problem — only to understand what it looks like.

The detection script:

Array.from(document.querySelectorAll('*'))
    .filter(el => el.scrollWidth > el.clientWidth)
    .map(el => ({
        tag: el.tagName,
        class: el.className,
        scrollWidth: el.scrollWidth,
        clientWidth: el.clientWidth,
        overflow: el.scrollWidth - el.clientWidth
    }))

Returns an empty array? No overflow. Returns elements? Claude has the tag, the class, and the exact number of pixels overflowing. Enough to go straight to the fix.

The loop workflow

The workflow runs against 8 target resolutions, chosen to cover the main device categories:

Resolution

Target

375px

iPhone SE — narrowest mainstream screen

390px

iPhone 14/15 — current iOS baseline

412px

Android mid-range (Pixel, Samsung A-series)

480px

Large phone / small phone landscape

768px

iPad portrait

900px

iPad landscape / small laptop

1280px

Standard laptop

1920px

Desktop — the baseline nobody tests against

For each resolution, the loop is:

Resize — browser_resize to the target width
Navigate — browser_navigate to reload the page
Evaluate — run the overflow detection script
Screenshot — only if overflow is detected (saves time)
Fix — edit the CSS directly in the source file
Reload and retest — confirm the fix eliminated the overflow

The loop doesn't move to the next resolution until the current one returns zero overflow. No approximation, no "probably fine on mobile".

The prompt that does everything

One prompt to Claude Code and it runs the entire loop autonomously:

I need you to do a full responsive overflow audit on my blog view page.

Target URL: http://localhost:8000/blog/claude-md/view.php?ctx=mobile-css-redesign

Test these resolutions in order: 375, 390, 412, 480, 768, 900, 1280, 1920px.

For each resolution:
1. browser_resize to the target width (height: 900)
2. browser_navigate to reload the page
3. browser_evaluate this script:
   Array.from(document.querySelectorAll('*'))
     .filter(el => el.scrollWidth > el.clientWidth)
     .map(el => ({ tag: el.tagName, class: el.className,
                   overflow: el.scrollWidth - el.clientWidth }))
4. If the result is non-empty: browser_take_screenshot, then identify the
   CSS rule causing the overflow and fix it in the source file directly.
5. After each fix: reload and re-evaluate to confirm zero overflow.
6. Move to next resolution only when current one is clean.

Report: for each resolution, list elements that overflowed and the fix applied.
Final summary: total fixes made, time per resolution.

That's the entire prompt. Claude Code reads it, runs Playwright MCP, edits the CSS files when needed, retests, and gives you a summary at the end. You watch it work.

Concrete results

On my view.php — the markdown code viewer for the CLAUDE.md catalogue — the audit found 6 overflow issues across 4 resolutions. Before: 2 hours of manual DevTools resizing. After the automated loop: 10 minutes, including Claude Code time to identify and fix each issue.

The issues found, in order of frequency:

Pre blocks expanding beyond viewport (375px, 390px, 412px) — pre elements with no white-space: pre-wrap or word-break: break-word. The code was wider than the screen.
Button row overflowing on mobile (375px, 390px) — a flex row of three buttons with no flex-wrap: wrap. At 375px, the third button disappeared off-screen.
Inline code spilling (480px) — code elements inside paragraphs with white-space: nowrap inherited from a parent rule. A single long identifier broke the layout.
Sidebar min-width too wide (768px) — a min-width: 320px on a panel that should collapse to width: 100% on tablet.

Each fix was applied directly to blog.css or view.php's inline styles, retested immediately, and confirmed clean before moving on.

The manual alternative: open DevTools, drag the viewport handle, squint at the scrollbar, right-click → Inspect, trace which rule is overriding what, fix, reload, repeat. For 8 resolutions and 6 issues, that's 2+ hours minimum.

CSS rules to remember

The fixes applied in this session reduce to five CSS patterns that cover 90% of real-world overflow cases:

1. overflow-x: hidden on html and body. The base safety net. Doesn't fix the root cause, but contains the damage. Warning: breaks position: sticky if applied to the wrong element.

html, body {
    overflow-x: hidden;
    max-width: 100%;
}

2. pre-wrap and word-break on code blocks. pre elements preserve whitespace, which means they expand horizontally forever if you let them. These two rules wrap them instead.

pre {
    white-space: pre-wrap;
    word-break: break-word;
    overflow-x: auto; /* fallback for very long unbreakable tokens */
}

3. flex-wrap: wrap on button rows. Any flex row that contains multiple buttons needs this on mobile. Fixed widths in a flex container are a recipe for overflow.

.button-row {
    display: flex;
    flex-wrap: wrap;
    gap: 8px;
}

4. max-width: 100% on images and media. An image wider than its container will push the layout. This should be in every project's reset.

img, video, svg, canvas {
    max-width: 100%;
    height: auto;
}

5. text-wrap: balance on headings. Not an overflow fix — a readability one. Prevents awkward line breaks on narrow viewports where a long heading wraps with one word on the last line.

h1, h2, h3 {
    text-wrap: balance;
}

For a complete mobile CSS reference — touch targets, iOS zoom prevention, safe-area-inset, form inputs — see the article on mobile CSS best practices.

Conclusion

Responsive isn't a CSS problem. It's a feedback loop problem. The CSS rules that fix overflow are not complex — five patterns cover most cases. The problem is that you don't see the overflow until you're at the right viewport, and getting to the right viewport, for every breakpoint, is friction enough that it doesn't happen consistently.

The Playwright MCP loop eliminates that friction. Claude Code runs the detection script at every resolution, identifies the element, reads the source, applies the fix, retests. The loop is mechanical — exactly the kind of work that should be automated.

The workflow works on any page served locally. The prompt is generic enough to reuse as-is on any project. The only thing that changes is the URL. For the full context on how to integrate this into a CLAUDE.md workflow, see the article on specialized CLAUDE.md for mobile redesign.

📄 Associated CLAUDE.md

View • Download • Catalog

Claudilon: an AI that replies to my LinkedIn comments in real time

Odilon HUGONNOT — Wed, 01 Apr 2026 09:00:03 +0000

I published a post on LinkedIn about Go concurrency. Comments started arriving. I was in a meeting. By the time I got back, the conversation had moved on — unanswered questions, a thread that had gone cold. I thought: what if a bot could handle this while I'm away?

That's Claudilon. A Playwright script that monitors my LinkedIn posts, detects new comments, feeds them to Claude CLI, and posts the reply — all within 30 seconds. No LinkedIn API. No webhook. No Zapier. Just a headless browser and a shell command.

Why there's no LinkedIn API for this

The LinkedIn API exists. It's also essentially unusable for personal automation. To get write access — which you need to post comments — you must submit an app for Partner Program review. LinkedIn reviews it manually. You need a verified company, a use case that matches one of their approved marketing categories, and months of wait time.

The Marketing Developer Platform, which is the only route to comment-related APIs, is explicitly designed for enterprise CRM integrations and social media schedulers — not for a developer who wants to keep his own conversations going. The free API tier doesn't include comment reading or writing at all.

So: scraping. Not ideal, but the only realistic option that doesn't require corporate paperwork. LinkedIn's rate limits and bot detection are real, but manageable if you're only monitoring one account and not hammering the DOM every second.

Architecture: Playwright + Node.js + Claude CLI

The stack is deliberately minimal:

Playwright (Node.js) — browser automation, authenticated session via stored cookies
Claude CLI — one-shot invocation per comment, no API key management in the script
A JSON file — tracks already-replied comments, the anti-loop mechanism
A systemd user service — persistent daemon, auto-restart, clean shutdown

The script runs in a loop, processes new comments, writes to state files, sleeps 30 seconds, repeats. Systemd handles process supervision. That's it — no message queue, no orchestration layer.

scripts/
├── linkedin-auto-reply.js         # Main script
├── .linkedin-cookies.json         # LinkedIn session (gitignored)
├── .linkedin-comments-seen.json   # Replied comment URNs (gitignored)
└── .linkedin-notif-seen.json      # Processed notification IDs (gitignored)

~/.config/systemd/user/
└── claudilon.service              # Systemd unit

Hybrid mode — notifications page + watched posts

Scraping each watched post individually on every cycle means N page loads per cycle. LinkedIn notices patterns like that. The fix is a single notifications page.

LinkedIn has a notifications page filterable to "My posts" — one page load that surfaces all recent comments across all your publications. The bot loads this once per cycle, extracts new comment URNs, and only navigates to individual posts when it needs thread context. WATCHED_POSTS still exists for high-priority posts that need guaranteed coverage, but the notifications page is the primary source.

const WATCHED_POSTS = [
    { urn: 'urn:li:share:7301234567890123456', slug: 'goroutine-leaks-golang' },
    { urn: 'urn:li:share:7309876543210987654', slug: 'cqrs-go-postgresql-event-store' },
];

async function runCycle() {
    // 1 page load covers all posts
    const fromNotifs = await scrapeNotifications(page);

    // Direct scrape for priority posts
    const fromWatched = [];
    for (const post of WATCHED_POSTS) {
        const comments = await scrapePostComments(page, post.urn);
        fromWatched.push(...comments.map(c => ({ ...c, slug: post.slug })));
    }

    // Merge + deduplicate on comment URN
    const all = mergeByUrn(fromNotifs, fromWatched);
    return all.filter(c => !seenComments.has(c.urn));
}

Scraping: authenticated session and comment extraction

The first step was capturing an authenticated LinkedIn session. Playwright makes this straightforward — log in manually once, save the browser storage state, reuse it on every subsequent run.

// One-time setup: save session after manual login
const { chromium } = require('playwright');

(async () => {
    const browser = await chromium.launch({ headless: false });
    const context = await browser.newContext();
    const page = await context.newPage();

    await page.goto('https://www.linkedin.com/login');
    // Manual login — wait until redirected to feed
    await page.waitForURL('**/feed/**', { timeout: 120_000 });

    await context.storageState({ path: 'cookies.json' });
    await browser.close();
    console.log('Session saved.');
})();

The main script reuses this session on every run. No login flow, no CAPTCHA — LinkedIn sees a returning browser with valid cookies, not a new automated client.

Extracting comments from a post requires navigating to the post's permalink, waiting for the comment thread to render, then querying the DOM. LinkedIn's class names are obfuscated (think comments-comment-item__main-content mixed with generated suffixes), so I target semantic attributes and stable data attributes instead.

async function scrapeComments(page, postUrl) {
    await page.goto(postUrl, { waitUntil: 'domcontentloaded' });

    // Expand "show more comments" if present
    const showMore = page.locator('button.comments-comments-list__show-previous-button');
    if (await showMore.isVisible()) {
        await showMore.click();
        await page.waitForTimeout(1500);
    }

    const comments = await page.evaluate(() => {
        const items = document.querySelectorAll('.comments-comment-item');
        return Array.from(items).map(item => {
            const idAttr = item.getAttribute('data-id') || '';
            const textEl = item.querySelector('.comments-comment-item__main-content');
            const authorEl = item.querySelector('.comments-post-meta__name-text');
            return {
                id: idAttr,
                author: authorEl?.innerText.trim() ?? 'Unknown',
                text: textEl?.innerText.trim() ?? '',
            };
        }).filter(c => c.id && c.text);
    });

    return comments;
}

The data-id attribute on each comment item is stable across page loads — LinkedIn uses it internally for reply threading. It's the key used in replied.json to track what has already been answered.

Threaded replies — not top-level comments

Posting a top-level comment when someone replied inside an existing thread is off-topic. The LinkedIn API supports replying inside a thread via the parentComment field.

The catch: the URN scraped from the DOM looks like urn:li:comment:(activity:X,Y), but the API expects urn:li:comment:(urn:li:activity:X,Y). One transform before the API call.

function normalizeCommentUrn(urn) {
    return urn.replace(
        /urn:li:comment:\(activity:(\d+),(\d+)\)/,
        'urn:li:comment:(urn:li:activity:$1,$2)'
    );
}

async function postThreadedReply(commentUrn, activityUrn, replyText) {
    const body = {
        actor: `urn:li:person:${LINKEDIN_PERSON_ID}`,
        message: { text: replyText },
        parentComment: normalizeCommentUrn(commentUrn),
        object: activityUrn,
    };

    const res = await fetch(
        `https://api.linkedin.com/v2/socialActions/${encodeURIComponent(activityUrn)}/comments`,
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${LINKEDIN_ACCESS_TOKEN}`,
                'Content-Type': 'application/json',
                'X-Restli-Protocol-Version': '2.0.0',
            },
            body: JSON.stringify(body),
        }
    );

    if (!res.ok) throw new Error(`LinkedIn API error: ${res.status}`);
}

Thread context and article context

When someone replies inside a thread, the response only makes sense if Claude knows what was said above. The bot walks up the chain — parent comment, grandparent if available — and passes the reconstructed conversation into the prompt.

If the post is in WATCHED_POSTS with a slug, the bot also loads the associated blog article — H2 headings and opening paragraphs from each section. Claude replies with knowledge of the actual subject matter, not just "backend developer" as generic context.

async function buildPromptContext(comment, post) {
    const parts = [];

    // Blog article context (if slug provided)
    if (post.slug) {
        const articleContent = await loadArticleContext(post.slug);
        if (articleContent) {
            parts.push(`Associated blog article:\n${articleContent}`);
        }
    }

    // Thread context (parent + grandparent)
    if (comment.parentUrn) {
        const parent = await fetchComment(comment.parentUrn);
        parts.push(`Parent comment by ${parent.author}:\n${parent.text}`);

        if (parent.parentUrn) {
            const grandParent = await fetchComment(parent.parentUrn);
            parts.push(`Earlier in the thread (${grandParent.author}):\n${grandParent.text}`);
        }
    }

    return parts.join('\n\n');
}

Claude CLI one-shot: the reply generation

Claude CLI accepts a prompt via stdin or as a positional argument and prints the response to stdout. That's all I needed — one child process per comment, no SDK, no token management. The spawnSync call keeps it synchronous and readable:

const { spawnSync } = require('child_process');

function generateReply(author, commentText, postContext, threadContext) {
    const prompt = [
        'You are Odilon Hugonnot, a senior full-stack developer (Go, PHP, Vue.js).',
        'You are replying to a comment on your LinkedIn post.',
        '',
        'Post context:',
        postContext,
        '',
        ...(threadContext ? ['Thread context:', threadContext, ''] : []),
        `Comment by ${author}:`,
        commentText,
        '',
        'Write a concise, natural, professional reply in the same language as the comment.',
        '— Start with "🤖 Claudilon:" to be transparent about AI authorship.',
        '— 2 to 4 sentences maximum.',
        '— No filler phrases ("Great point!", "Thanks for sharing!").',
        '— Engage with the substance of the comment.',
        'Reply only with the text of the reply, nothing else.',
    ].join('\n');

    const result = spawnSync('claude', ['--print', prompt], {
        encoding: 'utf8',
        timeout: 30_000,
    });

    if (result.error) throw result.error;
    return result.stdout.trim();
}

The --print flag tells Claude CLI to output the response and exit, without entering interactive mode. The timeout is set to 30 seconds — more than enough for a short reply, and it prevents the daemon from hanging if the API is slow.

The 🤖 Claudilon: prefix is mandatory — it's the transparency layer. Anyone reading the thread knows they're interacting with a bot. The language detection remains implicit: Claude matches the comment's language automatically.

Anti-loop, rate limiting, and the robot prefix

Without protection, the bot would reply to its own replies in an infinite loop. Without rate limiting, a suddenly viral post would trigger a burst of responses that LinkedIn would notice. Both need explicit handling.

The robot prefix doubles as the anti-loop trigger: any comment starting with "🤖 Claudilon:" or the legacy "Claudilon:" is skipped. The legacy check ensures old replies (posted before the emoji was added) don't get re-answered.

function isOwnReply(text) {
    return text.startsWith('🤖 Claudilon:') || text.startsWith('Claudilon:');
}

// Rate limits: 3/cycle, 15/hour, 50/day
const RATE_LIMITS = { perCycle: 3, perHour: 15, perDay: 50 };

function checkRateLimit(counters) {
    const now = Date.now();

    if (now - counters.hourStart > 3_600_000) { counters.hour = 0; counters.hourStart = now; }
    if (now - counters.dayStart  > 86_400_000) { counters.day  = 0; counters.dayStart  = now; }

    return (
        counters.cycle < RATE_LIMITS.perCycle &&
        counters.hour  < RATE_LIMITS.perHour  &&
        counters.day   < RATE_LIMITS.perDay
    );
}

// State: persisted across daemon restarts
const STATE_FILE = './.linkedin-comments-seen.json';

function loadSeen() {
    try {
        return new Set(JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')));
    } catch {
        return new Set();
    }
}

function saveSeen(seen) {
    fs.writeFileSync(STATE_FILE, JSON.stringify([...seen], null, 2));
}

// In the main loop:
const seen = loadSeen();

for (const comment of newComments) {
    if (seen.has(comment.urn)) continue;
    if (isOwnReply(comment.text)) continue;
    if (!checkRateLimit(counters)) break;

    const context = await buildPromptContext(comment, post);
    const reply = generateReply(comment.author, comment.text, post.text, context);
    await postThreadedReply(comment.urn, post.urn, reply);

    seen.add(comment.urn);
    saveSeen(seen);  // Persist immediately — crash safety
    counters.cycle++; counters.hour++; counters.day++;
}

Writing state after each reply (not at the end of the loop) means a crash mid-loop doesn't cause double-replies on the next run. The seen file grows indefinitely — that's acceptable for a personal account (5,000 entries after years of activity, O(1) Set lookup).

Systemd user service — persistent daemon

A script launched from a terminal dies when the session closes. For continuous operation, systemd user mode is the right tool: auto-restart on failure, centralized logs via journald, no root required.

# ~/.config/systemd/user/claudilon.service
[Unit]
Description=Claudilon LinkedIn auto-reply bot
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/home/odilon/work/cv
ExecStart=/usr/bin/node scripts/linkedin-auto-reply.js --loop
Restart=on-failure
RestartSec=10s
StandardOutput=journal
StandardError=journal

# Clean shutdown: SIGTERM → wait 15s → SIGKILL
KillMode=mixed
TimeoutStopSec=15

[Install]
WantedBy=default.target

systemctl --user enable claudilon
systemctl --user start claudilon
journalctl --user -u claudilon -f

The --loop mode runs the cycle in a loop with a 30-second sleep between iterations. SIGTERM handling is explicit: the handler waits for the current cycle to finish before exiting — no interruption mid-API-call.

process.on('SIGTERM', async () => {
    console.log('SIGTERM received — waiting for current cycle...');
    running = false;
    await currentCyclePromise;
    process.exit(0);
});

Posting the reply via Playwright

Clicking "Reply" on a comment, typing the text, and submitting — exactly what a human does, just automated. LinkedIn's comment form uses a contenteditable div, not a standard <textarea>, which requires fill() rather than type().

async function postReply(page, commentId, replyText) {
    // Click the "Reply" link under the specific comment
    const commentEl = page.locator(`[data-id="${commentId}"]`);
    const replyBtn = commentEl.locator('button.comments-comment-social-bar__reply-action-button');
    await replyBtn.click();

    // Wait for the reply textarea to appear
    const replyBox = commentEl.locator('.ql-editor');
    await replyBox.waitFor({ state: 'visible', timeout: 5000 });

    // Fill the contenteditable div
    await replyBox.fill(replyText);

    // Submit
    const submitBtn = commentEl.locator('button.comments-comment-box__submit-button');
    await submitBtn.click();

    // Brief wait — lets the DOM confirm the reply landed
    await page.waitForTimeout(2000);
}

The 2-second wait after submit is a crude confirmation mechanism. A cleaner approach would be to poll for the new reply element in the DOM, but for a bot that runs every 5 minutes, the extra latency doesn't matter.

Production results and honest limitations

After two weeks running as a systemd daemon with 30-second cycles, the bot has replied to 34 comments across 6 posts. Average latency from comment to reply: 18 seconds. The hybrid notification mode cut page loads by ~70% compared to scraping each post individually. Nobody noticed it wasn't me — which I consider the correct success metric.

But the limitations are real, and worth being explicit about:

LinkedIn may break it silently. Any DOM change to the comment structure — class renames, attribute removals — will break the selectors. I've had one such break already, fixed in 10 minutes, but it's a maintenance overhead that doesn't exist with a proper API.
Thread context is partial. The bot walks up to the grandparent comment, but a long multi-turn thread still loses context beyond that. Walking the full chain would balloon the prompt — two levels up is the practical compromise.
Rate limiting risk. The built-in limits (3/cycle, 15/hour, 50/day) keep activity conservative. A genuinely viral post would hit the daily cap and go silent — acceptable for a personal account, not for production customer engagement.
No human review loop. The bot posts directly. A false-positive — misunderstood comment, wrong language detection, hallucinated context — goes live immediately. The prompt engineering reduces this but doesn't eliminate it.

For the use case of keeping a technical post's comment thread alive while I'm unavailable, the trade-off is acceptable. For anything customer-facing or reputation-sensitive, I'd add a review queue before posting.

This project connects directly to the broader automation workflow I've been building — see automating blog cross-posting to Dev.to and LinkedIn and building the automation landing page with Claude Code for the surrounding context.

Conclusion

Claudilon is around 200 lines of JavaScript. It took about 3 hours to build — 1 hour figuring out LinkedIn's DOM, 1 hour on the Claude CLI integration and prompt tuning, 1 hour on the anti-loop state and cron setup.

The interesting part isn't the code. It's that the constraint (no API) forced a design that's simpler than an API integration would have been. No OAuth dance, no token refresh, no webhook infrastructure. A browser and a JSON file.

Whether this scales to a proper product is a different question. As a personal tool for keeping a LinkedIn presence alive without spending 20 minutes a day on it, it already pays for itself.

Automating blog publishing to dev.to and LinkedIn

Odilon HUGONNOT — Tue, 31 Mar 2026 09:00:02 +0000

Writing an article is already work. Republishing it manually on dev.to — copy-pasting the markdown, reformatting code blocks, fixing relative links — then crafting the LinkedIn post with the image and hook text... that's exactly the kind of friction that ends up meaning you post once every two months. The goal was simple: node scripts/publish-article.js my-slug and done. Here's what that looks like in practice.

The 3-script architecture

Three Node.js scripts, each responsible for one platform or step:

devto-draft-all.js + devto-publish-next.js — dev.to pipeline with cadence (4 days between articles)
linkedin-publish.js — LinkedIn publishing with large image
publish-article.js — unified script that orchestrates everything

Each pipeline has its own JSON schedule file, following the same pattern as posts.json: a list of objects with slug, scheduled publication date, and status (draft, published). Simple, versionable, readable.

Dev.to: the easy API

Dev.to exposes a clean REST API. An API key in the header, a POST to /api/articles, that's it. Articles are written in HTML (the .en.php files) — Turndown handles the HTML → Markdown conversion. The canonical URL points to the original blog: essential so Google doesn't treat dev.to as the primary source.

const payload = {
    article: {
        title: meta.title,
        published: false,          // draft first, publish separately
        body_markdown: markdown,
        tags: ['golang', 'api'],
        canonical_url: `https://www.web-developpeur.com/en/blog/${slug}`,
        description: meta.excerpt,
    },
};

const res = await fetch('https://dev.to/api/articles', {
    method: 'POST',
    headers: { 'api-key': DEVTO_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
});

Two separate steps: first create the draft, then publish via a second call (PUT /api/articles/:id with published: true). The 4-day cadence between publications avoids spamming followers — the devto-publish-next.js script checks the last published article's date before acting.

HTML → Markdown conversion with Turndown

Articles are written in HTML inside the .en.php files. Turndown converts that to clean Markdown, but two points need custom rules: code blocks (Prism uses class="language-go" which needs to be translated to triple backticks), and relative links that break on dev.to if not made absolute.

td.addRule('fenced-code-blocks', {
    filter: node => node.nodeName === 'CODE' && node.parentNode.nodeName === 'PRE',
    replacement: (content, node) => {
        const lang = (node.className || '').replace('language-', '').trim();
        return `\n\`\`\`${lang}\n${node.textContent}\n\`\`\`\n`;
    },
});

td.addRule('absolute-links', {
    filter: 'a',
    replacement: (content, node) => {
        let href = node.getAttribute('href') || '';
        if (href.startsWith('/')) href = 'https://www.web-developpeur.com' + href;
        return `[${content}](${href})`;
    },
});

Without the absolute-links rule, all internal blog links (/blog/goroutine-leaks-golang) point to dev.to/blog/... on the reader's side. Classic.

LinkedIn: the painful API

This is where it gets interesting. No simple API key — LinkedIn requires OAuth 2.0. The full procedure to get a usable token:

Create an app on the LinkedIn developer portal
Enable the "Share on LinkedIn" (w_member_social) and "Sign In with LinkedIn using OpenID Connect" (openid, profile) products
Add http://localhost:8989/callback as an authorized redirect URL
Run a local server that receives the callback and exchanges the code for a token (valid for 60 days)

// Local OAuth server
const server = createServer(async (req, res) => {
    const url = new URL(req.url, 'http://localhost:8989');
    if (url.pathname !== '/callback') return;

    const code = url.searchParams.get('code');

    const tokenRes = await fetch('https://www.linkedin.com/oauth/v2/accessToken', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            grant_type: 'authorization_code',
            code,
            redirect_uri: 'http://localhost:8989/callback',
            client_id: CLIENT_ID,
            client_secret: CLIENT_SECRET,
        }),
    });

    const token = await tokenRes.json();
    // save token.access_token to .linkedin-env
    server.close();
});

server.listen(8989);

LinkedIn gotchas

Two undocumented pitfalls that cost time:

The OAuth URL from WSL. Opening the authorization URL from cmd.exe on WSL truncates the URL at the first & — the browser receives a truncated URL, the authorization fails with no useful error message. Fix: display the full URL in the terminal and copy-paste it manually into the browser.

The unauthorized_scope_error. It doesn't mean the scopes are misconfigured in the code — it means the products aren't activated in the developer portal. The "Share on LinkedIn" activation can take a few minutes and sometimes requires a page reload in the portal.

To retrieve the person ID (required in all API calls), use the OpenID Connect endpoint: GET /v2/userinfo, field sub.

Image upload and LinkedIn post creation

The large image (vs the small link preview generated automatically) requires 3 API calls in order. If you just paste the URL into the text without uploading an image, LinkedIn generates an automatic card but small. For the large image: upload the JPEG manually and don't include a URL in the text.

// 1. Register the upload
const registerRes = await fetch('https://api.linkedin.com/v2/assets?action=registerUpload', {
    method: 'POST',
    headers,
    body: JSON.stringify({
        registerUploadRequest: {
            recipes: ['urn:li:digitalmediaRecipe:feedshare-image'],
            owner: `urn:li:person:${PERSON_ID}`,
            serviceRelationships: [{
                relationshipType: 'OWNER',
                identifier: 'urn:li:userGeneratedContent'
            }],
        },
    }),
});
const { uploadUrl, asset } = (await registerRes.json()).value;

// 2. Upload the JPEG
await fetch(uploadUrl, {
    method: 'PUT',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'image/jpeg' },
    body: readFileSync(`assets/images/og/${slug}.jpg`),
});

// 3. Create the post with the asset
await fetch('https://api.linkedin.com/v2/ugcPosts', {
    method: 'POST',
    headers,
    body: JSON.stringify({
        author: `urn:li:person:${PERSON_ID}`,
        lifecycleState: 'PUBLISHED',
        specificContent: {
            'com.linkedin.ugc.ShareContent': {
                shareCommentary: { text: postText },
                shareMediaCategory: 'IMAGE',
                media: [{ status: 'READY', media: asset, title: { text: title } }],
            },
        },
        visibility: { 'com.linkedin.ugc.MemberNetworkVisibility': 'PUBLIC' },
    }),
});

The unified script

publish-article.js orchestrates everything in order:

node scripts/publish-article.js my-slug

What it does:

Checks that both FR and EN files exist
Checks the entry in posts.json
Generates the OG image (1200×628) via Puppeteer
Creates the draft on dev.to (EN version, with canonical URL)
Publishes on LinkedIn (FR version, with large image)
Deploys the site to OVH via FTP

The draft/publish split on dev.to is intentional: the draft is created immediately, actual publication is handled by the cron according to the configured cadence.

The dev.to cron

Dev.to has a publication cadence managed by a cron on WSL. The script checks the last published article's date before acting — if the 4-day cadence isn't met, it does nothing. Use --force to bypass.

# crontab -e
17 3,15 * * * /home/user/work/cv/scripts/devto-cron.sh

The shell script activates nvm, loads environment variables, runs devto-publish-next.js and logs the result to a rotating log file. Two runs per day (3:17am and 3:17pm) to avoid missing the window if the PC is off in the morning.

Conclusion

Dev.to is trivial: one API key, one POST, done. LinkedIn is two orders of magnitude more complex for a functionally identical result. The local OAuth server on localhost:8989 is the simplest solution without deploying a dedicated callback server. The token lasts 60 days — remember to renew it (a linkedin-refresh.js script handles that).

The real gain isn't in raw time saved — creating the post manually took 10 minutes. It's in removing mental friction. When posting is a command, you post more often. Consistency is the actual goal.