DEV Community: KKK Dev

Why AI Coding Tools Over-engineer Your MVP — And the One Fix

KKK Dev — Sat, 16 May 2026 07:01:53 +0000

TL;DR — For reversible, stage-sensitive engineering decisions, AI assistants default to production-grade advice unless you specify business context. This isn't a model intelligence problem you can wait out. It's an objective-function problem you can fix in the next prompt. Below: the mechanism (with appropriate hedging), a before/after example, and a concrete taxonomy of what "context" actually means.

1. A Scene You've Probably Seen

Fifty users. MVP stage. Hypothesis validation is the only thing that matters.

You ask Claude Code to do a security review. You get back:

"Move the database into a separate VPC and use VPC Peering or PrivateLink."
"Wrap every external call in mTLS with automated cert rotation."
"Stream audit logs to a separate AWS account for SOC2 readiness."

None of it is wrong. But if you do all of it at this stage, you'll burn your runway on infra migration before validating whether anyone wants the product.

The same pattern shows up outside security:

Redis cluster with read replicas recommended for a 30 RPS service
Hexagonal architecture proposed for a 100-line script
GitOps + ArgoCD + Terraform module separation recommended for a 3-person team

The usual conclusion follows:
"AI can't do trade-offs. Humans need to decide."

The direction is right. The diagnosis is too vague to act on — so let's narrow it.

2. Scoping the Claim

This article is about a specific class of decisions: reversible and stage-sensitive.

Reversible: you can undo it without losing data, breaking contracts with users, or rewriting half the codebase. (Adding Redis is reversible. Changing your primary key strategy is not.)
Stage-sensitive: the right answer depends on where you are (MVP / growth / scale), not on universal best practice. (Caching layers, auth hardening depth, observability depth, infra topology.)

For irreversible or stage-insensitive decisions — DB engine, public API contracts, auth model, multi-tenancy boundaries, anything touching PII or payments — AI's conservative reflex is closer to right. That's covered in Section 6.

Within scope, the claim is:

AI assistants default to production-grade advice. You can change that, but only by stating your stage, scale, and trade-off weights explicitly.

3. Why the Common Diagnosis Falls Short

"AI only has the codebase as context, so it can't reason about trade-offs."

Three problems with this framing.

(a) Trade-offs are value judgments, not capability tests.
Risk preference, time preference, capital allocation — these are objective-function definitions, not things a model can derive from code alone. Two senior engineers reading the same code reach opposite conclusions. The CTO says "ship," the security lead says "no" — neither is smarter. They optimize different functions. Asking AI to "make the trade-off" without naming the objective is asking it to optimize without a loss function.

(b) You're not unable to give it context. You're choosing not to.
Every major coding assistant has a context-injection slot: CLAUDE.md, .cursorrules, AGENTS.md. Most "AI gave a bad recommendation" stories are at least partially "the user didn't specify context" stories — not all of them (models also hallucinate, miss repo state, or carry generic safety bias), but more than people admit.

(c) Humans over-engineer too.
Senior engineers carry trauma from past outages and pre-armor their code. AI's over-engineering and human over-engineering have different failure modes — AI tends toward boilerplate hardening, humans toward sticky abstractions — but neither is automatically easier to undo. The real axis isn't AI vs. human. It's context-aware vs. context-blind decisions.

4. A Hypothesis: The Production-Mature Prior

Here I have to hedge, because nobody outside the labs knows training mixes for sure. But the publicly visible candidates for what feeds these models are skewed:

High-star GitHub repos (already scaled, already hardened)
Vendor docs (AWS, GCP, k8s) — best-practice prose, not MVP code
High-vote Stack Overflow answers (often "the robust way")
Tech blog post-mortems ("here's what we should have done")

What these share: they document code that survived long enough to need scale, reliability, and compliance vocabulary. MVP-shaped code — single-file Flask apps, a docker-compose.yml with ten environment variables, a single RDS instance, hand-rolled session cookies — exists in training data too, but the advice prose attached to it is rare. The model has read a lot more "you should harden this" than "this is fine for now."

This is a hypothesis about a contributing factor, not a proven mechanism. Outputs also reflect instruction tuning, RLHF, system prompts, and safety policies — any of which can independently push toward caution. But it lines up with the observed behavior, and it's testable: try the before/after in Section 5 yourself.

Security review amplifies the effect. Threat catalogs (OWASP, CVE) are by construction lists of things that went wrong. A model trained heavily on those, when asked "is this secure?" without a threat model, hedges toward more findings — false positives increase when the model can't price the cost of being wrong in either direction.

5. Before / After — Same Model, Different Context

