DEV Community: Roy Berris

The Three-Layer System for Consistent AI Specifications

Roy Berris — Sun, 11 Oct 2026 13:37:00 +0000

TL;DR: We treat the specification as the single source of truth for user intent and business rules, compiling functional design down through three strict layers. Business rules stay in native prose, the domain model structures invariants in English, and the contract or wire schema is simply the final compiled layer. Splitting the process this way stops hallucinations and eliminates schema drift.

When we first asked an AI model to generate a functional specification directly from rough requirements, the result looked convincing on the surface. But when we inspected the logic, the problems jumped out. The model quietly dropped business validation rules, invented defaults out of thin air, and hallucinated system behavior. Trying to fix all of that by stuffing more instructions into one giant prompt just confused the model and made the output drift even further.

People often assume specification generation is just about producing API definitions or code stubs. In our team, we look at it differently. A specification is the functional design of your system, and it is the single source of truth for user intent and business rules. Today's language models cannot bridge human intent and rigid technical contracts in one jump. To solve this, we treat functional design like a compiler chain: three distinct, strictly one-way layers that compile human truth down into a verifiable contract.

Why Does Single-Shot Specification Lead to Drift?

Most teams start by feeding user stories or meeting notes into a chat prompt and asking for an interface definition or code stubs immediately. Under the surface, the model tries to solve three completely different problems at the same time: understanding business policies, modeling domain relationships, and formatting technical contract syntax. In that single pass, it silently invents enum values, misinterprets domain invariants, and overlooks edge cases just to produce syntactically valid output.

This creates silent drift between what business stakeholders expect and what engineers actually build. The trouble usually shows up late, often when validation fails in staging. When that happens, the temptation is to patch the generated schema or contract by hand.

But the contract is only the final compiled artifact of your functional design. Hand-editing downstream contracts breaks the chain of truth. The next time you run an AI generation tool, it overwrites those manual fixes or diverges further because the source of truth was never updated.

Splitting this workflow into sequential passes introduces a small latency trade-off. Generating intermediate representations takes a few minutes instead of a few seconds. In our experience, that extra time is worth it. You keep the context clean at each step and save yourself painful debugging sessions later.

How Does the Three-Layer Compiler Pipeline Work?

Instead of treating specification generation as a single prompt, we treat it like a compiler chain. Each stage has a single, clear job, moving strictly from human and business intent down to machine contracts. Upstream artifacts remain the single source of truth, and downstream layers are generated automatically.

The system organizes requirements into three distinct stages:

Layer 1 (Human and Business Truth): Written in native business prose to capture stakeholder rules directly. In our projects in the Netherlands, capturing policies in Dutch prevents premature translation errors and preserves regulatory nuances that non-technical domain experts care about. Stakeholders can read, verify, and own this layer directly.
Layer 2 (Functional Design and Domain Model): Expressed as an English architectural specification following Domain-Driven Design principles. This layer normalizes business concepts into formal entities, value objects, lifecycle states, and domain invariants without any transport or serialization baggage. It defines what the system does and why, independent of delivery protocols.
Layer 3 (Verifiable Contract): Defined in TypeSpec, OpenAPI, or schema definitions. This layer handles transport mechanics, status codes, query parameters, header definitions, and serialization, following the principles we described in Designing APIs for AI Agents. Wire contracts and API schemas are not the starting point. They are the final compiled layer of functional design.

This workflow is an automated compiler pipeline rather than a traditional waterfall process. We edit the upstream business rules, run the generation tool, and let the pipeline compile the downstream contracts. Nobody edits the compiled wire contract by hand.

How Do We Capture and Validate Business Rules?

You cannot expect an AI model or an engineer sitting alone to invent business truth. Layer 1 requires collaborative discovery with domain experts before any code or prompt runs. In our projects, we use three discovery techniques to draw out rules from stakeholders:

Event Storming: We gather domain experts and developers in a room to map domain events along a business timeline. We explore what happens across a process, what triggers each action, and which policies govern state changes.
Example Mapping: We take each user story and break it down into concrete business rules illustrated by realistic examples. Talking through concrete scenarios reveals edge cases and hidden assumptions that abstract bullet points conceal.
Stakeholder interviews: We talk directly with product managers, operational staff, and compliance officers. Capturing their exact words in their native language preserves legal and operational nuances that get lost when developers translate requirements straight into technical jargon.

Capturing fragments of rules is only half the battle. You also need to validate the requirements as a coherent whole before feeding them to an AI compiler.

We run validation sessions with the business to check completeness. We walk through the end-to-end user journey to make sure every failure mode, boundary condition, and lifecycle transition has an explicit rule. Walking through realistic examples surfaces edge cases early, when changing a rule costs nothing.

Once the rules are complete and unambiguous, we secure formal sign-off from business stakeholders. Because Layer 1 uses plain language without HTTP status codes, JSON fields, or database tables, non-technical experts can read every sentence and take full ownership. This sign-off freezes the baseline for Layer 1. Only after the business approves Layer 1 does the AI compiler pipeline turn those rules into downstream models and contracts.

Tracing an Example Through the Three Layers: A Library Book Loan

To see how this works in practice, consider a classic scenario: a member borrowing a physical book from a library. Walking this feature through the three layers shows how business intent compiles into a technical contract while maintaining complete traceability.

Layer 1: Business Rules

