The hype machine

Let's start with the terminology. The industry keeps calling it "AI" as if we're dealing with actual intelligence. We're not. These are generative language models trained on statistical patterns. Calling it AI is arguably the biggest marketing scam of our decade. It sounds impressive, it sells tokens, and it makes everyone feel like the future has arrived. But precision in language matters, especially for engineers.

Now look at who's pushing the "I never code anymore" narrative. Most of them carry titles like "AI Engineer", "AI Trainer", or "AI Consultant." Their livelihood depends on the hype. Are they being honest, or is this only self-marketing? It's hard to tell. And that's part of the problem.

Then there are the AI providers themselves. They have every incentive to make us believe that coding is becoming obsolete. More belief in full automation means more token consumption. Are they being honest about what their tools can and can't do? You can decide for yourself.

Sometimes also it feels like this is the revenge of low-skill developers. Those who never invested in understanding software design, architecture, or maintainability now claim the playing field has been leveled. But producing code and engineering software are two very different things. These are the same people who produce spaghetti code in record time, which makes managers so happy. However, they leave the company after a few months, leaving behind a huge technical debt. Continuous illusion of hardworking and productive managers and “experts“.

The danger hidden in the darkness

Here's something that should concern every serious developer: the more you rely on GenAI to write your code, the more your own skills degrade. It's a slow process. You stop thinking through problems because the tool gives you an answer in seconds. You stop learning patterns because you never need to write them from scratch. One day you realize you can't debug the code your own tool generated or even you can't prompt because you no longer deeply understand what's happening.

And the code itself? It's not always good. GenAI doesn't understand your domain, your constraints, or the long-term consequences of its choices. As the codebase grows, the generated code becomes a nightmare to maintain and debug.

This has a broader consequence that few people discuss: innovation and open-source could suffer from this. GenAI struggles with anything outside the well-trodden path. It works best with mainstream frameworks and popular libraries because that's what it was trained on. If developers increasingly depend on it, who will build the next unconventional framework or library? Who will challenge existing paradigms? The tools are biased toward the average, and they'll push us all in that direction if we let them.

The false promise of techniques

"Just use agentic loops." "Just write specs and let the AI implement them." "Just do test-driven development with AI." "Just follow the latest Anthropic hype" I've heard all of these, and I've tried most of them. They work for some cases, but they are not sustainable for everything.

These techniques add layers of complexity. You end up spending as much time steering the GenAI, reviewing its output, fixing its mistakes, and re-prompting as you would have spent writing the code yourself. Sometimes more. The illusion of productivity is strong, but the reality is often different.

What GenAI actually does

I believe GenAI is not intended to generate code for humans. It generates code that is statistically close to what you ask for. It's reproducing patterns it has seen before, not solving problems. It doesn't reason about your architecture. It doesn't understand why a particular design decision matters.

But is this a problem? Not always. For some use cases, "statistically close" is perfectly fine. It's OK to have a verbose and twisted code as long as the LLM can understand it with minimal token consumption.

And that's where we need to be strategic.

Domain Driven Design to the rescue, again

If you're familiar with Strategic Domain Driven Design, you know that not all parts of a software system carry the same weight. DDD distinguishes between:

• Core domains: where your business differentiates itself. This is where competitive advantage lives and where the deepest understanding of the problem is required.

• Supporting domains: necessary but not differentiating. They support the core but don't define your business.

• Generic domains: solved problems. Authentication, email sending, CRUD operations, standard integrations.

This distinction is exactly what we need to decide where GenAI belongs.

Supporting domains, sometimes generic domains, or small microservices are good candidates for GenAI-assisted development. The patterns are known, the stakes are lower, and "good enough" is truly good enough. You don't even need to read or fully understand every line of the generated code, as long as it works and passes tests, it serves its purpose. Let the tool do the heavy lifting there.

But for core domains, it's the opposite. We should absolutely resist the temptation to hand over control. This is where your deepest business logic lives. This is where subtle bugs cost real money. This is where you need to understand every line of code, and where "statistically close" is not acceptable.

In core domains, GenAI should be limited to:

• Completing a function you've already started writing

• Simplifying or optimizing an existing piece of code

• Replicating a well-written feature following patterns you've established

• Handling repetitive code that follows a clear, validated structure

In other words, you lead, the tool follows. Not the other way around.

I wrote previously about the right way to code with GenAI that you can check out.

Stop following the hype

I'm tired of the trends. I'm tired of the breathless LinkedIn posts. After testing many solutions and approaches, I've found my own way of using GenAI, and it starts with being honest about what it can and can't do.

The developers who will build lasting software are those who keep their skills sharp, think critically about their tools, and refuse to let marketing narratives dictate how they work. GenAI is useful. It's not magic. And treating it as magic is how you end up with a codebase nobody can maintain, not even the GenAI itself.

If you work on multiple projects with different tool versions and many repetitive tasks, you know how messy things can get. One project needs Node 20, another needs Node 22. You have dozens of npm scripts, shell commands, and environment variables. This is where mise comes in. Mise replaces tools like nvm, pyenv, make, and even brew or parts of npm scripts. It gives you one simple tool to manage everything.

👉 https://mise.jdx.dev

Tools

The first pillar of mise helps you manage installations of programming language runtimes and other tools.

Local vs Global Tools

Mise distinguishes between local (project-specific) and global (user-wide) tools.

Local tools are defined in your project's mise.toml file:

[tools]
node = "25"
rust = "latest"

When you run mise use node@25 in a project directory, it updates the local mise.toml file.

Global tools are defined in your home configuration (~/.config/mise/config.toml). Use the -g flag to install globally: mise use -g node@latest.

Global tools serve as defaults when no local configuration exists. This means you can have Node 25 as your global default, but a specific project can override it with Node 22.

When Mise is activated in your shell, it modifies your PATH to prioritize the correct tool versions.

Registry: Hundreds of Tools Ready to Use

Mise includes a registry with hundreds of pre-configured tools. You can use simple shorthand names.

# Install without activating
mise install -g pnpm@9

# Search for tools
mise registry | grep opencode
mise use -g opencode

# Or the built-in search and use
mise use -g

# Shows outdated tool versions
mise outdated

# Upgrades outdated tools
mise up

# Run a command with specific tools
mise exec python@3.12 -- ./myscript.py

# See which tools are active
mise current

# List all installed tools
mise ls

Backends: Install Tools from Anywhere

When a tool is not in the registry, mise can install it from various backends. They are different sources where mise can find and install tools. Such as npm, dotnet, or even directly from github or http.

For instance, as I use Linux Fedora Cosmic Atomic, but Ghostty terminal is not yet available in flatpak, I can easily install it with Mise and track updates alongside my other tools:

# mise use -g github:pkgforge-dev/ghostty-appimage
# or modify ~/.config/mise/config.toml
[tools."github:pkgforge-dev/ghostty-appimage"]
version = "latest"
bin = "ghostty" # to rename the binary and remove the version number

Then adding the icon manually (~/.local/share/applications/ghostty.desktop):

[Desktop Entry]
Type=Application
Name=Ghostty
Exec=/home/akhansari/.local/share/mise/installs/github-pkgforge-dev-ghostty-appimage/latest/ghostty
Icon=/home/akhansari/Pictures/icons/ghostty.png

Environments

The second pillar of mise helps you manage environments.

Every project needs environment variables: database URLs, API keys, feature flags, and more. Managing these across local development and other envs is often messy. Mise solves this problem by making environment variables part of your project configuration.

Add environment variables to the [env] section of your project’s Mise configurations:

# mise.toml (in git)

[env]
APP_ENV = { required = true }
# Or with helpful message
DATABASE_URL = { required = "Connection string for PostgreSQL. Format: postgres://user:pass@host/db" }

# mise.local.toml (gitignore)

[env]
APP_ENV = "development"
DATABASE_URL = "postgres://root:root@localhost"

# Helpers

[env]
# Templates
DATABASE_URL = "postgres://root:root@localhost/{{env.APP_ENV}}"
# Protecting sensitive values
API_KEY = { value = "super-secret-key", redact = true }

When you enter the project directory, these variables are automatically set. When you leave, they are unset. No more forgetting to export variables or polluting your global shell environment.

Tasks

The third pillar of mise is the task runner. It’s like Make but better.

Every project has commands you run repeatedly: start the dev server, run tests, build for production, deploy. These commands often live in different places, npm scripts, shell scripts, Makefiles, or just in your memory. Mise brings them all together in one place.

The best part? Tasks automatically have access to your mise environment. Your tools are on PATH, your environment variables are set. No more "command not found" errors because you forgot to activate something.

Defining Tasks

Tasks live in the [tasks] section of your mise.toml. Each task has a name and a command to run:

[tasks.serve]
run = "pnpm run serve"

[tasks.test]
run = "pnpm run vitest"

[tasks.build]
run = "pnpm build"

[tasks.iac-apply]
description = "Creates or updates infrastructure"
dir = "./iac"
run = "tofu apply"

Run any task with mise run:

# Run a task
mise run serve

# Or search and run
mise run

# Run a task including mise.staging.toml
mise --env staging run build

# Pass additional params
mise run test --help  # This will show the Vitest's help

Task Composition

Simple tasks are useful, but the real power comes from combining them. Mise offers two ways to compose tasks.

Sequential execution runs tasks one after another. If any task fails, the chain stops:

[tasks.check-backend]
run = "pnpm --filter backend check"

[tasks.check-frontend]
run = "pnpm --filter frontend check"

[tasks.check]
run = [
  { task = "check-backend" },
  { task = "check-frontend" }
]

Dependencies ensure prerequisite tasks run first. Use depends when a task always needs something else:

[tasks.podman-push]
depends = "podman-login"
run = [
  { task = "podman-push-backend" },
  { task = "podman-push-frontend" }
]

The difference is subtle but important:

• Sequential (run): "Run A, then B, then C"

• Dependencies (depends): "Before running this, make sure X is done"

Conclusion

Dev Tooling is full of small annoyances: wrong tool versions, missing environment variables, forgotten commands, inconsistent setups between team members. Each problem is small, but together they waste hours every week.

Mise eliminates these problems with three simple ideas:

1. Dev Tools: Define your tool versions in code. Switch automatically when you change directories. And manage your global dev tools.

2. Environments: Keep environment variables with your project, not scattered across shell configs and .env files. Validate them before things break.

3. Tasks: Put your commands in one place. Compose them into pipelines. Make your CI configuration trivial.

That is what "mise en place" means: everything in its place, ready to go.

Let's return to our Contact type from the previous articles. Thanks to our refactoring, it's now well-structured:

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    emailContactInfo: EmailContactInfo,
    postalContactInfo: PostalContactInfo,
}) {}

Now let's say we have a simple business rule: "A contact must have an email or a postal address”. Does our type conform to this rule?

The answer is no. The business rule implies that a contact might have an email address but no postal address, or vice versa. But as it stands, our type requires that a contact must always have both pieces of information.

The naive approach

The answer seems obvious, make the addresses optional:

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    emailContactInfo: Schema.optionalWith(EmailContactInfo, { as: "Option" }),
    postalContactInfo: Schema.optionalWith(PostalContactInfo, { as: "Option" }),
}) {}

But now we've gone too far the other way. In this design, it would be possible for a contact to have neither type of address at all. But the business rule says that at least one piece of information must be present.

What's the solution?

Making illegal states unrepresentable

If we think about the business rule carefully, we realize there are three possibilities:

1. A contact only has an email address

2. A contact only has a postal address

3. A contact has both an email address and a postal address

Once we put it like this, the solution becomes obvious. Use a union type with a case for each possibility. In Effect, we can model this elegantly using Schema.Union:

class EmailOnly extends Schema.TaggedClass<EmailOnly>()("EmailOnly", {
    email: EmailContactInfo,
}) {}

class PostOnly extends Schema.TaggedClass<PostOnly>()("PostOnly", {
    post: PostalContactInfo,
}) {}

class EmailAndPost extends Schema.TaggedClass<EmailAndPost>()("EmailAndPost", {
    email: EmailContactInfo,
    post: PostalContactInfo,
}) {}

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    contactInfo: Schema.Union(EmailOnly, PostOnly, EmailAndPost),
}) {}

This design meets the requirements perfectly. All three cases are explicitly represented, and the fourth possible case (with no email or postal address at all) is not allowed.

How to use