Here is the actual move. Same model (Claude Sonnet 4.6), same prompt, same code. The only difference is whether business context was supplied.

Code under review: a 60-line Express endpoint that accepts a JSON payload, looks up a user by email in Postgres, and returns a JWT.

Before — no context

Prompt: "Review the security of this endpoint."

Response (paraphrased, typical shape):

Add rate limiting with Redis token bucket
Move JWT secret to AWS Secrets Manager
Enforce mTLS between service and database
Audit-log every auth attempt to a separate AWS account
Add a WAF in front of the load balancer
Implement refresh token rotation with revocation list
Add CAPTCHA on repeated failures

Seven recommendations. None wrong in absolute terms. All sized for a company past Series A.

After — with context

Add this paragraph to the prompt (or to CLAUDE.md):

Stage: MVP, 50 users, solo dev, $200/month infra budget, 8-month runway.
Threat model in scope: of the OWASP Top 10, prioritize Injection (A03),
Broken Authentication (A07), and Sensitive Data Exposure (A02). Out of scope:
nation-state attackers, insider threats, denial-of-service.
Anti-goals: do NOT recommend mTLS, WAF, separate AWS accounts, or anything
requiring a dedicated infra hire.

Response (paraphrased, typical shape):

Confirm parameterized queries (looks fine)
Hash passwords with bcrypt cost ≥12 — current code uses cost 8, raise it
Validate JWT signing alg explicitly; reject alg: none
Put the JWT signing secret in an env var; document a rotation procedure (manual is fine at this stage)
Log auth failures to existing application logs; add a counter for "review at 5k MAU"

Five items, all things a solo dev can do this afternoon. Same model, same code.

That's the entire claim of this article, demonstrated. Try it on your own code; the shape of the answer changes.

6. The Reframe

The loose version:

"AI can't do trade-offs. Humans must decide."

The sharper version:

For reversible, stage-sensitive decisions, AI defaults to production-grade advice. The intervention point is supplying business context — stage, scale, trade-off weights, anti-goals.

This framing is more useful than the original because:

It points to an action. The responsibility moves from "AI is limited" to "I haven't told it where I am." Whether or not that's the whole story, it's the part you can fix in the next prompt.
It's durable, but not "permanently true." Future tooling will surely improve at inferring stage from repo shape, asking clarifying questions, and pulling org context from product telemetry. But humans will remain accountable for the objective function, even when they delegate parts of stating it.
It admits scope. It's a claim about reversible × stage-sensitive decisions, not all decisions.

7. What "Context" Actually Means — a Taxonomy

"Give the AI more context" is vague advice. Useful context has four layers:

Layer	What it answers	Where it lives
Stage	MVP / growth / scale. Reversibility budget.	`CLAUDE.md` top section
Constraints	Runway, team size, infra budget, latency targets	`CLAUDE.md` or per-prompt
Trade-off weights	Ship speed vs. quality vs. scalability ordering	`CLAUDE.md`
Anti-goals	Explicit list of recommendations to skip	`CLAUDE.md` "do NOT" list

A working CLAUDE.md snippet for an MVP:

## Project Context

- **Stage**: MVP — validating hypothesis. 50 users, target 200 MAU.
- **Team**: Solo developer. No ops headcount.
- **Constraints**: 8-month runway. Infra budget under $200/month.
- **Trade-off weights** (highest to lowest): ship speed, code clarity,
  scalability. Latency p95 under 1s is fine.
- **Security scope**: OWASP Top 10, prioritized — Injection, Broken Auth,
  Sensitive Data Exposure. Out of scope: nation-state, insider threats, DoS.
- **Anti-goals — do NOT recommend**:
  - Microservices, k8s, service mesh, mTLS
  - VPC Peering / PrivateLink / separate AWS accounts
  - Architecture patterns for files under 200 LOC
  - Caching, queues, or workers for features without measured load
- **Re-evaluation trigger**: revisit these weights at 5,000 MAU or when
  payments ship.

The anti-goals list is the unusual part. Most people skip it. It's the highest-leverage line in the file: it removes a class of recommendations the model would otherwise default to.

8. When AI's Default Is Actually Right

The thesis is scoped to reversible × stage-sensitive decisions. Outside that scope, AI's conservative bias is an asset:

Non-recoverable downside — anything touching PII, payment data, health data, customer secrets, auth tokens. Also: tenant isolation, key management, backup/restore, audit logs, retention/deletion compliance, breach notification readiness, secrets handling, vendor and supply-chain risk.
Regulated industries — finance, healthcare, government, ed-tech with minors. The default prior may even underestimate what's required.
Expensive-to-reverse decisions — primary DB engine, auth model, multi-tenancy boundaries, public API contracts, event schemas, ID strategy, billing model, permission model, observability foundations.

