Back in March, I was in full chaos mode with Windsurf on a codebase that had somewhere around five thousand lines of code spread across multiple services. The AI was doing exactly what I told it to do, which sounds good until you realize what I was actually telling it to do made no sense in the context of a large project.
Picture this. I’d ask Windsurf to “add this feature” and it would just start building from scratch. New patterns, new abstractions, new approaches to problems that had already been solved three times over in other parts of the codebase. It was like handing a contractor a blueprint and then they show up with their own design and building materials. Meanwhile my codebase is starting to look like a Frankenstein project with multiple ways of doing the same thing.
The worst part wasn’t even the duplication. It was that every change felt risky. Windsurf would make modifications that seemed reasonable in isolation but didn’t account for the three different environments I had running, or it would write code that only made sense in development and would break in production. I found myself spending more time undoing changes than I spent building new features.
I was stuck in that frustrating zone where the tool could do amazing things but I had no guardrails to keep it sane.
Then one day while digging through some notes and browser bookmarks, I found a set of coding pattern preferences that someone had written out. I can’t for the life of me remember where I pulled it from, but the timing was perfect. I looked at these guidelines and realized they weren’t just about good code practices. They were about communication. They were about telling an AI tool exactly what the rules of the game are.
The guidelines covered things that felt obvious once I read them but apparently needed to be stated explicitly. Always prefer simple solutions. Avoid duplicating code by checking if something similar exists elsewhere in the codebase first. Write code that works across dev, test, and production environments without special handling. Be careful to only make the changes that are actually requested. When you’re fixing a bug, don’t invent a whole new pattern to solve it. Keep the codebase clean and organized. Don’t write scripts into files if you can avoid it. Keep files under two to three hundred lines so they stay manageable.
And then the ones that really mattered for production safety. Only use mock data for tests, never for dev or prod environments. Never add stubbing or fake data patterns that could accidentally get deployed. Never overwrite the env file without asking first.
I put these guidelines into a system prompt for Windsurf and something clicked. The tool went from being a source of chaos to actually being helpful. It stopped inventing new patterns. It started respecting the existing architecture. Changes became smaller, safer, and actually fit into what was already there.
What surprised me most was how much this was about setting expectations. The AI wasn’t being malicious or stupid. It was just operating without boundaries. It was like telling someone “build me a thing” without giving them any constraints. Of course they’re going to do their own thing. But once you say “here’s how we do things, here are the rules, here’s what matters,” suddenly the work becomes coherent.
The really interesting part is that these guidelines apply way beyond just using Windsurf. I found myself thinking about them when reviewing code, when planning changes to the system, when bringing on new people to the project. They’re not flashy architectural decisions. They’re just… good practices for keeping a codebase sane and maintainable.
Looking back at March, I was frustrated at Windsurf. But the tool wasn’t the problem. I just wasn’t giving it enough structure. The moment I provided clear patterns and expectations, it became genuinely useful for a large, complex project.
If you’re struggling with AI coding tools on a substantial codebase, the issue might not be the tool. It might be that you need to get really explicit about how things work in your world. What patterns do you prefer? What are the non negotiables? What matters for safety and consistency? Once you articulate that stuff, everything gets easier.