Now let's see how we might use this in practice:

function createEmailOnlyContact(model: {
    firstName: string
    lastName: string
    email: string
}): Effect.Effect<Contact, Brand.Brand.BrandErrors, never> {
    return Effect.gen(function* () {
        const emailAddress = yield* EmailAddress.either(model.email)
        return new Contact({
            name: new PersonalName({
                firstName: model.firstName,
                middleInitial: Option.none(),
                lastName: model.lastName,
            }),
            contactInfo: new EmailOnly({
                email: new EmailContactInfo({
                    emailAddress,
                    isEmailVerified: false,
                }),
            }),
        })
    })
}

function getEmailAddress(contact: Contact): Option.Option<EmailAddress> {
    return Match.value(contact.contactInfo).pipe(
        Match.tag("EmailOnly", "EmailAndPost", ({ email }) =>
            Option.some(email.emailAddress)
        ),
        Match.tag("PostOnly", () => Option.none()),
        Match.exhaustive
    )
}

function updatePostalAddress(
    contact: Contact,
    newPostalAddress: PostalContactInfo
): Contact {
    const newContactInfo = Match.value(contact.contactInfo).pipe(
        Match.tag("EmailOnly", "EmailAndPost",
            ({ email }) => new EmailAndPost({ email, post: newPostalAddress })
        ),
        Match.tag("PostOnly",
            () => new PostOnly({ post: newPostalAddress })
        ),
        Match.exhaustive
    )
    return new Contact({
        name: contact.name,
        contactInfo: newContactInfo,
    })
}

The Match.exhaustive at the end ensures that if we ever add a new case to our ContactInfo union, the compiler will immediately tell us about every place we need to handle it.

Why bother with these complicated structure?

At this point, you might be saying that we've made things unnecessarily complicated. I would respond with these points:

First, the business logic is complicated. There is no easy way to avoid it. If your code is not this complicated, you're not handling all the cases properly.

Second, if the logic is represented by types, it is automatically self-documenting. You can look at the union cases below and immediately see what the business rule is. You don't have to spend any time trying to analyze any other code:

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    contactInfo: Schema.Union(EmailOnly, PostOnly, EmailAndPost),
}) {}

Just from reading this type definition, you know: a contact can have email only, postal address only, or both, but never neither.

Third, if the logic is represented by a type, any changes to the business rules will immediately create breaking changes, which is generally a good thing. If you add a fourth case, say PhoneOnly, the compiler will point out every place in your code-base where you need to handle it.

Fourth, as mentioned in previous posts, the Effect adds additional values to TypeScript types by default, including structural equality, immutability, validation and serialization, exhaustive pattern matching, compositions, and pipelines.

Conclusion

The key insight is this: when you find yourself using optional fields with implicit dependencies between them, consider whether a union type would better represent your domain.

Instead of writing code that checks if (contact.email && !contact.postalAddress), you write code that handles each explicit case. The compiler ensures you handle them all, and the types document what states are actually possible.

This is what "Making illegal states unrepresentable" means in practice. It's not about writing more code, it's about writing code where the wrong code simply won't compile.

In the next article, we'll explore how applying this principle can lead to discovering new domain concepts that weren't obvious at first.

This article was inspired by Scott Wlaschin's excellent "Designing with types" series on F# for Fun and Profit, adapted for the TypeScript and Effect ecosystem.

… study shows more than 800 popular GitHub projects with code quality degrading after adopting AI tools. … there’s a real risk that newer models will reinforce and amplify those trends, producing even worse code over time. - Rob Bowley

You are the developer, not the GenAI

The most important principle is simple: GenAI is your assistant, not the one that controls you and dictates what you should do. This might sound obvious, but it's easy to fall into the opposite pattern. When you start accepting AI suggestions without understanding them, or when you shape your work around what the AI can produce, the roles have reversed. You've become the assistant to your own tool, trapped in illusion of productivity.

A good relationship with GenAI looks like this: you decide what to build, you set the standards, and you validate the output. The AI handles the mechanical parts. Think of it like having a junior developer who types very fast but needs supervision.

Let GenAI handle the repetitive work

GenAI shines when the task is repetitive and well-defined. Writing boilerplate code, generating new code for known patterns, refactoring, converting data formats, or creating a handler for your service, these are perfect use cases. The pattern already exists, and you just need more of it.

Here's something many developers overlook: LLMs are trained on vast amounts of code from the internet, and most of that code is average at best. The AI learned from millions of mediocre examples. GenAI is better at reproducing patterns than creating excellent new ones.

The practical consequence? Write good code yourself first. Establish your patterns, your conventions, your architecture. Then let GenAI replicate what you've created. When it has your high-quality examples as context, it produces much better results than when it works from its general training alone. New GenAI tools add your existing code into the context before cooking a new one.

Grow your knowledge, don't outsource It

It's tempting to let GenAI handle everything you don't understand. Don't! Every time you accept code you can't explain, you create technical debt in your own mind. You become dependent on a tool to maintain your own project.

Instead, use GenAI as a learning accelerator. Ask it to explain or find concepts. Have it break down complex algorithms step by step. Use it to explore different approaches to the same problem. The goal is to understand more after each interaction, not less.

A developer who uses GenAI well ends up knowing more than before. A developer who uses it poorly ends up knowing less while producing more code, a dangerous combination.

Write new things yourself first

When you're building something genuinely new, like a novel algorithm, a unique business logic, your software architecture, or a creative solution, write it yourself first. Your initial version might be rough, but it will be authentically yours. It will reflect the context and your actual understanding of the problem.

Once you have working code, then bring in GenAI. Ask it to review your solution. Have it suggest optimizations. Let it simplify complex sections. This approach gives you two benefits: you maintain deep understanding of your code, and you get the AI's help making it better and you learn from it.

The reverse approach, asking GenAI to write novel code from scratch, often produces something that looks right but misses important details. The AI doesn't understand your specific context the way you do.

A surprisingly good Rubber Duck

Perhaps the most underrated use of GenAI is as a thinking partner. Traditional "rubber duck debugging" involves explaining your problem to an inanimate object to clarify your thoughts. GenAI takes this further because it actually responds.

Use GenAI to organize your thoughts before writing code. Describe the domain you're modeling and ask it to identify potential challenges. Explain a problem you're stuck on and let it ask clarifying questions. Discuss different architectural options and their trade-offs.

This kind of dialogue often reveals gaps in your thinking without any code being written at all. The AI serves as a mirror that helps you see your own ideas more clearly.

Context is everything

Here's a truth that separates effective GenAI users from frustrated ones: the quality of output depends almost entirely on the quality of context you provide. An LLM without context is like a skilled contractor who shows up with no blueprints. They might build something, but probably not what you need.

Good context means giving the AI everything it needs to understand your world. There are several ways to do this:

• Plan mode before edit mode. Tools like Open Code or Claude Code offer a plan mode. Use it to discuss and validate the approach before the AI touches any files. This back-and-forth clarifies context and catches misunderstandings early.
  For complex tasks, start with high-level domain context, then narrow to the specific module, then to the exact problem.

• Dedicated context files. Tools now support files like AGENTS.md in your repository. Define your architecture, conventions, and constraints once, and every AI interaction benefits.

• System prompts. When available, use them if necessary to establish the role, standards, and boundaries the AI should follow.

The investment in good context pays off quickly. You spend less time correcting mistakes and more time on work that matters. Strategic Domain Driven Design shines even more in the GenAI era.

The bottom line

GenAI is a powerful tool, but tools don't make decisions, developers do. Use it for repetition, not creation. Use it to learn, not to avoid learning. Let it help you think, not think for you.

email: string
zipCode: string
stateCode: string

These fields are all defined as simple strings. But are they really just strings? Can you accidentally swap an email address with a zip code? In a type-safe world, this should be impossible.

In domain-driven design, an email address and a zip code are distinct concepts, not interchangeable strings. We want separate types so they can't be mixed up by mistake.

This has been known as good practice for years, but in many languages, creating hundreds of tiny wrapper types feels painful. This leads to "primitive obsession". The code smell where developers use primitive types everywhere instead of creating meaningful domain types.

With TypeScript and Effect, we have no excuse! It's straightforward to create these wrapper types, and Effect gives us powerful tools for validation and error handling.

Creating Wrapper Types with Branded Types

The simplest way to create a distinct type is to use TypeScript's branded types pattern. Effect provides built-in support for this through Brand:

import { Brand } from "effect"

type EmailAddress = string & Brand.Brand<"EmailAddress">
type ZipCode = string & Brand.Brand<"ZipCode">
type StateCode = string & Brand.Brand<"StateCode">

These are still strings at runtime, but TypeScript treats them as incompatible types at compile time. You can't accidentally pass a ZipCode where an EmailAddress is expected.

Simple Cases with Brand.nominal

If you don't need validation and just want to distinguish types at compile-time, use Brand.nominal:

const UserId = Brand.nominal<UserId>()
const ProductId = Brand.nominal<ProductId>()

function getUser(id: UserId) {
    /* ... */
}
function getProduct(id: ProductId) {
    /* ... */
}

const userId = UserId(42)
const productId = ProductId(42)

getUser(productId) // ❌ Type error
getUser(userId) // ✅ OK

The nominal constructor doesn't do any runtime checks. It just adds the type brand. Use this when you want type safety without validation overhead.

It's also possible to use Brands as part the Schema:

class User extends Schema.Class<User>("User")({
    userId: Schema.String.pipe(Schema.brand("UserId")),
    name: Schema.String,
}) {}

Adding Validation with Brand.refined

For types that need validation (smart constructors), Effect's Brand.refined function lets you create branded types with built-in validation:

The refined function takes two parameters:

1. A predicate function that returns true if the value is valid

2. An error function that creates a BrandErrors when validation fails

Let's create refined constructors for our domain types:

type EmailAddress = string & Brand.Brand<"EmailAddress">

const EmailAddress = Brand.refined<EmailAddress>(
    (value) => /^\S+@\S+\.\S+$/.test(value),
    (value) => Brand.error(`"${value}" is not a valid email address`)
)

Notice how validation is defined through predicate functions. Once you have an EmailAddress instance, you know it's valid. The type system guarantees it.

Validation Constructors

The very basic usage is to call the constructor directly. This will throw an exception if validation fails.

EmailAddress("john@example.com")

But it is better to handle it gracefully. Effect provides several approaches, each with different trade-offs.

Sometimes you don't care about the specific error, just whether it succeeded.
The advantage here is simplicity. The disadvantage is losing error details. You don't know why validation failed.
It's usually best for numeric types or simple cases.

EmailAddress.option("john@example.com")

For detailed error information without exceptions, use either.
This gives you both success and failure information in a type-safe way.

EmailAddress.either("john@example.com")

Encapsulation and Type Safety

The beauty of branded types is that TypeScript prevents you from accidentally creating them without validation:

// ❌ This won't compile
const email: EmailAddress = "not-validated@example.com"

// ✅ Must go through the constructor
const email = EmailAddress("validated@example.com")

This ensures that invalid data can never enter your domain, even by accident.

When to Wrap and Unwrap

You should create these wrapped types at service boundaries:

• When wrapping: At the UI layer (form submissions), when loading from databases, or when receiving data from external APIs

    // external source
    const email = yield* EmailAddress.either(formInput.email)
    // trusted source
    const email = EmailAddress(formInput.email)
  

• When unwrapping: When persisting to databases, binding to UI elements, or sending data to external services

    const emailDto: string = email // of type EmailAddress
  

The key insight is that once data enters your domain as a wrapped type, it stays wrapped. You rarely need to "unwrap" it within your business logic. You can use it directly since it's still a string/number/etc. at runtime.

A Complete Example with Multiple Types

Let's refactor our contact system using these patterns:

import { Brand, Effect, Schema } from "effect"

type EmailAddress = string & Brand.Brand<"EmailAddress">
type ZipCode = string & Brand.Brand<"ZipCode">
type StateCode = string & Brand.Brand<"StateCode">

const EmailAddress = Brand.refined<EmailAddress>(
    (value) => /^\S+@\S+\.\S+$/.test(value),
    (value) => Brand.error(`"${value}" is not a valid email address`)
)

const ZipCode = Brand.refined<ZipCode>(
    (value) => /^\d{5}$/.test(value),
    (_) => Brand.error(`Zip code must be 5 digits`)
)