Layer 1 captures the intent and rules in plain language approved by the library staff:

User Intent: A registered library member wants to borrow a physical book.
Rule 1 (Loan limit): A member can have at most 5 active book loans at any time.
Rule 2 (Good standing): A member cannot borrow books if they have an unpaid fine.
Rule 3 (Loan period): The standard loan period is 21 days from the date of checkout.

There are no endpoints, status codes, or database keys here. Any librarian can read this list and confirm whether it accurately describes how the library operates.

Layer 2: Domain Model

Next, the compiler pipeline generates the English architectural specification. Layer 2 applies domain-driven design concepts to model entities, invariants, post-conditions, and domain events:

Entity: Loan (attributes: loanId, memberId, bookId, loanDate, dueDate, status).
Domain Invariant (BorrowBookPolicy): A loan can only be created if the member's current active loans count is less than 5, and the member's unpaid fine balance is zero.
Post-conditions: A new Loan is instantiated with status: Active and dueDate calculated as loanDate + 21 days.
Domain Event: The system emits a BookBorrowed event containing loanId, memberId, bookId, and dueDate.

Layer 2 defines what the domain logic must enforce. It still contains zero HTTP headers or serialization details.

Layer 3: Verifiable Contract

Finally, the pipeline compiles Layer 2 into a verifiable API contract. Here is the OpenAPI definition for the borrow operation:

paths:
  /members/{memberId}/loans:
    post:
      summary: Borrow a book
      operationId: borrowBook
      security:
        - bearerAuth: ["loans:borrow"]
      parameters:
        - name: memberId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bookId
              properties:
                bookId:
                  type: string
      responses:
        "201":
          description: Book borrowed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Loan"
        "409":
          description: Business policy violation
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - loan-limit-reached
                      - unpaid-fine

Notice how this contract structures the response codes. The schema returns a 201 status code with the created loan on success, or a 409 Conflict with a machine-readable error when a domain rule fails.

Emphasizing Traceability

Look closely at how every line in this Layer 3 contract traces directly back through Layer 2 to Layer 1:

The path /members/{memberId}/loans and operation summary Borrow a book trace directly to the plain-language user intent in Layer 1.
The required permission loans:borrow traces to the library policy that the caller must have borrowing privileges.
The 409 error enum loan-limit-reached traces through the Layer 2 BorrowBookPolicy invariant back to Rule 1 (limit of 5 active loans).
The 409 error enum unpaid-fine traces through the Layer 2 invariant back to Rule 2 (no unpaid fines allowed).
The dueDate in the returned Loan object traces through the Layer 2 post-condition back to Rule 3 (21-day loan duration).

Nothing in the contract appears out of thin air. If a model generates an unexpected error code or an extraneous query parameter, you can flag it instantly because it lacks an upstream parent in Layer 1. Every line in the contract traces directly back to an approved business rule.

Why Is This Three-Layer Scaffolding Temporary?

We want to be clear about why this system exists today. These three separate stages are practical scaffolding built around the limits of current language models. Right now, models cannot reliably preserve nuance across multiple levels of abstraction in a single inference pass.

We think of this three-layer pipeline as a deliberate engineering hedge. It stabilizes model outputs today without locking our architecture into rigid, permanent workflow machinery. We documented this architectural boundary choice in an Architecture Decision Record (ADR) so our team understands why we enforce these boundaries and under what conditions we can simplify them.

Eventually, models will be capable enough to jump from business discussions to validated wire schemas without intermediate steps. When that shift happens, explicit file-based handoffs between layers will disappear from our daily work. Even then, the underlying separation of concerns between business truth, functional design, and verifiable contracts will remain structurally sound.

How Does the Pipeline Stay Consistent When Models Change?

Model behavior changes with every new release, but this pipeline keeps our specifications stable. Layer 1 functions as source code, while Layer 2 and Layer 3 act as compiled build artifacts. When business requirements shift, we update the business rules in Layer 1 and trigger a clean compilation rather than patching downstream files.

In our team, we store domain rules, conventions, and architectural constraints inside version-controlled repository instructions and skills. Keeping guidance in git repositories ensures every engineer and continuous integration agent runs the exact same prompts. Ad-hoc chat sessions lose context quickly, but versioned skills keep that knowledge in the repository where everyone can use it.

The architecture remains completely tool-agnostic. You can switch the underlying foundation model or migrate from TypeSpec to another interface definition language whenever you choose. Because your core functional design lives upstream in clean domain models, changing a code generator never forces a rewrite of your business rules. When tools improve, downstream layers are simply regenerated.

Recommendations for Your Team

Setting up this pipeline requires discipline around layer boundaries and prompt management. If you want to set up this system in your own projects, here is our practical advice:

