Forem: Junkyu Jeon

How to Write Better Prompts for Bolt, Lovable, and Cursor

Junkyu Jeon — Mon, 20 Apr 2026 23:21:36 +0000

You and your friend both use Cursor. You both ask for "a simple to-do app." Three hours later, your friend has a working app with auth, persistence, and a clean UI. You have a pile of files, a broken login, and a database that won't connect.

Same model. Different prompt.

People talk about prompt engineering like mysticism. It isn't. It's closer to a checklist. Here's the checklist — plus templates you can copy.

Why Most Prompts Fail

Bad prompts share a few patterns. The AI isn't guessing maliciously — it's filling blanks you left empty.

No stack specified. "Add a database" — which one? SQLite? Supabase? Postgres? AI picks. Often picks something that doesn't fit.
Whole-app requests. "Build me an Airbnb clone." 40 files of plausible-looking code, none of which fit together.
Vague verbs. "Make it better." "Refactor this." No target — so it changes everything, including parts that were fine.
No examples. "Format the date nicely." AI guesses what "nicely" means.
Missing constraints. No edge cases, no max length, no expected error behavior. AI handles the happy path and ignores the rest.

Each blank is a decision the AI makes for you — usually not the one you'd have made.

The Anatomy of a Good Prompt

Five parts. Don't need every part every time, but more = less guessing.

1. Context

What is this project? What stack? What conventions? If you have a CLAUDE.md or .cursorrules, this is already covered. If not, lead with one sentence: "This is a Next.js 15 + Supabase + Tailwind app. We use shadcn/ui and follow App Router conventions."

2. Goal

What specifically do you want? One concrete change. "Add a button on the dashboard that exports the visible projects to CSV" — not "add export functionality."

3. Constraints

Must do? Must not do? "Must work for up to 10,000 rows. Must not block the UI. Use the existing supabase client from lib/supabase.ts."

4. Output Format

How do you want the answer? Code only? Diff only? Specify it.

5. Verification

How will you know it worked? Tell the AI. "After this, I should be able to click Export, get a CSV download named projects-{date}.csv, and open it in Excel without warnings."

When the AI knows what success looks like, it writes code aimed at that result — not at "something CSV-ish."

5 Patterns That Make Prompts Work

1. Specify the Stack and Version

"Use Next.js" is not enough. Next.js 13 Pages Router and Next.js 15 App Router are different worlds.

Bad: "Add a server-side API route."
Good: "Add a Next.js 15 App Router route handler at app/api/export/route.ts. Use the new Web Request/Response API, not the old req/res."

2. Show, Don't Tell

Examples beat adjectives every time.

Bad: "Format the price nicely."
Good: "Format as USD with dollar sign and 2 decimals: '$1,234.56'. Under $1, show 4 decimals: '$0.0042'."

3. One Feature at a Time

Resist the mega-prompt. Split it:

"Create /profile route. Fetch current user from Supabase, display name/email/joined date."
"Add Edit button. Toggles name/email to inputs."
"Add Save button. Updates user via Supabase. Shows success toast."
"Add avatar upload. Stores in Supabase Storage. Updates avatar_url."

Each step verifiable. When something breaks, you know which step. With a mega-prompt, you don't.

4. Constrain the Data Shape

Most bugs come from data the AI didn't expect.

Bad: "Calculate the order total."
Good: "Inputs: array of { price: number, quantity: number } (price in cents, quantity positive integer), and optional discountPercent (0-100, default 0). Return cents. Empty array → return 0. Negative quantity → throw."

5. Ask for Tests Explicitly

AI rarely writes tests unless asked. Almost never thinks about edge cases unless told.

Add one line: "Also write a test file covering: empty input, single item, max items, zero discount, 100% discount, one negative input that should throw."

The test file does double duty: forces edge-case thinking, and gives you a regression net.

5 Anti-Patterns to Avoid

1. "Make it better"

The vaguest possible prompt. Name what you want: "Reduce the number of state variables. Right now there are 7 useState calls; consolidate where possible."

2. "Add authentication"

Auth isn't one feature. Sign-up, sign-in, sign-out, password reset, session, route protection, email verification — at minimum. Pick a flow:

"Add Supabase email/password sign-in. One page at /login. On success, redirect to /dashboard. On failure, show Supabase error inline. Don't add sign-up or password reset yet."

3. Pasting whole logs without context

200-line stack trace + "fix this" = AI guessing what part matters and what your code looks like.

Paste the relevant error line, the function it points to, one-line description of what you were doing.

4. "Refactor this"

Refactor for what? Performance? Readability? Reuse? Each goal points at different changes.

Better: "Extract the price-formatting logic from this component into a function in lib/format.ts. Don't change behavior. Update component to import and use the new function."

5. Mid-stream stack swaps

Three hours into a Supabase project. You read a tweet about Drizzle ORM. "Switch the database to use Drizzle." AI tries. Half-rewrites a few files, leaves Supabase imports scattered, nothing works.

