The AI Workflow

This is a member-only chapter. Log in with your Signal Over Noise membership email to continue.

Module 6: The AI Workflow

Every site I’ve built in the past year has used the same underlying pattern: a project CLAUDE.md that gives Claude Code context, a set of repeatable prompts for common tasks, and a deploy script that makes shipping a one-command operation. This module covers what that actually looks like in practice.

This is not the “use AI to write your content” workflow. It’s the workflow for using AI as a pair programmer throughout the entire build process — from scaffold to shipped.

Your Project CLAUDE.md

A project CLAUDE.md lives at .claude/CLAUDE.md in your project root. Claude Code reads it at session start. Without it, every session starts from scratch. With it, Claude Code knows your project’s conventions, file structure, and constraints from the first message.

Here’s what a Astro site CLAUDE.md needs:

# My Site — Claude Code Instructions

## Project

This is an Astro 5 site. Framework: Astro. Language: TypeScript.
Package manager: npm. Build output: dist/.

## Structure

- Pages: src/pages/
- Layouts: src/layouts/ (BaseLayout.astro is the base)
- Components: src/components/
- Content: src/content/ (typed collections, config in src/content/config.ts)
- Styles: src/styles/global.css (CSS custom properties — no hardcoded values)
- Public assets: public/

## Commands

- Dev server: npm run dev (localhost:4321)
- Build: npm run build
- Preview build: npm run preview
- Deploy: ./deploy.sh

## Rules

- Read a file before editing it
- Use CSS custom properties from src/styles/global.css — never hardcode hex values
- Follow the existing component structure before creating new ones
- Run npm run build to verify before telling me something is done
- All content in British English
- Conventional commits for git messages

## Conventions

- Components receive typed props via Astro.props
- Pages import layouts and wrap content in them
- Collection frontmatter must match the schema in src/content/config.ts
- Images go in public/images/ and are referenced from /images/

This file is the difference between “Claude Code helping with one task” and “Claude Code building your entire site without context gaps”. Invest 20 minutes writing a thorough one at the start of every project.

Repeatable Prompts for Common Tasks

The most useful AI workflow is a small library of prompts you’ve tested and know work. These are mine for Astro sites.

New component:

Create a [component name] component in src/components/.
It should [describe what it does].
Props: [list props with types].
Use CSS custom properties for all styling.
Read the existing components in src/components/ first to match the pattern.

New page:

Create a new page at src/pages/[path].astro.
It should use BaseLayout from src/layouts/BaseLayout.astro.
Title: "[page title]"
Content: [describe the content]
Read src/pages/index.astro first to match the pattern.

New blog post:

Create a blog post in src/content/blog/.
Slug: [slug]
Title: [title]
Topic: [topic]
Read src/content/config.ts to get the required frontmatter fields.
The post should be [length] words, in British English.

Debug build error:

The build is failing with this error:
[paste error output]

Read the file mentioned in the error and fix the issue.
Run npm run build after fixing to confirm it's resolved.

The “read X first” instruction in every prompt is the most important part. Claude Code working from context is meaningfully better than Claude Code working from a blank slate.

The SEO Preflight

Before shipping any content site, run a build and check the output. There are four things to verify:

Title tags: Every page has a unique <title>. Check dist/ for any pages with a generic or missing title.

Meta descriptions: Every page has a <meta name="description"> with content that’s under 160 characters.

Open Graph tags: For shared links to look right in social feeds and chat apps, add og:title, og:description, and og:image to your layout head.

Canonical URLs: For sites with multiple versions of the same URL (with and without trailing slash, for example), add <link rel="canonical"> to prevent duplicate content issues.

A Claude Code prompt for this:

Check the SEO setup for this Astro project.
Read src/layouts/BaseLayout.astro and check:
- Is there a <title> tag that uses a prop?
- Is there a <meta name="description"> tag?
- Are there Open Graph tags (og:title, og:description, og:image)?
If any are missing, add them. The og:image should default to /og-default.png
if no specific image is provided.

Deploy Automation

The deploy workflow for VPS-hosted sites is always the same three steps:

Build
Rsync to server
Optionally verify

Automating it:

#!/usr/bin/env bash
set -e

REMOTE_HOST="my-vps"
REMOTE_PATH="/var/www/my-site"

echo "Building..."
npm run build

echo "Deploying to ${REMOTE_HOST}..."
rsync -avz --delete dist/ "${REMOTE_HOST}:${REMOTE_PATH}/"

echo "Done. Checking live site..."
curl -s -o /dev/null -w "%{http_code}" https://my-domain.com

For Cloudflare Pages, deploy automation is git push. The CI/CD is built in — every push to the main branch triggers a build and deploy.

Building a Site Start to Finish

The workflow across all eight of my sites follows this pattern:

Scaffold — npm create astro@latest, empty template, TypeScript yes.
CLAUDE.md — Write it before writing any code. Describe the project, the structure, the commands, the rules.
Design tokens — Write src/styles/global.css with colour, typography, and spacing variables.
Base layout — One layout that wraps every page. Get this right before building pages.
Index page — The homepage, using the layout. Enough content to see the design working.
Components — Header, footer, any repeated UI. Each one generated with a prompt that references existing components.
Content — Collections defined, schema written, first few entries added.
Additional pages — Blog index, about, contact. Each one follows the established layout pattern.
SEO preflight — Check titles, descriptions, OG tags.
Deploy — Cloudflare Pages or VPS, depending on the project.

Steps 2 and 3 are where most people skip ahead. Don’t. The CLAUDE.md and the design tokens are what make every subsequent step faster. They’re the foundation that Claude Code builds on.

What Compounds Over Time

The honest answer to “what makes AI-assisted development valuable” is not any single task. It’s that context accumulates.

A good CLAUDE.md means every session starts informed. Repeatable prompts mean you don’t reinvent the wheel for common tasks. A tested deploy script means shipping takes 30 seconds instead of ten minutes of typing.

Build one good site this way and the second is meaningfully faster. By the fourth or fifth, you have a toolkit that’s yours — prompts that work, patterns you trust, a deploy setup that runs without thought.

That’s what this course is actually about. Not Astro specifically, not Claude Code specifically. The compounding workflow that makes you faster every time you build something.

You’ve been through all six modules. Go build something.