Adopt a spec-first mindset: Treat functional design as the single source of truth for user intent and business rules, not code stubs or handwritten schemas.
Treat Layer 1 as the sole source of truth: Update business rules in native prose and secure business sign-off before compiling downstream layers.
Ensure strict traceability: Make sure every property, operation, and error status in Layer 3 is derived from and traceable to an approved Layer 1 rule.
View the wire contract as the compiled layer: Treat APIs and schemas as the final compiled representation of functional design, not the starting point.
Ground Layer 2 in domain-driven design: Express domain invariants, entities, and events in clean English before worrying about transport protocols.
Regenerate downstream layers when tools improve: Treat Layer 2 and Layer 3 as build artifacts. When you upgrade models or linters, recompile from Layer 1 instead of hand-patching files.
Automate downstream compilation: Run models in strict one-way passes using automated scripts or continuous integration tasks.
Version control your prompt instructions: Commit architectural rules, ADRs, and skills to your git repository alongside the project code.
Validate contracts with deterministic tools: Use standard TypeSpec compilers or schema linters to catch syntax errors and contract flaws immediately.
Never edit generated layers by hand: If you hand-tweak Layer 2 or Layer 3 outputs, subsequent compilations will wipe out your modifications.
Avoid two-way sync: Never attempt to back-propagate changes from a wire contract back into the domain model. Keep it strictly one-way.
Keep transport details out of business rules: Serialization quirks, status codes, and HTTP headers do not belong in Layer 1 or Layer 2.

Conclusion

A specification is not just an API contract. It is the functional design that captures user intent and business rules as your single source of truth. By treating functional design as a three-layer compiler pipeline, you stop hallucinations and keep your contracts consistent with what the business actually needs.

Give the model one job at a time, and let the compiler do the rest.

FAQ

Is this three-layer system only for APIs?

No. While the final layer often produces API schemas or interface definitions, the pipeline is about generating the functional design as a whole. The specification is the single source of truth for user intent and business rules, and the contract is simply the final compiled layer of that functional design.

How do you capture business rules before compiling?

We capture business rules through collaborative workshops with domain experts, using Event Storming to discover events, Example Mapping to pin down rules and edge cases, and stakeholder interviews. We validate the rules as a coherent whole and secure formal business sign-off before running the AI compiler pipeline.

Why write Layer 1 in native language instead of English?

Writing Layer 1 in native business prose, such as Dutch in our projects in the Netherlands, captures policies directly from stakeholders without premature translation. This preserves regulatory nuances and policy details that domain experts care about, before Layer 2 translates and normalizes them into English domain concepts.

What happens when business requirements change or tools improve?

You update the approved business rules in Layer 1 and recompile downstream layers through the automated pipeline. Because Layer 2 and Layer 3 are compiled build artifacts, you never hand-patch downstream files, and you can regenerate your entire contract whenever your foundation models or toolchain improve.

Originally published at berris.dev.

Start Treating AI Like a Human Colleague

Roy Berris — Sun, 11 Oct 2026 13:36:47 +0000

TL;DR: The biggest mistake with AI in software engineering is component-level micromanagement: pre-designing every interface, class, and table yourself before handing off the pieces. When you treat AI like a capable engineering colleague, you define the desired business outcome and domain boundaries, then let it architect and build the whole system. Your job shifts from sketching components to steering outcomes, evaluating trade-offs, and mentoring.

I'll be honest with you: as a software architect, my default instinct has always been to break everything down. For years, I treated system design like a puzzle where my job was to shape every single piece. When AI coding tools arrived, I brought that exact habit with me.

I would spend hours mapping out every database table, defining every service interface, specifying every Data Transfer Object (DTO), and deciding which method called which helper. Once I had pre-chewed every component, I handed the pieces to the AI one by one, like an architect handing brick specifications to a bricklayer.

It gave me a sense of control, but it was exhausting. I was doing ninety percent of the thinking myself, drawing boxes and dictating signatures. I was acting as the architect, the product manager, and the micromanager, using AI as a fast typist to fill in the blanks I had already solved. I was the biggest bottleneck on the project.

The turning point came when I stopped and looked at how I work with senior engineering colleagues. When a talented engineer joins the team, you don't hand them a diagram of twelve classes and tell them what to name every variable. You explain the business problem, lay out the constraints and domain boundaries, and say: "We need this outcome. Design the system and build it." Once I gave an AI agent an outcome and let it design the whole system, the way I work changed completely.

Why Does Component-Level Micromanagement Fail?

When developers tell me that AI only produces shallow code, the problem is almost always how they divide the work. They do all the high-level thinking themselves, break the problem into tiny component-level tasks, and then ask the model to implement one isolated piece at a time. In my experience, this micromanagement breaks down in three ways.

First, the architect stays the bottleneck. If you have to design every component before an agent can write a line of code, your delivery speed is capped by your own calendar. You spend your day writing micro-specifications, reviewing tiny pull requests, and answering questions about isolated classes. You aren't scaling your engineering output. You are just drowning in administrative overhead.

Second, systems end up fragmented. When you feed an AI agent one component at a time, it has no visibility into how the whole system fits together. It writes a clean repository class, a nice validator, and an isolated controller. But when you wire them up, the pieces clash. The validator expects data the controller never extracts, the database transaction doesn't cover the event publisher, and error handling is inconsistent. Because the model was trapped inside a single component, it couldn't design for the real failure modes of the system.

Third, you waste the model's actual reasoning strength. Modern frontier models can inspect an entire repository, understand cross-cutting concerns, and reason about architectural trade-offs across multiple layers. When you force the model to only fill in pre-defined method stubs, you discard that capability. You treat an engine capable of designing systems like a line-by-line code generator.

How Do You Hand Over an Outcome Instead of a Component?

In my post on AI-assisted blogging, I described how I treat AI as a writing partner rather than a ghostwriter. I bring the ideas, the real-world experiences, and the editorial judgment, while the model helps with structure and flow.

Engineering delegation works the same way, but at the system level.

