서론

웹 제작(Astro를 이용한 클라이언트 사이트 제작)을 본업으로 하고 있어, 한정된 시간 내에 여러 프로젝트를 처리해야 했습니다.

그래서 Claude Code를 사용하여 제작 프로세스 전체를 13개의 슬래시 명령어(Slash Command)로 시스템화했습니다. 약 1년 동안 개선을 지속해 온 끝에 드디어 안정화되었기에, 설계 방식에 대한 모든 생각을 적어보려 합니다.

"AI에게 통째로 맡겼더니 속도가 엄청 빨라졌다"와 같은 이야기가 아닙니다. 오히려 통째로 맡기면 느려진다는 것이 결론 중 하나입니다.

이 글에서 다룰 내용:

• 명령어의 입도(Granularity)를 어떻게 결정했는가
• CLAUDE.md에 무엇을 적어야 효과적인가 (실측 결과)
• 가이드라인을 외부 파일로 분리하는 이유
• 실제 13개 명령어의 구성
• 잘 되지 않았던 점

동일하게 제작 프로세스를 시스템화하고 싶은 분이 이 글만 보고도 자신만의 버전을 만들 수 있는 것을 목표로 작성합니다.

전제: 무엇을 자동화하고 싶었는가

자동화하고 싶었던 것은 "디자인을 생각하는 것"이 아닙니다. 판단이 필요 없는데도 매번 발생하는 작업입니다.

제작의 모든 공정을 나열하고, "매번 똑같은 일을 하는 작업"에 표시를 해보니 상상 이상으로 많았습니다.

• 프로젝트 폴더를 만들고 구조를 정리하기
• Figma 와이어프레임으로부터 원고 작성하기
• 공통 파트(헤더, 푸터, CTA)의 더미 정보 교체하기
• 공개 전 링크 끊김, meta, 전화번호 링크 체크하기
• 모바일에서의 레이아웃 깨짐 확인하기

이 부분은 **생각할 가치가 제로(0)**인 영역입니다. 이곳을 줄이는 것을 목표로 삼았습니다.

설계 방식

1. 명령어의 입도는 "1개 명령어 = 1개의 완료 상태"

가장 고민했던 것이 입도입니다.

• 너무 세밀함 → 사용할 때 어떤 것을 호출할지 망설여짐
• 너무 거침 → 도중에 분기되어 파탄 남

최종적으로 정착한 기준은 **"끝을 정의할 수 있는 단위로 자른다"**였습니다.

❌ /setup … "셋업"은 끝이 모호함
✅ /new-project … "프로젝트 폴더가 생성되고 CLAUDE.md가 채워짐"으로 완료

각 명령어에 "Done 조건"을 한 줄로 쓸 수 있는지 여부를 판정 기준으로 삼고 있습니다. 쓸 수 없다면 입도가 잘못된 것입니다.

2. 프로젝트마다 CLAUDE.md (프로젝트 고유 메모리)를 둔다

CLAUDE.md에는 "금지 사항"을 적습니다.

여기서 효과가 컸던 것은, 디자인 취향을 적는 것보다 금지 사항을 적는 것이었습니다.

## 절대 금지
- CSS에 값을 직접 입력하지 말 것 (반드시 변수 사용)
- HTML에 style 속성을 쓰지 말 것
...

"이런 분위기로"라는 지시는 해석의 폭이 넓어, 긴 작업의 후반부에는 반드시 무너집니다. 반면 "이것을 하지 마라"는 판정이 기계적이기 때문에 무너지지 않습니다.

해도 되는 것보다, 해서는 안 되는 것을 적는다. 이것이 가장 효과적이었습니다.

3. 가이드라인은 프롬프트가 아니라 외부 파일에 둔다

처음에는 프롬프트에 규약을 전부 적었지만, 작업이 길어지면 후반부에 지켜지지 않게 됩니다.

해결책은 작성 방식이 아니라 위치였습니다.

guidelines/
├── design_rules.md … 디자인 규약
├── ai_design_quality_checklist.md … 품질 체크리스트
...

그리고 각 명령어의 절차서에 "작업 전에 반드시 design_rules.md를 읽을 것"이라고 적어둡니다.

프롬프트는 짧게, 규약은 외부에. 이렇게 함으로써 컨텍스트(Context)가 길어져도 무너지지 않게 되었습니다.

4. 폴더 구조는 "인간이 찾기 쉬운" 것보다 "AI가 헤매지 않는" 것

폴더 구조를 다시 만들었습니다.

<프로젝트 폴더>/
├── 01_wireframe/ … Markdown 원고
├── 02_design/ … 디자인 컴프(Design Comp)
...

인간은 감으로 찾을 수 있지만, AI는 찾지 못합니다. 번호를 매겨 역할을 이름으로 나타내고, 계층을 얕게 만듭니다.

구조를 정리하는 것이 사실 가장 효과적인 프롬프트 개선이었습니다.

실제 명령어 구성

단계 순으로 13개입니다.

Phase 0: 프로젝트 시작

템플릿 폴더(Astro의 scaffold 포함)를 복제하여 이름을 바꾸는 방식을 채택했습니다. 매번 30~60분 걸리던 시작 작업이 5분으로 단축되었습니다.