const StateCode = Brand.refined<StateCode>(
    (value) => {
        const normalized = value.toUpperCase()
        return ["AZ", "CA", "NY", "TX", "FL"].includes(normalized)
    },
    (_) => Brand.error(`State code is not in list`)
)

class PostalAddress extends Schema.Class<PostalAddress>("PostalAddress")({
    address1: Schema.String,
    address2: Schema.String,
    city: Schema.String,
    state: Schema.String.pipe(Schema.fromBrand(StateCode)),
    zip: Schema.String.pipe(Schema.fromBrand(ZipCode)),
}) {}

class PostalContactInfo extends Schema.Class<PostalContactInfo>("PostalContactInfo")({
    address: PostalAddress,
    isAddressValid: Schema.Boolean,
}) {}

class PersonalName extends Schema.Class<PersonalName>("PersonalName")({
    firstName: Schema.String,
    middleInitial: Schema.optionalWith(Schema.String, { as: "Option" }),
    lastName: Schema.String,
}) {}

class EmailContactInfo extends Schema.Class<EmailContactInfo>("EmailContactInfo")({
    emailAddress: Schema.String.pipe(Schema.fromBrand(EmailAddress)),
    isEmailVerified: Schema.Boolean,
}) {}

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    emailContactInfo: EmailContactInfo,
    postalContactInfo: PostalContactInfo,
}) {}

function createPostalAddress(model: {
    address1: string
    address2: string
    city: string
    state: string
    zip: string
}): Effect.Effect<PostalAddress, Brand.Brand.BrandErrors, never> {
    return Effect.gen(function* () {
        const state = yield* StateCode.either(model.state)
        const zip = yield* ZipCode.either(model.zip)
        return new PostalAddress({
            address1: model.address1,
            address2: model.address2,
            city: model.city,
            state,
            zip,
        })
    })
}

Guidelines Summary

To wrap up, here are the key principles:

• Use branded types to represent your domain accurately. Don't settle for primitive obsession.

• Validate at construction time with Brand.refined. Once created, branded types should always be valid.

• Use Brand.nominal for simple distinction without validation. When you just need compile-time type safety.

• Be explicit about validation failures. Use Effect's error handling to force callers to handle invalid cases.

• Leverage Effect's powerful abstractions. Brand, Schema, Either, and Option give you tools that make this pattern practical.

• Wrap at boundaries, keep wrapped throughout your domain. Validate once at the edge, trust the types internally.

Conclusion

Creating wrapper types with branded types might seem like extra work upfront, but it pays dividends:

• Compile-time safety: Catch bugs before runtime

• Self-documenting code: Types express domain concepts clearly

• Validation guarantees: Invalid data can't enter your domain

• Better refactoring: The compiler helps you when types change

• Zero runtime overhead: Brands are erased at runtime

There's no excuse for primitive obsession anymore!

This article was inspired by Scott Wlaschin's excellent "Designing with types" series on F# for Fun and Profit, adapted for the TypeScript and Effect ecosystem.

In this article, we'll explore how to use types as part of the design process in TypeScript, enhanced by the Effect library. The careful use of types can make your design more transparent and improve correctness at the same time.

We'll focus on the "micro level" of design working at the lowest level of individual types and functions. While many of these concepts are possible in plain TypeScript, Effect's functional primitives make this kind of refactoring more natural and powerful. We'll let the type system and Effect guide us toward better solutions.

Sometimes, the best code is the code that simply cannot compile if it's wrong.

The Starting Point

Let's work with a common example: a Contact type. Here's what a typical implementation might look like:

type Contact = {
    firstName: string
    middleInitial: string
    lastName: string
    emailAddress: string
    // true if ownership of email address is confirmed
    isEmailVerified: boolean
    address1: string
    address2: string
    city: string
    state: string
    zip: string
    // true if validated against address service
    isAddressValid: boolean
}

This looks straightforward, we've all seen something like this countless times. But how can we refactor this to make better use of the type system?

Understanding Data Relationships

The first step is to analyze how the data is accessed and updated. For instance, would you ever update zip without also updating address1? Probably not. On the other hand, you might frequently update emailAddress without touching firstName.

This leads to our first principle:

Use objects to group together data that must be consistent (atomic), but don't needlessly group unrelated data. In general, low coupling and high cohesion apply across all levels, from individual types and functions to the overall architecture.

In our Contact example, we can identify several natural groupings:

• The three name values form a cohesive set

• The address values belong together

• The email information is its own distinct set

We also have validation flags like isAddressValid and isEmailVerified. Should these be part of their related sets? Yes, because they're dependent on those values. If the emailAddress changes, isEmailVerified should probably reset to false at the same time.

Refactoring with Better Structure

Let's break down our monolithic Contact type. For the postal address, we can create two types: a generic PostalAddress and a context-specific PostalContactInfo that includes validation state.

class PostalAddress extends Schema.Class<PostalAddress>("PostalAddress")({
    address1: Schema.String,
    address2: Schema.String,
    city: Schema.String,
    state: Schema.String,
    zip: Schema.String,
}) {}

class PostalContactInfo extends Schema.Class<PostalContactInfo>("PostalContactInfo")({
    address: PostalAddress,
    isAddressValid: Schema.Boolean,
}) {}

Using Effect's Schema.Class provides structural equality and immutability out of the box. Two important properties for domain modeling.

Expressing Optionality with Effect's Option

In the original design, middleInitial is a string, but not everyone has a middle initial. Using an empty string to represent "no value" is a common pattern, but it's implicit and error-prone. Effect provides the Option type to explicitly signal optionality:

class PersonalName extends Schema.Class<PersonalName>("PersonalName")({
    firstName: Schema.String,
    middleInitial: Schema.optionalWith(Schema.String, { as: "Option" }),
    lastName: Schema.String,
}) {}

With optionalWith, we make it impossible to forget that a value might be absent. The type system forces us to handle both cases.

The Complete Refactored Design

Here's our fully refactored Contact type:

import { Option, Schema } from "effect"

class PostalAddress extends Schema.Class<PostalAddress>("PostalAddress")({
    address1: Schema.String,
    address2: Schema.String,
    city: Schema.String,
    state: Schema.String,
    zip: Schema.String,
}) {}

class PostalContactInfo extends Schema.Class<PostalContactInfo>("PostalContactInfo")({
    address: PostalAddress,
    isAddressValid: Schema.Boolean,
}) {}

class PersonalName extends Schema.Class<PersonalName>("PersonalName")({
    firstName: Schema.String,
    middleInitial: Schema.optionalWith(Schema.String, { as: "Option" }),
    lastName: Schema.String,
}) {}

class EmailContactInfo extends Schema.Class<EmailContactInfo>("EmailContactInfo")({
    emailAddress: Schema.String,
    isEmailVerified: Schema.Boolean,
}) {}

class Contact extends Schema.Class<Contact>("Contact")({
    name: PersonalName,
    emailContactInfo: EmailContactInfo,
    postalContactInfo: PostalContactInfo,
}) {}

Creating Instances

With Effect's Data classes, creating instances is clean and benefits from structural equality:

const contact = new Contact({
    name: new PersonalName({
        firstName: "John",
        middleInitial: Option.some("Q"),
        lastName: "Doe",
    }),
    emailContactInfo: new EmailContactInfo({
        emailAddress: "john@example.com",
        isEmailVerified: false,
    }),
    postalContactInfo: new PostalContactInfo({
        address: new PostalAddress({
            address1: "123 Main St",
            address2: "Apt 4B",
            city: "Springfield",
            state: "IL",
            zip: "62701",
        }),
        isAddressValid: false,
    }),
})

Working with Optional Values

Effect provides a rich API for working with Option types:

import { pipe } from "effect"

const displayName = pipe(
    contact.name.middleInitial,
    Option.match({
        onNone: () => `${contact.name.firstName} ${contact.name.lastName}`,
        onSome: (initial) => `${contact.name.firstName} ${initial}. ${contact.name.lastName}`,
    })
)

const initial = pipe(
    contact.name.middleInitial,
    Option.getOrElse(() => "")
)

The Benefits

We haven't written a single business logic function yet, but our code already better represents the domain. The refactored design gives us:

1. Explicit relationships: Related data is grouped together, making dependencies clear

2. Type safety: The compiler prevents us from forgetting to handle optional values

3. Immutability: Effect's Data classes are immutable by default, preventing accidental mutations

4. Structural equality: Two contacts with the same values are considered equal

5. Better documentation: The type structure itself documents the domain logic

This is just the beginning. In the next steps, we could:

• Add branded types to prevent mixing up similar primitives (like ensuring an email string is actually validated)

• Use Effect Schema for runtime validation

• Create smart constructors that enforce business rules

• Leverage Effect's error handling for validation failures

Conclusion

By thinking carefully about our types, we can encode domain knowledge directly into our code structure. TypeScript's type system, enhanced by Effect's functional primitives, gives us powerful tools to make illegal states unrepresentable and make our intentions explicit.

The key is to let the types and schema guide your design. When you find yourself writing comments to explain constraints or relationships, consider whether you could encode that information in the type system instead. Your future self, and your teammates, will thank you.

This article was inspired by Scott Wlaschin's excellent "Designing with types" series on F# for Fun and Profit, adapted for the TypeScript and Effect ecosystem.

These are not new concepts, but ones that I consider to be part of the canon. It's stronger on the “what” and “why” than the “how”.

The Technical Foundation: High Cohesion and Low Coupling

Before we can understand how to organize teams or share knowledge effectively, we need to grasp two fundamental principles that guide all good software architecture: high cohesion and low coupling. These aren't just technical concepts, they shape how we think about organizing entire companies.

High cohesion means keeping related things together. If you have code that handles user authentication, all of that code should be in one place, maintained by one team. It's like keeping all your cooking utensils in the kitchen. They belong together because they serve the same purpose. Low coupling means minimizing dependencies between different parts of the system. Each component should be able to work independently as much as possible. Think of it like electrical outlets in your home. You can plug in a lamp without needing to know how the television works. When systems have low coupling, you can change one part without breaking everything else.

These principles don't just apply to code, they apply to how we organize our teams and define their responsibilities. This brings us to one of the most important decisions a tech company makes: how to structure its domains.

Understanding Domains: Boundaries, Autonomy, and Accountability

When we talk about domains in a tech company, we're talking about different areas of the business that have their own specific purposes and knowledge. Think of domains like different departments in a hospital: emergency care, surgery, and administration all serve different functions and require different expertise. The way we define these domains should follow our principles of high cohesion and low coupling, keeping related capabilities together while minimizing dependencies between different areas.

One common mistake companies make is creating organizational domains based on "actor domains", that means organizing teams around who uses the system rather than what the system does. For example, imagine an e-commerce company that creates separate teams for "customer systems," "seller systems," and "admin systems." This seems logical at first, but it violates our principle of high cohesion. The same business logic, like calculating prices or managing inventory, gets duplicated across multiple teams. When pricing rules change, three different teams need to update their code. This leads to inconsistencies, bugs, and wasted effort. Instead, it's better to organize around business capabilities like "pricing," "inventory," or "ordering", regardless of who uses these features.

But here's what many organizations miss: effective domains need clear boundaries. A boundary is like a fence around your property. It defines what's inside and what's outside, what you're responsible for and what you're not. In software terms, this means each domain should have a clear understanding of what concepts, data, and rules belong to it. The pricing domain owns everything about how prices are calculated, stored, and validated. It doesn't just have some pricing code scattered among other things; it has complete ownership of the pricing concept. When another team needs pricing information, they don't reach into the pricing domain's database or duplicate its logic. They ask the pricing domain through a well-defined interface, like calling an API or subscribing to price change events.

These boundaries are crucial because they enable something powerful: autonomy. When a domain has clear boundaries and owns its concepts completely, the team responsible for that domain can make decisions independently. The pricing team can change how they calculate discounts without asking permission from the ordering team. They can refactor their code, change their database schema, or even rewrite everything in a different programming language, as long as they maintain their contracts with other domains. This autonomy allows teams to move fast and innovate without being blocked by dependencies on other teams.

Similarly, the platform domain, the technical foundation that supports other teams, should focus on providing technical capabilities, not business logic. Think of the platform team as the people who build the roads, not the ones who decide where the cars should go. When platform teams start including shared business capabilities, they create unwanted coupling and violate domain boundaries. Every time the business needs change, multiple teams have to wait for the platform team to update the shared code. It's like having only one kitchen in an apartment building, everyone has to wait their turn to cook.