The component-level approach looks like this: "Create an order validation service with an interface that checks inventory levels against the database and returns a validation result enum." You have already made every design decision. The model is just typing syntax.

The outcome-level approach looks like this: "We need an order processing subsystem that handles checkout requests under high concurrency. It must guarantee that we never sell out-of-stock items, handle payment gateway timeouts cleanly without leaving orphaned orders, and publish domain events for downstream shipping. Respect our existing outbox pattern, write the database migrations, and verify the flow with integration tests."

When you frame the task around an outcome, you let the AI do what engineers do: synthesize a solution. The agent evaluates the data model, chooses how components interact, designs the API contracts, and wires up the persistence layer.

When you delegate at this macro level, your role shifts upward:

Framing outcomes and success criteria: You define what the system must accomplish, including performance targets, consistency requirements, and compliance rules.
Guarding domain invariants: You make sure illegal states are unrepresentable in your domain models, an idea I explored in Using Value Objects in .NET. Strong domain invariants prevent the agent from inventing invalid business logic.
Setting system boundaries: You establish the perimeter, including security policies, external contracts, and integration protocols (as discussed in Designing APIs for AI Agents).
Reviewing architecture and mentoring: You evaluate the agent's proposed system design and review the resulting pull request with the same rigor you would give a human peer.

What Does System-Level Delegation Look Like in Practice?

Here's how this actually works in practice across our team's daily cadence.

Aligning on Outcomes and Architecture

Instead of spending hours drafting component specifications, I write a clear outcome brief for an entire subsystem. I describe the problem, the existing system topology, and our operational constraints.

Before writing application code, the agent explores the repository and proposes an architectural plan or a draft Architecture Decision Record (ADR). As I wrote in Standardizing API Conventions with ADRs, written records make architectural intent explicit. The agent outlines how it plans to structure components, what data models it needs, and what trade-offs it considered. For example, it might explain why it chose an outbox pattern with transactional messaging over synchronous HTTP calls to downstream services.

I review that architecture proposal. If the design has a flaw, we discuss it and adjust the plan before any code is written.

System-Wide Implementation and Verification

Once we align on the architectural direction, the agent builds the entire system across the codebase. It doesn't stop at one class. It creates the database migrations, implements domain logic, builds API endpoints, configures background workers, and writes integration test suites.

Because the agent owns the full system, the contracts between components fit together naturally.

The agent also runs the test suite locally. If an integration test fails because an outbox event didn't publish during a database rollback, the agent diagnoses the failure across both components and fixes the transaction boundary. It doesn't wait for me to find the bug in code review; it verifies its own work.

Mentoring and Harness Feedback

When I review the pull request, I look at the big picture: Does this architecture fit our long-term goals? Are our operational failure modes covered?

If the agent made an architectural misstep, like introducing an unnecessary distributed lock or violating an API convention, I don't just quietly patch the code. I explain the issue and update our repository instructions, ADRs, or test fixtures. Just like mentoring a human colleague, you teach the agent how your team thinks so it doesn't repeat the mistake on the next system.

Where Are the Boundaries Between Macro Delegation and Direct Control?

Delegating entire systems to AI is powerful, but it does not mean stepping away from responsibility. You have to know where your boundaries lie.

What Humans Must Own

There are areas where human judgment is irreplaceable:

Strategic business trade-offs: AI cannot know the organizational politics of your company, which features can be compromised to hit a launch deadline, or how much operational risk your business can absorb. You own the strategy.
Security perimeters and blast radiuses: Authentication mechanisms, tenant isolation rules, authorization boundaries, and secrets management must be strictly guarded. You define the perimeter; the agent builds inside it.
Production accountability: When a system breaks in production at 3 AM, the AI isn't on call. You are. That is why reviewing the macro architecture, inspecting failure modes, and enforcing automated verification remain your responsibility.

When to Keep It Interactive

There are two scenarios where autonomous system delegation doesn't work well:

Ambiguous or exploratory requirements: If the business problem is still vague and you don't know what outcome you want, delegating an entire system will only produce the wrong architecture faster. In those moments, I sit with product managers and sketch ideas interactively before delegating anything.
Visual user interfaces: Building web or mobile UIs relies heavily on visual feedback, brand feel, and subjective aesthetic judgment. Autonomous delegation often struggles here; interactive pairing with fast hot-reloading remains far more effective.

Save system-level delegation for substantive backend subsystems, data pipelines, integrations, and automated test coverage. Those are the areas where clear specifications, domain invariants, and automated verification shine.

Conclusion

Treating AI like an engineering colleague isn't about pretending software has feelings. It is about understanding where human thinking creates the most value.

When you spend your week micromanaging components, drafting method signatures, and pre-chewing classes, you become a bottleneck. You end up tired, and your systems end up fragmented.

When you step back, define clear outcomes, and let AI architect and build the whole system, your day changes. You spend your time on what truly matters: defining domain boundaries, evaluating architectural trade-offs, and mentoring.

If you want real impact from AI, stop pre-chewing every component and start handing over the whole problem.

FAQ

What does it mean to delegate at the outcome level instead of the component level?

It means asking AI to solve a complete business problem rather than write an isolated class or method. You provide the goals, domain boundaries, and constraints, and let the agent design the component architecture, data contracts, and implementation across the whole system.

How do you stop an AI agent from choosing the wrong architecture for a whole system?

