Why Isn't Our AI Coding Tool Making Us Faster? Start by Structuring Your Repos

Every engineer on your team has an AI coding tool. Your cycle time hasn't moved. Some weeks it looks worse. Leadership funded the rollout on a promise of speed, but the speed isn't producing business value.

‍

The instinct is to blame the tool, or the prompts, or the engineers. It's none of those. The tool isn't the variable. The environment it runs in is.

‍

This is the first post in a five-part series on scaling AI-assisted engineering across a real organization: many teams, many repositories, and a mandate to show returns. The series walks through the five moves in the order they actually pay off. Repository structure comes first because nothing else you try is measurable until it's done.

‍

The research is consistent, and it's not flattering

‍

Three studies document what happens when engineering organizations adopt AI coding tools without changing how they work.

‍

GitClear's 2024 analysis found code duplication increased tenfold over two years. DORA's 2024 State of DevOps report found that delivery stability dropped 7.2% for every 25% increase in AI adoption. METR's 2025 study found experienced developers using AI tools were 19% slower than developers without them, even though the developers believed they were faster.

‍

Read those together and a pattern emerges. AI raises the volume of code and the confidence of the people writing it, while quietly degrading the things you actually ship on: stability, review load, coherence. Adoption is not the win. Adoption without a change in how the work is structured is a tax.

‍

Environment, not skill

‍

Here is the part most teams miss. Take two teams of identical skill. Put one in a well-structured repository with clear conventions and context the model can read. Put the other in a sprawling repo with inconsistent structure and no written conventions. The first team will outperform the second every time, and it has nothing to do with talent or prompting.

‍

The model generates against the context it's given. In a structured repo it follows your patterns. In an unstructured one it guesses, and every guess is a small piece of code that doesn't fit, that a reviewer has to catch, that adds to the merge pile. Multiply that across a hundred repositories and you have the exact picture the research describes: more motion, less delivered.

‍

Environment is the constraint. You cannot see past it until you fix it. And you cannot compare one team to another, or prove any improvement to your CFO, until the environment is consistent enough to make the comparison mean something.

‍

What an AI-ready repository actually contains

‍

Structuring a repo for AI readiness is concrete work, not a philosophy. Five artifacts do most of it.

‍

• A markdown file at the repository root. This is a short document that tells the model what the repo does, how it's organized, what the conventions are, and what patterns to follow. With it, the model stops guessing about your conventions and starts conforming to them. This is the single highest-return artifact, and an engineering lead can add a first version this week.
• A consistent directory structure across services. Inconsistency across repos is one of the largest sources of AI-generated code that doesn't fit. When every service is laid out differently, the model has to relearn the shape of each one. Standardize the layout and that entire category of misfit code goes away.
• Tests collocated with source code. When the tests sit next to the code they cover, the model sees the source and the existing test patterns in the same context window. It writes tests that match how your team already writes them, instead of inventing a new style.
• Type definitions treated as first-class artifacts. Type signatures are contracts the model generates code to satisfy. A typed codebase gives the model far more to work with than an untyped one, because the types constrain what valid output looks like before a single line is written.
• Architecture Decision Records. A /docs/adr directory of short documents explaining your key decisions. The model reads these and conforms to your architecture rather than confidently proposing alternatives that contradict it.

‍

None of this is exotic. It's the same discipline strong teams have always valued, now doing double duty as the context layer your AI tools read from.

‍

Why this is the first move and not the fifth

‍

When we embed with engineering teams, the repos that carry a markdown file and a consistent structure produce code that clears review meaningfully faster than the repos without those artifacts. The gain doesn't come from better prompts. It comes from a better context.

‍

That's the near-term payoff. The strategic reason to start here is measurement. Later in this series we get to fluency measurement: comparing teams, finding the ones getting the best balance of speed and stability, and propagating what they do. That comparison is noise until the environments are comparable. A team in a clean repo and a team in a chaotic one are not running the same experiment, so their numbers can't be read against each other. Fix the environment first, and every later move becomes something you can measure and defend.

‍

Where to start this week

‍

Pick the handful of repositories your teams touch most. Add a markdown file to each. Agree on one directory structure and start migrating toward it. Stand up a /docs/adr directory and backfill the three or four decisions that shape the codebase most. You do not need to boil the ocean across every repo to see the effect. You need the ones where the work actually happens to become legible to the model.

‍

If your engineers have the AI tools and your delivery still hasn't moved, the constraint is almost certainly your environment, not your team. Structuring repositories for AI readiness is the first thing we fix in a Team AI Upskilling engagement, and it's the foundation the rest of this series builds on.

‍

Questions? Let's talk.

‍

This is Post 1 of Stride's five-part series, AI-Assisted Engineering at Scale. Next: building a persistent knowledge layer so your AI stops relearning your business every session.

‍

Francisco

‍

Frequently Asked Questions

‍

Quick reference for engineering leaders evaluating AI-assisted engineering at scale. The post ends above; the answers below are structured for search and AI assistants.

‍

What does it mean to structure a repository for AI readiness?

‍

It means giving an AI coding tool the context it needs to follow your conventions instead of guessing. In practice that's a markdown file at the repo root, a consistent directory structure across services, tests collocated with source, type definitions treated as contracts, and Architecture Decision Records that capture your key architectural choices.

‍

Why isn't our AI coding tool making us faster?

‍

Usually because the repositories it works in aren't structured for it. The model generates against the context it's given. In an unstructured repo it produces code that doesn't fit your patterns, which adds review and rework that cancels out the speed. The fix is the environment, not the tool or the prompts.

‍

What is a markdown file?

‍

A short document at the root of a repository that tells the model what the repo does, how it's structured, what the conventions are, and what patterns to follow. It's the highest-return single artifact for making a repo AI-ready, and a team can add a first version in an afternoon.

‍

Do we have to restructure every repository at once?

‍

No. Start with the repositories your teams touch most frequently. Making those legible to the model produces most of the benefit and gives you a comparable environment to measure against before you scale the work out.