Last year we took over a Symfony e-commerce application that was struggling under a combination of high customer traffic and a constant flood of write operations from external systems: product updates, price changes, availability feeds, all hitting the application simultaneously. The Messenger setup was already in place. Messages were being dispatched. Workers were running. On paper, everything was fine.

In practice, the workers were consuming 600MB of memory and climbing. The queue had thousands of unprocessed messages backed up. The failure transport (never monitored) contained over 400 entries, some of them weeks old. And because product availability messages were sharing a transport with payment confirmation messages, a slow availability handler was blocking payment confirmations for customers trying to check out.

No single thing was catastrophically wrong. The problems were configuration decisions that looked reasonable in isolation and fell apart under load. We fixed them: restructured the transports, configured proper retry strategy, added memory limits, set up failure transport monitoring, separated handler concerns. The instability went away.

This is a writeup of what we changed and why. It assumes you know Symfony. It is not a getting-started guide.

Your Message Classes Will Outlive Your Code

Most developers treat message classes like DTOs: a constructor, some readonly properties, done. That works fine until you deploy a change, a hundred messages with the old payload are still sitting in the queue, and deserialization starts throwing.

A message class is not a DTO. It is a versioned contract between two processes that may be running different code. Unlike a DTO, you can't just change it and move on.

Versioning is not optional, it is inevitable. Adding a required constructor parameter to a message class will fail deserialization for any messages already sitting in the queue with the old payload. You have two options: make new parameters optional with a default, or version the class explicitly.

Optional parameters are fine for purely additive changes:

final class SendInvoice
{
    public function __construct(
        public readonly int $orderId,
        public readonly ?string $locale = null, // added in v2, defaults gracefully
    ) {}
}

For anything that changes the meaning of the message, not just the signature, version it explicitly:

// Keep SendInvoice alive until its queue is fully drained.
// Only remove it in a follow-up deployment.
final class SendInvoiceV2
{
    public function __construct(
        public readonly int $orderId,
        public readonly string $locale,
        public readonly string $templateId,
    ) {}
}

The deployment sequence matters: first deploy SendInvoiceV2 alongside both handlers, wait for the SendInvoice queue to drain completely, then remove the old class in a separate deployment. During the drain window you need both handlers live: SendInvoiceHandler consuming the old queue, SendInvoiceV2Handler consuming new dispatches. Do not remove the old handler before the old queue is empty. This is a two-deployment operation, not one.

Skip the drain step and you get deserialization exceptions that are impossible to reproduce locally, appearing hours after a deployment when an old worker picks up a message for a class that no longer exists.

Sometimes the drain window is not an option. If the queue has tens of thousands of messages and the client needs the change deployed now, you have two paths. The first is a compatibility shim: keep the old message class but make it deserialize into the new handler by implementing a custom DenormalizerInterface that maps old payloads to the new shape. It is extra code but it eliminates the drain dependency entirely. The second is a forced drain: temporarily scale workers up aggressively to exhaust the queue fast, then deploy. Neither is elegant, but both are better than deploying a breaking change against a live queue and discovering the consequences at 3am.

The secondary concern, and it matters just as much, is entity state drift. Don't put Doctrine entities in messages. By the time the handler runs, the order that was pending when the message was dispatched might now be cancelled. Fetch fresh state in the handler, carry only the intent-critical values that must reflect the moment of dispatch:

// This looks convenient. It will eventually cause a subtle bug.
final class ProcessRefund
{
    public function __construct(public readonly Order $order) {}
}

// This forces the handler to work with current reality,
// while preserving the amount the customer was actually charged.
final class ProcessRefund
{
    public function __construct(
        public readonly int $orderId,
        public readonly string $currency,
        public readonly int $amountCents,
    ) {}
}

Currency and amount are explicit not because they cannot be fetched from the order (they can), but because they represent the intent at the moment of dispatch. If the order amount is corrected between dispatch and consumption, the refund should reflect what was charged, not what was later edited.

Transport Configuration: The Defaults Will Eventually Let You Down

In the application we inherited, all messages shared a single doctrine:// transport. Product availability updates, price syncs, order confirmations, invoice generation: all in the same queue, all consuming from the same database table under load. That is not a configuration mistake exactly. It is what you get when you follow the getting-started guide and never revisit it.

The Doctrine transport is recommended because it requires no additional infrastructure. Fair enough. But it uses SELECT ... FOR UPDATE SKIP LOCKED to claim messages. Multiple workers polling the same table means database load that scales with worker count, not message volume. Under the kind of write pressure we were seeing (external systems pushing thousands of product updates per hour), the lock contention was visible in slow query logs and was adding latency to the same database handling customer requests.

If you are on PostgreSQL, switch to the native PostgreSQL transport:

MESSENGER_TRANSPORT_DSN=postgresql://user:password@localhost/dbname

It usesLISTEN/NOTIFY. Workers sleep until a message arrives instead of polling. The migration from doctrine:// is a drop-in replacement. There is no good reason to stay on the polling transport if you are already on PostgreSQL.

Turn off auto_setup in production:

transports:
    async:
        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
        options:
            auto_setup: false

auto_setup: true creates the messenger_messages table the first time a message is dispatched. Convenient in development. In production, your deployment process should own schema changes. Create the table via a Doctrine migration and turn auto_setup off outside local development.

For Redis, set stream_max_entries. Redis Streams are append-only by default and grow indefinitely without trimming:

MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages/symfony/consumer?stream_max_entries=2000

The number depends on your throughput and how much recent history you want visible for debugging. We use 2000 in our e-commerce setups. Enough to see recent activity, bounded enough that memory usage stays predictable.

Separate transports by concern. This was the most impactful single change we made to the inherited application. Payment confirmations and product availability updates have completely different latency requirements, different failure modes, different acceptable retry windows. One slow handler type on a shared transport holds up everything else:

framework:
    messenger:
        transports:
            catalog_sync:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                options:
                    queue_name: catalog_sync
            orders_high:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                options:
                    queue_name: orders_high
        routing:
            App\Message\UpdateProductAvailability: catalog_sync
            App\Message\UpdateProductPrice: catalog_sync
            App\Message\SendOrderConfirmation: orders_high
            App\Message\SendInvoice: orders_high

Give each transport a dedicated worker. A slow catalog sync handler on a shared transport was the direct cause of delayed payment confirmations in the system we inherited. Separate workers, separate queues, separate failure modes:

# Run dedicated workers per transport
php bin/console messenger:consume catalog_sync --memory-limit=128M --time-limit=3600
php bin/console messenger:consume orders_high --memory-limit=256M --time-limit=3600

