Practice what you Preach

I'm the maintainer of the Python tools for the Polylith Architecture, that adds useful tooling support for teams having their code organized according to the Polylith Architecture. So far in 2026, I have made seven Feature releases (i.e. minor versions) and a bunch of smaller ones (i.e. patches).

One of the features that was added this year is the possibility to inspect the coupling between individual parts of the code. In Polylith, code is logically grouped into something called bricks. For Python, these are what we know as namespace packages within the same repo.

Each package has an __init__.py, and you can define the interface of the package there. This is optional, and it is perfectly valid Python to access the modules within a package directly. In Polylith, a stricter approach is recommended: explicitly define the things that should be exposed outside of the package (aka brick).

      from my_package import my_function

      __all__ = ["my_function"]
    

The new feature is exactly about this: visualize and validate the usage of brick interfaces across the repository. With a simple command, you will find out if code is bypassing the explicit interface of a brick. This is still optional, and as long as it is valid Python you can safely ignore this. There's benefits of having code that interacts via explicit interfaces, such as refactoring - it's very easy to move code - and low-risk of breaking things when changing the code within the brick.

      # the existing command visualizing coupling between bricks
      poly deps

      # the addition, that will inspect the brick interfaces
      poly deps --interface

      # or inspect a single brick
      poly deps --interface --brick the_brick
    

Vizualize coupling, bypassed interfaces or circular dependencies.

What about circular dependencies between bricks?

Remember, a brick is a namespace package and that means that it is on a level above the individual Python modules. It can be valid Python to have two packages depend on each other, if the imports are for different modules in the packages. But this is an indication that something might be wrong with the Design. I would even go so far calling it a Bug. Two packages that import code from each other could be refactored into three, where the shared things are in a separate package. This is how the Polylith tool identifies circular dependencies between the bricks. The same command as for validating interfaces is used for this feature (poly deps) and it will inspect the code in the entire repo, to look for any circular brick dependencies. The interface lookups and the circular dependency checks are both internally using the builtin AST parsing.

Control your Agents

Many teams use agents today during development and knowing that agents can produce a lot of code in a fast pace, these two features are very useful if you want to avoid any unexpected side-effects of importing Python code without clear boundaries. Agents can use the poly tool too, just like when doing linting and testing. Static analysis is a great thing to have in the Agentic Engineering toolbox. The Polylith tool includes agent skills, so your agent will understand how to use it.

Practice what I Preach

I knew from before that the source code of Polylith tool bypassed interfaces in a couple of places, but I thought this is fine since it is valid Python. But I realized that my future self will thank me if these risky parts are fixed now and not later. Also, it is good if I actually practice what I preach being the maintainer of the Polylith tool for Python. So I fixed that. In addition, I also learned that two bricks in the repo had circular dependencies caused by a recently added feature. In this case, it was a circle of several bricks that initially made me worried. But the solution was simple: move the parts that caused the circularity into a different brick. I already had an existing brick that made sense to host the couple of Python functions that caused the circular dependency.

After refactoring: no interface violations, no circular dependencies.

Related posts and resources

• post: An Agent- and Human-friendly Architecture
• repo: the Python tools for the Polylith Architecture
• docs: the Python tools for the Polylith Architecture

^{Top Image generated by Mistral AI with modifications by me.}

Reflections: 6 months of Agentic Engineering

As many developers today, I'm using agents on a daily basis for software development. At work, we went all-in Agentic Engineering in early 2026 and for me it has worked well.

Not perfect, not 10x, but well and the shift was surprisingly easy. I quickly found that good coding practices are still applicable and relevant. I’m not into that vibe coding stuff, I care too much about the output. What has been occasionally overwhelming is the uncertainty about The Next Step - just like many developers out there I have thought about how we, the Humans, will keep up with the speed of the Agents?

Here's some reflections after about six months of developing software according to Agentic Engineering.

Human reviews have not become the bottleneck. From my experience, human reviews was a bigger bottleneck before Agentic Engineering. We have made efforts in our Team to improve the review flow, to avoid the need of constantly reminding people to review and approve changes. We have made the review process itself more efficient than before.

For me, the ratio of Development time vs Planning and Reviewing is about the same as before. I find myself designing and developing solutions the same amount of time as before the agentic era. In the beginning, I thought it would be the opposite!

I haven't run into the problem of having my agents produce hundreds of pull requests on a daily basis. I know there are people out there doing amazing stuff over the weekends with agents, but I'm not one of them. I haven't yet found a need to rebuild an existing SaaS tool from scratch with AI.

