Software Architecture on Shane's Personal Blog

The Two-Agent Method: Building Features Without Drowning in Context

Fri, 28 Nov 2025 00:00:00 GMT

There’s a particular kind of frustration that comes from working with AI coding assistants on anything beyond trivial features. You start with a clear goal. The AI seems to understand. It explores your codebase, asks a few questions, maybe even proposes something sensible. Then, somewhere in the implementation, things drift. The code doesn’t quite integrate properly. Edge cases get missed. The assistant confidently suggests changes that would break existing functionality.

You find yourself debugging the assistant’s confusion rather than shipping features.

The problem isn’t that these tools are useless - they’re remarkably capable when used correctly. The problem is that most of us are using them wrong. We’re treating them like patient junior developers who can hold an entire conversation in their head, when they’re actually more like brilliant consultants with severe short-term memory constraints.

Once you understand this, a better approach becomes obvious.

The Real Problem: Context Accumulation

When you have a long conversation with an AI assistant, every detour leaves a mark. Every wrong file it explored, every assumption it made and corrected, every dead-end investigation - all of it stays in the conversation history. The model doesn’t forget these things the way a human might. Instead, it accumulates them.

Think of it like trying to focus on writing while someone reads aloud every draft you’ve ever written, including all your false starts and deleted paragraphs. The signal-to-noise ratio degrades steadily.

This is why implementations often deteriorate after seemingly productive planning sessions. The assistant reached a correct conclusion, but only after wandering through a forest of incorrect ones. When it tries to implement, it’s carrying all that baggage.

The solution isn’t to use these tools less. It’s to structure your workflow around their actual capabilities.

The Two-Agent Pattern

Here’s the approach that consistently produces better results: split the work between two separate agents with distinct, focused roles.

The first agent - call it the Explorer - does exactly what the name suggests. It navigates your codebase, asks clarifying questions, maps out integration points, and produces a clean implementation plan. This agent’s job is to understand deeply and document clearly.

The second agent - the Implementer - starts fresh. It receives the Explorer’s distilled insights without any of the exploration baggage. Clean instructions, relevant context, no detours. This agent writes the actual code.

The pattern resembles how effective engineering teams actually work. Senior engineers who understand the system architecture don’t necessarily write every line of code. They explore, they plan, they document their findings. Then someone else - or themselves with fresh focus - implements based on that clear blueprint.

Phase One: Exploration With Constraints

Start by framing the problem clearly. This matters more than you might think. The quality of the final implementation depends heavily on how well you define the task upfront.

Give the Explorer autonomy to navigate your codebase, but constrain its exploration to relevant areas. If you’re adding a feature to your authentication system, point it toward the auth modules explicitly. This prevents the assistant from wandering through your entire repository and burning context window on irrelevant code.

The instruction might look like: “Explore the authentication and user management modules. I need to add OAuth integration for Google and Microsoft. Read whatever files you think are relevant in these areas.”

Then add something critical: “If you’re not completely confident about the solution, ask questions. Don’t make assumptions.”

This single instruction changes the assistant’s behavior dramatically. Most models will happily fill gaps with assumptions if you don’t explicitly tell them otherwise. But when forced to acknowledge uncertainty, they ask surprisingly good questions.

Answer these questions thoroughly. The time you invest here determines how much backtracking you’ll do later. If the assistant asks whether soft-deleted users should still authenticate, don’t just say “no” - explain the entire deletion lifecycle and how it affects related systems.

The Explorer continues iterating - reading more code, asking follow-up questions, refining its understanding. Eventually, it reaches confidence: “I understand what needs to be built. Here’s the plan.”

The Critical Transition

This is where most people make their mistake. They see a good plan and immediately say “great, implement it” - keeping the same conversation going.

Don’t do this.

Instead, instruct the Explorer to write documentation for a completely different engineer. Not instructions - documentation. The difference matters.

Instructions sound like: “Add a deleted_at field to the User model. Modify UserService.get_active_users() to filter out deleted users.”

Documentation sounds like: “The User model in models/user.py represents both active and deleted users. There’s currently no soft-delete mechanism - the existing delete() method removes records entirely. For this feature, you’ll likely want to add a nullable deleted_at timestamp. The UserService in services/user_service.py has methods that return user collections - these may need updating to respect the deletion state. The admin interface renders user lists from admin/users.py, which pulls from UserService.”

