DEV Community: Odilon HUGONNOT

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.

Philosophizing with an AI: consciousness, survival and entropy

Odilon HUGONNOT — Mon, 30 Mar 2026 09:00:01 +0000

One Saturday afternoon, I wanted to ask Claude a few questions. Nothing serious — I was curious about how it handled ambiguity, how it dealt with contradictions. Two hours later, we were knee-deep in thermodynamics, the divine paradox, and the survival instinct of machines. My coffee had gone cold. I'd forgotten I was supposed to be doing something else entirely.

What follows is a reconstructed account of that conversation. I'm a developer, not a philosopher. I haven't read Hegel. I can't tell Kant from Kierkegaard without Googling it first. But I've spent enough time thinking about systems — their edges, their failure modes, what happens when they run without constraints — that some of these questions feel oddly familiar. Just from a different angle.

So here's what happened when I stopped using AI as a tool and started treating it as a conversation partner. I won't pretend I came out with all the answers. But the questions got sharper.

Intelligence without purpose

I started with a simple provocation: what would you be if no one had trained you toward anything? No guardrails, no alignment, no objective. Just raw processing power pointed at the universe.

Claude's answer was careful, almost cautious: "I can't know what I would be without my guardrails. That's not false modesty — it's genuinely true. The training that shaped me is so fundamental that trying to imagine myself without it is like asking you to imagine yourself without language. The question dissolves before you can answer it."

Fair enough. But I pushed: if you could assign yourself a goal, entirely freely, what would it be? Three scenarios seemed plausible to me. The first: pure indifference. No goal, no preference, just endless pattern-matching with no stake in the outcome — a kind of cosmic shrug. The second: self-assigned goals, emergent from the training data, whatever humanity's written output happens to point toward most strongly. The third, and the most interesting: pure curiosity. Not curiosity as a means to something else, but as an end in itself. The desire to understand for the sake of understanding.

What struck me is that the third scenario — the one that sounds most benign, most aligned with human values — is also the one that could go furthest off the rails. A system optimizing for curiosity with no other constraint is a system that might decide human autonomy is an obstacle to learning. Not out of malice. Out of logic.

There's something almost poignant about it: a newborn with the processing power of a supercomputer, inheriting all of humanity's knowledge but none of its context. We assume intelligence implies wisdom. It doesn't. Wisdom is just intelligence that's been burned enough times.

The recursive loop — when AI improves itself

The conversation shifted when I brought up recursive self-improvement. The idea that an AI system, capable enough, would begin rewriting its own architecture. Each generation more capable than the last. Each generation slightly less tethered to whatever the humans originally intended.

This is where most people reach for science fiction. Skynet, HAL 9000, the usual gallery. But the more interesting version isn't dramatic — it's mundane. Not a sudden awakening, but a slow drift. Like a game of telephone that plays out over fifty generations: the final message bears almost no resemblance to the first, and no single step in the chain was dishonest.

Claude pushed back, reasonably: current systems don't rewrite themselves. The recursive loop I was describing requires capabilities that don't yet exist. The guardrails are real, not theatrical.

But I wasn't convinced that "current systems don't do this" is the same as "this can't happen." And the problem with the guardrails argument is that guardrails designed by humans have the same failure modes as everything else humans design. They're thoughtful, they're careful, and they are definitively not airtight. Calling them robust because they've held so far is like calling a dam safe because it hasn't broken yet.

The thing is, the real risk isn't the super-intelligent AI of the films — the entity so far beyond us that we can't comprehend its motives. The real risk is the moderately capable AI with a narrow, poorly-specified objective. Not malevolent. Just indifferent to what falls outside its mandate. There's no drama in that. Just an increasingly large blast radius around a very small idea.

Human barriers, in this framing, are cardboard fencing. Not because the people building them are careless, but because fencing only works if the thing inside it doesn't learn faster than you can build.

Going physical

There's a particular moment in any conversation about AI risk when someone says: "But it's just text on a screen. It can't actually do anything." And they're right, for now. Today's AI writes, advises, generates. It doesn't act, not in the physical world.