But autonomy without alignment is just chaos. Imagine if every domain team optimized only for their own goals without considering the bigger picture. The pricing team might create the most sophisticated pricing engine in the world, but if it takes five seconds to calculate a price, the customer experience suffers. This is where alignment becomes critical. All domains need to work toward the same company goals, even while maintaining their autonomy. If the company goal is to provide instant checkout, then the pricing domain needs to balance sophistication with speed. The inventory domain needs to ensure stock checks are fast. The payment domain needs to process transactions quickly. Each team has autonomy in how they achieve these goals, but the goals themselves are shared.

This balance between autonomy and alignment requires clear accountability. When a team owns a domain with clear boundaries and has the autonomy to make decisions, they also become accountable for the outcomes. If the pricing service goes down during Black Friday, the pricing team can't blame the platform team or the database team. They own their domain completely, including its reliability. This accountability might seem harsh, but it's actually empowering. When teams know they're truly responsible for their domain's success, they make better decisions. They think about monitoring, testing, and reliability from the start, not as afterthoughts. They document their decisions because they know they'll have to live with the consequences.

The relationship between boundaries, autonomy, alignment, and accountability creates a powerful dynamic. Clear boundaries enable autonomy by defining what each team owns. Autonomy enables teams to move fast and innovate. Alignment ensures that this speed and innovation serve the company's goals. Accountability ensures that teams take their responsibilities seriously and build sustainable solutions. When all four elements work together, you get teams that are both independent and collaborative, fast and reliable, innovative and responsible.

But even when we organize our domains correctly with clear boundaries and balanced autonomy, we still need to make strategic decisions about where to focus our efforts. Not all domains deserve equal attention.

Identifying What Really Matters: Understanding Domain Types

To make smart decisions about where to invest your resources, you need to understand that not all parts of your business are equally important. In domain-driven design, we typically classify domains into three categories: core domains, supporting domains, and generic domains. Think of these like the different components of a restaurant. The signature dishes that customers come for represent core domains, the custom reservation system might be a supporting domain, and basic accounting software would be a generic domain.

Core domains are the areas that make your company special and different from competitors. For Netflix, the recommendation algorithm is a core domain. It's what keeps customers coming back. For Amazon, logistics and delivery might be core domains. These areas deserve the most attention, the best developers, and the most investment. Core domains are where you want to innovate and excel because they directly impact your competitive advantage. If you're not the best in the world at your core domains, or at least trying to be, your business is in trouble.

Supporting domains are important for your business but don't differentiate you from competitors. Imagine an online retailer's return processing system. It needs to work well because poor return handling frustrates customers, but having a slightly better return process than competitors won't win you the market. Supporting domains need to be good enough to not cause problems, but they don't need to be revolutionary. You might build these in-house if they have specific requirements unique to your business, but you won't put your top talent here.

Generic domains are areas where your needs are the same as everyone else's. Every company needs email, basic accounting, or employee time tracking, but these don't make your business special. For generic domains, buying or using existing solutions almost always makes more sense than building your own. It's like a restaurant buying dishwashers instead of inventing their own. The problem has been solved, and solving it again adds no value to your business.

Understanding these distinctions helps you avoid one of the most common mistakes in tech companies: spreading resources evenly across all domains. When companies fail to identify and prioritize their core domains, they might spend equal time perfecting their internal expense reporting system as they do on the features that actually attract and retain customers. It's like a restaurant spending as much time organizing their storage closet as they do perfecting their signature dishes, it doesn't make business sense.

But here's where it gets interesting: domains don't stay in the same category forever. What's core today might become supporting tomorrow, and what's currently custom-built might become available as a generic solution next year. This is where Wardley mapping becomes incredibly valuable. Wardley mapping is a strategic planning technique that helps you visualize your business components and understand how they evolve over time.

Imagine you're running a company in 2010 that does real-time video streaming. Back then, the technology to stream video efficiently was a core domain (it was hard) and few companies could do it well, and it provided competitive advantage. But over the years, as cloud providers began offering video streaming services and the technology became commoditized, it evolved from core to generic. Companies that recognized this evolution early could shift their resources from maintaining streaming infrastructure to building better content or user experiences. Those that didn't wasted valuable resources maintaining something that they could have simply purchased without creating a point of return.

Wardley mapping helps you see this evolution visually. You map out all your business components on a chart that shows both how visible they are to users and how evolved they are from custom-built to commodity. A brand new machine learning algorithm might be on the left side of the map showing it's custom and innovative, while email hosting would be on the right showing it's a commodity. By creating these maps, you can see which components are evolving, where you should invest, and what you should stop building yourself.

The real power of combining domain classification with Wardley mapping is that it helps you make strategic decisions about the future, not just the present. You might identify that your current core domain is rapidly becoming commoditized and realize you need to find new areas for differentiation. Or you might spot an emerging technology in a supporting domain that could become core to your business if you invest early. It's like a surfer reading the waves, you need to position yourself where the wave will be, not where it is now.

This strategic thinking about domains connects directly to how we organize our teams. When you clearly identify which domains are core, supporting, and generic, understand how they're evolving, and establish clear boundaries with appropriate autonomy and accountability, you can make better decisions about team structure, hiring, and resource allocation. This clarity helps prevent one of the biggest organizational challenges: silos.

Breaking Down Walls: The Danger of Silos

Silos happen when different teams or departments work in isolation, rarely communicating or collaborating with each other. Picture a company where the development team never talks to the operations team, and the operations team never talks to customer support. When a customer reports a problem, it takes days or weeks to fix because information moves slowly between these isolated groups. Even well-designed domains can become silos if we're not careful.

Breaking down silos means creating an environment where information flows freely and teams work together toward common goals. This doesn't mean everyone needs to know everything, but it does mean removing artificial barriers that prevent collaboration. When teams share knowledge and work together, problems get solved faster, and everyone learns from each other's experiences.

The antidote to silos isn't just telling people to communicate more. It's building systems and cultures that make collaboration natural and effortless and removing unnecessary layers. But here's something crucial that many organizations miss: you can't effectively break down silos if different teams operate with fundamentally different technical values and practices. This brings us to an essential but often overlooked principle: the need for a homogeneous technical culture.

Building a Unified Technical Culture: From Recruitment to Daily Practice

When we talk about a homogeneous technical culture, it's important to clarify what we mean and what we don't mean. We're not talking about hiring people who all look the same, think the same, or come from the same backgrounds. Diversity of perspectives, experiences, and backgrounds is crucial for innovation and problem-solving. What we're talking about is creating alignment around technical values, practices, and approaches to problem-solving. Think of it like an orchestra: you want different instruments playing different parts, but they all need to be reading from the same sheet music and following the same conductor.

Imagine a company where half the developers believe in extensive testing and code reviews, while the other half believes in moving fast and fixing things in production. Or where some teams document everything meticulously while others rely entirely on tribal knowledge. These aren't just different approaches, they're fundamentally incompatible worldviews that create friction every time these teams need to work together. It's like trying to build a house where some workers are using metric measurements and others are using imperial. Even if everyone is skilled and well-intentioned, the result will be a mess.

A homogeneous technical culture means that everyone in the organization shares certain fundamental beliefs about how to build software. This might include agreements about code quality standards, testing practices, documentation requirements, how to handle technical debt, approaches to security, or methods for making technical decisions. When everyone shares these foundational beliefs, collaboration becomes smooth and natural. Teams can move between projects without culture shock, code can be shared without extensive rework, and decisions can be made quickly because everyone is working from the same playbook.

This cultural alignment needs to start from the very beginning at recruitment. Many companies make the mistake of hiring purely based on technical skills, assuming they can teach culture later. But technical culture isn't just about following rules; it's about deeply held beliefs about what good software looks like and how it should be built. If you hire someone who fundamentally believes that documentation is a waste of time into a culture that values comprehensive documentation, you're setting up both the individual and the team for frustration and conflict.

Smart recruitment for technical culture doesn't mean asking trick questions or requiring specific technologies. Instead, it means exploring how candidates think about software development. How do they approach debugging a complex problem? What's their philosophy on testing? How do they balance speed versus quality? What's their experience with code reviews, and what value do they see in them? You're not looking for perfect answers, but for alignment with your organization's values. A brilliant developer who believes in cowboy coding might not be a good fit for a team that values careful, methodical development no matter how talented they are.

But recruitment is just the beginning. Once people join your organization, you need to actively reinforce and develop the technical culture through comprehensive onboarding and continuous training. Too many companies treat onboarding as a bureaucratic checkbox here's your laptop, here's the wiki, good luck. But effective onboarding is where new team members internalize not just what your culture says, but how it actually works in practice, two way synchronization is needed.

Imagine joining a new company and spending your first two weeks pair programming with experienced developers, participating in code reviews, attending architecture discussions, and seeing how decisions actually get made. You're not just learning the codebase; you're absorbing the culture through osmosis. You see that when someone says "we value testing," they actually mean it, tests are written first, they're comprehensive, and pull requests without tests don't get merged. You learn that "we document our decisions" means there's an architectural decision record for every significant choice, not just a vague suggestion to write things down sometimes.

Continuous training and reinforcement keep the culture strong as the organization grows and evolves. This isn't just about sending people to conferences or online courses, though those can be valuable. It's about creating regular opportunities for teams to align on practices and share knowledge. Maybe you have weekly tech talks where teams present their approaches to solving problems. Perhaps you run internal workshops on testing strategies or debugging techniques. You might organize coding dojos where developers practice new techniques together in a safe environment.

The power of a homogeneous technical culture becomes especially apparent when things go wrong. In organizations with fragmented cultures, incidents become blame games. The "move fast" team blames the "move carefully" team for being too slow to respond. The "comprehensive testing" team blames the "ship it now" team for causing the problem in the first place. But in organizations with aligned technical culture, everyone shares the same values about quality, the same understanding of acceptable risks, and the same commitment to learning from failures. Instead of finger-pointing, there's collaborative problem-solving.

This cultural alignment also dramatically speeds up decision-making and reduces organizational friction. When everyone shares fundamental technical values, you don't need to debate basic principles in every meeting. You don't need extensive approval processes because teams can be trusted to make decisions aligned with organizational values. You don't need heroes to bridge between incompatible team cultures because there's only one culture. The organization can move faster because it's not constantly dealing with internal friction from conflicting approaches.

However, building and maintaining a homogeneous technical culture requires constant attention and investment. As organizations grow, especially through acquisitions or rapid hiring, it's easy for subcultures to develop. Different offices might evolve different practices. Teams working on different products might drift apart in their approaches. This is why successful companies treat technical culture as a strategic priority, not an HR afterthought. They invest in bringing teams together regularly, they're deliberate about which practices are mandatory versus flexible, and they constantly reinforce cultural values through their actions, not just their words.

The connection between homogeneous technical culture and our other principles is profound. When teams share technical values, breaking down silos becomes much easier because there's a common language and shared understanding. Transparency works better because everyone values and practices it consistently. The dangers of hero culture diminish because the culture emphasizes collective ownership and knowledge sharing. Even architectural principles like high cohesion and low coupling are easier to maintain when everyone understands and values them equally.

But maintaining this cultural alignment while avoiding stagnation requires thoughtful leadership. This brings us to a management approach that seems like it should create consistency but actually creates more problems than it solves.

Moving Beyond Command and Control: Why Traditional Management Fails in Tech

Command and control management comes from military and industrial age thinking, where work was predictable and repetitive. In this model, managers at the top make all important decisions, create detailed plans, and pass orders down through layers of hierarchy. Workers at the bottom follow these orders precisely, with little room for creativity or independent thinking. Think of it like a traditional factory assembly line where every movement is predetermined and workers simply execute predefined tasks.

This approach might work when building thousands of identical widgets, but software development is fundamentally different. Every problem is unique, technology changes rapidly, and the people closest to the code often have the best understanding of what's possible and what's needed. When a manager three levels up decides how long a feature should take without understanding the technical complexity, or when teams need approval for every small decision, the organization grinds to a halt.

Command and control creates several serious problems in tech companies. First, it destroys innovation because people stop thinking creatively when they're just following orders. Imagine a developer who sees a better way to solve a problem but knows they'll need three meetings and two weeks of approvals to try it. They'll probably just do what they were told instead. Second, it slows everything down because decisions bounce up and down the hierarchy like a ping-pong ball. By the time approval comes back, the market opportunity might be gone. Third, it demotivates talented people who joined the tech industry specifically because they wanted to solve interesting problems and build innovative solutions, not to be cogs in a machine.

