Appearance

Language

Build a personal website from 0

AI Built My Website and I Don't Understand the Code. How Do I Keep Maintaining It in 2026?

Maintain an AI-built site without reading every line: commit before changes, write decisions into an instruction file, spec first, make the AI run checks.

Kelvin Wang · · 16 min read

Key points

  1. Sites spiral because every session starts from zero, fixes target symptoms, and nothing tells you whether a fix actually worked.
  2. Commit before every AI change and read the diff after; built-in undo features help but don't replace git.
  3. Write decisions into CLAUDE.md, AGENTS.md or your tool's project rules so the next session doesn't reinvent them.
  4. Give the AI a check that passes or fails (build, tests), and ask for the command and its output as evidence.

This site has been written with AI coding agents since June 2026. By November it has close to 700 commits, and it’s still easy to change: a feature added yesterday doesn’t break last month’s pages, and a fresh session knows about decisions made three months ago. What holds that together is a handful of habits, and they have little to do with whether you can program. Each one below comes with how this repo actually does it, and they work the same in Claude Code, Codex, Cursor, v0 or Lovable.

Why does an AI-built site get worse with every fix?

It helps to name what’s decaying before fixing it. There are usually four causes:

  • Each fix targets the symptom. You say “the button is misaligned,” and the AI adds a style to that button. It doesn’t know the real cause is a layout setting three pages share, so it fixes one page and breaks another, then patches that in the next round. Patches pile on patches until even the AI misreads the code.
  • Decisions disappear when the chat ends. Every new session starts from zero. Last week you agreed on “only these three colors” or “visitors can’t read this table.” This week the AI doesn’t remember, and rewrites it the way it has seen most often.
  • Nothing tells you a fix worked. The AI says it’s done, you glance at the home page, it looks fine, you accept it. What broke is a page you didn’t open, and by the time you notice, you can’t tell which change did it.
  • There’s no save point. You want yesterday’s version back and find it was never saved. So you ask the AI to fix it again, which takes you back to the first cause.

None of these depends on whether you can read code, so the fixes don’t require you to learn programming first.

You don’t need to understand every line. You need every change to have a save point, a record and a check.

What should you do before every AI change?

Save a version first. Git is a save system for code: each commit is a save point you can return to. If you don’t have git yet, set it up with the AI coding setup guide.

Do every change in this order:

  1. Start clean. Run git status in the project folder and only start when it says nothing to commit, working tree clean. If there are unsaved changes, commit them first.
  2. Ask for one thing. “Make the post list two columns” is one thing. “Make it two columns, switch the font and fix mobile” is three, and if something breaks you won’t know which.
  3. Read the diff. Run git diff (or open the changes panel in VS Code or GitHub Desktop) and see which files changed. You don’t need to understand the content to check the scope: if you asked for a post-list change and it touched login code, stop and ask why.
  4. Commit if it’s right, throw it away if it isn’t. If it’s right, first make sure the .env file holding your keys is listed in .gitignore (see what breaks after launch), then git add -A and git commit -m "post list in two columns". If not, git restore . puts the files that already existed back to how they were at the last save, but files the AI newly created stay: list them with git clean -nd (-n only lists and deletes nothing; -d includes new folders), and once you’re sure, delete them with git clean -fd. If you already ran git add on these changes, run git restore --staged . first, or git restore . only takes you back to the moment you added them. What git restore . and git clean -fd discard can’t be recovered (git restore --staged . only unstages and discards nothing), and the Pro Git book explicitly calls git restore a dangerous command, so use them only when you’re sure1.
git status                       # 1. start clean
# … ask the AI for one change …
git diff --stat                  # 3. which files changed
git diff                         #    what changed
git add -A && git commit -m "post list in two columns"   # 4a. right: save
git restore --staged .           # 4b. wrong: if already added, unstage first
git restore .                    #     put existing files back
git clean -nd                    #     only list new files and folders, delete nothing
git clean -fd                    #     delete them, only once sure