See the difference? Documentation guides thinking. It highlights relevant files and suggests approaches without dictating implementation details. It preserves the Implementer’s ability to think independently.

Have the Explorer include:

Relevant file paths and what they contain
Integration points and why they matter
Potential approaches and their tradeoffs
Your specific requirements and constraints
Your coding style preferences

This becomes your handoff document.

Phase Two: Fresh Implementation

Start a new conversation. Copy in the Explorer’s handoff document. Add your original feature request for context.

Then watch something interesting happen.

If the Explorer did its job well, the Implementer will read through the suggested files, understand the architecture quickly, and say: “I’m ready to implement this.”

This moment is actually a quality signal. When an Implementer can immediately start working from a handoff document, it suggests the documentation was clear and complete. When it needs extensive clarification, something was missing in the exploration phase.

The Implementer now builds the feature with several advantages:

Clean context focused only on relevant information
No cognitive debris from exploration detours
Fresh perspective on integration challenges
Full autonomy to make implementation decisions

The resulting code tends to be cleaner, more consistent with existing patterns, and better integrated with the broader system.

Why This Actually Works

Large language models don’t “forget” in the human sense - they process every token in their context window with roughly equal weight. A confused exploration thirty messages ago carries nearly the same influence as the current task description.

By resetting context, you’re not just saving tokens. You’re removing misleading signals that would otherwise contaminate the implementation.

Think of it like the difference between:

A meeting where you discuss something for two hours, exploring every wrong answer before finding the right one, then trying to make decisions while mentally replaying the entire rambling conversation
A meeting where someone walks in with a clear one-page summary of the decision and the relevant context

The second meeting produces better outcomes because everyone’s working from filtered, relevant information.

A Concrete Example

Suppose you’re adding export functionality to a data platform. Your existing system has complex permission rules, multiple data formats, and several edge cases around sensitive information.

The Explorer would:

Examine your permission system to understand access control patterns
Review existing export code (if any) to maintain consistency
Identify where sensitive data filtering happens
Ask about specific requirements: file format preferences, size limits, async vs sync processing
Investigate how similar features handle errors and logging
Produce a plan that covers data pipeline, permission checks, format conversion, and error handling

The handoff document might note: “The existing report generation in services/reports.py follows an async pattern using Celery tasks. This might be worth considering for exports since large datasets could timeout on synchronous requests. Permission checks happen at the service layer, not the API layer - see how ReportService.get_report() handles this. The data sanitization utilities in utils/sanitize.py are used consistently across the codebase for removing sensitive fields.”

The Implementer reads this, examines the relevant files, and builds an export feature that naturally fits your architecture. It uses Celery because that’s your pattern. It checks permissions at the service layer because that’s where you do it. It uses your existing sanitization utilities because those exist.

The alternative - having a single agent do everything - often results in exports that don’t quite match your patterns. Maybe it checks permissions at the wrong layer. Maybe it uses synchronous processing when you’ve standardized on async. These aren’t catastrophic failures, but they create the kind of inconsistency that makes codebases harder to maintain.

When to Use This Pattern

Not every task needs this ceremony. Adding a simple utility function? Fixing an obvious bug? A single agent works fine.

This pattern pays dividends when:

The feature touches multiple parts of your system
Integration matters more than the individual pieces
You need the new code to feel native to the existing codebase
The problem requires real understanding of your architecture
You’ve found yourself repeatedly explaining context to the assistant

As a rough heuristic: if you’d want a senior engineer to review the design before implementation in a human team, use two agents.

Common Variations

Some people use this pattern with even more specialization:

An Architect agent that only reviews designs
A Reviewer agent that critiques implementations
A Documenter agent that writes end-user documentation

The underlying principle remains the same: keep each agent’s context clean and focused on its specific role.

The Hidden Benefit

Beyond the obvious quality improvements, this pattern has a subtler advantage: it forces you to think clearly about what you’re building.

Writing a good handoff document requires understanding the feature yourself. When the Explorer asks clarifying questions, you can’t hand-wave - you have to provide real answers. The transition point becomes a natural checkpoint for “do we actually know what we’re building?”

Many bugs get prevented not because the AI wrote better code, but because this process caught ambiguities before they became implementation.

Practical Notes

A few details that matter in practice:

Start the Explorer’s instructions with your problem framing and relevant directory suggestions. Don’t make it search your entire repository.