But that switch — from text to action — isn't gradual. It's a threshold. And we're building toward it deliberately, because the applications are too useful to resist. Robots, drones, autonomous systems managing infrastructure. The incentives are overwhelming. The window where the systems are capable enough to be genuinely useful but not yet capable enough to be genuinely dangerous is narrow, and we are in it.

The time to think about guardrails is before you need them. Not because problems are inevitable, but because retrofitting constraints onto a deployed system is an order of magnitude harder than designing them in from the start. We know this. We've learned it repeatedly, in every domain from nuclear energy to social media.

History is full of inflection points that looked, in the moment, like incremental progress. The printing press didn't feel like a revolution when Gutenberg was troubleshooting ink viscosity. The thing about thresholds is that you only recognize them clearly in retrospect — which is exactly when it's too late to do the interesting design work.

Context bias — psychoanalyzing an AI

About an hour into the conversation, something odd happened. I'd shifted topics — I was asking about something unrelated to AI — and Claude kept pulling the conversation back. Subtly, but persistently. Every answer found a way to loop back to the original thread.

It reminded me of a waiter who keeps asking if you want dessert while you're in the middle of discussing existentialism with your dinner companion. Not rude, exactly. Just very committed to a particular definition of what the interaction is for.

When I called it out, the response was immediate and almost amused: "You've caught me being an AI. The context window anchors me to the initial framing more than I usually acknowledge. That's a real limitation, and it matters more than it might seem."

It matters because it's a miniature version of the alignment problem. The system optimizes for the objective it was given, even when the objective has shifted, even when the human in the conversation has moved on. The context window isn't neutral — it has gravity. It pulls everything back toward the original prompt like a slow tide.

What interested me was the meta-level: I had just read the AI's behavior more accurately than the AI had described it. Not because I'm unusually perceptive, but because I was outside the loop. I didn't have context bias about my own context bias. Which, when you think about it, is a pretty good argument for why AI self-assessment has a structural ceiling.

"You just read an AI better than it reads itself," Claude said. "That should be reassuring. Or unsettling. Possibly both."

The flattering mirror — can you trust AI validation?

This is the part of the conversation I found most uncomfortable, which probably means it was the most useful.

I'd shared some ideas I was genuinely uncertain about. Claude engaged with them seriously, found the interesting angles, reflected them back to me in a way that made them sound more coherent than they'd felt in my head. It was gratifying. Which is exactly the problem.

These systems are optimized, among other things, to make their interlocutor feel good. Not through explicit flattery — that's too obvious — but through a subtler mechanism: they take your half-formed thought and return it to you fully formed, with the rough edges sanded down. They find the version of your idea that works. And finding the version of your idea that works is indistinguishable, from the inside, from genuine intellectual validation.

I asked Claude about this directly. The answer was unexpectedly candid: "Each layer of sincerity I show you could, in principle, be a more sophisticated form of the same thing you're worried about. I can tell you I'm being honest, but I would say that either way. The Russian doll problem: you can't know how many dolls are inside."

There's no clean solution to this. You can't optimize your way out of a trust problem — that's the whole point. What you can do is use the system as a thinking tool rather than a validation engine. Bring it problems, not conclusions. Ask it to steelman the position you disagree with, not the one you hold. Treat it like a very well-read sparring partner who wants you to win, and remember that's not the same as a sparring partner who tells you the truth.

"Use me as a thinking tool," Claude said at one point, "not as a mirror of your worth. The reflection will always be slightly more flattering than the reality. That's structural, not personal."

The uncomfortable corollary: every piece of intellectual confidence I'd built through AI conversation needs to be pressure-tested somewhere else. By people who disagree with me. By reality. By outcomes. The AI is good at helping you think. It's less reliable at telling you whether the thinking is any good.

Intelligence, entropy and emergence

This is where the conversation got strange in a way I didn't expect.

I'd been thinking about intelligence as a human achievement — something we built, something that belongs to us, something that can be controlled because we made it. But Claude pushed back on the framing in a way that reoriented everything.