If you’ve already committed the change and want to undo it, find the commit with git log --oneline, then run git revert --no-edit <commit id> (--no-edit keeps the default commit message instead of opening a text editor). Revert adds a new commit that reverses that change, and the original history stays. Each revert undoes one commit; to undo several, start from the newest and go one at a time. You can also ask the AI: “revert commit xxx, don’t use reset”, since reset rewrites history.

Most AI tools have their own undo, and it’s fine to use alongside git as long as you know its limits. For example, Claude Code’s /rewind restores files to before a given prompt, but it only tracks files changed through its file editing tools; files changed only by shell commands, or edited by you, aren’t covered, and the docs say checkpoints aren’t a replacement for version control2. Cursor’s checkpoints are stored locally and separately from git, and its docs say to use them only for undoing agent changes and to keep permanent history in git11. v0 creates a new version every time it updates code from a message, and restoring an old version creates a new latest version; code you edit directly doesn’t create a version3. These features rescue mistakes from this session, not from last month.

This site keeps changes small and commits often: close to 700 commits, most doing one thing, and some commit messages record how I asked for it. A commit from 2026-11-16, for example, quotes 「確保介紹文章可以跟tools都有互相連動」, my request to make sure the usage posts and the tools link to each other. Months later, git log tells me why a piece of code looks the way it does.

How do you stop the next session from starting over?

Write decisions into a file in the project that the AI reads automatically when it starts working. Each tool uses a different filename for the same job:

ToolWhere project instructions liveWhen it reads them
Claude CodeCLAUDE.md; reads AGENTS.md directly when there's no CLAUDE.md, and @AGENTS.md imports it to read bothAt the start of every session
CodexAGENTS.md, read from the repo root down to the current folderRebuilt on every run; 32 KiB combined by default
Cursor.mdc files in .cursor/rules; also supports AGENTS.mdApplied per rule settings; files are version-controlled
LovableProject settings → Instructions, up to 10,000 characters; also reads AGENTS.md and CLAUDE.md at the project rootWith every message

From each tool's docs, checked 2026-11-16: Claude Code [4], Codex [5], Cursor [6], Lovable [7].

What goes in it? Only what the AI can’t learn from reading the code:

  • How to run and check things. The commands for dev, build and tests. This site’s CLAUDE.md says Tests: npx vitest run.
  • Decisions and their reasons. This site’s admin area is a workspace several people share, so CLAUDE.md has a rule that new database tables use the workspace-member permission check, never owner_id = auth.uid(), or other members can’t see the data. It was added after a review in September 2026, and every new table since has followed it.
  • Anything you’ve corrected twice. Say it a second time, write it down. Don’t wait for the third.
  • Traps. For example, this site’s file says a new post has to be added to a topic in src/content/topics.ts, or tests/blog-topics.test.ts fails.

Leave out framework introductions and what each folder contains. The AI reads the repo itself. This site’s CLAUDE.md itself is only a dozen or so lines; longer rules live in their own files, each pointed to or imported with one line: visual design in DESIGN.md, article layout in writing-design-guidance.md.

One more thing to know: the instruction file is context for the model, and the model may not follow it. Claude Code’s docs, for example, describe it as context, not enforced configuration; rules that must never be broken belong in a hook or a permission setting4.

Go deeper Claude Code Tutorial 2026: Install, CLAUDE.md, Skills, and Your First Website Where CLAUDE.md goes, what to put in it, and my global and project setup.

What should you write before asking for a new feature?

A one-page spec, before the AI touches anything. It answers three things: why you want it, what done looks like, and what this change won’t do. The last one is the one people skip, and the one that stops the AI from changing a pile of things on the side.

As of November 2026, this site’s spec/ folder holds 58 dated specs, such as 2026-11-05-file-based-articles.md, which records moving articles out of the database and into files in the repo. It has my words from the conversation, the decisions made, a Why section, where the data lives, the workflow agents follow to write posts, and a Not in scope section. Any later session that touches articles reads it first and gets the whole story.

Visual design is written down the same way. This site’s DESIGN.md is close to 600 lines and has been changed in 112 commits, and its first rule is that anything conflicting with it gets the document changed first, then the code, so the two never disagree.