Correction (March 2026)

The advice on switching to the PostgreSQL-native transport is outdated, and I should have caught this before publishing.

The article states that doctrine:// uses polling and that switching to the native PostgreSQL transport is necessary to get LISTEN/NOTIFY behaviour. That was true before Symfony 5.1. Since then it is not — though I should be precise about what "since 5.1" actually means, because the history here is slightly messier than a clean version bump suggests.

The feature was introduced in PR #35485 by Kévin Dunglas and merged into the 5.1 branch. The official documentation picked it up in 5.2. There were also meaningful bug fixes to the PostgreSQL connection behaviour in 5.2 and 5.3, so if you were on 5.1 at launch you may have hit rough edges. The canonical advice has been "use 5.1 or later", but in practice "5.3 or later" is where it became solid.

The factory code tells the story clearly:

$useNotify = $options['use_notify'] ?? true;

if ($useNotify && $driverConnection->getDatabasePlatform() instanceof PostgreSQLPlatform) {
    $connection = new PostgreSqlConnection($configuration, $driverConnection);
}

use_notify defaults to true. If your connection is PostgreSQL, Symfony detects the platform and routes you to PostgreSqlConnection with LISTEN/NOTIFY automatically. You do not need to change your DSN. You do not need to migrate anything.

The line "there is no good reason to stay on the polling transport if you are already on PostgreSQL" is wrong. You are not on the polling transport. You never were, assuming a maintained Symfony version.

Set use_notify: false only if you have a specific reason to opt out. Otherwise, leave it alone and it works.

Retry Strategy: The Defaults Are Too Aggressive

Three retries. One second delay. Multiplier of two. Retries at 1, 2, and 4 seconds. Total window: about 7 seconds before a message lands in the failure transport.

Consider what that covers: a service restarting after a deployment typically needs 20 to 60 seconds. A rate-limited external API may respond with 429 for several minutes. A transient network partition can last longer than 7 seconds. The default retry window is too short for anything involving an external dependency, and in a system receiving constant feed updates from external systems, external dependencies are everywhere.

A more realistic starting point:

transports:
    catalog_sync:
        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
        retry_strategy:
            max_retries: 5
            delay: 5000        # 5 seconds
            multiplier: 3
            max_delay: 300000  # cap at 5 minutes

Retries at 5s, 15s, 45s, 2min 15s, and then 5min (capped by max_delay). Without the cap, retry 5 would be 405 seconds. The max_delay brings it down to a sensible ceiling. That spread covers most transient failures without waiting so long that the failure transport fills up during a routine dependency outage.

Classify your failures explicitly. This is where most Messenger implementations waste their retry budget: retrying errors that will never resolve, burning through retries in seconds, flooding the failure transport with messages that should have been discarded immediately:

