why your AI coding agent keeps getting it wrong (and how to fix it)

# Stack — be specific

- React 19 with Server Components (not client components by default)
- Next.js 15 App Router (NEVER Pages Router)
- Tailwind CSS (NO CSS modules, NO styled-components, NO inline styles)
- Prisma with PostgreSQL (NO raw SQL queries)
- Zod for runtime validation (NOT Yup, NOT Joi)

# API response format

Every API response follows this exact shape:

```typescript
type ApiResponse<T> = {
  data: T | null;
  error: { message: string; code: string } | null;
  meta?: Record<string, unknown>;
};

export async function GET(request: NextRequest) {
  try {
    const users = await getUsers();
    return NextResponse.json({ data: users, error: null });
  } catch (err) {
    return NextResponse.json(
      { data: null, error: { message: "Failed to fetch users", code: "FETCH_ERROR" } },
      { status: 500 }
    );
  }
}

One concrete example in your config is worth ten sentences of abstract description.

## Mistake 3: Missing error handling

**The symptom:** The AI writes `await db.query(...)` without try/catch. Or makes an API call without handling the failure case. Or reads a file without checking if it exists.

**Why it happens:** Error handling adds length to code. The AI often optimizes for the happy path because that's what makes demonstrations clean.

**The fix:** Make error handling a mandatory criterion for "done":

```markdown
# Definition of done

No code is complete until:
- All async operations have try/catch or use a result type pattern
- All external API calls handle failure cases explicitly
- All user inputs are validated before use
- Error messages are logged appropriately (use our logger, not console.log)

# Error handling

We use a Result pattern for expected failures:
```typescript
type Result<T> = { ok: true; value: T } | { ok: false; error: string };

## Mistake 4: Wrong architectural layer

**The symptom:** The AI puts a database query inside a React component. Or puts business logic in a route handler. Or puts validation in the UI layer.

**Why it happens:** The AI doesn't know your architectural boundaries unless you document them explicitly.

**The fix:** Document where things belong:

```markdown
# Architecture boundaries

## Database
- Database queries ONLY in `lib/db/*.ts`
- Never query the database from components, route handlers, or server actions directly
- Always go through the `lib/db/` abstraction layer

## Business logic
- Business logic goes in `lib/[domain]/`
- Route handlers and server actions call into lib/, they don't contain logic

## Validation
- Input validation in the layer closest to the user (server actions, route handlers)
- Never validate in components
- Always use Zod schemas from `lib/validations/`

# Linting requirements

Before considering any code complete:
- Run `pnpm lint` and fix ALL errors (not just warnings)
- Run `pnpm check` for TypeScript errors

Key rules in our ESLint config:
- No `any` type — TypeScript strict mode is on
- No unused variables
- No `console.log` — use our logger from `lib/logger.ts`
- Prefer const over let
- Arrow functions for callbacks and utility functions

# Testing principles

Tests must verify behavior, not implementation.

Bad test (tests nothing):
```typescript
it("should work", async () => {
  const result = await getUser("123");
  expect(result).toBeDefined();
});

it("returns null for non-existent user", async () => {
  const result = await getUser("non-existent-id");
  expect(result).toBeNull();
});

it("returns user with correct shape for valid id", async () => {
  const user = await getUser(testUserId);
  expect(user).toMatchObject({
    id: testUserId,
    email: expect.stringContaining("@"),
    createdAt: expect.any(Date),
  });
});

## Mistake 7: Not following naming conventions

**The symptom:** The AI creates `fetchUser` when your codebase uses `getUser`, or `UserCard` when your convention is `UserCardComponent`, or `user-service.ts` when your convention is `userService.ts`.

**Why it happens:** Naming conventions aren't obvious from code context. The AI invents names based on general patterns.

**The fix:** Be explicit about naming in every category:

```markdown
# Naming conventions

Functions:
- Database queries: `get[Entity]`, `get[Entity]By[Field]`, `list[Entities]`
- Mutations: `create[Entity]`, `update[Entity]`, `delete[Entity]`
- Utilities: verb + noun (`formatDate`, `parseConfig`, `validateEmail`)

Files:
- Components: PascalCase (`UserCard.tsx`, `AuthButton.tsx`)
- Utilities: camelCase (`dateUtils.ts`, `stringHelpers.ts`)
- Types: camelCase with `.types.ts` suffix (`user.types.ts`)

Variables:
- Boolean flags: `is`, `has`, `should` prefix (`isLoading`, `hasError`, `shouldRedirect`)
- Arrays: plural nouns (`users`, `items`, `filteredResults`)