Avoid AI code drift with small, well-defined steps 🐢

AI-generated code often looks impressive at first, but then it drifts: it ignores conventions, duplicates logic, breaks architectural constraints, and assumes things that aren’t true.

To control this code drift you need to make AI take small, well-defined steps.

Prefer small, well-defined steps #

Small steps help AI stay aligned with the current codebase. With small steps, the model has concrete anchors: visible surrounding code, naming patterns, imports, function signatures, tests. It can pattern-match effectively.

With large steps, those anchors become sparse, and the model starts filling gaps with statistically plausible but project-inaccurate constructs. The larger the step, the greater the drift.

Reduce drift further by clearly defining goals and boundaries.¹ Tell the AI exactly what it should and should not change. Open-ended tasks widen the search space and increase drift.

For some changes, like a big feature or global refactor, a large step may seem necessary. But even then, it is likely better to ask AI to generate a “big plan” and then execute that plan incrementally. Or to experiment with various big steps to get inspiration, but then revert and execute one of them carefully.

Why this happens #

AI code agents are based on autoregressive models—they predict the next token based on the previous ones. They optimize for locally plausible tokens, not global consistency. Without tight constraints and rich context, large steps force the model to invent structure from generic patterns rather than project-specific conventions.

This explains the focus on prompt and context engineering. Results become better when you load things like nearby code, project-specific APIs, and naming conventions. Bad context will cause drift regardless of step size.

Code quality still matters #

In one sense, AI is not special. Keeping a codebase from drifting has always been hard.

Long-lived software projects often see significant architectural drift, where the codebase slowly diverges from the intended architecture. Similarly, we often experience scope creep, where the work performed expands beyond the original plan.

The difference is that while humans can write bad code slowly, AI can do it at scale.^2,3

Ironically, it seems that the qualities that make code easier for humans to understand are the same that help AI perform better. You need solid architectural principles, clear concepts, consistent style, and good naming. What the AI will give you is a best-effort copy of the code it sees. If the existing code is inconsistent, don’t expect the code generated by AI to be any better.

What can you do? #

How can you help the AI stay on track and minimize code drift?

First, you need to put effort into the instructions you give to the AI.

• Require a plan. Ask for a step-by-step plan before generating code. Execute each step separately. This helps the AI stay on track during the change. The explore, plan, code, commit workflow is a common recommendation.
• Constrain the search space. Provide boundaries such as “do not add dependencies”, “preserve public APIs”, or “touch only files X and Y”.
• Provide idiomatic examples. Refer to 2–3 high-quality snippets from the codebase as style anchors.⁴

A good basic approach can be that you design components, interfaces, data structures, and function signatures but let the AI fill in the implementation.

If signs of drift appear, such as unexpected dependencies or patterns, stop and revert.

Next, follow up on the code that is generated.

• Review and adjust. Make sure you understand every line of code written and can vouch for it. Don’t blindly accept the generated code, or you’ll be generating instant legacy code.
• Automate quality checks. Run linting, tests, and a duplicate-code scan. The sooner bad code is detected, the better. Ideally, the AI agent can detect and fix violations by itself.
• Use TDD to enforce small steps. Test-driven development forces incremental change and naturally allows the AI to validate each step before drift accumulates.
• Continuously refactor. Keep the codebase consistent and well structured, for the benefit of both humans and AI agents.

AI code drift is inevitable, but small, well-defined steps keep it bounded and correctable. Generate incrementally, validate continuously, and refactor often to stay aligned.