Have the agent produce an architectural plan or draft Architecture Decision Record (ADR) before it writes code. By reviewing the proposed component boundaries, data models, and trade-offs upfront, you catch misalignments before implementation starts.

Does letting AI design whole systems replace the software architect?

No, it elevates the architect. Instead of spending your time specifying low-level interfaces and drawing component boxes, you focus on business strategy, domain invariants, security perimeters, and architectural evaluation.

When should you avoid delegating an entire system to an AI agent?

Avoid it when the business requirements are still ambiguous, or when working on visual user interfaces that require subjective aesthetic judgment. In those cases, interactive pairing and rapid prototyping work much better.

Originally published at berris.dev.

Managing AI Agents on a Remote Devbox

Roy Berris — Sun, 11 Oct 2026 13:31:33 +0000

TL;DR: Running autonomous AI coding agents across local terminal tabs and desktop apps drops running tasks whenever your laptop sleeps, and scatters mental focus across unmanaged branches. I moved my agent runtime to a dedicated Linux devbox orchestrated with git worktrees, tmux, and an open-source VS Code extension. This turns VS Code into a persistent control plane, keeps tasks isolated from my working tree, and retains access to private networks and multi-repo test suites.

I'll be honest with you: when I first started running autonomous AI coding agents, I thought my local terminal was all I needed. I opened Claude Code in one tab, OpenAI Codex in another, and kept the desktop app open on a second screen for quick questions. It felt fast at first. But within two weeks, that setup completely fell apart under heavy daily use.

I was losing mental bandwidth trying to remember which terminal tab was refactoring which service. Worse, long-running agent tasks died the moment I shut my laptop lid to step into a meeting. If you run multiple coding agents concurrently, running them locally turns into a constant fight with interrupted sessions and dirty git trees.

Why Does Running AI Agents Locally Fall Apart?

Running AI coding agents locally starts simple when you run a single prompt. But once you run multiple tasks concurrently, that setup quickly breaks down in three distinct ways.

First, you run into open mental loops. Having four or five concurrent agent sessions scattered across local terminals, integrated editor panes, and desktop apps scatters your focus. You forget which task was running where, only to rediscover abandoned branches days later as open pull requests (PRs). Those unresolved loops linger in your head during evenings and weekends.

Second, local sessions lack durability. The moment you close your laptop, walk into a meeting, or switch between Wi-Fi and ethernet, local terminal connections break. Long-running test suites, dependency builds, or multi-step agent refactors terminate abruptly halfway through execution. You have to inspect the partial state, clean up unstaged changes, and restart the prompt from scratch.

Third, standalone desktop apps hit hard environment boundaries. The Claude Desktop app handles isolated questions well, but it falls short in complex environments. It operates in isolation and cannot manage multi-repo workflows where a front-end monorepo must talk directly to a local services monorepo to run end-to-end integration tests. It also lacks access to private networks. It cannot authenticate against internal Virtual Private Clouds (VPCs) or query Application Insights logs over a non-production Virtual Private Network (VPN) using a read-only Azure CLI session.

How Does a Remote Devbox Solve This?

The alternative I moved to is treating my laptop as a thin display and moving the entire agent execution runtime to a dedicated Linux devbox. In my setup, that is an 8-core, 16 GB RAM Ubuntu server running in my home lab, but a cloud virtual machine or an office server works just as well. Instead of running agents directly inside my primary working tree, every agent session runs in its own persistent tmux session attached to an isolated git worktree (agent/<task-name>).

I considered using separate full repository clones or Docker containers for each agent. But full clones waste disk space on duplicate .git directories and slow down dependency installs. Docker containers add overhead, slow down file watching, and make running native developer tooling clumsy. Git worktrees share the same underlying repository storage and object history, but check out a completely independent branch into a separate directory. This gives the agent total isolation without duplicating repository data, preventing file-lock collisions and unstaged diff pollution.

This completely changes how I use Visual Studio Code (VS Code). Manual side-by-side programming is gone. VS Code becomes an orchestration dashboard and terminal control plane: one large terminal surface connected to the devbox, a sidebar tracking running sessions and processes, and the file explorer to inspect docs-as-code, Architecture Decision Records (ADRs), and generated diffs whenever verification is needed.

A key practical advantage of using VS Code Remote - SSH here is automatic port forwarding. When you or an agent run a dev server on the devbox (like npm run dev), VS Code Remote detects the listening process and forwards the port automatically. You can open localhost:3000 directly in your local laptop browser without fiddling with manual SSH tunnel flags. The devbox handles the compute and file watching, but previewing the application feels like running it locally.

How Does the Extension Architecture Work?

To tie this workflow together without switching windows, I built devbox-vscode-extension (documented in our Projects catalog). You can install it directly from the VS Code Marketplace. It runs directly inside VS Code over VS Code Remote - SSH and acts as the interface layer over tmux, git worktrees, and running agent processes.

Worktree Isolation and Session Management

The extension eliminates manual git worktree plumbing. Launching an agent provisions a dedicated worktree and spawns a background tmux session tied to that directory.