Phase 1: 원고 정리

Figma MCP를 통해 각 섹션의 이미지와 텍스트를 추출하여, h1 / h2 / p / ul / cta 수준으로 구조화하여 저장합니다.

이 단계가 후속 공정의 사고율을 결정합니다. "여기에 제목"이라고만 적힌 원고를 전달하면 해석의 폭이 너무 넓어져 매번 결과가 어긋나기 때문에, 원고 포맷을 고정하는 것이 중요했습니다.

Phase 2: 구현

더미 정보(샘플 주식회사 / 000-000-0000 등)가 남아 있지 않은지 체크하는 것도 절차에 포함되어 있습니다. 사소해 보이지만, 이를 잊으면 실제 운영 단계에서 사고가 발생합니다.

Phase 3: 디자인 마무리

명령어를 세 가지로 나눈 이유는 시작 상황이 다르면 최적의 절차도 다르기 때문입니다. 처음부터 만드는 것인지, 기존 것을 다듬는 것인지, 일부만 수정하는 것인지에 따라 달라집니다.

Phase 3.5: 품질 체크

/rwd-check는 Playwright 테스트(e2e/responsive.spec.ts)를 통해 다음 사항을 기계적으로 검출합니다.

• 가로 스크롤이 발생하지 않는지
• 햄버거 메뉴가 올바른 브레이크포인트(Breakpoint)에서 전환되는지
• 메뉴 내부 레이아웃이 깨지지 않았는지

사람의 눈은 반드시 놓치는 부분이 생기지만, 테스트는 매번 같은 장소를 같은 정밀도로 확인합니다.

유틸리티

CSS 구성

프로젝트 간 재사용을 위해, CSS는 편집할 수 있는 곳을 단 한 곳으로 제한했습니다.

public/css/
├── style.css … 엔트리(Entry, @import만 수행) 
├── _global.css … 구조 · 공통 모듈 (변경 금지)
...

**"변경할 수 있는 곳은 _theme.css뿐이다"**라는 규칙을 세움으로써, 프로젝트가 바뀌어도 토대(Foundation)가 무너지지 않게 되었습니다.

AI에게도 "_global.css는 절대로 건드리지 마라"라고 명시할 수 있어 사고가 급격히 줄어들었습니다.

효과

...
다만 뒤에서 설명하겠지만, "버튼 하나로 완벽한 사이트가 나오는 것"은 아닙니다.

잘 되지 않았던 점

솔직하게 적겠습니다.

시스템화가 너무 빨랐다

두 번째 프로젝트에서 템플릿화를 시작했더니, 세 번째 프로젝트에서는 전부 다시 만들어야 했습니다. 샘플이 너무 적어서, "우연히 두 프로젝트에 공통적이었을 뿐인 것"을 공통화했기 때문입니다.

지금 생각하기에 적정 라인은 5개 정도입니다. 그전까지는 직접 손을 움직이며 관찰에 집중하는 것이 더 빠릅니다.

통째로 맡기면 오히려 느려진다

Claude Code에 모든 것을 맡겨서 시간이 더 걸렸던 패턴:

• 원고가 확정되지 않았는데 구현을 시키는 경우
• "적당히 알아서 해줘"라고 모호하게 던지는 경우
• 출력을 확인하지 않고 다음 지시를 겹쳐서 내리는 경우

공통점은 인간 측의 결정이 끝나지 않았다는 것이었습니다. AI는 판단을 대행할 수는 있어도, 결정을 대행할 수는 없습니다.

이터레이션(Iteration)은 반드시 포함된다

TOP을 한 번 생성하고 끝나는 것이 아닙니다. 실제로는

생성 → 확인 → "여기가 달라요"라고 지시 → 재생성

이 2~3회 포함됩니다. 다만 지시는 비디자이너 수준이어도 괜찮으며, "조금 더 차분한 느낌으로" 정도의 소박한 언어로도 통합니다.

줄일 수 있는 것은 수십 시간의 수작업이지, 대화 시간은 오히려 필요합니다.

요약

시스템화하며 깨달은 가장 큰 사실은, 줄어든 것은 작업 시간이 아니라 "판단 횟수"였다는 것입니다.

매번 "이 섹션을 어떻게 구성할까"를 고민하던 것을 하나의 패턴으로 고정하는 순간, 체감 속도가 달라졌습니다.

그리고 목적도 도중에 바뀌었습니다. 처음에는 "빨리 끝내고 싶다"였지만, 지금은 **"매번 동일한 품질을 내고 싶다"**가 되었습니다. 속도는 결과일 뿐이며, 진정으로 원했던 것은 일관성이었습니다.

시스템화는 그것을 위한 도구입니다.

이 기사의 내용을 실제로 작동하는 형태로 정리한 것을 Skill Pack으로서 공개하고 있습니다. 명령어 13개, 워크플로우(Workflow) 13개, 가이드라인 6개, Astro의 템플릿 일체가 포함되어 있습니다.

직접 구축하는 경우에 참고가 된다면 기쁘겠고, 시간을 사고 싶은 분들은 이용해 주세요.

질문이 있다면 댓글이나 X (@nyaco_ai)로 편하게 문의해 주세요.

Discussion