#[AsMessageHandler]
final class SyncProductAvailabilityHandler
{
    public function __construct(
        private readonly ProductRepository $productRepository,
        private readonly WarehouseApiClient $warehouseClient,
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(UpdateProductAvailability $message): void
    {
        $product = $this->productRepository->findBySku($message->sku);

        if ($product === null) {
            // The product no longer exists in our catalog.
            // Retrying will not change that. Discard immediately.
            throw new UnrecoverableMessageHandlingException(
                sprintf('Product SKU %s not found, discarding availability update', $message->sku)
            );
        }

        try {
            $availability = $this->warehouseClient->getAvailability($message->sku);
            $product->updateAvailability($availability);
            $this->productRepository->save($product);
        } catch (WarehouseApiRateLimitException $e) {
            // The API will accept this later. Worth retrying.
            throw new RecoverableMessageHandlingException(
                'Warehouse API rate limited, will retry',
                previous: $e
            );
        } catch (WarehouseApiProductNotFoundException $e) {
            // The warehouse does not know this SKU either. Retrying is pointless.
            throw new UnrecoverableMessageHandlingException(
                sprintf('SKU %s unknown to warehouse API', $message->sku),
                previous: $e
            );
        }
    }
}

UnrecoverableMessageHandlingException bypasses the retry strategy entirely and goes straight to the failure transport. RecoverableMessageHandlingException forces a retry even for exception types Messenger would not normally retry. In the application we inherited, unclassified exceptions from a warehouse API that was frequently rate-limiting were consuming the entire retry budget in 7 seconds, then flooding the failure transport. Classifying them correctly, and extending the retry window, reduced failure transport entries by roughly 80% without changing a single line of handler logic.

Handlers Must Be Idempotent

We found this out the hard way. When we scaled the catalog workers from one process to three, two handlers ran simultaneously on the same SKU. Both read the current stock figure of 1. Both decremented it. We ended up with -1 inventory on a product that had just sold its last unit. The handlers had been written assuming sequential execution. Three parallel workers made that assumption false.

A message can be delivered more than once under normal operating conditions. Not just from bugs. A worker can process a message successfully and crash before sending the acknowledgement. The transport redelivers. On a Redis or AMQP transport with manual acknowledgement, a network hiccup between the handler completing and the ack being sent means the broker considers the message undelivered and requeues it. In a high-volume system this is not an edge case. It is routine.

If running a handler twice produces different outcomes (decremented stock, duplicate charge, second confirmation email), you have a correctness problem that no amount of retry configuration will fix.

For catalog sync the fix was straightforward: replace the decrement with an absolute write. The warehouse feed sends the current stock figure, not a delta. Writing it twice is harmless. That is natural idempotency and it is the easiest kind to achieve: design the operation as a set rather than an increment wherever the domain allows it.

For payment handlers the domain does not allow it. A charge is inherently an increment. The fix there is an idempotency key that derives from the business event, not from the dispatch:

// The key is generated when the payment intent is created, before dispatch.
// It is stable: the same order at the same version always produces the same key.
// A double-submit or a redelivery carries the same key. Both are caught.
final class ProcessPayment
{
    public function __construct(
        public readonly int $orderId,
        public readonly string $idempotencyKey, // e.g. "payment-{orderId}-{orderVersion}"
    ) {}
}

A UUID generated at dispatch time does not work. If the controller dispatches twice (double form submission, request timeout with retry), each dispatch generates a new UUID and both pass the idempotency check. The key must be stable across any number of deliveries of the same logical event:

#[AsMessageHandler]
final class ProcessPaymentHandler
{
    public function __invoke(ProcessPayment $message): void
    {
        if ($this->paymentRepository->existsByIdempotencyKey($message->idempotencyKey)) {
            $this->logger->info('Duplicate payment message, skipping', [
                'idempotency_key' => $message->idempotencyKey,
                'order_id' => $message->orderId,
            ]);
            return;
        }

        // ... process payment, store record with idempotency key
    }
}

The database-level uniqueness constraint on idempotency_key is the actual safety net. The existsByIdempotencyKeycheck is an optimisation that avoids calling the payment gateway unnecessarily. Without the constraint, two concurrent deliveries can both pass the check before either has written the record, and both attempt the charge.

Design for idempotency when you write the handler, not after you find negative inventory in a live catalog.

Memory Leaks: Long-Running Processes Require Different Habits

Workers are long-running PHP processes and PHP accumulates memory. Leaks that do not matter in a 50ms request lifecycle compound over hours in a worker. In the application we took over, workers had no memory limits and no restart schedule. By morning they were consuming 600MB each and climbing. The server was struggling and workers with no ceiling were a direct contributor.

The primary source is Doctrine. The entity manager accumulates every object it loads in its identity map and never releases them. In a worker processing thousands of messages per hour, each loading several entities, the identity map grows without bound.

Symfony's ResetServicesMiddleware handles this by calling $container->reset() after each message, which clears the identity map and resets other stateful services. It is in the default middleware stack. Don't remove it, and verify it is present if you have customized the stack.

The second source is your own code: static properties, unbounded service-level caches, third-party libraries holding references. Profile worker memory over time. Log memory_get_usage(true) with each message, graph it over an hour, watch for growth that does not plateau after the first few messages.

The operational fix regardless of whether you have traced every leak:

php bin/console messenger:consume async --memory-limit=256M --time-limit=3600

--memory-limit causes the worker to finish the current message and exit cleanly when it crosses the threshold. --time-limit restarts it after an hour regardless of memory. This catches slow drifts that ResetServicesMiddleware does not cover. Both are non-negotiable in production.

[program:messenger-catalog-worker]
command=php /var/www/app/bin/console messenger:consume catalog_sync --memory-limit=128M --time-limit=3600
user=www-data
numprocs=3
autostart=true
autorestart=true
process_name=%(program_name)s_%(process_num)02d
stderr_logfile=/var/log/messenger-catalog.err.log
stdout_logfile=/var/log/messenger-catalog.out.log

[program:messenger-orders-worker]
command=php /var/www/app/bin/console messenger:consume orders_high --memory-limit=256M --time-limit=3600
user=www-data
numprocs=2
autostart=true
autorestart=true
process_name=%(program_name)s_%(process_num)02d
stderr_logfile=/var/log/messenger-orders.err.log
stdout_logfile=/var/log/messenger-orders.out.log

The catalog worker runs three processes because catalog sync is high volume and the handlers are fast. The orders worker runs two: lower volume but more critical, and handlers call external APIs that occasionally block.

Graceful Shutdown: SIGTERM, Not SIGKILL

Workers respond to SIGTERM by finishing the current message and exiting cleanly. The message is acknowledged, the worker stops. SIGKILL is not graceful. A message mid-processing is not acknowledged, and depending on your transport's visibility timeout it may be redelivered or lost.

This matters at deployment time. If your deployment pipeline stops workers with SIGKILL (the default for many container orchestration setups if you are not explicit), you will occasionally interrupt a handler mid-execution. In an e-commerce context, that might mean a payment is partially processed, an inventory update is half-written, or an invoice is generated but not sent.

In Kubernetes, set terminationGracePeriodSeconds long enough for your longest-running handler to complete:

spec:
  terminationGracePeriodSeconds: 60

Supervisor uses SIGTERM by default and waits for the process to exit before restarting, so it handles this correctly out of the box.

The piece most deployment guides skip is how workers restart during a code deployment. Supervisor will restart a worker automatically when it exits, but you need the workers running the new code, not stuck processing messages with the old codebase. The reliable approach is to run messenger:stop-workers as a deployment step after your code is on disk but before traffic shifts:

# In your deployment script, after code deploy and cache warmup:
php bin/console messenger:stop-workers

This sets a cache flag that tells each worker to finish its current message and exit cleanly. Supervisor restarts them, they pick up the new code, and the transition happens without a forced kill or a gap in processing. If you are on Kubernetes and running workers as a separate Deployment, a rolling restart achieves the same thing, but only if terminationGracePeriodSeconds is long enough for the current message to finish before the pod is replaced.

The Failed Transport: Your Production Safety Net

Every message that exhausts its retries ends up in the failure transport. If you have not configured one, they are dropped silently. Configure it:

framework:
    messenger:
        failure_transport: failed
        transports:
            failed:
                dsn: 'doctrine://default?queue_name=failed'

The 400 entries we found in the inherited application's failure transport when we took it over (some of them weeks old) were the direct result of nobody monitoring this queue. Product availability for discontinued SKUs, orders referencing deleted customers, payment messages for cancelled subscriptions. Most were legitimately unrecoverable. Some were failures caused by a bug that had since been fixed. Without monitoring, nobody knew.

Treat the failure transport as a production incident queue. We wrap messenger:failed:show in a cron job, pipe the count into our monitoring platform, and page on-call if it exceeds a threshold. The specific tooling does not matter. Growth in the failure transport should be investigated the same day, not discovered during a quarterly review.

Failed messages go through the full middleware stack again when you replay them. If the failure was a handler bug you have since fixed, replaying is safe. If it was a transient infrastructure issue that has resolved, same. If it was data-related (entity deleted, third-party account closed), replaying will produce another UnrecoverableMessageHandlingExceptionand the message will be cleaned up. Inspect before replaying blindly:

php bin/console messenger:failed:show --max=20
php bin/console messenger:failed:retry 42     # specific message
php bin/console messenger:failed:retry        # all: use with caution

Use separate failure transports per transport. Mixing catalog sync failures with order failures in the same queue makes triage slower than it needs to be:

transports:
    catalog_sync:
        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
        failure_transport: failed_catalog
    orders_high:
        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
        failure_transport: failed_orders
    failed_catalog:
        dsn: 'doctrine://default?queue_name=failed_catalog'
    failed_orders:
        dsn: 'doctrine://default?queue_name=failed_orders'

The Doctrine Transaction Gotcha That Silently Eats Messages

If you have customized the Messenger middleware stack and your messages are mysteriously ending up in the failure transport with "entity not found" errors that cannot be reproduced locally, check whether DoctrineTransactionMiddleware is still in your chain. Its absence is one of the harder failure modes to diagnose because nothing obviously breaks: the message is dispatched, the worker picks it up, the handler fails cleanly, and the retry clock starts. By the time the transaction that created the entity commits, the message has exhausted its retries.

The middleware holds transport sends until after the transaction commits. Remove it and dispatch happens immediately, before the row exists. Verify it is present if you have a custom chain:

framework:
    messenger:
        buses:
            command.bus:
                middleware:
                    - doctrine_transaction

The second scenario bites in a different way. If your handler dispatches a follow-up message and the outer handler later throws, rolling back the transaction, that inner message has already been sent. The follow-up handler runs against data that was never committed. No error, no indication anything is wrong. Just work being done against a row that does not exist.

DispatchAfterCurrentBusStamp defers the inner dispatch until the outer handler completes without throwing:

#[AsMessageHandler]
final class PlaceOrderHandler
{
    public function __invoke(PlaceOrder $message): void
    {
        // ... write order to database inside a transaction

        // Not dispatched until this handler returns successfully.
        // Transaction rollback = this message never leaves the bus.
        $this->bus->dispatch(
            new SendOrderConfirmation($message->orderId),
            [new DispatchAfterCurrentBusStamp()]
        );
    }
}

Use this stamp any time you dispatch from inside a handler. The cases where you don't need it are rarer than the cases where you do.

Stamps Worth Knowing Beyond DelayStamp

DelayStamp is well-documented. Three others are just as useful and rarely appear in tutorials.

TransportNamesStamp overrides routing at dispatch time. In our agency work, premium merchants get their order processing routed to a dedicated high-priority transport regardless of what the YAML routing says. Encoding that in YAML would mean a new routing rule for every merchant tier. Encoding it at the dispatch site means the business logic lives where the decision is made:

$stamps = $merchant->isPremium()
    ? [new TransportNamesStamp(['orders_premium'])]
    : [];

$this->bus->dispatch(new ProcessOrder($orderId), $stamps);

RedeliveryStamp tracks retry count. Access it in your handler when retry state should influence behaviour, for example to escalate to a manual review queue after several failed attempts:

public function __invoke(SyncProductToErp $message, Envelope $envelope): void
{
    $retries = $envelope->last(RedeliveryStamp::class)?->getRetryCount() ?? 0;

    if ($retries >= 3) {
        $this->operationsQueue->escalate($message->productId, $retries);
        return;
    }

    $this->erpClient->syncProduct($message->productId);
}

AddEnvelope $envelope as a second parameter to __invoke and Messenger injects it automatically.

SentToFailureTransportStamp marks messages that have entered the failure transport. If your monitoring middleware counts all handled messages, use this to separate replays from first-time dispatches. Otherwise your metrics count failure transport replays as new work.

Correction (March 2026)

A member of the Symfony community caught something I got wrong in this section, and they were right.

I wrote that adding Envelope $envelope as a second parameter to __invoke is enough for Messenger to inject it automatically. It isn't. I checked the framework source after the message came in. HandleMessageMiddleware::callHandler() builds its argument list explicitly: the message, optionally an Acknowledger for batch handlers, and anything added via HandlerArgumentsStamp. The Envelope never makes it into that list on its own.

The handler code in the example works. Just not for the reason I gave.

The project this came from has a custom middleware that stamps the envelope as an additional argument before HandleMessageMiddleware runs:

final class InjectEnvelopeMiddleware implements MiddlewareInterface
{
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        return $stack->next()->handle(
            $envelope->with(new HandlerArgumentsStamp([$envelope])),
            $stack
        );
    }
}