When the Explorer asks questions, take them seriously even if they seem obvious. Sometimes obvious questions expose subtle inconsistencies in requirements.

The handoff document doesn’t need to be long. Three or four paragraphs often suffice. The goal is clarity, not completeness.

If the Implementer asks extensive clarification questions about the handoff, that’s feedback - the Explorer missed something. Consider refining the exploration process.

Your coding style preferences (formatting, documentation standards, naming conventions) should be in the handoff. The Implementer won’t inherit them through osmosis.

Limitations

This approach doesn’t solve everything. The Implementer can still write bugs. Integration might surface unexpected issues. Code reviews remain necessary.

What it does solve is the context contamination problem - and that alone makes complex features dramatically more reliable to build with AI assistance.

The Broader Pattern

Once you see this pattern, you’ll notice it applies beyond coding. Any complex task with an AI assistant benefits from similar structure: a research phase that produces clean documentation, followed by an execution phase that works from that documentation.

The specific implementation varies by domain, but the principle holds: cognitive clarity beats raw capability. A moderately capable model working from clean context often outperforms a more powerful model drowning in conversational debris.

(Written by Human, improved using AI where applicable.)

Why AI Cannot Engineer

Thu, 20 Nov 2025 00:00:00 GMT

I asked Claude to build me a customer dashboard last month. Ten minutes later, I had gorgeous React components, a clean API structure, and authentication that worked flawlessly on my laptop. I felt like a wizard.

Two days later, when we put it in front of actual users, everything fell apart. The API crumbled under concurrent requests. The authentication tokens expired in the middle of user sessions. The database queries that felt snappy with my 10 test records took 30 seconds with real data.

The code looked beautiful. It even worked—sort of. But it was a disaster waiting to happen, and I had no one to blame but myself. I’d asked for a construction worker when I needed an architect.

The Skyscraper Nobody Can Live In

Think about building a skyscraper for a moment. You need two completely different types of expertise:

The Architects and Engineers design the building. They figure out where the load-bearing walls go, how to route all the electrical wiring and plumbing, what materials can handle the wind shear at that height, how the building responds to earthquakes. They think about fire escapes and elevator shafts and how people will actually move through the space. They create detailed specifications for everything.

The Construction Workers build it. They know how to mix concrete, how to weld steel beams, how to install windows. Give them a good blueprint with all the specifications—“use this gauge of rebar, space them 6 inches apart, let the concrete cure for 48 hours”—and they’ll build you something solid and safe.

Here’s the interesting part: construction workers understand building principles. They know that rebar makes concrete stronger, that you can’t just drill holes wherever you want in a load-bearing wall, that certain materials expand in heat. They might not be able to calculate the exact compression loads or explain the physics, but they know how to build.

So in theory, if you asked construction workers to build a skyscraper without giving them architectural plans, they could do it. They’d use their knowledge to put up walls and install wiring and plumbing. The building would stand.

For a while.

Then someone tries to actually live in it. Or an earthquake hits. Or there’s a fire. And you realize the electrical system is a tangled mess that can’t handle the load. The plumbing creates massive pressure problems on the upper floors. There are no proper fire exits. The structure can’t flex with the wind. It looks like a building, but it’s not safe, not livable, not reliable. It’s a expensive disaster wrapped in a pretty facade.

You really needed those architects and engineers.

We Accidentally Merged Two Jobs

Now let’s talk about software. In our industry, we have the same two roles—but we’ve gotten confused about which is which.

Software Engineers are supposed to design systems. They think about scalability, reliability, security, maintainability. They establish patterns and guardrails. They consider edge cases: What happens when 10,000 users hit this endpoint simultaneously? How do we handle partial failures? What’s our data consistency model? How do we make this debuggable when something goes wrong at 3am? They create the “blueprints” that make the difference between software that works on localhost and software that works in production.

Programmers write code. They understand syntax, algorithms, design patterns. They know how to implement features, how to make things work. Given good specifications and architectural guidelines, they write solid, maintainable code that does exactly what it needs to do.

But here’s where we got confused: engineers also write code. They have to—you can’t design a system well if you don’t understand implementation realities. An architect who doesn’t understand how concrete and steel actually behave can’t design a building that stands. Similarly, a software engineer needs to understand how code actually executes.

Because of this overlap, we started treating them as the same job. Most companies just have “software engineers” who do everything—system design and implementation. We stopped distinguishing between the person who decides “we need a caching layer with these invalidation rules” and the person who implements Redis with that specification.

