Why Your AI Coding Agent Writes Bad Code (And How Specs Fix It)

You have tried Claude Code, Cursor, or GitHub Copilot and been impressed — until you looked at the code it produced for anything beyond a simple script. Wrong patterns, invented APIs, inconsistent naming, missing error handling. The code works but it does not fit your project.

The problem is not the AI. The problem is that you are asking it to build something without telling it how your project works. Here are the five most common failure modes — and how specification documents fix each one.

1. The Agent Invents Requirements

When you say "add user authentication," the AI has to decide: Email + password? OAuth? Magic links? What password rules? Session duration? It picks whatever seems most common in its training data, which may not be what you want.

The fix: A Product Requirements Document (PRD) with explicit acceptance criteria. Instead of vague instructions, the PRD says: "Support email + Google OAuth. Passwords must be 8+ characters with one number. Sessions expire after 24 hours. Rate limit login attempts to 5 per 15 minutes." The agent follows these requirements exactly.

2. The Architecture Does Not Match Your System

Without architecture context, an AI agent structures code however it thinks is best. It might put business logic in API routes, create a monolithic service when you wanted microservices, or use client-side data fetching when your project uses server components.

The fix: An architecture document that defines system boundaries, data flow, and technology choices. When the agent knows "all business logic goes in lib/services/" and "use server components for data fetching, client components only for interactivity," it follows your architecture instead of inventing its own.

3. API Endpoints Are Inconsistent

Ask an AI agent to build three different features and you will get three different API conventions. One uses /api/users with camelCase, another uses /api/v1/task_lists with snake_case, and the third returns errors in a completely different format.

The fix: An OpenAPI specification that defines every endpoint, request/response schema, and error format upfront. The agent implements endpoints to match the spec, ensuring consistent naming, pagination, and error handling across the entire API.

4. The Data Model Has Problems

Without a defined schema, AI agents create database tables on the fly. The result is usually functional but poorly designed — missing indexes, no foreign key constraints, redundant columns, or a schema that makes future queries unnecessarily complex.

The fix: A database schema document that defines tables, relationships, indexes, and constraints before any code is written. The agent builds the data layer to match the schema, with proper relationships and indexes from the start.

5. The Code Style Does Not Match Your Project

AI agents default to whatever patterns are most common in their training data. This means generic React patterns instead of your team's specific conventions, default error handling instead of your custom error classes, and file placement that does not match your project structure.

The fix: A CLAUDE.md or .cursorrules file that explicitly states your conventions. When the agent knows "always use AppError from lib/errors.ts" and "put components in src/components/features/," the generated code fits your project like it was written by a team member.

The Pattern: Specs Before Code

Every failure mode above has the same root cause: the AI agent is missing context. And every fix involves the same approach: write the spec before the code. This is spec-driven development — defining what to build in structured documents that AI agents can follow.

Keeborg generates the complete spec stack — PRD, architecture, OpenAPI spec, database schema, CLAUDE.md, and more — from a plain English description of your project. The result is AI coding agents that build the right thing on the first attempt, not the third. Try it free at keeborg.com.