AI generates code fast, but without structure it produces bloated PRs, unnecessary abstractions, and code nobody understands. I applied TDD as a framework for human-AI collaboration: one failing test, minimum code to pass, refactor, repeat. A guidelines file trains the AI to follow the cycle, and a set of context files give it project memory between sessions. The result: smaller PRs, faster reviews, real ownership, and predictable quality. The human thinks, the AI implements. At the end of the article you'll find an example of the guidelines I give the AI to work together doing TDD.

title: Red, Green, Refactor… and AI: How I Turned AI Into a Reliable Pair Programming Partner published: true description: AI generates code fast, but without structure it produces bloated PRs, unnecessary abstractions, and code nobody understands. I applied TDD as a framework for human-AI collaboration: one failing test, minimum code to pass, refactor, repeat. A guidelines file trains the AI to follow the cycle, and a set of context files give it project memory between sessions. The result: smaller PRs, faster reviews, real ownership, and predictable quality. The human thinks, the AI implements. At the end of the article you'll find an example of the guidelines I give the AI to work together doing TDD. tags: #TDD #AI #tui #bubbletea cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sjv97jp5kfj80p17kc8t.jpeg

Use a ratio of 100:42 for best results.

published_at: 2025-03-19 17:25 +0000

TL;DR

AI generates code fast, but without structure it produces bloated PRs, unnecessary abstractions, and code nobody understands. I applied TDD as a framework for human-AI collaboration: one failing test, minimum code to pass, refactor, repeat. A guidelines file trains the AI to follow the cycle, and a set of context files give it project memory between sessions. The result: smaller PRs, faster reviews, real ownership, and predictable quality. The human thinks, the AI implements. At the end of the article you'll find an example of the guidelines I give the AI to work together doing TDD.

Sound useful? Let's dive in.

More and more teams are integrating AI into their development cycle. But since it's still a recent technology for many, we don't always know how to turn it into a reliable and reproducible working method.

This article comes from a talk I gave at work, which was well received by over 250 developers from different projects (The Walt Disney Company, FIFA, Verizon, ...). The feedback I got, that it has genuinely helped them in their day-to-day, motivated me to put it in writing so it can reach more people.

I'm sharing a method I use daily with Claude Sonnet 4.6 as my AI assistant, and that has become reliable: a combination of TDD and AI assistance that allows tackling complex tasks in an orderly way, with the well-known benefits of TDD: reliable code, behavior-driven design, early bug detection, fast feedback, and confidence to make safe changes.

Most teams that adopt AI go through an exploration phase. They experiment, get excited, but stay there. What sets apart the teams that truly transform how they work is that they manage to move from experimentation to building habits, and from there to lasting adoption. This method is what allowed me to make that leap.

A Lot of Code, Little Value

I work with a team of over 50 developers. When we started using AI to generate code, the initial reaction was excitement. Features were delivered faster, PRs were flowing, and everyone felt productive. Until the code reviews and defects started piling up.

PRs were massive. Abstractions appeared that nobody asked for. Variable names were generic. And the most concerning pattern: developers stopped being able to explain their own code.

The AI generated it, I'm not sure what this part does

We had traded ownership for speed. And the codebase was paying the price.

AI Generates Complexity You Didn't Ask For

There's a concept in software engineering that Fred Brooks introduced decades ago: essential complexity vs. accidental complexity.

Essential complexity is inherent to the problem. Business rules, domain logic. It can't be eliminated. Accidental complexity is everything else: boilerplate, unnecessary abstractions, over-engineered configurations. It's introduced by tools, decisions, and, as we discovered, AI.

AI doesn't get tired. It doesn't bear the maintenance burden of the code it generates. It doesn't know your business domain. It optimizes for probability, not context. And it will happily generate 200 lines of code when 20 would suffice.

TDD: Giving AI a Bite, Not the Whole Plate

We didn't ban AI. That would be absurd. Instead, we changed how we work with it.

The answer was Test-Driven Development, applied in a way Kent Beck's original intent didn't cover: as a framework for human-AI collaboration.

TDD forces you to think before you implement. You define the expected behavior first, in a test. Then, and only then, you write the minimum code to make it pass. Then you clean up.

