Prompt engineering is not the answer — Specs are

The AI coding community has spent two years optimizing prompts. "Be specific." "Use chain-of-thought." "Provide examples." "Add system instructions."

These techniques help. But they're optimizing the wrong variable.

The quality of AI-generated code is determined by the quality of the requirements, not the quality of the prompt wrapping them.

The prompt engineering trap

Prompt engineering for code generation looks like this:

``` You are an expert software engineer. Use TypeScript with strict types. Follow SOLID principles. Write clean, maintainable code. Include error handling. Add JSDoc comments.

Now build a user authentication system. ```

This prompt is well-engineered. It sets the tone, specifies the language, and provides guidelines. But the actual requirement — "build a user authentication system" — is completely underspecified.

What kind of authentication? OAuth? Email/password? Magic link? What permissions model? What session management? What about rate limiting? Account lockout? Password requirements?

No amount of prompt engineering answers these questions. Only a spec does.

Prompt vs. Spec: The distinction

| | Prompt | Spec | |--|--------|------| | Scope | How to generate code | What code to generate | | Lifetime | Single use | Persistent | | Audience | AI model | AI model + team | | Review | Individual | Collaborative | | Structure | Free-form | Problem/Scope/Out of Scope/Approach | | Accountability | None | Approval workflow |

A prompt is a wrapper. A spec is the content. You can have the best wrapper in the world, but if the content is vague, the output will be wrong.

The evidence

Consider two scenarios:

Scenario A: Great prompt, vague spec ``` [Expertly crafted system prompt with 500 words of instructions] Build a notification system for our app. ```

Scenario B: Simple prompt, great spec ``` Implement the following spec:

Problem: Users miss important updates because we have no notification system. Scope:

• In-app notifications for: spec approved, task assigned, comment mention
• Bell icon in navbar with unread count badge
• Notification panel with mark-as-read and mark-all-read
• Store in PostgreSQL, serve via existing Connect RPC API Out of Scope:
• Email notifications (Phase 2)
• Push notifications (Phase 2)
• Notification preferences/settings ```

Which one produces better code? Scenario B, every time. The AI has clear requirements, explicit boundaries, and knows what NOT to build.

Why this matters for teams

For individual developers, the prompt-vs-spec distinction is nuanced. You know what you want, and a good prompt might be enough.

For teams, the distinction is critical:

1. Prompts aren't shared. Each developer writes their own. Specs are shared — the team writes one together.
2. Prompts aren't reviewed. Nobody approves your prompt before you hit Enter. Specs are reviewed and approved.
3. Prompts aren't persistent. They disappear after the conversation. Specs persist and serve as the record of what was agreed.
4. Prompts don't define "done." Specs include acceptance criteria that objectively define completion.

The practical shift

Stop optimizing your prompts. Start writing specs.

Instead of spending 30 minutes crafting the perfect prompt, spend 30 minutes writing a structured spec with:

• Problem — Why this change matters
• Scope — What specifically will change (bullet points)
• Out of Scope — What won't change (equally important)
• Acceptance Criteria — How to verify it's done

Then use the simplest possible prompt: "Implement this spec."

The spec does the heavy lifting. The prompt is just the delivery mechanism.

FAQ

Q: Should I still learn prompt engineering? A: Basic prompt skills are useful for ad-hoc tasks. But for team projects, invest in spec writing over prompt crafting.

Q: What about system prompts and CLAUDE.md files? A: These are valuable — they set project-level context (like Project Memory in Colign). But they complement specs, they don't replace them. System prompts define how to work. Specs define what to build.

Q: Can AI help write specs? A: Yes — and this is a better use of AI than prompt engineering. Use AI to draft specs, then have humans review and approve them. Colign's suggest_spec tool does exactly this.