AI AI Tools Guidebook
Indie Dev & Website Building

Designing Prompts for Website Building (So AI Doesn't Drift)

Keep AI agents on-spec for multi-file website work with this CLAUDE.md template, 3-part prompt structure, and per-task constraint pattern.

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

Most “AI built me a bad website” stories are really “I wrote a bad prompt” stories. The model is fine; the spec was vague. Here is how to write prompts that keep an agent on rails over an entire build — with a real CLAUDE.md template and per-task prompt structure you can paste.

Background

When you build a website with an AI agent, drift is the enemy. Drift is the agent silently changing your design system, route conventions, or content schema across tasks. It does not happen because the model is bad — it happens because each task lacks the anchor of what came before. Good prompt design solves this by making the spec explicit, persistent, and narrow.

How to tell

  • Your agent generates code that contradicts code from a previous task.
  • You find yourself re-explaining your stack at the start of every session.
  • Files diverge from your intended folder structure over time.
  • The agent invents UI components or routes you never asked for.
  • The same prompt produces different outputs across sessions.

Quick verdict

Use persistent spec files (CLAUDE.md, AGENTS.md, or similar) plus narrow per-task prompts. Never rely on conversational memory alone for anything that should survive across sessions.

Before you start

  • Pick the spec filename your tooling reads (CLAUDE.md for Claude Code, AGENTS.md for OpenAI/codex tooling).
  • Your repo’s stack and conventions are decided — write them down, don’t discover them.
  • Budget 30-60 minutes to draft the spec; it pays for itself within a week.

Step by step

  1. Create a single source-of-truth spec file in the repo root. Aim for one page. Template:
# CLAUDE.md

## Stack
- Framework: Astro 5 (Content Collections, MDX)
- Styling: Tailwind v4 (NO CSS modules, NO styled-components)
- Hosting: Firebase Hosting (static; `firebase.json` is canonical)
- Languages: en, zh — parallel folders under src/content/articles/

## Conventions
- Slugs: `^[a-z0-9-]+$`, kebab-case, no dates, no category prefix
- Folder layout: src/content/articles/{en,zh}/<hub>/<slug>.mdx
- Content schema: defined in src/content/config.ts; do not modify without explicit ask
- Image refs: use `image()` helper, never `/public/...`

## Article shape (mdx files)
- Frontmatter fields required by schema: title, description, urlSlug, category, tags, publishedAt, lang, translationKey
- Body sections in this order: Lead, Background, How to tell, Step by step, FAQ, Related

## Banned
- Adding npm packages without asking
- Editing files outside the path the user provided
- Renaming any frontmatter field
- Inventing new components when one in src/components/mdx/ would do
  1. For each task, write a 3-part prompt: context (point at the spec), task (one specific deliverable), constraints (what not to do). Template:
[CONTEXT]
Repo conventions are in CLAUDE.md. The article schema is in src/content/config.ts. We use Astro Content Collections.

[TASK]
Add a new article at src/content/articles/en/indie-dev/<slug>.mdx that follows the article shape in CLAUDE.md. Title: "<title>". Primary keyword: "<keyword>". Length 600-900 words. Include at least one bash code block and one config code block.

[CONSTRAINTS]
- Do NOT modify src/content/config.ts.
- Do NOT add npm dependencies.
- Do NOT touch other articles.
- Slug must match the filename and pass /^[a-z0-9-]+$/.
- Do NOT use {variable} in prose (MDX brace bug). Wrap any literal braces in backticks.

Reply with the file content only; I will commit.

  1. Make tasks small enough that the agent’s output fits in one diff you can read in 2 minutes. A 200-line diff is the soft cap.

  2. Use explicit negative constraints. “Do not introduce new dependencies,” “Do not modify files outside src/components/,” “Do not change the content schema.” A useful list to keep handy:

Constraint library
─────────────────────────────
DO NOT add npm/pip dependencies
DO NOT modify files outside <path>
DO NOT change <named-config-file>
DO NOT introduce client-side JS for <page-type>
DO NOT rename any export/symbol used elsewhere
DO NOT silently update package versions
DO NOT add comments that explain obvious code
  1. When the agent produces something close but wrong, send a diff, not a fresh prompt. Models follow edits better than “redo with these changes”. Format:
Apply this diff and produce the updated file:

@@ src/content/articles/en/indie-dev/foo.mdx @@
- Some sentence with a problem
+ The corrected sentence

  1. After each accepted change, update the spec file if anything in it implicitly changed. A 2-line edit beats a 2-hour drift debug a month later.

  2. For multi-file refactors, ask for a plan first, approve it, then execute step by step. Template:

Before editing any file, list:
1. Files you will change
2. The 1-line nature of each change
3. Risks / order dependencies
Wait for me to say "go" before producing diffs.
  1. Save successful prompts as templates. Build a prompts/ directory and store the ones that worked. Your prompt library compounds faster than your codebase.

Implementation checklist

  • CLAUDE.md (or equivalent) exists at repo root and matches reality.
  • Each per-task prompt has context, task, and constraints sections.
  • Constraint library lives in a shared note.
  • Successful prompts are saved as templates in prompts/.
  • Multi-file changes go through a plan-then-execute gate.

After-launch verification

  • A new agent session, fed the same spec + task prompt, produces a near-identical diff (low variance = low drift).
  • The agent declines or asks when a task violates a spec rule.
  • Spec file diffs match accepted feature changes.

Common pitfalls

  • Writing prompts as conversations instead of specs. “Hey, can you make the nav nicer?” produces nice-feeling, unpredictable output.
  • Letting the spec file go stale. If CLAUDE.md says you use Tailwind but you switched to CSS modules, the agent will pull in Tailwind on the next task.
  • Asking for too much at once. A prompt that includes “and also fix routing and add OG tags and update the footer” will get one of those right and the others wrong.
  • Skipping constraints because “obviously the agent would not do that.” It will do that.
  • Trusting that the agent remembers earlier in the same session. Long sessions lose early context — restate.
  • Approving large diffs without reading them. The next task will branch from whatever you accepted.

FAQ

  • How long should the spec file be?: One page max. If it grows beyond that, split into per-area files (CONTENT.md, DESIGN.md) and reference them from the top-level spec.
  • Should I use natural language or structured format?: Either, but pick one and stick to it. Mixed-style specs confuse the agent because it does not know which parts are normative.
  • Does this work for Codex too?: Yes. The principles are model-agnostic — they apply anywhere you are running an agent against a repo.
  • What if I am not technical enough to write a spec?: Have the agent write the first draft of the spec by interviewing you, then edit it. Bootstrapping is fine; the spec must still exist.
  • Should I include examples in the spec?: Yes. One concrete example beats five abstract rules.

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

Related Articles