How to Debug with AI (Without the Guesswork)

I’ve been a software engineer for over 10 years. I’ve seen so many ways a build can break, but Vercel still managed to surprise me this week.

Everything looked perfect locally. Even a full production build on my Mac was flawless. But the second it hit the server? Total disaster. No spacing, tiny headers, and code blocks that looked like they’d been stripped of all dignity.

Usually, this is where you might start blindly changing code or begging an AI to "just fix it." Instead, I used this as an opportunity to pair with the AI differently. Here is the playbook for how we solved a silent Tailwind failure by treating the AI as a colleague, not a magic wand.

---

1. Don't code. Write a theory.

The first thing I told the AI was: "Do not make any changes yet. Troubleshoot, spot what is happening, and write a theory."

This is the most important step. If the AI can’t explain why it thinks something is broken, any code it writes is just a guess. We spent the first few interactions just building a document in the articles/ folder. We mapped out the symptoms and wrote down exactly why we thought the CSS extraction was failing.

Staff Engineer Pro-Tip: When a bug is environment-specific, don't ask the AI to fix it. Ask it to "Analyze the differences between a permissive Mac environment and a strict Linux environment." The nodes of failure always live in the delta.

If you can't document the theory, you aren't ready to commit the fix.

---

2. Human-led research is the multiplier

AI is great at processing what’s in front of it, but it isn’t always a great detective for obscure, environment-specific bugs.

While the AI was analyzing my config, I went out and did the "manual" work. I dug through GitHub issues, StackOverflow, and Vercel's knowledge base. I found four specific links from people who had seen similar behavior—specifically issues with ESM interop on Linux and how Next.js handles dynamic imports.

Our Research Log

• Next.js Issue #65388: Tailwind styles missing in production Link
• Vercel KB: Deploying MDX Deck Link
• StackOverflow: Tailwind styles in production Next.js Link

I fed those URLs back to the AI. "Read these and understand whether something similar is impacting us."

This changed the game. It shifted the AI’s focus from "maybe your CSS is wrong" to "maybe the Vercel build environment is failing to resolve your external config files."

---

3. One fix at a time (The Staff Engineer way)

Once we had three solid theories, the temptation was to try all three at once. I pushed back: "Let’s do 1 at a time, starting from the one with the highest likelihood. That way we will know what the problem actually was."

This is discipline. If you change three things and it starts working, you’ve learned nothing. You haven't fixed the bug; you've just obscured it.

The Debugging Sprint

• Phase 1: Syntax Cleanup — Fix non-standard @screen in JS ⮕ No change ❌
• Phase 2: ESM Interop — Explicitly handle .default exports ⮕ No change ❌
• Phase 3: The Big Guns — Inline the config and refine content paths ⮕ FIXED ✅

The "Smoking Gun"

Here is the syntax that worked locally but crashed the build on Vercel:

// ❌ The "Permissive" Mac syntax
'@screen lg': { ... }

// ✅ The "Production-Safe" syntax
[`@media (min-width: ${theme('screens.lg')})`]: { ... }

---

4. Turn the fix into a Playbook

Once the styles snapped back into place, we didn't just delete the troubleshooting doc. We turned it into a permanent playbook at the top of the file.

I asked the AI to create a "When to use this" section. Now, if this ever happens again, I don't have to remember the fix. I have a documented process that tells future-me:

## 📖 When to use this playbook
Use this if you encounter the following:
- Site looks perfect on localhost but broken on Vercel.
- Classes like .prose appear in HTML but have no CSS rules.
- Using Tailwind plugins that rely on external config files.

---

The Takeaway

The "Mystery of the Missing Styles" wasn't actually about CSS. It was about how Tailwind’s scanner works in a strict Linux environment versus a permissive Mac environment.

But more importantly, it was about how to work with AI. Don't let it shotgun changes into your codebase. Make it write theories. Feed it your own research. And move one phase at a time until there's nowhere for the bug to hide.

That’s how you debug without losing your mind—or your CSS.

---