Automated Worktree Lifecycle: When an agent starts, a new branch is cut and mounted in an isolated worktree path under the repository root. When the work is merged or abandoned, tearing down the session removes the worktree cleanly without leaving stale directories behind.
Process Inspection and Cleanup: The extension queries the host for running Claude Code and Codex process IDs. It identifies whether a process originated from tmux, an interactive SSH session, or became an orphaned daemon, exposing one-click kill controls right in the sidebar.
Repository Discovery: It scans ~/repos on the devbox, showing ahead and behind commit counts, uncommitted working tree changes, and missing dependencies across every monorepo.

Reviewing Pull Requests Directly in the Editor

Because the extension relies on native git worktrees rather than proprietary containers, it integrates cleanly with the official GitHub Pull Requests and Issues extension. When an agent completes a task and opens a PR, you check out and review the pull request directly inside VS Code over VS Code Remote - SSH on the existing worktree. You never leave the editor to open a browser tab or desktop application just to inspect code changes.

Host-Level Sandboxing and Guardrails

Running agents on a dedicated Linux host makes sandboxing practical. Instead of granting blanket permissions on your personal workstation, the devbox runs agents with explicit command and network boundaries:

Command Allowlisting: Critical deployment tools, production credentials, and destructive system commands are restricted or blocked entirely.
Scoped Network Access: The devbox maintains a non-production VPN tunnel and a read-only Azure CLI session. Agents can inspect telemetry and logs in Application Insights to debug issues without having permissions to modify infrastructure or leak sensitive keys.

What Happened in Practice: Gotchas and Trade-offs

Adopting a remote devbox for agent workflows is not without friction. A few real-world trade-offs stand out from my experience:

The Hardware Paradox: Running agents on a remote 8-core Ubuntu devbox means my powerful local machine (an Apple Silicon M4 Max) sits mostly idle while the devbox compiles code. You trade raw local burst speed for persistence and isolation.
Rate Limit Juggling: Heavy agent usage burns through provider quotas quickly. When hitting Claude rate limits or weekly token caps, the devbox setup lets me pivot the existing worktree session to Codex without losing worktree state or branch progress.
Overkill for Casual Use: If you run one or two simple prompts a day, maintaining a remote server, SSH keys, VPNs, and worktree extensions is unnecessary overhead. This architecture only pays for itself when managing multiple autonomous tasks concurrently across complex repositories.

Recommendations for You

If you want to move your own agent workflows to a remote machine, start with simple boundaries. Here is what worked best in my setup:

Isolate every agent in a dedicated git worktree: Never let an autonomous agent touch your main working copy. Worktrees isolate file locks, dependencies, and experimental commits.
Keep architectural specifications inside the repository: Store Architecture Decision Records (ADRs) and specifications directly in the codebase so agents and human reviewers evaluate diffs against the same documented requirements.
Run long tasks on persistent remote sessions: Relying on local terminal sessions guarantees interrupted runs the moment your laptop sleeps or your Wi-Fi drops.
Sandbox permissions on a dedicated host: Setting up a non-root user, firewall rules, and a command allowlist is straightforward on a dedicated Linux host, whereas locking down your primary laptop without breaking your daily tools is nearly impossible.
Consolidate sessions into a single control plane: Keep your terminal, session list, diff review, and pull request workflows anchored inside a single editor window instead of scattering them across multiple apps.

Conclusion

Moving AI coding agents from my local laptop to a remote Linux devbox solved the two biggest headaches I had: lost execution state and scattered mental focus. With git worktrees for isolation, tmux for session durability, and VS Code Remote - SSH as a control plane, I can kick off three agent refactors, shut my laptop, and come back to review clean pull requests when I'm ready.

Autonomous coding agents are only as good as the environment you give them to run in.

FAQ

Why use git worktrees instead of Docker containers or fresh git clones?

Git worktrees share the same underlying repository storage and commit history without downloading gigabytes of duplicate files, while keeping the agent's changes completely isolated from your main working tree. They avoid the file-watching and tooling friction of Docker containers while preventing file-lock collisions.

What happens to a running agent session if my laptop loses Wi-Fi?

Nothing stops running. Because the agent executes inside a tmux session on the remote devbox, tests keep running and the agent keeps editing code. When you reconnect over VS Code Remote - SSH, you attach right back to the active session.

How do you sandbox agent permissions on the remote devbox?

The devbox runs agents with command allowlists that block critical deployment commands and destructive system tools. It uses a non-production VPN tunnel and a read-only Azure CLI login, letting agents inspect telemetry in Application Insights without granting permission to change infrastructure.

Is a remote devbox setup worth it for casual AI coding?

No. If you only prompt an AI assistant a couple of times a day for small snippets, setting up a remote server, SSH keys, and worktree tooling is unnecessary overhead. It only pays off when you run multiple autonomous tasks concurrently across complex or multi-repo projects.

Originally published at berris.dev.

Designing APIs for AI Agents: Schemas, Security and MCP

Roy Berris — Sun, 11 Oct 2026 13:31:28 +0000

TL;DR: Postman's 2025 State of the API report shows that 89% of developers use AI in their daily work, but only 24% design APIs with AI agents in mind. My answer is to design for humans and AI agents at the same time: treat the schema as the shared language, put business context in it, keep every pattern consistent, rethink security for automated consumers and design endpoints as tools with clear contracts.

The API development world changed a lot in 2024, and it caught many of us by surprise. While we were busy making APIs better for human developers, a new consumer appeared that works very fast: AI agents. Postman's 2025 State of the API report shows clearly that 89% of developers now use AI tools every day, but only 24% design APIs with AI agents in mind. This gap shows a big problem that needs new design patterns.