I wrote the article from memory of working code. The middleware had become invisible infrastructure, something registered once and forgotten. When I described the handler pattern, I described what I saw in the codebase without tracing it back to what was actually making it work.

The pattern is solid. HandlerArgumentsStamp is the official mechanism for this. If you want the handler signature from the example, register this middleware before HandleMessageMiddleware in your bus configuration and it works exactly as shown.

The sentence about automatic injection was wrong. The rest stands.

Multiple Buses: Earn the Complexity

A single bus is the right default. Add a second bus when you need a different middleware stack, not because CQRS says you should. Those are different reasons.

We learned this the hard way on a project where we introduced a command bus and query bus early, convinced the architectural separation would pay off. It did not. Both buses had identical middleware stacks for the first eight months. The only effect was that every service needed two injected buses, every new developer asked why, and the answer was "for the architecture". That is not a good answer.

We now add a query bus only when the middleware difference is concrete. In our current agency setup, the command bus carries doctrine_transaction middleware and the query bus does not. That difference is real and measurable. Reads do not need transaction overhead:

framework:
    messenger:
        default_bus: command.bus
        buses:
            command.bus:
                middleware:
                    - doctrine_transaction
            query.bus: ~

final class ProductService
{
    public function __construct(
        #[Target('command.bus')] private readonly MessageBusInterface $commandBus,
        #[Target('query.bus')] private readonly MessageBusInterface $queryBus,
    ) {}
}

If you cannot name a concrete difference in what each bus does, you do not need two buses yet.

Testing: What Goes Where

Test handlers as plain PHP classes. Inject mocks, call __invoke, assert the outcome. No Messenger infrastructure:

final class SyncProductAvailabilityHandlerTest extends TestCase
{
    public function testUpdatesAvailabilityForKnownProduct(): void
    {
        $product = new Product(sku: 'ABC-123', availability: 10);

        $repository = $this->createMock(ProductRepository::class);
        $repository->method('findBySku')->with('ABC-123')->willReturn($product);
        $repository->expects($this->once())->method('save')->with($product);

        $warehouseClient = $this->createMock(WarehouseApiClient::class);
        $warehouseClient->method('getAvailability')->with('ABC-123')->willReturn(25);

        $handler = new SyncProductAvailabilityHandler(
            $repository,
            $warehouseClient,
            $this->createMock(LoggerInterface::class)
        );

        $handler(new UpdateProductAvailability(sku: 'ABC-123'));

        self::assertSame(25, $product->getAvailability());
    }

    public function testThrowsUnrecoverableForUnknownProduct(): void
    {
        $repository = $this->createMock(ProductRepository::class);
        $repository->method('findBySku')->willReturn(null);

        $handler = new SyncProductAvailabilityHandler(
            $repository,
            $this->createMock(WarehouseApiClient::class),
            $this->createMock(LoggerInterface::class)
        );

        $this->expectException(UnrecoverableMessageHandlingException::class);
        $handler(new UpdateProductAvailability(sku: 'UNKNOWN'));
    }
}

Use the in-memory:// transport in functional tests to verify that the right message was dispatched in response to an action. If you are following the transport separation from earlier in this article, map each named transport to in-memory:// in your test configuration:

# config/packages/test/messenger.yaml
framework:
    messenger:
        transports:
            catalog_sync: 'in-memory://'
            orders_high: 'in-memory://'