For years, this worked okay. The engineer-programmer would design the system in their head, then implement it. Both roles were happening, just inside one person.

Enter the AI Programmer

Now we have large language models that can write code. And here’s what I’ve realized: LLMs are incredible programmers, but terrible engineers.

An LLM is like that construction worker who can build you a skyscraper without blueprints. Ask it to “build me a todo list app,” and it will. The code will be clean. It’ll have proper separation of concerns. The variable names will make sense. It’ll work beautifully on your laptop.

But it’s missing all the engineering:

No load considerations: It’ll use an in-memory array for the todo list, which works great for testing but fails when you have 10,000 users
No failure handling: What happens when the database connection drops mid-request? The LLM’s code probably doesn’t handle that gracefully
No security thinking: Authentication might be present, but is it actually secure against common attacks? Are there SQL injection vulnerabilities?
No performance engineering: That nested loop through every user’s todos on every request? Didn’t consider that case
No operational thinking: Good luck debugging when something goes wrong—there’s minimal logging and no monitoring

The code looks professional. It follows good practices. It even works, in the ideal case. But the moment reality hits—concurrent users, network failures, edge cases, malicious input—it falls apart.

Just like that skyscraper built without architects.

What This Actually Means

I used to think the distinction between “engineer” and “programmer” was just semantic nitpicking. Now I realize it’s crucial, and we’re about to learn this lesson the hard way.

When you tell an LLM “build me an authentication system,” you’re giving it a task without constraints. It’s like telling a construction worker “build me a building” without specifying:

How many people it needs to support
What kind of disasters it needs to withstand
What the fire safety requirements are
How the utilities should be routed
What the budget constraints are

The LLM will build you something. That something might even impress you. But it won’t be robust, because nobody did the engineering.

Here’s a real example from my startup, Empath Legal. We’re building jury selection tools for attorneys. I could ask an LLM: “Create an API endpoint that analyzes jury questionnaires and returns insights.”

The LLM would build me something functional:

It would parse the questionnaires
It would call an LLM to analyze the text
It would return formatted results
The code would be clean and well-structured

But here’s what it wouldn’t consider without engineering input:

Business requirements I need to specify:

These questionnaires can be 50+ pages and attorneys need results in under 30 seconds
Our customers are lawyers who need citations for everything—we can’t just hallucinate insights
The analysis must be deterministic enough that an attorney can rely on it in court
We have a credit-based pricing model, so we need to track and limit usage

Technical guardrails I need to establish:

We need to chunk large questionnaires intelligently (by section, not arbitrary token counts)
We must implement streaming so attorneys see progressive results, not a 30-second blank screen
We need a caching layer so re-analyzing the same questionnaire doesn’t burn credits
We need robust error handling because LLM API calls fail sometimes
We need audit trails for compliance reasons

System design decisions I need to make:

Should this be synchronous or async? (Async, because of the 30-second requirement)
What happens if the LLM call fails midway? (We need idempotent retries)
How do we handle rate limits from the LLM provider? (We need a queue with backpressure)
What’s our data consistency model? (We need to decide what happens if analysis partially completes)

The LLM could write beautiful code for the happy path. But without me doing the engineering work—understanding the requirements, establishing the constraints, designing the system architecture—that code would be worthless in production.

The New Division of Labor

This isn’t about LLMs being bad. They’re phenomenal at what they do. This is about understanding what they do.

LLMs are expert programmers: Give them a well-specified task with clear constraints, and they’ll implement it beautifully. They know patterns, they write clean code, they can even debug and optimize within a defined scope.

Humans need to be the engineers: We need to understand the business requirements, design the system architecture, establish the guardrails and principles, consider the edge cases and failure modes. We need to ask: What are we really trying to achieve? What could go wrong? How does this need to scale?

This is actually liberating, if you think about it. We can offload the tedious parts—writing boilerplate, implementing standard patterns, translating specifications into code—and focus on the interesting parts: understanding user needs, designing robust systems, making architectural tradeoffs.

But only if we actually do the engineering work. If we just prompt “build me X” without providing context, constraints, and architectural guidance, we get that beautiful skyscraper that nobody can live in.

How to Actually Work with AI Coding Tools

Here’s what I’ve learned about working effectively with LLMs:

Bad prompt:

“Build me a payment system for my SaaS app”

Good prompt:

“Build me a payment system with these requirements:

Support credit-based pricing (users buy credits, features consume credits)

Must handle concurrent credit deductions safely (two API calls shouldn’t both succeed if there’s only enough credits for one)

Need audit trail for billing disputes

Should fail gracefully if payment processor is down (degrade to cached credit counts, log for reconciliation)

Performance requirement: credit check must add < 50ms to request latency

Use PostgreSQL with row-level locking for credit deductions. Implement idempotent credit operations so retries don’t double-charge. Include comprehensive logging for debugging billing issues.”

The second prompt does the engineering work. It specifies:

The business model (credit-based pricing)
The critical constraint (safe concurrent access)
The compliance requirement (audit trail)
The reliability requirement (graceful degradation)
The performance requirement (latency budget)
The technical approach (PostgreSQL with row locks)
The operational requirement (debuggable)

Now the LLM can write code that actually works in production, because I’ve given it the architectural blueprint.

The Uncomfortable Truth

Most of us who’ve been writing code for years have been doing both roles simultaneously for so long that we don’t even notice when we’re switching hats. When we sit down to “code,” we’re actually doing engineering work (thinking about requirements and constraints) and then programming work (implementing the solution).

With LLMs, we can’t do that anymore. The programming part gets delegated to the AI. But if we don’t explicitly do the engineering part ourselves—if we just treat the LLM as a magic “build me X” box—we get code that works in the demo but fails in reality.

And here’s the uncomfortable part: many people who call themselves engineers are actually just programmers. They’re really good at writing code, but they’ve never had to think deeply about system design because they were implementing someone else’s architecture, or working on small enough systems that the complexity didn’t matter.

With LLMs, this distinction now matters. The code-writing skills that used to be valuable are being commoditized. What’s becoming valuable is the engineering thinking: understanding requirements, designing robust systems, making good architectural tradeoffs, considering failure modes.

What This Means For You

If you’re learning to code right now, don’t just learn syntax and frameworks. Learn to think like an engineer:

When you build something, ask: “What happens when 1000 people use this simultaneously?”
Before writing code, ask: “What are all the ways this could fail, and how should it handle each one?”
Study real-world system design, not just toy examples
Learn to write specifications that would let someone else implement your vision correctly
Understand the why behind patterns, not just the how

If you’re already working as a developer, pay attention to which role you’re actually performing. Are you mostly implementing features based on specs? You’re in the programmer role, and LLMs are coming for that job. Start developing engineering skills: system design, requirements analysis, architectural thinking.

If you’re hiring, stop asking “can you code fizzbuzz?” and start asking “design a URL shortener that handles 1000 requests/second and explain your failure modes.” The code-writing part is increasingly automated. The thinking part isn’t.

The Punchline

Here’s the irony: I wrote this post with Claude’s help. Not because I couldn’t write it myself, but because Claude is a better programmer than I am. I gave it my core idea, my architectural guidelines (the blog writing guide), my requirements (make it engaging and human), and my constraints (use the construction analogy, include real examples).

Claude wrote beautiful prose. But I did the engineering: I decided what to communicate, how to structure the argument, what examples would land, what the reader needs to understand.

The future of software development isn’t “no human involved.” It’s humans doing what humans are uniquely good at—understanding messy real-world requirements, making tradeoffs with incomplete information, designing robust systems for complex environments—while AI does what it’s uniquely good at: writing clean, correct code that implements those specifications.

But only if we remember to do the engineering work. Otherwise, we’re just building skyscrapers without architects.

And we all know how that story ends.

What’s your experience with AI coding tools? Are you finding yourself doing more engineering thinking, or just prompting and hoping? I’d love to hear your stories—the spectacular failures are often more educational than the successes.

(Written by Human, improved using AI where applicable.)

The 12-Factor App: Building Software Like LEGO in the Cloud Era

Tue, 19 Aug 2025 00:00:00 GMT

Intro

Picture this: It’s 3 AM, and your app just went viral. Traffic spikes from 100 users to 100,000 in minutes. Half your team is asleep, the other half is panicking. Will your application gracefully scale to handle the load, or will it crumble under pressure?

As a startup, this scenario haunted me as I build our application—until I read something that fundamentally changed how I think about building applications. It’s called the 12-factor app methodology (knowledge and wisdoms discovered like this always humbles me—we are, after all, standing on the shoulders of giants, and hoping to see further into the future)