Quality is important. I think it is even more important than before, because an agent will be confused by complex code. Not only that, it will likely produce code that is equally complex (there's research about this available). This will be a downward spiral. Here's where Agentic Engineering is different from Vibe coding. A vibe coder treats the code, the output, as a black box. The risk with that is software that is very difficult to maintain. An agentic engineer keeps their eyes on the incremental result, and steer the agent during the process. The Human decides what Quality is, what is Readable code and what is Simple code (just like before).

Static analysis tools are a great to have in the agentic toolkit. Linters and Unit Tests are as important as before. I have added tooling that reports on complexity and readability issues, and use the Code Health MCP for that. Without the need of human interaction, the agent will verify its result while working and adjust it until the score is healthy before it reaches my eyes. Having static analysis tools doing this kind of work instead of an AI will reduce token spend. Reducing spend will be important in the future as the cost of tokens likely will increase.

Always bet on Open Source. Back in the days, as a .NET developer (when it was closed source and Windows only), developers were heavily dependent on Microsoft. Not only for the framework, but also for most of the tooling. I don't want to go back to that era, and see the same kind of vendor lock-in pattern with the AI providers of today. My tooling of choice is Emacs and the provider-agnostic tool Eca. When Anthropic has its downtime issues, I just switch to Gemini and can seamlessly continue while my colleagues at work are frustrated and post Claude is Down memes.

After six months, I still have a skeptic view on agents and LLMs in general. I simply don't trust the output. But at the same time, Agentic Engineering has made my workflow more efficient and I can more confidently step in to developing things outside of my comfort zone.

Related posts

• Agile and Agentic Engineering
• The tools of an Agentic Engineer
• A workflow for Agentic Engineering
• An Agent- and Human-friendly Architecture

^{Top Photo by me from Hoburgen, Gotland in Sweden.}

An Agent- and Human-Friendly Architecture

"Software Architecture in the agentic era?"

What's needed for an architecture to fit well in the agentic era? Probably many things, but I would say at least simplicity and available context as two very important things to consider. Even if it for sure was not the purpose from the beginning (it was born many years ago), Polylith is about that and is a good choice for Agentic Engineering. That's a nice side-effect of keeping things simple and having all necessary context at your fingertips, which is the guiding star for this software architecture.

A year ago, agent-friendly architectures was not something I had thought about at all. Today, a lot of things has changed. But many ideas about good software remains valid.

If you haven't heard about Polylith, here's an elevator pitch: the main use case is having Microservices in a Monorepo, and share code between the services.

It's an architecture with useful tooling support and great development experience for both humans and agents. All of it Open Source. I'm the maintainer of the tooling support for Python, and teams can use it with their favorite existing tools (such as uv, poetry, pdm, pixi, maturin, hatch). The Polylith tool also includes a set of agent skills, that will add knowledge about Polylith in general and the available commands to your agent. Recently, I also added skills that are specific for migrating a single-repo Python project into a monorepo. I hope that this will help teams to more easily start using this way of structuring code.

The code in a Polylith monorepo is basically building blocks, just like LEGO bricks. Some bricks are small, some are bigger and some are a combination of other bricks. All code lives in a well-structured Monorepo (without symlinks or complex custom setups). The code is organized into smaller reusable parts with clear boundaries between them. The tooling will notify if these boundaries are bypassed or if references are circular.

LEGO bricks and code, what's the connection? In Python, a file is a module. One or more modules in a folder is a package. One or more packages can be combined into a feature. In Polylith, this is called bricks. There are two types of them: components and bases. Components are the main building blocks in Polylith. This is where the business logic lives, the actual features and functionality. Bases are the entry points to your apps or services. A base should ideally be thin, and delegate the business logic to components.

Microservices are great, but the standard setup can introduce new problems: code in many places, duplications, shared code as libraries (that means even more repositories) and different versions of everything. That can be a lot of things to maintain, for agents too.

With a monorepo structured as a Polylith, the agents will have all the necessary context in one single place. It's right there! Agents perform better when things are simple, very much like us humans do. Besides having all needed context, an agent can also use the Polylith tool just like a human would. This will save tokens, and likely speed up the development process even more. The agent skills of the tool will tell the agent how and when to use it. Having all code there at your fingertips is also great for Test & REPL Driven Development, making coding both joyful and interactive.

Link to the Python tools for the Polylith Architecture repo.

^{Top Photo by Mitchell Hartley on Unsplash}

Refactoring with AI?

With Agentic Engineering there's an opportunity to refactor legacy code, but this aspect of AI isn't that that much talked about and seems to be overlooked by teams out there. So far, the main thing with AI and agents has been to build new things in a fast pace.

After several months of practicing Agentic Engineering, I've realized that code quality - or code health - is more important than ever. Agents get confused by complexity, just like humans. You've probably seen it (I have too) and now there is also research backing it up. Keeping code simple is a good guideline also in the agentic era.

This is where I believe the Polylith Architecture is a good fit, for both humans and agents. The original idea of Polylith was to keep things simple and great Developer Experience for Humans. As a nice side effect, Agents will probably like this setup too. An agent will have the context it needs to build new features from the existing well-organized code in the Monorepo.

Since before, the Polylith tool for Python includes a set of agent skills about the commands and about Polylith in general. But what about migrating an entire existing single-repo project into a Polylith Monorepo? With AI, many steps could be automated here.

I recently added additional skills to the Polylith tooling that are focused on migrating and refactoring an existing Python project into an Agent friendly Monorepo. The migration skills handles the extracting of application code, restructuring and also refactoring of large components into smaller ones.

The agentic flow for the migration of a project is:

1. discover
2. analyze-imports
3. extract-to-base
4. update-imports
5. prepare-project
6. verify-stability
7. isolate-base-and-big-component
8. split-big-component
9. extract-standalone-modules
10. isolate-shared-and-project-logic
11. distribute-wiring
12. split-component-internals
13. refactor-tests
14. definition-of-done

Also, the project-specific tooling (such as Project & Dependency management, linting and type checking) is migrated and converted according to what’s already in the monorepo.

Example: you use uv and ruff in the Polylith Monorepo, and migrate a project that uses Poetry and flake8. The migration will convert those to uv and ruff.

I have tested the skills with Claude (Opus 4.7 and 4.8) and Mistral (mistral-large and devstral). One of the tests I ran was converting the FastAPI repo (just for fun and to test the skills out) into Polylith.

my migration prompt

In this repo, there is @./.agents instructions about the Polylith Architecture and the "poly" tool. There is also migration instructions, and those are important here. I want to migrate the project #./project/fastapi according to the migration instructions.

Before running the prompt, I copied the contents of the FastAPI repo into the Polylith projects folder. I also removed the existing .git folder in there, to avoid any confusion during the agentic work.

Hint: the more unit tests the project to migrate has, the better!

The skills are part of the polylith-cli, and you can copy the contents of the .agents file or use a tool like library-skills to add them to your monorepo. Agents are unpredictable and different models behave differently. If you decide to try this thing out, please let me know how the skills works for you.

You'll find info about Polylith for Python here.

^{Top Photo by Blend Archive on Unsplash}

A workflow for Agentic Engineering

"- Claude, build the entire Platform from scratch. Make no mistakes."

In the agentic engineering community, some think that 100% test coverage will guarantee the quality of generated code. I think that relying too much on automated tests is problematic, because testing is difficult. I'd rather review the actual source code. More importantly, having an active part in the development of it by steering the agent(s) in real time.

I usually develop a feature step by step, to not focus too much on upfront planning. I used to do this before the agents joined the development process, and have found that it works well today too. When beginning with a new task, I often have some clear ideas and some vague ideas about how to solve the problem. By starting with the things that are clear, I can postpone thinking about the implementation details of the more vague parts of the overall feature. I can worry about that later, when I have learned more. During the development, the how and what to implement will likely change. This is a natural thing, as you learn more along the way and understand more about the actual problem to solve. I guess this is the basic idea behind Embrace Change (from the Agile Manifesto).

I haven't yet felt any need to set up larger Agent Orchestrations for the kind of problems that I solve. It mostly seems like overdoing it, doesn't it? I don't know about you, but we are not building or reinventing an entire E-Commerce or Social Media platform every day. The things we do is on a much smaller and human-friendly scale. I think the idea about 100% test coverage might be about scaling up fast and the assumption that agents will produce so much code, that it becomes impossible for humans to grasp.

An Example

I recently developed a new feature that involved several repos, a combination of Python backends and Next.js apps. I decided to do this in smaller steps and began with the most straightforward step, which in this case was one of the backend services that I already know well. I had a pretty clear idea on what needed to be changed in there and added a simple Solution Design into the ticket.

For context: I used the same ticket for all the development of this particular feature. Each plan an agent produced was submitted as a comment to the ticket. I have automated this with an MCP server connected to the issue system that we currently use at work. It seems like having the relevant data collected in the ticket made the upcoming tasks clearer for the agent(s). Each task begun with a new context, but I instructed the agent to read the ticket that contained the problem to solve, the solution design, previous plans and linked pull requests before planning how to implement things.

It felt like things went pretty smooth. However, the very first task needed several iterations. I realize now that even if the basic setup of that particular repo was straightforward, the service has evolved over time and the structure of it has diverged. I think this is quite common in long-lived repos. This confused the agent, so I practiced the stop-the-line principle by rejecting generated code, correcting and steering the agent in real time. I did this when I noticed that the implementation (the code) went into a direction I didn't like. My agentic tool of choice, Eca, recently added support for a new steer command that is very useful for this kind of workflow. You can change the direction, or steer, while the agents are working. It is not always necessary to halt all ongoing work, sometimes a friendly nudge in the right direction is enough.

Sometimes, unexpected things happen: the other day, the main model I use was unreachable about half the day (again). Oh no. But I just switched to a different provider and continued the work! This is another thing where an Open Source and Provider-agnostic tool like Eca shines.

Another thing that I noticed was that the short summary the agent produced for each Pull Request covered the whole feature and the particular details pretty well. The data in the actual ticket was probably helpful for this kind of task too.

I've been advocating Test Driven Development (TDD) and the sibling REPL Driven Development for many years. The real-time steering, the stop-the-line principle with origins from The Toyota Way could be an Agentic Engineering version of the Test Driven approach. It's about fast feedback loops. What do you think?

^{Top Photo: that's me pretending to do something important on the cell phone, taken at Åreskutan, Jämtland, Sweden.}