How to Build Websites with AI Coding Agents That Non Technical Clients Can Actually Maintain

You built the site in a weekend with an AI coding agent. Clean, fast, deployed by Friday.

Two weeks later the client emails. They want a new headline on the homepage and one more person added to the team page. You open your terminal. Again.

That is the handoff problem. Most developers try to solve it after the site is finished. By then it is too late. The fix belongs in the first prompt you write.

Below is the stack I use, the exact prompts, and what 230+ developers said when I asked them how they handle it.

Why AI-built sites break at handoff

AI coding agents (Claude Code, Cursor, Codex, Antigravity, and others) build what you ask for. Ask for a website and you get a React app or a folder of HTML files. Copy ends up inside components. Headings sit in JSX. The about page bio is a string in a div.

That site is maintainable by you. Nobody else.

Two things follow. You become the client's content team for free. Or you charge a retainer they never agreed to, and they resent every invoice.

The client is not going to learn Git. If you work in tech it is easy to assume everyone else does too. They don't. And regardless of which agent you used to build the site, the content structure problem is identical across all of them.

What 230+ developers said when I asked

I posted a question across several AI developer communities with a combined reach of over two million members:

How do you hand off a site built with an AI coding agent to a non-technical client, and how do they edit the content when they need to?

The thread passed 230 comments. Six answers came back over and over.

Build a custom admin panel. You now maintain two products instead of one. Auth, roles, validation, updates, all for a single client site. The admin panel becomes the project.

Send them the repo or a zip. They open it once. Then they email you.

Keep them on retainer and never hand off. This works. It is a business model, not a solution. It also stops working around client number five.

Use WordPress, Webflow or Wix instead. You lose the build speed that made AI worth using. You add hosting cost, plugin cost, and a security surface you have to watch. Those platforms are not AI-native yet.

Give them docs and a readme. They will not read it.

Use a headless CMS. Closest to correct. But almost everyone meant an API-based CMS like Contentful or Sanity. That adds a second source of truth, a monthly bill, and a build that depends on someone else's uptime.

What surprised me most: almost nobody named a git-based CMS.

I have worked in the static site space for five years, so I am biased. I still think it is the right answer for this class of site. Here is the build.

Step 1: name the framework in your prompt

Say it explicitly or you get a React app. This applies whether you are using Claude Code, Cursor, Codex, Antigravity, or any other agent.

Astro for most marketing and content sites. Hugo when you need build speed across hundreds of pages. Next.js when the client will want app features later.

All three are open source with years of public documentation behind them. Every AI agent builds with them following convention instead of inventing its own structure. That matters, because every CMS, plugin and deploy platform expects that convention.

Build a marketing site for a dental clinic using Astro.

Requirements:
- Astro 5 with content collections
- Tailwind for styling
- Static output, no SSR
- Pages: home, services, about, contact
- Include sitemap and robots.txt
- Semantic HTML, one h1 per page, alt text on every image

Do not use a client-side router. Do not add React unless a component needs interactivity.

This prompt works the same whether you paste it into Claude Code, Cursor, Codex, or Antigravity.

Step 2: force a content layer the agent cannot skip

This step decides whether handoff is possible at all.

A git-based CMS reads your repository. If your copy is scattered inside components, there is nothing for it to read. You can add the CMS later, but you cannot add structure later without a rewrite.

Give your AI coding agent these constraints before it writes a line:

• Every piece of copy lives in /src/content as markdown with frontmatter
• No user-facing string is hardcoded in a component
• One schema per content type, defined once, with types
• Images live in one folder and are referenced by path
• Site name, nav links, social links and contact details sit in a single config file

Structure all content as editable data, not as code.

Rules:
- All page copy lives in /src/content as markdown files with frontmatter
- Define a Zod schema for each collection in /src/content/config.ts
- No headline, paragraph, button label or meta description is hardcoded in a .astro file
- Components receive content as props from the collection entry
- Site title, nav items, footer links and contact info live in /src/config/site.json
- All images live in /src/assets, referenced by relative path in frontmatter