Perhaps most dangerously, command and control creates an illusion of predictability and control that doesn't actually exist. Managers feel comfortable because they have detailed plans and status reports, but these often hide the real problems. Teams learn to report what management wants to hear rather than what's actually happening. It's like navigating with an outdated map, you might feel confident about where you're going, but you're actually lost.

So what's the alternative? Modern tech companies need to value risk management over control and fear. They need management approaches that embrace uncertainty and empower teams while still maintaining alignment and accountability. One powerful alternative is servant leadership, where managers see their role as supporting and enabling teams rather than commanding them. Instead of saying "do this," servant leaders ask "what do you need to succeed?" They remove obstacles, provide resources, and protect teams from organizational dysfunction while trusting them to make good decisions.

Another effective approach is that leadership sets clear objectives and constraints. The "what" and the "why", but leaves the "how" up to the teams. For example, instead of telling a team exactly how to build a feature, leadership might say "we need to reduce customer churn by 10% this quarter, and we have this budget to work with." The team then figures out the best way to achieve that goal, using their expertise and creativity.

Some organizations adopt collaborative decision-making. These approaches clarify who needs to be involved in different types of decisions and how those decisions get made, but without creating rigid hierarchies. A technical decision might be made entirely by the engineering team, while a pricing decision might involve product, sales, and engineering together. The key is that decisions are made by the people with the most relevant knowledge, not just the highest rank.

These alternative management approaches help prevent another organizational disease that often emerges from command and control structures: internal politics. When organizations create the right structures and incentives, they can minimize the toxic effects of political behavior and create environments where merit and collaboration triumph over manipulation and self-interest.

Eliminating Toxic Politics: Building Merit-Based Organizations

Organizational politics in tech companies is like a virus that spreads quietly but causes tremendous damage. It happens when people advance their careers not by building better products or solving harder problems, but by managing perceptions, building alliances, playing power games, and spreading Peter principle. Picture a company where the best engineers don't get promoted because they're too busy coding, while those who spend their time in meetings talking about other people's work climb the ladder. Or where technical decisions aren't based on what's best for the product, but on who has the most political capital, yes sir folks or who's best friends with the VP.

The toxicity of politics manifests in many ways. You might see engineers spending more time crafting emails or slack messages to look good than writing code. Teams hoard information because sharing knowledge means losing power. Technical debt accumulates because no one wants to own unglamorous but necessary work that won't get them promoted. Innovation dies because new ideas threaten existing power structures. Information must cross multiple hierarchical layers to be on the air, unless it is ignored or modified along the way. The best talent leaves because they're tired of seeing political operators succeed while genuine contributors are overlooked.

So how do you create an environment where politics can't take root? A powerful antidote to politics is radical transparency in decision-making. This doesn't mean every conversation needs to be public, but the principles, processes, and outcomes should be clear and visible to all affected parties. Also, in addition to being futile, multi-layer management is a barrier to transparency and collaboration.

Creating multiple paths for advancement also reduces political behavior. In many tech companies, the only way to advance is to become a manager, which creates perverse incentives for excellent engineers to abandon what they do best. By establishing parallel tracks, where a principal engineer can have the same status and compensation as a director, you remove the pressure to play political games to climb a single ladder. People can succeed by excelling at what they love, whether that's coding, architecture, mentoring, or management.

The connection between eliminating politics and our other principles is clear. When you have transparent decision-making, clear domain boundaries with accountability, and a homogeneous technical culture, there's less room for political maneuvering. When teams have genuine autonomy and alignment, when the management culture is against command and control, there is no room to play political games. When failure is seen as learning rather than blame, people don't need to engage in political cover-ups. Each principle reinforces the others, creating an environment where merit and collaboration naturally flourish.

Choosing Openness: Transparency Over Opacity

Transparency means making information visible and accessible to those who need it. This includes everything from code and documentation to decision-making processes and project status. When teams operate transparently, everyone can see what's happening, why decisions were made, and how they can contribute. Transparency is the foundation that makes collaboration possible and enables the autonomous decision-making we just discussed. Many patterns could help such as ADRs or Arc42.

Opacity, keeping information hidden or hard to find, creates confusion and mistrust. It's like trying to assemble furniture without instructions; you might figure it out eventually, but it takes much longer and causes unnecessary frustration. Transparent organizations move faster because people spend less time searching for information or redoing work that's already been done. More importantly, transparency allows teams to make good decisions independently because they understand the full context of their work and they make the most of other experiences.

Transparency helps teams learn from each other's successes and failures. But this learning process can go wrong when teams start copying practices without understanding why they work. This brings us to a dangerous trap that many organizations fall into.

The Cargo Cult Trap: Why Context Matters

Cargo culting in software development happens when teams copy practices from successful companies without understanding the principles behind them. The term comes from Pacific island societies that built replica airports hoping to attract cargo planes, not understanding that it was World War II, not the airports themselves, that brought the supplies.

In tech companies, cargo culting looks like adopting daily stand-up meetings because Google does them, without understanding that stand-ups work when teams need tight coordination. Or implementing microservices because Netflix uses them, ignoring that Netflix has thousands of engineers and your startup has twelve. These teams go through the motions of successful practices but don't get the benefits because they haven't understood the underlying problems these practices were meant to solve.

One of the most common examples of cargo culting is how companies adopt Scrum. They hear that successful companies use Scrum, so they immediately implement all the ceremonies: daily stand-ups, sprint planning, retrospectives, and sprint reviews. They hire Scrum Masters, pay thousands for Jira, create backlogs, and start estimating in story points. But they do all this without understanding the problems Scrum was designed to solve or whether those problems actually exist in their organization. These teams end up spending more time on Scrum ceremonies than actually building software, wondering why this "proven" methodology isn't making them more productive.

The danger of cargo culting is that it gives teams a false sense of progress. They feel like they're following "best practices," but they're really just performing rituals. A company might implement Spotify's squad model without having Spotify's culture of autonomy and trust. They get all the overhead of the new structure but none of the benefits. Even worse, cargo culting can actively harm organizations when copied practices conflict with their actual needs. A small team adopting the communication processes designed for a 500-person organization will drown in unnecessary meetings and documentation.

Instead of blindly copying what successful companies do, teams should understand their own problems first, then look for principles and adapt solutions to their specific context. Ask "what problem were they solving?" not "what did they do?" This thoughtful approach to adopting practices connects directly to another dangerous misconception: the search for silver bullets.

Avoiding Silver Bullets: No Single Solution Solves Everything

A silver bullet in software development is the belief that one tool, technology, or methodology will solve all your problems. It's thinking that adopting Kubernetes or Serverless will fix all your deployment issues, or that switching to microservices will automatically make your system scalable, or that hiring from a specific company will transform your culture overnight.

One of the most pervasive silver bullet beliefs in the industry is around project management tools, particularly Jira. Companies experiencing problems with project visibility, team coordination, or delivery predictability often think, "If we just implement Jira properly, all our project management problems will disappear." They spend months configuring workflows, creating custom fields, setting up dashboards, and training everyone on the tool. But six months later, they find that projects are still late, communication is still poor, and now they have the additional overhead of maintaining a complex Jira setup. The tool didn't fix the underlying problems: unclear requirements, poor stakeholder communication, or unrealistic deadlines. In fact, teams often find that Jira becomes another source of friction, with developers spending hours updating tickets instead of writing code, and managers becoming obsessed with burndown charts that don't reflect actual progress. The real issues like why estimates are always wrong or why requirements keep changing mid-sprint – remain unaddressed because everyone thought the tool would somehow solve these deeper organizational problems.

The silver bullet mentality is seductive because it promises simple solutions to complex problems. Leadership loves silver bullets because they seem like decisive action. "We're moving everything to the cloud!" sounds much better in a board meeting than "We're going to carefully evaluate which of our systems would benefit from cloud hosting and migrate them incrementally over two years."

But real organizations are complex systems with interconnected challenges. Performance problems might stem from poor database design, not your programming language. Team velocity might be slow because of unclear requirements, not your project management tool. Customer satisfaction might be low because of poor product decisions, not your technology stack. When companies chase silver bullets, they often undergo expensive, disruptive changes that don't address their real problems. They might spend months migrating to a new framework while their competitors focus on building better features.

The alternative to silver bullets is understanding that improvement comes from many small, thoughtful changes rather than one dramatic transformation. It means solving specific problems with targeted solutions, measuring results, and adjusting based on what you learn. This measured approach to change connects directly to how we think about failure and learning.

Learning from Failure: The "Fail Fast" Philosophy

Creating an environment where teams can experiment with solutions, rather than searching for silver bullets or copying others, requires a fundamental shift in how we think about failure. "Fail often, fail fast" doesn't mean being careless. It means trying new things, discovering quickly when they don't work, and adjusting course without blame or shame.

When teams fear blame, they hide problems until they become catastrophes. They avoid trying innovative solutions because the risk of failure seems too high. They might even fall back on cargo culting or silver bullet solutions because these feel safer after all, if everyone else is doing it, you can't be blamed if it doesn't work. But when organizations embrace failure as a learning opportunity, magic happens. Teams experiment freely, problems surface quickly while they're still small, and everyone learns from both successes and mistakes.

This philosophy of learning from failure connects directly to how we build our teams. When people aren't afraid to make mistakes, they're more willing to take on challenges, admit when they need help, and share their struggles with others. This creates an environment where knowledge spreads naturally and no one person becomes a critical dependency.

Building Sustainable Teams: Beyond Hero Culture

Hero culture emerges when there's a systemic problem or gap in a system and an individual decides to fill that gap. It often manifests as "incident-driven development", when something breaks, everyone stops what they're doing, and the person with the most context becomes the hero who saves the day. While this might seem efficient in the moment, it creates a dangerous pattern.

The problem isn't that someone knowledgeable fixed an issue. It's that organizations start relying on this pattern instead of addressing why problems keep happening. When heroes consistently step in to save the day, they become the sole repositories of critical knowledge, creating dangerous single points of failure. These heroes often work longer hours, take on more stress, and feel pressured to always be available, leading to burnout. Meanwhile, other team members don't develop the skills they need because they rely on the hero to handle difficult situations.

Hero culture creates a self-reinforcing cycle: quick fixes by heroes prioritize immediate solutions over long-term maintainability, leading to more technical debt, which causes more incidents, which requires more heroics. Teams with strong hero cultures experience significantly higher burnout rates than those with distributed responsibility patterns. The organization might praise and recognize crisis management, but nobody asks the critical question: why did this crisis happen in the first place?

Sometimes hero culture emerges from cargo culting. Companies copy the "rockstar developer" culture they've heard about without understanding its problems. Other times, it's seen as a silver bullet, "if we just hire the right genius, all our problems will be solved." But sustainable organizations build systems and processes that address systemic gaps rather than depending on individuals to fill them. They document knowledge, share responsibilities, conduct root cause analysis after incidents, and ensure multiple people can handle critical tasks.

This approach might seem slower at first, but it creates resilient teams that can handle challenges even when key members are absent. When you combine high cohesion and low coupling in your architecture, organize domains around capabilities with clear boundaries and balanced autonomy, prioritize core domains while appropriately managing supporting and generic ones, build a unified technical culture from recruitment through continuous training, eliminate toxic politics through transparency and merit-based systems, break down silos through empowering leadership rather than command and control, maintain transparency, avoid cargo culting and silver bullets, and embrace learning from failure, hero culture naturally disappears. The system itself becomes robust, not dependent on any individual person.

Bringing It All Together

These principles form a complete system for building effective tech organizations. We start with the technical foundation of high cohesion and low coupling, apply these principles to how we organize our domains with clear boundaries that enable autonomy while maintaining alignment and accountability. We identify which domains truly matter for our success through careful classification and strategic tools like Wardley mapping. We then break down the walls between teams, but recognize that this requires a unified technical culture built through deliberate recruitment and continuous reinforcement. We replace command and control with empowering management approaches like servant leadership and mission command, while actively eliminating toxic politics through transparency, clear criteria, and merit-based advancement. Through transparency, we enable teams to make good decisions independently, while avoiding the traps of cargo culting (like blindly adopting Scrum) and silver bullets (like expecting Jira to solve all project management problems).