// Assert that placing an order dispatched a confirmation message
// to the orders_high transport, not to catalog_sync, not missing entirely.
/** @var InMemoryTransport $transport */
$transport = self::getContainer()->get('messenger.transport.orders_high');

self::assertCount(1, $transport->getSent());
self::assertInstanceOf(SendOrderConfirmation::class, $transport->getSent()[0]->getMessage());
self::assertSame(42, $transport->getSent()[0]->getMessage()->orderId);

The functional test asserts routing and dispatch. The handler test asserts business logic. They cover different things and should not bleed into each other.

Async Is Not an Upgrade

Use async because it feels sophisticated and you will be living with the consequences for a long time.

In e-commerce specifically, async has costs that are easy to underestimate. An availability update sitting in a queue for 30 seconds is 30 seconds during which a customer can add an out-of-stock product to their cart, proceed through checkout, and reach payment before the handler has run. You have not just delayed a database write. You have created an oversell window. The async layer that was supposed to protect the application under load has introduced a consistency gap directly in the checkout flow.

The same applies to pricing. A price update dispatched asynchronously means there is a window, however brief, where the displayed price and the stored price disagree. For most products that is tolerable. For a flash sale that starts at midnight, it is not.

These are not arguments against Messenger. They are arguments for being deliberate about which operations can afford eventual consistency and which cannot. Availability and pricing updates that feed from external systems are genuinely good candidates for async. The volume is too high for synchronous handling and the latency is bounded. But the decision should be made explicitly, with the consistency window understood, not by defaulting to async because the infrastructure is already in place.

In the application we fixed, async was the right call. The volume of external feed updates was genuinely incompatible with synchronous handling under customer traffic. But the correct Messenger setup for that application required transport separation, failure monitoring, idempotent handlers, memory-bounded workers, and a retry strategy matched to the actual failure modes. The component was already installed. None of that was configured.

That gap, between "Messenger is installed" and "Messenger is working correctly under production conditions", is what this article is about.

What We Actually Delivered

None of the fixes were exotic. The Symfony Messenger component was already doing exactly what it was configured to do. That was the problem.

A single shared transport meant catalog sync volume could starve order processing. Separating them meant the payment confirmation backlog cleared within minutes. Not because anything got faster, but because the two workloads stopped competing for the same queue.

Workers without memory limits ran until the server complained. The 600MB figure was not a memory leak in the traditional sense. It was Doctrine's identity map accumulating every loaded entity in a process that had been running for days. --memory-limit and --time-limit brought it down to a stable 80-120MB range.

The 400 failure transport entries were the most instructive part. Roughly a third were genuinely unrecoverable: deleted products, closed merchant accounts, SKUs the warehouse had never heard of. They had been burning through retries in 7 seconds and sitting in the failure queue unnoticed for weeks. Proper exception classification would have discarded them on the first attempt. The remaining two thirds were transient failures: rate limits, a deployment window where an upstream service was briefly unreachable. A wider retry window would have resolved all of them without ever touching the failure transport.

It was not all clean. When we separated the transports and restarted the workers, we discovered that three handler classes were not idempotent. That had never mattered with a single slow worker, but became obvious immediately when three catalog workers started running in parallel. The first sign was a product showing -1 stock in the catalog. Two availability handlers had picked up the same SKU simultaneously. Both queried the current stock figure of 1. Both decremented it. Neither knew the other existed. The race had always been possible in theory; the single-worker setup had just made it vanishingly unlikely in practice.

We had to stop the catalog workers, audit all handler classes that touched shared state, add idempotency keys to the messages, add uniqueness constraints at the database level, and redeploy before restoring full worker concurrency. It took most of a day. The fix itself was not complicated: switch from decrements to absolute writes for the availability handlers, add the idempotency key pattern for the two handlers where that was not possible. Finding every affected handler and being confident we had not missed one was the slow part. This is exactly the kind of thing you want to discover in a staging environment under a load test, not on a live catalog at 11am on a Wednesday.

That complication aside, the application has been stable under the same traffic and feed volume ever since. The queue depth stays low. The failure transport gets a handful of entries per week, all unrecoverable, all expected.

That is what a well-configured Messenger setup looks like. Not invisible, but quiet.

Clean code is dead. The AI doesn't care about your variable names, your single responsibility principle, your beautifully extracted service classes. It'll read your 800-line controller and generate another one without blinking. The humans are leaving the loop.

Why are we still writing code for them?

Because the AI is the loop now. And you just taught it everything.

The Pattern Matcher in Your Codebase

AI assistants are pattern matchers. Your codebase is the pattern.

Every autocomplete suggestion, every refactor request, every "explain this function" runs through a model trying to understand what normal looks like here. What the conventions are. What this team considers acceptable.

It doesn't read your best code first. It reads all of it, equally. The clean service you wrote on a good Tuesday and the nightmare controller you hacked together at 6pm before a deadline carry the same weight. Same influence. Same lesson absorbed.

You already have an AI apprentice. It showed up the moment you installed Copilot, opened Cursor, or started pasting code into Claude. No interview. No onboarding. It just started watching and learning.

A human junior eventually pushes back. Asks "should this really be in the controller?" Gets uncomfortable and starts questioning it. The AI never gets uncomfortable. It sees the fat controller and thinks: this is how we do things here. Then it makes another one. Faster. With more features. In places you haven't looked at yet.

The question isn't whether it learned from you. It's what you taught it.

Someone Has a Different Theory

Last week, Joppe De Cuyper published "I deleted my source code." He built a Symfony app with an empty src/ directory. No committed code. On every CI run, an AI agent reads a spec file and a test suite, generates the full implementation, runs the tests, and throws everything away. The spec is the source. Code is a build artifact, like a compiled binary.

His conclusion: code is becoming disposable. Clean code is a convention we built for humans, not machines. The machine doesn't care about your naming. It'll generate an 800-line controller and move on.

The direction of travel is real. But his proof of concept is a greenfield TODO app. Clean domain. Controlled from the start. No legacy, no accumulated edge cases, no fix from 2019 that lived only in the implementation because nobody updated the spec.

He admits it himself: "Most knowledge in a codebase is implicit." The bug you fixed last year. The subtle business rule that exists because a client complained once in 2022. The performance hack that solved a real production problem. None of that is in the spec. It's in the code. Regenerate, and it's gone.

His experiment works because he controlled every variable. Most of us are working in codebases that have been out of control for years. There's no spec to regenerate from. There's just what was left behind. And the AI is working from it right now, on the ticket that just got assigned.

