My name is Juan and I work as the team lead for the cloudnative technology team in a company called banking circle. Mainly we are a global crossborder payments provider on top of accounts and liquidity management. We process over €1 trillion euro per year and we provide banking services to over 700 regulated financial institutions. More than 250 people in banking circle are building some type of technical systems and this includes the APIs that our clients are using. Because of that, we have decided to establish a platform that all of these teams can use so that we abstract away the complexity in some of the underlying infrastructure and cloud concerns. We call that platform Atlas.

Now we have come a long way in this platform engineering journey, but it wasn't always easy. Let's say that we have a new developer and they have joined the company. They build their first application but eventually they hit a wall. They have the code but they need to deploy that application somewhere. Then the developer will naturally ask someone in the team, hey, what should I do with this application? And then the person in the team might say, well, you know what? Actually, I did that, but it's already set in this pipeline. Why don't you copy it from there? The developer might go copy the pipeline. Maybe the pipeline will fail. And ultimately the developer doesn't know why it's failing because the error has nothing to do with the application that they coded. Maybe the teammate might say you should talk to this person that is working in the infrastructure team. Now this developer will go maybe they will talk with this person and eventually realize they also needed a database or maybe some blob storage. Back to square one. Maybe the person in the infrastructure team will say, I actually have a lot of other things that I'm working on. I will help you, but that's going to be next week. Obviously the developer will get frustrated because they kind of had done their part but then they struggled a lot in this process to then deploy the application and to get it running with all of the dependencies that it needs.

Now this is a bad situation that again I think all of us have been at some point. It's a bad situation for a person, but today all of us are using LLMs, we're using AI agents to help us in our daily job. And if this situation was tricky for a developer, this situation is essentially impossible for a machine because the machine is not going to, you know, go and try the pipeline and then go up to the second floor and talk to the person in that other team. A coding agent is not going to be able to do all of these things. So these pain points that the developers were facing suddenly become much more obvious when an agent is facing them and they are a limiting factor in how productive this coding agent can be or how productive the developer can be when using the coding agent.

The gist of it is that best practices are still best practices. We have known for a while that some of these things like relying on a teammate to tell us how to deploy an application or having to reach out to a person in a different team or having to wait for a pipeline only to realize that it wasn't exactly what we needed. They were never good. They are just much more obvious and perhaps much more painful now that we have these coding agents working next to us.

So what can we do about it? Well, the first thing to me it has to be self-service. If I need any resources from this platform, I should be able to do it on my own. Similarly, if my agent needs to be able to do anything on the platform, it should be able to do it on its own. There should be no process that requires talking to a specific person or waiting for a specific person to do something. Make it automatic, remove people from the process and make it easy to the greatest extent possible.

The second point is make it API based. Agents are good at calling well-defined APIs. It could also be a CLI on top of the API or something like an MCP server. Generally under all of that, you should have a well-defined API. This is discoverable, it has scheme validation, it also has authentication and authorization in place. With this the agent can go back and forth in a loop until it gets what it needs.

Which brings me to my next point: make it local first. Shift left as much as possible. If something is going to fail, it should fail as soon as possible. So don't make the agent push something to your version control system only to then fail on some workflow after a few minutes. If you can validate things up front, if you can run them just locally, do that. It is important that you give it precise instructions and tell the agent this is how you know you have succeeded at the task. Agents are not going to be looking at graphical interfaces. So make those logs, metrics, traces available via an API or CLI. By doing that, you're letting the agent close the loop.

Something that is crucially important is documentation. When we need to expose this documentation to agents, we need to be structured around it. One strategy is keep your documentation next to the code it's documenting. If you're working on something bigger, put it in a centralized place so that the agent can go there and start discovering. Think API first because the agent is going to be much better at consuming the specific bits of documentation that it needs over API.

Of course, when we talk documentation, we can also think about agent-specific documentation like the agent.md files or instructions.mmd depending on your agent of choice. You can tell it: well, you should always build in this way, test in this way, deploy in this way. On top of that, you can also use skills. If you have some conventions, you can codify those in a skill, which is again just a markdown document. By doing that, you're telling the agent when you do this type of task, you should do it like that. I would encourage a combination of guardrails thinking about security or compliance and then on top of that, use these markdown files to help the agents work in the way that you want them to.

The way of knowing if it works is by measuring. You can focus on Dora metrics: change frequency, mean time till recovery, lead time. Those metrics are measuring how often your developers are able to release and how good those releases typically go. You can also measure reliability. Or you might want to look at more platform specific metrics such as how many support requests have I got? If people and their agents can do everything on their own, am I then not needed to support them?

Maybe your organization has been resisting some of these best practices like API first platforms or to make them more local friendly or to have the time to write proper documentation. But then you have gotten some resistance because people were focused on other priorities. Take advantage. Everyone from the executive level to the individual contributors are looking at AI now. It is a very hot topic. So you can use AI as the excuse to implement some best practices that again were always best practices if you didn't have the chance to do it until now.