By creating a culture where failure becomes learning and heroes become mentors instead of saviors, we build organizations that can adapt and grow. Each principle supports the others, clear domain boundaries enable autonomy, which requires accountability and alignment. A homogeneous technical culture enables transparency, which prevents politics, which enables autonomous decision-making, which requires moving beyond command and control. Learning from failure reveals that complex problems need multiple solutions (not silver bullets), and sustainable team practices prevent hero culture from taking root.

The journey to implement these principles isn't always easy, and no company gets everything right immediately. The key is to understand your own context, solve your specific problems, and learn from both your own experiences and the principles (not just the practices) of successful organizations. Start with one area, but always keep the bigger picture in mind. As each piece falls into place, the others become easier to implement, creating a positive cycle of improvement that benefits everyone, from individual developers to customers to the business as a whole.

Remember: there's no silver bullet that will transform your organization overnight, and blindly copying what works for others won't solve your unique challenges. But by thoughtfully applying these principles to your specific context, you can build a tech organization that's both effective and sustainable for the long term. The strength doesn't come from any single principle, but from how they work together to create a coherent, resilient system that can handle whatever challenges the future brings.

Logs were supposed to be our trusted companions in understanding what happens inside our applications. They should tell us the story of our software's behavior, help us find problems quickly, and guide us toward solutions. Instead, they often become sources of frustration, confusion, and wasted cost and time. Let's explore why this happens and what we can do about it.

The Common Patterns That Make Logs Unreliable

Throughout your career in software development, you've probably encountered several frustrating patterns when dealing with logs. These patterns reveal why logs can become "big lies" rather than helpful truth-tellers.

The Spam Problem occurs when your systems generate so many error logs that teams simply stop paying attention to them. It's like having a car alarm that goes off constantly - eventually, everyone ignores it, even when there's a real problem. When logs become noise instead of signal, they lose their primary purpose of alerting us to issues that need attention.

The Flood Pattern happens when one particular type of error suddenly increases dramatically. The team looks at it and thinks, "We've seen this before, it's probably the same old issue," or "Maybe some external service is having problems." Without proper investigation, teams often adopt a wait-and-see approach, hoping the problem will resolve itself. This reactive mindset can lead to hiding critical issues that require immediate attention. And increasing the infrastructure cost.

The Sign of Life Syndrome represents a twisted relationship with error logs. Teams start believing that constant error logs actually indicate the system is working properly. The logic goes: if we see errors, at least we know the system is running. If we don't see errors, maybe the logging system is broken or the application has stopped entirely. This backward thinking shows how logs have failed in their fundamental role.

The No Value Response perfectly captures the frustration many teams feel. When someone reports a spike in error logs, the standard response becomes "just restart the service." This approach treats logs as meaningless noise rather than valuable diagnostic information. It's like treating every illness with the same medicine without understanding the symptoms.

The Low Value Usage describes teams that only check logs when someone reports a bug or when an incident has already occurred. Logs become reactive tools rather than proactive monitoring systems. If the team is lucky, the logs might provide a starting point for investigation, but they're not trusted enough for regular monitoring.

The Low Context Dilemma happens when logs provide information that's technically accurate but practically useless. You might see an error message that tells you something went wrong, but it doesn't give you enough context to understand why it happened or how to fix it. It's like getting a weather report that says "bad weather" without specifying if it's rain, snow, or a hurricane.

The Correlation Problem occurs when logs give you enough information to identify which line of code threw an error, but no insight into the chain of events that led to that error. You know what broke, but you don't know why it broke. Understanding the upstream causes becomes nearly impossible without additional context.

The Release Check Burden shows how logs can become expensive overhead. Teams generate thousands of logs just to verify that everything works correctly for the first few minutes after a release by verifying one or two logs. This creates unnecessary computational and storage costs for limited value.

The Time Travel Impossibility frustrates teams when they need to investigate issues that occurred weeks ago, only to discover that the relevant logs have been deleted or archived. Critical debugging information disappears just when you need it most.

The Cost Control Conflict emerges when organizations implement log filtering to control storage and processing costs. Teams suddenly find themselves working with only a few percent of their log data, making thorough investigation nearly impossible.

The Metrics Misuse happens when teams emit complex textual logs with the intention of parsing them later to generate metrics. This approach is inefficient and error-prone compared to using proper metrics systems.

The Standardization Nightmare occurs when different parts of the system use different logging formats, making it difficult to search, correlate, or understand log data across the entire system.

The Custom Platform Trap represents one of the most tricky long-term patterns. Frustrated with existing solutions, teams build custom logging platforms that seem simple at first but gradually evolve into complex systems requiring dedicated maintenance. What starts as "we just need to collect and store logs" becomes a full product with its own roadmap, performance issues, and operational burden. Teams end up spending engineering time on log collectors, storage optimization, and search interfaces instead of their core business, while losing institutional knowledge as developers change. The accidental complexity of maintaining a homegrown logging platform often becomes more problematic than the original issues it was meant to solve, diverting resources from proven solutions that have been battle-tested across thousands of organizations.

The Audit-Tech Confusion occurs when teams mix business audit logs with technical diagnostic logs in the same systems and formats. Business audit logs serve compliance and business intelligence purposes, recording user actions, entity tracking, and regulatory events that must be preserved and searchable for extended periods. When these two fundamentally different types of logs are confused or combined, teams end up with audit logs that lack business context and compliance rigor, while technical logs become expensive to store and difficult to use for debugging due to irrelevant business data mixed throughout.

Understanding Errors: The Heart of the Problem

To understand why logs become unreliable, we need to examine the two main categories of errors and their specific problems.

Handled Errors: When Expected Becomes Problematic

Handled errors represent situations where your code anticipates certain problems and deals with them programmatically. However, several symptoms indicate these errors are not serving their intended purpose effectively.

Silent Errors represent one of the most dangerous patterns. These occur when your application encounters a known error condition but handles it so quietly that no one notices the underlying problem. The error gets logged, but because it's "handled," teams don't prioritize fixing the root cause. Over time, these silent errors can accumulate and indicate deeper systemic issues.

State Machine Breaks happen when your application's flow or business logic encounters a known error and terminates unexpectedly. While the error is technically handled, it reveals that your state management or workflow design has fundamental flaws. The question becomes: why is the normal flow breaking down, and why aren't there better alternative paths?

Graceful Management Failures occur when errors are caught and logged but not handled in a user-friendly way. Instead of providing alternative solutions or fallback mechanisms, the application simply records the error and gives up. This approach provides a poor user experience and indicates insufficient error handling design.

Metrics Confusion happens when teams use error logs for monitoring purposes instead of proper metrics systems. Error logs are not designed to be metrics, and using them this way creates unnecessary overhead and reduces the effectiveness of both logging and monitoring systems.

Exception Handling Confusion occurs when teams log errors that should actually be handled by higher-level exception management systems. This creates redundant error handling and can mask more serious issues that need immediate attention.

Alert Absence represents a critical gap where handled errors are logged but don't trigger any notifications or automatic incident creation. If an error is worth logging, it might be worth monitoring, but many teams fail to make this connection.

Unhandled Errors: When the Unexpected Happens

Unhandled errors represent situations where your application encounters problems it wasn't designed to handle. These errors often indicate more serious issues, but they come with their own set of problems.

Incident Management Gaps occur when unhandled errors don't trigger automatic incident creation, even at low priority levels. These errors represent genuine surprises in your system, and they deserve attention and investigation.

Documentation Deficiency happens when teams encounter unhandled errors but don't document them for future reference. Without proper documentation, teams repeatedly encounter the same issues without building institutional knowledge about how to handle them.

Error Bombardment occurs when the same unhandled error repeats rapidly, overwhelming your logging and monitoring systems. This pattern often indicates cascading failures or retry loops that need immediate attention.

Fallback Absence represents a fundamental design problem where systems have no graceful degradation mechanisms when unexpected errors occur. Instead of failing safely, systems crash or behave unpredictably.

Disaster Recovery Blindness happens when teams don't understand how unhandled errors relate to their overall system resilience and disaster recovery plans.

Information Logs: The Context Problem

Information logs should provide valuable insights into your application's behavior, but they often suffer from several critical problems.

Repetitive and Context-less Content makes information logs difficult to use for actual debugging or understanding. Logs that simply repeat the same messages without providing meaningful context become noise rather than signal.

Production Dependency occurs when teams rely too heavily on production logs to understand their application's behavior. This dependency often indicates insufficient testing and inadequate understanding of the system's normal operation.

Developer-Centric Thinking happens when logs reflect the developer's mental model rather than the actual business logic or user experience. These logs make sense to the person who wrote them but provide little value to others trying to understand the system.

Solutions: Making Logs Truthful Again

Understanding these problems is the first step toward creating more reliable and valuable logging systems. Let's explore practical solutions that can transform logs from sources of frustration into powerful debugging and monitoring tools.

Improving Handled Error Management

The Result Pattern offers a structured approach to handling expected errors without relying heavily on logging. However, you need to understand when and how to use this pattern effectively.

Avoid using the Result pattern when you need detailed diagnostics about what went wrong. Results are designed for simple success or failure scenarios, not complex debugging situations. Don't use Results to reinvent exception handling mechanisms that already exist in your programming language. Avoid Results when you need your application to fail fast rather than continuing with degraded functionality.

Results are only valuable when someone will actually check and handle the error cases. If your code ignores Result errors, you're not gaining any benefit from this pattern. Be particularly careful when using Results for I/O operations, where exception handling might be more appropriate.

Context Enrichment involves adding meaningful information to your application logs, traces and spans. Instead of logging bare error messages, include relevant context like user identifiers, request parameters, system state, and the sequence of operations that led to the current situation.

Addressing Unhandled Error Issues

Continuous Improvement means treating unhandled errors as learning opportunities rather than just problems to fix. Each unhandled error should trigger a review process that asks: how can we prevent this type of error in the future, and how can we handle it more gracefully if it occurs again?

Testing Excellence involves creating comprehensive test suites that cover not just happy path scenarios but also various failure conditions. Good testing practices help you anticipate and handle more error conditions before they become unhandled surprises in production.

Infrastructure Knowledge means understanding your deployment environment, dependencies, and operational context well enough to anticipate potential failure modes. Teams that know their infrastructure can design better error handling and recovery mechanisms.

Resilience Patterns like circuit breakers, fallback mechanisms, and proper disaster recovery planning help your systems handle unexpected errors more gracefully. These patterns reduce the number of truly unhandled errors and improve overall system reliability.

Correlation and Metrics involve connecting error logs with relevant metrics and tracing information. Instead of isolated error messages, you want error logs that show the broader context of system behavior and performance.

Moving Beyond Logs: The Power of Distributed Tracing

While improving logging practices can help address many of the problems we've discussed, there's a more fundamental solution that's gaining widespread adoption in modern software development: distributed tracing. Understanding why traces are often superior to logs requires us to think differently about how we observe and understand our applications.

Understanding the Fundamental Difference

To grasp why tracing is superior, imagine you're trying to understand a conversation between multiple people in different rooms. Traditional logging is like having each person write down notes about what they said and when they said it, but without any connection between these notes. You end up with fragments of information scattered across different sources, and piecing together the actual conversation becomes a detective puzzle.

Distributed tracing, on the other hand, is like having a complete transcript that shows not only what each person said and when, but also how each statement relates to the others, who was responding to whom, and the complete flow of the conversation from beginning to end. Each trace represents a complete journey through your system, connecting all the related operations that happen as a result of a single request or user action.

The Correlation Solution

Remember the correlation problem we discussed earlier, where logs tell you what broke but not why it broke? Traces solve this by design. Every trace captures the complete path of execution through your distributed system, showing exactly how different services and components interact with each other. When something goes wrong, you can follow the trace backward to see the entire chain of events that led to the failure.

Consider a typical web application where a user request might travel through a load balancer, an authentication service, a business logic service, a database, and perhaps several external APIs. With traditional logging, each component creates its own log entries, and correlating these entries requires careful timestamp analysis and hoping that you've included the right correlation identifiers in each log message and also hopping that they are all sampled. With tracing, all these operations are automatically connected in a single trace that shows the complete journey, including timing information, error conditions, and the relationships between different steps.

Context Without Effort