Why Do AI Agents Need Different API Design?

When I design APIs today, I still think about the developer who will read my docs, understand my endpoint patterns, and write code to connect with it. But here's what Postman's research showed that really changed how I think about building APIs: AI agents are already using APIs at huge scale with a 40% increase from last year.

The disconnect is there. While 89% of developers use AI tools for making code and solving problems, most of us keep designing APIs using patterns made for human use. Only 13% design equally for humans and AI agents, while just 7% mainly design for AI agents. This mismatch creates basic problems when AI agents meet APIs that don't have clear schemas, typed errors, and clear behavioral rules.

How Do You Design an API for Both Humans and AI Agents?

The key thing I've learned is that AI agents are trained on human language, which means we shouldn't design only for machines. Instead, we need to design for both humans and machines at the same time through consistent, well-documented interfaces that show intent and purpose.

Schema as the Shared Language

I think of the API schema as the shared language between humans and machines. The schema is not just a technical contract. It's a complete way to communicate that shows intent, purpose, and business context in ways both developers and AI agents can understand.

Semantic Metadata: Intent and Purpose

The schema should tell a story about what the API does and why it exists. This means using clear field names that show business concepts, useful error codes that help fix problems, and response structures that show how things work together. When an AI agent sees a well-designed schema, it understands not just what data to send, but why that data matters and how it connects to real business work.

Functional Documentation: Business Context

Traditional OpenAPI specs focus on technical contracts, but AI agents need business context to make smart decisions. I learned this the hard way when building APIs that agents couldn't use effectively. Now I put functional context directly into schema definitions through custom properties (OpenAPI specification extensions, the x- fields) that give semantic meaning, links that connect technical operations to business outcomes, and workflow descriptions that show how endpoints work together to solve real problems.

This approach changes the schema from a purely technical thing into a complete communication tool. Instead of keeping separate technical and functional documentation, the schema becomes one source of truth that shows both implementation details and business intent.

Navigation Metadata: Easy Discovery

The schema should help find related functionality through structured navigation data. This includes relationship patterns that mirror real-world workflows, endpoint hierarchies organized around functional use cases rather than technical resource structures, and built-in guidance that helps both humans and AI agents understand when and how to use specific operations.

In my experience, organizing APIs around the problems they solve, rather than just data model relationships, makes them much easier for human developers while giving AI agents clear functional context about usage patterns.

Example: Traditional vs. Agent-Aware Schema Design

Here's how the same endpoint looks when designed traditionally versus with AI agents in mind:

# Traditional approach - technical focus
/api/users/{id}:
  get:
    responses:
      200:
        content:
          application/json:
            schema:
              properties:
                id: { type: string }
                name: { type: string }
                email: { type: string }

# Agent-aware approach - semantic focus
/api/users/{userId}:
  get:
    summary: "Retrieve user profile for account management"
    x-business-context:
      purpose: "Account management and user support"
      workflows: ["user-lookup", "billing-inquiry"]
    parameters:
      - name: userId
        schema:
          type: string
          pattern: "^usr_[a-zA-Z0-9]{16}$"
        x-semantic-meaning: "Primary user identifier"
    responses:
      200:
        content:
          application/json:
            schema:
              properties:
                userId: { type: string }
                profile:
                  type: object
                  x-business-purpose: "Identity verification"
                accountStatus:
                  type: string
                  enum: ["active", "suspended", "pending"]
                  x-business-impact: "Determines available actions"
      404:
        description: "User not found"
        x-remediation: "Verify user ID format"

Consistency as a Design Language

Consistency becomes the design language that both humans and machines can learn and use. This means using the same naming rules across all endpoints, standard HTTP status code usage, the same authentication methods, and error handling patterns that create a predictable interaction model.

I use a pattern where every endpoint follows the same basic template: consistent parameter naming that shows business concepts, standard response envelopes that tell a complete story, the same error response formats that give useful guidance, and predictable resource relationship patterns that mirror real-world workflows. This consistency allows both human developers and AI agents to learn patterns once and apply them across the entire API surface.

Unified Communication Architecture

The diagram below shows how schema-driven design creates a unified communication layer that serves both human developers and AI agents:

How Should API Security Change for AI Agents?

The security implications of AI agents as API consumers present a big challenge, but one that can be addressed with thoughtful design patterns. Postman's research shows that 51% of developers now cite unauthorized agent access as their top security concern, highlighting the need for better security approaches.

Traditional API security designs assumed predictable human behavior, developers making dozens of calls per day, following documented patterns, operating within reasonable rate limits. AI agents challenge these assumptions by operating at high speeds, keeping persistent automated access, and potentially turning a single compromised API key into a gateway for extensive data extraction. However, these challenges create opportunities to build stronger security designs.

Behavioral Security Architecture

The unpredictable behavior of AI agents makes it hard to tell legitimate automation from attacks using traditional rule-based approaches. While I haven't needed to implement these patterns at scale yet, my team is exploring security designs that move beyond static rules to behavioral analysis systems that can recognize patterns in real-time and adjust responses dynamically.

This approach needs dynamic rate limiting based on behavioral patterns, better monitoring for suspicious activity, and shorter-lived credentials with automatic rotation. The key is building systems that can tell the difference between legitimate automation and potential attacks through behavior rather than static rules.

What Does the Model Context Protocol (MCP) Change?

