How This Site Is Built: Claude Code, Astro & an AI-First Workflow

This site runs on a straightforward stack: Astro 5 for static HTML, Tailwind CSS for styling, Vercel for hosting, and GitHub for version control. What makes it different is how it gets built. Nearly every page, component, and deploy is driven by Claude Code running in PowerShell on a Surface Laptop.

AI-assisted coding tools are growing fast. GitHub reports that Copilot now generates 46% of code across files where it is enabled. Anthropic’s Claude Code takes a different approach — it operates as a full agentic CLI rather than an autocomplete layer, reading your project, running commands, and pushing commits autonomously.

Source: GitHub Copilot Productivity Report 2025

Claude Code is Anthropic’s terminal-based AI coding tool. Instead of suggesting snippets inside an editor, it reads your entire repository, plans changes across multiple files, runs your build commands, and commits directly to Git. The workflow looks like this:

1. Open PowerShell on the Surface Laptop and cd into the project
2. Launch Claude Code with claude
3. Describe the task in plain English — “add a new article page about the tech stack”
4. Claude Code reads the codebase, writes the files, runs npm run build to verify
5. Review the diff, approve, and it pushes to GitHub

The entire cycle from prompt to production deploy can happen without leaving the terminal. Vercel picks up the push to main and deploys automatically.

A CLAUDE.md file at the project root is the single most important setup step when working with Claude Code. It acts as persistent instructions that the AI reads at the start of every session. Without it, you repeat the same context in every prompt.

Here is a simplified version of the structure used on this site:

# Page Sands — pagesands.com

## Stack
- Framework: Astro 5 (static output)
- Styling: Tailwind CSS
- Hosting: Vercel

## Commands
- npm run dev    — Start dev server
- npm run build  — Type-check + build

## SEO / GEO Requirements
- All content must render in initial HTML
- JSON-LD schema on every page
- FAQ sections use FAQPage schema
- Content blocks under ~800 tokens
- Canonical URLs set on every page

## When Adding New Pages
1. Add JSON-LD schema appropriate to page type
2. Set SEO props on BaseLayout
3. Include FAQ section with FAQPage schema
4. Update public/llms.txt with the new page

This file defines the stack, the build commands, SEO requirements, and a checklist for new pages. Claude Code follows these rules automatically — it adds JSON-LD schemas, sets canonical URLs, and updates llms.txt because the instructions say to.

The key sections to include in any CLAUDE.md:

• Stack and tools — framework, language, styling approach
• Build and test commands — so the AI can verify its own work
• Project structure — where files live and naming conventions
• Coding standards — formatting, patterns, things to avoid
• Domain-specific rules — SEO requirements, accessibility standards, etc.

Model Context Protocol (MCP) is an open standard that lets AI tools connect to external data sources and APIs. Claude Code supports MCP servers natively, which means you can give it access to tools like Ahrefs, databases, or internal APIs without leaving the terminal.

For this site, the Ahrefs MCP integration is particularly useful. When writing SEO-focused articles, Claude Code can pull live data:

• Keyword difficulty scores — check competitiveness before targeting a term
• Search volume data — validate whether a topic has enough demand
• Backlink profiles — understand what competing pages have earned
• Content gap analysis — find topics competitors rank for that you don’t

MCP servers are configured in a JSON settings file. A simplified example:

// .claude/mcp.json
{
  "mcpServers": {
    "ahrefs": {
      "command": "npx",
      "args": ["-y", "ahrefs-mcp"],
      "env": {
        "AHREFS_API_KEY": "<your-key>"
      }
    }
  }
}

Once configured, Claude Code can call Ahrefs functions directly during a session. You ask “what keywords should I target for this article?” and it returns real data instead of guessing.

Other useful MCPs for web development workflows include GitHub (issue and PR management), Fetch (reading live web pages), and Context7 (up-to-date library documentation).

Astro is a static-site framework that ships zero JavaScript by default. Every page compiles to plain HTML and CSS at build time. This matters for two reasons: performance and AI crawler compatibility.

AI crawlers like GPTBot, ClaudeBot, and PerplexityBot cannot execute client-side JavaScript. A React SPA or Next.js app with client-rendered content is invisible to them. Astro’s static output means every word, every JSON-LD schema, and every FAQ answer is in the initial HTML response.

The Astro component model uses .astro files that combine frontmatter (data and logic) with an HTML template. Here is a simplified look at how a page is structured:

---
// Frontmatter: runs at build time
import BaseLayout from "@/layouts/BaseLayout.astro";

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: "Page Title",
  // ... structured data
};
---

<BaseLayout
  title="Page Title"
  description="Meta description"
  canonical="https://pagesands.com/page-slug"
  ogType="article"
  jsonLd={jsonLd}
>
  <article>
    <!-- Static HTML content -->
  </article>
</BaseLayout>

Astro also supports component islands — interactive UI fragments hydrated on demand — but this site uses none. Pure static output keeps the page weight minimal and ensures full content availability for both search engines and AI answer engines.

Source: Astro documentation, astro.build

Every change goes through a branch-based Git workflow. Claude Code handles the Git operations directly from the terminal — creating branches, staging files, writing commit messages, and pushing to GitHub.

The typical flow for a new feature or article:

1. Branch: Claude Code creates a feature branch off main (e.g., claude/add-tech-stack-article)
2. Commit: Changes are committed with descriptive messages. Claude Code writes the commit message based on the diff — no manual writing needed
3. Push: The branch is pushed to GitHub with git push -u origin <branch>
4. Preview: Vercel detects the new branch and generates a unique preview URL within seconds
5. Review: Check the preview deploy — verify content, layout, links, and structured data
6. Merge: Merge the branch into main via GitHub (pull request or direct merge)
7. Deploy: Vercel automatically triggers a production build and deploys to the edge network

This branch-per-change model means production is never touched by work in progress. You can have multiple articles or features in flight on separate branches without conflict. Vercel gives each branch its own preview URL, so you can share drafts before they go live.

# Typical session in PowerShell
claude                              # Start Claude Code
> "Add an article about the tech stack"

# Claude Code runs:
git checkout -b claude/tech-stack-article
# ... writes files, runs build ...
git add src/pages/articles/pagesands-tech-stack.astro
git commit -m "Add tech stack article with JSON-LD and FAQ schema"
git push -u origin claude/tech-stack-article

# Vercel preview: https://pagesands-xyz123.vercel.app
# Review → Merge to main → Live on pagesands.com

Vercel connects directly to the GitHub repository. No CI/CD configuration files, no Docker containers, no build servers to maintain. The connection is set once and works automatically from that point forward.

When a commit lands on main, Vercel:

1. Pulls the latest code from GitHub
2. Runs astro check && astro build to type-check and compile
3. Deploys the static HTML output to its global edge network
4. Invalidates the CDN cache so visitors see the new content immediately

Build times for this site run under 10 seconds. The @astrojs/vercel adapter handles routing, redirects (including the www → non-www 301), and response headers without extra configuration.

For every non-production branch, Vercel creates a preview deployment with a unique URL. This is what makes the review step practical — you see exactly what the live site will look like before merging.

Plausible is a privacy-friendly analytics platform that tracks pageviews and referral sources without cookies. It produces a script under 1 KB — roughly 45x smaller than Google Analytics. No cookie consent banner is required under GDPR or CCPA because it collects no personal data.

On this site, Plausible is loaded through Google Tag Manager rather than being hardcoded into the HTML. The setup:

1. Add the GTM container snippet to your site layout
2. Create a Custom HTML tag in GTM
3. Paste the Plausible tracking script inside the tag
4. Set the trigger to All Pages

Why route through GTM instead of embedding Plausible directly? Two reasons. First, it keeps all tracking centralized — if you add other tools later (heatmaps, A/B testing, conversion tracking), they live in one place. Second, you can enable or disable analytics without touching your codebase.

Plausible provides the metrics that matter for a content site: top pages, referral sources, country breakdown, and device types. No session recordings, no user profiles, no data sold to third parties.

Here is the end-to-end workflow for publishing a new page on this site:

1. Open PowerShell on the Surface Laptop
2. Run claude in the project directory
3. Claude Code reads CLAUDE.md and loads MCP servers (Ahrefs, GitHub)
4. Describe the page: topic, target keywords, structure
5. Claude Code writes the Astro page with JSON-LD, FAQPage schema, and proper SEO props
6. It updates resources.astro and llms.txt per the checklist in CLAUDE.md
7. Runs npm run build to verify everything compiles
8. Commits and pushes to a feature branch on GitHub
9. Vercel creates a preview deploy — review and merge
10. Production deploy happens automatically; Plausible tracks the first visitors

No IDE needed. No copy-pasting between browser tabs. The AI handles the mechanical work — creating files, wiring up schemas, running builds — while the human provides direction and review.