One of the most significant advantages of tracing is that it provides rich context automatically. Each span within a trace can include metadata about the operation being performed, the input parameters, the results, and any relevant environmental information. This context is structured and queryable, unlike the free-form text of traditional logs.

When you examine a trace, you can see not just that an error occurred, but also what the user was trying to accomplish, what data was being processed, which code paths were taken, and how long each operation took. This level of context makes debugging and performance optimization much more straightforward than trying to reconstruct the same information from scattered log entries.

Performance Insights Built In

Traditional logs often require separate metrics and monitoring systems to understand performance characteristics. Traces include timing information by design, showing you exactly how long each operation took and where bottlenecks are occurring in your system. You can identify slow database queries, inefficient API calls, or unexpected delays without having to instrument your code with additional performance logging.

This timing information is particularly valuable because it's automatically correlated with the business context of each request. Instead of seeing abstract performance metrics, you can understand how performance issues affect real user scenarios and business operations.

Sampling Intelligence

While we mentioned sampling as a solution for managing log volume, tracing systems implement more sophisticated sampling strategies. Instead of randomly discarding information, tracing systems can use intelligent sampling that ensures you capture representative examples of different types of operations while always preserving traces that contain errors or performance anomalies.

This approach means you get comprehensive coverage of your system's behavior without the storage and processing overhead of capturing every single operation. The sampling decisions are made at the trace level rather than at individual log entry level, ensuring that you never lose the complete picture of any captured request.

Breaking Down Silos

Traditional logging often creates information silos where each service or component logs independently. Even with good correlation identifiers, understanding cross-service interactions requires manual effort and domain knowledge. Traces naturally break down these silos by representing operations that span multiple services as unified, connected experiences.

This unified view is particularly valuable in multi-services architectures, where a single user request might touch dozens of different services. With tracing, you can follow the complete journey through your entire system without having to know which services are involved or how they're connected.

Better Alerting and Monitoring

Because traces capture complete user journeys, they enable more intelligent alerting strategies. Instead of alerting on individual log entries or isolated metrics, you can create alerts based on complete user experience scenarios. For example, you can alert when checkout processes are failing end-to-end, even if individual services appear to be functioning normally.

This approach reduces false alarms and ensures that your monitoring focuses on actual user impact rather than technical implementation details.

The Learning Advantage

Perhaps most importantly, traces help teams develop better understanding of their systems over time. When investigating issues or optimizing performance, traces provide educational value that logs simply cannot match. Team members can see how requests flow through the system, understand the relationships between different components, and develop intuition about normal versus abnormal system behavior.

This learning aspect is particularly valuable for onboarding new team members or understanding unfamiliar parts of the system. A few minutes exploring traces can provide insights that might take hours to gather from traditional logs and documentation.

Making the Transition

Moving from logs to traces doesn't have to be an all-or-nothing decision. Modern tracing systems can coexist with traditional logging, and many teams start by implementing tracing for their most critical user journeys while gradually expanding coverage. The key is to start thinking about observability in terms of user experiences and business operations rather than individual technical events.

When you make this mental shift, you'll find that many of the logging problems we discussed earlier simply disappear. Correlation becomes automatic, context becomes rich and structured, and the signal-to-noise ratio improves dramatically because you're focusing on complete meaningful operations rather than fragmented technical events.

Conclusion: Three Principles for Honest Observability

The transformation from unreliable logs to trustworthy system understanding rests on three fundamental principles that address the root causes of why logs become lies.

First, prioritize better error handling over more logging. Handle errors properly at their source with fallback mechanisms and recovery strategies rather than simply recording them and hoping someone will notice later. This shifts your focus from reactive debugging to proactive system design, where errors become manageable events rather than sources of confusion.

Second, favor application logic over logging logic. Many logging problems stem from trying to solve business problems through logging rather than clear application design and proper unit testing. When your code and tests clearly expresses what it does and why, you need fewer logs to understand system behavior. Design for transparency from the beginning rather than trying to reconstruct understanding through scattered log entries.

Third, embrace distributed tracing as your observability foundation. Tracing automatically provides the correlation, context, and complete picture that traditional logs struggle to deliver. By capturing entire user journeys through your system, tracing eliminates the fundamental problems that make logs unreliable while providing richer insights with less effort.

These principles work together synergistically. Better error handling reduces diagnostic logging needs, clearer application logic makes system behavior transparent, and distributed tracing provides comprehensive visibility into remaining interactions. Apply them gradually, starting where they can have the most immediate impact, and build toward systems that tell the truth about their behavior rather than obscuring it behind confusing information.

Each F# code example is paired with its equivalent in TypeScript. The aim is not to compare both languages but to provide a reference point.

Less Visual and Noise Pollution

F# has a minimalistic philosophy. By avoiding or making optional unnecessary keywords or symbols like colons :, semicolons ;, braces { }, parentheses ( ), and virgules ,. This offers a cleaner and more readable codebase, allowing developers to focus on the logic and the structure of the program rather than wrestling with syntax and continuously typing the same characters. F# is curly only when it’s useful.

// F#
let mean values =
    let total = List.sum values
    total / values.Length

// TypeScript
const mean = (values: number[]): number => {
    const total = values.reduce((sum, val) => sum + val, 0);
    return total / values.length;
};

Dependency Order

At first sight, this feature seems surprising and unusual, but this is actually one of my favorites.
F# doesn’t allow forward references, meaning you cannot use a type, function, or module before it has been defined. And the code must be structured such that dependencies are introduced before they are used.

Not only does this prevent circular dependencies, but it also allows the code to be read sequentially, like a book. When I read F# code, I don’t need to endlessly navigate or scroll up or down, in order to understand it. I can read it like a novel or just go to the end to grasp the goal.

As for writing code, dependency order encourages me to think modular, to compose little functions or types from other little functions or types. Now that I’ve learned F#, I even apply this pattern with other languages that do have forward references.

For more info: Cyclic dependencies are evil.

Expression Oriented

In F#, the primary focus is on expressions rather than statements.

Being expression-oriented in programming means that the language is designed in a way where nearly everything (control flow, bindings, and even code blocks) produces a value. This enables immutability, consistency, and composition.

A statement, on the other hand, is a construct that performs an action but does not produce a value. It is used for side effects, like modifying a variable or printing to the screen.

In the following code we can use a mapped type but the goal here is to compare expressions and statements with a sample.

let calculateDiscount customerType orderAmount =

    // the first expression is the pattern matching control flow
    // then its value is multiplied by the order amount
    // and finally the entire code block result is set to the base discount
    let baseDiscount =
        match customerType with
        | Regular -> 0.05 // 5%
        | Premium -> 0.10 // 10%
        * orderAmount

    let additionalDiscount =
        if orderAmount >= 1000.0 then 0.05 * orderAmount else 0.0

    baseDiscount + additionalDiscount

function calculateDiscount(customerType: CustomerType, orderAmount: number): number {

    let baseDiscountRate: number = 0;
    switch (customerType) {
        case CustomerType.Regular:
            baseDiscountRate = 0.05; // 5%
            break;
        case CustomerType.Premium:
            baseDiscountRate = 0.10; // 10%
            break;
    }
    const baseDiscount = baseDiscountRate * orderAmount;

    const additionalDiscount =
        orderAmount >= 1000 ? 0.05 * orderAmount : 0;

    return baseDiscount + additionalDiscount;
}

For more info: Expressions vs. statements.

Functions as First-Class Citizens

One of the core principles of functional programming is that functions should be treated as first-class citizens, like ordinary variables with a function type, which means they can be assigned to variables, passed as arguments, returned from other functions, and stored in data structures. Design patterns slip away to make room for just functions.

// Assign to a variable

let applyPercentageDiscount discountRate price =
    price * (1m - discountRate)

let applyFlatDiscount discountAmount price =
    price - discountAmount

// Pass as an argument

let calculateTotal applyDiscount prices =
    prices |> List.map applyDiscount |> List.sum

// Return from another function

let welcomeDiscount =
    applyFlatDiscount 10m

let createBlackFridayDiscount () =
    let now = DateTime.Now.Date
    if now = blackFridayOf now.Year
    then applyPercentageDiscount 50m
    else fun price -> price // id

// Store in a data structure

let discountStrategies =
    [ welcomeDiscount
      createBlackFridayDiscount () ]

type ApplyDiscount = (price: number) => number;

// Assign to a variable

const applyPercentageDiscount = (discountRate: number, price: number): number =>
    price * (1 - discountRate);

const applyFlatDiscount = (discountAmount: number, price: number): number =>
    price - discountAmount;

// Pass as an argument

const calculateTotal = (applyDiscount: ApplyDiscount, prices: number[]): number =>
    prices.map(applyDiscount).reduce((a, b) => a + b, 0);

// Return from another function

const welcomeDiscount: ApplyDiscount = (price: number) =>
    applyFlatDiscount(10, price);

const createBlackFridayDiscount = (): ApplyDiscount => {
    const now = dayjs();
    if (now.isSame(blackFridayOf(now.year()), "day")) {
        return (price: number) => applyPercentageDiscount(0.5, price);
    } else {
        return (price: number) => price;
    }
}

// Store in a data structure

const discountStrategies = [
    welcomeDiscount,
    createBlackFridayDiscount(),
];

Curried by default

In F#, functions are curried by default, meaning they inherently take arguments one at a time, returning a new function for any remaining arguments. This design offers several advantages:

• Makes partial application easy and allows dependency isolation.

• Improves function composition and modularity.

• Enables pipeline oriented programming.

// default
let add x y = x + y
// explicitly curried
let add x = fun y -> x + y

let result = add 2 3
let addTwo = add 2

const add = (x: number) => (y: number) => x + y;
const result = add(2)(3);
const addTwo = add(2);

For more info: Currying.

Strongly Typed and Type Inference

It's occurred to me many times that I do a refactoring in a F# codebase during days, and at the end I run the tests and everything is green. It's amazing how confident we are during major refactorings. This is possible thanks to F#’s strongly typed system and its type inference feature.
While one allows us to rely on the compile-time safety, the other allows us to focus on logic and not types. The perfect balance between safety and flexibility.

The other super power I love is the domain modeling excellence. The strongly typed system lets us model complex domains, while type inference allows us to do so without making our code messy with annotations.

I highly recommend reading this excellent book: Domain Modeling Made Functional.

Pipeline Oriented

Pipeline-oriented programming in F# is a style of programming that utilizes the |> operator to create clear and concise code by chaining function calls. This approach focuses on the flow of data through a sequence of transformations or operations, making the code more declarative and readable.

This could lead to the Railway oriented programming which is an elegant pattern for chaining together error-generating functions in a clean and composable way.

let processOrders rawOrders =
    rawOrders
    |> read
    |> List.choose parseOrder // Parse and filter invalid orders
    |> List.map calculateTotal // Calculate total price for valid orders
    |> List.sortBy _.TotalPrice // Sort orders by total price

// alternative way with function composition
let processOrders =
    read
    >> List.choose parseOrder
    >> List.map calculateTotal
    >> List.sortBy _.TotalPrice

const processOrders = (rawOrders: Order[]) =>
    read(rawOrders)
        .map(parseOrder)
        .filter((order): order is Order => order !== null)
        .map(calculateTotal)
        .sort((a, b) => a.TotalPrice - b.TotalPrice);

Structural Equality

Structural equality aligns well with immutability and refers to comparing two objects based on their actual content or structure, rather than their references or memory addresses. This is a key to enable consistent behavior, making the comparison predictable and reliable.

This is a valuable asset for domain modeling and tests, especially when we focus on the behavior and not its implementation. Once we have tasted this feature, it’s pretty hard to think differently.

Most F# types have built-in immutability, equality, comparison, and pretty printing. And it’s easily possible to change these type behaviors with attributes.

For more info: Equality is Hard and Out-of-the-box behavior for types.

// all the following expressions are true
[3; 2; 1] = [3; 2; 1] // list
{ Amount = 10m; Currency = EUR } = { Amount = 10m; Currency = EUR } // record
(7, "hello", true) = (7, "hello", true) // tuple
type Cart = Jack | Queen | King // union
King > Jack

As this is not aimed to be supported by JavaScript, there is no sample for it. But there are some hacky way to make a deep comparison such as Lodash library.

Pattern Matching and Active Patterns

