Ready for AI: Preparing your codebase for assistants

The hype around AI coding assistants is hard to miss

Tools like GitHub Copilot, ChatGPT, and various others are already helping developers write code faster, navigate unfamiliar APIs, and translate legacy systems. While these tools can feel magical, the results you get depend heavily on what you give them.

AWS CEO Matt Garman recently made headlines by calling the idea of replacing junior engineers with AI “the dumbest thing” he’d ever heard. Beyond the soundbite, he emphasised that the real value of AI isn’t in how many lines of code it produces, but in the broader ways developers can use these tools to create impact.  That impact depends heavily on the quality of the codebase itself and the practices that make a codebase effective for AI also make it far easier for humans to work with.

If your codebase lacks type annotations, meaningful tests, and clear documentation, even the most advanced AI coding assistants will struggle to provide accurate or useful support. The same is true for human developers; especially new team members or external contributors trying to navigate unfamiliar code. The good news is that with a few targeted improvements, you can make your codebase more understandable, testable, and maintainable for both AI tools and the people who work alongside them.

This blog outlines practical changes you can make today to get your codebase ready for AI assistance. These are low-effort, high-impact steps that help humans and machines alike and they’ll improve quality even if you never use an AI tool.

1. Add an AGENTS.md to explain what’s going on

Think of this as a README.md but written for an AI agent instead of a human developer.

Your goal isn’t to give a full system overview, it’s to give the AI the minimal context it needs to answer a question or generate working code. This can be incredibly helpful when using retrieval-based agents, or when copy-pasting chunks of your repo into a chat-based model.

What to include:

This doesn’t need to be long, 300–400 words are usually enough. The goal is to give the agent a head start.

2. Type hint your code

In dynamically typed languages like Python, functions can quickly become unclear, especially when it is not obvious what types of inputs they require or what they return. Type hints help resolve this by making those expectations explicit. Even when used selectively, type annotations provide meaningful context to both AI tools and human developers. They improve the accuracy of AI-generated suggestions, make interfaces more predictable, and reduce the time it takes for new contributors to understand and work with the codebase.

3. Add tests the assistant can run

Tests act as a form of executable documentation. A good test:

Even a small suite of pytest tests, written with real input/output examples, helps dramatically. The ability to “make this test pass” is one of the clearest prompts you can give an AI model.

4. Improve naming and local clarity

Descriptive function and variable names make a bigger difference than most people realise, especially for LLMs. Avoid generic names like tmp, data2, or foo.

Good naming conventions and local docstrings allow the assistant to understand intent, which is critical for generating changes that are correct and safe.

5. Reduce unnecessary indirection

Keep core logic in one place. Avoid heavy indirection, dynamic imports, and metaprogramming; these all make it harder for an AI to follow the flow of logic and generate useful suggestions.

For maintainability, clarity helps just as much as cleverness.

6. Add an end-to-end script or entry point

If your project has a well-defined entry point (whether it’s a CLI, script, or full application) it becomes much easier for AI tools to follow and extend the main workflow.

Files like run_pipeline.py, main.py, or a Makefile target make prompting far more effective. They’re also a best practice for onboarding and debugging, AI or not.

A quick word on the controversy

Before fully embracing AI tooling, it’s worth acknowledging the ongoing debate around these assistants.

Some of the key concerns:

That said, when used well, with strong quality controls, these tools can accelerate development, reduce boilerplate, and help teams maintain momentum. The goal isn’t to replace engineers. It’s to free them from repetitive, mechanical tasks so they can focus on high-value thinking.

Every team will need to decide its own boundaries but getting your codebase into a “LLM-friendly” shape is a net positive, even if AI generation isn’t used directly. It improves testability, readability, and maintainability; benefits that hold up with or without automation.

Final thought: Build for the team you’ll have tomorrow

Modern software development doesn’t just involve developers; it involves tooling, agents, automation, and collaboration across time zones and roles. The better your code explains itself through structure, naming, tests, and documentation, the easier it is to maintain and extend.

If you’re planning to integrate AI assistants into your development process, or want to future-proof a legacy codebase, these are some of the most accessible first steps.

Just as preparing your codebase makes it easier to work with AI assistants, energy organisations are also exploring how to get AI-ready. To learn more, download our free guide on Agentic AI in energy.