◉ANTIGRAVITY LABJP
Articles/Tips & Best Practices
✦ Tips & Best Practices/2026-11-19Advanced

Before an Agent Clones Your Template Repo, Hand It a Trap Index: One Line per Fix, the Reasons Kept in One Place

When you copy a running site to start the next one, an agent carries the fixes over but leaves the reasons behind. A symptom-first trap index, a one-page porting plan written before the copy, and three small scripts that catch drift between the index, the source docs and their mirrors.

agents151templatesrepository portingdocumentation designNext.js8indie development32Antigravity419

✦ Premium Article

One evening early in the autumn I was getting ready to start a new artist's site by copying one I already run. The chapter layout, the gallery that scrolls sideways, the language routing: nearly all of it carried over. If I asked the agent to "build it the same way as the last one," I expected it to get most of the way overnight.

I stopped when I opened the implementation notes of the site I was copying. Dated additions had started to pile up outside their sections, and the same caution appeared in another document in slightly different words. I wrote all of it, and I still couldn't say at once which version was current. Hand that over as it is, and the agent will pick one of them and fix things in a way that disagrees with the others.

Since then, as an indie developer copying my own work, I give the agent a one-page trap index before any step-by-step guide. What follows is the shape of one row in that index, the porting plan I write before the copy, and three small scripts that keep the index and the source documents from drifting apart, exactly as I run them.

The index holds one line of fix, and nothing more

The index exists to be looked up by symptom. Each row has four columns (symptom, cause, fix, source), and the fix stops at one line. Why that fix works, and how I found it, lives in a section of the source document; the index only points there.

It took me a while to settle on this. At first I kept adding the reasons to the index too. When a bad night is still fresh, you want to write all of it down. It didn't go well. The longer the rows grew, the more the same explanation sat in both the index and the source, and sooner or later only one of them got corrected.

I think a short index suits the agent as well. It narrows things down by symptom, opens the source section to read the reason, and only then makes a change. When the reading order is that clear, there is less room for it to invent a plausible alternative of its own.

What a row looks like, and rows I actually keep

Here are rows from my own index with the specific names removed. Each one is something I hit on a site built from the same template.

| Symptom | Cause | Fix | Source |
| --- | --- | --- | --- |
| Commit "succeeds" but push says everything is up to date | A stale .git/index.lock on the synced folder made the commit fail silently | Check HEAD with git log --oneline -1 | rules.md §3 |
| Deploy fails quietly and the old version stays live | A downloadable PDF exceeded the host's 25 MiB per-file limit | Check sizes with ls -l after generating | ops_guide.md §6 |
| Background flickers at chapter boundaries, worst on iOS | Current chapter picked by an IntersectionObserver center band | Treat the chapter containing the viewport's center point as current | knowhow.md §2 |
| On dark chapters in light theme, the toggle label disappears | One of the inverted tokens leaked | Invert all six tokens as one set on dark chapters | knowhow.md §2.1 |
| Build stalls for 10+ minutes on the synced folder | Writes to the synced folder are slow | Copy to a local disk, build there, bring back only the output | rules.md §3 |

The fourth row carries something I only noticed after building the index. I used to fix vanishing text in the zoom overlay with a local workaround: always give the overlay a dark background. Lined up in the index, that turned out to be just one symptom of a single leaked token, and the same root was making text disappear elsewhere too. Workarounds stay out of the index; the root goes in, in one line. Once I held to that, similar symptoms started showing up together when I looked them up.

Three rules for writing a row:

  • The symptom in the words of what you saw on screen ("the toggle label disappears," not "layout breaks")
  • The cause in one sentence, in terms of the mechanism
  • The source down to the file and section number
✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN
✦Before starting a new project from an existing repository, you will be able to turn the traps you have already hit into a symptom-first index, so an agent stops before carrying the same breakage across
✦You can catch, with a script and before release, the moment your index starts growing reasons of its own and becomes a second source of truth that disagrees with the first
✦Right after copying a template, you'll be able to count exactly where its specific values still live, separating deliberate traces in comments from real leftovers, and run that loop on your own repo
Secure payment via Stripe · Cancel anytime
✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

or
Unlock all articles with Membership →
Share

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

Related Articles

✦ Tips2026-11-17
Why a Small sizes Value Shrinks the Image Itself, and the CSS Line to Add When width and height Attributes Stretch It
The day I added responsive images, one artwork shrank and another stretched sideways. How sizes sets the displayed size, the one CSS line for width and height attributes, and how to work out sizes for tall art in a frame, with numbers and a check script.
✦ Tips2026-10-30
The sed -i That Worked on Linux and Stalled on My iMac: Checking an Agent's Steps Before You Run Them
A sed -i step that ran fine on Linux can stall on a Mac or leave backup files behind. Here is what I reproduced with GNU sed, the forms that behave the same on both, and a short check to run first.
✦ Tips2026-10-23
594 Articles Had No Body-Link Entrance. Counting the Related-Articles Box Left Only 6 Truly Orphaned
Counting only body links made half my MDX site look orphaned. Here is the full Python script that mirrors the related-articles scoring and also catches links the build strips.