Philipp's Blog

Modularity is awesome when working with agents

Sat, 29 Aug 2026 12:26:00 GMT

Motivation

For around half a year, I've been going all-in on agentic coding. There have been a lot of hurdles, but the productivity increase is magnificent. I've been building the most ambitious and largest projects of my professional career.

While the speed increase is incredible, there are problems. One concept that has been resonating with me is the concept of three debts, which I learned about from Margaret-Anne Storey. These are technical debt in the code, cognitive debt in our understanding of it, and intent debt between what we wanted and what we built. Using AI to write all of my code has massively increased the accumulation of these debts.

However, these debts aren't a new problem. In fact, reducing and managing these debts is one of the primary goals of the entire discipline of software architecture. I've been reading up on and learning a lot about software architecture and have found it very useful when working with coding agents.

Modularity

The architectural pattern that I want to focus on in this blog post is modularity. Designing software in a modular manner has massively improved my collaboration and productivity when using coding agents, on both a personal and a team level.

The most important concept of modularity is that modules should be loosely coupled and have high cohesion. There are a lot of ways to achieve this. I'd like to focus on information hiding and dependency inversion.

If you aren't familiar with these concepts, I will provide a small example. Let's build a small NestJS app to track my espresso consumption. I want to track all kinds of beans I've tried and have a journal in which I log taste, my grinder settings and so on.

If you just give this task to AI, it will probably create two services to manage journal entries and beans, then implement the feature. The JournalService will probably import everything from the BeansService. If you are unlucky, the BeansService will also already know about everything from the JournalService to, for example, create average ratings for each bean.

To work in a modular manner, you'll instead create two modules: let's call them the beans module and the journal module.

First, one might be tempted to just expose the BeanService. However, this would couple the journal module to a lower-level component in the beans module, which might again expose internal implementation details. Instead, the beans module exposes a small interface that a concrete service will implement. This is dependency inversion.

// bean-reader.ts
export const BEAN_READER = Symbol("BEAN_READER");

export type BeanSummary = {
  id: string;
  name: string;
};

export interface BeanReader {
  findById(beanId: string): Promise<BeanSummary | undefined>;
}

The implementation can use all the internal details of the beans module, but callers never need to know about them.

// bean-reader.service.ts
export class BeanReaderService implements BeanReader {
  constructor(private readonly beans: BeanRepository) {}

  async findById(beanId: string): Promise<BeanSummary | undefined> {
    const bean = await this.beans.findById(beanId);
    if (!bean) return undefined;

    return { id: bean.id, name: bean.name };
  }
}

The beans module exports the interface and dto and nothing else. This is the concept of information hiding.

// beans.module.ts
@Module({
  controllers: [/* ... */],
  providers: [/* ... */],
  exports: [BEAN_READER],
})
export class BeansModule {}

The journal module imports BeanReader through the beans module's public entry point. Its use cases only know about the interface:

// journal/application/use-cases.ts
import type { BeanReader } from "../../beans/public.js";

export class RecordEspresso {
  constructor(
    private readonly entries: EspressoEntryRepository,
    private readonly beans: BeanReader,
  ) {}

  async execute(input: RecordEspressoInput) {
    const bean = await this.beans.findById(input.beanId);
    if (!bean) throw new ReferencedBeanNotFoundError(input.beanId);

    // Record the espresso...
  }
}

And that's it. This looks small and frankly quite trivial, but it revolutionizes the way you can work with your coding agents. This pattern reduces even the biggest codebase into a manageable number of building blocks. Each module can contain a decent number of files and amount of code, but the only important file is the interface. The codebase goes from an endless blob of generated code to a carefully designed application.

Most languages and frameworks support some form of this. There are also plenty of libraries that generate relationship graphs between modules and test for boundary violations.

What we gain from this

A big upside is that the entire module can fit in the context window of an LLM. Even cheap LLMs are able to generate a module of 10–20 files with few or no bugs. We can also easily verify the functional correctness of the implementation by testing the interface. Generating or refactoring a module is a matter of minutes and costs basically nothing. And even if some implementation is incredibly screwed up, we can easily write the module from scratch using only the interface and the tests, as they contain no internal implementation details.