For these, lean into the conservative recommendation. Override only with a written reason.

The honest summary: this article is a heuristic for one specific quadrant of decisions, not a universal law.

9. What Would Change This?

It's tempting to add "at least for now" at the end and move on. Worth a beat instead.

Things that would partially close the gap:

Stage inference from repo shape — a meta-layer that looks at commit cadence, test coverage, observability stack, and recommends differently for "solo founder Express app" vs. "Series B microservice fleet."
Org-aware agents — read access to product metrics, infra spend, roadmap, risk policy. So the model can reason about cost the way a senior engineer does.
Policy profiles — "MVP mode" / "scale mode" / "compliance mode" as first-class settings.

What won't change: humans remain accountable for the objective function. Even if the tool infers your stage, you still own the decision of whether to accept the inference. So the practical claim — supply context, or don't be surprised by the defaults — survives most plausible improvements.

10. Summary

Loose framing	Sharper framing
AI can't do trade-offs	AI optimizes the objective you give it; default objective is production-grade
Humans must decide	Humans must specify stage, constraints, trade-off weights, anti-goals
"AI's limitation"	"Missing intervention at the context layer"
Time-bounded ("for now")	Humans stay accountable for objectives regardless of model progress

One actionable rule: before your next "review this" prompt, write four lines — stage, constraints, trade-off weights, anti-goals — into the prompt or into CLAUDE.md. Re-run. If the recommendations don't shift, your context is probably still too thin or you've hit a different failure mode (the model ignoring the file, generic safety bias, or a genuine capability limit). At that point, you have a real problem to debug instead of a vague "AI gave bad advice."

Open to feedback. Especially curious: (a) does the before/after replicate cleanly on your codebase? (b) where does the "Production-Mature Prior" hypothesis break — concrete counter-examples wanted. (c) is the same pattern visible in adjacent tooling — data engineering, MLOps, security scanners?

Why every Claude Code-built site looks the same — and the image layer that breaks it

KKK Dev — Sat, 16 May 2026 05:18:06 +0000

TL;DR:

AI-built sites look uncannily similar because they share the same defaults — Tailwind + shadcn/ui + Lucide + the same gradients. It's not a placeholder problem; it's a visual-stack problem. Real, project-specific images are the cheapest way out.
I wrote a small Claude Code skill that wraps Codex CLI's gpt-image-2 and triggers on natural-language asks. Drop a DESIGN.md at the project root, tell Claude to insert images, and you get a coherent, on-brand set across the site.
Biggest win for solo developers shipping without a designer. Repo: github.com/JunSeo99/claude-skill-codex-imagegen — install takes 30 seconds (or just hand the URL to Claude Code itself).

Claude Code can build a working site in one session. The structure, the routing, the component library — it all comes together fine on the first pass. The problem is more subtle: most of these sites end up looking like each other.

The reason is the stack. Claude reaches for the same defaults every time — Tailwind, shadcn/ui, Lucide icons, a slate-or-zinc palette, a hero with a soft purple-to-blue gradient, cards with a 1px border and rounded-2xl corners, an abstract SVG blob somewhere in the header. None of those choices are bad. But across hundreds of vibe-coded sites, the cumulative effect is that someone landing on one feels like they've been on this site before — even when they haven't. Visitors don't say "this is shadcn." They say "this feels AI-generated." And the surface they're reacting to is mostly visual: the same component library, the same icon language, the same illustration-less spaces.

The cheapest way out of that uniformity, I've found, is real images. Not stock. Not Unsplash. Project-specific, style-consistent images generated to match a brand voice. Three or four of them placed where default vibe-coded sites would have left a Lucide icon over a gradient, and the "feels AI-generated" reaction collapses. The site stops reading as a template.

I wanted that to stop being a manual step.

In April, OpenAI shipped gpt-image-2 and bundled an $imagegen skill into Codex CLI. That gave me what I needed: a real image model I could shell out to from inside Claude Code. So I wrote a Claude Code skill that triggers on natural-language asks like "make a hero image for this landing page" and dispatches the actual generation to Codex.

Then I spent a weekend learning why nobody had a clean solution yet.

gpt-image-2 has three sharp edges and none of them are documented loudly

These are the things I hit, in order, on the first day:

Size requests are advisory, not enforced. I asked for 256×256. Got 1254×1254. Asked for 1024×1024 — also 1254×1254. The model picks its own dimensions based on what it thinks the prompt needs. If you actually need a specific size for a CSS slot, you resize after, not before. You can't prompt your way out of it.