The Machine Absolutely Cares About Your Variable Names

This is the part of Joppe's argument that sounds right and isn't.

The interpreter doesn't care. $x parses identically to $userEmailAddress. The runtime has no opinions about your naming choices.

The AI assistant isn't the runtime. It's an LLM, and LLMs understand code through semantics. The meaning of names. The shape of structures. The relationship between concepts. All of it feeds into how the model reasons about what your code does and what it should do next.

A method called process() that does three different things depending on an internal flag gives the model nothing. It guesses. Then it commits to that guess, because these models don't say "I'm not sure." They pattern-match to the most plausible continuation and ship it.

A method called markTaskAsCompleteIfSubtasksAreDone() is a different thing entirely. Preconditions, side effects, intent — all communicated before a single suggestion is made. Every line generated nearby is shaped by that clarity.

Clean naming isn't aesthetics. It's signal. Signal is what separates an AI that makes you faster from one that introduces bugs in files you haven't opened in months.

Give it noise, it generates noise. That's not a metaphor. It's just how the math works.

The Debt Doesn't Sit Still Anymore

You've been tolerating a mess. The deadline was real. You'd clean it up later. Only teammates would see it.

That tolerance used to cost one thing: a developer, slowed down, on a future ticket. Annoying. Manageable. The kind of debt you could argue you'd eventually address.

The AI changed the math.

Every bad pattern is now a lesson that gets applied again, faster, in more places, with more confidence, across every interaction with your codebase until someone cleans it up. The debt has an engine now. Tireless. Tasteless. Incapable of telling the difference between your best work and your worst.

It used to be linear. Now it compounds. It's been compounding since the day you gave it access.

Specs and Clean Code Aren't Alternatives

Joppe gets one thing right: specs should be where decisions live. Explicit, testable, precise. If your spec isn't detailed enough to generate correct code from, it wasn't detailed enough to build correct code from by hand either.

But specs describe what. Code is where how lives. How you handle two events arriving out of order. How domain logic stays separated from infrastructure. How the subtle business rule actually gets enforced when things get messy at runtime. No spec captures all of that. The implementation is still full of decisions, and when those decisions are buried in noise, the AI guesses at them. Repeatedly. Confidently.

Precise specs make the AI more capable. Clean code makes it more correct. Not competing priorities. Two layers of the same problem.

Write better specs. And clean up the code you actually have today, because that's what the AI is reading right now.

So What Did You Teach It?

The AI is reading your codebase while you read this. Building a model of what normal looks like. Your patterns. Your shortcuts. Your tolerated messes.

In six months, when you open a file you don't recognize, you'll know whose fault it is.

You wrote the curriculum. You left the mess on the desk and called it pragmatism.

Most developers I know use the EventDispatcher the same way. They create an event, wire up a listener, dispatch it somewhere, and move on. It works. Nobody complains.

The problem is that "works fine" is exactly what keeps you from going deeper. I spent years in that spot, using the EventDispatcher for simple notifications and never feeling the need to push further. What I missed were the patterns that actually change how you structure an application. That's what this is about.

The Basics (So We're On the Same Page)

You know this part. Skip ahead if you want.

class OrderPlaced
{
    public function __construct(public readonly Order $order) {}
}

$this->dispatcher->dispatch(new OrderPlaced($order));

#[AsEventListener]
class SendOrderConfirmation
{
    public function __invoke(OrderPlaced $event): void
    {
        // send the email
    }
}

The #[AsEventListener] attribute (Symfony 6.0+) wires the listener automatically. On a class with __invoke, Symfony infers the event type from the type hint of the first parameter. Leave it untyped and it fails silently. That one will bite you eventually.

Stoppable Events

Without stoppable events, a "first responder wins" pattern looks like this:

class ResolvePaymentMethod
{
    public function __invoke(ResolvePaymentMethodEvent $event): void
    {
        if ($event->getMethod() !== null) {
            return; // someone else already resolved it
        }

        if ($this->supports($event->getOrder())) {
            $event->setMethod('stripe');
        }
    }
}

Every listener manually checks whether a previous one already ran. It works, but the contract is implicit. You're trusting that every future developer reads every other listener before writing a new one.

Stoppable events make the contract explicit:

use Symfony\Contracts\EventDispatcher\Event;

class ResolvePaymentMethod extends Event
{
    private ?string $method = null;

    public function setMethod(string $method): void
    {
        $this->method = $method;
        $this->stopPropagation();
    }

    public function getMethod(): ?string
    {
        return $this->method;
    }
}

The moment a listener sets a method, propagation stops. No manual checks. No scattered conditionals.

One caveat I've learned the hard way: use stoppable events on events you fully own. If a third-party bundle registers a listener on the same event at a higher priority, it can stop propagation before yours runs. Silently. No error, no warning. Run debug:event-dispatcher before you assume your listener is executing.

Priorities: Good for Ordering, Unreliable for Correctness

Priorities let you control when listeners run. Higher numbers run first. In Symfony 6.0+ the attribute handles it cleanly:

#[AsEventListener(event: UserRegistered::class, priority: 100)]
class ValidateUserData { ... }

#[AsEventListener(event: UserRegistered::class, priority: 50)]
class CreateDefaultWorkspace { ... }

#[AsEventListener(event: UserRegistered::class, priority: 0)]
class SendWelcomeEmail { ... }

#[AsEventListener(event: UserRegistered::class, priority: -10)]
class LogRegistrationForAnalytics { ... }

On Symfony 5.x, set priorities via getSubscribedEvents(). The nested array format exists because a single event can have multiple listeners in the same subscriber, each with their own priority:

public static function getSubscribedEvents(): array
{
    return [
        // Single listener with priority
        UserRegistered::class => [['onUserRegistered', 50]],

        // Multiple listeners on the same event
        OrderPlaced::class => [['firstHandler', 20], ['secondHandler', 10]],
    ];
}

Here's the thing I keep coming back to with priorities: they're fine for loose ordering. "Logging should happen after the main work." Reasonable. But the moment your application's correctness depends on strict execution order, you're on shaky ground. Any listener from a bundle, or from a colleague who skipped the architecture docs, can slip in at any priority without warning.

Use priorities to express when something runs. If you need to express whether something runs based on what came before, that's a job for explicit service calls, not priority numbers.

Event Subscribers: Co-locating Related Behavior

Subscribers let a single class listen to multiple events. The reason I reach for them is co-location: all the behavior for a given concern lives in one place.

class AuditLogSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            OrderPlaced::class    => 'onOrderPlaced',
            OrderCancelled::class => 'onOrderCancelled',
            OrderRefunded::class  => 'onOrderRefunded',
        ];
    }

    public function onOrderPlaced(OrderPlaced $event): void
    {
        $this->auditLog->record('order_placed', $event->order->getId());
    }

    // ...
}

