AI AI Tools Guidebook
Indie Dev & Website Building

Using Claude Code to Build a Content Site End-to-End

A realistic 2026 walkthrough of building an Astro content site with Claude Code — from repo setup to deploy — including what to delegate, what to keep, and where the model bites you.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Claude Code can go from empty folder to deployed bilingual content site in a weekend if you set it up right. This is the actual workflow I use, including the parts where the agent gets confused and you have to step in.

Background

Most “AI built my site” posts skip the boring middle: the part where the agent generates 40 files, half of which conflict, and you spend two hours untangling it. The trick with Claude Code is treating it like a junior engineer who has read every Astro doc but has not shipped a real site. You give it a clear repo structure, narrow tasks, and you review every commit. With that scaffold, it genuinely can do 80% of the work.

A starter CLAUDE.md that prevents most rework:

# Site brief
Stack: Astro 4 + MDX + Tailwind. Bilingual en/zh under src/content/articles/{en,zh}/.
Routing: /en/articles/{slug}, /zh/articles/{slug}, sitemap split per language.
Frontmatter schema: title, description, urlSlug, category, tags[], publishedAt, lang, translationKey.

# Guardrails for you (the agent)
- Never invent frontmatter fields. Read src/content/config.ts before adding any.
- Translation pairs share translationKey. Slugs and tags must match across en/zh.
- Never touch deploy config (firebase.json, vercel.json) without explicit approval.
- One feature per commit. Keep diffs reviewable.

Once that file exists, every Claude Code session in the repo inherits it.

How to tell

  • You already know what you want to build — niche, languages, monetization — and you just need to ship.
  • You are comfortable reading and rejecting code, not just accepting suggestions.
  • You can describe your content schema in one paragraph (categories, frontmatter fields, routing).
  • You have a deploy target picked (Vercel, Cloudflare Pages, or Netlify) and a domain ready.

Quick verdict

Use Claude Code when you have clarity on what to build and want speed; use a manual setup when you are still exploring stack choices, because the agent will over-commit to whatever you mention first.

Step by step

  1. Start with an empty repo and a single CLAUDE.md file describing the site: stack (Astro + MDX), languages (en/zh), routing pattern, and the content collection schema in plain English.
  2. Ask Claude Code to scaffold the Astro project with content collections, i18n routing, and a minimal layout — review the generated astro.config.mjs and src/content/config.ts carefully before accepting.
  3. Add one real article in MDX manually so the agent has a concrete schema to match — never let it invent the frontmatter shape on its own.
  4. Delegate the layout components (BaseLayout, ArticleLayout, Nav) one at a time, reviewing each before moving on. Do not let it generate all components in a single pass.
  5. Have it generate the sitemap, robots.txt, and RSS feed — these are well-defined tasks the agent handles cleanly.
  6. For SEO meta (canonical, hreflang, OpenGraph), give it the exact tag list you want and ask for a single helper component, not scattered logic across pages.
  7. Deploy to Vercel or Cloudflare Pages manually the first time. Once it works, ask Claude Code to add a GitHub Actions workflow if you need one.
  8. After launch, switch the agent into “review mode” for new articles and refactors — it is better at incremental work than greenfield.

Common pitfalls

  • Letting the agent pick the stack. It will default to whatever was popular in its training data and may pull in Tailwind, shadcn, and 15 npm packages you do not need.
  • Accepting the first content schema it proposes. Schemas are sticky — once you have 50 articles, changing a frontmatter field is painful.
  • Asking for “a beautiful homepage” with no constraints. You will get a generic SaaS landing page. Specify sections, content, and the actual tone you want.
  • Skipping commits. Commit after every accepted change so you can revert when the agent goes off the rails on the next task.
  • Trusting the deploy config. Always do the first deploy yourself, watching the build output, before automating anything.

Who this is for

Solo builders who already know Astro or Next.js fundamentals and want to compress two weeks of setup into a weekend.

When to skip this

Complete beginners who cannot read the code being generated — you will end up with a site you cannot maintain when the agent breaks something.

FAQ

  • Do I need the Claude Code CLI or is the web chat enough?: For full repo work you want the CLI — it can read/write files and run commands. Web chat is fine for snippet-level help but loses context across sessions.
  • How much should I trust the generated code?: Treat it as a PR from a contributor you do not fully know. Read it, run it, test it. The success rate is high but never 100%.
  • Will Claude Code handle bilingual routing correctly?: Yes if you tell it the routing pattern upfront (e.g. /en/articles/[slug] and /zh/articles/[slug]). If you let it improvise, it tends to invent inconsistent paths.
  • Can I let it write articles too?: For structural drafts, yes. For published content, you still need a human review pass — see the article on avoiding low-quality AI content.

Tags: #Indie dev #AI-assisted build #Claude Code #Astro #Workflow

Related Articles