이 문서는 순수 HTML과 Tailwind CSS v4로 만든 사이트를, 브라우저에서 실시간으로 CSS를 만들어 주던 방식에서 미리 컴파일된 하나의 정적 CSS 파일로 굳혀 다시 배포하는 절차를 다룹니다. AGY(구글 안티그라비티)로 사이트를 만들어 GitHub Pages에 이미 올린 상태를 전제로 씁니다. 다 따라 하면 브라우저가 페이지를 열 때마다 CSS를 계산하는 부담이 사라지고, 배포 파일 하나만 보고도 어떤 스타일이 들어갔는지 확인할 수 있게 됩니다.
이 매뉴얼은 CLI 명령을 학습자가 직접 치는 대신 AGY에게 프롬프트로 시켜 실행하게 하는 바이브 코딩 방식으로 씁니다. 각 절 끝의 「AGY 프롬프트」 블록을 그대로 복사해 AGY 대화창에 붙여 넣으면 됩니다.
1 – 왜 최종 빌드가 필요한가
Tailwind CSS는 사용자가 HTML에 적은 class="..." 값을 훑어 필요한 스타일 규칙만 골라 CSS로 만들어 줍니다. 사이트를 만들 때는 이 계산을 브라우저에서 실시간으로 시키는 「Play CDN」 방식이 편하지만, 실제 사용자에게 보이는 사이트에서는 세 가지 문제가 있습니다.
- 페이지를 열 때마다 브라우저가 스타일을 다시 계산해서 화면이 뜨기까지 시간이 더 걸립니다.
- Tailwind가 지원하지 않는 오래된 브라우저에서는 스타일이 아예 안 나올 수 있습니다.
- 배포된 파일만 봐서는 어떤 스타일이 최종적으로 들어갔는지 확인이 어렵습니다.
최종 빌드는 Tailwind CLI라는 명령 도구를 한 번 돌려 정적 CSS 파일 하나를 미리 만들어 두는 일입니다. HTML은 그 파일 하나만 <link>로 불러오면 되므로 위 세 문제가 모두 사라집니다.
2 – 준비
이 작업은 팀 사이트 소스가 자기 컴퓨터에 내려받아져 있고, AGY 프로젝트에 그 폴더가 열려 있는 상태에서 시작합니다.
폴더 안 파일 구조는 팀마다 조금씩 다르지만 아래 두 가지가 있어야 합니다.
- HTML 파일 여러 개(대표 페이지 + 나머지 페이지들).
@theme { ... }블록이 들어간 CSS 파일 한 개(이름은 팀마다 다름. 예:style.css,main.css).
Node.js가 자기 컴퓨터에 설치돼 있어야 Tailwind CLI를 실행할 수 있습니다. AGY 대화창에 node -v를 물으면 설치 여부와 버전을 알려 줍니다. v20 이상이 나오면 됩니다. 아무 응답이 없거나 command not found가 나오면 nodejs.org에서 LTS 버전을 먼저 설치합니다.
3 – Tailwind CLI 설치
Tailwind CLI는 팀 프로젝트 폴더 안에만 설치합니다. 다른 프로젝트에 영향을 주지 않도록 지역 설치(local install)로 넣습니다.
지역 설치는 프로젝트 폴더 안 node_modules에만 저장되는 방식입니다. 다른 폴더에서는 이 도구가 안 보이므로 팀마다 독립적으로 관리할 수 있습니다.
AGY 프롬프트:
이 프로젝트 폴더에 Tailwind CSS v4를 지역 설치해 주세요.
1) 프로젝트 루트에 package.json이 없으면 npm init -y 로 만듭니다.
2) 다음 명령을 실행해 Tailwind와 CLI를 함께 설치합니다.
npm install tailwindcss @tailwindcss/cli
3) 설치가 끝나면 node_modules/@tailwindcss/cli 폴더가 생겼는지 확인해 결과를 알려 주세요.프롬프트를 AGY 대화창에 붙여 넣고 실행하면 AGY가 순서대로 명령을 돌리고 결과를 화면에 보여 줍니다. 「installed 2 packages」 같은 문구와 함께 node_modules 폴더가 새로 생기면 설치가 끝난 것입니다.
4 – input.css 정리
Tailwind CLI에 넘길 입력 파일을 만듭니다. 이 파일은 두 부분으로 이뤄집니다.
- Tailwind 본체를 불러오는 한 줄:
@import "tailwindcss"; - 팀이 이미 쓰고 있던
@theme { ... }블록(색·폰트·간격 토큰 정의).
이미 쓰던 CSS 파일에 @theme 블록이 들어 있으니, 그 파일 맨 위에 @import "tailwindcss"; 한 줄만 얹으면 그대로 입력 파일이 됩니다.
AGY 프롬프트:
이 프로젝트의 CSS 파일을 Tailwind CLI 입력 파일로 정리해 주세요.
1) 현재 @theme 블록이 들어 있는 CSS 파일의 이름과 경로를 찾아 알려 주세요.
후보: {현재 쓰는 CSS 파일 경로 예: ./css/style.css}
2) 그 파일 맨 위에 아래 한 줄이 이미 있는지 확인하고, 없으면 추가합니다.
@import "tailwindcss";
3) 이 파일을 src/input.css 위치로 복사합니다. src 폴더가 없으면 만듭니다.
4) 복사한 src/input.css의 첫 5줄을 화면에 보여 주세요.변수 채우기:
{현재 쓰는 CSS 파일 경로}— 팀이 지금 HTML의<link>태그로 물고 있는 CSS 파일 경로. 예:./css/style.css,./assets/main.css.
원본 CSS 파일을 옮기지 않고 src로 복사하는 이유는, 정리하다 문제가 생겼을 때 원본을 곧바로 되돌릴 수 있게 하기 위함입니다. 최종 빌드가 확인되면 원본 CSS 파일은 그대로 두거나 지워도 됩니다.
5 – 정적 CSS 파일 만들기
준비된 src/input.css를 Tailwind CLI에 넣어 최종 CSS 파일을 만듭니다. 결과 파일은 dist/output.css에 저장하고, 배포용이므로 공백을 다 제거하는 --minify 옵션을 붙입니다.
AGY 프롬프트:
Tailwind CLI로 배포용 CSS 파일을 만들어 주세요.
1) dist 폴더가 없으면 만듭니다.
2) 아래 명령을 실행합니다.
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify
3) 실행이 끝나면 dist/output.css 파일의 크기(바이트)와 첫 3줄을 알려 주세요.
4) 파일이 만들어지지 않았거나 오류가 났으면 오류 메시지를 그대로 알려 주세요.정상으로 끝나면 Done in ...ms 같은 문구가 뜨고 dist/output.css 파일이 새로 생깁니다. 파일 크기는 팀 사이트에서 실제로 쓴 클래스 수에 따라 다르지만 보통 10KB에서 50KB 사이입니다.
Cannot find module 오류가 나면 3절의 설치가 안 끝난 것입니다. npm install tailwindcss @tailwindcss/cli를 다시 실행하도록 AGY에게 요청합니다. @theme block invalid 오류가 나면 4절의 @theme { ... } 문법 안에 오타가 있는 것이니 그 파일을 열어 확인합니다.
6 – HTML의 CSS 링크 정리
이제 HTML 파일이 새 정적 CSS 파일 하나만 불러오도록 정리합니다. 정리 대상은 두 가지입니다.
- Tailwind Play CDN을 부르는
<script>태그(있으면 지움). - 예전 CSS 파일을 부르는
<link>태그(새 경로로 바꿈).
AGY 프롬프트:
이 프로젝트의 모든 HTML 파일에서 Tailwind CSS 링크를 정리해 주세요.
1) 프로젝트 루트의 HTML 파일 목록을 찾아 알려 주세요.
대상 예: {팀 사이트 HTML 파일 목록 예: index.html, about.html, reports.html, contact.html}
2) 각 파일의 <head> 안에서 아래를 찾습니다.
- <script src="https://cdn.tailwindcss.com"></script>
- <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
- {현재 쓰는 CSS 파일 경로}를 물고 있는 <link> 태그
3) 위 <script> 태그가 있으면 지웁니다.
4) 예전 <link> 태그의 href 값을 ./dist/output.css 로 바꿉니다.
예전 <link>가 없으면 <head> 끝에 아래 한 줄을 새로 추가합니다.
<link href="./dist/output.css" rel="stylesheet">
5) 파일마다 몇 곳을 어떻게 바꿨는지 목록으로 알려 주세요.변수 채우기:
{팀 사이트 HTML 파일 목록}— 팀 사이트에 실제로 있는 HTML 파일 이름들. 폴더 안을 보고 그대로 옮겨 적습니다.{현재 쓰는 CSS 파일 경로}— 4절에서 확인한 원래 CSS 파일 경로.
서브 폴더 안에 있는 HTML 파일은 ../dist/output.css처럼 상대 경로가 달라집니다. 파일이 어느 폴더에 있는지 AGY에게 함께 알려 주면 경로를 알아서 맞춰 줍니다.
7 – 로컬 미리보기로 확인
배포에 반영하기 전에 자기 컴퓨터에서 화면이 예전과 똑같이 나오는지 눈으로 확인합니다.
AGY 프롬프트:
프로젝트 폴더에서 로컬 미리보기 서버를 켜 주세요.
1) 프로젝트 루트에서 다음 명령을 실행해 간단한 미리보기 서버를 시작합니다.
npx serve .
2) 화면에 나오는 http://localhost:3000 주소를 알려 주세요.
3) 서버는 계속 켜 두세요. 확인이 끝나면 제가 종료 요청을 드립니다.주소가 나오면 크롬에서 그 주소를 열고 페이지를 하나씩 눌러 봅니다. 확인할 것은 세 가지입니다.
- 화면이 최종 빌드 전과 똑같이 나오는가.
- 개발자 도구(F12)의 [Network] 탭에서
dist/output.css파일이 200 상태로 잘 불러와지는가. - 같은 [Network] 탭에서
cdn.tailwindcss.com이나@tailwindcss/browser요청이 더 이상 없는가.
화면이 스타일 없이 흑백 텍스트만 보이면 6절의 <link> 경로가 잘못된 것입니다. 페이지가 있는 폴더에서 ./dist/output.css가 실제로 어디를 가리키는지 확인합니다.
8 – 배포 반영
로컬에서 화면이 잘 나오면 바뀐 파일을 GitHub에 올려 GitHub Pages에 반영합니다.
AGY 프롬프트:
바뀐 파일을 GitHub에 올려 주세요.
1) 아래 파일들을 스테이징합니다.
- package.json, package-lock.json
- src/input.css
- dist/output.css
- 6단계에서 수정한 모든 HTML 파일
2) node_modules 폴더는 .gitignore 에 추가해 커밋에서 빼 주세요.
.gitignore 파일이 없으면 만들고 아래 한 줄을 넣습니다.
node_modules
3) 커밋 메시지 "final build: switch to compiled tailwind css"로 커밋합니다.
4) 원격 저장소에 푸시합니다.
5) 푸시가 끝나면 GitHub Actions 실행이 시작됐는지 알려 주세요.푸시가 끝나면 GitHub Pages가 새 파일을 몇 분 안에 반영합니다. 배포된 공개 URL을 크롬 시크릿 창(캐시가 남지 않는 창)에서 열어 6절 확인 세 가지를 다시 한 번 봅니다. 시크릿 창에서도 화면이 잘 나오면 최종 빌드가 완료된 것입니다.
9 – 자주 나는 문제
화면이 스타일 없이 나온다 — HTML의 <link> 경로가 실제 dist/output.css 위치와 다릅니다. 페이지가 있는 폴더 기준으로 상대 경로를 다시 확인합니다.
일부 클래스만 스타일이 안 먹는다 — Tailwind CLI가 그 클래스를 못 찾은 것입니다. HTML에서 class="..." 값을 JavaScript로 만들어 붙이면 CLI가 훑을 때 놓칩니다. 그런 자리는 class 문자열을 통째로 코드 안에 적어 두거나 src/input.css에 @source "../*.html";처럼 대상 폴더를 지정합니다.
dist/output.css 파일이 너무 크다(100KB 초과) — --minify 옵션을 빠뜨렸을 수 있습니다. 5절 명령을 그대로 다시 실행합니다.
수정한 뒤에 매번 정적 CSS를 다시 만드는 것이 번거로우면 개발 중에는 --watch 옵션(--minify 대신)을 쓰면 파일이 바뀔 때마다 자동으로 다시 컴파일됩니다. 다만 최종 배포 전에는 반드시 --minify로 한 번 더 만들어 올립니다.
10 – 출처와 최신성 주의
도구의 명령·옵션은 자주 바뀝니다. 아래 내용은 2026-09-06에 공식 문서에서 확인한 것이며, 명령이 안 되면 문서를 다시 봅니다.
Get started with Tailwind CSS — Tailwind CLI Installation —npm install tailwindcss @tailwindcss/cli, 입력 파일에 @import "tailwindcss";, 빌드 명령 npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch, 배포용 --minify 옵션, @theme 블록으로 토큰 정의.