Build a Portfolio Site With Claude Code
Zero to live site in a few hours. No coding experience required.
What you'll end up with
A multi-page personal portfolio site — consistent theme, clean layout, responsive — deployed to a custom domain. Built with Next.js, styled with Tailwind CSS, hosted free on a static hosting provider. You'll own the code and can update it anytime by talking to Claude Code.
Before You Start
Install these (10 minutes)
The CLI that builds your site
Required to run Next.js
Version control — needed for deploy
Claude Code runs inside both
Also create a GitHub repo and an empty project folder on your machine before starting.
Create Your Brief + CLAUDE.md
Open Claude Code in your project folder and send this prompt. Claude will create two template files for you to fill in.
Create two template files for a personal portfolio site project.
brief.md — a site planning template with fill-in brackets for: who I am, site goal, pages + contents, design direction (tone, accent color, fonts), phase 1 definition, constraints.
CLAUDE.md — project memory file with fill-in brackets for: what this is (one line), design system (background/card/text/accent hex codes, fonts), file structure (app/ pages/, content/ data, components/), deployment (host: [your chosen host], trigger: push to main = auto-deploy, build: npm run build → out/), rules (never add unrequested features, never change design system without asking, never paraphrase my copy, whenever a new page or section is added add the corresponding content fields to content.md before building), read at session start (brief.md, content.md, SESSION_LOG.md).
Use realistic placeholder examples in each bracket so I know what format to use. Do not fill in any real content.Fill in brief.md and CLAUDE.md before moving on. These are the decisions that shape everything — your positioning, your pages, your design system. Take the time to get them right.
Need help filling them in? Ask Claude: "Interview me to help fill out brief.md and CLAUDE.md — ask me one question at a time." It will walk you through each field.
Once both files are filled in, send this prompt to generate your content template:
Read brief.md. Create content.md — a content template with a section for every page and section defined in the brief. Each field should have a [BRACKET] placeholder describing exactly what copy goes there. Shape the sections to match my specific pages, not a generic template.content.md is your content worksheet — one file with every text field on the site, ready to fill in before building.
Scaffold the Site
Send this prompt. Claude reads the files it just created and builds the full project structure.
Read CLAUDE.md and brief.md. Scaffold a personal portfolio site based on them.
STACK
- Next.js (App Router, TypeScript)
- Tailwind CSS v4 (config in globals.css via @theme, not tailwind.config.ts)
- Static export (output: 'export' in next.config.ts, images: { unoptimized: true })
- No database. No auth. No server features.
STRUCTURE
- Pages in app/
- Shared components in components/ (Nav, Footer, any reusable pieces)
- All content data in content/ as TypeScript files with typed exports
- TypeScript interfaces in content/types.ts
PLACEHOLDER RULES
- Use realistic placeholder text, not lorem ipsum
- Use [BRACKETS] for anything I need to fill in
- Create enough placeholder cards/items to make the layout reviewable
Build in this order: types → shared components → layout → pages (home first).
When done, confirm npm run dev and npm run build both succeed.After the scaffold builds
Run npm run dev and open localhost:3000
Click through every page — check layout, colors, spacing
Give feedback now, before adding real content. Layout changes are cheap on a scaffold, expensive on a finished page.
Add Your Real Content
Fill in content.md — replace every [BRACKET] with your real copy. This is different from brief.md, which defined the plan. content.md is the words: your bio, project descriptions, career history, anything that will appear as text on the site.
Have source material? Paste in your resume, LinkedIn bio, or any existing writing and ask Claude to draft the content fields from it: "Here's my resume: [paste]. Use it to fill in as many fields in content.md as you can. Leave brackets for anything not covered." You'll get a strong first draft to edit rather than starting from scratch.
Read content.md. Replace all placeholder content with my real content.
Update the content/ files — identity, projects, about, and any others.
Rules:
- Use my exact words — do not paraphrase or improve
- Do not change any layout, component, or design file
- Do not add new sections or pages
- If a field has no real content yet, leave the [BRACKET] placeholderReview each page after content is populated. This is where you'll catch copy that reads wrong or sections that need reordering.
Deploy
GitHub
Push your project to GitHub — this is the source of truth your host will pull from.
git init && git add -A && git commit -m "Initial scaffold"
git remote add origin https://github.com/[you]/[repo].git
git push -u origin mainOnce this is set up, every future deploy is just:
git add -A && git commit -m "Update" && git pushSite host
Connect your GitHub repo to a static hosting provider. They watch your main branch and redeploy automatically on every push.
Build settings (all hosts):
npm run buildOutput: outWhat vandervalk.ai uses. Fast global CDN, free custom domain.
Made by the Next.js team. Easiest setup for Next.js.
Similar to Vercel, well-established.
Iterate
Now you're in the feedback loop. Open Claude Code, describe what you want changed, review, push. The skill that saves the most time: giving specific feedback.
Instead of...
"The header looks off"
Say...
"Reduce the header text size to match the body"
"Make it more premium"
"Double the padding above each section heading"
"The image is wrong"
"Show the full headshot — use object-contain, not object-cover"
"Clean this up"
"Remove the status badges from project cards"
One sentence: what you see + what should change.
Keep a Session Log
Claude Code doesn't remember previous sessions. A session log fixes this — and Claude writes it, not you. At the end of each session, say:
"Log this session."
Claude will append an entry to SESSION_LOG.md covering what was built, what was decided, and what's next. CLAUDE.md already tells Claude to read this file at session start, so every session picks up where the last one ended.
To make this permanent, add this rule to your CLAUDE.md:
When asked to "log this session", append an entry to SESSION_LOG.md with: what was built, key decisions made, and the recommended next action.Tips That Save Hours
Scaffold first, content second.
Get the structure right before writing any content. An empty scaffold is easy to change; a half-built site with the wrong structure is expensive to change.
One page at a time.
Don't ask Claude Code to build everything at once. Build, review, iterate, move on.
Your words, not AI words.
Add your real copy to brief.md and tell Claude to use it verbatim. The output will be dramatically sharper than anything it drafts on its own.
Two-way door decisions.
If a choice is reversible — a color, a layout, a font — just decide and move. Say "let's go with X." Don't agonize over things you can change in 30 seconds.
Describe what you see.
When giving feedback, name the specific element and say exactly what should change. Vague feedback = vague results.
Based on building vandervalk.ai with Claude Code in April 2026.