
Every day, developers complain that AI assistants write terrible code, miss obvious bugs, or spiral into endless loops. Meanwhile, I'm shipping production features faster than ever with the same tools. It took me months to realize that working with AI isn't about better prompts—it's about applying the same collaboration skills I use in pair programming.

Today I’d like to share 10 AI-driven development heuristics that I’ve been using over the last few months to build real world production grade software that real users are using today.

Before we get into it, let me provide some definitions, disclaimers, tools, and context.

## Definition

Heuristic — practical approach to solving a problem when finding the perfect solution would be too slow, complex, or impossible

## Disclaimers

_I am using "heuristics" loosely here to cover rules of thumb, workflows, and practices_

_You may be using different coding agents, so some of this may or may not apply to you. I’ve tried to keep this general, but I’m [just sharing](https://justsharing.dev/)._

## Tools

- Claude Code (I will refer to this agent as Claude, it, or bot)
- Webstorm (my IDE of choice)
- Git (frequent commits, because bots can mess things up quickly)

## Context

I gathered all of these heuristics while delivering user stories for an actively used product. These are not necessarily the same heuristics I use when [vibe coding](https://simonwillison.net/2025/Mar/19/vibe-coding/) on a personal project.

## 10 heuristics

### 1. Stop the bot when it starts to wander and gets lost

After prompting Claude to introduce a small increment of functionality, I continue to pay attention. I read almost everything it’s doing, thinking, planning, and pondering. Instead of treating Claude like a worker bee, I treat it as my pair. We’re collaborating to reach an optimal solution that works and is easy to extend.

Over the course of this reading, I sometimes don’t agree with specific approaches Claude decides to take. I press the `esc` key and inspect even further. Pressing the `esc` stops the bot. This gives me time to read the same files Claude is reading and determine what I think the best approach is. Sometimes I realize that it’s taking the right approach and tell it to continue. Claude will pick up right where it left off as if I never stopped it at all.

Other times, I see a better way of approaching the problem or the root cause of the error. Instead of just telling Claude to continue, I will relay my findings to it. This usually results in Claude’s favorite saying, “You’re absolutely right!”—and it reevaluates its task list and continues with the new information in mind.

![Stopping Claude Code](/images/stop-claude-code.png)

Instead of waiting for Claude to finish the whole solution, I actively review its thought process. This is a habit I’ve picked up from many years of pair programming. I always want my pair and me to be on the same page and well aligned with the path we’re taking. While pairing, it’s common to stop and talk about what’s happening, where we’re going, and if that’s still a sensible direction to go. These constant check-ins save a lot of time and are part of the work. This is collaborative engineering. I’ve brought this collaborative spirit to my interactions with Claude and found it to be incredibly rewarding

### 2. Find the issue myself

One of the biggest arguments against using coding agents is that they get stuck in loops when trying to debug and investigate tricky bugs and errors. I’ve experienced this myself, but it’s not just Claude solving the issue—it needs my input and assistance too! I will give Claude 2–3 chances to find the root cause and resolve the issue before stopping it and investigating myself. This happened just the other day.

Claude and I were adapting an LLM test to use [Test Containers](https://testcontainers.com/?language=nodejs) instead of a locally running MySQL instance. It seemed like everything was set up correctly, but when adding the next test that would trigger reading the test data, the tool call of the Chat Assistant failed. So I put told Claude to fix it and make the test pass. It added tons of logs and tried an array of different things, but it couldn’t tell me why the test was failing. After a few rounds of this, I stopped Claude and investigated the issue myself.

I set up breakpoints in WebStorm and finally got to the root cause of the problem. Any reads that the function calls made were not targeted at the correct MySQL instance. The app was set up in a way that on startup the database connection was initialized. When running these tests, we wanted to use only the Test Containers database. Now that I knew exactly what the issue was, I relayed it to Claude, and it pursued several different solutions.

Unfortunately, I had to bail on the Test Containers approach because of how this monolith was structured, and we could not justify refactoring it to make it easier to substitute databases on startup. However, the point here is just telling Claude to fix the issue is not enough all the time. For more complex issues, a human getting involved and detecting the root cause is less expensive both in time and token costs. Most times, once Claude understands the issue, it’s able to engineer a working solution.

### 3. Extended Thinking Modes

This mode costs more, so I use it pragmatically. Here are a few situations I will trigger the thinking modes:

> After Claude has failed a task once, and it seems to be getting confused...
> <br/>this usually gets it back on task and either leads to a solution or helps me to discover the issue for Claude

> On an initial prompt that seems very complex and I want Claude to use as many of its resources

> Before embarking on a complex task, I may prompt Claude to think and plan and discuss different options

I usually start with think hard and go to the higher thinking modes on later prompts if needed. Like humans, coding agents perform better when they track their thought process. Thinking aloud is a crucial part of pairing, so a mode like this makes it even easier to pair with Claude.

All you need to do is say the 'magic' word somewhere in your prompt. "Each level allocates progressively more thinking budget for Claude to use." — [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)

The modes are:

- think
- think hard
- think harder
- ultrathink

### 4. Ask me questions

Sometimes, at the end of an initial prompt I will tell Claude to ask me any clarifying questions if needed. The phrasing here is important. If you tell Claude to ask you questions, it will do so, and they may be silly and unnecessary questions that it could explore on its own using its many tools.

Some reasons why I tell Claude to ask questions are:

- to give it any missing information it needs to solve the problem
- to explore different solutions
- to gauge whether Claude understands the task at hand

It can be tedious to answer all the questions. I usually skip questions that are not relevant, but it can help get it and I aligned on the task.

### 5. Claude the student

Coding agents can do some amazing things for professional programmers, but they need to be mentored along the way. I continually educate Claude on how to iterate towards maintainable software. We debate each other on Object-Oriented principles, DDD, refactoring, and iterative development. Coding agents are willing pairs that will conform to your style, but you must be patient and repetitive. I store learnings in a directory of .md files that I have a custom command for. After a session and before clearing or compacting, I can export all of my teachings of how I approach programming to an .md file that Claude can reference in a future session. This way the learning doesn’t get cleared out, and Claude can continue to grow as we pair together.

### 6. Working → Maintainable

After the code works, I don’t stop there. I want to improve the design. Software design is all about making the next change easy. I may ask Claude to review its own code or suggest some refactorings that will improve the design.

I’ve heard some people say that in the future the code won’t even matter anymore. We will just be prompting and communicating with an agent—the code will never be looked at so who cares if it’s not readable. Maybe that will be the reality one day as coding agents improve more and more, but today code reviews are still a reality. Humans still need to be able to understand the code you’ve written no matter if it was generated by a bot or not.

In this AI coding world, refactoring remains a huge part of my development process.

As software products evolve and grow, continual change must be supported or else features that used to take a few days now take a few weeks. Estimations become impossible and even the coding agents can’t add new features because no one bothered to care for the software design.

I iterate on Claude’s code and turn it into something I’m proud to ship to production.

### 7. Commit before prompting

Working with Claude has made me even more disciplined when it comes to committing to version control frequently. I never know what crazy ideas Claude is going to spout out so I want to be in the position that I can revert its changes and start over again.

My workflow:

1. prompt until the code works
2. commit
3. refactor with Claude or myself
4. commit
5. push remotely

### 8. Make Claude experience the failure

I used to copy and paste errors into Claude. Honestly, I still do sometimes, but I try to have Claude run the app or the tests or whatever it needs to see the issues first hand. This process puts Claude into a loop where it can try something and get feedback.

### 9. Is there a simpler way to do this?

This is one of my favorite followups to Claude’s code generation. It should be specific, but if the task is small I will ask generally, “Is there a simpler way to do this?” Yes is usually the answer and Claude tries to simplify the approach.

Most of the time, I see a better way and want to challenge Claude to simplify the approach. Other times I don’t necessarily see a simple way or even understand the code, but I just ask it because it generally produces great results.

### 10. Work from a task list

All of my career I’ve had a habit of working from a task list. I make a Markdown file and organize my thoughts with my pair. This habit hasn’t changed working with Claude and has been even more valuable.

I have a custom slash command that instructs Claude to go through my todo list and work on the highest priority item.

Benefits of using a task list:

- Reduces cognitive load
- Focus on one thing at a time
- Reduce the risk of forgetting things you wanted to do

## Working with AI is like learning to pair program all over again.

When I first started pair programming, I had to learn a whole new way of working—communicating constantly, staying aligned, and checking in with my pair. It was uncomfortable at first, but it made me a better developer.

Working with Claude feels remarkably similar. These 10 heuristics aren't just tips and tricks—they're the foundation of building a sustainable relationship with AI that actually makes you a better programmer.

**Don't treat AI like a magic wand—treat it like your most eager junior developer.** One who's incredibly capable but needs guidance, mentoring, and clear direction. One who benefits from your experience but also challenges you to think differently.

The future belongs to developers who can effectively collaborate with AI while maintaining the craftsmanship that makes software maintainable and elegant. These heuristics will help you get there.

---

_Want to consistently ship high-quality code that's easy to change and understand? [Subscribe to Refactor to Grow](https://subscribepage.io/refactor-to-grow) for bi-weekly insights delivered to your inbox._


10 Heuristics for Pairing with Claude


I've been pair programming with AI coding agents for over 3 months, and I've noticed something crucial: bots generate code so fast that we often skip a vital step. The refactoring step.

When the bot generates code, resist immediately moving on to the next feature. Instead, take a moment to understand what just happened. Read through the code. Question the design decisions. Make it yours.

Yes, you can ask the AI to refactor for you. But unfortunately, LLMs still hallucinate and tend to make large, sweeping changes that introduce subtle bugs. That's why you need solid test coverage before letting any bot refactor the code.

In the [previous issue](https://diamantetechcoaching.com/newsletter/issue-002-refactoring-agent-code), I talked about how coding agents can refactor the code it generated. This process needs a solid test suite because coding agents are not as reliable at refactoring as the automated refactorings in IDEs.

As a long time practitioner of TDD, I’ve been experimenting with a different way of programming inspired by Dan North’s technique of [Spike and Stabilize](https://dannorth.net/the-art-of-misdirection). Over the course of my career, I’ve mostly been in large enterprise organizations that move slowly and gradually. Health insurance and banking industries are highly regulated so being super fast and risky is not wise in this context. However, I’ve now had my first startup experience where there’s high pressure to deliver to users quickly.

## Spike and Stabilize in Action

What started out as a spike and proof of concept ended up turning into the real thing. Over the course of a week, my pair, Claude Code, and I created a POC of an LLM Chatbot. It had a RAG pipeline that imported the companies’ knowledge base articles into a vector database so the LLM could use that as its context to pull from.

### LLM Terminology

RAG stands for retrieval-augmented generation. Instead of allowing the model to pull from all of its training data, you give it access to only specific data that it determines to be relevant to the provided query. This relevant context is where the vector database comes into play. The initial query is embedded (turned into a vector) and used in a cosine similarity lookup. Whatever embeddings are most related to the initial query will be added to the context of the prompt and the LLM will use that to create a response it chooses that best answers the query.

### Spike → prod deploy

I’ve seen spikes turn into production deploys many times over my career and have been warned against it. At one point, I said to my pair—”Now that we’ve seen how to build this, we can start from scratch and use our learnings to build it the right way (using TDD and evolutionary design)”. And they said “Why don’t we just use this? Is this the wrong way?”. They were challenging the dogmatic views of spike vs. TDD and I agreed. Except for the frontend, we used every piece of that original POC and got it ready for production. Without realizing it, we were applying the Spike and Stabilize technique.

Over the next week, we focused exclusively on refactoring. There were parts of the code that were complex and we didn’t understand, so with a mix of bot-driven refactoring and classic IDE-driven refactoring we started to make the code our own.

Some of the refactorings we did were:

- introducing clean architecture (segregated packages of infrastructure, domain, etc.)
- introducing domain objects to encapsulate complex article chunking behavior
- started moving toward a more generic architecture as we knew we needed to build at least one more pipeline

We also improved the performance by adding Node Streams and making the number of articles pulled at a time configurable.

### Build in quality last?

Instead of building in the quality up front as I am used to by writing tests first, we wrote the tests as needed. Early on we only had 1 test 😯! It was an edge-to-edge acceptance test that faked out the source of data and the sink datasource. It gave us roughly 40% of coverage all on its own and temporarily used [approval testing](https://youtu.be/vNaHTSuH6Bw?si=xPh4clCREf-GEl-U&t=1604) to capture the approved behavior. Before that we would run the pipeline and import 10 articles to verify no functionality had broken. We didn’t have edge cases covered, because we were focusing on the core functionality at that time.

As we started to separate the I/O from the behavior, it was easy to add unit tests to verify some of those edge cases. This helped us identify some over-engineering our coding agent had done and we were able to simplify the logic further.

For untested code I used automated refactorings in Webstorm or carefully carried out manual refactorings with verification by running the pipeline. For tested code, I would ask the coding agent to carry out more complex refactorings that would take me more time to do on my own.

One huge benefit of refactoring the code myself is I get to truly understand the generated code and make it my own. Eventually we had to share our work with the rest of the team so we needed to understand how every part of the pipeline worked so we could confidently explain it.

One rule I always follow in this new paradigm of programming is:

**Never ship code to production that you don’t understand.**

Once we refactored the app to have more structure and consistent patterns, it made the work of the coding agent more consistent and reliable. Bots, as do humans, tend to generate new code with a similar style as to what already exists in the codebase. So if the codebase is unstructured and highly coupled then the bot will generate code to conform to this norm. However, when software design concepts like ports & adapters, DDD, and encapsulation are consistently applied across the codebase then the bot will add to it with more structured code that aligns with that design.

## Make it work → Make it right → Make it fast

In the end, this pipeline that will have light usage over the years only had 60% test coverage. We were okay with this because of the context we were in. If this were an application that was used daily by thousands of users we would have poured even more effort into the quality. There will always be a long list of improvements, tweaks, and design enhancements that can be made, but the pragmatic engineer knows when enough is enough, ships it, and moves on.

### When to use this approach

This spike and stabilize method works best when you're exploring unfamiliar technologies or working in fast-moving environments that prioritize rapid iteration over upfront design. It's particularly effective in startup contexts where market feedback trumps perfect architecture, or when you're prototyping with new AI tools and frameworks where the "right way" isn't yet established. However, avoid this approach for mission-critical systems, heavily regulated environments, or codebases that will immediately scale to thousands of users where comprehensive test coverage is non-negotiable.

I’ve shared my experience with you today as one way to collaborate with coding agents and get the best out of them.

Our workflow looked like this:

1. Prompt the agent to add a new behavior (no tests)
2. Run the app to confirm new functionality
3. Review the code and work with the bot to improve poor design decisions
4. Evaluate if tests are needed
5. Refactor the code on our own to understand the [theory](https://pages.cs.wisc.edu/~remzi/Naur.pdf)
6. Evaluate performance needs

If your context needs a different way of working, then try some other approach, but be willing to experiment, refactor often, and challenge your coding agents to write simpler code that solves the problem at hand.

---

_Want to consistently ship high-quality code that's easy to change and understand? [Subscribe to Refactor to Grow](https://subscribepage.io/refactor-to-grow) for bi-weekly insights delivered to your inbox._


Spike & Stabilize with Coding Agents


Last issue, I argued that refactoring skills are more valuable than ever in the age of coding agents. Today, let's get tactical. I'll show you exactly how I safely refactor code generated by coding agents.

## The Problem with Agent-Generated Code

Coding agents generally produce working code, but it's sloppy. Much like the kind of code I write when making a test go green in TDD. The agent has solved the immediate problem, but the design often suffers.

Here's what I consistently see in agent-generated code:

- **Long Parameter Lists** - Functions that take 6+ parameters
- **Feature Envy** - Methods that seem more interested in other classes
- **Primitive Obsession** - Using strings and integers instead of domain objects
- **Duplicated Logic** - Similar code scattered across multiple places

These are classic code smells that signal design problems lurking beneath working code.

## Bot Refactoring Protocol

When I get working code from a bot, I never ship it immediately. Here's my process:

### 1. Review the Diff

I carefully examine what the agent changed or created. I need to understand the solution before I can improve it.

### 2. Take Note of Code Smells

I scan for the common patterns - long parameter lists, feature envy, duplicated logic. After three years of studying refactoring, these jump out immediately.

### 3. Remove Comments

Agent-generated comments are usually noise. Good code should be self-documenting. (I do this myself in a JetBrains IDE)

### 4. Refactor with Test Safety Net

I ensure there's test coverage, definitely at the acceptance test level. Then I start refactoring using specific vocabulary with the agent. If I don't have solid test coverage then I will refactor using automated refactoring tools that are much more deterministic and reliable. The coding agents have improved a lot, but the way they refactor code is error-prone. I'm looking forward to the day Claude Code can use the refactorings tools in IntelliJ via MCP.

## Real Example: Parameter Object Refactoring

Let me show you this in action. Recently, a coding agent generated this method:

```java
public void processOrder(String customerId, String customerName,
    String customerEmail, String productId, String productName,
    double productPrice, int quantity, String shippingAddress) {
    // ... implementation
}
```

Instead of accepting this parameter soup, I coached the agent:

**Me:** "This method has a Long Parameter List code smell. Let's introduce Parameter Objects to group related data. Create a Customer class and a Product class."

The agent immediately understood and refactored to:

**Bot:**

```java
public void processOrder(Customer customer, Product product,
int quantity, String shippingAddress) {
// ... implementation
}
```

Much cleaner. But I wasn't done.

**Me:** "We still have primitive obsession with the shippingAddress string. Let's create an Address value object."

**Bot:**

```java
public void processOrder(Customer customer, Product product,
int quantity, Address shippingAddress) {
// ... implementation
}
```

## The Key: Speak the Language

Notice how I didn't say "make this better" or "clean this up." I used precise refactoring terminology:

- Long Parameter List
- Parameter Objects
- Primitive Obsession
- Value Object

The coding agent understood exactly what I wanted because I spoke its language—the language of refactoring patterns.

## Beyond Code: Strategic Thinking

This isn't just about cleaner code. Each refactoring makes the next feature easier to add. When the next requirement comes in—maybe we need to handle international shipping—the Address value object gives us a natural place to extend functionality.

> "Make the change easy, then make the easy change." - Kent Beck

## Your Next Steps

- **Learn the vocabulary** - Start with 5 common code smells and their refactoring solutions
- **Practice with your next agent session** - Don't accept the first working solution
- **Build the habit** - Refactor agent code before you ship it

**Remember:** Coding agents give us working code fast. But professional developers deliver maintainable code that evolves gracefully with changing requirements.
Anything you ship to production you **must understand**, and refactoring is the best way I know to understand code. That's where your refactoring skills make all the difference.

Have you tried coaching a coding agent with refactoring vocabulary? What happened? Hit reply and let me know.

---

_Want to consistently ship high-quality code that's easy to change and understand? [Subscribe to Refactor to Grow](https://subscribepage.io/refactor-to-grow) for bi-weekly insights delivered to your inbox._


HOW STRONG ARE YOUR
CRAFTSMANSHIP SKILLS?

HowICoach

📖Active Learning

👥Collaborative Practice

🔎Design Habits

What Developers Say About This Approach

Myles Woerner

Sudeep Moothedath

Archana Subba

Eric Olaya

HOW STRONG ARE YOURCRAFTSMANSHIP SKILLS?