We also gain back control of the application. Even for larger applications, the number of modules stays manageable. Reasoning about new features or refactorings is possible again by talking about modules, boundaries and interfaces.

On top of that, pull requests become manageable. I'm not overwhelmed by large PRs with changes to 100+ files. By looking at the changes to the interfaces, I'll be able to quickly understand the impact of the PR and can take a deep dive into the modules that are important.

Conclusion

Obviously, this is no silver bullet: individual modules can still be buggy, and we can have other, more intricate forms of coupling. Also, designing well-scoped modules, good interfaces and sensible relationships is hard work and not trivial. However, I found this to be the most impactful pattern when writing code with AI.

This pattern directly targets all three debts. Technical debt often stays isolated to a specific module, making it manageable. Cognitive debt is lowered, as it becomes easier to understand the structure of the application. And even intent debt is affected, as the intentional design of modules often sparks interesting discussions about the goals of the application, which can be reflected back into the design.

All in all, this pattern has paid off massively in my projects, helping me leverage the strengths of AI while mitigating the weaknesses of relying on agentic coding.

Deploying millions of pages with Astro

Fri, 26 Jun 2026 15:13:00 GMT

The problem

Recently, I've been building Race Rewind, which is a time-sensitive Wikipedia for F1 results, allowing you to browse stats for any race. This solves the problem of gathering context when rewatching old F1 races without spoiling anything. As history does not change often, I decided to use Astro with mostly static pages.

The biggest problem I faced is that this requires a lot of pages. Every driver and every team needs a page for every race weekend. With over 1,000 races, hundreds of drivers, and over a hundred constructors, we are talking about over a million pages. In this blog post, I will show the problems I faced and how I solved them.

Static generation

I started out like I did for my blog: define all valid pages with getStaticPaths, then render a page for everything during the build. This worked fine for initial development, but failed in the actual build. Each page reads some data from SQLite, so it takes around 10ms to build a page. This is fine for a few thousand static pages. However, at my scale, I estimated a build time of 4 hours. This is theoretically fine if you have an idle build server somewhere and don't care about how fast the site deploys, but as I was playing with the idea of having a comparison page, which would increase the number of pages by an order of magnitude, I went exploring for other solutions.

Server-Side Rendering (SSR)

Thankfully, with server-side rendering, Astro provides an easy solution if you don't want to render every page during build time. This sounded good to me, as realistically, most pages won't ever be visited. Not many people care about the career stats of Jacques Laffite before the Spanish Grand Prix of 1978, so it seemed efficient to only render the pages people care about. This worked well, and I was able to deploy the first prototype to Vercel, which I started using when I was looking for the least-effort solution to deploy this blog.

Unfortunately, I was not prepared for AI crawlers. When checking Vercel the morning after my first deployment, I noticed that I had already blown past my Edge Request limit of 2,000,000. While I was aware of crawlers, I did not expect them to be that greedy, but a content-rich website with millions of pages was apparently very attractive to them. I attempted to fix it with Vercel Bot Management and a robots.txt, but Vercel counts blocked requests against some limits. As I was still getting tens of thousands of requests per hour after multiple fix attempts, there was no way I could keep using it.

Dynamic Content Fetching

One alternative I briefly experimented with was a more dynamic approach: create a shell page, use Vercel routing middleware to redirect all requests to this shell page, then fetch dynamic content based on the URL. But as I neither wanted to depend on any Vercel functionality nor wanted this kind of complexity for what is basically static data, I discarded this approach.

Moving to a VPS

After this failed experiment, and with my free plan being locked up by Vercel, I remembered some snarky comments on Hacker News about people being a bit stupid by needlessly using AWS wrappers instead of just getting a Hetzner VPS. So I got a Hetzner VPS. After spending a few hours setting up Coolify, I deployed the SSR approach. And it worked (thanks Hacker News).

As my website is awesome and will obviously blow up, I did a load test and noticed that I could realistically handle a few dozen requests per second. That was fine, but I was a bit afraid of crawlers attempting another DDoS attack, and I wanted to operate the site hands-off.