Transparent PNGs aren't supported. gpt-image-2 will not emit alpha. Only gpt-image-1.5 does. This is buried in the OpenAI image-generation guide. The first time I asked for an icon "on transparent background," I got a perfectly nice icon sitting on a solid white square. The workaround is to generate on a flat removable background — green or pure white — and chroma-key it out locally. Fine, but you need to know that going in.

The PNG doesn't land where you asked. It lands at ~/.codex/generated_images/<session-uuid>/ig_*.png. Telling Codex "save to assets/hero.png" doesn't move the file there. You move it yourself afterwards.

Each of those is a 20-minute debug session if you don't know them. Stacked, they make image generation feel "kind of broken" when it's actually working as designed, just badly documented.

And then there's the prompt itself

Even if you handle all three edges above, your output is only as good as your prompt. And gpt-image-2 punishes keyword soup.

The "stunning cinematic 8K masterpiece volumetric lighting" energy that worked on Midjourney v5 produces visibly worse output here. The OpenAI cookbook recommends a five-part structure — Scene → Subject → Details → Use case → Constraints — and front-loading the first 50 words because the model weights the opening more heavily. This is real. I A/B'd it. The five-part one wins every time.

For text in images (logos, banners, posters), wrap the literal text in double quotes or ALL CAPS so the model knows what's literal vs. descriptive. gpt-image-2 is genuinely strong here — short labels, signs, and UI mockups land at near-perfect spelling across Latin and CJK scripts, which is a meaningful jump from older models. Where it still wobbles is (a) long multi-line paragraphs baked into the image, (b) brand names and uncommon spellings, and (c) very small text inside dense layouts. For brand names, the OpenAI prompting guide recommends spelling the tricky word out letter-by-letter in the prompt ("the word ACME spelled A-C-M-E"). For paragraph-length text, render it as an HTML/CSS overlay over the generated image instead of asking the model to bake it in — that's the workflow gpt-image-2's own docs recommend.

For edits, the trick is "change only X, keep everything else identical." The model preserves what you don't mention vaguely — but it preserves what you explicitly tell it to keep very well.

None of this lives in the recipes that just say "run codex exec and you're done." So I baked all of it into the skill's playbook.

What the skill actually does

One SKILL.md plus two reference files (prompting-guide.md, cli-reference.md) that Claude Code auto-loads from ~/.claude/skills/codex-imagegen/. No Node, no install step beyond git clone && ln -s.

When you say something like "make a hero image of an origami crane for the landing page, save to assets/hero.png at 1600×900," the skill:

Rewrites your request into the five-part structure (Scene → Subject → Details → Use case → Constraints), front-loaded.
Runs codex exec --sandbox workspace-write '$imagegen <prompt>. Print only the absolute path on the last line.' — Codex generates, doesn't move.
Parses the path from stdout. Runs cp and sips -z 900 1600 (macOS) or convert -resize 1600x900 (Linux) to land the file where you actually asked.
Prints the final path. Done.

The natural-language trigger is the part that matters most to my actual goal. I want Claude Code, mid-build, to decide on its own that this <section> needs a hero image, and just generate one. Not "user types a special slash command." The skill fires from phrases like "generate an image," "make an icon," "create a banner," "OG image," "hero illustration." Claude calls it the same way it calls anything else in its toolkit.

That's the whole point. The site shouldn't end up looking like every other vibe-coded site because the agent never broke out of its default visual stack. The agent building the site should be reaching for project-specific imagery on its own.

The trick that changes everything: DESIGN.md

Here's the bit I didn't expect to matter as much as it does.

If you drop a DESIGN.md at the root of your project — palette, type, illustration style, tone — and then ask Claude Code:

Using DESIGN.md as the style reference, insert images that fit the site.

…it just works. Really well.

Claude reads DESIGN.md, decides which slots in the codebase need imagery, writes prompts that incorporate the palette and tone, calls the skill, and inserts the resulting paths into the right <img> tags. The hero image, the empty-state illustration, the OG card, and the favicon all end up looking like they belong to the same product. Without DESIGN.md it still works, but each image drifts a little — palette, mood, lighting are all slightly off across slots, and you can feel it even if you can't immediately name what's wrong.

DESIGN.md doesn't have to be fancy. Here's a trimmed version of one I'm using right now:

# Design

## Concept
Calm, considered, modern. The kind of feel that gets out of the user's
way instead of demanding attention.

## Palette
- Surface (main):  #F4F1ED  — warm off-white
- Surface (cards): #FFFFFF
- Text:            #1A1A1A  — near-black, not pure
- Accent / CTA:    #C46A4E  — soft terracotta, used sparingly

