A guide for building an AI-assisted portfolio site using Claude Code. Not a template — a process. Your site should look and feel like you, not like mine.
This guide gives you the prompt structure and step-by-step process to build a portfolio site with Claude Code as your technical partner. But the important parts — your story, your visual direction, your quality bar — come from you.
This is not fully automated, on purpose.
You could paste a prompt and get a site in 20 minutes. It would look generic. The value of this process is the thinking it forces: what do you want people to understand about you? What should your site feel like? What are you not? Those answers can’t be delegated.
Claude Code is your builder, but you are the product owner. You need to arrive with answers to these questions — or be willing to think through them in the process.
1. Your positioning
What role are you targeting? What audience will see this? What should they understand in 30 seconds? What’s your career arc in 3 sentences?
2. Your visual direction
Find 2-3 sites whose visual energy you admire. Not portfolios — any site with a feeling you want. Share these as reference. Claude Code can’t invent taste; it can execute a direction you define.
3. Your shipped work
A list of 8–20 things you’ve shipped, with: title, company, 1-line description, public link (if available), and a category tag. This is your evidence.
4. Your anti-patterns
What do you NOT want? Skill bars? Dark mode? Timeline graphics? Corporate tone? “Passionate about” copy? Knowing what to avoid is as important as knowing what to build.
5. Your willingness to review and decide
The AI will produce draft copy, layout options, and design directions. You need to review them, say what works, say what doesn’t, and make the call. This is the job.
Use the starter prompt below. Fill in every blank. The more specific you are about positioning, audience, and visual direction, the better the output. Spend 30–60 minutes on this.
⚠ YOU DO THIS. Claude cannot invent your career story or aesthetic taste.
Take your brief to claude.ai and ask it to produce a visual design prototype (HTML mockup). Share your reference sites. Ask for 2–3 directions. Pick one and refine it.
⚠ YOU DO THIS. You must choose and refine the visual direction. Don’t skip this step — a generic-looking site wastes everything that follows.
Open Claude Code in your terminal. Give it your brief and your approved visual direction. Ask it to scaffold the project, set up the tech stack, and build the page structure. It will create the files, install dependencies, and get a development server running.
Claude Code does this. You review the result.
Ask Claude to draft copy for each section. Then review every word. Read it out loud. Does it sound like you? Would you say this in a conversation? If not, ask for revisions. Be specific about what feels off.
⚠ YOU DO THIS. The copy is how the world sees you. You approve every sentence. Expect 2–3 revision rounds.
Claude Code builds the pages, components, and interactions. You preview in the browser. You give feedback: “the cards feel too cramped,” “the hero needs more breathing room,” “this section doesn’t need to exist.” Iterate until it feels right.
This is collaborative. Claude builds, you direct.
Push to GitHub, deploy to Vercel (free). Connect your domain. Done. Claude Code can walk you through every step.
This is the prompt you give to Claude Code (or Claude on the web for the design phase). Replace everything in [brackets] with your own information.
Claude Code is a terminal tool, not a web app.
Install it with npm install -g @anthropic-ai/claude-code, then run claude in your project folder. It reads and writes files directly on your machine.
Start with the brief, not the code.
Don’t jump into “build me a site.” Give it the full brief. The more context it has about you, your audience, and your visual direction, the less iteration you’ll need.
Use Claude Design (claude.ai) for visual exploration first.
Claude on the web can produce HTML mockups quickly. Use it to explore visual directions before committing to code. Paste your reference sites and ask for 2–3 prototype directions. Once you pick one, bring it to Claude Code for the real build.
Preview constantly.
After Claude Code makes changes, preview in your browser. Give feedback on what you see, not what you imagine. “The spacing between cards feels tight” is better feedback than “make it look better.”
Read the copy out loud.
The biggest risk with AI-assisted copy is that it sounds like AI. Read every section out loud. If a sentence doesn’t sound like something you’d say in a conversation, change it. This is the most important quality gate.
You can use a CLAUDE.md file for persistent context.
Create a CLAUDE.md file in your project root with your brief, brand guidelines, and key decisions. Claude Code reads it automatically every session — so you don’t have to repeat yourself.
Commit often. Push to GitHub.
Claude Code can commit for you. Ask it to commit after each meaningful change. This gives you a safety net — you can always go back. Push to GitHub for backup and for Vercel auto-deploy.
Don’t accept the first draft.
The first version will be competent but generic. The second version, after your feedback, will be better. The third version, after you’ve made specific decisions about tone, content, and visual details, will actually feel like yours. Budget 3–5 iteration rounds for a site you’re proud of.
Decide your positioning for you. You need to know who you’re talking to and what you want them to do. The AI builds the container; you fill it with meaning.
Replace taste. If you don’t have opinions about how your site should feel, the output will be mediocre. Bring references. Be specific about what you like and don’t like.
Write your story. It can help you structure and edit, but the raw material — your career arc, your key achievements, your point of view — comes from you.
Produce a unique-looking site without direction. Without visual references and specific anti-patterns, you’ll get a competent but forgettable template. The uniqueness comes from your inputs.