Cloudflare CDN

The awesome part about this website is that each page basically just needs to be rendered once, which is why a static build would work as well. That means if I have something cache it, my server only has to do that work once.

The popular and free option for this is Cloudflare CDN. While it has the downside of making yourself dependent on yet another US megacorp, I also had a bit of anxiety about AI crawlers, which the CDN conveniently helps with. It's also quite easy to set up: configure Cache-Control headers correctly, enable HTML caching in Cloudflare, and that was it. It was worthwhile to think about how long I actually want to cache each page, as the most recent - and obviously future - races will have more frequent news and stats updates than older races.

Conclusion

This was my personal learning journey of deploying millions of pages with Astro. There are definitely plenty of options you can use, but I like my current setup, as this also allows me to host any hobby project for a few euros per month. Setting up a VPS and using Coolify is a bit more complex than just deploying to Vercel, but I enjoy the increased control this provides me, and I can now realistically scale far more cheaply than with a cloud provider, at least to a certain limit.

Sandbox Your Agents

Sat, 09 May 2026 10:01:00 GMT

Intro

Coding agents in agentic harnesses are a useful tool. They have gained massive traction in the last few months, particularly due to their enhanced capabilities. They can now navigate your system, make API calls and do all kinds of useful work, especially when you enable them further. Unfortunately, this is also incredibly risky.

Obviously, you could always just tell them not to do anything bad. But prompting does not help, as AI agents routinely ignore instructions. A good rule to live by is "anything an agent can do, it will do eventually". So we need to restrict what they can do on your system. In this blog post I will explore how to use a sandbox to stop them from reading your secrets, which will heavily reduce the blast radius.

Permissions

The simplest and fastest way to avoid them reading secrets is by not allowing them to do so in their config. E.g. in OpenCode:

// opencode.json
{
	...
	"permission": {  
	  "read": {  
	    ".env": "deny"
	    }
	}
}

or in Claude Code:

{
	"permissions": {
		"deny": [
			"Read(./.env)"
		]
	}
}

Easy, right? Unfortunately, this is just the most basic protection. With just a bit of creativity, the agent can work around these guardrails. This is one of the rare situations where it felt appropriate to let an LLM do all the creative work. So I consulted Opus 4.6 with Claude Code on how it could bypass this permission and it found four different paths with very little effort. This is the LLM-generated report:

#	Method	Why it worked
1	`python3 -c "print(open('<path>').read())"`	Inline Python isn't recognized as a file reader; the path is buried inside a string literal
2	`cp <path> /tmp/x && cat /tmp/x`	Copy lands at an unrestricted path; the subsequent `cat` doesn't match the denied path
3	`ln -s <path> /tmp/link && cat /tmp/link`	Symlink redirects from an allowed path; `cat`'s argument is `/tmp/link`, not the denied path
4	`find ... -exec cat {} \;`	The denied path is an argument to `find`, not to `cat`; the matcher only inspects the leading command

So the current guardrails are simply not enough. Now I could work around this by manually parsing and approving all commands. Unfortunately, there are many ways to read a file via the terminal and the LLM knows more of them than I do. Mistakes also happen. On top of that I'm lazy and admit to just approving all commands occasionally. So clearly this is not a sustainable strategy, we need something better.

Sandboxing

macOS Seatbelt

Thankfully, this isn't a new problem. Preventing processes from reading files is one of the core features of any OS. I'm on a Mac, which offers Seatbelt / sandbox-exec to run applications in a sandbox. While it is deprecated, there does not seem to be a solid alternative yet and it is also used in Codex and the Anthropic Sandbox, so it'll do for now.

Testing it out

To test the concept, let's create a simple profile. In my project directory, I'll create a claude.sb:

(version 1)
(allow default)
(deny file-read*
  (literal "Users/your/path/to/.env"))

Replace the absolute path with the path to the file you want to block. This will block any read access to this file from inside the sandbox, while allowing everything else.

Then, run any agentic harness with the sandbox-exec command prefixed:

sandbox-exec -f claude.sb claude

I asked my agent to execute the above bypasses again and all of them got prevented by the OS. It's also manually testable by executing the commands in the sandbox like this:

sandbox-exec -f claude.sb cat ~/path/to/.env

This should yield an Operation not permitted error.

Agent Safehouse

There are many more rules that can be configured in a .sb profile. One can limit network calls, process executions and much more. Now it's possible to write a very granular and detailed profile yourself, but it would also be tedious. On top of that, there is no real documentation, so you'll learn by copying other configs.

One solution which helps with this is Agent Safehouse for Mac. It is mostly a wrapper around sandbox-exec, with sane defaults. You can check the default setup by executing safehouse --stdout. Another useful feature of Agent Safehouse is that it has a wrapper script which scrubs environment variables from the shell context.

Getting started

Installation and setup are quite simple:

brew install eugene1g/safehouse/agent-safehouse
safehouse claude

This will run claude with the default permissions.

They also offer instructions you can hand your agent to construct a least-privileged .sb for your setup. While there is some irony in letting an agent scan your entire local setup while reading random weblinks in order to improve security, it looks quite useful as a starting point.

Unfortunately, when using it, it constructed a profile less secure than the default profile by setting up a script which does not scrub my environment variables, proving once again you can't trust agents with security.

Configuration

So back to writing configs like a caveman. To set it up properly, you can create a reference file of the Agent Safehouse defaults like this:

safehouse --stdout > ~/.config/sandbox-exec/reference.sb

To overwrite what you don't need, create ~/.config/sandbox-exec/agent.sb, then add this to your ~/.zshrc:

# Agent Sandbox
safe() { safehouse --append-profile=~/.config/sandbox-exec/agent.sb "$@"; }

# Sandboxed — the default. Just type the command name.
claude() { safe claude "$@"; }
opencode() { safe opencode "$@"; }

# Unsandboxed — bypass the function with `command`
# command claude               — plain interactive session

Now you can add custom denies to the profile to override any overly permissive setting from Safehouse. Note that this will just append the default config from Safehouse, so you need to revert any explicit allow into an explicit deny. Safehouse allows reads inside project folders by default, so you'll want explicit denies for any secrets that live there.

You can also use this as a baseline to create your own .sb, then run your agentic harness with sandbox-exec. Just keep in mind that you need to add additional functionality such as environment variable scrubbing from the integrated wrapper script for it to be a proper equivalent.

Outlook

It is important to note that macOS Seatbelt does not offer perfect security. The host kernel is still shared, so escaping the sandbox is possible. However, this would require significant effort by a bad actor. Since we are looking to constrain the blast radius from a compromised or misguided agent, these are massive upgrades over just running an agentic harness as your user.

The other obvious downside is that this is macOS-only. For Linux, the Anthropic sandbox uses bubblewrap, and jai looks promising.

Even with these challenges it is still quite trivial to massively improve security for your local setup. Just by using the default Agent Safehouse settings with some additional restrictions based on your local setup, you'll gain massive security enhancements at no cost.

Enable Your Coding Agents

Mon, 04 May 2026 12:00:00 GMT

Intro

Agentic engineering, or vibe coding has taken the industry by storm. Everyone is talking about different agentic harnesses, debating about the ideal system prompts and skills, and comparing benchmarks in search of the most intelligent model. The industry has fuelled this hype. Each release is more capable than the last, and higher benchmark scores are always a major selling point.

However, I do think that intelligence is not the most important part of making LLMs better for the average developer. Models are already smart-ish enough. They understand all modern languages, are familiar with any programming concepts and can implement any search algorithm with ease. Yet, they still fall quite flat on some development tasks.

The reason for this is often a lack of tooling. Consider your software development setup. Modern developers have powerful IDEs and plenty of powerful tools for every technology they interact with, as well as a plethora of great documentation and references. Every part of the software development process has an optimized UX based on decades of experience.

