In 2024 I heard for the first time people talking about "AI-friendly software architecture." At the time I didn't really see a need to change things. Fast forward to 2026; I'm using AI for most projects (hobby and professional work). And I noticed that I'm actually starting to design my codebase a bit differently.

Use bigger files

AI tends to work better on bigger files (~500 LOC). Just by the nature of how Claude Code and the like work, switching between files requires summarizing and linking them. This is usually done via a sub-agent and is one reason why Claude (and other agent-based LLM tools) take so long before they actually start working. They have to build up a knowledge base first.

However, bigger files only work if everything in the file is relevant. For example, having CSS, JS, and HTML in one file is a really good approach for LLMs. Similarly, having interfaces together with the code that is using them is also very helpful.

This does not mean that you should stop splitting your files. If the LLM only needs parts of a file but can safely ignore the rest, then it should probably be moved to a separate file.

Import functions explicitly

For languages that support a more duck-typing approach (like JavaScript), you can lean into it by importing the functions of a file directly and not using the interface. This way the LLM knows exactly what functions exist and can infer the types based on its usage.

I'm thinking explicitly about JavaScript here. There are languages where this concept does not work at all. But I noticed that I can use the interface for type safety and explicit imports to tell the LLM what functions a file has. (In that case the interface does not need to be in the same file.)

Again, this technique does not work for every language or every paradigm. If most of your functions are methods of a class, then the only option is an interface. But for a more functional approach, where methods are mostly static and (depending on your language) can be imported without the class, this is a very viable option.

Add example code

If your interface is designed to be used in a specific way, then add a quick comment with a small example. It does not need to be working code; pseudo-code or plain English works as well. The idea is that LLMs should not start looking for examples. It should have everything it needs in one file.

Over time, the LLM will adapt the examples and add to them. But you should keep it small and short. Too many examples work against you, as the best example is the code itself. So ideally you only want to have examples for use cases that are not yet present in that file.