You write a detailed design doc. You paste it into your AI assistant. You wait.

The output compiles. Tests pass. And yet — it's not quite what you designed. The auth middleware is in the wrong layer. The error handling pattern differs from the rest of the codebase. The field names don't match the schema.

You fix it. Next task, same thing.

This happens constantly, and it's not a model capability problem. It's a structural problem in how we communicate design intent to AI. And "write better prompts" is not the solution — it's a band-aid.

---

Why "Better Prompts" Doesn't Scale

The instinct when AI misses the mark: add more detail to the prompt. Describe the pattern more explicitly. Give an example.

This works — sometimes, for that one task.

The problem: design intent isn't a single instruction. It's institutional knowledge accumulated over months. It's the reason two experienced engineers on your team write recognizably similar code without coordinating on every PR. It's the unspoken answer to "what does good look like here?"

You can't fit that into a prompt. And even if you could, you'd need to paste it every single time.

Think about onboarding a new engineer. You don't brief them on your entire codebase in the first conversation. You give them documentation, you pair with them, you let them absorb context over weeks. The conventions transfer gradually because there's a persistent learning mechanism.

With AI, there's no persistent learning mechanism by default. Every conversation starts from scratch. Your prompt is one-time context. Your design intent is institutional knowledge that needs to live somewhere the AI can always access.

---

Three Structural Gaps

Gap 1: Implicit Conventions Stay Implicit

Every team has them. Rules that are enforced in code review but never written down because "everyone knows that."

• "We use ActionResult<T> for Server Actions"
• "Zod schemas live in lib/schemas/, not colocated with components"
• "Don't use useEffect for data fetching — we have Server Components for that"
• "Always call auth() before any database access in an API route"

These live in your engineers' heads. When a new hire submits a PR that violates them, a reviewer catches it and leaves a comment. The new hire learns. The knowledge transfers.

AI doesn't get those review comments. It generates code, the review happens, but the AI's context doesn't update. Next task, same violation.

The cost: every AI output needs a manual convention-correction pass. The faster AI can generate code, the more convention-correction work piles up.

Gap 2: Specs Describe WHAT, Not HOW or WHY

Your design doc says "implement user authentication with session management." Good.

What it doesn't say:

• Auth middleware belongs in the route handler, not a global Next.js middleware
• Sessions are stored in the database, not JWT (because you had a security incident)
• Use NextAuth's auth() helper, not direct session inspection
• All session-dependent routes return 401, not redirect to login

These "how" and "why" constraints are the engineering culture. They're the decisions your team made, the tradeoffs you've accepted, the patterns you've settled on. A spec that describes the what gives AI enough rope to generate something plausible that violates all of the above.

An AI-effective spec would include the constraints that shape implementation, not just the behavior.

Gap 3: No Feedback Loop for Rule Violations

Human code review creates a feedback loop. Author submits code → reviewer catches violations → author adjusts → over time, author internalizes the rules.

AI-generated code breaks this loop in two ways.

First, the feedback doesn't persist. You can tell Claude "in this project, Server Actions always return ActionResult<T>" in one conversation. Next conversation, you tell it again.

Second, the volume overwhelms the feedback loop. One engineer might submit 3 PRs a week. With AI assistance, they might submit 20. Reviewers who were previously keeping up now face a backlog. Review quality degrades under volume. Violations start slipping through.

At scale, violations accumulate faster than review can catch them. Plausible-but-wrong patterns spread across the codebase. Six months later, you have a refactoring problem that looks like technical debt but is actually accumulated convention drift.

---

The Compounding Effect

A single convention violation in one file: minor, easy to fix.

10 AI-generated files with the same violation: a pattern.

50 AI-generated files with diverse convention violations: an architectural consistency problem. Different error handling here, different auth patterns there, schemas mixed into component files, raw Prisma objects returned from APIs.

This is the state many teams are in now — not because AI is bad, but because they're using AI without the infrastructure to give it their institutional knowledge.

From retrospectives I've reviewed and conversations with teams adopting AI tools: teams without explicit guidelines consistently report spending significantly more time — often 2–4× — on "cleanup" and "consistency work" than teams with structured rule systems. A common pattern: the team celebrates 3× faster feature generation, then quietly absorbs the same hours back in review cycles, convention-fixing passes, and cross-file inconsistency cleanup. The productivity gains from AI generation are real; they're being partially eaten by convention-drift cleanup.

---

What "Design Intent" Actually Means

When I say "design intent," I mean more than the features described in a spec. I mean:

Naming conventions and why they exist. Not just "use camelCase" but "function names that fetch data start with get, mutations start with update or create, and no function is named handle because it tells you nothing."

Which patterns are preferred and which are deprecated. "We use Server Components for data fetching. useEffect for data fetching was how we did it two years ago and there's still some in the codebase — don't follow it."

Security invariants. "Every external-facing API route must validate the session. This is not a preference, it's a requirement. There are no exceptions."

The tradeoffs you've accepted. "We verbose-type everything even when TypeScript could infer it. We know this is more code. We've decided explicit types are worth it for this team."

These don't belong in a design doc — they're too foundational, too stable. They belong in a persistent context that every AI interaction can access.

---

Rethinking What a Spec Is For

A traditional specification document is written for humans. It describes desired behavior, UI flows, data models, and edge cases. The reader is assumed to already know your team's conventions.

An AI-effective specification is different. It still describes behavior. But it also includes:

• The constraints that shape implementation ("use NextAuth, not custom JWT")
• The non-options ("do not introduce a new state management library")
• The patterns that must be followed ("Server Actions must follow the ActionResult<T> pattern")
• The why behind significant decisions ("we use Prisma's typed client because we've been burned by SQL injection in the past")

Consider the difference between these two spec sections:

Traditional:

Implement an API endpoint that allows authenticated users to update their profile information.

AI-effective:

Implement an API route at app/api/profile/route.ts that allows authenticated users to update their profile.

Implementation constraints:

• Use auth() from @/lib/auth to verify the session
• Accept only name and image fields — no other fields should be updatable via this endpoint
• Validate input with a Zod schema before any database operation
• Return { data: user } on success with only safe fields selected (no passwordHash, emailVerified, or internal IDs)
• Return { error: "..." } with appropriate HTTP status on failure

The second version leaves less room for AI to infer its own patterns. It specifies the how alongside the what.

---

The Solution Direction: Externalizing Tacit Knowledge

The fix isn't writing better prompts. It's building an infrastructure that makes your team's tacit knowledge persistent and accessible.

The practical shape of this:

This is a systems-design problem, not a prompting problem. You design the system once. The AI operates within it on every task.

The next article in this series walks through building this infrastructure for a Next.js project — step by step, with before/after code.

---

The structural gap between specs and implementation isn't inherent to AI. It's a gap we created by giving AI our "what" without our "how."

Closing it requires treating your team's conventions as infrastructure, not tribal knowledge.

---

What's the most persistent spec-drift you've hit with AI coding tools? Drop it in the comments — I'm cataloging these to improve guideline templates.

Next in this series: Codifying Tacit Knowledge: The Missing Layer Between Your Team's Conventions and Your AI Assistant (link will be added on publish)