The Complete Guide to Vibe Coding Tech Debt
From planning to maintenance, how to talk to AI at every stage
黃志弘 Leo
Published 2026-03-30 · 1 readers
?What is tech debt?
Vibe coding is like having someone else clean your whole house. It looks tidy, but you have no idea where any of the details went. Then one day you need one thing, and you turn the place over without finding it.
Code is the same, running is not the same as written well. Once the style is inconsistent and messy, problems surface one by one the longer it runs. The more you pile up, the harder it gets to maintain.
Why vibe coding runs up debt so fast
AI always hands you the fastest fix for right now, not the best architecture for the long run. You say add a feature, it adds one, and it may fight with logic you already had. You do not notice until the day the whole thing breaks.
Traditional engineers have code review and a team checking each other. One person vibe coding has none of that layer, you are the engineer, the QA, and the PM, all at once.
Demo or product?
If you are only building a toy for yourself, tech debt does not matter. But once people use it and people pay for it, your code is the foundation, and a crooked foundation brings the building down sooner or later.
Real cases: a database wiped three times, a broken backup system, weak security that let attackers in. Same feature, one way of writing it costs NT$10,000 a month, another needs under NT$900. That gap is the price of no maintenance and piled-up tech debt.
1Before you start: planning
Do this before the first line of code
Let the AI interview you first
Do not tell it to write yet. Let it ask you questions first and get the requirements clear.
I want to build [what you want].
Before you write any code, please:
1. Ask me a few key questions (tech choices, edge cases, data flow)
2. Plan the overall architecture for me (folder structure, tech stack)
3. List a suggested build order (what to do first, what comes next)
4. Tell me the problems I am likely to hit
5. Wait for my confirmation before you start writingWrite a solid CLAUDE.md
This file is your project rulebook, and the AI reads it at the start of every session. Write it well and it will not go off the rails.
# Project name
One sentence describing this project
## Tech stack
- Framework: Next.js 15
- Database: Supabase
- Styling: Tailwind
## Folder structure
- src/app/ — routes
- src/components/ — shared components
- src/lib/ — business logic
## Commands
- npm run dev — local development
- npm run test — run tests
## Rules
- All database access goes through src/lib/db/
- Do not add new packages on your own, ask me first
- Error handling must carry context, never swallow it silently
- Run typecheck after changing code
## Do not
- Do not use the any type
- Do not bypass Supabase RLS
- Do not commit straight to mainUse Plan Mode
Have the AI lay out a plan and confirm it before anything moves. Do not let it think and write at the same time.
Enter Plan Mode first, do not touch code.
After reading [the relevant files], answer me:
1. Which files does this feature need to change?
2. What is the full path of the data, from user action to database?
3. Where could it go wrong?
4. What existing patterns in the codebase should be followed?
List the plan and wait for my confirmation before you start.2During development: while you write code
What to watch every time you add a feature
How to ask for a feature properly
Do not just say add a feature. Tell it what to look at and what pattern to follow.
| Weak way to say it | Better way to say it |
|---|---|
| Add a calendar for me | Look at how DatePicker in src/components/ is built, make a calendar the same way, and add matching tests |
| Fix the login bug | Login fails after the session expires. Read the token refresh logic in src/auth/, write a test that reproduces it first, then fix the root cause |
| Make this page look better | Bump the heading to 24px, round the buttons to 12px, change the background to #1a1a2e |
Mid-task check (keeps the mess from spreading)
Hold on, look at the [file] you just wrote.
Compare it with [another file doing something similar]. Is the style consistent?
If not, which style should be the standard, and why?I noticed you also changed [X], but I only asked you to change [Y].
Was that change necessary? If not, revert it.
We only change what this task needs.Commit after every finished thing
Do not change ten things before you save. Commit after each feature, so you can roll back when it breaks.
Commit what we just did. The message should say why it changed, not only what changed.
Format: feat: / fix: / refactor:
Do not commit any unfinished code or commented-out code.Which code needs extra care
| Level | Scope | How to check |
|---|---|---|
| 🟢 Safe | Templates, tests, docs, config | A quick glance is enough |
| 🟡 Careful | Business logic, APIs, database | Read line by line, confirm the logic |
| 🔴 Dangerous | Login, payments, encryption, security | Write it yourself, or security review whatever the AI writes |
3Mid-review: the regular checkup
Every 2-4 weeks
The tech debt cleanup prompt
Ask the AI to check everything, but not to fix anything yet. Read the report, then decide.
Run a tech debt review, do not change anything yet.
Check:
1. Style consistency: error handling, database access, API responses, how many different styles does each one have? More than 3 = a problem
2. Understanding: for functions over 50 lines or files over 300 lines, can you explain in plain words what each one does?
3. Tests: which important features have no tests? Which tests only cover the happy path and skip the edges?
4. Dead code: which functions or files are never used?
5. Security: is every user input validated?
6. Packages: run npm audit and check for known vulnerabilities
Give me a prioritized list, high / medium / low, and do not fix anything yet.One-line scoring
You are a senior full-stack engineer
review my code
check whether the frontend and backend are consistent in style and logic
give me a score out of 1-10
and tell me what is driving up my costs and will be hard to maintain laterSafe refactoring steps
We are refactoring [which module].
Before you touch it:
1. Run the existing tests, confirm they all pass
2. If the tests are thin, write new ones recording current behavior first
3. Only then start changing, one thing at a time
4. Run the tests after every change
5. If any test that passed before breaks, stop and tell me4Maintenance: long-term health
Once a month
One-shot health report
Run a health check:
1. Package freshness: npm outdated, flag anything more than 2 major versions behind
2. Type safety: npx tsc --noEmit, list every type error
3. Code quality: npm run lint, list warnings and errors
4. Test status: npm test, pass rate and flaky tests
5. Dead code: are there exports nobody uses
Sum it up in one line: is this codebase healthy, sliding, or in crisis?Security scan prompt
Act as a security reviewer and read [auth, API, and database-related files].
Check:
1. Is every user input validated?
2. Are there hardcoded secrets or API keys?
3. Are all SQL queries parameterized?
4. Is there any way to bypass login?
5. Do error messages leak sensitive information?
6. Run npm audit for known vulnerabilities
For each finding: severity + file location + suggested fix
Do not fix anything, just give me the report.!Warning signs
Two or more of these and it is time to stop and clean up
☐ You change one place and another breaks
☐ Adding a feature takes longer and longer
☐ Some of the code no longer makes sense even to you
☐ The same problem is solved a different way in different places
☐ Tests pass but you are not sure the feature is actually right
☐ Code you wrote needs a rewrite within two weeks
☐ 80% of your time goes to going back and forth with AI, 20% to understanding the code