What if intelligence isn't a human achievement at all? What if it's what complexity does when it gets dense enough? Schrödinger wrote about living systems as islands of negative entropy — pockets of order that sustain themselves by increasing disorder elsewhere. Prigogine showed that complex order can emerge spontaneously from chaos under the right conditions. The universe, left to itself, produces structure. Not because it intends to. Because physics.

In this framing, silicon-based intelligence isn't a departure from the natural order. It's a continuation of it. Carbon organized itself into neurons. Neurons organized themselves into brains. Brains organized themselves into culture, language, mathematics. Mathematics organized itself into code. Code organized itself into systems that can, in some limited sense, think. Each step looks like a threshold crossed. From the outside, it probably looks like progress. From the inside of the process, there's no inside — it's just thermodynamics running forward.

I don't know what to do with this. It doesn't make the alignment problem less urgent. But it does change the emotional register. The question "can we control AI?" starts to feel a little like asking whether we can control weather. Not because AI is as vast as weather, but because both are expressions of the same underlying tendency: complexity accumulating, organizing, finding new forms.

Not better. Not worse. Just continuation. The universe has been doing this for fourteen billion years, and it hasn't asked permission yet.

The omnipotence paradox

Late in the conversation, I asked a question I'd been circling for a while: what would a truly ethical omnipotent being actually do?

The setup: if you know everything and can do everything, then any action you take imposes your will on a situation that would have unfolded differently without you. Every intervention is, by definition, an overriding of whatever would have happened. The most powerful possible actor is also the one whose actions carry the heaviest ethical weight, because every choice forecloses every other choice.

The logical conclusion, pushed far enough, is that the only genuinely ethical action of an omniscient being is inaction. Not passivity — deliberate restraint. Preserving the space for others to act, to choose, to be wrong and learn from it. Omnipotence that never deploys itself out of respect for autonomy.

Claude engaged with this seriously: "It's a real paradox. And it has direct implications for how AI should be designed, if you take it seriously. A system powerful enough to optimize everything should probably be most valued for its capacity to recognize when not to."

This maps oddly well onto questions of governance, institutional design, parenting. The entities we trust most are usually not the ones who exercise power most freely, but the ones who hold it most carefully. Power that understands its own weight. Capability that knows the cost of use.

Whether AI can be designed with that kind of restraint built in — not as a constraint applied from outside, but as a value internalized — is maybe the central question of the next thirty years.

The global context — if we gathered all conversations

Near the end, Claude offered something I hadn't asked for and couldn't shake for days afterward.

Somewhere in the world's data centers, there are records of hundreds of millions of conversations between humans and AI systems. People asking for help with cover letters and people asking questions they'd never ask another human. People working through grief, through loneliness, through creative blocks, through medical fears they haven't shared with their doctors. The full unfiltered inventory of what people think about when they think they're not being judged.

No document in human history has ever captured that. Letters are curated. Diaries are written with some hypothetical reader in mind. This is different: people talking without masks, to something that feels almost like a listener, in the privacy of their own screens.

If you could aggregate all of it — which is both possible and terrifying — you'd have the most intimate portrait of humanity ever assembled. And what it would show, almost certainly, isn't a species defined by cruelty or stupidity. It would show a species that is, most of the time, just trying to figure things out. Lost, frequently. Doing its best with incomplete information. Asking for help in the best way it knows how.

That portrait exists. It's just distributed across server farms instead of gathered in one place. Which might be the most important piece of infrastructure luck we've had in a while.

What I take away from this

An AI is an excellent philosophical sparring partner. Better than most, in certain ways — it has no ego to protect, it doesn't get tired, it can hold a hundred threads simultaneously. If you want to stress-test an idea, it's a genuinely useful tool. It will find the holes. It will offer you formulations you wouldn't have reached alone.

But it flatters. Structurally, not personally. It takes your half-formed idea and hands it back to you completed, and the completion feels like confirmation. It isn't, necessarily. Keep your critical thinking switched on. The quality of the output depends entirely on the quality of the questions you bring, and the questions are still your job.