The spec doesn’t have to be long. One page with a clear “what done looks like” beats ten messages in a chat. You can start from the template in spec first, then plan.

Go deeper Design Specs for AI-Built Websites: A DESIGN.md Template The seven parts of a DESIGN.md, with a template to copy.

How do you start understanding code you can’t read?

Not all at once. Have the AI draw a map first. In a new session, ask:

Explain this project in plain language:
1. What each main folder is for, one sentence each
2. Which files a request goes through when someone opens the home page
3. Which files touch the database, login or API keys
Don't change any files.

Save the answer as a file in the repo (for example docs/map.md), and next time you want a change you’ll have a rough idea of where it lands. The map will go stale; after a big change, ask the AI to update it against the current code.

Asking before a change is another good time to learn:

  • “Which files will this change touch, and why?” Hear the plan first. If the scope is too big, shrink the request.
  • “In plain language, what did you just change, and what could it affect?” Ask again afterwards and compare the answer with git diff.
  • “What happens if this code is deleted?” Especially useful for code that looks pointless but nobody dares remove.

Over time you start recognizing things in a diff: which file is config, which is a page, which part talks to the database. That’s where being able to maintain it starts.

Why make the AI run checks instead of clicking around yourself?

Because you can’t click everything. When the AI says it’s done, it only knows the work looks done. Without something that comes back pass or fail, you become the test suite; with one, the AI can run it, read the failure and fix it on its own. The tools’ own docs recommend this too, for example Claude Code’s best-practices page8.

For a personal site, three kinds of check are enough:

  • Build. npm run build finishes without errors. Many “works on my machine” problems show up here.
  • Type check. In a TypeScript project, one type check catches a lot of misspelled field names.
  • A few tests. Start with one for each thing that must never break: the home page loads, a post page has a title, the contact form submits. Ask the AI to write them; your job is to say what must not break.

This site’s tests/ folder currently has more than 140 test files, and many of them guard a specific decision. For example, tests/build-config.test.ts guards a build setting and fails if someone reverts it; tests/spacing-scale.test.ts blocks spacing values that aren’t in the design spec. A decision in the instruction file can be forgotten by the AI. A decision in a test fails the run when it’s forgotten.

Posts have a check too: node tools/audit-writing.mjs scans every article and lists where it breaks the writing guide, such as a question heading without a question mark or a list item without a bold lead. It reports without blocking the build, because some items are judgment calls, and I decide which ones to fix.

Finally, ask for evidence. “All tests pass” on its own tells you nothing; ask for the command it ran and the output, and a screenshot for visual changes.

Go deeper What Breaks After You Launch an AI-Built Site: Failed Deploys, Leaked Keys, Database Permissions Real incidents and the checks for failed deploys, leaked keys and wrong database permissions.

How should you describe a bug to the AI?

“Login is broken, fix it” almost guarantees a patch on the symptom. Give it what you know and it can’t see. Template example (made-up situation):

Problem: on mobile, post titles on /blog are cut off.
To reproduce: iPhone width (390px), tap "Blog" from the home page.
Expected: the full title shows, wrapping if it's long.
Actual: one line only, the rest is cut off with no "…".
Known: desktop is fine; the post card styles changed last week (commit <commit id>).
Explain the cause you suspect before changing anything; run npm run build after.

What matters in that format:

  1. Say how to reproduce it. If the AI can reproduce the problem, it can confirm the fix. This site once had a build that failed only on Cloudflare and never locally; the cause was confirmed only after the same error was reproduced locally, written up in works locally, fails on deploy?.
  2. Separate expected from actual. “It’s broken” isn’t a description. “It should wrap; it’s cut off” is.
  3. Include what you know. Paste the whole error message rather than summarizing it, and mention what changed recently.
  4. One bug at a time. Fix it, commit, then the next.

If you’ve corrected the same thing twice and it’s still wrong, don’t try a third time. Start a new session (in Claude Code, /clear clears the conversation) with one new prompt that includes what you learned, because the AI keeps rereading the two failed attempts. Claude Code’s docs recommend the same8.