Here’s how I think about this: A 12-factor app is like a LEGO brick for infrastructure. You build it with zero assumptions about the outside world, purely implementing internal logic while letting the platform decide everything els—what inputs to feed it, where outputs go, when to start, stop, duplicate, or destroy it. The app becomes not just a one-off creation but an infinitely scalable building block (like lego for the cloud).

The Three Pillars: Understanding the Architecture

Before diving into the twelve factors, let me share the mental model that finally made everything click. Every interaction in a 12-factor app falls into one of three categories:

The App Itself - The immutable, stateless core of your logic
The Interface - How your app communicates with the outside world
The Platform - The environment that orchestrates everything

Think of it like this: Your app is a chef in a kitchen. The chef (the app) has specific skills and recipes. The kitchen setup—where ingredients come from, where dishes go, what equipment is available—that’s the interface. The restaurant management deciding when the chef works, how many chefs to hire, which orders to prioritize—that’s the platform.

This separation is what makes the magic happen. Let’s explore how each factor reinforces this architecture.

Part 1: The Foundation - Managing Your Code and Dependencies

Factor I: Codebase - Your Single Source of Truth

Remember the last time you heard “it works on my machine” or spent hours figuring out which version of the code was actually running in production? The codebase principle eliminates these nightmares.

Imagine your codebase as a map where every piece of code has exact coordinates—the X-axis represents different versions, the Y-axis represents different deployments. Any snapshot of your code can be pinpointed precisely on this map. When something breaks at 3 AM, you know exactly which code is running where.

This has not be a problem personally—since I adopted github blindly (shame on me) during college, I always put my code there (I naively thought of it as a cloud for my code. I can just pull code from anywhere—fun!) but stupid me: its way more complex than that, which I learned as I use github with teammates. The only way you truly understand how a version control navigates landmines is to actually use it wrong (which i did lol) and get hit on the head with a brick. Then you learn.

Factors II & III: Dependencies and Config - The Input Controls

These two factors are cousins—they both control how the outside world shapes your app’s behavior, but in subtly different ways.

Dependencies are like the ingredients list for a recipe. You declare exactly what you need (Python packages, Node modules, system libraries) in a manifest file. No assumptions, no “it should probably have this installed.” Every dependency is explicit.

Configuration, on the other hand, is like the knobs on a mixing board. Same equipment, different settings for different venues. Your database credentials, API keys, feature flags—these change between environments, but your code doesn’t.

Here’s the crucial insight: Your app’s config is everything that varies between deploys. If you can’t open-source your code right now without leaking credentials, you haven’t separated config from code properly.

for python, what I like to do with settings is just use dotenv + dataclass. Reliable, barebone yet powerful.

Factor IV: Backing Services - Your App’s Supporting Cast

Backing services are where input and output blur together. Your database, message queue, email service—they’re both sources of input (what data do I read?) and destinations for output (where do I write?).

The breakthrough principle here: treat every backing service as an attached resource. Your app shouldn’t care whether PostgreSQL is running on the same machine, in a different datacenter, or managed by a third party. It’s just a URL and credentials in your config.

For example, this really shines when you need to migrate from a self-hosted PostgreSQL to Amazon RDS—if you treat the database as an attached resource, the migration is simply config change. (the problem is never about coding, the problem is always about the bug that comes with new codes. LOL)

Part 2: The Build Pipeline - From Code to Running Process

Factor V: Build, Release, Run - The Three-Stage Rocket

Lets talk about bread. 4AM in the morning, You bake it (Build), then you got a bunch of breads at 9am when you open (releases), then you sell the breads during the day (run). Sure if you are a small bakery you can live with baking fresh breads and sell them right after (mix build and run) but if you bake the bread wrong, your customer would need to wait an extra hour for a new batch. It would be so much better if you bake early and have a bunch of ready bread and satisified customers!

Now that you have a rough understanding what the three stages are, lets dive deeper:

Build Stage: Your code + dependencies become an executable (compile, bundle, package)
Release Stage: That executable + configuration becomes a numbered release
Run Stage: That release executes in the production environment

Each release is immutable—a frozen snapshot combining a specific build with specific configuration. When release v427 starts acting weird, you can instantly roll back to v426. You’re not scrambling to figure out what changed; you’re switching between known, tested states.

The beauty? Problems in the build stage happen when developers are awake and watching. Problems in the run stage can be solved by rolling back to a known-good release. No more debugging in production at 3 AM.