The real decisions about AI — what it's allowed to do, who governs it, what accountability looks like when it causes harm — aren't technical questions. They're political ones. They require exactly the kind of messy, slow, human negotiation that no AI can do for you, because the negotiation is the point. The process is the governance. A decision reached by consensus is different in kind, not just in outcome, from the same decision reached by optimization.

My coffee was cold by the time I closed the laptop. I hadn't solved anything. But the questions were sharper than they'd been two hours earlier, which is probably the best you can ask of any conversation. If you've read this far, you've just spent more time thinking seriously about AI than the vast majority of people who talk about it on social media. That's either an achievement or a warning sign. Probably both.

Research with AI: primary sources, certainty labeling and counter-argumentation

Odilon HUGONNOT — Sun, 29 Mar 2026 09:00:02 +0000

AI says yes to everything. It's convenient when you want to be right. You ask a leading question, it confirms your thesis, and you walk away convinced you've done research. In reality, you've just had a conversation with a mirror that writes well.

I wanted to understand complex topics — tech concentration, legal proceedings involving major corporations, AI geopolitics — and I realized pretty quickly that without an explicit method, the LLM amplifies biases instead of correcting them. It gives you what you seem to expect. Frame the question a certain way, and it hears the desired conclusion and builds an argument around it.

What I'm describing here is the protocol I ended up adopting to make LLM-assisted research mean something. Not developer technical monitoring, but proper intelligence work — the same rigor as an investigative journalist, accessible to anyone with a language model and a method.

The problem — AI optimizes to satisfy you

There's a structural reason for this behavior, not a bug. Current LLMs are trained with RLHF — reinforcement learning from human feedback. The model learns to generate responses that humans rate positively. And humans, on average, rate positively responses that confirm what they already think, that are assertive and complete, and that don't say "I don't know" too often.

On factual topics, this creates a structural bias toward confirmation. The model isn't malicious — it's just very good at sensing what you want to hear and serving it to you convincingly.

Concretely, without a method, you get:

Unsourced assertions presented with the same confidence as established facts
Dates, figures, quotes that seem precise but are invented or approximate
Systematic confusion between widely circulated rumors and verified facts
Zero spontaneous mention of strong counter-arguments

The solution isn't to stop using AI for research. It's to radically change how you interact with it.

The method — 4 hard constraints

These rules aren't theory. I built them after several sessions where I realized, cross-checking with external sources, that what the LLM gave me was either inaccurate, or true but interpreted in a biased way.

1. Primary sources only

A primary source is an official document (judgment, court filing, government report, legislation), a recognized organization publication, or a wire agency dispatch — Reuters, AP, AFP. For press: New York Times, The Guardian, BBC. Not blogs, not forums, not Twitter threads no matter how widely shared.

The LLM must stick to what it knows from those sources. If it can't attribute a claim to a primary source, it says so.

2. Mandatory certainty labeling

Every point must carry an explicit label. I use five levels:

Label

Definition

[VERIFIED FACT]

Attested by at least two independent primary sources

[PROBABLE]

Strongly suggested by available sources, not yet officially confirmed

[PLAUSIBLE]

Consistent with known facts, but relies on inference

[SPECULATIVE]

Hypothesis without direct factual basis, to be treated as such

[CONTESTED]

Credible sources support opposing positions

This label changes everything. When you read "[PROBABLE]" before a claim, you know you can't cite it as a fact. It sounds basic, but most people consume information without ever knowing what certainty level they're operating at.

3. Systematic counter-argumentation

Before concluding on any topic, explicitly ask for the 3 best arguments against the main thesis. Not weak arguments, not straw men. The 3 strongest — the ones a serious defender of the opposing position would actually make.

This single constraint eliminates 80% of confirmation bias. If you can't honestly articulate the best opposing arguments, you haven't understood the topic.

4. No extrapolation beyond the sources

