Microservice architecture

Microservices Platforms - part 8: Getting started with platforms

Wed, 03 Jun 2026 08:03:00 +0000

This is the eighth article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

While creating the conference presentation, I came across a rather depressing article Why Up to 70% of Platform Engineering Teams Fail to Deliver Impact.

It describes how most platform teams fail:

Based on my experiences over the years, I am not surprised. In this article, I shall share a few thoughts about why platform engineering often fails and what can be done to increase the chances of success.

Need help with modernizing your architecture?

I help organizations modernize safely and avoid creating a modern legacy system — a new architecture with the same old problems. If you’re planning or struggling with a modernization effort, I can help.

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 4: The coding agent sandwich pattern

Tue, 19 May 2026 08:03:00 +0000

This article describes the “coding agent sandwich” — an architecture pattern consisting of a tasty filling of LLM invocations sandwiched between two slices of plain old code (POC).

This article is part of a series about the GenAI-based development platform (a.k.a. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive, more secure and less frustrating. The complete list of articles in the series is as follows:

The worked example is the implement plan sub-workflow, which is the last step of idea-to-code, my open-source GenAI-based development workflow. The implement plan workflow uses test-driven development (TDD) to turn the generated plan into code.

Before looking at the different parts of the sandwich, let’s start with an overview of the implement plan workflow.

An overview of the `implement plan` workflow

The input to this workflow is the plan. The plan consists of a set of tasks. The implement plan workflow turns each task into a Git commit on either trunk or a pull request branch. The following diagram shows the implement plan workflow:

The workflow begins with i2code cleaning up from a previously failed implementation by committing any uncommitted changes and pushing them to the remote repository.

Once it has cleaned up, i2code iteratively implements each task in the plan. The plan implementation loop consists of the following steps:

If there’s a running CI build, wait for it to complete.
If the CI build failed, fix it.
Respond to any comments on the pull request.
Get the next task from the plan.
If there are no more tasks, break the loop.
Implement the task.
Mark the task as complete in the plan.
Commit the changes to Git.
Push the commit to the remote repository.

Why not implement the `implement plan` workflow using a coding agent?

In theory, i2code could simply implement the implement plan workflow by invoking a coding agent (e.g. Claude Code) with a suitable prompt that tells it to implement the entire plan:

claude -p "Implement the following plan: ${plan_file} using the following workflow:

commitChanges()
pushCommits()
while True
    1. If there's a running CI build, wait for it to complete.
    2. If the CI build failed, fix it.
    3. Respond to any comments on the pull request.
    4. Get the next task from the plan.
    5. If there are no more tasks, break the loop.
    6. Implement the task.
    7. Mark the task as complete in the plan.
    8. Commit the changes to Git.
    9. Push the commit to the remote repository.
"

However, in practice, this approach is often unreliable and it’s certainly inefficient. The non-deterministic nature of LLMs means that it’s unlikely that the agent will successfully implement the entire plan in one go. For example, I’ve found that it will simply stop partway through. Also, LLMs are computationally expensive, so it’s wasteful to use an LLM when there is a far more efficient way to implement a function: plain old code (POC) - the top slice of the sandwich.

The top slice: orchestrating the `implement plan` workflow using plain old code

i2code implements the implement plan workflow using plain old code. The actual Python code is not that different from the pseudo-code in the workflow diagram above:

def execute(self):

    self._loop_steps.commit_recovery.commit_if_needed()
    if self._git_repo.has_unpushed_commits():
        self._push_and_ensure_pr()
    while True:
        if self._loop_steps.build_fixer.check_and_fix_ci():
        ...

This code is deterministic, efficient and easy to develop and debug. There’s no need to experiment with different prompts and hope that the agent will do the right thing only to find that it doesn’t. Don’t waste your time trying to solve a problem with an LLM when there are far simpler solutions.

Let’s now look at the sandwich’s filling: the coding agent.

The filling: invoking the coding agent for narrowly defined actions

Of course, there are some steps in the workflow that are not easily implemented using POC. For those, the POC-based orchestrator invokes the coding agent for narrowly defined tasks that cannot be implemented deterministically. Specifically, the i2code implement workflow invokes the coding agent for the following tasks:

Committing changes - completing the pre-commit checklist, generating a commit message and committing the changes
Fixing a broken CI build - analyzing the CI failure, identifying the cause and creating a commit that fixes it
Responding to pull request comments - analyzing comments, grouping related comments, and generating commits
Implementing a task - analyzing the task, identifying the necessary code changes, making the changes that implement the task, marking the task as complete and creating a commit for the changes

This approach allows us to leverage the strengths of both POC and the coding agent. However, there’s still one more layer of the sandwich: the deterministic tools that the coding agent can use to implement the tasks.

The bottom slice: deterministic tools used by the coding agent

To complete these tasks, the coding agent must be grounded in reality and perform various deterministic actions, such as running tests, verifying code quality, committing and pushing changes, and monitoring CI builds.

For example, during the implement plan workflow, the coding agent invokes various tools including:

uv or gradlew commands for running tests
git commands
gh commands for diagnosing a failed build
i2code plan commands for marking a task in a plan file as complete, etc.
CodeScene MCP server for analyzing code quality and identifying problems
gitleaks for checking for secrets in the code before committing

Claude Code has either built-in knowledge of these tools or is instructed to use them via skills or CLAUDE.md instructions.

We’ve now seen all three slices. Let’s step back and look at what kind of pattern this is.

Functional decomposition, layered and fractal

This approach of using a mixture of POC and LLMs is an example of functional decomposition - a general software design principle where a system is divided into components based on responsibility, and each function is implemented using the most appropriate technology.

In this case:

deterministic, well-defined logic is implemented using POC
ambiguous, language-oriented, or probabilistic tasks are implemented using LLMs

Rather than treating the LLM as the entire application, the system decomposes responsibilities and uses the LLM only where its capabilities provide value.

Functional decomposition can be applied recursively. The tools that form the bottom slice are all deterministic, but in principle a tool could itself incorporate LLM-based technology - in which case the tool is its own sandwich of POC orchestrating LLM calls. The architecture is fractal as well as layered.

Use POC whenever you can, LLMs only when you must

The practical rule: reach for POC first, fall back to an LLM only where determinism breaks down, and give the LLM deterministic tools so that it’s grounded in reality.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservices Platforms - part 7: Deployment platform

Thu, 23 Apr 2026 08:03:00 +0000

This is the seventh article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article describes the Deployment platform, which provides production and production-like environments that run the application’s services. Together with the Build platform, it defines the path that changes take from laptop to production.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 3: Announcing Isolarium, three flavors of secure sandboxes for GenAI-based coding agents

Thu, 26 Mar 2026 08:03:00 +0000

I’m pleased to announce that I’ve open-sourced Isolarium, a companion project to Idea to Code workflow that provides secure sandboxes for running GenAI-based coding agents like Claude Code.

In this article, I first describe the risks of running coding agents on a developer workstation and why secure sandboxes are necessary. I then briefly describe Isolarium and the three flavors of sandboxes that it offers. Let’s start by looking at the motivation for Isolarium.

Why coding agents need secure sandboxes

There are three reasons why coding agents need secure sandboxes:

Coding agents are vulnerable to attacks that can compromise the developer’s machine
Container-based testing libraries such as Testcontainers introduce additional risks
Even well-intentioned coding agents can cause damage

Let’s look at each one.

Coding agent security risks

Coding agent security risks have been on my mind ever since I watched the excellent and deeply disturbing presentation Agentic ProbLLMs: Exploiting AI Computer-Use and Coding Agents by AI researcher Johann Rehberger. His The Month of AI Bugs series - one post per day for the month of August 2025 - shows the risks that we face when we run coding agents.

Coding agent security risks include:

Exfiltration of developer credentials (SSH keys, GitHub tokens, cloud credentials)
Leakage of sensitive local files from the developer workstation
Unauthorized access to other repositories or organization resources
Execution of malicious commands on the developer’s machine
Malicious or unsafe dependency installation affecting the host environment
Persistence of compromise on the developer machine after an agent session ends

Container-based testing libraries introduce additional risks

Testing technologies such as the incredibly useful Testcontainers library that allow tests to run arbitrary Docker containers introduce additional risks since they can be used to run malicious containers that attack the host machine.

Even well-intentioned coding agents can cause damage

There’s also the risk of a well-intentioned coding agent causing damage by making unintended changes to the developer’s machine or code repository. Coding agents, for example, attempt to run arbitrary Bash commands, or write code that runs Bash commands.

Secure sandboxes for GenAI-based coding agents

Isolarium is a command line tool intended to address these problems. It runs coding agents in a secure, isolated and disposable environment. For example, to run Claude Code:

$ cd my-project
$ isolarium run --create -- claude -p ...

This command creates an isolated environment for the coding agent to run in, and then runs claude inside that environment.

Three flavors of isolation

Isolarium offers three flavors of isolation that make different trade-offs between security and overhead:

Nono - the most lightweight yet least secure option since the agent has access to some of the host’s filesystem.
Container - more overhead due to image and container creation yet more secure since only the working tree is shared with the host.
Virtual machine - slow to provision but provides the strongest isolation since the agent has no access to the host’s filesystem. What’s more the coding agent has more freedom: e.g., run tests that use Testcontainers.

Isolarium works with `i2code implement`

The i2code implement command described in the previous article implements the final step of the Idea to Code workflow, which turns a plan derived from an idea into a pull request consisting of production code and tests. It can now use Isolarium to run the coding agent in a secure, isolated environment:

$ isolarium implement --isolation-type <type>...

This command runs the i2code implement command inside an Isolarium environment with the specified isolation type.

Next steps

To learn more about Isolarium and to get started, check out the GitHub repository. I welcome your questions, feedback, and contributions.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservices Platforms - part 6: Build platform

Fri, 20 Mar 2026 08:03:00 +0000

This is the sixth article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article describes the Build platform, which provides the infrastructure and templates for the deployment pipelines that build and test the application’s services. Together with the Deployment platform, it defines the path that changes take from laptop to production.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 2: How Idea to Code turns an idea into working, tested software

Tue, 17 Mar 2026 08:03:00 +0000

This article is the third in a series about the GenAI-based development platform (aka. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive and less frustrating. The platform is a set of tools, constraints and feedback loops that guide their behavior, catch mistakes and prevent them from generating large amounts of poor-quality code that is often incomplete and untested.

The complete list of articles in the series is as follows:

This article is about the last step in the Idea to Code workflow that turns a plan derived from the initial idea into a pull request consisting of production code and tests. The actual development is performed by the i2code implement subcommand.

$ i2code implement docs/ideas/amazing-idea
...
PR marked ready for review
PR: https://github.com/humansintheloop-dev/humansintheloop-dev-workflow-and-tools/pull/31

docs/ideas/amazing-idea is a directory that contains the idea along with a specification and implementation plan that were derived from the idea.

Let’s explore the implementation of this coding agent orchestrator.

How `i2code implement` orchestrates Claude Code to implement a plan

The i2code implement command combines deterministic Python code and Claude Code invocations.

The following diagram shows how i2code implement works:

The input to i2code implement is a plan derived from the idea and consists of a series of small tasks. The output is a GitHub pull request consisting of roughly one commit per task. The i2code implement command uses TDD, so each commit contains both production code and tests.

Let’s look at how this works in more detail.

Setup phase

The first phase is a one-time setup that, among other things, creates a Git working tree for the branch that will be used to implement the plan. Subsequent runs of i2code implement for the same plan will reuse the same working tree, so the setup phase is only needed once per branch. This step is entirely deterministic, implemented in Python.

Recovery phase

The second phase is the recovery phase, which attempts to recover incomplete work from previous runs of i2code implement for the same plan. If there are uncommitted changes that complete a task, i2code implement invokes Claude Code to generate a commit message and commit the changes. Next, if there are commits in the local repository that haven’t been pushed to the remote, i2code implement pushes them. It then enters the main implementation loop.

Main implementation loop

The implement loop iteratively executes the tasks in the plan until all tasks are completed.

The loop consists of the following steps:

Fix any failed GitHub actions workflow for the current HEAD, waiting for the build to complete if necessary. If the build is broken, i2code implement invokes Claude Code to diagnose the failure, and commit a fix. It then pushes the fix and waits for the build to complete again.
Respond to comments and reviews of the pull request. If there are any comments or reviews requesting changes, i2code implement first invokes Claude Code to triage the feedback and determine what changes, if any, are needed to address it. The i2code implement command invokes Claude Code one or more times to generate commits that address the feedback and pushes the changes. It also responds to the comments and review with an explanation of the changes.
Implement the next task in the plan. The i2code implement then takes the next task in the plan, and invokes Claude Code to implement it using TDD, creating a commit.
Push the commit and, if necessary, create a pull request.
Wait for the build to complete and repeat.
Mark the pull request as ready for review. Once all the tasks in the plan have been implemented, i2code implement marks the pull request as ready for review.
Wait for the comments or reviews. The i2code implement command can wait for comments or reviews on the pull request, and respond to them as described in step 2.

Trunk mode

The i2code implement command also supports a trunk-based development mode, where instead of creating a pull request, it commits directly to the current branch.

To learn more

Take a look at the design document for i2code implement in the Humans in the Loop Dev repository.

What’s next

In the next post, I’ll describe how i2code implement can execute Claude Code within a sandbox environment, which minimizes the security risks of using coding agents.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 1: guardrails

Mon, 09 Mar 2026 08:03:00 +0000

This article is the second in a series about the GenAI-based development platform (aka. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive and less frustrating. The platform is a set of tools, constraints and feedback loops that guide their behavior, catch mistakes and prevent them from generating large amounts of poor-quality code that is often incomplete and untested.

The complete list of articles in the series is as follows:

Because coding agents cannot be relied on to consistently follow instructions, they must operate within deterministic guardrails that catch mistakes and enforce quality. Guardrails are therefore a central part of the platform. This article describes some of these guardrails.

Specifically, there are four guardrails that I want to cover:

Pre-commit checklist skill
Pre-commit Git hook
GitHub Actions workflow jobs
Automated pull request reviews

The first guardrail relies on the coding agent following instructions, while the others are deterministic mechanisms that enforce quality regardless of the agent’s behavior. Together, they provide defense in depth: if one guardrail is bypassed or ignored, the others still catch problems.

Let’s dive into each guardrail in turn, starting with the pre-commit checklist.

Pre-commit checklist skill

The first guardrail is the pre-commit checklist provided by the commit-guidelines skill that is part of the idea-to-code plugin in the Humans in the Loop workflow and tools repository.

This pre-commit checklist instructs the coding agent to run several quality and safety checks before creating a Git commit, including:

Dead code detection (using vulture for Python)
Linting with auto-fix (using ruff) to enforce coding standards
Static type checking for Python (using pyright)
Shell script linting for new or modified .sh files (using shellcheck)
Code health analysis using CodeScene, requiring a score of 10 for all modified files
Test coverage verification to ensure tests cover new or changed production code

If any quality gates fail, the agent must stop and fix the issues before committing.

CodeScene provides incredibly valuable feedback that has significantly improved the quality of the code generated by Claude Code. For example, requiring a CodeScene score of 10 for all modified files - in other words, the boy scout rule - has significantly improved the maintainability of the Idea To Code code base. One challenge, however, is that Claude Code often tries to justify not addressing code smells identified by CodeScene, such as claiming they are “pre-existing” or otherwise “acceptable”. This is one of the motivations for implementing the next guardrail.

Pre-commit Git hook

The second guardrail is a pre-commit Git hook that automatically runs quality and security checks before allowing commits to be made. It’s implemented using the pre-commit framework, which is configured by a .pre-commit-config.yaml file. See, for example, the .pre-commit-config.yaml files for the Idea to Code, and Eventuate RealGuardIO repositories.

In addition to running the tests, the pre-commit hook largely repeats the pre-commit checklist. The pre-commit hook does not run the dead code detection tool since its output needs to be interpreted and acted upon by the coding agent, which is not something a pre-commit hook can do. The hook also runs gitleaks to prevent secrets from being committed.

The pre-commit hook is essential because, unlike a Claude Code skill, it is deterministic. Its checks don’t rely on the GenAI-based coding agent following the checklist, which is often not the case. Fortunately, Claude Code hasn’t tried to bypass this pre-commit hook like I described previously. And even if it did, there are two more guardrails.

GitHub Actions workflow

The third guardrail is the set of checks performed by the GitHub Actions workflow that runs on every push or merge. A GitHub Actions workflow runs the tests. It also has one or more lint jobs.

For example, the Eventuate RealGuardIO repository’s workflow has a lint job that performs various quality and security checks on the codebase, including shell script linting and secret scanning using gitleaks. So does the Idea To Code repository’s GitHub Action’s workflow.

These checks will be performed even if the GenAI-based coding agent bypasses the pre-commit hook. In a later post, I will describe how to block a GenAI-based coding agent from modifying the GitHub Actions workflow files, which provides an additional layer of protection.

Automated GitHub status checks: CodeScene pull request review

The fourth and final guardrail is a set of automated checks that are performed when a pull request is created or a new commit is added. The failure of one of these GitHub status checks can prevent the pull request from being merged until the issues are addressed.

For example, I’ve configured CodeScene to automatically review all pull requests for the Eventuate RealGuardIO and Idea to Code repositories and provide feedback on code health. The GitHub status check will fail if the CodeScene score is below 10. It can also trigger a coding agent to respond to the CodeScene review and push a new commit that addresses the issues. However, these days CodeScene issues are almost always detected earlier by the Git pre-commit hook, and so the pull request reviews rarely fail.

What’s next

In future articles, I’ll describe other elements of the GenAI-based development (aka. Harness) platform that I’m developing.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Why GenAI-based coding agents are a complex domain in Cynefin - and what that means for adoption

Sun, 01 Mar 2026 08:03:00 +0000

These days, tremendous energy is being poured into software delivery using GenAI-based coding agents. A key part of using coding agents successfully is context engineering - carefully crafting prompts, skills, AGENT.md files, guardrails, etc. - to guide agent behavior. This typically requires significant experimentation and iteration. A prompt that works for one model version may fail with another.

This difficulty is not accidental. Using GenAI-based coding agents to reliably create high-quality software is fundamentally different from using traditional developer tools. The relationship between prompt and outcome cannot be fully predicted in advance. Effective practices evolve as teams experiment and learn.

As a result, organizations cannot treat coding agents like conventional technologies that can be standardized through a single “one true way.” Instead, they must adopt a mindset that prioritizes safe experimentation, rapid feedback, and continuous adaptation.

This article introduces the Cynefin framework - a model for understanding different types of problem domains - and explains why using GenAI-based coding agents belongs in the complex category and what that means for platform strategy and adoption.

About Cynefin

Cynefin is a framework that helps us understand the nature of the problem we’re facing and how we should respond to it. It characterizes problems as either clear, complicated, complex, or chaotic, and for each category, it prescribes a different approach to problem-solving. Cynefin distinguishes between situations where cause and effect are obvious, where they require expert analysis, where they can only be understood in retrospect, and where no perceivable order exists.

The framework is typically visualized as follows:

The Cynefin framework — image from Wikipedia

Let’s look at the clear, complicated, and complex domains in more detail and then see how they relate to software development in general and GenAI-based coding agents in particular.

About Clear domains

In clear domains, the relationship between cause and effect is obvious. You simply need to recognize the situation and apply the established rule or best practice.

In a clear domain, effective problem-solving requires:

Sense - observe and establish facts
Categorize - match it to a known pattern
Respond - apply the established best practice

A simple CRUD-style User Profile Management subdomain can be considered a clear domain.

About complicated domains

In complicated domains, the relationship between cause and effect is knowable but not obvious. Determining the correct response requires analysis and expertise.

In a complicated domain, effective problem-solving requires:

Sense - gather data
Analyze - use expertise to determine cause
Respond - apply a good practice

Income tax calculation is an example of a complicated domain: the rules are deterministic, but applying them correctly requires careful analysis and expert knowledge, due to the large number of interdependent rules, exceptions, and conditional thresholds.

About Cynefin complex domains

In a complex domain, the relationship between cause and effect can only be understood in retrospect and may not be repeated reliably. Progress requires safe-to-fail experiments rather than upfront analysis. There may not be a single optimal solution - only solutions that work better or worse in a given context.

In a complex domain, effective problem solving requires:

Probe - run safe experiments
Sense - observe what happens
Respond - amplify what works, dampen what doesn’t

Urban delivery routing and scheduling is an example of a complex domain. Traffic patterns, demand fluctuations, and human behavior create emergent outcomes that cannot be fully predicted in advance, which means effective solutions require experimentation and adaptation.

Why software development is complex

Software development - the activity of building and evolving non-trivial software systems - is complex in Cynefin terms. Some individual development tasks are clear or complicated - for example, applying a framework API, configuring infrastructure, or implementing a well-understood algorithm. But architectural and design decisions must be made under uncertainty before their full consequences can be known. Defining service boundaries, choosing abstractions, and modeling the domain are therefore complex activities in their own right, since the “right” decision cannot be determined through analysis alone. Quite often the consequences of these decisions only become visible through testing, deployment, and real-world use rather than through upfront analysis. As a result, effective software development requires iterative experimentation, rapid feedback, and continuous adaptation. Except when building trivial applications, it also requires expert architectural judgment - in other words, experienced developers.

Developer tools are clear or complicated

Although software development as a whole is complex, typical developer technologies - programming languages, frameworks, build tools, databases - are usually clear or complicated domains. The relationship between cause and effect is stable and knowable. You learn the rules, the APIs, and the configuration options, and then apply them.

When problems arise, they can usually be resolved through analysis, debugging, or consulting documentation. Even when experimentation is required, the underlying behavior is governed by defined rules and produces consistent results. And, while systems built with these tools can exhibit complex behavior, the tools themselves operate according to stable and analyzable rules. What’s more, when the tools themselves are changing rapidly, they might feel even chaotic, but that’s an emotional response to change rather than an inherent property of the domain. In other words, most developer tools require expertise and analysis rather than safe-to-fail experimentation.

Using an LLM-based coding agent is a complex domain

What makes LLMs so powerful is that they can tackle tasks within complex domains - including software development. Yet this power comes with important differences. LLM-based coding agents are fundamentally different from traditional developer tools. Using such agents to reliably create high-quality software is a complex domain because the relationship between prompt and outcome cannot be fully predicted in advance. A prompt that works in one context may fail in another. Small changes in wording, context, or model version can produce disproportionately different results.

Cause and effect can only be understood in retrospect

The system does not expose a stable, fully understandable set of rules that can be exhaustively learned and applied. Because outcomes depend on the interaction between prompt wording, model configuration, tool calls, retrieved context, and the surrounding codebase, behavior arises from the system as a whole rather than from a single predictable rule set. Instead, progress requires iterative prompting, experimentation, and rapid feedback. Effective use of a coding agent therefore resembles safe-to-fail experimentation more than traditional tool usage driven by analysis and expertise.

Probabilistic nature of LLMs

This unpredictability stems from the nature of LLMs themselves. LLMs are probabilistic models that generate tokens by sampling from a probability distribution conditioned on the context. Depending on the sampling strategy and model configuration, the same prompt can yield different outputs. This probabilistic behavior helps explain why using an LLM-based coding agent is a complex domain, where cause and effect cannot be reduced to fixed, analyzable rules.

Organizations must manage the complexity of the software system and the complexity of using coding agents at the same time. Adoption therefore requires a thoughtful and deliberate approach.

Organizations must adopt a complex-domain mindset for coding agents

When an organization adopts GenAI-based coding agents, it cannot treat them like traditional developer tools. First, it must shift engineering practices toward fast feedback and disciplined experimentation. Second, the organization must define a GenAI-based development platform - the platform that supports the use of coding agents - as a learning amplifier, not as a vehicle for enforcing a rigid “one true way.” Let’s first look at the implications for engineering practices and then explore how this complexity shapes platform strategy and governance.

Engineering practices must shift

First, if coding agents are treated instead as a merely complicated domain - essentially as more advanced automation - organizations are likely to overtrust their outputs and underinvest in feedback loops, guardrails, and human-in-the-loop checkpoints. In such a complex environment, automated testing and real-time observability must explicitly replace manual policy as the primary mechanism for governance. This, in turn, requires a fast-flow development model designed for experimentation and rapid feedback - without it, large-scale adoption of coding agents will stall.

Managing the unpredictability of outcomes

Second, the inherent unpredictability of GenAI-based coding agents requires a profound leadership mindset shift: moving away from the illusion of top-down control and toward a culture of continuous discovery. Because adoption is non-linear and success emerges through iteration rather than upfront analysis, leaders cannot rely on traditional rollout schedules or standardized mandates. Instead of attempting to eliminate variance, leaders must embrace an agile mindset that prioritizes enablement and evolutionary progress.

The platform must not act as a policy factory

Third, this complexity also shapes platform strategy and governance. In clear or complicated domains, a platform group that’s responsible for an internal development platform can act as a policy factory. It defines standards, publishes the one true way, and measures success through consistency and compliance. That approach works when cause and effect are stable and the best practices are knowable.

Because developing software with GenAI-based coding agents is a complex domain, practices do not converge on a single, fixed best practice. Prompting strategies, context engineering patterns, guardrails, and workflows evolve as teams experiment and learn. What works today may need refinement tomorrow as models, tooling, and organizational context change. The “one true way” is neither fully knowable nor stable. Although certain patterns may stabilize over time, model evolution, changing tooling, and shifting organizational context ensure that practices remain sensitive to change.

The GenAI-based development platform must amplify learning

Because reliably using coding agents operates in the Cynefin complex domain, a policy factory approach freezes learning too early. Instead, the GenAI-based development platform - the platform that supports the use of coding agents - must function as a learning amplifier. It should enable safe-to-fail experimentation, share emerging patterns, and provide guardrails. The goal of the platform and its team shifts from prescribing correctness to accelerating collective learning.

Acknowledgements

Thanks to Indu Alagarsamy for reviewing this article and providing valuable feedback.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservices Platforms - part 5: Observability platform

Tue, 24 Feb 2026 08:03:00 +0000

This is the fifth article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article describes the Observability platform, which simplifies the development of observable microservices - services whose behavior and usage can be understood by their teams. It explains how a platform group provides shared observability capabilities that enable service teams to focus on their core domain responsibilities.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Authentication and authorization in a microservice architecture: Part 6 - implementing complex authorization using Oso Cloud local authorization

Fri, 13 Feb 2026 08:03:00 +0000

This article is the sixth in a series of articles about authentication and authorization in a microservice architecture. The complete series is:

In the previous article, I described how a microservices-based application can use an authorization service, such as Oso Cloud, to make authorization decisions. Once the application’s authorization policy is defined declaratively in Oso, the application populates Oso with facts which correspond to relationships between entities. Then, when handling a request, such as disarmSecuritySystem(), the Security System Service invokes Oso passing the user’s identity, the operation to authorize (“disarm”), and the security system ID. Oso decides whether the operation is authorized by evaluating the authorization policy using its stored facts and the authorization request’s parameters.

This approach works well for operations that act on a single entity. Potentially complicated authorization logic is replaced by much simpler calls to Oso Cloud. But invoking Oso repeatedly for bulk operations that act on large collections of entities is likely to be inefficient due to the communication overhead. This article starts by exploring a more efficient way to authorize bulk query operations using a combination of local facts and facts stored in Oso Cloud. After that, it revisits how to authorize single-entity operations using locally stored facts. Let’s begin by looking at a simple example of a bulk query operation.

Problem: Implementing `findSecuritySystems()`

The findSecuritySystems() system operation returns a list of the security systems that the user is authorized to access. This data is used to populate the View Security Systems page of the RealGuardIO application’s UI. Let’s first look at why such a bulk query is challenging to implement.

Inefficient approach: One-by-one authorization using Oso

One way to implement authorization for findSecuritySystems() to do the following:

Query the database for all security systems - the Security System Service doesn’t maintain any other authorization-related data
For each security system, query Oso to check whether the user is authorized to view that security system

This approach is straightforward to implement. The problem is that unless there are just a few SecuritySystems, it’s likely to be inefficient.

A better approach, which was described in part 1, is to integrate the authorization check into the data access logic, i.e. the SQL query. In part 4 I described this approach with an example that efficiently retrieved SecuritySystems by executing SQL SELECT that joined the security_systems table with data replicated from the Customer Service. Let’s look at how to do that when using Oso Cloud.

Integrating Oso into the database access logic using local authorization

Oso Cloud has a feature called local authorization, which makes authorization decisions using a combination of facts stored in Oso Cloud and the service’s database. Two key local authorization methods are oso.listLocal() and oso.authorizeLocal(). The oso.authorizeLocal() method is the local authorization equivalent of oso.authorize(). It returns a SQL SELECT statement that, when executed by the service, returns either true (authorized) or false (not authorized). The oso.listLocal() method returns a SQL WHERE clause fragment that can be used to implement bulk queries such as findSecuritySystems(). I’ll describe how to use oso.authorizeLocal() later in this article. Let’s first look at how to use oso.listLocal().

Configuring local authorization

To use local authorization, you must specify a local_authorization_config.yaml when creating the Oso client:

public class OsoServiceConfiguration {

  String configurationFilePath = ...;

  @Bean
  public Oso oso(@Value("${oso.url}") String osoUrl,
                 @Value("${oso.auth}") String osoAuth) {
      var optionsBuilder = new OsoClientOptions.Builder();
      if (configurationFilePath != null) {
          optionsBuilder.withDataBindingsPath(configurationFilePath);
      }
      return new Oso(osoAuth, URI.create(osoUrl), optionsBuilder.build());
  }

The path to the configuration file is passed to optionsBuilder.withDataBindingsPath(). One interesting challenge in a Spring Boot application is that the configuration file is typically in a JAR file nested within the Spring Boot JAR file. The RealGuardIO example application contains a ClasspathLocalAuthorizationConfigFileSupplier that maps a classpath resource to a java.nio.file.Path using a Virtual FileSystem - a Java feature that I was previously unaware of.

The local authorization configuration file contains two sections. First, the first section maps Polar predicates, such as has_relation(…), which are named logical rules or facts in Oso Cloud’s policy language, to SQL SELECT queries. This mapping enables Oso Cloud to generate SQL that uses facts stored locally. Second, the second section maps resource types to database column types. This section is optional but recommended in order to improve performance.

Interestingly, in this particular example, all required authorization data is replicated to Oso, so no fact mappings are required. Strictly speaking, this example can use Oso.list() instead of local authorization. Oso.list(user, permission, resourceType) returns a list of resourceIDs that the user has permission to perform an action on. A service can then use that list to construct an SQL SELECT. However, oso.listLocal() is not only more convenient, since it returns a SQL fragment, but it also supports scenarios, such as the one described later in this article, that require local data.

Here’s the configuration file that configures local authorization:

facts:

sql_types:
  Location: integer
  SecuritySystem: integer

This configuration file specifies that Locations and SecuritySystems have an Integer primary key. Later in this article, we will revisit this configuration file for a scenario where some facts are stored locally.

Implementing `findSecuritySystems()` with `oso.listLocal()`

Let’s now look at how findSecuritySystems() can use oso.listLocal(). The listLocal() method has four parameters:

user - the ID of the user attempting to access the resources
permission - the permission, such as view
resourceType - SecuritySystem
ID column - the primary key column of the table containing SecuritySystems

This method makes it straightforward to integrate authorization checks into SQL queries. The SQL SELECT for retrieving SecuritySystems looks something like this:

var sql = "SELECT * FROM ss security_systems WHERE " + oso.listLocal(...);

The SELECT’s WHERE clause is simply the fragment returned by listLocal(). The following diagram shows how this works:

In this example scenario, listLocal() returns a SQL fragment that’s equivalent to ss.id IN (202, 203). In other words, Oso Cloud returns an SQL WHERE-clause predicate containing inline values that constrain the IDs of the SecuritySystems that the user is allowed to view. Later, you will see that the SQL predicate can join with other tables when authorization uses local data. Let’s now look at an example of using local fact data for authorization.

Making authorization decisions with locally stored facts

Currently, the Customer Service and Security Service populate Oso with all the facts needed for authorization. As a result, the SQL fragment returned by Oso.listLocal() does not reference any database tables. However, while the Customer Service needs to publish its data to Oso so that it is available to the Security Service, the Security Service does not. Instead, it can use local authorization to combine the facts in its database with those in Oso.

Specifically, the Security Service does not need to publish the SecuritySystemAssignedToLocation event to maintain the Location-SecuritySystem relationship in Oso. Instead, the has_relation(SecuritySystem{…}, "location", Location{…) fact can be mapped to the SQL SELECT that queries the security_system table.

Let’s first look at the configuration file that defines the mapping. After that, we’ll revisit the findSecuritySystems() query. Finally, we’ll explore how to use oso.authorizeLocal().

The configuration file

Here’s the Oso configuration file that maps the has_relation(SecuritySystem{SECURITY_SYSTEM}, "location", Location{LOCATION}) relation to the security_system table:

facts:
  "has_relation(SecuritySystem:_, String:location, Location:_)":
    query: 'SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL'

sql_types:
  Location: integer
  SecuritySystem: integer

Let’s now look at how this affects the SQL fragment returned by oso.listLocal().

The `findSecuritySystems()` query with local facts

While the code that implements findSecuritySystems() is unaffected by this change, the SQL fragment now references the security_system table. Oso Cloud determines the locations that the user is authorized to access and returns an SQL fragment that queries the security_system table to determine the IDs of the SecuritySystems at those locations. Here’s an example fragment:

ss.id IN (WITH RECURSIVE
c0(arg0, arg2) AS NOT MATERIALIZED (
SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL
)
 SELECT f1.arg0
FROM c0 AS f1, (
VALUES (1769998271122), (17699982711222)
) as cs( arg0 )
WHERE f1.arg2 = cs.arg0
)

This generated fragment uses common table expressions that are essentially named subqueries. It’s equivalent to:

  ss.id IN (SELECT id  FROM security_system  WHERE location_id IN (1769998271122, 17699982711222))

Now that we’ve seen how to use oso.listLocal() to implement bulk queries, let’s look at local authorization for single-entity operations.

Using `authorizeLocal()`

Since some facts are only available locally, the Security System Service cannot use oso.authorize() (described previously in part 4) to authorize operations such as ‘arm’ and ‘disarm’. Instead, it must use oso.authorizeLocal(). This method has three parameters:

user - the user attempting to perform the operation
permission - the operation, such as “disarm”
resourceID - SecuritySystem with ID 101

It returns a SQL query that determines whether the user is authorized to access that resource. The query returns true or false. The following diagram shows how it works:

Here, for example, is how the Security System Service can check whether a user is authorized to disarm a security system:

var sql = oso.authorizeLocal(
              new Value("CustomerEmployee", userId),
              "disarm",
              new Value("SecuritySystem", securitySystemId)
      )
Boolean allowed = jdbcTemplate.queryForObject(sql, Boolean.class);

Here’s the SQL query returned by authorizeLocal():

WITH RECURSIVE
c0(arg0, arg2) AS NOT MATERIALIZED (
SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL
)
SELECT EXISTS (SELECT 1
FROM c0 AS f0, (
VALUES (1767657091967), (17676570919672)
) as cs( arg0 )
WHERE f0.arg0 = 1 and f0.arg2 = cs.arg0
) as allowed

This query is equivalent to:

  SELECT EXISTS (
    SELECT 1 FROM security_system
    WHERE id = 1 AND location_id IN (1767657091967, 17676570919672)
  ) AS allowed

In other words, Oso generates a SQL query that determines whether the specified SecuritySystem is at a location that the user is allowed to disarm.

Show me the code

The RealGuardIO application (work-in-progress) can be found in the following GitHub repository.

Acknowledgements

Thanks to Hazal Mestci for reviewing this article and providing valuable feedback.

Summary

Oso local authorization enables a service to make authorization decisions using a combination of facts stored in Oso and the service’s local database
- listLocal(user, permission, resourceType, ID column) - returns a SQL WHERE clause fragment that filters results based on permissions
- authorizeLocal(user, permission, resource) - returns a SQL SELECT that makes authorization decisions using local data
Local authorization requires a configuration file that maps Polar predicates facts, such as has_relation, which are named logical rules or facts in Oso Cloud’s policy language, to SQL queries
The generated SQL fragments and SELECT statements can include Oso facts, such as resource IDs
If local tables and Oso-stored data overlap, the generated SQL can contain a union of local and Oso-stored data

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservice architecture

Microservices Platforms - part 8: Getting started with platforms

Need help with modernizing your architecture?

GenAI-based development platform - part 4: The coding agent sandwich pattern

An overview of the implement plan workflow

Why not implement the implement plan workflow using a coding agent?

The top slice: orchestrating the implement plan workflow using plain old code

The filling: invoking the coding agent for narrowly defined actions

The bottom slice: deterministic tools used by the coding agent

Functional decomposition, layered and fractal

Use POC whenever you can, LLMs only when you must

Need help with modernizing your architecture?

Microservices Platforms - part 7: Deployment platform

Need help with modernizing your architecture?

GenAI-based development platform - part 3: Announcing Isolarium, three flavors of secure sandboxes for GenAI-based coding agents

Why coding agents need secure sandboxes

Coding agent security risks

Container-based testing libraries introduce additional risks

Even well-intentioned coding agents can cause damage

Secure sandboxes for GenAI-based coding agents

Three flavors of isolation

Isolarium works with i2code implement

Next steps

Need help with modernizing your architecture?

Microservices Platforms - part 6: Build platform

Need help with modernizing your architecture?

GenAI-based development platform - part 2: How Idea to Code turns an idea into working, tested software

How i2code implement orchestrates Claude Code to implement a plan

Setup phase

Recovery phase

Main implementation loop

Trunk mode

To learn more

What’s next

Need help with modernizing your architecture?

GenAI-based development platform - part 1: guardrails

Pre-commit checklist skill

Pre-commit Git hook

GitHub Actions workflow

Automated GitHub status checks: CodeScene pull request review

What’s next

Need help with modernizing your architecture?

Why GenAI-based coding agents are a complex domain in Cynefin - and what that means for adoption

About Cynefin

About Clear domains

About complicated domains

About Cynefin complex domains

Why software development is complex

Developer tools are clear or complicated

Using an LLM-based coding agent is a complex domain

Cause and effect can only be understood in retrospect

Probabilistic nature of LLMs

Organizations must adopt a complex-domain mindset for coding agents

Engineering practices must shift

Managing the unpredictability of outcomes

The platform must not act as a policy factory

The GenAI-based development platform must amplify learning

Acknowledgements

Need help with modernizing your architecture?

Microservices Platforms - part 5: Observability platform

Need help with modernizing your architecture?

Authentication and authorization in a microservice architecture: Part 6 - implementing complex authorization using Oso Cloud local authorization

Problem: Implementing findSecuritySystems()

Inefficient approach: One-by-one authorization using Oso

Integrating Oso into the database access logic using local authorization

Configuring local authorization

Implementing findSecuritySystems() with oso.listLocal()

Making authorization decisions with locally stored facts

The configuration file

The findSecuritySystems() query with local facts

Using authorizeLocal()

Show me the code

Acknowledgements

Summary

Need help with modernizing your architecture?

An overview of the `implement plan` workflow

Why not implement the `implement plan` workflow using a coding agent?

The top slice: orchestrating the `implement plan` workflow using plain old code

Isolarium works with `i2code implement`

How `i2code implement` orchestrates Claude Code to implement a plan

Problem: Implementing `findSecuritySystems()`

Implementing `findSecuritySystems()` with `oso.listLocal()`

The `findSecuritySystems()` query with local facts

Using `authorizeLocal()`