Build a Personal Website with Claude Code or Codex CLI

What you will build

By the end of this tutorial you will have a simple personal website page inside an existing project, generated and refined with an AI coding agent, and verified with a real build. Along the way you will practice the core skill that makes these tools useful: writing scoped requests instead of vague ones.

The example project is the Learn Web4 site itself, an Astro static site where pages live in src/pages/ and adding an .astro file creates a new route (see Astro’s pages documentation). The prompts below work in any project, though — only the file paths change.

A finished version already exists on this site: the Personal Website Demo. Open it in a second tab so you can compare as you go.

Prerequisites

You need exactly one AI coding agent installed and signed in. Pick one and follow its dedicated guide — install steps change often, so they live there instead of here:

Claude Code Installation Guide — Anthropic’s CLI agent. Current recommendation: the native installer curl -fsSL https://claude.ai/install.sh | bash, with npm still available as an advanced option (Claude Code quickstart).
Codex CLI Installation Guide — OpenAI’s CLI agent. Current installs include curl -fsSL https://chatgpt.com/codex/install.sh | sh, npm install -g @openai/codex, and brew install --cask codex (Codex CLI documentation).

If you are not sure what these tools are or which one fits you, read the local AI coding agents guide first.

You also need a project folder to work in — ideally one tracked by Git, because Git is your undo button (more on that in the safety notes).

Plan the four sections first

Resist the urge to prompt before you know what you want. A first personal website needs only four sections:

Section	Content
Personal introduction	Who you are, what you are learning, and what you want to build
Skills list	HTML, CSS, JavaScript, Astro, AI tools, and similar skills
Project showcase	Two or three practice projects
Contact information	Email, GitHub, LinkedIn, or portfolio links

That is enough for a stranger to understand you in thirty seconds, and small enough that an AI agent can build it in one pass without wrecking anything else.

Step 1: Ask the agent to read the project first

Open a terminal and enter the project folder:

cd learnweb4

Start your tool — claude for Claude Code or codex for Codex CLI.

Do not ask it to edit files immediately. Ask this first:

Please read this project first. Tell me what framework it uses, where the page files are, and where the content files are. Do not modify any files yet.

Two things happen here. You learn what the project roughly looks like, and the agent builds a correct mental model before touching anything. Agents that edit before reading are the source of most “it broke my site” stories.

Step 2: Make the first request

You can copy this prompt:

Please build a clean personal website with a personal introduction, skills, projects, and contact information. The style should be simple and suitable for a Web4 learner.
Please reuse the current project's layout and styles where possible. Do not rewrite the entire site CSS.
If a new page is needed, place it under an appropriate src/pages route.

The prompt pins down four things: the topic, the required sections, the style, and a hard boundary (do not break the existing site). Compare it with “build me a website” — the vaguer the request, the more the agent guesses, and the more you have to undo.

Step 3: Let the agent add the page

In Astro, files under src/pages/ become routes. In this project the agent created:

src/pages/demos/personal-website.astro

which generates:

/demos/personal-website/

Before you accept the result, check that the new page contains all four planned sections: introduction, skills, projects, contact. The Personal Website Demo on this site is the reference output.

Step 4: Switch the agent into review mode

Once the page exists, change the agent’s job from building to checking:

Please check this personal website page for obvious issues: title, mobile layout, internal links, SEO description, and accessibility. List the issues first, then suggest fixes.

Asking for a list first keeps the agent from charging ahead with changes you have not approved. Then bound the fix:

Please fix only the first three issues you listed. Do not edit unrelated files.

The clearer the scope, the steadier the result.

Step 5: Ask for focused improvements

After the first version works, refine it one request at a time. These prompts are ready to copy.

Make it feel more like a developer portfolio:

Make the page feel more like a developer portfolio.
Emphasize project cards, tech stack, and contact buttons.
Do not add complex animations.

Add dark mode:

Add a simple dark mode.
If the current project does not have a theme system, explain the smallest implementation plan first, then make the change.

Check mobile responsiveness:

Check mobile responsiveness.
Focus on whether text feels cramped on phone widths, cards become too narrow, and buttons are easy to tap.

Improve the SEO title and description:

Improve the SEO title and description for this personal website page.
Keep it natural and avoid keyword stuffing.
The title can include my name and personal website.

Replace the demo with your own content:

Please replace the demo content with my information:
Name: Your Name
Role: Web4 learner / frontend beginner
Skills: HTML, CSS, JavaScript, Astro, AI coding tools
Projects: Personal website, learning notes site, AI-friendly page checklist
Contact: your-email@example.com

If you later want the page to be readable and usable by AI agents, not just humans, that is a separate topic covered by the pillar on how to build an agent-ready website. You do not need it for a first portfolio page.

Verify the result

Two checks before you call it done.

First, the build. In this Astro project:

npm run build

A passing build means the page at least compiles and will be generated.

Second, your own eyes. Start the dev server, open the page in a browser, and resize the window to phone width. Agents are good at plausible-looking layout; only you can confirm the page actually reads well.

If the build fails, paste the error into the agent:

This is the npm run build error. Please explain the cause and give the smallest fix plan.

Explanation first, fix second — otherwise you learn nothing from the failure.

Common problems

Symptom	Likely cause	Fix
The agent rewrote unrelated files	Prompt had no scope boundary	Revert with Git, re-prompt with “do not edit unrelated files”
New page returns 404	File placed outside `src/pages/` or wrong extension	Move it under `src/pages/` as an `.astro` file and rebuild
Page looks broken or unstyled	Agent wrote its own CSS instead of reusing the site layout	Ask it to reuse the existing layout and remove the extra styles
Agent keeps adding features you did not ask for	Open-ended prompt like “make it better”	Request a specific change with an explicit stop condition
Build error after an edit	Syntax error in generated code	Paste the full error back and ask for the smallest fix

Safety notes

A few habits that keep AI-assisted editing boring instead of stressful:

Commit or stash your work before letting an agent edit. git diff and git checkout are the fastest undo you have.
Review the diff before accepting changes, especially in files the agent was not asked to touch.
Never paste API keys, tokens, or personal data you would not publish into a prompt. Assume prompts may leave your machine.
Run build and browser checks after every significant change, not once at the end — small errors are easy to locate, piled-up ones are not.

Practice task: make it yours

Open the Personal Website Demo and turn it into your own version:

Replace the name with your name.
Write one sentence about what you are learning.
Add five skills.
Add three practice projects.
Add a contact method you are comfortable making public.
Ask the agent to check mobile layout.
Ask the agent to improve the SEO title and description.

If you do not know how to start, copy this:

Please turn the personal website demo into my own personal website version. Ask me what personal information you need before making changes.

Letting the tool ask you questions first is a legitimate way to work — you do not have to specify everything up front.

When the page feels done, natural continuations are real project screenshots, GitHub links, and deploying it somewhere public. If a step above failed at the tool level, go back to the Claude Code Installation Guide or the Codex CLI Installation Guide.

FAQ

Do I need a complex framework for my first personal website?

No. A static page is enough at first. A clear introduction, skills, projects, and contact information matter more than chasing complex technology right away.

Will I learn less if I build a personal website with AI?

You will learn less if you only copy the result. A better approach is to ask AI to explain the project structure first, make changes step by step, and ask why each change was made.

Can I edit this demo directly?

Yes. Replace the demo name, skills, projects, and contact information with your own, then ask Claude Code or Codex CLI to improve mobile layout and SEO.

Changelog

Jul 26, 2026: Restructured into a goal → prerequisites → steps → verify → common problems → safety notes flow; moved install details to the dedicated install guides; added troubleshooting and safety sections.
May 8, 2026: Initial publication.