Logging, auditing, metrics: these are the cases where subscribers earn their keep. The behavior is genuinely independent of the dispatching code. Grouping it by concern, all audit logic together regardless of which events trigger it, makes it easier to find and change.

That said, the discoverability problem is real. A developer debugging a missing audit entry still needs to know AuditLogSubscriber exists. The grouping helps once you know where to look. It doesn't help you find it from the dispatch site. That's a general property of event-driven code, and I think it's worth being honest about before you wire everything this way.

Extension Points: Before and After Hooks

If you're building something others will extend, events are one of the cleanest mechanisms I've found. Inheritance ties you to a class hierarchy. Callback arrays get unwieldy as the number of extension points grows. Events give you explicit contracts that downstream code can hook into without touching yours.

The pattern I use most often is a before/after pair:

class PreOrderProcessing extends Event
{
    private bool $cancelled = false;

    public function __construct(public readonly Order $order) {}

    public function cancel(): void
    {
        $this->cancelled = true;
    }

    public function isCancelled(): bool
    {
        return $this->cancelled;
    }
}

class PostOrderProcessing extends Event
{
    public function __construct(public readonly Order $order) {}
}

class OrderProcessor
{
    public function process(Order $order): void
    {
        if ($this->dispatcher->dispatch(new PreOrderProcessing($order))->isCancelled()) {
            return;
        }

        // ... core processing logic

        $this->dispatcher->dispatch(new PostOrderProcessing($order));
    }
}

A listener on the after hook:

#[AsEventListener]
class NotifyWarehouseAfterOrder
{
    public function __invoke(PostOrderProcessing $event): void
    {
        $this->warehouseNotifier->notify($event->order);
    }
}

OrderProcessor dispatches two events and knows nothing else. Everything that needs to happen before or after plugs in without touching the core. This is how Symfony's HttpKernel works. kernel.request, kernel.response, kernel.exception: the routing and security system hangs off those hooks. The kernel knows nothing about any of it directly.

Where this breaks down is when listeners start needing to feed complex information back to the dispatching code. At that point the indirection is fighting you. A direct service call is clearer.

The Honest Problem: Event-Driven Code is Hard to Trace

I want to be direct about this because I've seen it glossed over in every EventDispatcher tutorial I've read.

When you dispatch an event, the execution path splits across however many listeners are registered. You can't follow it by reading the code at the dispatch site. You have to know the full listener graph, and in a large codebase that's not always obvious.

Symfony gives you tools:

# See all registered listeners
php bin/console debug:event-dispatcher

# Filter by event (single backslashes, works on Linux and macOS without quotes)
# On Windows, behaviour varies by shell; wrap in double quotes if needed
php bin/console debug:event-dispatcher App\Event\UserRegistered

The debug toolbar shows the same for web requests: what fired, in what order, whether propagation stopped. Use both regularly.

But tooling has limits. In a codebase with thirty listeners, debugging an unexpected side effect means tracing a graph, not reading a call stack. That cognitive overhead is real and it compounds as the codebase grows.

One thing that helps: if your listeners are doing work that doesn't need to complete synchronously, dispatch via Symfony Messenger. With the sync transport, messages are handled immediately in the same process. No infrastructure required, but also no retry logic or failure isolation. With an async queue transport, you get retries, failure handling, and full decoupling from the request lifecycle. Either way, you're separating what happened from what should happen next, which makes both sides easier to reason about. I'll come back to this in the domain events section.

When to Reach for It (and When Not To)

After nineteen years of Symfony projects, the framing that's helped me most is this: events are for concerns that are genuinely independent. Not just loosely coupled. Genuinely independent, meaning neither side needs to know the other exists.

What that looks like in practice: logging and auditing that doesn't affect the outcome of the dispatching code. Extension points in bundles where you want downstream hooks without modifying core logic. First-responder chains where the chain stops once one listener resolves a value, and you want that contract in the event class rather than scattered across guard clauses.

What it doesn't look like: listeners that need to share state or coordinate with each other. Dispatching code that needs reliable return values or structured error handling from what runs next. Flows where execution order is load-bearing for correctness. And situations where the code is simple and stable enough that a direct service call would just be easier to follow. Not everything needs to be decoupled. Indirection has a cost even when it's justified.

The test I apply: if I removed the EventDispatcher and replaced this with a direct service call, would the code be meaningfully harder to extend or maintain? If the answer is no, the event is probably not earning its place.

Domain Events: Modeling Intent, Not Just Plumbing

This is the pattern I'd push hardest if someone asked where to invest time beyond the basics.

Without domain events, side effects accumulate in services:

class PlaceOrderService
{
    public function place(Order $order): void
    {
        $order->setStatus('placed');
        $this->entityManager->flush();
        $this->mailer->sendConfirmation($order);
        $this->inventory->reserve($order);
        // and so on
    }
}

Every new consequence of placing an order becomes another dependency on this service. The list grows. The coupling grows. The service becomes the place where everything ends up because it has to be somewhere.

Domain events break that apart:

class Order
{
    private array $domainEvents = [];

    public function place(): void
    {
        // ... business logic
        $this->domainEvents[] = new OrderPlaced($this);
    }

    public function pullDomainEvents(): array
    {
        $events = $this->domainEvents;
        $this->domainEvents = [];
        return $events;
    }
}

Then in the application layer, after the flush:

$entityManager->persist($order);
$entityManager->flush();

foreach ($order->pullDomainEvents() as $event) {
    $this->dispatcher->dispatch($event);
}

place() now expresses intent. It says: this happened. Not: here are all the things that should follow. Each consequence registers itself as a listener. The service stops being the place where everything accumulates.

The flush ordering is non-negotiable. Dispatch before flush and if the flush fails, you've fired side effects for a state change that never committed. I've seen this cause hard-to-reproduce bugs in production.

Even with correct ordering, you're exposed if dispatching throws mid-loop. Some events have fired, some haven't. Dispatching via Messenger helps: side effects become retryable messages rather than in-process calls, and a failure in one doesn't leave the rest in an unknown state.

For "exactly once" delivery guarantees, the outbox pattern is the real answer. Events are persisted transactionally alongside your domain data, then processed by a dedicated worker. It's genuinely more complex: a polling mechanism or change data capture tooling like Debezium, idempotency on the consumer side, at-least-once delivery semantics. Reach for it when you actually need those guarantees. Most applications don't.

