Claude Code can take an empty folder to a deployed bilingual content site in a weekend, but only if you scaffold the guardrails first. This is the exact workflow I run, including the steps where the agent gets confused and you have to step in. It assumes you can read the code being generated and reject it when it is wrong.
TL;DR
- Use Claude Code (the terminal agent bundled into Claude Pro at $20/mo, $17/mo annual, as of June 2026) for repo-level work; the web chat loses context across sessions.
- Drop a tight
CLAUDE.mdat the repo root before generating anything. It is read at the start of every session and prevents most rework. - Build on Astro 6 (current stable in 2026) with the Content Layer API for content collections, MDX, and per-language sitemaps.
- Deploy a monetized content site to Cloudflare Pages (free, commercial use allowed, unlimited bandwidth), not Vercel Hobby (free but non-commercial only).
- Use plan mode for big refactors, one feature per commit, and review every diff. The agent is far better at incremental work than greenfield.
Why an agent instead of a starter template
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 fix is to treat Claude Code like a strong junior engineer who has read every Astro doc but has never shipped a real site. Give it a clear repo structure, narrow tasks, and review every commit. With that scaffold it genuinely does about 80% of the work, and the remaining 20% is the part only you know: your niche, your taxonomy, your tone.
Claude Code runs Anthropic models only. As of June 2026 the workhorse is Claude Sonnet 4.6 with Claude Opus 4.7 for the hard reasoning passes, both at a 1M-token context window via API. On the $20 Pro subscription you get roughly 200K tokens of working context in the terminal, which is plenty for a content repo if you keep sessions focused.
A starter CLAUDE.md that prevents most rework
This file goes at the repo root and is loaded automatically at the start of every Claude Code session in that directory. Keep it short and declarative.
# Site brief
Stack: Astro 6 + 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 (wrangler.toml, firebase.json, vercel.json) without explicit approval.
- One feature per commit. Keep diffs reviewable. Run `npm run build` before declaring done.The last line matters: tell the agent how to verify its own work so it stops handing you code that does not compile.
When this workflow fits you
- 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 and a domain ready.
Use Claude Code when you have clarity 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
- Seed the repo. Start with an empty repo and a single
CLAUDE.mddescribing the site in plain English: stack (Astro 6 + MDX), languages (en/zh), routing pattern, and the content collection schema. - Scaffold in plan mode. Toggle plan mode (Shift+Tab in the CLI as of June 2026) and ask Claude Code to scaffold the Astro project with content collections, i18n routing, and a minimal layout. Approve the plan, then review the generated
astro.config.mjsandsrc/content/config.tsline by line before accepting. - Hand-write the schema sample. Add one real article in MDX manually so the agent has a concrete frontmatter shape to match. Never let it invent the schema on its own; schemas are sticky once you have 50 files.
- Delegate components one at a time. Build
BaseLayout,ArticleLayout, andNavin separate turns, reviewing each before moving on. Do not let it generate all components in a single pass. - Generate the mechanical files. Sitemap, robots.txt, and RSS feed are well-defined tasks the agent handles cleanly. Ask for all three.
- Centralize SEO meta. For canonical, hreflang, and OpenGraph tags, give it the exact tag list you want and ask for one helper component, not logic scattered across pages.
- Deploy by hand the first time. Push to Cloudflare Pages or Vercel yourself, watching the build output, before automating anything.
- Switch to review mode after launch. For new articles and refactors, the agent is better at incremental work than greenfield. Consider a subagent for parallel chores (link audits, alt-text passes) so each runs in its own context window.
Where to deploy a monetized content site
If your site shows ads or affiliate links, deploy target choice is not cosmetic. Vercel’s Hobby plan is free but explicitly non-commercial under its fair-use guidelines, so a content site that earns money belongs on Pro ($20/seat per month) or somewhere else.
| Host (as of June 2026) | Free tier | Commercial use on free? | Bandwidth | Builds |
|---|---|---|---|---|
| Cloudflare Pages | Yes | Yes | Unlimited | 500/month |
| Vercel Hobby | Yes | No (non-commercial only) | 100 GB fast transfer | 6,000 build min/month |
| Netlify Free | Yes | Yes | 100 GB/month | 300 build min/month |
| Firebase Hosting (Spark) | Yes | Yes | 10 GB stored, 360 MB/day transfer | n/a (deploy via CLI) |
For a static Astro content site that monetizes, Cloudflare Pages is the default pick: commercial use is allowed on the free tier and bandwidth is unlimited, which matters once a post catches traffic. Vercel Pro is worth it if you want its DX and analytics and the $20/month is fine.
Common pitfalls
- Letting the agent pick the stack. It defaults to whatever was popular in its training data and may pull in Tailwind, shadcn, and a dozen npm packages you do not need. State the stack in
CLAUDE.md. - Accepting the first content schema it proposes. Changing a frontmatter field after 50 articles is painful. Lock the schema yourself in step 3.
- Asking for “a beautiful homepage” with no constraints. You will get a generic SaaS landing page. Specify sections, content, and the tone you actually want.
- Skipping commits. Commit after every accepted change so you can revert cleanly when the next task goes sideways.
- Trusting the deploy config. Always do the first deploy yourself, watching the build, before automating with GitHub Actions.
- Forgetting the build step. The agent will declare a feature done without running
npm run build. Put the build command inCLAUDE.mdso it self-checks.
FAQ
- Do I need the Claude Code CLI, or is the web chat enough?: For full repo work you want the CLI; it reads and writes files and runs commands in your project. Web chat is fine for snippet-level help but loses context across sessions. The CLI ships bundled with Claude Pro at $20/month ($17 annual) as of June 2026.
- Which Claude model does Claude Code use?: Anthropic models only. As of June 2026 the default workhorse is Claude Sonnet 4.6, with Claude Opus 4.7 available for harder reasoning. You cannot point Claude Code at GPT-5.5 or Gemini 3.1 Pro; use Cursor or Codex for those.
- 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. Add
npm run buildtoCLAUDE.mdso the agent verifies before claiming success. The hit rate is high but never 100%. - Will Claude Code handle bilingual routing correctly?: Yes, if you give it the routing pattern upfront (
/en/articles/[slug]and/zh/articles/[slug]) and require a sharedtranslationKeyper pair. Let it improvise and it tends to invent inconsistent paths. - Can I let it write the articles too?: For structural drafts, yes. For published content you still need a human review pass, both for quality and to stay on the right side of search-engine and AdSense policy on machine-generated content.
- Astro 6 or stick with Astro 5?: Astro 6 is the current stable release in 2026 and the Content Layer API it inherits from Astro 5 is the right foundation for content collections. Pin the major version in
CLAUDE.mdso the agent does not mix v5 and v6 patterns.
Related
- Doing an SEO Review of Your Site with Codex
- Designing Prompts for Website Building
- Astro Best Use Cases
Tags: #Indie dev #AI-assisted build #Claude Code #Astro #Workflow