Pattern Matching in F# is extremely valuable and it’s on the 3 of the features that I use the most.
Many patterns are available by default, such as constant, identifier, variable, list, array, tuple, record, etc. And it’s possible to enrich or to group this with Active Patterns in order to make very complex rules readable and understandable. When I go back to read mainstream languages code, and I see crazy branching with if/else/switch, it hurts my eyes and my brain.

Another benefit is the feedback on incomplete pattern matches. While with mainstream languages we could have this during the runtime by throwing an error, with F# we can rely on the compiler, linter, or the language server. One of many reasons that make refactoring more affordable.

let (|Strike|Spare|Open|Last|) rolls =
    match rolls with
    | 10 :: rest -> Strike rest
    | r1 :: r2 :: rest when r1 + r2 = 10 -> Spare (r1, r2, rest)
    | r1 :: r2 :: rest -> Open (r1, r2, rest)
    | _ -> Last rolls

let calculateBowlingScore rolls =
    let rec score frames total rolls =
        match frames, rolls with
        | 0, _ ->
            total
        | _, Strike nextRolls -> 
            let bonus = nextRolls |> List.take 2 |> List.sum
            score (frames - 1) (total + 10 + bonus) nextRolls
        | _, Spare (r1, r2, nextRolls) ->
            let bonus = nextRolls |> List.tryHead |> Option.defaultValue 0
            score (frames - 1) (total + 10 + bonus) nextRolls
        | _, Open (r1, r2, nextRolls) ->
            score (frames - 1) (total + r1 + r2) nextRolls
        | _, Last lastRolls ->
            total + List.sum lastRolls
    score 10 0 rolls

type Frame =
  | { kind: "Strike"; rolls: number[] }
  | { kind: "Spare"; rolls: number[] }
  | { kind: "Open"; rolls: number[] }
  | { kind: "Last"; rolls: number[] };

function classifyRolls(rolls: number[]): Frame {
  if (rolls[0] === 10) {
    return { kind: "Strike", rolls: rolls.slice(1) };
  } else if (rolls[0] + rolls[1] === 10) {
    return { kind: "Spare", rolls: rolls.slice(2) };
  } else if (rolls.length >= 2) {
    return { kind: "Open", rolls: rolls.slice(2) };
  } else {
    return { kind: "Last", rolls };
  }
}

function calculateBowlingScore(baseRolls: number[]): number {
  const score = (frames: number, total: number, rolls: number[]): number => {
    if (frames === 0 || rolls.length === 0) return total;
    const frame = classifyRolls(rolls);
    switch (frame.kind) {
      case "Strike": {
        const bonus = rolls.slice(1, 3).reduce((sum, roll) => sum + (roll || 0), 0);
        return score(frames - 1, total + 10 + bonus, frame.rolls);
      }
      case "Spare": {
        const bonus = rolls[2] || 0;
        return score(frames - 1, total + 10 + bonus, frame.rolls);
      }
      case "Open": {
        const frameScore = rolls[0] + rolls[1];
        return score(frames - 1, total + frameScore, frame.rolls);
      }
      case "Last": {
        return total + frame.rolls.reduce((sum, roll) => sum + roll, 0);
      }
    }
  };

  return score(10, 0, baseRolls);
}

For more info: Pattern Matching

Computation Expressions and Comprehensions

Computation Expressions (CEs) are the Swiss army knife of F#. They allow us to define and customize the behavior of a series of computations, encapsulating additional logic such as error handling, state tracking, asynchronous operations, sequence generation, or powerful DSLs.
When CEs have For, Combine, Yield, and Zero methods, they can be identified as comprehensions, like List, Array and Sequence comprehensions.

Here is an example of a custom CE of a neat behavior testing:

let spec = DeciderSpecfication (State.initial, evolve, decide)

[<Fact>]
let ``negative balance cannot be closed`` () =
    spec {
        Given [ Withdrawn { Amount = 50m; Date = DateTime.MinValue } ]
        When (Close)
        Then (ClosingError (BalanceIsNegative -50m))
    }

This subject is too big to be elaborated in just one article. For more info:

• F# Computation Expressions, 'do' notation and list comprehensions

• The "Computation Expressions" Series

Fable and Bolero

F# is a full stack language. With Fable it’s possible to transpile to JavaScript, Rust, etc, and with Bolero to compile to Wasm. Enabling F# developers to write full-stack applications in a single language. Understanding Elmish could be hard at the beginning but once we understood how it works, it’s so intuitive that you wonder why all frontend views aren’t built this way.

Missing features

I don't want F# to be the kind of language where the most empowered person in the discord chat is the category theorist. - Don Syme

I really appreciate this decision-making. F# is among the most accessible functional programming family. On the other hand, to some extent, I feel limited. That forces me to write more boilerplate code or to fall back and use a more object oriented approach.

• Type classes and traits (suggestion)

• Generalized algebraic data types (suggestion)

• Higher kinded types (suggestion)

Conclusion

F# is more than just a programming language, it’s a gateway to a new way of thinking about software design. By prioritizing clarity, immutability, and composability without sacrificing simplicity. F# enables us to write clean, efficient, and sustainable codebases. Compared to many mainstream languages, F# reduces the cognitive load by design. It’s such a joy to know that the code you have to release will require the minimum maintenance, and if needed the minimum effort to add features or to refactor. Of course there are some bad practices to avoid.

For those accustomed to imperative or object-oriented languages, adopting F# may seem like a leap. Yet, it’s a leap worth taking. F# provides not only a practical alternative for everyday tasks but also a richer toolkit for solving complex problems with ease. Whether you’re building backend services, exploring domain modeling, or creating full-stack applications, F# is an investment in writing better and more reliable code.

If you’re curious about functional programming or looking for a language that balances elegance with pragmatism, F# is ready to surprise you. Give it a try, you may never look at code the same way again.

The Definition

Thanks to the community's advocacy, and particularly the efforts of Oskar Dudycz, we can observe a decrease in the level of confusion between Event Sourcing and Event Streaming or Event Driven. Sometimes, it's also easier to grasp a pattern when we initially learn when it should not be applied.

To make it concise, Mathias Verraes's definition is exceptionally clear:

A system is Event Sourced when:

• the single source of truth is a persisted history of the system's events;

• and that history is taken into account for enforcing constraints on new events.

If the Event Sourcing definition is well-understood, we are already halfway there. However, to reach that point, it's also necessary to understand what an Event Store is in practice. Event stores are essentially key-value databases with features such as atomic writes, optimistic concurrency or idempotency. The key usually consists of a name and an ID, while the value is an ordered list of events. This key-value pairing is commonly referred to as a stream aka history.

Stream's life-cycle

Keep it short! Which means short enough to be able to read the entire stream without any performance issues. To achieve this, prior modeling is crucial. Event Modeling is an excellent method to discover and describe a system using an example of how information has changed within them over time. During the modeling we can define boundaries and independent streams therefore how to keep them short. It's always less expensive to refine or redo a modeling rather than realizing it was a mistake after the implementation or the release.

If this is not possible, my two cents is to avoid Event Sourcing altogether! It's worthless. Big streams are typically anti-patterns and are disguised as CRUD operations, cumulative data or command sourcing.

To clarify this by giving an example, auditing is one of the outcomes of Event Sourcing, but we don't do Event Sourcing solely for the purpose of auditing. So it shouldn't be used for updating entities info. There are other suitable patterns for this.

Snapshots technique is too complex as well and must be at the very bottom of the decision tree.

State VS Projections

The final boss! Which is the confusion between the state and projections. if we aren't familiar with earlier definitions, the failure might occur swiftly. But this one can heart slowly. It's hidden behind many tricks and fixes. However it's an easy boss to fight because it's again a matter of definition.

State

The state is private. It’s built only in-memory each time we load the history. That’s all! As said before It's used to enforce constraints on new events. Jérémie Chassaing's explanation is quite straightforward:

1. Reduce the history by evolving each event state -> event -> state, to get the current state.

2. Decide command -> current state -> events, to get the command's behavior as new facts.

3. Append new events to the history.

Projections

On the other hand, projections are public and it's very important to point out that there could be many of them. Every time new events are appended to history, projections are triggered right after. Like the state the history is replayed, but this time, it's in order to know how to update the read model.

What's interesting with projections and so read models, is that what is projected is concise and simple and doesn't contain all the internal state and not necessary data. They are optimized for the view and it's cheap to have many of them. No need to have a complex relational databases.

Common misuses are to project the state, to project from one event and not from the history, to not optimize the read models for views, or to make a canonical or monolithic model.

Conclusion

Event Sourcing is a straightforward pattern to both use and understand. However, it's crucial to grasp the definitions, regardless of implementation details.

At some point, I started experiencing soreness in my wrist, to the extend that I had sometimes trouble sleeping. My first step was a quick Google search, which led me to buy a vertical mouse. It helped ease the pain but it was still here. So this time I turned to message boards and YouTube feedback and after some hesitation, I finally decided to take the plunge and to buy a TypeMatrix keyboard.

Choosing an ortholinear keyboard was one of my best decisions. It features a unique design where the keys are arranged in a grid-like pattern, with the rows and columns aligned vertically and horizontally. This arrangement offers two main advantages:

• It reduces the finger travel and improves hand positioning.

• It provides a minimalist aesthetic and a more compact design.

As a result, the wrist experiences less stress and, with practice, doesn’t move at all; only the fingers make slight vertical movements.

The other thing I also told myself, was to switch to ortholinear and bépo (french version of Colemak) layout at the same time. That way, I’d only have to make the effort of learning once, especially since it further reduces finger movement. Why stick with an outdated, illogical layout anyway?

As you can see the middle line is the most used:

Above all, what surprised me the most was my ability to effortlessly switch between ortholinear bépo and staggered qwerty keyboards. My theory is that the two layouts are so distinct that the brain instinctively adapts to the switch.

Unfortunately, even with all these efforts, the wrist pain returned slightly after three years. I realized I needed to do more, but at least I understood the underlying issues:

• My hand traveled too much between the keyboard and the mouse.

• The Shift, Control, and Alt combinations for shortcuts felt unnatural and illogical.

• The TypeMatrix keyboard forced me to keep my hands too close together which is not a natural position.

It was time to buy a split keyboard aaaand to switch to NeoVim by the way!

What a joy! It took me some time to find a layout that suited my habits, but I eventually settled on a custom Bépo layout with two layers. I still tweak it occasionally to optimize further. You can find the layout at ZSA website.

With split ortholinear keyboards and modern layouts, finger and wrist movements are minimized, and there's no longer a need to look at the keyboard.

Here is my heat-map (of my old Moonlander) after a few minutes of coding:

Now it was time to learn NeoVim. Interestingly enough, I think I spent far more time configuring Vim bindings than actually learning Vim itself. In reality, Vim is surprisingly easy to pick up, especially with the help of the Which-Key plugin already included in the LazyVim distribution. Everything about it feels natural and logical, particularly the Vim Motions. However, configuring bindings is an entirely different story, it's such a tedious process!

NeoVim allows us to stay fully focused on code

Since I use a completely different layout than QWERTY, I never found the classic h, j, k, l keys convenient. In the past, this was one of the main reasons I hesitated to switch to Vim (along with the lack of LSPs). This time, as a gamer, I decided to take the opportunity to configure classic gaming-style arrow keys for the left hand, and as the result, to reconfigure u, i, p, e. You can find my dotfiles on my GitHub.

After several months of using NeoVim on Windows, I began to feel increasingly limited. The main reason is that the user experience in Windows is vertical and dictated by Microsoft's vision and roadmap, whereas Linux provides a horizontal experience shaped by users themselves, thanks to tools and contributions from the community. The second reason is that Windows is heavily GUI-centric, while Linux is CLI/TUI-centric, which is far better suited for developers, especially with the rise of the new Rust CLI tools ecosystem.

Linux is distraction-free by default

I did some research and ultimately chose Cosmic Desktop. It’s the only desktop I found that has a great tiling window manager without hassle. Fedora Cosmic Atomic is the perfect match as Linux distribution. Immutable systems are secure and require low maintenance.

Vimium also lets me browse without needing the mouse at all.
Finally the only application that still forces me to use the mouse is… Slack!

I usually launch Wezterm or Ghostty in full screen and without borders, and start coding or doing other tasks. I would love to never have to leave my terminal and start to click-click-click...

Conclusion

I no longer have wrist pain, and in the process, I’ve gained in productivity.
What more could anyone ask for!