Stack swaps mid-project are surgery, not a prompt. Plan it as its own deliberate session.

Real Before / After

Same goal, two prompts.

Before:

Add export to CSV.

What the AI does: invents a button somewhere, picks a CSV library you don't have, exports fields it guesses are interesting, ignores filtering, blocks UI for large datasets.

After:

Context: Next.js 15 App Router project, Supabase backend.
Dashboard at app/dashboard/page.tsx shows a table of "projects"
filtered by search input and status dropdown.

Goal: Add an "Export CSV" button next to the search input that
downloads the *currently visible* (filtered) rows as CSV.

Constraints:
- No new dependencies. Build the CSV string manually.
- Columns: id, name, status, created_at (ISO string), owner_email.
- Handle commas and quotes correctly (RFC 4180).
- Filename: projects-{YYYY-MM-DD}.csv.
- Must work for up to 10,000 rows without freezing.

Output: Diff to dashboard/page.tsx and any new helper file. No explanation.

Verification: With dashboard filtered to status=active, I click
Export CSV → download with only active projects, named
projects-2026-04-21.csv, opens cleanly in Excel.

Second prompt: 60 seconds longer to write. Saves 30 minutes of back-and-forth.

Steal These Templates

New Feature

Context: [stack + relevant existing code]
Goal: [one specific user-visible change]
Constraints:
- [must do X]
- [must not do Y]
- [data shape, edge cases]
Output: [code only / diff only / explain first]
Verification: After this, I should be able to [observable thing].

Bug Fix

Repro:
- Steps: [1, 2, 3]
- Input: [exact values]
- Expected: [what should happen]
- Actual: [what happens, including error]

Suspect file: [path]

Don't change behavior elsewhere. Show your hypothesis before
the fix, then minimal change to address the root cause.

Data Model

Add a Supabase table "[name]" with:
- id: uuid primary key
- [column]: [type, nullable?, default?]
- created_at: timestamptz default now()
RLS: [who reads, who writes]
Generate SQL migration under supabase/migrations/ with
timestamp prefix, and TypeScript type in lib/types/[name].ts.

When Prompting Alone Isn't Enough

For a single feature, a good prompt is enough. For a whole app, you need a sequence — and getting the sequence right is its own skill. Data model before UI. Auth before features that need it. Deploy setup before you have anything to deploy.

Better prompts aren't about being clever. They're about leaving fewer blanks. Every blank is a decision the AI makes for you — and it doesn't know your project, your users, or what you actually want.

The skill compounds. Every well-crafted prompt teaches you what to specify next time. Within a few weeks, your hit rate moves from "sometimes works, mostly weird" to "ships first try, most of the time."

Steal the templates. Add to them as you find what your stack needs. Your AI is the same as everyone else's — your prompts don't have to be.

Originally published at bivecode.com

How to Debug AI-Generated Code: A Systematic Approach

Junkyu Jeon — Sun, 19 Apr 2026 14:23:57 +0000

The Debugging Trap With AI Code

You built something cool with Cursor or Bolt. It worked on the demo. Then a user tried it with a slightly different input — and it blew up. You paste the error into the AI, it confidently rewrites the function, and now a different thing is broken. Welcome to the debugging trap.

Research from GitClear and others suggests around 43% of AI-generated projects need real debugging work before they're production-ready. AI coding tools are good at the happy path — the flow you described in the prompt. They are bad at the unspoken edges: empty arrays, zero values, null users, timezone boundaries, race conditions.

And here's the trap: when something breaks, the natural move is to paste the error into the AI and say "fix this." The AI does what you asked. It patches the symptom. The bug moves somewhere else. You paste that error. Repeat. Pretty soon you have a codebase held together with duct tape and nobody — not you, not the AI — understands what's actually happening.

There's a better way. It isn't magic. It's the same debugging discipline engineers have used for decades, just applied intentionally to AI-authored code.

Why "Just Ask AI to Fix It" Doesn't Work

AI is a great debugging assistant, but a terrible debugging driver. Here's why:

AI doesn't know which parts are working. From its perspective, everything in the file is suspect. It will often "fix" code that was fine and leave the actual bug untouched.
Without a reproduction case, AI guesses. If you say "sometimes the total is wrong," the AI has no way to know when or why. It will generate plausible-looking code that addresses a plausible-sounding problem. Plausible is not correct.
Each "fix" can introduce new bugs. AI can't see your app's runtime behavior. It can't observe the actual values. It's writing code based on pattern-matching, not evidence.
The fix-depth problem. AI tends to fix symptoms, not causes. A wrong total? Add a check in the caller. A null crash? Wrap it in a try/catch. The real bug — upstream, where the bad data was born — stays alive and keeps spawning new symptoms.

The fix is to stop outsourcing the thinking part of debugging. Use AI as a tool inside a process you control.

The Systematic 5-Step Debugging Approach