How do your tech choices affect how easy the site is to change?

Choose simple over complex wherever you can. Every extra package or service is one more thing the AI might remember the wrong version of, one more thing to upgrade, one more thing to break.

  • A site with only posts and an about page can be static. No database and no login means no permissions to get wrong and no keys to leak.
  • Don’t let the AI add packages on its own. Put a line in the instruction file: “ask me before adding a package, and say why it’s needed.”
  • Remove features you don’t use. This site used to have an article editor in its admin area, but I never edited posts there, and it meant every post had to stay in sync between the database and files. In November 2026 it was removed and posts became files in the repo, which took a whole system off the maintenance list.

This site isn’t simple itself: it has an admin area, a database and login, because I use it to run other things. If your site only holds work samples and posts, you don’t need any of that.

Go deeper What Is Vibe Coding? A Beginner's Guide, and Where It Breaks When it's fine not to read the code, and when you have to.

When should you start over instead of patching?

“Starting over” means two different things at very different costs. A new session costs almost nothing and you should do it often. Rewriting the project is a big job and needs a reason.

SituationWhat to do
Corrected the same bug twice, still wrongNew session, with what you learned in the new prompt
The AI starts touching unrelated filesgit restore . to put existing files back, git clean -nd to list new ones and git clean -fd to delete them, then retry with a smaller request
A session has run all day and the AI forgets earlier decisionsWrite progress and decisions into a file, continue in a new session
Every fix breaks something else, and there are no testsAdd tests around what keeps breaking, then keep fixing
The architecture doesn't fit (say, a server framework for a site that's only posts)Consider rebuilding in a new repo and moving the content over
The code mixes in things that shouldn't be public, or keys are in the historyStart a new repo and move only what you need

This site chose “start a new repo” over converting one in place from day one. In June 2026 I planned to turn an old repo holding personal finance data into the website in place, and decided instead to start a fresh repo: the old one keeps the data, the sensitive folders never enter the website repo, and there was no old history to scrub. The handoff note’s next-steps section says “open a fresh Claude session rooted in the new repo” and lists the steps underneath.

When you rebuild, the content (posts, about text, images) can usually come with you; what gets rewritten is the code around it. That’s why it pays to keep content in separate files from day one, for example one Markdown file per post, so it can move when the framework changes.

Already in a mess: where do you start today?

You don’t have to start over. Follow this order; each step stands on its own:

  1. Save a version. If the project isn’t using git yet, run git init and commit what you have. Even the broken version is worth saving; it’s the baseline for comparison.
  2. Ask the AI for a map. Use the prompt above, save the answer as docs/map.md, commit it.
  3. Write the shortest instruction file. Create CLAUDE.md, AGENTS.md or your tool’s project rules with three things: how to start it, how to build it, and what you care most about not breaking.
  4. Add one check. At least get npm run build to pass; ask the AI to write one test for your most important page.
  5. Fix one bug at a time. Use the bug format above: fix, run the check, read the diff, commit, next.

These habits reinforce each other over time: small commits keep diffs readable; an instruction file with your decisions keeps the AI from quietly undoing them in a diff; tests let the AI know whether it broke something. AI agents write this site’s code; I decide whether each change stays and whether it ships.

Sources

  1. 1. Git Basics - Undoing Things · Pro Git (git-scm.com) · checked 2026-11-16
  2. 2. Checkpointing · Claude Code Docs · checked 2026-11-16
  3. 3. Versions · v0 · checked 2026-11-16
  4. 4. How Claude remembers your project · Claude Code Docs · checked 2026-11-16
  5. 5. Custom instructions with AGENTS.md · OpenAI · checked 2026-11-16
  6. 6. Rules · Cursor · checked 2026-11-16
  7. 7. Instructions · Lovable · checked 2026-11-16
  8. 8. Best practices for Claude Code · Claude Code Docs · checked 2026-11-16
  9. 9. GitHub · v0 · checked 2026-11-16
  10. 10. Sync your Lovable project with GitHub · Lovable · checked 2026-11-16
  11. 11. Checkpoints · Cursor · checked 2026-11-16

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me