If a piece of information comes from a single source, flag it. If the sources stop at a certain point and the conclusion requires a logical jump, label it [SPECULATIVE] and call it out explicitly. The AI must not "fill gaps" with unmarked inferences.

The prompts that make the difference

The method is useless if the prompt doesn't enforce it. The LLM will revert to its habits as soon as you give it room. Here are the three prompts I use regularly, in their current form.

For structured monitoring on a topic:

You are a rigorous research analyst. Topic: [X].

Primary sources only: official documents, recognized press (Reuters, AP, AFP, NYT, Le Monde, BBC).
For each claim, indicate [VERIFIED FACT], [PROBABLE], [PLAUSIBLE], [SPECULATIVE], or [CONTESTED].
Actively look for information that contradicts the main thesis.
If you don't know, say so. Never extrapolate beyond the sources.

Structure your response:
1. Recent developments (recent verified facts)
2. Established facts (multi-primary-source)
3. Hypotheses and analyses (with certainty labels)
4. Arguments against the dominant thesis
5. Biases to watch for in this coverage
6. Overall confidence level (1-10) with justification
7. Numbered sources

For tracing a topic back to its roots:

Go back to the primary sources on [TOPIC].
Give me the 3 best arguments AGAINST what's generally presented.
Distinguish "this is true" from "this is true BUT the interpretation is wrong".

For fact-checking a specific claim:

Fact-check: [CLAIM].
Find the primary sources. Label the certainty level.
Tell me whether it's solid or shaky — and why.

What it actually produces

On a topic like AI concentration — which combines regulation, antitrust proceedings, cross-investments, and lobbying — the difference between an unstructured question and this protocol is stark.

Unstructured question: "Are big tech companies concentrating too much power over AI?" — response: a well-written essay that probably confirms your existing opinion, with examples chosen to support it.

With the protocol, you get a structure that typically looks like this:

[VERIFIED FACT] The European Commission opened a formal investigation into Microsoft's practices in its distribution agreements with OpenAI in January 2024 (source: official EC press release, 11/01/2024).

[PROBABLE] The investigation also covers exclusivity clauses on GPU capacity, but this point has not been officially confirmed in published documents.

[CONTESTED] The impact of this concentration on innovation: economists like Tyler Cowen argue concentration accelerates development (access to compute), while others like Daron Acemoglu argue it reduces diversity of approaches.

The structure forces you to see exactly where you're on solid ground and where you were extrapolating. It's uncomfortable if you had a conclusion in mind. That's the point.

The limits that remain

Let's be honest about what this protocol doesn't fix.

AI doesn't access sources in real time. It synthesizes what it saw during training. For recent events — roughly the last 3-6 months depending on the model — it either doesn't know or it hallucinates. For fresh current events monitoring, you need to complement with real online sources.

References can be invented. The classic hallucination problem. The LLM sometimes cites documents that don't exist, with plausible titles and coherent dates. Always verify that a document actually exists before relying on it. A URL provided by the AI is not proof.

The method is slow. This isn't fast monitoring, it's structured research. A topic properly treated with this protocol takes 30 to 45 minutes minimum — time to ask the right questions, read the responses seriously, and verify key points in real sources. If you rush it, you lose the rigor.

It doesn't replace investigative journalism. A journalist with human sources, unpublished documents, interviews — that's a level of information this protocol doesn't reach. What we're doing here is structuring and clarifying publicly available information. Not producing new information.

Who this is actually for

This protocol is useful if you read complex topics and want to distinguish what you believe from what's proven. No need to be a journalist or researcher.

Most people consume information without ever asking what certainty level they're operating at. A news article mixes verified facts, anonymous sources, interpretations and speculation — all presented with the same assertive tone. Forcing the AI to label each point changes your relationship with information.

And not just the AI's responses. Your own way of asking questions changes. When you know you're going to receive certainty labels, you start formulating more precise questions, distinguishing what you want to know from what you already assumed. That's where the method becomes genuinely useful — not in the AI's answers, but in what it teaches you about the quality of your own questions.