# How to customize an Astro template with Claude Code: a step-by-step plan

> Five steps from an unpacked Astro template to a published site with Claude Code: prompts to copy, a check after each step and save points in Git.

- Author: [Vas](https://shipthemes.com/authors/vas)
- Published: Oct 29, 2026
- URL: https://shipthemes.com/blog/customize-astro-template-with-claude-code

You've downloaded or bought a ready-made Astro website template and want to make it yours: your name, colours, copy and pricing. Doing it all by hand is slow and tedious. So you can hand the routine work to an assistant, Claude Code, and keep the decisions and the checking for yourself.

Below is a plan in five steps, from an unpacked archive to a finished site. Each step has a prompt you can copy and a way to check the result. You don't need to be a programmer, but you will need to open a terminal or the Claude app once and run a few commands.

This article covers one specific path: an Astro template and Claude Code. The general plan for working with any template and AI is in [How to work with a website template using AI: a simple step-by-step plan](https://shipthemes.com/blog/work-with-website-template-using-ai). For more on the rules file for the assistant, see [our guide to AGENTS.md and CLAUDE.md](https://shipthemes.com/blog/agents-md-claude-md-llms-txt). You can read this article without them.

> **Current as of October 26, 2026.** The Claude Code commands and modes were checked against its documentation on that date.[1] Versions and subscription terms change, so check the current pages before you start.

## In short

First preparation, then five steps. After each step there is a check and a "save point" in Git, so you can always go back.

- **Preparation.** Unpack the template, save it in Git and make sure it builds before you change anything.
- **Step 1. Map the project.** Have the assistant study the project and explain where everything lives. Write a few short rules for it.
- **Step 2. Brand.** Name, colour, fonts and logo, using what the template already has, without reworking the layout.
- **Step 3. Copy and offer.** Service pages and pricing are written from your list of facts. What you don't know stays a [TODO] marker, not an invention.
- **Step 4. Check it like a customer.** Look at the site on a phone, find leftover demo text, run the build.
- **Step 5. Publish.** Put the site on any static host.

In the end you get a site with your name, colours and copy that builds without errors and has been checked on a phone. What the assistant won't do: it doesn't know your facts, prices and terms. You supply those yourself; more on that near the end.

## What you need

Besides the template itself, you need four things.

| What | Why | What to know |
|---|---|---|
| Node.js | Runs the site on your computer | Current Astro needs version 22.23.4 or higher; odd-numbered versions such as 23 are not supported.[2] The command `node --version` shows yours |
| Git | Keeps "save points" and lets you go back | A free program. For Windows, the Claude Code documentation recommends Git for Windows[1] |
| Claude Code | The assistant itself | Works in a terminal or in the Code tab of the Claude app[1, 3] |
| Paid access to Claude | Claude Code won't start without it | A Pro, Max, Team or Enterprise subscription; for the terminal, a Console account or a supported cloud provider also works[1, 3] |

### How to launch Claude Code

**Option 1. The Claude app.** Install the app and sign in. Open the **Code** tab, choose the **Local** environment, then **Open folder…** and pick the project folder. The Code tab itself needs neither Node.js nor a terminal; the assistant's changes show up in a diff view, and in **Plan** mode it first proposes a plan and edits nothing.[3] You still need Node.js to run the site itself.

**Option 2. The terminal.** Install on macOS, Linux and WSL:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Install in Windows PowerShell:

```powershell
irm https://claude.ai/install.ps1 | iex
```

After installing, open a new terminal window and check the installation with `claude --version`. To start working, go to the project folder and type `claude`.[1]

## Honest about what this is

**This is a plan, not a test report.** We did not time it and have not tried this plan on a client's site. "An evening or two" is our estimate for someone comfortable with a computer; it may take you longer. The prompts below are a starting point: in your template the folders and files may be named differently, so the first thing the assistant does is study your project.

**The assistant makes mistakes.** The Astro documentation says plainly that AI-generated code must be reviewed carefully and tested.[4] It also warns that AI tools may use outdated approaches and not know about newer Astro features.[4] That is why every step in the plan has a check.

**You don't need secrets.** Don't put passwords, access keys or customers' personal data into the project or into the chat with the assistant. For an ordinary brochure site you typically don't need them.

## Preparation: save the template and make sure it builds

Before you change anything, you need to know that the original template works. Then any error later comes from your edits, not from the template. The assistant isn't needed here yet, only a few commands.

1. Unpack the archive into a convenient folder and open a terminal in it. In the Claude app, the terminal opens with Ctrl+`.[3]
2. Save the original state. If the folder already has a hidden `.git` folder, skip this step.

   ```bash
   git init
   git add -A
   git commit -m "Initial template"
   ```

   If Git asks you to introduce yourself, it will tell you which commands to run.
3. Install the dependencies and start the site:

   ```bash
   npm install
   npm run dev
   ```

   Open the address the terminal shows in your browser, usually `http://localhost:4321`.[5] You can stop the site with Ctrl+C. Warnings during installation are normal; errors are not.
4. Check the build:

   ```bash
   npm run build
   ```

   The build creates the finished site files, by default in the `dist` folder.[5] If it finishes without errors, the original template is fine. If not, a common cause is a Node.js version that is too old (our assessment): compare `node --version` with the table above.

If the commands in your template are named differently, they are listed in the README file and in the `scripts` section of `package.json`.

Done: you have a working template and a first "save point."

## Step 1. Have the assistant study the project without changing anything

Before editing anything, the assistant has to understand where the pages, colours, fonts and copy live in your template. Different templates name their folders differently, so there's no point guessing: let it look at your project.

Turn on plan mode. In the terminal, press Shift+Tab until plan mode appears, or start with `claude --permission-mode plan`; in the app, choose Plan mode. In this mode the assistant studies the project and proposes a plan, but doesn't change files.[6, 3]

A prompt to copy:

```text
Study this Astro project and change nothing. Explain in plain words, without jargon:
1. Which pages the site has and which files they live in.
2. Where the site name, menu and footer are set.
3. Where the colours, fonts and logo live.
4. Where the page copy and pricing live.
5. Which commands are needed to run, check and build the site.
At the end, list the files that are best left alone when changing the brand and copy.
```

**Check:** the answer names real files from your project, not general words. If the assistant couldn't find something, that's fine: clarify the question.

### Write a few short rules

The assistant doesn't remember past conversations, but it reads the rules file in the project folder every time. Don't turn that file into a description of the whole project. A 2026 study of such files found that they did not reliably raise the share of tasks solved but did make the work more expensive: by over 20% on average for files written by AI, and by up to 19% for files written by developers. They helped where non-standard rules needed describing.[7] Its tasks were Python projects, not website templates, so treat it as a guide, not a law.

So the file contains only what can't be understood from the code itself: check commands, where things live and what must not be done. Leave plan mode (Shift+Tab) and give a second task: "Create an `AGENTS.md` file following the sample below, filling in the real paths from your answer. Add nothing extra."

```markdown
# AGENTS.md

## Commands
- `npm run dev`: run the site locally
- `npm run build`: build the site. It must pass without errors before you say "done"

## Where things live
- Site name, menu, footer: [path from the answer]
- Page copy: [path from the answer]
- Colours and fonts: [path from the answer]

## Rules
- Change only what I ask for. Don't touch layout, spacing or component markup if the task is about copy or branding.
- Use the colours and fonts already defined in the template. Don't add new libraries or fonts.
- Use only the facts I give you. If a fact is missing, write [TODO: what is needed]; invent nothing: names, numbers, prices, reviews, clients.
- Before finishing, show the list of changed files and run the build.
```

Claude Code reads `AGENTS.md` directly from version 2.1.277, and the documentation recommends keeping a `CLAUDE.md` file under 200 lines;[8] the same logic applies to `AGENTS.md` (our assessment). If your version is older or the assistant doesn't see the file, create a `CLAUDE.md` next to it with a single line, `@AGENTS.md`: it pulls in the contents of the first file.[8] For more on how to write these files, see our [guide to AGENTS.md and CLAUDE.md](https://shipthemes.com/blog/agents-md-claude-md-llms-txt).

An optional tip: if the assistant gets confused about Astro's features, connect the free Astro documentation server with `claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp`.[4]

**Save:** use `git status` to check that only the rules files appeared, and make a commit.

```bash
git add -A
git commit -m "Add AGENTS.md"
```

## Step 2. Brand: name, colours, fonts and logo

We change only what the template already exposes as settings: name, colours, fonts, logo. We don't touch the layout: in a good template the spacing and the look on a phone are already worked out, and extra edits easily spoil them.

Don't ask for "make it pretty." Name concrete values and forbid the extras. A prompt to copy (replace the [brackets] with your own):

```text
Rebrand the site for my company. Change only the name, logo, colours, fonts and copy. Don't change the layout, page structure or component markup, and don't add libraries.

Details:
- Name: [name]
- What we do, in one sentence: [description]
- Main (accent) colour: [#RRGGBB]
- Fonts: [heading font] and [body font], or keep the template's fonts
- Logo: file [path to file]; put it where the current logo lives

Use the colours and fonts through what is already defined in the template (variables or settings), rather than writing them in again in every place. After the edits, run the build and show the list of changed files.
```

The sentence about the build isn't for show. The Claude Code documentation advises always giving the assistant a check it can run itself: tests, a build or a screenshot to compare.[9] For a website, that check is `npm run build`.

**Check:**

- Run `npm run dev` and look at the home page and one inner page. Is the old name left in the menu, the footer or the browser tab title?
- Is the text on buttons and coloured backgrounds readable? Light text on a light accent is a common problem (our assessment).
- `git diff --stat` shows which files changed. They should be settings, styles, copy and images. If the assistant changed component markup or page structure, ask it to undo those edits.

**Save:** `git add -A`, then `git commit -m "Rebrand"`.

## Step 3. Copy and offer: service pages and pricing

The template has pages with demonstration copy: services or features, pricing, blog, contact. They need rewriting for your business. This is where the assistant is most useful and most dangerous: it happily invents attractive but made-up facts.

So the order is: first you write a list of facts, then the assistant turns it into copy. What the list should contain:

- what you sell (three to five items, one sentence each);
- who it's for;
- pricing: names, prices, what each plan includes;
- contacts;
- what you don't have. If you have no reviews, case studies or awards, write that down, so the assistant doesn't invent them for you.

A prompt to copy:

```text
Rewrite the service pages and the pricing page for my company. Use only the facts from the list below. If a block lacks a fact, leave a [TODO: what is needed] marker in the text and invent nothing: no numbers, no client names, no reviews, no awards, no prices.
Write in plain language, in short sentences, without the words "unique", "cutting-edge" and "innovative".
Don't change the layout. If I have a different number of services or pricing plans than the template, ask me first and only then change the structure.
If the template has demo blocks for which I have no facts (reviews, client logos, statistics), list them and I will decide what to do with them.
After the edits, run the build and show the list of changed files.

Facts:
[paste your list here]
```

Work on one page at a time: it's easier to check the result. Between unrelated tasks, enter the `/clear` command so the assistant doesn't drag leftover context from the previous task into the new one.[9]

The privacy policy and terms pages are not part of this step. Why is explained in the section "Where the assistant doesn't decide for you."

**Check:**

- Compare every price, number and name with your list of facts. The assistant may have "slightly improved" them for a nicer phrase.
- Ask it to find all `[TODO]` markers and list them. Each one you must close yourself or remove the block; otherwise the marker stays on the site.
- Run `npm run build`.

**Save:** `git add -A`, then `git commit -m "Rewrite pages and pricing"`.

## Step 4. Check the site like a customer

A build without errors doesn't mean the site is good. Go through it the way a customer will. That's five checks.

1. **Phone.** Run `npm run dev`, open the site in Chrome and press F12. In the developer tools, turn on the **Toggle device toolbar** button, choose Responsive mode and enter a width of about 360 pixels (our choice: a typical narrow phone).[10] The Chrome documentation warns that this is only an approximation, and that testing on a real device is more reliable.[10] Look for cut-off text and horizontal scrolling, and check that the menu opens and the buttons can be tapped with a finger.
2. **Template leftovers.** Ask the assistant to find everything left over from the original:

   ```text
   Find everything left over from the original template in the project: the previous name, demo names and companies, other people's email addresses, links to the demo site, lorem ipsum and placeholder images. Change nothing, just show the list of files and lines.
   ```

   Then open every page from the menu and click every link and button. While you're at it, check that each page has its own title in the browser tab.
3. **The form.** The form on the site has to send messages somewhere. How that works depends on the template, so send a test message and make sure it reaches you, not a demo address or nowhere.
4. **The build.** Run `npm run build`. If the template has a check command (often `npm run check`), run that too: `astro check` finds errors in `.astro` files and exits with an error if it finds something.[5] `npm run preview` shows the built site the way visitors will see it; it isn't meant for publishing.[5]
5. **Edits you didn't ask for.** `git diff --stat` shows which files changed; in the Claude app you see the same in the diff view.[3] The changes should touch only settings, styles, copy and images. If the assistant changed the layout "while at it," ask it to undo those edits.

**Save:** if you had to fix something, run `git add -A` and `git commit -m "Fix after review"` again.

## Step 5. Publish the site

Astro builds the site into ordinary ready-made files (the `dist` folder),[5] so any static host will do. The Astro documentation has instructions for many hosts.[11] For a detailed walkthrough using Cloudflare as the example, see our [guide to publishing on Cloudflare](https://shipthemes.com/blog/publish-astro-site-on-cloudflare).

Go through this list before publishing:

- no `[TODO]` markers are left in the copy;
- contacts and prices are real, and you checked them against your own list yourself;
- the template's demo site address has been replaced with yours (the assistant will find it with the prompt from Step 4);
- `npm run build` passes without errors and the site has been checked on a phone;
- everything is saved in a commit;
- the legal pages are ready (see below).

## If something goes wrong: how to roll back

This is exactly why we make a commit after each step. Two simple cases:

- **The edits aren't saved yet, and one file doesn't suit you.** The command `git restore path/to/file` returns the file to its last saved state, and your unsaved edits in it are lost. It works for edits you haven't yet added with `git add`: if you did add them, the file returns to its state at the time of `git add`.[12]
- **A commit is already made, but you don't like the result.** `git revert HEAD` creates a new commit that undoes the last one; the old history isn't rewritten. For this, the folder must have no unsaved edits.[13]

If you don't know which command to choose, ask the assistant. But ask it to explain first what the command will do, and don't let it run deleting commands until you understand what they mean.

Claude Code also has its own quick "undo": pressing Esc twice or the `/rewind` command restores a previous state. But it tracks only edits made by Claude's own tools and, according to the documentation, is not a replacement for Git.[9] Rely on commits.

## Where the assistant doesn't decide for you

You can hand over the routine, but not the responsibility. Five things stay with you:

- **Facts about you.** Services, timelines, experience, clients, reviews, awards. The "don't invent" rule in the `AGENTS.md` file lowers the risk but doesn't guarantee there are no errors. Read all the text yourself.
- **Prices and terms.** Whatever the site says, the buyer will expect to receive. Check every figure yourself.
- **Legal pages.** Privacy policy, terms of service, refund terms, cookie consent. They must describe your business and your country, and text from a template or from AI may not fit. Show them to a lawyer. We are not lawyers, and this is not legal advice.
- **The licence and rights to materials.** Every template has its own licence terms: read them before publishing. Images and fonts that you add yourself must be yours or carry a suitable licence.
- **A last look.** Before publishing, go through the site yourself as a visitor, without relying on the assistant saying "all done."

## Summary

Claude Code is good at the routine: moving the name and colours over, rewriting copy from your list of facts, finding forgotten bits of the demo (our assessment, not a measurement). Deciding what to tell the customer, and checking the result, is still up to you. Three rules keep the work calm:

- a commit after each step, so you have somewhere to go back to;
- one task at a time, so you check small pieces;
- checking with the build and with your own eyes, not on the assistant's word.

If you don't have a template yet, take a look at the [ShipThemes catalog](https://shipthemes.com/templates). The templates are standard Astro projects, so Claude Code, Cursor, Codex or GitHub Copilot can open them and make changes from plain-English instructions. For example, [Nodezy](https://shipthemes.com/templates/nodezy) is a template for AI products with 13 pages: home, three feature pages, pricing, a journal and an article page, contact, sign-up, log-in, a 404 page, privacy policy and terms. The standard licence covers your own and your clients' sites, on as many projects as you need, but not reselling the template itself, and it includes updates ([licence](https://shipthemes.com/license)). The current price is on the [template page](https://shipthemes.com/templates/nodezy).

### Keep reading

- [How to work with a website template using AI: a simple step-by-step plan](https://shipthemes.com/blog/work-with-website-template-using-ai): the general plan, suitable for any template and tool.
- [AGENTS.md, CLAUDE.md and llms.txt](https://shipthemes.com/blog/agents-md-claude-md-llms-txt): how to write a rules file for the assistant.
- [How to publish an Astro site on Cloudflare](https://shipthemes.com/blog/publish-astro-site-on-cloudflare): Step 5 in more detail.
- [Astro vs Next.js for a company website](https://shipthemes.com/blog/astro-vs-nextjs-marketing-sites): if you haven't yet decided what to build the site on.

## Frequently asked questions
### Do I need a paid Claude plan?

Yes. Claude Code requires a Pro, Max, Team or Enterprise subscription; for the terminal, a Console account or a supported cloud provider also works.[1, 3] There is no free plan on that list. We don't give prices here because they change: check the current ones on Claude's pricing page.

### Do I need a terminal?

Not for the assistant itself: the Code tab in the Claude app works without a terminal and without installing Node.js for it.[3] But you need Node.js to run the site itself, and you'll have to run a few commands (`npm install`, `npm run dev`, Git). You can enter them in the app's built-in terminal or ask the assistant: in manual mode it asks before editing files or running commands.[3]

### What if the assistant breaks the site?

Don't panic; roll back to the last save point. The commands are in the section "If something goes wrong: how to roll back." That's why the plan has a commit after every step. The smaller the tasks, the fewer edits you'll have to undo.

### Does AI invent facts?

It can: make up clients, reviews, figures and awards for the sake of nice copy (our assessment: it makes mistakes with code, and with copy too). The protection has three parts: a list of facts, the rule "no fact, write [TODO]," and your own check of every figure before publishing. The first two reduce the risk, but only the third removes it.

### What do I do when a new version of the template comes out?

Your site is already a modified copy, so a new version won't pull in by itself. A sensible way (our assessment; we haven't tried it in practice): download the new version into a separate folder, ask the assistant to compare it with your first commit, "Initial template," and list what changed, then bring over what you need as a separate task with a separate commit. Don't copy the new version over your site wholesale: you'll lose your edits.

### Can I use ChatGPT, Cursor or another assistant instead of Claude Code?

Yes. The plan itself (Git, rules, steps and checks) doesn't depend on the tool. Many tools support the `AGENTS.md` file: the list on the format's site names, for example, Codex, Cursor, VS Code, Gemini CLI and GitHub Copilot coding agent.[14] But the commands and modes in this article are described for Claude Code; other tools name them differently. We have only checked the plan against the Claude Code documentation, not tested it.

## Sources

Pages checked on October 26, 2026.

1. [Anthropic, "Quickstart" (Claude Code: installation, account requirements)](https://code.claude.com/docs/en/quickstart)
2. [Astro, "Install Astro" (Node.js requirements, creating a project from a template)](https://docs.astro.build/en/install-and-setup/)
3. [Anthropic, "Get started with the desktop app" (Claude Code: the Code tab, permission modes, reviewing changes)](https://code.claude.com/docs/en/desktop-quickstart)
4. [Astro, "Building Astro sites with AI tools" (warning about AI mistakes, the Astro documentation server)](https://docs.astro.build/en/guides/build-with-ai/)
5. [Astro, "CLI commands" (the `astro dev`, `build`, `preview` and `check` commands; default port)](https://docs.astro.build/en/reference/cli-reference/)
6. [Anthropic, "Choose a permission mode" (plan mode, switching with Shift+Tab)](https://code.claude.com/docs/en/permission-modes)
7. [Gloaguen T. et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" arXiv:2602.11988 (v1: February 12, 2026; v3: September 29, 2026)](https://arxiv.org/abs/2602.11988)
8. [Anthropic, "How Claude remembers your project" (CLAUDE.md and AGENTS.md, the `@AGENTS.md` import, file size)](https://code.claude.com/docs/en/memory)
9. [Anthropic, "Best practices for Claude Code" (checking results, `/clear`, rollback and Git)](https://code.claude.com/docs/en/best-practices)
10. [Google Chrome for Developers, "Simulate mobile devices with device mode" (device mode in DevTools)](https://developer.chrome.com/docs/devtools/device-mode)
11. [Astro, "Deploy your Astro Site" (instructions for hosts)](https://docs.astro.build/en/guides/deploy/)
12. [Git, "git-restore" (documentation)](https://git-scm.com/docs/git-restore)
13. [Git, "git-revert" (documentation)](https://git-scm.com/docs/git-revert)
14. [AGENTS.md, "AGENTS.md" (the format and the list of supporting tools)](https://agents.md)