Red. Green. Refactor.

When you apply this cycle with AI, instead of asking it to "build a session manager," you ask it to write one failing test for one behavior. Then you ask it to make that test pass with the minimum code possible. Then you review, refactor, and move on.

You're giving AI a problem the size of a bite, not the whole plate. You don't try to transform everything at once. You stabilize one cycle and repeat it. And that's exactly what turns experimentation into a habit.

The Trick to Make It Always Work: The Guidelines File

AI assistants have no memory between sessions. Every new conversation starts from zero. So I needed a way to make the workflow reproducible.

I created a TDD_GUIDELINES.md file, a set of rules I feed to the AI at the start of every session:

• Always follow Red-Green-Refactor. Never skip a phase.
• Write only one test at a time.
• Implement only the minimum code to make the failing test pass.
• The AI must always ask about refactoring after green.
• The AI must not generate code beyond what the current test demands.
• The AI must not introduce abstractions unless explicitly requested.
• The human owns the design decisions. The AI proposes, the human decides.

This file evolved during our sessions. Every time the AI did something I didn't like (forgot to ask about refactoring, used syntax I find unreadable, hardcoded a magic number in a test) I'd say "add this to the guidelines." The file grew organically from real friction points.

Some examples of rules that emerged from practice:

• "Always use table-driven tests."
• "Doc comments must explain what and why, not restate the function name."
• "Avoid negation-based reassignment (e.g., x = !x). Use explicit if/else instead."
• "Tests must avoid magic numbers. Use values derived from the system under test (e.g., config.MaxRetries instead of 3) so tests remain valid when defaults change."
• "The AI must gently redirect the human back to the TDD cycle when the conversation drifts."

That last one is my favorite. I trained the AI to keep me disciplined.

What this file does isn't spectacular: it simply makes explicit what works. But that's exactly what allows the method to be adopted. Any developer can take these guidelines, start a session with AI, and get consistent results.

Giving AI the Memory It Doesn't Have

Guidelines alone aren't enough. The AI also needs to understand what you're building. I maintain a set of markdown files that serve as the project's memory:

• PROJECT_DESCRIPTION.md What the project is, who it's for, the philosophy, planned features.
• ARCHITECTURE.md Architecture decisions, package structure, key patterns. Permanent technical documentation.
• SESSION_HANDOFF.md Current development state: what we're working on, what's left, where to pick up. Updated at the end of each session so the next one starts without friction.
• TODO.md Progress tracking with ✅, 🔧, and ⬜ emojis. The AI updates it as we complete features.
• TDD_GUIDELINES.md And here's the key to everything: the rules of the game. The file that defines how human and AI work together, cycle by cycle.

When I start a new session, I point the AI to these files. In seconds, it knows the project structure, the patterns we follow, the conventions we've established, and what to work on next.

No ramp-up time. No "let me explain the project again." Just: "Read the context, let's continue."

A Normal Day in My IDE

A typical cycle:

Me: "What's the next item on the TODO?"

AI: "Implement email field validation in the CSV files."

Me: "OK, let's start there."

AI: Writes a failing test (RED)

Me: "It fails. Good."

AI: Writes the minimum code to make it pass (GREEN, of course you can also write the code yourself)

Me: "Tests pass."

AI: "Anything to refactor?"

Me: "Yes, extract that validation into its own function" / "No, next behavior."

And we repeat. Feature by feature, test by test. Each cycle takes 2 to 5 minutes. In a single session, we can implement a complete feature with full test coverage, clean architecture, and proper documentation.

But here's the key: I'm always in control. I decide what to test. I decide when the design needs to change. I decide when the AI is overcomplicating things. The AI is fast, but I'm the one steering.

And the Team... What Did They Say?

After adopting this approach:

• PRs got smaller and focused. Each one maps to a clear set of behaviors, defined by tests.
• Code reviews sped up. Tests document the intent. Reviewers read the test name and immediately understand what the code should do.
• Ownership came back. Developers define behavior before generating code. They understand every line because they drove the process.
• Accidental complexity dropped. When you can only write the minimum code to pass a test, there's no room for unnecessary abstractions.
• AI output became predictable. Same guidelines, same patterns, same quality. Every time.