Step 1: Reproduce Reliably

You cannot fix what you cannot reproduce. Before anything else, get the bug to happen on demand.

Write down:

The exact steps that trigger it
The exact input values
The expected output
The actual output (including error messages and stack traces)

Then try to shrink it. This is called a minimal reproduction case (MRC). Remove everything that isn't part of the bug. If the bug shows up when you submit a form with 20 fields, can you reproduce it with 3? With 1? The smaller the MRC, the faster every subsequent step goes.

If you can't reliably reproduce it, don't skip to "fix." Keep poking until you can. An intermittent bug you can't reproduce is a bug you cannot verify you've actually fixed.

Step 2: Isolate the Scope

Once you can reproduce, figure out where the bug lives. The answer is almost never "the whole codebase."

Techniques that work:

Binary search. Comment out half the code path. Does the bug still happen? If yes, it's in the remaining half. If no, it's in the commented half. Keep halving until you land on it.
Logs at boundaries. Put a console.log at the entry and exit of each function in the suspect path. Print the inputs and outputs. The bug is between the last log that looks right and the first log that looks wrong.
Git bisect. If it used to work and now doesn't, git bisect will pinpoint the commit that introduced the bug.

// Suspect path: submit -> validate -> calculateTotal -> persist
function handleSubmit(order) {
  console.log('[submit] input:', order);
  const valid = validate(order);
  console.log('[submit] validated:', valid);
  const total = calculateTotal(valid);
  console.log('[submit] total:', total);
  return persist(valid, total);
}

Boring? Yes. Effective? Extremely. Four logs will usually cut the search space in half.

Step 3: Form a Hypothesis (Not a Guess)

Once you've narrowed the scope, stop and think. Before you change any code, write down:

What do I think is happening? In one sentence.
What would prove me right? A specific log value, a specific state, a specific code path.
What would prove me wrong? Because you might be wrong, and you want to know fast.

This sounds fussy. It isn't. The difference between a hypothesis and a guess is that a hypothesis is falsifiable. "Maybe the discount is being applied twice" is a hypothesis — you can check it. "Something's wrong with the pricing" is a vibe, and vibes lead to vibe-fixes.

Step 4: Verify With Evidence, Not Vibes

Test the hypothesis against reality. Read the actual values. Don't assume, observe.

console.log the specific variable at the specific line
Drop a debugger; statement and step through in DevTools
Set a breakpoint in your editor's debugger

This also applies to AI output. If the AI says "the bug is that discount is undefined at this line," don't just trust it — console.log(discount) and see. AI is often close but not exactly right, and acting on a confident wrong diagnosis wastes more time than verifying it.

Trust but verify applies to AI the same way it applies to your own assumptions.

Step 5: Fix the Root, Not the Symptom

Once you've confirmed the hypothesis, resist the urge to patch the nearest visible symptom. Trace upstream.

If a function returned a wrong number, don't add if (total < 0) total = 0 in the caller. Ask: why did it return a wrong number? Where did the bad input come from? Fix it there.

A common anti-pattern: wrapping symptoms in if-statements and try/catches. It feels like progress because the error goes away. But the bad data is still flowing through your system; you've just muffled its scream. A month later, the same root cause shows up in a different shape.

How to Use AI Effectively During Debugging

AI belongs inside this process, not on top of it. Use it like a sharp tool with a specific job:

Give AI the MRC, not the whole file. A 10-line reproduction is easier for both of you to reason about than 400 lines of context.
Share the actual evidence. The error message, the stack trace, the input values, the expected vs actual output. Not "it doesn't work."
Ask AI to explain its hypothesis before writing code. "What do you think is happening, and why?" If the explanation doesn't match what you've observed, don't let it write the fix.
If the fix doesn't work, go back to Step 1. Don't ask AI to "try again." That's how you end up with ten rounds of whack-a-mole. If the fix failed, your hypothesis was wrong. Re-reproduce, re-isolate, re-hypothesize.

Also: good tests make debugging dramatically faster, because they tell you which parts of the code are already proven to work. Tests catch regressions while you debug, so you're not accidentally breaking other things while chasing the current bug.

A Real Debugging Example

Let's make this concrete. Here's a function an AI generated for calculating an order total with a discount:

// pricing.ts
export function calculateTotal(
  price: number,
  quantity: number,
  discountPercent: number
): number {
  const subtotal = price * quantity;
  const discount = subtotal * (discountPercent / 100);
  return subtotal - discount;
}

Your users are reporting that when they apply no discount, the total comes out as NaN. Let's walk through the 5 steps.

Step 1 — Reproduce. In a test or a REPL:

calculateTotal(100, 2, 0);    // expected: 200, actual: NaN
calculateTotal(100, 2, null); // NaN
calculateTotal(100, 2);       // NaN

Confirmed: it breaks when discountPercent is 0, null, or missing.

Step 2 — Isolate. Add logs:

console.log('price:', price, 'quantity:', quantity, 'discount%:', discountPercent);
const subtotal = price * quantity;
console.log('subtotal:', subtotal);
const discount = subtotal * (discountPercent / 100);
console.log('discount:', discount);

Output for the zero case shows subtotal: 200, discount: 0, total: 200. So the zero case is actually fine. It's the missing case that prints discount: NaN, because undefined / 100 is NaN.

Step 3 — Hypothesis. When discountPercent is undefined (not passed in), undefined / 100 produces NaN, which then contaminates subtotal - discount.

Step 4 — Verify. console.log(undefined / 100) in DevTools → NaN. Confirmed.

Step 5 — Fix the root. The root cause is that the function doesn't handle the "no discount" case. Don't patch the caller; fix the signature:

// pricing.ts
export function calculateTotal(
  price: number,
  quantity: number,
  discountPercent: number = 0
): number {
  const subtotal = price * quantity;
  const discount = subtotal * (discountPercent / 100);
  return subtotal - discount;
}

One character fixed the bug. But you wouldn't have known which character without the 5 steps. Notice how much more useful this is than pasting "my total is NaN, fix it" into the AI — which might have rewritten the whole function, added a try/catch, or coerced every input to a number just in case.

Debugging Tools Vibe Coders Should Know

A small toolkit goes a very long way:

Browser DevTools. Console, Network, Sources. Learn the Sources tab specifically — breakpoints, watch expressions, and the call stack will save you more time than any AI prompt.
Strategic console.log. Log at boundaries, print the variable name with the value (console.log('user:', user)), and clean up when you're done.
The debugger statement. Drop debugger; anywhere in your code and execution will pause there when DevTools is open. Step through line by line.
Error tracking (Sentry free tier). Captures errors from real users in production with full stack traces and the state at the moment of failure. You stop debugging in the dark.

Honest truth: for a lot of everyday bugs, a developer who knows DevTools is faster than any AI. The AI has to reason about possibilities. You can look at the actual value.

When Debugging Reveals Architectural Problems

Sometimes the problem isn't the bug in front of you. It's the shape of the code around it.

Watch for these signals:

You keep fixing bugs in the same file or module
Every fix breaks two other things
You can't explain how the data flows from input to output
The same logic is duplicated in three places, and you have to fix each one

When this happens, debugging is telling you something bigger: the code is tightly coupled, the abstractions are missing, the data flow is unclear. These are signs that refactoring — not more patches — is the real fix.

And if every bug fix seems to break something else, you might be past the point where you can debug your way out of it. That's when it's time to bring in help to stabilize the codebase before you keep shipping on top of it.

Closing

Debugging is a skill, not a magic AI trick. Each bug you debug properly makes you measurably better at the next one — you build intuition about where bugs hide, which tools to reach for, and which AI fixes to trust.

AI accelerates debugging when you use it inside a real process. It replaces debugging when you use it instead of one. The difference is whether you're in control, or whether you're stuck in a loop asking "fix it" until the code is unrecognizable and the bug is still there.

Next time something breaks: reproduce, isolate, hypothesize, verify, fix the root. In that order. Every time.

Originally published at bivecode.com. If you're struggling with an AI-built codebase that's become unmanageable, BiveCode Rescue can help.

Why AI Coding Goes Off the Rails — And How to Take Back Control

Junkyu Jeon — Thu, 16 Apr 2026 06:44:54 +0000

The Honeymoon Phase

You remember the moment. You opened Cursor, or Bolt, or Claude for the first time, typed something like "Build me a landing page with a hero section and a pricing table," and watched as fully functional code materialized in front of you. In minutes, not hours.

You kept going. "Add a contact form." Done. "Make it responsive." Done. "Add dark mode." Done. You felt like a 10x developer. The possibilities felt limitless. You started telling friends about it. You stayed up late building things you'd been putting off for months.

This phase is real. It's not a trick. AI coding tools genuinely are that powerful for getting something off the ground. The problem is what happens next.

When Things Start Breaking

It's subtle at first. Around the time your project hits 20-30 files, something shifts. The AI that was nailing everything starts... stumbling.

You notice it in small ways:

It forgets decisions it made earlier. You established a pattern for how components fetch data, but the AI starts using a completely different approach in new files.
It contradicts its own patterns. Half your files use one error-handling style, the other half use another. Neither is wrong, but the inconsistency makes everything harder to follow.
It breaks existing features while adding new ones. You ask for a new settings page and suddenly your authentication stops working.
Its fixes create new problems. You point out a bug, it patches it, and now something else is broken. You fix that, and the original bug comes back.
It goes in circles. Fix this, breaks that. Fix that, breaks this. You spend an hour and end up back where you started, except now the code is messier.

If this sounds familiar, you're not alone. This is the experience of almost every developer who uses AI tools on a project beyond a certain size. And it's not because the AI got dumber or because you're doing something wrong.

