Write the spec first — let your agent write the code second

Your coding agent is writing spaghetti code because you're asking it to think and code at the same time. Stop doing that.

Here's what happens when you tell your agent "build a user authentication system": it starts writing code immediately. No planning. No architecture. Just straight into implementation details. Twenty minutes later, you have 400 lines of code that sort of works but is impossible to extend.

The fix is simple: make your agent write the specification first, then write the code.

The two-phase pattern that works:

Phase 1: Agent writes a detailed spec
Phase 2: Agent implements against the spec

I've been running this pattern for three months. The code quality improvement is dramatic. More importantly, the agent stops second-guessing itself mid-implementation.

Here's the prompt structure:

PHASE 1 - SPECIFICATION:
Write a complete technical specification for [feature]. Include:
- API endpoints and data structures
- Database schema changes
- Error handling scenarios
- Integration points
- Testing requirements

Do NOT write any code yet. Focus only on the spec.

PHASE 2 - IMPLEMENTATION:
[Paste the spec here]

Now implement this specification exactly as written.

The magic happens in the handoff between phases. Your agent has to commit to an architecture before it touches code. No more "I'll figure it out as I go" implementations.

What this prevents:

• Scope creep mid-implementation
• Inconsistent naming and patterns
• Missing error handling
• Incomplete test coverage
• Architecture drift

I run this as two separate sessions. Phase 1 gets saved to a specs/ directory. Phase 2 references that spec file. The agent can't change the requirements once it starts coding — it has to implement what it designed.

Example spec output:

# User Authentication System Specification

## API Endpoints
POST /auth/login
  Input: {email, password}
  Output: {token, user, expires_at}
  Errors: 401 (invalid), 429 (rate limit)

POST /auth/logout
  Input: Authorization header
  Output: {success: true}

## Database Schema
users table:
  - id (uuid, primary)
  - email (unique, indexed)
  - password_hash (bcrypt)
  - created_at, updated_at

sessions table:
  - token (uuid, primary)
  - user_id (foreign key)
  - expires_at (indexed)
  - created_at

The agent that wrote this spec will implement it consistently. No surprises, no architectural pivots halfway through.

Pro tip: Include the spec file in your agent's context for future modifications. When you need to extend the feature, the agent reads its own spec first, then proposes changes to the spec before touching code.

This pattern works because it matches how senior engineers actually build things — design first, implement second. Your agent gets the same benefits: cleaner code, fewer bugs, and implementations that actually scale.

The best part? You can review and modify the spec before any code gets written. Much easier to catch problems in a 2-page spec than in 20 files of implementation.