The emergence of the Model Context Protocol represents an interesting development in API architecture for AI use. While 70% of developers know about MCP according to Postman's research, only 10% use it regularly. This points to growing interest but limited readiness in the ecosystem.

MCP introduces new patterns for structured interfaces between AI models and real-world systems. It addresses critical problems like unified agent access, standard security models, and structured tool definitions that agents can reliably understand. The protocol defines clear boundaries between what AI agents can discover, understand, and invoke.

Key Principles from MCP

Regardless of whether MCP becomes the standard, the principles it embodies represent the direction we need to move. Structured interfaces with explicit capability declarations, clear tool definitions with typed parameters and responses, standard security models that work across different agent implementations, and discovery mechanisms that allow agents to understand available functionality.

In my projects, implementing these principles improves API architecture even without full MCP adoption. Making APIs agent-consumable through structured interfaces provides immediate benefits and future flexibility, whether MCP succeeds or alternative standards emerge.

Example: Semantic Extensions in Practice

Here's how I extend OpenAPI schemas with semantic metadata in my projects:

{
  "paths": {
    "/customers/{customerId}/support-tickets": {
      "post": {
        "summary": "Create customer support ticket",
        "x-business-context": {
          "purpose": "Enable customers to report issues",
          "workflow-stage": "issue-reporting",
          "related-operations": [
            {
              "operation": "GET /customers/{customerId}/support-tickets",
              "relationship": "list-related"
            }
          ]
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "subject": {
                    "type": "string",
                    "x-semantic-purpose": "Primary classification for routing"
                  },
                  "priority": {
                    "type": "string",
                    "enum": ["low", "medium", "high", "critical"],
                    "x-business-rules": {
                      "critical": "Service outage affecting multiple customers",
                      "high": "Feature broken for paying customer"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "x-business-outcome": "Customer issue is now tracked",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "ticketId": {
                      "type": "string",
                      "x-semantic-purpose": "Primary reference for follow-up"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This shows how semantic extensions (x-business-context, x-semantic-purpose) provide context for both developers and AI agents.

Preparing for Protocol Evolution

The low adoption rate suggests practical barriers that the industry needs to address, but the design patterns remain valuable. Building APIs with explicit capability declarations, structured tool definitions, and clear security boundaries positions systems to adapt to whatever standards emerge.

This approach means designing APIs as tool catalogs rather than simple data interfaces. Each endpoint becomes a tool with clear inputs, outputs, and behavioral contracts that both human developers and AI agents can understand and invoke reliably.

Key Design Priorities for the Future

Based on what I've seen in recent projects and the trends Postman identified, there are big changes coming in API architecture. The shift from human-focused to machine-focused design needs new patterns, different security models, and better documentation strategies. Three design priorities emerge as critical for systems that need to support both human developers and AI agents well.

Machine-First Interface Design

APIs must be built with AI agents as primary users rather than afterthoughts. This means designing interfaces that provide machine readable schemas, predictable patterns, and comprehensive behavioral specifications from the ground up. The architecture should assume automated use and optimize for reliability at high speeds.

Adaptive Security Architecture

Security models must evolve beyond traditional patterns to handle high-speed exploitation, persistent automated attacks, and unpredictable behavior. This needs architectural approaches that can tell the difference between legitimate automation and attacks through behavioral analysis rather than static rules.

Tool-Oriented Design Patterns

API architecture must shift from simple data interfaces to structured tool catalogs where each endpoint represents a well-defined capability with clear inputs, outputs, and behavioral contracts. This design pattern enables both human developers and AI agents to understand and invoke functionality reliably.

Conclusion

The API landscape stands at a turning point where we must design for both human understanding and machine use at the same time. The key insight is that AI agents are trained on human language patterns, which creates an opportunity to build unified architectures that serve both audiences well.

My experience shows that the practices needed for effective human-machine API use (consistent patterns, schema-driven functional documentation, and discoverable use case context) create better APIs overall. These aren't competing design goals but approaches that work together and strengthen each other.

The future belongs to APIs that work as complete communication systems, where schemas serve as natural language interfaces and functional documentation is discoverable through the same mechanisms that AI agents use for technical discovery. The design patterns we implement today will determine whether our systems can communicate effectively with both human developers and AI agents.

The time to start building these unified communication architectures is now.

FAQ

How many developers design APIs for AI agents?

According to Postman's 2025 State of the API report, 24% of developers design APIs with AI agents in mind. Only 13% design equally for humans and AI agents, and 7% mainly design for AI agents. At the same time, 89% of developers use AI in their daily work.

What should an API schema include for AI agents?

Clear field names that match business concepts, useful error codes, and the business context behind each operation. I add that context with custom x- extensions such as x-business-context and x-semantic-purpose, including the workflow an endpoint belongs to and which operations relate to it.

Do I need MCP to make my API ready for AI agents?

No. MCP adoption is still low, but its principles already help: explicit capability declarations, typed tool definitions, standard security models and discovery. In my projects, applying those principles improves the API even without full MCP adoption.

How do AI agents change API security?

AI agents work at high speed with persistent automated access, so a single compromised API key can open the door to large-scale data extraction. My team is exploring behavioral analysis, dynamic rate limiting and shorter-lived credentials with automatic rotation instead of static rules. I haven't needed these patterns at scale yet.

Originally published at berris.dev.