납품용 화면 사양서를 Claude Code에 맡겼을 때, Excel 대신 HTML로 출력하는 것이 최적이었다는 경험 기록

납품용 화면 사양서 작성을 Claude Code에 의뢰했을 때, 처음에는 Excel 출력을 시도했지만 결국 HTML로 생성하여 PDF화하는 방식이 가장 적절했다는 실전 경험 기록입니다.

지금까지 화면 사양서 작성 경험이 없었던 제가, 납품 전에 60개가 넘는 화면의 사양서 작성을 처리하기 위해 Claude Code를 병렬 에이전트로 가동시켜 만든 프로세스와 노하우를 정리했습니다.

• 60개 이상의 화면 사양서를 만들 때 Excel(.xlsx) 출력을 시도함 - 하지만 Claude는 Excel의 모양을 확인할 수 없기 때문에, Excel 출력에서는 심각한 레이아웃 깨짐이 발생함
• 대책으로 AI가 잘하는 'HTML 생성 → PDF화'로 접근 방식을 전환함
• 5대의 Claude Code에 역할(텍스트 작성・이미지 촬영・결합・PDF 변환・교정)을 분담시켜 병렬로 작업을 진행함
• 첫 번째 화면에서 틀을 잡고 대량 생산함으로써, 효율적으로 화면 사양서를 만들 수 있음! (다만 병렬 가동으로 인한 토큰 상한에는 주의가 필요합니다)

프로젝트는 웹 브라우저에서 구동하는 게임 앱이었으며, 화면 수가 많아 최종적으로 64개의 화면이 있었습니다.

약 반년 동안 개발을 진행했지만, 처음부터 명확한 화면 사양서를 가지고 진행한 것은 아니었습니다. 개발 기간 중 여러 차례 사양 변경이 있었고, 저희 회사에서 기획 제안을 하고 상대방에게 검토를 받는 형태로 진행되었기 때문입니다. 요구사항 정의 단계에서 화면 수가 명확하게 정해져 있지 않았고, 납품 시점에 화면 사양서를 작성하게 되었습니다.

회사 계약의 Claude Code($20/월 플랜)을 사용했습니다.

납품 형식은 최종적으로 PDF로 제출하면 문제가 없었지만, 나중에 내용을 업데이트할 수 있도록 xlsx와 같은 편집 데이터도 준비해 둘 필요가 있었습니다. 포맷 자체는 특별한 것이 아니라, 과거 프로젝트의 구성을 모방하는 형태였습니다.

처음에는 과거 프로젝트처럼 Excel로 화면 사양서를 만들려고 했습니다.

프로젝트의 git 관리 외에 myself라는 저 전용 디렉토리를 만들고, 그곳에 과거 프로젝트의 샘플 사양서(PDF 형식과 xlsx 형식)를 배치했습니다.

그 후 Claude에게

이 라인 전체를 저와 X 자문위원의 시선으로 지켜보며, 지시 및 조정을 진행했습니다.

화면은 순차 번호를 매겨 관리했습니다.

• A 텍스트가 조사하여 전체 화면 수가 약 60개(최종적으로 64개)임을 파악했기 때문에, A 텍스트가 화면 설명 문서를 Markdown 파일로 작성해 나갔습니다.
• 작성된 문서는 표기 오류나 부자연스러운 표현이 없는지 X 자문위원에게 교열을 맡겼습니다.
• 병행하여 B 이미지가 Playwright를 사용해 스크린샷을 촬영했습니다.
• 소재가 갖춰진 화면부터 순서대로 C HTML이 텍스트와 이미지를 통합하여 HTML을 작성했습니다.
• HTML 작성이 완료되는 대로 D PDF가 자율적으로 라이브러리를 구동하여 PDF로 변환했습니다.

먼저 화면 사양서의 첫 페이지를 확실하게 만드는 데 집중했습니다.

C HTML에게 한 번에 만들게 하지 않고, 첫 번째 화면(01 화면)만 선행해서 작성하게 했습니다. 1화면에서 HTML 구조와 CSS 시각적 요소를 탄탄하게 잡은 후, 다른 화면으로 전개시켰습니다.