## Typography
- Inter, system-ui sans-serif

## Illustration style
- Single subject, plenty of whitespace, no busy backgrounds
- Soft natural light from upper left, gentle shadows
- Hand-folded paper / origami feel where applicable
- No text inside images unless explicitly asked
- Avoid stock-photo vibes and over-saturated colors

That's 20-ish lines. But Claude treats it as a hard constraint when writing prompts, and the visual consistency across a 4–5 page site is night and day vs. asking for each image cold. The "Illustration style" block is doing about 80% of the work — palette obviously matters, but the qualitative instructions ("hand-folded paper feel," "no busy backgrounds") are what stop each image from feeling like it came from a different stock-image library.

Why this is the year vibe-coded sites stop looking vibe-coded

A year ago this would have been a different post. Back then, even if you wanted to break out of the shadcn-default look, generated images weren't the answer. The available models produced output that screamed AI louder than the layout did — slightly melted typography, off-axis lighting, the same handful of obvious tells. So the fastest path was usually "just don't add an image," and the result was a sea of sites that all leaned on the same component library to do all the visual work.

gpt-image-2 changes the math. With a tight DESIGN.md and a five-part prompt, generated images now look like they came from a brand, not from a model. Text spells correctly. Light angles agree across slots. Subject framing is intentional. They're not hand-crafted illustrations from an agency, but they no longer carry the "AI tell" that earlier generations did. And once those images sit alongside the shadcn cards and the Lucide icons, they shift where the eye lands. A visitor reads the hero illustration, the OG card, the empty-state graphic — slots that on a default vibe-coded site were either missing or generic — and the site registers as a product instead of a template.

The interesting part isn't any individual image. It's that the gap between "site built by a small team with a designer on call" and "site built solo with Claude Code overnight" is mostly carried by image quality and visual specificity. The structure is solved. The components are solved. What's left, and what was carrying most of the "feels AI-generated" signal, was the image layer — and that's the slot this skill fills.

If you ship as a solo developer — no designer on call, no illustration budget, no Figma file from a teammate — this is the part of the workflow that used to force a compromise. Either you paid for stock images that didn't quite match the rest of the site, or you pulled an SVG from Heroicons and called it a hero. With gpt-image-2 plus a DESIGN.md, that compromise mostly goes away. The same person who writes the code can produce custom, on-brand visuals in the same session, without leaving the editor and without commissioning anyone. That's the audience I built this skill for, and the audience it changes the most for. Designers will always have an edge on intentional taste — I'm not pretending otherwise — but for the long tail of side projects, landing pages, and internal tools that were never going to get a designer in the first place, the bar just moved.

Once you have this loop — Claude builds the site, reads DESIGN.md, decides where images belong, generates them with consistent style, drops them in place — visitors stop registering that AI built the site. Which is the bar.

Caveats

gpt-image-2 turns burn 3–5× your Codex usage limit vs. a plain text turn. If you're iterating a lot, set OPENAI_API_KEY and switch to per-image API billing.
macOS is primary. Linux works via ImageMagick. Windows is not on the roadmap.
The skill is around 200 lines of markdown plus a small shell helper. If you don't like a default, edit it. There's no framework to wrestle.
For small text or dense multi-font layouts, bump quality to medium or high — gpt-image-2 is honest about which slots benefit from extra compute.

Repo

github.com/JunSeo99/claude-skill-codex-imagegen

git clone https://github.com/JunSeo99/claude-skill-codex-imagegen \
  ~/.claude/skills/codex-imagegen

If even that feels like effort, just hand the repo URL to Claude Code itself and tell it to install the skill — something like "install this Claude Code skill: https://github.com/JunSeo99/claude-skill-codex-imagegen". It'll read the README, run the clone-and-symlink, and the next session will just have it. Mildly recursive — using Claude Code to install something Claude Code is going to use — but it works, and honestly it's how I install most of my own skills these days.

Once it's installed, restart Claude Code. Drop a DESIGN.md at the root of your project. Build your site. Then say: "Using DESIGN.md as the style reference, insert images that fit the site."

Curious if anyone else is doing the DESIGN.md-as-style-anchor pattern for AI-generated assets — I'd love to compare notes on which fields actually move the needle and which are noise. The "Illustration style" block is doing 80% of the work in my setup, but I haven't tested it across enough projects to call it.

And feedback on the skill itself is genuinely welcome — issues, PRs, "this default is wrong," "this caveat is missing," "this prompt pattern didn't work for me." It's still early, and I plan to keep iterating on it as people actually run it in their own projects. If you try it and something breaks or feels off, please tell me — that's the fastest way I'll make it better.