A non-technical person should be able to change any word on this site by editing one markdown file.

Then run the test. Could someone change the homepage headline by editing a single markdown file? If the answer is no, the structure is wrong. Fix it before you deploy, not after the client asks.

Step 3: Git plus a free host

Push the code to GitHub or GitLab. A private repo is fine.

Connect the repo to Vercel, Netlify, or Cloudflare Pages. Every push to main triggers a build and a deploy. Set it up once and forget it.

Cost so far: zero.

Step 4: attach a git-based CMS

A git-based CMS shows your repository's content through the Git API.

The client opens a URL, logs in, edits a field, and clicks save. That save is a commit. The commit triggers a build. The change is live in about a minute. They never see a repo, a branch, or a terminal.

What you get from this that an API-based CMS does not give you:

• No database and no second copy of the content
• No monthly bill at small scale
• No vendor holding your content hostage
• Your Git workflow stays exactly as it was, including pull requests and rollbacks
• If the CMS disappears tomorrow, your content is still sitting in the repo as markdown

Options worth looking at: Decap CMS, Tina CMS, Keystatic, and Sitepins.

I should say the obvious. Sitepins is ours. We built it at Themefisher after Forestry shut down in 2023 and left our template library without a CMS. It is open source, so you can self-host it for clients, and there is a free cloud plan.

Whichever one you pick, the pattern is the same. Configure the collections to match the schema you defined in step 2, invite the client, done.

The handoff kit

Hand over these five things and you are finished.

1. CMS login for the client, created by you, with the password reset already done by them
2. A one-page doc with three screenshots: how to log in, how to edit a page, how to add a blog post
3. A three-minute Loom walking through those same three tasks. They will watch this. They will not read the doc
4. Editor-level permissions, not admin. They can change content. They cannot change the schema or delete a collection
5. One sentence on escalation. What to email you about, and what your rate is if it goes past content edits

What this costs

Compare that against managed WordPress hosting plus a page builder license plus a backup plugin. The gap is real, and it recurs every month for as long as the site exists.

When this is the wrong stack

Be honest with the client before you build.

Skip this approach if the site needs live inventory and checkout. Skip it if they publish several times a day with ten or more editors who need approval workflows. Skip it if the client has said clearly that they want to drag boxes around and redesign pages themselves.

Those are real requirements. A git-based CMS is for editing content inside a design you built. It is not a page builder, and pretending otherwise gets you an unhappy client in month three.

For a brochure site, a portfolio, a local business, a clinic, a small SaaS marketing site, this stack is hard to beat.

The point

You are not trying to make the client technical. You are trying to make the site editable without you.

Get the content layer right in the first prompt, regardless of which AI coding agent you use, and the handoff takes an afternoon. Get it wrong, and you own that client's copy edits forever.

If you want the CMS layer for this, Sitepins is what we built for it. Open source, self-hostable, free cloud plan.

FAQ

Can a client edit an AI-built site without using GitHub?

Yes. A git-based CMS gives the client a browser editor. The CMS commits their changes to the repository through the Git API. The client never opens GitHub.

Does it matter which AI coding agent I use (Claude Code, Cursor, Codex, Antigravity)?

No. The handoff problem is structural, not agent-specific. The same prompts and the same content layer work across all of them. What matters is that you define the content structure before the agent writes a single component.

What is a git-based headless CMS?

A git-based headless CMS is an editing interface that reads and writes content files in a Git repository. Content stays as markdown in the repo. There is no separate database.

Should I use Astro or Next.js for a client site?

Use Astro for content and marketing sites. Astro ships less JavaScript and builds static pages by default. Use Next.js when the client needs authentication, dashboards or other app features.

Does a static site need a database?

No. A static site stores content as files in the repository. The site generator turns those files into HTML at build time.