Why This Happens: The Context Problem

Here's the thing most people don't understand about AI coding tools: they have a limited working memory.

AI models operate within something called a context window — the amount of text they can "see" and think about at any given time. Think of it like a desk. When your project is small, all your files fit on the desk. The AI can see everything at once — every component, every function, every decision you've made together.

But as your project grows, files start falling off the desk. The AI can only look at a slice of your codebase at a time. It literally cannot see what's in the other files. It doesn't know what patterns were established. It doesn't remember what constraints exist. It doesn't recall the naming conventions you agreed on three sessions ago.

It's like asking someone to renovate your house, but they can only see one room at a time. They might pick a great paint color for the kitchen — that clashes horribly with the living room they can't see.

And here's the part that really stings: each conversation starts fresh. When you open a new chat or start a new session, the AI has zero memory of your previous interactions. It doesn't know about the bug you spent two hours fixing yesterday. It doesn't know about the architectural decision you made last week. Every time, it's meeting your project for the first time.

This isn't a flaw that'll be fixed in the next update. It's a fundamental characteristic of how these models work. And once you understand it, the frustrating behavior makes perfect sense.

The Snowball Effect

Here's where it gets really painful. When things break, the natural instinct is to tell the AI: "Fix it." And the AI obliges — it patches the immediate symptom. But because it can't see the full picture, it's not fixing the root cause. It's applying a band-aid.

Each band-aid adds complexity. And that complexity makes it even harder for the AI to understand the codebase on the next request. So the next fix is even more likely to be a band-aid. And the cycle continues:

Something breaks
AI patches the symptom
The patch adds complexity
The added complexity causes something else to break
Go to step 1

Your codebase becomes a patchwork of contradictory patterns, redundant logic, and fragile workarounds. Eventually the AI is spending more tokens trying to understand the mess than actually solving the problem you asked about.

This is why vibe coding hits a wall. Not because AI is bad at coding. Not because you're not technical enough. But because the approach of "just keep prompting" doesn't scale. The more you build, the less effective each prompt becomes, until you're fighting the tool instead of building with it.

The Shift: From Prompting to Harness Engineering

When people hit this wall, their first instinct is to write better prompts. More detailed instructions. Longer explanations. "Be very careful not to break the auth system when you add this feature."

This helps a little. But it's treating the symptom, not the disease. You can't prompt your way out of a structural problem.

The real unlock is something we call harness engineering — designing the environment and structure that the AI works within.

Think about it this way:

Prompt engineering is telling the AI what to do.
Harness engineering is setting up where and how the AI works.

A "harness" is everything that surrounds the AI: the project structure, the rules it follows, the context it receives, the guardrails that catch its mistakes. It's the difference between dropping a builder in an empty field and saying "build a house," versus handing them blueprints, a materials list, and a building code.

When you invest in the harness, the AI performs dramatically better — even with the exact same prompts you were using before. Because the environment compensates for the AI's limitations.

Here's what harness engineering looks like in practice:

CLAUDE.md / .cursorrules files that give the AI persistent context about your project — your tech stack, your conventions, your constraints. Things the AI would otherwise forget between sessions.
Clean folder structure so the AI only needs to see the relevant files for any given task, keeping more of the important context on that "desk."
Module boundaries that limit the blast radius of AI changes. If the AI makes a mistake in the settings module, it shouldn't be able to break authentication.
Test suites that catch when the AI breaks something, before you even notice.
Memory systems that preserve decisions across sessions — so the AI doesn't have to rediscover your architecture every time.

None of these require you to be a senior engineer. They require you to think like an architect, not a prompter.

Practical Steps to Take Back Control

You don't need to rebuild everything from scratch. Here are concrete things you can do today to improve how AI works with your project:

1. Set Up a CLAUDE.md or .cursorrules

This is the single highest-leverage thing you can do. Create a file that tells the AI everything it keeps forgetting: your tech stack, your folder structure, your naming conventions, your patterns, your constraints. The AI reads this at the start of every session, giving it the context it would otherwise lack.

We wrote a full guide on how to do this well: How to Make AI Tools Understand Your Codebase.

2. Break Your Project Into Modules

Smaller, self-contained pieces mean less context needed per task. When your auth logic is in its own module with clear boundaries, the AI can work on it without needing to understand your entire app. Feature-based folder structure is a great starting point — see our guide on how to structure your AI project.

3. Give AI One Job at a Time

Instead of "Build the auth system with social login, password reset, 2FA, and admin panel," try:

"Add a basic email/password login page"
"Add password reset functionality"
"Add Google OAuth login"

Each focused request is more likely to succeed because it requires less context and produces smaller, more reviewable changes.

4. Add Tests Before Adding Features

Tests are your safety net. When the AI changes something, tests tell you immediately if it broke something else. You don't need 100% coverage. Even basic tests for your critical paths — login works, data saves correctly, pages load — will catch the most damaging regressions.

