Planning Before You Build with Claude Code

The biggest mistake people make with Claude Code isn't giving bad instructions. It's skipping the planning step entirely. "Build me a personal website." Five words. Claude will produce something in about thirty seconds. And you'll spend the next hour saying "no, not like that" and "change this" and "actually, start over." Fifteen minutes of planning saves an hour of correcting. ## Step 1: Set Up the Project Let's create a project folder and initialize it with Claude Code's memory. Open your terminal and run: **Windows (PowerShell):** ```bash mkdir "$HOME/Documents/my-portfolio" cd "$HOME/Documents/my-portfolio" ``` **Mac/Linux:** ```bash mkdir -p ~/Documents/my-portfolio cd ~/Documents/my-portfolio ``` Now start Claude Code: ```bash claude ``` ## Step 2: Write Your Bullet List Before Claude builds anything, make a list of what your website needs. Not in your head. Written down. Tell Claude: ```text Create a file called _docs/plan.md with a website plan. Here's what I want: Pages: - Home: my name, what I do, brief intro, call to action - About: my story, background, what I care about - Projects: 3-5 things I've worked on, each with a title and description - Contact: email address and a simple contact form Design: - Dark background, light text - Clean and minimal - Professional but not corporate Navigation: - Top of every page - Links to all four pages - Highlight the current page Content I need to write: - My tagline (what I do in one sentence) - About me paragraph (3-4 sentences) - Project descriptions (title + 2 sentences each) - Contact information ``` Adjust this to fit you. Different color preference? Different pages? Add or remove whatever doesn't apply. The point is writing it down before building. > **Have existing content?** Give Claude your CV, LinkedIn profile, or any digital content about yourself. Just say: "Here's my CV. Use this to write the content for my portfolio site." Or: "Here's my LinkedIn profile content - it's not up to date but good to start with." Claude will extract the relevant details and adapt them for web copy. Once Claude finishes, you should see the file created. You can open `_docs/plan.md` with any text editor (Notepad, VS Code, whatever you prefer) to review what Claude wrote. An example of what Claude might create: ```markdown # Website Plan ## Pages ### Home - Your name prominently displayed - What you do (tagline) - Brief intro paragraph - Call to action (e.g., "View my work" or "Get in touch") ### About - Your story and background - What you care about / your values - Personal touch without being too informal ### Projects - 3-5 featured projects - Each project includes: - Title - Description (2 sentences) - Optional: link, image, or tags ### Contact - Email address - Simple contact form (name, email, message fields) --- ## Design - **Theme:** Dark background, light text - **Style:** Clean and minimal - **Tone:** Professional but not corporate - **Typography:** Easy to read, modern font choices - **Spacing:** Generous whitespace --- ## Navigation - Fixed at top of every page - Links to: Home, About, Projects, Contact - Current page link highlighted/styled differently - Mobile-friendly (hamburger menu or responsive layout) --- ## Content To Write ### Tagline > What you do in one sentence > > _Example: "I build thoughtful digital experiences."_ ### About Me > 3-4 sentences covering: > - Who you are > - Your background > - What drives you ### Project Descriptions For each project (3-5 total): > **Project Title** > > Two sentences: what it is and what you did / why it matters. ### Contact Info - Email address to display - Any social links (optional) ``` ## Step 3: Show Claude What You Like This step is optional but effective. Find one or two websites you like the look of. They don't need to be similar to what you're building. You just need something to point at and say "that vibe." Take a screenshot and either: - Paste it directly into Claude Code (Ctrl+V or Cmd+V) - Save it to your project folder and tell Claude: "Look at screenshot.png in my project folder" Then say: ```text I like the feel of this design. Not everything about it, but the general tone. Clean, minimal, good use of space. I want my site to feel similar. ``` Or describe it in words if you don't have a screenshot: ```text I want something like a modern portfolio site. Think Apple-level clean. Lots of white space. Big headings. No clutter. ``` Claude uses this as a reference point. It won't copy the design, but it'll aim for the same aesthetic territory. When Claude wants to create or edit files, you'll see a permission prompt like this: ![Claude Code permission dialog asking to create plan.md with three options: Yes, Yes allow all edits during this session, and No](/images/blog/ai-tools/claude-code-permission-prompt.png) You have three options: 1. **Yes** - Approve this specific action (full control, asked every time) 2. **Yes, allow all edits during this session (Shift+Tab)** - Let Claude make file edits without asking again 3. **No** - Decline the action As you work through this guide, you'll see more of these prompts. If you want full control, always choose "Yes." If you trust Claude with file operations for this session, choose option 2 and you won't be interrupted. ## Step 4: Plan Mode Now let Claude plan the build. Press **Shift + Tab** to enter Plan Mode, then type: ```text Read _docs/plan.md and create a detailed build plan for this website. Show me what files you'd create, what each page would contain, and what the design approach would be. Don't build anything yet - just update the plan.md file with your detailed implementation plan. ``` Claude will come back with a structured plan. Something like this: ![Claude Code terminal displaying website build plan with file structure tree and ASCII wireframes showing page layouts for Home and About pages](/images/blog/ai-tools/claude-code-build-plan.png) The plan typically includes: - Files to create: `index.html`, `about.html`, `projects.html`, `contact.html`, `css/styles.css` - Home page layout: hero section with name and tagline, brief intro, link to projects - Design approach: dark background (#0d0d0d), light text, minimal borders, clean spacing - Navigation: horizontal links at top, current page highlighted Review this plan. Does it match what you want? If something's off, say so: ```text Good plan, but I want the navigation to be on the left side, not the top. And use a dark blue background instead of black. ``` Claude adjusts the plan. Once you're happy, tell it to proceed to the next step. > **Note:** Claude's output will vary from session to session. That's the beauty of working with AI. Your plan.md might look completely different from someone else's - different format, different structure, different level of detail. As long as it captures your intent, the format doesn't matter. Don't worry if yours looks nothing like the example. **Important reminder:** We're still planning, not building yet. Tell Claude explicitly: "Update plan.md with this plan, don't build anything yet." Claude can be eager and might start creating files. If it does, that's okay - let it finish or press **Esc** to stop it. You can also type while Claude is working if you need to redirect it. But ideally, we want the plan finalized before we start building. ![Claude Code apologizing for jumping ahead - showing it already created index.html, about.html, projects.html, contact.html and asking if user wants to delete them](/images/blog/ai-tools/claude-code-eager-building.png) ### Bonus: Enable the Design Plugin Claude Code has optional plugins that enhance its capabilities. For web design, the **frontend-design** plugin is the one you want - it gives Claude specialized knowledge about modern UI patterns, color theory, and professional design techniques. To enable plugins, type `/plugins` in Claude Code. You'll see a discovery screen: ![Claude Code plugin discovery screen showing available plugins: frontend-design with 141K installs, context7, code-review, github, and feature-dev with install counts](/images/blog/ai-tools/claude-code-plugin-discovery.png) Use **arrow keys** to navigate, **Space** to select plugins (you'll see an asterisk `*` next to selected ones), and **Enter** to install. The **frontend-design** plugin is the one we want for this project. You can also enable **feature-dev** if you want more structured feature development workflows. The interface may look slightly different in newer versions, but the concept is the same: find the design-related plugin and enable it. Once enabled, you can ask Claude to enhance your design plan: ```text Use your frontend design knowledge to improve the Design section in plan.md. I want a premium, modern, glossy website aesthetic. Give me specific recommendations for: - Color palette (with hex codes) - Typography choices - Visual effects (gradients, shadows, etc.) - Component styling - Overall visual hierarchy ``` Claude will update your plan with professional design specifications instead of generic "dark background, light text." This is optional but can noticeably improve your final design. ## Step 5: Create CLAUDE.md Before Claude starts building, let's give it permanent memory of your preferences. Tell Claude: ```text Create a CLAUDE.md file for this project based on our plan. Include the project description, design preferences, page list, and any rules we've discussed. Keep it concise - no code examples, just clear rules and references. Aim for under 50 lines. ``` Claude will create something like: ```markdown # My Portfolio Website ## Project Personal portfolio with 4 pages: Home, About, Projects, Contact. Built with HTML and CSS. No JavaScript unless needed. ## Design - Dark blue background (#0a1628) - White text, light gray for secondary text - Clean, minimal layout - Left-side navigation - Font: Inter ## Rules - Keep all CSS in css/styles.css - Images go in images/ - Pages go in the root folder - Every page must have a title tag and meta description ``` Now every future session starts with this context. You won't repeat yourself. ## The REQUIREMENTS.md Trick For bigger projects, I do something that works surprisingly well. Instead of writing the plan yourself, tell Claude: ```text Interview me about this project. Ask me questions about what I want, one at a time. When you have enough information, write a _docs/requirements.md file summarizing everything. ``` Claude becomes a project manager. "What's the primary purpose of this site?" "Who's the target audience?" "Do you want a contact form or just an email address?" "Any color preferences?" ![Claude Code interview mode asking about portfolio goals, with suggested answer "thought leadership and personal branding" shown as faded autocomplete text](/images/blog/ai-tools/claude-code-interview-suggestions.png) You answer each question. Claude compiles the answers into a structured document. This often captures details you wouldn't have thought to include on your own. **Tip:** Notice the faded text in the input field? After a question or two, Claude Code starts suggesting answers based on context. If the suggestion looks good, press **Tab** to accept it, then **Enter** to confirm. It's a small time-saver that adds up. After the interview, you can tell Claude to use the REQUIREMENTS.md to create your plan.md. They work together: requirements capture what you want, the plan captures how Claude will build it. ## What You Should Have Now At minimum, your project folder has: ``` my-portfolio/ CLAUDE.md _docs/ plan.md ``` If you used the interview approach, you might also have: ``` my-portfolio/ CLAUDE.md _docs/ plan.md requirements.md ``` > **Did Claude already start building?** Sometimes Claude gets enthusiastic and creates files before you ask. That's fine! If you have HTML files, CSS, or even a working site already - you're ahead of schedule. AI is unpredictable like that, and that's okay. Just make sure CLAUDE.md exists so your preferences persist across sessions. Two key things matter: Claude knows what you want, and that knowledge is saved. When you start building in the next chapter, every instruction builds on this foundation. Planning isn't overhead. It's the foundation. > Next up: building your first page. We'll start with the home page and create a reusable design pattern you can apply across the rest of the site.

Planning Before You Build with Claude Code

Step 1: Set Up the Project

Sign In to Unlock

Check Your Email