Why Your AI Coding Agent Keeps Making Bad Decisions (And How to Fix It)
A 30-minute feature has ballooned into three hours. Cursor has rewritten half your codebase, added an unwanted dependency, and nothing compiles. You backtrack, try again, and watch the agent cheerfully make the same mistakes in a slightly different order.
Welcome to the doom loop.
If you've spent any time with agentic development tools, Cursor, Copilot, or the one-shot platforms like Lovable, v0, Replit, and Bolt, you've probably experienced this. The promise is magical: describe what you want, watch it appear. The reality often involves debugging AI-generated spaghetti code while muttering about how you could have just written it yourself.
But here's the thing: these tools can work. The frustration isn't random. It stems from two specific, addressable problems.
TL;DR: The Two Fixes#
| Problem | Root Cause | Solution |
|---|---|---|
| Assumptions | LLMs force solutions rather than asking clarifying questions | Use structured planning workflows (like AWS AIDLC) before coding |
| Code Quality | LLMs trained on average-quality code produce average-quality output | Layer in IDE rules + MCP connections to docs and standards |
Why Do LLMs Make So Many Assumptions in Agentic Coding?#
Large Language Models (LLMs) are statistically biased toward forcing solutions rather than stopping to ask for missing information. Research from the paper "Can Tool-Augmented Large Language Models Be Aware of Incomplete Conditions?" confirms this: when presented with scenarios where critical information is missing, LLMs rarely pause to request it. Instead, they attempt to force a solution by making assumptions or selecting irrelevant tools.
This plays out constantly in practice. Give an agent a feature request and it will make assumptions about:
- Functional requirements: what "it should work like X" actually means
- Non-functional requirements: performance, security, accessibility
- Tech stack decisions: which libraries, which patterns
- Database architecture: schema design, relationships, indexing
- Implementation approach: how to structure the code
Each assumption is a coin flip. String enough of them together and you've got a codebase that technically runs but doesn't actually do what you need, or does it in a way that's unmaintainable.
The Fix: Structured Planning Before Code Generation#
You might be thinking your prompts are thorough enough. Every time I've had that thought and then used structured planning anyway, I've been surprised at the assumptions still being made.
Tools like Cursor have their own planning agents, and they help. But they still leave plenty of room for the agent to go off course.
The most robust solution I've found is AWS's AIDLC Workflows: github.com/awslabs/aidlc-workflows. It's a series of markdown documents with rules and steering files that transform agentic development into a structured process:
Inception Phase:
- Verify requirements with explicit questions
- Develop execution plans broken into units of work
- Document application design and dependencies
- Surface assumptions before any code is written
Construction Phase:
- Build plans with clear scope
- Functional design documents
- Testing plans
- Code generation against verified specs
Yes, this process is slower than throwing a prompt into Cursor and letting it rip. But we have found it's still dramatically faster than writing code by hand, especially for large features, and it follows the "measure twice, cut once" principle. You end up with code you're actually happy with.
The AIDLC workflows run natively in Kiro IDE, Kiro CLI, Claude Code, Cursor, Codex CLI and GitHub Copilot.
Why Is AI-Generated Code Quality So Inconsistent?#
LLMs are trained on vast datasets that include code of wildly varying quality (IEEE: Security Vulnerabilities in AI-Generated Code). And in practice, the "average" of that training data is... not great. Reason being that it's very difficult for LLMs to ensure the quality of their training datasets (ASE'24 Practitioner Survey). When writing code, LLMs pattern-match against this training data, often producing output that:
- Contains subtle bugs
- Performs poorly under load
- Includes security vulnerabilities
- Uses outdated or insecure patterns
- Violates your team's conventions
The result is AI slop. Technically functional output that's tangled, inconsistent, and painful to maintain. It compiles. It might even pass basic tests. But extending it or debugging it six months later? Good luck.
Our experience with one-shot platforms like Lovable, v0, Replit, and Bolt has been that they're excellent for prototyping and validating ideas quickly. But building production software on them without additional guardrails typically ends in a mess. (If you do end up in that situation, hit me up. We fix these regularly. 😜)
The Fix: Rules and External Context#
The good news: LLMs are getting better. OpenAI's Codex, for example, now curates high-quality repositories for training data (How Much Training Data Was Used for Codex). But you don't have to wait for models to improve, in our experience existing tools can dramatically improve output quality today.
IDE Rules
Cursor's rules provide persistent, reusable context at the prompt level. You create markdown files that guide the LLM's implementation choices. At The Gnar, we maintain rules for:
- General code standards: keep things simple, SOLID principles, DRY
- Language-specific conventions: Ruby idioms, TypeScript patterns, React best practices
- Project-specific patterns: how we structure services, naming conventions, testing approaches
Rules function as a persistent voice in the LLM's ear: "Actually, we do it this way here."
MCP (Model Context Protocol)
Most modern coding agents support MCP, which connects your agent to external tools and data sources. This is crucial for code quality because it gives the LLM access to:
- Up-to-date documentation: Context7 MCP provides version-specific docs for frameworks and libraries, so the agent uses current best practices instead of outdated patterns from training data
- Your codebase context: GitHub MCP connects to your remote repository
- Design files: Figma MCP for UI implementation
- Project management: Atlassian MCP for ticket context
- Debugging context: Sentry MCP gives your agent access to error traces, stack traces, and issue details so it can fix bugs with real production context instead of guessing
The combination of rules (your standards) plus MCP (current external knowledge) gives the LLM a much better foundation than raw training data alone. Teams that want the same for their company's documents build a knowledge base for LLMs.
How Do You See What Your Agent Decided and Keep It for Next Time?#
To see what your agent decided, use a workflow that records it. To keep those decisions, write them down where the agent reads them next time. Claude Code's docs say, "Each Claude Code session begins with a fresh context window."
- Put decisions in a file the agent reads. Claude Code loads CLAUDE.md files, which its docs describe as markdown files that give Claude persistent instructions for a project. Cursor's rules, covered above, do the same job.
- Use a workflow that records what it decided. The AIDLC Workflows README says the workflow "asks for missing decisions, and stops at approval gates before moving forward." It also keeps an audit trail.
- Turn a repeated correction into a rule. When you fix the same mistake twice, add a line to your rules file so the next session starts with it.
- Ask what the agent ran and read its output. Anthropic's Claude Code guide says an agent's report that "All tests pass" on its own tells you very little.
The Gnar Company's case study with GSC Enterprises shows the first item on this list in practice. Every participant left with "a maintained context file, at least one reusable skill, and a workflow they can describe."
Which File Does Each Coding Agent Read for Instructions?#
Each coding agent looks for an instructions file in your project. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads project rules stored in .cursor/rules. GitHub Copilot reads repository instructions in .github/copilot-instructions.md. A personal file or setting holds rules that only you use.
| Tool | Project file, in the repository | Personal rules, for you only |
|---|---|---|
| Claude Code | CLAUDE.md or .claude/CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md | ~/.codex/AGENTS.md |
| Cursor | .mdc files in .cursor/rules | User Rules, set in Customize, then Rules |
| GitHub Copilot | .github/copilot-instructions.md | Personal custom instructions, for Copilot Chat on GitHub only |
Claude Code's docs say, "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it."
Cursor and GitHub Copilot's agents also read AGENTS.md, the file Codex uses. One file can serve several tools.
Anthropic's guide gives one test for what goes in the file: "Only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session." Its section called "Keep CLAUDE.md short" lists "the exact test, typecheck, and lint commands."
Rules hold what applies to every change. The requirements for one change go in a spec. Anthropic's guide has Claude write one to SPEC.md, then says to "start a fresh session to build from it." Gnar's own method also starts from written requirements. Its Context-Driven Development post gives the definition: "Context-Driven Development (CDD) is a software development methodology where detailed requirements serve as the primary input for AI-powered code generation."
How Do You Keep an Agent From Copying Old Code Patterns?#
Tell the agent which pattern to skip and which file to follow. Anthropic's guide says Claude "starts every task by reading your code." It finds "how existing components are built" on its own. An older codebase can hold patterns your team has moved away from. Two habits help.
- Mark what not to copy in your rules file. Anthropic's guide lists "an old pattern that's everywhere but that new code must not copy" as a line for CLAUDE.md. Its example file says, "
src/legacy/ is still live but don't copy its patterns into new code." - Name the file to copy. The same guide replaces the prompt "add a calendar widget" with one that starts "follow the pattern in HotDogWidget.php".
These steps assume someone can explain the old code. The Gnar Company's codebase audit page answers "How do I know if our codebase is ready for AI?" with three questions: "Does the code have tests? Is it organized? Can anyone explain what it does?"
FAQ#
Can I use vibe coding tools like Lovable or Bolt for production?#
For prototyping and validation, absolutely. They're fantastic for quickly testing ideas. For production software, the lack of structured planning typically leads to unmaintainable code. Use them to validate concepts, then rebuild properly with guardrails in place.
Do Cursor rules actually make a difference?#
Significantly. Rules provide persistent context that steers the LLM toward your team's standards rather than defaulting to "average" training data patterns. The effect compounds over a project with consistent conventions, fewer weird one-off decisions, code that looks like your team wrote it.
How much slower is structured planning vs. just prompting?#
For small, well-defined tasks, the overhead isn't worth it. Just prompt and review. For features that touch multiple files, introduce new patterns, or have any ambiguity in requirements, structured planning pays for itself quickly (as evidenced by Boehm's cost curve). The time you spend up front is less than the time you'd spend untangling assumptions later.
Is this overkill for side projects?#
Depends on your goals. If you're prototyping to learn or validate an idea, vibe coding is fine, speed matters more than maintainability. If you're building something you'll need to extend and maintain, even side projects benefit from some structure. The "measure twice, cut once" approach scales down as well as up.
How do you debug code an AI agent wrote that looks right but is wrong?#
Start by reading the command the agent ran and its output. Write a failing test that shows the bug, then give the agent the real error trace. Claude Code's /verify command builds and runs the app to catch problems that tests and typechecks miss.
What happens when the model provider behind my coding agent goes down?#
If your tool supports more than one provider, as Cursor does, pick a model from another provider until the outage ends. Cursor's docs say it "supports frontier models from OpenAI, Anthropic, Google, SpaceXSI, and more."
How often does AI-generated code contain security flaws?#
In two studies, 45% of AI code samples across Veracode's test tasks (Veracode, 2025) and about 40% of programs written for security-sensitive tasks (Pearce et al.) had security flaws. Veracode's 2025 GenAI Code Security Report tested code samples from over 100 large language models. It found "45% of code samples failed security tests." A 2022 IEEE study of GitHub Copilot, by Pearce and colleagues, used 89 scenarios relevant to high-risk security weaknesses. It found approximately 40% of 1,689 programs vulnerable.
Why does my coding agent pick a popular tool instead of the one I want?#
One reason is that your preference is not written anywhere the agent reads. Anthropic's guide says of a preference between two reasonable approaches, "Claude can't read that from the code, so if you care which one it picks, say so up front." Name the tool and its version in your rules file. A docs tool such as Context7 gives your coding agent up-to-date, version-specific documentation for the library you name.
The Bottom Line#
Agentic development tools are genuinely powerful, but they're not magic. The frustration most developers experience comes from two specific failure modes:
- Assumptions: LLMs force solutions rather than asking for missing information
- Code quality: Training data averages down, not up
Address both with structured planning workflows and persistent context (rules + MCP), and you'll find these tools actually deliver on their promise: faster development of code you're happy with.
The goal isn't to fight the AI or work around it. It's to give it the constraints and context it needs to do good work. Just like you would with a junior developer except this one types really, really fast.


