말과 코드 사이가 비어 있습니다
"휴가 결재 화면 하나 만들어줘"라고 하면, 말한 사람과 만든 사람이 서로 다른 화면을 떠올립니다. 그렇다고 바로 제품 코드로 만들면, 아니라는 걸 알았을 때 되돌리는 값이 이미 비쌉니다.
그 사이에 한 칸을 두는 방법이 HTML 한 장입니다. 파일 하나 안에 CSS와 JS까지 다 들어 있어서 더블클릭하면 브라우저에서 열립니다. 설치도 빌드도 서버도 없습니다. 그래서 만드는 데 몇 분, 고치는 데 한 마디, 버리는 데 0원입니다.
| 말로 설명 | HTML 한 장 | 제품 코드 | |
|---|---|---|---|
| 만드는 시간 | 0분 | 몇 분 | 며칠 |
| 확인 방법 | 서로의 상상 | 브라우저에서 직접 | 브라우저에서 직접 |
| 고치기 | 말이 점점 길어짐 | "이 버튼 위로" 한 마디 | 컴포넌트 · 상태 · 테스트가 딸려옴 |
| 버리는 부담 | 없음 | 없음 | 아까워서 못 버림 |
effective-html은 이 "한 장"을 어떻게 만들지 정해 둔 스킬 모음입니다. 여섯 개 전부 아래 규칙을 지킨 파일 하나를 내놓습니다.
| 규칙 | 뜻 |
|---|---|
| 파일 하나 | CSS · JS를 인라인으로. 딸려 나오는 첨부 파일이 없습니다 |
| 빌드 없음 | npm install 없이 더블클릭으로 열립니다 |
| 네트워크 없음 | 허락하지 않으면 외부 CDN · 웹폰트 · API를 쓰지 않습니다 |
| 진짜 내용 | lorem ipsum 금지. 실제 항목 이름과 숫자를 씁니다 |
| 반응형 · 접근성 | 좁은 화면에서도 읽히고, 키보드로 조작되고, 가로 스크롤이 새지 않습니다 |
무엇을 물어보는 중이냐로 고릅니다
여섯 개지만 외울 필요는 없습니다. /html 하나만 부르면 요청을 읽고 알맞은 쪽으로 넘겨줍니다. 어느 단계인지 이미 알고 있다면 그 스킬을 바로 부르는 게 빠릅니다.
| 스킬 | 언제 쓰나 |
|---|---|
| /html | 넓은 요청 전부 — 보고서 · 설명 자료 · 발표 · 랜딩 페이지 · 작은 도구. 알맞은 전문 스킬로 넘겨주는 역할도 겸합니다 |
| /design-artifact | 색 · 서체 · 구도를 정해야 할 때. 이 모음의 미술감독 자리입니다 |
| /html-wireframe | 무엇이 화면에 있어야 하는지가 아직 안 정해졌을 때 |
| /html-prototype | 눌러 봐야 판단이 되는 때. 안 눌리는 목업도 여기 들어 있습니다 |
| /html-plan | 계획 · 로드맵 · 작업 순서를 보이게 정리할 때 |
| /html-diagram | 구조 · 순서 · 상태 · 계통을 그림으로 설명할 때 |
헷갈리는 건 사실 세 개뿐입니다. 같은 화면을 다른 깊이로 그리기 때문입니다.
| 와이어프레임 | 목업 | 프로토타입 | |
|---|---|---|---|
| 답하는 질문 | 무엇이 화면에 있어야 하나 | 어떻게 보여야 하나 | 어떻게 동작해야 하나 |
| 정해 두는 것 | 내용 · 묶음 · 순서 · 이동 | + 색 · 서체 · 간격 | + 상태 · 입력 · 오류 · 복구 |
| 열어 두는 것 | 보이는 것 전부 | 실제 동작 | 진짜 저장 · 인증 |
| 일부러 이렇게 | 안 예쁘게 | 안 눌리게 | 한 흐름만 |
/design-artifact만 성격이 다릅니다. 화면을 만드는 스킬이 아니라, 어떤 톤으로 만들지를 정하는 스킬입니다. 정해진 회사 스타일을 씌우는 게 아니라 매번 주제에 맞는 톤을 새로 고르게 합니다. 그래서 저장소에 이미 DESIGN.md나 디자인 토큰이 있으면 그쪽이 먼저입니다.
세 가지 경로, 하나만 고르면 됩니다
Claude Code만 쓴다면 ①이나 ②, Codex도 같이 쓴다면 ①이 편합니다.
# ① 스킬만 설치 — Claude Code · Codex · Cursor 등 공용 (터미널) npx skills add plannotator/effective-html # 목록만 보기 / 하나만 골라 설치 npx skills add plannotator/effective-html --list npx skills add plannotator/effective-html --skill html-wireframe # ② Claude Code 플러그인 (Claude Code 안에서) /plugin marketplace add plannotator/effective-html /plugin install plannotator-effective-html@effective-html # ③ Codex 플러그인 (터미널) codex plugin marketplace add plannotator/effective-html codex plugin add plannotator-effective-html@effective-html
①로 설치하면 지금 폴더 안에 이렇게 들어갑니다. 실제 파일은 한 벌이고, 도구별 폴더는 그것을 가리키는 링크입니다.
.agents/skills/html/SKILL.md ← 실제 파일 (6개) .claude/skills/html → 위를 가리키는 링크 skills-lock.json ← 어느 버전을 받았는지 기록
| 경로 | 설치 위치 | 부르는 법 |
|---|---|---|
| npx skills add | 프로젝트 폴더 .agents/skills/ | /html-wireframe |
| Claude Code 플러그인 | Claude Code 플러그인 폴더 | 이름 앞에 플러그인 이름이 붙습니다 |
플러그인으로 설치하면 스킬 이름 앞에 플러그인 이름이 붙어 /plannotator-effective-html:html-wireframe 형태가 됩니다. 설치한 뒤 /를 눌러 목록에서 실제 이름을 확인하세요. ①로 설치했다면 그냥 /html-wireframe입니다.
브리프 한 장에서 프로토타입까지
순서가 중요합니다. 브리프 없이 와이어프레임부터 시키면 화면은 나오는데 무엇을 판단해야 할지가 없습니다.
브리프를 적는다
네 항목이면 충분합니다 — 사용자와 할 일 · 필요한 정보 · 필요한 동작 · 하지 않을 것. 마지막 항목이 결과를 제일 많이 바꿉니다.
와이어프레임 3방향
한 파일 안에 배치가 실제로 다른 세 개를 받아 나란히 비교합니다. 색만 다른 건 다른 방향이 아닙니다.
하나를 고른다
고르고 나머지는 버립니다. 여기서 안 고르면 다음 단계가 세 배로 늘어납니다.
프로토타입 — 흐름 하나
화면을 다 만들지 않습니다. 판단이 필요한 흐름 하나와 그 흐름이 실제로 닿는 상태들만 만듭니다.
브리프는 파일로 저장해 두면 다음 단계에서 계속 참조합니다. brief.md로 저장하세요.
# 브리프 — 휴가 결재 화면 ## 사용자와 할 일 팀장이 대기 중인 휴가 신청을 보고 승인하거나 반려한다. ## 필요한 정보 - 신청자 · 기간 · 일수 · 남은 연차 - 같은 기간에 자리를 비우는 팀원 - 신청 사유와 첨부 - 지금 상태(대기 · 승인 · 반려) ## 필요한 동작 반려하려면 사유를 반드시 적어야 한다. 사유가 비어 있으면 반려 버튼이 눌리지 않는다. ## 하지 않을 것 - 로그인, 실제 저장, 메일 발송 - 인사 시스템 연동
다음은 와이어프레임입니다. 색 얘기를 아직 꺼내지 않는 것이 요령입니다.
/html-wireframe brief.md를 읽고 와이어프레임을 만들어줘. 배치가 실제로 다른 방향 3개를 한 파일에 넣고, 위에서 골라 볼 수 있게 해줘. - 방향마다 이름과 "무엇을 포기하는지" 한 줄 - 색과 서체는 아직 정하지 말 것 - 좁은 화면에서 어떻게 접히는지도 보이게
하나를 고른 다음 프로토타입으로 넘어갑니다. 이때 상태를 먼저 나열해 주면 결과가 크게 좋아집니다.
/html-prototype 두 번째 방향으로 프로토타입을 만들어줘. 흐름은 "대기 건을 연다 → 반려 사유를 적는다 → 반려한다" 하나만. 상태는 이만큼: - 불러오는 중 / 대기 건이 하나도 없을 때 - 사유가 비어 반려 버튼이 안 눌리는 상태 (이유가 보이게) - 반려 완료 / 실패했을 때 다시 시도 저장은 하지 말고, 진짜 시스템이 이어받는 지점은 화면에 적어줘. 키보드로만도 끝까지 되게 해줘.
| 상태 | 언제 넣나 |
|---|---|
| 불러오는 중 | 시간이 걸리는 동작이 있을 때 |
| 비어 있음 | 목록이 있는 화면이면 거의 항상 |
| 오류 · 다시 시도 | 실패할 수 있는 동작이 있을 때 |
| 완료 | 끝났다는 표시가 필요할 때 |
| 비활성 | 버튼이 왜 안 눌리는지 보여야 할 때 |
| 좁은 화면 | 항상 |
git clone https://github.com/plannotator/effective-html cp effective-html/examples/release-readiness/wireframe.html my-flow.html
바꾸는 순서는 브리프 → 라벨 → 데이터 → 상태이고, 색은 맨 마지막입니다. 색부터 손대면 구조가 안 보입니다.
프로토타입은 제품이 아닙니다
이걸 흐리면 사고가 납니다. 눌러 보고 "다 됐네"라고 판단하는 사람이 반드시 생기기 때문입니다.
| 합니다 | 하지 않습니다 |
|---|---|
| 화면과 흐름 하나 | 로그인 · 권한 |
| 눌리는 버튼과 상태 변화 | 실제 저장 · 전송 |
| 좁은 화면 · 키보드 조작 | 라이브 데이터 연결 |
| 오류와 복구 표시 | 실제 배포 |
그래서 안 되는 버튼을 그냥 두면 안 됩니다. 지우거나, "여기서부터는 실제 시스템이 이어받습니다"라고 화면에 적습니다. 눌렀는데 아무 일도 안 일어나는 버튼이 제일 나쁩니다.
| 이건 고장이 아닙니다 | 이유 |
|---|---|
| 와이어프레임이 안 예쁘다 | 회색만 쓰는 건 사람들이 색 얘기 대신 구조 얘기를 하게 만들려는 것입니다 |
| 화면이 하나뿐이다 | 흐름 하나를 제대로 만드는 게 화면 열 개를 겉만 만드는 것보다 판단에 쓸모 있습니다 |
| 매번 톤이 다르다 | 같은 스타일을 재사용하지 않는 것이 설계 의도입니다. 고정하고 싶으면 DESIGN.md를 두세요 |
- 와이어프레임 · 목업 · 프로토타입이 각각 무엇을 답하는지 구분할 수 있다
- 스킬을 설치했다 (npx skills add 또는 플러그인)
- 브리프 4항목을 적었다 — 하지 않을 것까지
- /html-wireframe으로 방향 3개를 받아 하나를 골랐다
- /html-prototype으로 상태까지 있는 화면을 만들고 브라우저에서 직접 확인했다