As for when to use this pattern at all: if your entities have real business logic and placing an order means something beyond setting a status field, domain events will pay for themselves quickly. If you're working in a thin CRUD app where entities are essentially database row representations, the ceremony probably isn't worth it. The honest test is whether your domain objects have behavior worth expressing. If they do, domain events give you a clean way to express it.

What I've Landed On

The EventDispatcher is one of those tools where the basic usage is obvious and the advanced usage is invisible until you've needed it and didn't have it.

The question that matters is whether the behavior you're wiring is genuinely independent of the code dispatching the event. If it is, events are a natural fit and they'll keep your services small and your extension points clean. If it isn't, you're adding indirection to a problem that a direct service call would solve more clearly.

Used well, the EventDispatcher doesn't add complexity. It moves complexity to where it belongs.

Recently I caught myself doing something I wouldn't have let slide in a code review.

I'd asked an AI assistant to scaffold a Symfony service. It came back with something reasonable: correct structure, working logic, passing tests. I skimmed it, made one small change, and pushed it. Didn't think twice.

Some days later I was in that file chasing a bug and I genuinely couldn't follow what it was doing. Not because it was broken. Because it had no voice. No intent. It was code written by something that doesn't have to maintain it afterwards.

That's what got me paying closer attention to what I was actually shipping.

I've been writing PHP for the better part of 19 years. I've watched the language go from something developers apologised for to something they actively choose. I've seen frameworks come and go. And I've learned, slowly and the hard way, that making things work has never really been the hard part. Making things understandable is the hard part. Right now, I think that skill is quietly getting deprioritised.

Working and good are not the same thing

AI is genuinely impressive at producing working code. I don't want to be unfair about that because it would be dishonest. The tools are fast, they know a lot, and they save real time.

But there's a gap between code that works and code that's good, and AI sits firmly on the working side of it. It doesn't know your domain. It's never been burned by a badly-named variable at 11pm on a Friday. It hasn't had the argument with a colleague about where business logic should live, or watched a codebase become unworkable because nobody drew clear boundaries early enough.

So it reaches for $data and $result and processItems(). It writes methods that fetch, filter, transform and fire off side effects all in one go, because that's the most direct path between the prompt and the output. It doesn't stop to ask whether a class is taking on too much, because responsibility isn't something it carries.

None of this is a knock on the tools. It's just a description of what they are. The problem is when we forget the gap exists.

You own what you merge

The thing I keep coming back to is this: the moment AI-generated code lands in your repository, it's yours. Not the model's. Yours.

The architectural shortcuts it took? Yours. The test that only covers the happy path? Yours. The class that quietly violates the single responsibility principle because it was easier to generate that way? Also yours.

I think of it a bit like buying a second-hand car. You're still going to look under the hood before you take it on the highway. Not because you assume it's broken, but because you're the one driving it.

Teams that are moving fast with AI are, in some cases, quietly building up technical debt at the same speed they're shipping features. The code works, the sprints look great, and then six months in the codebase starts fighting back. Every change requires understanding ten things that should only require understanding one. That's when the bill arrives.

Working code that nobody understands is not an asset. It's a liability with passing tests.

The fundamentals don't go away. They just move.

What I've found is that the clean code principles I've been applying for years don't matter less in this new workflow. They matter more, because now they're the filter rather than the output.

Naming. AI leans toward generic names because it has no context for your specific domain. It doesn't know that in your system, a User isn't just any user. It might be an authenticated account holder with a billing state, an access tier, and a set of permissions that matter a lot. When I rename $filteredUsers to $activeSubscribers, that's not cosmetic. That's the difference between code that speaks your domain's language and code that could have come from anywhere.

Function size. Ask AI for a service method and you'll often get one that does everything in one shot, because that's what you asked for. It's trying to be helpful. But that's not how I want my Symfony services to look. Each of those concerns deserves its own home. Splitting it apart isn't refactoring for the sake of it. It's making the code navigable.

Architectural boundaries. AI has no idea what your architecture looks like. It will reach across layers without hesitation, inject infrastructure into your domain, and build a class that answers the prompt perfectly but fits nowhere cleanly. This is where knowing your own system becomes genuinely important. You can see what the AI can't.

If you're reviewing AI-generated code and you're not running quality tools in CI, you're leaving a lot to chance. Static analysis catches what tired human eyes skip when the code looks reasonable at a glance. In an AI-heavy workflow it's not optional.

The architect's eye

The framing that's helped me most is this: my job is the blueprint, not the bricks.

Before any AI-generated code lands in my codebase, the important decisions are already made. What are the layers? Where does business logic live? What does the domain language look like? What are the rules around dependencies? Those decisions are mine. They come from understanding the system, its history, and where it needs to go. The AI has no access to any of that. It works from the prompt, not from the architecture.

So when I review AI output, I'm not just checking whether it works. I'm checking whether it fits. Does this class belong in this layer? Does this name match the language we use in this domain? Does this dependency point in the right direction? Those are architectural questions, and they require architectural knowledge to answer. That's the thing the AI genuinely cannot bring to the table.

This also changes what "good review" means. It's less about catching bugs and more about enforcing coherence. Does this fit the system we're building? If not, it goes back, however cleanly it was generated.

The AI can build a room. Only you know what building it belongs in.

Think of it as a very fast junior

The mental model I've landed on: AI is an exceptionally fast junior developer who's very good at syntax and not yet great at judgment.

I wouldn't merge a junior's PR without reading it carefully. I wouldn't assume their naming matched our conventions or that they'd thought through the wider architectural implications. I'd review with genuine curiosity, not looking for reasons to reject but making sure what goes in actually belongs there.

That's the posture I try to bring to AI output now. Not suspicion, just attention. The tools have earned a seat at the table. They haven't earned the right to skip review.

And the better your architectural instincts are, the faster and more accurate that review gets. You can't enforce boundaries you haven't defined. You can't catch a misplaced dependency if you don't have a clear picture of where things are supposed to live. The fundamentals aren't the thing you learn before the real work starts. They are the real work.

To wrap up

I want to be clear: I'm not skeptical of AI tools. I use them every day and I'm not going back.

What I am is someone who's seen what happens when a team prioritises shipping speed over code quality. The codebases that become genuinely painful to work in don't usually get there through one big bad decision. They get there through a thousand small ones, each of which seemed fine at the time.

"It passes the tests" was never the bar. It's still not.

Code gets read far more than it gets written. It gets maintained by people who weren't there when it was made. The decisions baked into it compound over time.

AI changed who writes the first draft. It hasn't changed any of that. Write for the reader.