Controlled AI Coding: A Practical Guide for Dev Teams

Benny May 2, 2026 0 comments

The 6-month codebase problem

If you run a development team in 2026, you’ve probably already seen this movie. A developer ships a feature in two days that would have taken five. Everyone is happy. The PR gets merged. Three sprints later, somebody else needs to extend that module and finds 400 lines of code nobody fully understands — half of it generated, half of it hand-edited, none of it documented. The original developer says, “Yeah, I let Copilot handle that part.” The original Copilot session is gone. The reasoning is gone. What’s left is working code that nobody can confidently change.

This is not an AI problem. This is a discipline problem that AI has accelerated.

At Macronimous we’ve been writing PHP and JavaScript for clients since 2002. We’ve watched every productivity wave — frameworks, no-code, low-code, and now AI assistants — promise to remove engineering discipline from the picture. None of them have. What they actually do is shift where the discipline needs to live. AI coding is no different. The teams that will still be maintainable in 2028 are the ones treating AI output the same way a senior engineer would treat code from a junior who’s fast, prolific, and occasionally confidently wrong.

Why traditional discipline matters more, not less

There’s a tempting narrative that AI changes everything about how teams should write code. It doesn’t. The practices that mattered before AI matter more now, because the volume of code being produced has gone up while the per-line attention has gone down.

The four traditional disciplines we lean on hardest:

• Modular code review. A 50-line function reviewed properly is worth more than a 500-line file skimmed. AI makes large files cheap, which means insisting on modularity is more important, not less.
• Scheduled refactoring intervals. If you only refactor when something breaks, you’ll only refactor what’s already on fire. We refactor at sprint-end, every two weeks, before the debt compounds.
• Reusable component repositories. The oldest practice in software engineering — keep what works, call it when you need it. AI tempts teams to regenerate similar code from scratch each time. That’s how you end up with seven slightly different date pickers in one project.
• Documented intent. AI can write the code. It can’t write why you needed the code. That part is still on you, and it’s the part that matters in month seven.

The Code-Check-Refactor (CCR) loop

We organize our AI coding workflow around a three-step loop we call CCR. It’s deliberately boring. Boring is what survives.

Code — the AI-assisted writing phase. Cursor, GitHub Copilot, and Claude Code all earn their keep here. The developer is in charge; the AI is a collaborator, not an author. Generation happens against a clear, scoped prompt — a single function, a single component, a single migration. Not “build me the dashboard.”

Check — human review of every AI-generated block before it touches the main branch. This is non-negotiable. Two questions every reviewer asks: Do I understand what this does? and Do I understand why it does it this way? If the answer to either is no, the code goes back, regardless of whether tests pass.

Refactor — sprint-end consolidation. Every two weeks we set aside time to look at what was added, what duplicated existing utilities, and what should be promoted into the shared repository. This is when AI-generated sprawl gets compressed back into reusable parts.

How we actually do this at Macronimous

Specifics matter, so here’s the actual workflow our React and PHP teams run, not a generalized version of it.

1. Scoped prompts, not open-ended ones

We treat the AI like a contractor. Contractors get scopes of work. So does the AI. Instead of “build the user profile page,” the prompt is “write a React functional component that takes a user object as a prop and renders name, avatar, role badge, and last-login timestamp. Use our existing <Avatar /> and <Badge /> components from /shared/ui.” The narrower the scope, the better the output and the easier the review.

2. The shared repository is sacred

Every project has a /shared/ directory — components, utilities, hooks, helpers — that’s been written, reviewed, and battle-tested. AI is instructed to use these, not to regenerate equivalents. When a developer notices the AI has produced something that duplicates shared code, that’s a Check failure. The PR gets sent back.

3. Two-pass review on AI-heavy PRs

Any PR where more than 30% of the diff is AI-generated gets a second reviewer. Not because we don’t trust the first reviewer, but because AI-generated code has a particular failure mode: it looks reasonable. Two pairs of eyes catch the “looks reasonable but isn’t” cases.