5. Review Before Accepting

This is the hardest habit to build. AI-generated code comes out fast and looks professional, so it's tempting to accept it without reading. Don't. Spend 30 seconds scanning each change:

Does it follow your existing patterns?
Did it change files it shouldn't have touched?
Does the logic actually make sense, or does it just look right?

You don't need to understand every line. But you should understand the shape of the change.

6. Version Control Religiously

Commit every working state. Every one. When the AI inevitably breaks something, you can roll back to the last good version instead of trying to untangle the damage. git commit is your undo button. Use it early and often.

The Mindset Shift

Here's the most important thing to internalize: you're not a prompter. You're an architect.

The AI is the builder. It's fast, it's capable, and it works tirelessly. But builders need blueprints. They need someone who understands the whole structure, who can see across all the rooms at once, who makes sure the kitchen paint works with the living room.

That's you.

The best AI-assisted developers don't write the most code. They don't write the fanciest prompts. They design the best structures for AI to work within. They set up the harness so well that the AI almost can't fail.

And that's a skill worth developing — because as AI tools get better, the people who know how to direct them effectively will build things the rest of the world didn't think were possible.

If your project has already gone off the rails and you're not sure how to get it back on track, we can help. We specialize in taking AI-built codebases and giving them the structure they need to keep growing.

And if you want to prevent this from happening on your next project, start with our guide on how to structure your AI project from day one.

Originally published at bivecode.com

Cursor Rules vs CLAUDE.md: When to Use Which (And How They Work Together)

Junkyu Jeon — Thu, 16 Apr 2026 06:39:12 +0000

If you're using AI coding tools seriously, you've probably heard of both .cursorrules and CLAUDE.md. They solve the same fundamental problem: giving AI persistent context about your project.

Without them, every AI session starts from scratch. The AI doesn't know your tech stack, your folder conventions, your naming patterns, or the quirks that make your project unique. You end up repeating the same instructions over and over.

Both files fix this. But they work differently, they're read by different tools, and they have different strengths. Most developers pick one and ignore the other. That's a mistake — they're most powerful when used together.

What .cursorrules Does

.cursorrules is Cursor's project-level configuration file. When you open a project in Cursor, it automatically reads this file and applies the rules to every AI interaction within that project.

Key characteristics:

Tool-specific — only Cursor reads it. Other AI tools ignore it completely.
Instruction-focused — best for telling the AI what to do and what not to do.
Applies to all interactions — every chat, every inline edit, every Cmd+K generation follows these rules.
Supports glob patterns — you can scope rules to specific file types or directories.

A typical .cursorrules:

You are an expert in TypeScript, React, Next.js App Router, and Tailwind CSS.

Key Principles:
- Write concise, technical TypeScript code
- Use functional and declarative programming patterns
- Prefer iteration and modularization over duplication
- Use descriptive variable names with auxiliary verbs (isLoading, hasError)

Naming Conventions:
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with "use" prefix (useAuth.ts)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE

DO NOT:
- Use `any` type
- Use default exports (except for pages)
- Put business logic in components
- Use inline styles

What CLAUDE.md Does

CLAUDE.md is Claude's project context file. Claude Code, Claude in the terminal, and other Claude-powered tools read it automatically when they enter your project directory.

Key characteristics:

Tool-specific — Claude tools read it. Cursor doesn't (unless you explicitly include it in context).
Context-focused — best for explaining your project's architecture, decisions, and constraints. Not just rules, but why those rules exist.
Hierarchical — you can have a root CLAUDE.md plus subdirectory-specific ones (e.g., src/components/CLAUDE.md). Claude merges them based on what files it's working with.
Supports project commands — you can define shortcuts for common tasks like building, testing, and deploying.

A typical CLAUDE.md:

# Project Overview
Next.js 15 SaaS app for invoice management.
- Frontend: React 19, TypeScript, Tailwind CSS
- Backend: Next.js API routes, Drizzle ORM
- Database: PostgreSQL (Supabase)
- Auth: Better Auth with Google OAuth
- Payments: Stripe
- Deployment: Vercel

# Architecture
Feature-based folder structure:
src/
  app/         # Pages and API routes
  features/    # Feature modules (auth/, billing/, invoices/)
  components/  # Shared UI components
  lib/         # Utilities, DB client, API helpers

# Important Constraints
- Auth middleware runs on Edge Runtime — no Node.js APIs
- All monetary values stored as integers (cents), displayed as decimals
- Invoices use optimistic locking — always check version before update

# Commands
- Build: npm run build
- Test: npm run test
- Dev: npm run dev

The Key Differences

Aspect	.cursorrules	CLAUDE.md
Read by	Cursor only	Claude tools only
Primary strength	Coding rules and patterns	Project context and architecture
Tone	Imperative ("Do this, don't do that")	Descriptive ("Here's how the project works")
Hierarchy	Single file at project root	Root + subdirectory files, merged contextually
Best for	Enforcing code style and patterns	Explaining architecture and constraints
Project commands	Not supported	Supported (build, test, lint)
Glob scoping	Supported	Via subdirectory files