화면별로 개별적인 HTML 파일을 생성하면서도, 최종적으로는 이들을 하나의 거대한 HTML 파일에 모아 한 권의 PDF로 변환했습니다.

이미지는 HTML과는 별도의 폴더에 저장하고, HTML 내부에서는 <img> 태그의 상대 경로로 참조하는 구성으로 했습니다. 이를 통해 나중에 화면의 모습이나 사양이 변경되더라도, 같은 파일명으로 이미지를 교체하는 것만으로도 업데이트할 수 있는 설계가 되었습니다.

플로우 다이어그램(flowchart) 설명에는 Mermaid.js를 사용했습니다.

'Mermaid.js를 사용해서 플로우 다이어그램을 그려줘'라고 AI에게 지시하기만 하면 됩니다.

AI와 플로우 다이어그램 스타일 조정 등도 진행했습니다.

작성된 HTML의 경우, 코드는 외부 JS 파일이나 CSS 파일로 분리하지 않고 HTML 내부의 <script> 태그 및 <style> 태그에 직접 내장했습니다.

HTML 파일 + IMG 디렉토리라는 단순한 형태로 제출하고 싶었기 때문입니다.

문서 수정 정도라면 비엔지니어(non-engineer)도 HTML을 직접 편집하여 대응할 수 있고, CSS 수정도 필요 없는 상태입니다.

PDF로 출력했을 때 페이지 나누는 위치가 이상했던 부분에 대해서는 '중간에 애매한 요소 내에서 페이지를 나누지 않도록', '1화면 단위로 확실하게 페이지를 나누도록'과 같이 자연어로 Claude Code에게 지시하여 조정하게 했습니다.

구체적인 라이브러리나 기술의 지정은 하지 않고, AI에게 맡겼습니다.

AI가 자율적으로 라이브러리 등을 조사해 주었습니다.

도중에 스마트폰 화면 폭과 PC 화면 폭의 표시가 섞였을 때도, '이 화면군(메인 화면 등)에서는 스마트폰 화면 폭으로, 이 화면군(관리 화면 등)에서는 PC 화면 폭으로 부탁드립니다'라고 전달함으로써 의도한 대로의 표시를 대응시킬 수 있었습니다.

사람 측에서 별도의 내보내기 도구를 준비할 필요 없이, Claude가 스스로 툴을 가동하여 납품할 수 있는 상태까지 완성했습니다(최종적인 육안 검토는 사람이 진행했습니다).

결과적으로 며칠이 걸렸지만, 그대로 납품 가능한 수준의 화면 사양서가 완성되었습니다.

Excel로는 재현할 수 없었던 스타일 조정도 세부적인 부분까지 할 수 있었으며, 샘플로 제공된 과거 프로젝트 PDF에 준하는 모양을 재현하면서도 더욱 보기 좋게 개선된 결과물이 되었습니다.

64개 화면 분량의 스크린샷 촬영도 문제없이 성공했습니다.

화면 사양서 작성 경험이 없었지만, 60개가 넘는 문서 작성을 며칠 만에 완료할 수 있었던 것은 분명 Claude 덕분이었습니다.

AI의 특성에 맞춰 Excel을 포기하고 텍스트 기반의 HTML로 전환하는 판단을 내릴 수 있었던 점과, 5개의 Claude Code를 병렬로 구동하여 완전 분업화시킨 선택은 이번에 특히 큰 성과가 있었습니다.

반면, 작업 중에 여러 번 토큰 상한선(Limit)에 도달해서 작업이 멈춘 것은 상당히 힘들게 느껴졌습니다. AI를 사용할 수 없는 동안에는 현재 나온 결과물을 점검하거나 작전 재검토를 하고 있었습니다. 화면을 다루는 무거운 처리였고, 전체 64개 화면을 일괄로 불러오는 광범위한 작업이었으며, 게다가 5대의 에이전트가 동시에 토큰을 소모했기 때문에 고갈이 빨랐다고 느낍니다.

이번에는 시행착오를 거쳐 틀을 만드는 데 시간이 걸렸지만, 노하우가 쌓인 이후부터는 시도와 오류의 과정을 생략할 수 있기 때문에 다음번부터는 더욱 효율적으로 실행할 수 있을 것이라고 생각합니다.