Guides

Why AI-built apps fall apart, and a checklist to make yours last

The short answer: AI-built apps usually fall apart because nothing was written down, nothing was checked and nothing could be undone. Fix those three things early and the app can keep growing.

Key points

  • Write it down first: a short CLAUDE.md, and a plan file for each larger feature.
  • Add checks that run by themselves, and ask for the check after every change.
  • Save versions in Git, and keep a copy somewhere other than your laptop.
  • Do clean-ups on their own, not mixed with new features.
On this page
  1. Why do apps built with AI fall apart?
  2. What is the first thing to fix?
  3. How do I make sure it keeps working?
  4. How do I make changes safe to undo?
  5. How do I keep the code tidy?
  6. What about secrets and access?
  7. How do I keep my own knowledge?
  8. When should I rebuild instead?
  9. The checklist

Why do apps built with AI fall apart?

Not because the AI is bad. They fall apart because building fast skips the boring parts that keep a project steady. These are patterns, not statistics: I have not counted them, and you will see them in many projects.

  1. Nothing is written down. Claude starts each session with a fresh memory. The docs say each Claude Code session begins with a fresh context window (memory docs). If your decisions only exist in old conversations, the next session decides again, differently.
  2. Nothing is checked. The best-practices page says that without something to run that returns pass or fail, “looks done” is all Claude has (best practices). Each new feature quietly breaks an old one, and nobody notices until a user does.
  3. Nothing can be undone. Without saved versions, a bad change on a Friday night becomes a rebuild.
  4. Everything is in one big pile. Fast building adds code wherever it fits. After a few weeks even Claude has trouble finding what depends on what.
  5. Secrets and access are an afterthought. Keys end up in the code, and anyone signed in can see everything.
  6. Nobody knows why. Months later, no one can say why it works the way it does, so every change is a risk.

What is the first thing to fix?

Write it down. Create a CLAUDE.md with the commands that run and check your app, the decisions already made and the traps. Keep it short: the docs target under 200 lines. See our guide on how to write a CLAUDE.md that works.

Then write a plan file for each larger feature before you build it. A plan is a record of what you decided and why, and it is the document you will thank yourself for in a month.

How do I make sure it keeps working?

Add checks that run by themselves. Ask Claude:

Ask Claude

Add automated tests for the most important things this app does, and a single command that runs them all. Put that command in CLAUDE.md.

From then on, ask for the check after every change. The docs list what can serve as a check: a test file, a build’s exit code, a linter, a comparison script or a screenshot. Ask for evidence, not “all good”: the command that ran and its output.

Note

Tests are not magic. They only catch what they cover. But a small set that covers the main path already stops the most common failure, which is breaking something old while adding something new.

How do I make changes safe to undo?

Use Git, the standard way of saving versions of a project. Ask Claude to set it up and commit after every working change with a clear message. Claude Code’s own /rewind helps inside a session, but the docs say checkpoints work alongside version control and don’t replace it, and files changed only by commands aren’t restored (checkpointing docs).

Also keep a copy of your project somewhere other than your laptop, such as a private repository on a hosting service. A stolen or broken laptop should never be the end of the app.

How do I keep the code tidy?

You don’t need to read it. Do three things:

  • Ask Claude once in a while to list the biggest or most tangled files, and to suggest small clean-ups with tests passing before and after.
  • Keep one folder or area per feature, and tell Claude in CLAUDE.md where things belong.
  • Delete what you don’t use. Ask Claude to find code and files nothing refers to, and to explain before removing.

Tip

Do clean-ups on their own, not mixed with new features. If something breaks, you will know which change did it.

What about secrets and access?

Keys and passwords never belong in the code. They live in a settings file or a secrets manager that is not saved to Git. Ask Claude to check for secrets in your project and in your Git history. Also check that each user can only see their own data. Broken access control is the first category in the OWASP Top 10:2025, the widely used list of the most critical web application security risks (OWASP). Our security checklist for AI-built apps goes through it.

How do I keep my own knowledge?

You are the one who knows what the app is for. Keep a short note, in the project, with:

  • Who the app is for and what they do in it.
  • The three to five things that must never break.
  • What you decided not to build.
  • Where the app runs, and how to put a new version live.

When Claude suggests something that goes against the note, you will see it. Without the note, you will not.

When should I rebuild instead?

Rarely, and only after you have written down what the app must do. If the checks you added keep failing, if every change breaks something else, and if a fresh look from an expert says the foundation is wrong, then rebuilding from a plan is cheaper than patching. Having the plan, the tests and the CLAUDE.md makes the rebuild far faster, because the knowledge is in files and not in your head.

The checklist

Run this with Claude, one line at a time. Ask it to show proof for each.

  • CLAUDE.md exists, under 200 lines, with the check command first.
  • A plan file exists for each feature you built or are building.
  • Tests cover the main path, and one command runs them.
  • The project is saved in Git, with a clear message per change, and a copy lives somewhere else.
  • No keys or passwords in the code or in Git history.
  • Each user can only see their own data (test it with two accounts).
  • The app tells users clearly when something fails.
  • You can say, in one paragraph, what it does and for whom.
  • Someone else could start working on it from the files alone.

If you can tick all nine, you are ahead of most projects of this kind. The point is not perfection. The point is that you can still change the app in six months without fear.