When to Use Which

Use .cursorrules when:

Your team primarily uses Cursor as their AI coding tool
You want to enforce strict coding patterns across all AI interactions
Your rules are mostly about code style: naming, imports, error handling patterns
You want rules that apply to inline edits and quick generations, not just chat

Use CLAUDE.md when:

Your team uses Claude Code or Claude-powered tools
You need to document complex architecture that requires explanation, not just rules
Your project has non-obvious constraints (edge runtime limitations, data format decisions, etc.)
You want project commands integrated into the AI workflow
Different parts of the codebase need different context (use subdirectory CLAUDE.md files)

Use both when:

Team members use different AI tools (some on Cursor, some on Claude)
You want consistent AI behavior regardless of which tool is used
You want the best of both: Cursor's pattern enforcement + Claude's architectural context

How to Use Them Together

Here's the approach that works best: put architectural context in CLAUDE.md, put coding rules in .cursorrules, and keep them in sync.

What goes in CLAUDE.md only:

Project overview and tech stack
Architecture decisions and their reasoning
Non-obvious constraints ("monetary values are stored as cents because...")
Common tasks with step-by-step instructions
Build/test/deploy commands

What goes in .cursorrules only:

The persona prompt ("You are an expert in...")
Cursor-specific behaviors (how to handle inline edits, tab completions)

What goes in both (keep synced):

Naming conventions
Folder structure
Import patterns
Error handling approach
"Do not" rules

Yes, there's some duplication. That's the cost of supporting multiple tools. The alternative — having rules in one file and not the other — means your AI behavior is inconsistent depending on which tool you're using. That's worse.

Keeping them in sync

The practical approach: treat CLAUDE.md as the source of truth for architecture and constraints, and .cursorrules as the source of truth for coding patterns. When you update a shared rule (like naming conventions), update both files. It takes 30 seconds and prevents drift.

Common Mistakes

1. Making them too long

Both files compete for the AI's attention window. A 2,000-line rules file means the AI is spending context on your instructions instead of on understanding the code it's working with. Aim for 200-500 lines max for each file.

2. Being vague

"Write clean code" is useless in both files. "Use named exports for all non-page files" is actionable. Be specific enough that there's only one way to interpret the rule.

3. Never updating them

Your project evolves. Your rules should too. If you switched from REST to tRPC three months ago but your CLAUDE.md still describes REST patterns, the AI will generate REST code. Review your files monthly.

4. Not including examples

AI tools are pattern matchers. A rule like "use the repository pattern for database access" is vague. A rule with a 5-line code example of what that looks like in your project is crystal clear.

Getting Started Today

If you have neither file, here's the 30-minute setup:

Create CLAUDE.md — write your project overview, tech stack, folder structure, and top 5 constraints.
Create .cursorrules — write your coding conventions, naming rules, and "do not" list.
Copy shared rules — naming conventions, folder structure, and import patterns should appear in both.
Test it — ask both tools to create a new component. Does the output match your conventions? If not, your rules aren't specific enough.

If you already have one file, creating the other takes 15 minutes — most of the thinking is already done.

For a deeper dive into CLAUDE.md specifically, check out our CLAUDE.md setup guide.

Originally published at bivecode.com

The Vibe Coding Security Checklist: 7 Things to Check Before You Ship

Junkyu Jeon — Thu, 16 Apr 2026 06:36:05 +0000

Here's a stat that should keep you up at night: 24.7% of AI-generated code contains security vulnerabilities. Nearly 45% of those hit the OWASP Top 10 — the most common, most exploitable categories of web security flaws.

This isn't because AI is bad at coding. It's because AI optimizes for making things work, not making them safe. When you ask it to "add a user login," it builds a functional login. It doesn't think about session fixation, brute force protection, or what happens when someone puts a SQL statement in the email field.

If you've built an app with Cursor, Bolt.new, Lovable, or any AI coding tool and you're about to ship it to real users — run through this checklist first. Each item takes 5-15 minutes. All of them together could save you from a breach that kills your product.

1. Secrets Are Not in Your Code

This is the most common and most dangerous mistake in AI-built apps. AI tools love to hardcode API keys, database URLs, and secrets directly in the source code.

Check for:

API keys in JavaScript/TypeScript files (search for sk-, pk_, key_, secret)
Database connection strings in source code
JWT secrets hardcoded in auth files
Third-party service credentials (Stripe, SendGrid, AWS) in client-side code

How to fix:

# Search your codebase for exposed secrets
grep -rn "sk_live\|sk_test\|password\|secret\|api_key\|apiKey" src/

# Move all secrets to environment variables
# .env.local (never committed to git)
DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...
JWT_SECRET=your-secret-here

# .gitignore (make sure this exists)
.env
.env.local
.env.production