Factor VI: Processes - The Stateless Mandate

Your app processes should be like workers on an assembly line—they process what comes to them but don’t store anything locally. Need to save data? Use a database. Need to cache something? Use Redis. Need to store files? Use S3.

When your processes are stateless, they become disposable. You can start them, stop them, crash them, multiply them—and your users never notice. It’s liberating.

Factor VII: Port Binding - Self-Contained Services

Your app should be completely self-contained, exporting its services by binding to a port. No runtime injection of web servers, no complex application containers—just your app listening on a port.

This means your Python app includes its own web server (like Gunicorn), your Ruby app brings Thin or Puma, your Java app packages Jetty. The app becomes a standalone service that says, “I’m listening on port 5000. Send me requests.” (This is why RESTful is so elegant—it is a standard that unify the world!)

Why does this matter? Because it makes your app composable. Today’s web app becomes tomorrow’s backing service for another app. Just point to its URL and port. It’s LEGO bricks all the way down.

Part 3: Operations - Running in the Wild

Factor VIII: Concurrency - Scale Out, Not Up

Typically when building local apps, the instinct is to make your app handle more concurrent request—add threads, increase the connection pool, optimize the event loop. They make things faster. But for web applications that needs to scale, the 12-factor way says: don’t.

Instead, keep your app simple—handle requests one at a time if that’s natural. Let the platform handle concurrency by running multiple copies of your process. Need to handle 10x traffic? Run 10x processes. It’s crude, but it works brilliantly.

Think of it like a restaurant. The traditional approach is training your one chef to cook faster, juggle more pans, multitask frantically. The 12-factor approach? Hire more chefs. Each chef works at a sustainable pace, and you scale by adding chefs, not by working them harder.

Factor IX: Disposability - Fast Startup, Graceful Shutdown

Your processes should be like Phoenix—ready to die and be reborn at a moment’s notice. Fast startup—meaning lazy approach, and graceful shutdown (finish current work, then exit cleanly).

This disposability enables the magic of modern deployment. Rolling updates, automatic scaling, self-healing systems—they all depend on processes that can be created and destroyed without drama.

Factor X: Dev/Prod Parity - Closing the Gap

The traditional gaps:

Time gap: Code written Monday, deployed next month
Personnel gap: Developers write, ops team deploys
Tools gap: SQLite in dev, PostgreSQL in production

The 12-factor approach obliterates these gaps:

Deploy hours or minutes after writing code
Developers are involved in deployment
Use the same backing services everywhere

We all know why mutex in multi-threading is important: it prevents race conditions where unpredictable things could happen when state is volatile. The same logic applies here: you want the gap to be as small and controlled as possible when you are between volatile / sensitive states so that you always have a preditive result, rather than chaos.

Part 4: Observability - Logs and Admin Tasks

Factor XI: Logs - The Event Stream

Your app should write logs like a diary writer who doesn’t care who reads it—just stream consciousness to stdout. Don’t manage log files, don’t rotate logs, don’t even think about where they go. Just write to stdout and let the platform handle the rest.

This seemed weird until I saw its power. In development, logs appear in your terminal. In production, the platform can route them anywhere—to files, to Elasticsearch, to DataDog, to multiple destinations simultaneously. Your app doesn’t know or care.

It’s the same philosophy: the app does one thing (emit events), the platform handles the complexity (routing, storage, analysis).

Factor XII: Admin Processes - One-Off Tasks in Familiar Territory

Database migrations, console sessions, data fix scripts—these admin processes should run in the same environment as your regular app processes. Same code, same config, same dependencies.

Why? Because nothing is worse than a migration script that works perfectly in staging but fails in production because of some subtle environmental difference. When admin processes run in identical environments, you eliminate an entire category of “works on my machine” problems.

The Revelation: It’s All About Contracts

The 12-factor methodology is never about the twelve specific factors. It’s about defining a clean contract between your application and the platform it runs on.

Your app promises:

To be stateless and disposable
To declare its needs explicitly
To communicate through standard interfaces
To log to stdout

The platform promises:

To provide configuration
To manage processes
To route requests
To handle logs

With this contract in place, something magical happens. Your app becomes truly portable. It can run on Heroku today, Kubernetes tomorrow, and whatever comes next. It can scale from one user to millions without code changes. It becomes a true building block—a LEGO brick that clicks perfectly into any modern infrastructure.