4. Sprint-end refactor block

Last day of every sprint, two hours blocked. The team walks through what was added that sprint and asks three questions:

• What duplicates something we already had?
• What got hand-patched in three places that should be one utility?
• What’s complex enough that future-us will thank present-us for simplifying it now?

5. Commit messages that explain why

AI is great at commit messages that describe what changed. We require commit messages that describe why. “Refactored auth flow” is rejected. “Refactored auth flow to remove duplicate token validation between middleware and controller” is accepted. The why is what makes the code base navigable in month seven.

6. The “explain it to me” gate

Before any AI-generated code merges, the developer who wrote the prompt has to be able to explain the code without referring to the AI. If they can’t, they don’t understand it well enough to maintain it. Which means nobody on the team does.

Seven practical tips you can apply Monday morning

1. Set a “no main branch from AI alone” rule. Every AI-generated change passes through human review and a named human author on the commit. Not as a formality — as a record of accountability.
2. Build a prompt library, not a prompt history. Save the prompts that produced good code. Treat them like reusable assets. New developers should be able to read your prompt library and understand how the team works with AI.
3. Cap AI-generated PR size. We use a soft 400-line limit. Above that, the PR gets split. Large AI PRs are where review fatigue compounds and bugs slip through.
4. Tag AI-generated functions during review. Not forever — just during review. A simple // AI-generated, reviewed by [name] comment makes the second reviewer’s job easier and creates a temporary audit trail.
5. Run a duplication check before each sprint-end refactor. Tools like jscpd for JavaScript or PHP Copy/Paste Detector for PHP take five minutes and surface where AI has reinvented something you already had.
6. Write the test first when the AI writes the implementation. If you let the AI write both, you get tests that pass against the implementation rather than tests that prove the implementation is correct. Human-written test, AI-written implementation — that order.
7. Document the prompt alongside the code, not just the code. A short comment block at the top of an AI-generated module noting the original prompt and intent saves an hour of archaeology in month nine.

Uncontrolled vs. Controlled AI coding

Dimension	Uncontrolled AI coding	Controlled AI coding
Prompt scope	“Build the feature”	“Write this function with these inputs and these dependencies”
Review process	Skimmed if tests pass	Line-by-line, two reviewers on AI-heavy PRs
Reuse strategy	Regenerate from scratch each time	Shared repository of known-good components, called by reference
Refactoring	When something breaks	Sprint-end, every two weeks, before debt compounds
Documentation	“AI wrote this”	Intent, scope, and prompt context recorded
6-month maintainability	Original author needed; archaeology required	Any team member can extend or fix
Onboarding new developers	“Good luck”	Prompt library and shared repo are the orientation

The team audit checklist

Run this checklist on your team’s current AI workflow. If you can’t tick five of these, you have an emerging maintainability problem — even if everything is shipping fine right now.

• Every AI-generated PR has a named human reviewer who can explain the code without the AI
• The team has a documented shared repository of reusable components, and AI is instructed to use it
• Refactoring is scheduled, not reactive
• AI-heavy PRs (above 30% generated) get a second reviewer
• Commit messages explain why, not just what
• Prompts that produced good code are saved in a team-accessible prompt library
• There is a hard or soft cap on AI-generated PR size
• Duplication detection runs before each sprint-end refactor
• Tests are written by humans for AI-written implementations, not the other way around
• New developers are onboarded onto the team’s AI workflow as part of their first week

Frequently asked questions

The bottom line

AI coding is not the end of engineering discipline. It’s the beginning of needing more of it, applied differently. The teams that recognize this and build a controlled workflow — Code, Check, Refactor, sprint after sprint — will own maintainable, extendable code bases that compound in value. The teams that don’t will spend 2027 and 2028 untangling what they shipped in 2026.

The old practices weren’t outdated. They were waiting for a moment exactly like this.