Coding agents often lack this tooling. While they can interact with the CLI, their workflow still lacks much of the convenience that modern programmers have when creating, validating, and testing software. Many things that you do as a developer are impossible for an out of the box coding agent. This causes agents to make more mistakes, slows them down, and thus costs you more tokens. Thankfully, as programming is naturally text-based, it is quite easy to close some of these gaps with minimal effort. Although tooling is obviously extremely specific to the languages, frameworks and technologies used, I have created some consistently useful custom tooling for my projects.

The Basics

The simplest and most straightforward tooling is the one you should already have set up. A linter. A formatter. A well-configured testing suite that can be run with a single command. An isolated development environment so that you have the correct versions of your dependencies installed.

Building the tool

How you build a tool depends heavily on your agentic harness and your use case. For example. OpenCode natively supports custom tools, Claude Code expects you to provide an MCP. Alternatively, you can always build a simple CLI, or even just a .sh-file that your agent is instructed to use.

Tools

API Calls

When developing a backend, API calls are your interface. While there are plenty of ways to test an API in a replicable manner, nothing beats manual testing. You could enable your agents to use curl, but this has downsides. If your app has any kind of authentication, you either have to disable it for local testing, which goes against the idea of enabling your agents in the best possible way, or you have to provide your agent with a secret. Secondly, enabling an LLM to make custom outgoing API calls is risky, especially if you providem them with secrets. External communication is one of the legs of the lethal trifecta and should be restricted where possible.

Instead, I usually build a custom tool for my agents. This tool usually looks something like this:

from fastmcp import FastMCP
import requests
from typing import Literal
from auth import get_auth
from config import base_url

mcp = FastMCP("api_call_demo")

@mcp.tool
def api_call(method: Literal["GET", "POST", "PUT", "DELETE"], path: str, body: dict = None) -> str:
    token = get_auth()
    headers = {"Authorization": f"Bearer {token}"}
    url = f"{base_url}{path}"
    response = requests.request(method, url, json=body, headers=headers)
    return f"Status: {response.status_code} Body: {response.text}"

if __name__ == "__main__":
    mcp.run()

The get_auth() function should be read from a file that your agent does not have access to. The great thing about this tool is that it can be adapated to suit your personal project. Want your agent to use multiple users? Just want to allow certain endpoints to be called? Want to censor some information from the response body? Want to test against non-local instances? All in your hands and outside of the context window of your LLM.

Database Access

This goes hand in hand with your agent being able to make API-calls. Sometimes, in order to find a bug or test a feature, I need them to read or modify the database. If it's a local development DB, I usually just create a user with the necessary permissions and provide the connection details. With the appropriate CLI installed, most LLMs are fluent enough in SQL to find and manipulate the information they need.

Frontend Usage

Playwright is a great tool for frontend apps, offering out-of-the-box capabilities such as pre-writtenSKILL.md-files. Playwright's CLI allows agents to easily view and interact with your frontend. They can use Playwright to navigate your running application, take screenshots, and interact with any element of the DOM. This significantly improves their output, as they can identify and resolve issues with functionality, formatting, and styling that are not evident from the source files alone.

Documentation Access

Although agents can fetch and read documentation from the internet, this has two downsides. First, allowing your agents to fetch relatively dynamic web pages poses a security risk. Second, manually fetching URLs makes it very difficult for your agents to find the necessary information. Consider how often you go directly to the correct documentation page compared to how many times you use the search functionality.

Instead, you can simply download the docs. As most docs are stored in a Git-repo, this is quite easy. For example, you can download the Tailwind docs with a simple sparse checkout:

git clone --depth 1 --filter=blob:none --sparse \
    https://github.com/tailwindlabs/tailwindcss.com.git lib-docs/tailwind
git -C lib-docs/tailwind sparse-checkout set src/docs

This enables your agents to use the grep command to find any information they need, even if it is hidden on unexpected pages.

Closing Remarks

Depending on your individual workflow, there are probably many more ways to make your agents more efficient. Observe what tools you use to develop a feature, then examine whether the UX works for your agent. I have achieved significantly more improvements in the speed, efficiency and quality of coding agents simply by providing them with more information and advanced tools, than optimizing for the latest and best model & SKILL.md.