Want to Try It? Some Tips

1. Create a guidelines file. Start simple. Add rules as friction points emerge. This file is your most valuable asset.
2. Give context, not just instructions. Acceptance criteria, project structure, conventions. The more the AI knows, the better it performs.
3. Use different instructions for Red, Green, and Refactor. Each phase has a different goal. The AI should behave differently in each.
4. Ask the AI to explain what it generated. If it can't explain it clearly, the code is probably too complex.
5. Track progress in a TODO file. Let the AI update it. It creates a shared sense of momentum.
6. Evolve the guidelines. Every session will reveal new patterns. Capture them. Your future self (and your future AI sessions) will thank you.

To Wrap Up

TDD turns AI from a wild, unrestrained code cannon into a precise instrument. The investment is small: a markdown file with rules, a few context documents, and the discipline to follow the cycle. The return is significant: consistent quality, real productivity, and code you actually understand.

Red. Green. Refactor. And AI.

TDD Guidelines for AI-Assisted Development

General Principles

• Always follow the Red-Green-Refactor cycle. Never skip a phase.
• Write only ONE test at a time. Do not batch multiple behaviors in a single test.
• Each test must fail before writing any implementation code.
• Implement only the minimum code necessary to make the failing test pass. Nothing more.
• Refactor only when all tests are green.

Red Phase (Write a Failing Test)

• The human defines the behavior to test, based on acceptance criteria.
• The test must be clear, focused, and test a single behavior.
• Run the test and confirm it fails for the expected reason.
• Do not write implementation code during this phase.

Green Phase (Make It Pass)

• Write the simplest, most minimal code that makes the failing test pass.
• Do not anticipate future requirements.
• Do not introduce abstractions, helpers, or patterns that are not strictly needed.
• Do not modify or add any other tests during this phase.
• Run all tests and confirm they all pass.

Refactor Phase

• Improve code structure, readability, or naming without changing behavior.
• All tests must remain green after refactoring.
• Remove duplication only when it genuinely improves clarity.
• Do not add new functionality during this phase.

Rules for AI Assistance

• The AI must not generate code beyond what the current test demands.
• The AI must not introduce abstractions, design patterns, or utilities unless explicitly requested.
• The AI must not add, modify, or skip tests on its own.
• The AI must explain what it generated and why, when asked.
• The AI should ask clarifying questions when requirements are ambiguous.
• The human owns the design decisions. The AI proposes, the human decides.
• The AI must not run tests. The human validates RED and GREEN phases.
• The AI must gently redirect the human back to the TDD cycle when the conversation drifts away from it.
• The AI must always verify and update import statements when adding references to external packages or symbols.

Error Handling

• Use sentinel errors (e.g. var ErrEmpty = errors.New("...")) instead of inline error strings.
• Tests must validate errors using errors.Is against sentinel errors.
• The wantErr field in table-driven tests must be of type error, not string.

Naming and Style

• Test function names must reference the function under test (e.g. TestNewSession), not the behavior. The behavior is described in each table-driven test case's name field.
• Keep tests independent from each other. No shared mutable state.
• Always use table-driven tests.
• Add doc comments to functions only after their implementation is complete, not during RED or GREEN phases.
• Doc comments must explain what and why, not restate the function name.
• Always use the comma-ok idiom for type assertions and map key lookups.
• Avoid negation-based reassignment (e.g., x = !x). Use explicit if/else instead.
• Unused function parameters must be removed. If the parameter is required by an interface, use _ to ignore it.
• Tests must avoid magic numbers. Use values derived from the system under test (e.g., config.MaxRetries instead of 3) so tests remain valid when defaults change.

Workflow Summary

1. Human defines the next behavior to test (from the TODO list)
2. AI (or human) writes a failing test        → RED
3. Run test → confirm it fails
4. AI implements minimum code to pass          → GREEN
5. Run tests → confirm all pass
6. AI must always ask about refactoring        → REFACTOR
7. Run tests → confirm all still pass
8. Repeat

Progress Tracking

• At the start of each TDD session, create or update a TODO.md file in the .tdd/ folder.
• Use ✅ for completed items, 🔧 for in-progress, and ⬜ for pending.
• Group items by feature or topic with a title.