Critical: If secrets were ever committed to git, they're in the history even after removal. Rotate them immediately — generate new keys and revoke the old ones.

2. All User Input Is Validated

AI-generated code almost never validates input properly. It trusts whatever the user sends, which opens the door to injection attacks, crashes, and data corruption.

Check for:

Form inputs used directly without validation
API route parameters used without type checking
Database queries built from user input (SQL injection risk)
File uploads without type/size restrictions

How to fix:

// Use Zod for input validation in API routes
import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email().max(255),
  name: z.string().min(1).max(100),
  age: z.number().int().min(13).max(150).optional(),
});

export async function POST(request: Request) {
  const body = await request.json();
  const result = CreateUserSchema.safeParse(body);

  if (!result.success) {
    return Response.json(
      { error: result.error.flatten() },
      { status: 400 }
    );
  }

  const { email, name, age } = result.data;
  // ... safe to use
}

Validate on the server, always. Client-side validation is for UX — server-side validation is for security. Never trust the client.

3. Authentication Is Actually Protecting Routes

AI tools often generate auth that looks right but has gaps. The login page works, but the API routes behind it? Wide open.

Check for:

API routes that should require authentication but don't check for a session
Middleware that checks auth on some routes but misses others
Admin-only endpoints accessible to regular users (broken access control)
Direct object references — can user A access user B's data by changing an ID in the URL?

Quick test: Open your browser's dev tools, find an API call your app makes, copy it as a cURL command, remove the auth cookie/token, and run it. If it still returns data, your route isn't protected.

// Every protected API route should start with this
export async function GET(request: Request) {
  const session = await getSession(request);
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // For user-specific data, always filter by the authenticated user
  const data = await db.query.items.findMany({
    where: eq(items.userId, session.user.id), // NOT from URL params
  });

  return Response.json(data);
}

4. No Sensitive Data in Client-Side Code

Everything in your frontend JavaScript is visible to anyone who opens dev tools. AI tools frequently put things on the client side that should stay on the server.

Check for:

API keys in .env files prefixed with NEXT_PUBLIC_ that shouldn't be public
Business logic that reveals pricing algorithms, discount rules, or internal calculations
Error messages that expose database schema, file paths, or internal system details
User data from other users leaking into API responses (overfetching)

How to fix:

Only prefix env variables with NEXT_PUBLIC_ if they're truly meant to be public
Move business logic to server-side API routes or server components
Return generic error messages to the client, log detailed errors on the server
Shape API responses to include only what the requesting user needs to see

5. Rate Limiting Exists

Without rate limiting, anyone can hammer your API thousands of times per second. This leads to DDoS vulnerability, brute force attacks on login, and runaway costs on pay-per-use services (like AI APIs).

AI-generated code almost never includes rate limiting.

What to protect:

Login/signup endpoints — prevent brute force (5-10 attempts per minute)
AI generation endpoints — prevent cost abuse
Password reset — prevent email bombing (2-3 per hour)
General API — prevent abuse (100-1000 requests per minute)

// Using Upstash Redis for serverless rate limiting
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '1 m'),
});

export async function POST(request: Request) {
  const ip = request.headers.get('x-forwarded-for') ?? '127.0.0.1';
  const { success } = await ratelimit.limit(ip);

  if (!success) {
    return Response.json(
      { error: 'Too many requests' },
      { status: 429 }
    );
  }
  // ... handle request
}

6. Dependencies Are Not a Liability

AI tools add npm packages liberally. Each dependency is code you didn't write running in your app. Some may have known vulnerabilities, be abandoned, or even be malicious.

# Check for known vulnerabilities
npm audit

# See what you've got installed
npm ls --depth=0

# Check for unused dependencies
npx depcheck

Fix critical and high vulnerabilities. Remove packages you don't use.

7. HTTPS, Headers, and CORS Are Configured

The boring infrastructure stuff that AI never sets up but attackers always check.

Essential security headers (add to next.config.ts):

const securityHeaders = [
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-XSS-Protection', value: '1; mode=block' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
];

const nextConfig = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};

CORS: If your API is only used by your own frontend, don't enable CORS at all. If you need CORS, whitelist specific origins — never use * in production.

The 15-Minute Security Sprint

If you can only do one thing from this list, here's the priority order:

Secrets audit (5 min) — grep for exposed keys. Highest-impact, easiest-to-exploit.
Auth check (5 min) — test your API routes without authentication. Find the gaps.
Input validation (5 min) — add Zod to your most critical endpoint.

These three catch the majority of real-world attacks on AI-built apps.

A security breach doesn't just break your app. It breaks trust. Users whose data gets leaked don't come back.

AI made it possible to build an app in a weekend. But shipping it without a security review is like driving a car without brakes — it works fine until it doesn't, and when it fails, it fails catastrophically.

Spend the hour. Run the checklist. Ship with confidence.

Originally published at bivecode.com