Project Setup & Architecture

Lesson 19

Before writing a single line of code, ask Claude Code to plan the architecture. This one step prevents the most common vibe coding mistake: jumping straight to implementation and then having to restructure everything halfway through.

The architecture prompt

Start every project with this prompt:

다음 사이트를 만들려고 해. 어떤 파일 구조를 추천해?

포트폴리오 사이트:
- 홈페이지 (소개 + featured work)
- Work 페이지 (프로젝트 그리드)
- About 페이지
- Contact 폼
- 디자인 토큰 (색상, 타이포그래피, 간격)

A good architecture answer looks like a file tree with a brief rationale for each decision — not just a list of folders. If the answer doesn’t explain why, follow up: “각 폴더와 파일이 왜 필요한지 설명해줘.”

Start static, layer in JS

The principle is simple: get the HTML content structure right before adding any behavior. A common mistake is asking for a fully interactive component in the first prompt. Instead, build in two passes:

  1. Pass 1: “HTML만 먼저 만들어줘. CSS나 JS는 아직 필요 없어.”
  2. Pass 2: “이제 스타일 추가해줘. 이 디자인 토큰 파일 기준으로.”

This forces AI to focus on semantic structure first, which leads to better accessibility and cleaner code.

Design token setup

After the file structure is agreed on, ask Claude Code to generate your design tokens from your brand colors:

브랜드 컬러: primary #2563eb, neutral #111.
이 색상 기반으로 CSS custom properties 세트를 만들어줘.
라이트 모드와 다크 모드 버전 포함.
--color-primary, --color-bg, --color-surface, --color-text,
--color-text-secondary, --color-border 형태로.

The result is a design-tokens.css file that every other file imports. This means changing your brand color later requires editing exactly one line.

Folder naming conventions

Claude Code follows consistent conventions when you ask it to generate a project structure. Files go where developers expect them: pages/ for HTML files, components/ for reusable snippets, assets/ for images and fonts. Always ask Claude Code to follow the convention it generates — if you stray from it mid-project, the AI loses context of where things live.

The portfolio project

This module builds toward a complete portfolio site. Each lesson adds a layer: this lesson sets up the structure, the next adds phased development, and later lessons cover review and deployment. By the end, you have a real deliverable, not just isolated demos.

The demo shows the portfolio project’s file structure as an interactive tree. Click any file or folder to see what it contains and a starter code snippet. A design tokens panel below the tree shows the CSS variables palette with live color swatches.