AI와 함께 일하면서 HTML 문서가 많이 생기기 시작했어요.
복잡한 마이그레이션 작업의 흐름, 인프라 구조, 정책 변경 전후의 As-is / To-be처럼 텍스트만으로 설명하기 피곤한 내용은 HTML로 시각화하면 훨씬 빠르게 맥락을 맞출 수 있었어요. 공유를 위한 문서이기도 했지만, 만드는 사람 스스로 복잡한 구조를 이해하는 데도 도움이 됐어요.
다만 이런 문서는 HTML 파일 하나로 끝나지 않는 경우가 많았어요. 이미지, CSS, SVG 같은 정적 자원이 함께 생겼고, HTML은 그 파일들을 상대 경로로 참조했어요.
문제를 느낀 곳은 문서를 만드는 단계가 아니었어요. 만들어진 HTML을 다른 사람이 열어 보고, 나중에 다시 찾는 단계였어요.
개발팀에서 먼저 만난 문제
여러 저장소와 워크트리를 오가며 작업하다 보면, 만들어 둔 HTML 문서가 어디에 있는지 찾기 어려운 일이 있었어요. 작업하던 저장소의 stash에 묻히기도 했고, Slack으로 파일을 보내면 보는 사람은 매번 내려받아야 했어요.
HTML 파일만 전달해서는 충분하지 않았어요. 옆에 있던 이미지나 스타일 파일까지 함께 전달하지 않으면 문서가 의도한 모습으로 열리지 않았어요.
그래서 개발팀이 사용할 내부 문서 저장소를 만들었어요. HTML을 저장소에 넣고 push하면 CI가 S3 정적 호스팅에 자동으로 배포하고, 이후에는 파일 대신 링크를 공유하는 흐름이에요.
문서 목록도 README에서 자동으로 관리했어요. 문서를 처음 추가한 시점과 마지막으로 수정한 시점을 남겼어요. 모든 문서를 완벽하게 최신 상태로 유지할 수는 없겠지만, 나중에 정리할 때 "이 문서가 아직 살아 있는가"를 판단할 힌트는 필요하다고 생각했어요.
이 흐름은 개발자에게 잘 맞았어요.
- HTML과 필요한 정적 자원을 폴더 구조 그대로 함께 배포해 이미지가 깨지지 않았어요.
- 파일을 내려받지 않아도 링크 하나로 문서를 열 수 있었어요.
- 문서가 개인 로컬 환경이나 stash에만 남는 일을 줄였어요.
- 문서는 사무실 네트워크 안에서만 열리도록 제한했어요.
HTML의 모양을 일정하게 만들기 위해, Claude 세션의 맥락과 결정 내용을 바탕으로 문서를 만드는 htmlize 스킬도 만들었어요. 물론 모든 문서가 같은 형식에 잘 어울리지는 않았어요. 문서 성격과 맞지 않는 표현이 나오기도 했고, 디자인 취향도 달랐어요.
그래도 이때의 목표는 "모든 문서를 아름답게 통일하기"가 아니었어요. 만든 문서를 팀이 바로 열고, 다시 찾을 수 있게 만드는 것이었어요.
개발팀에서는 이 흐름이 꽤 잘 작동했어요.
그런데 Slack에서 HTML 파일 하나를 받았다
그러던 어느 날, 기획자분에게 정책 변경 문서를 Slack으로 받았어요.
구조와 흐름은 잘 정리된 HTML 문서였어요. 하지만 파일을 다운로드해 열어 보니 이미지 일부가 깨져 있었어요. HTML은 남아 있었지만, 문서가 참조하던 다른 파일까지 함께 전달되지는 않았던 것 같아요. 파일은 다운로드 폴더에 남았고, 다른 사람에게 다시 전달하려면 또 파일을 보내야 했어요.
그때 처음 든 생각은 단순했어요.
이 문제는 이미 개발팀에서 해결했는데.
기획과 운영 업무에서도 정책 변경의 구조나 업무 흐름을 설명하기 위해 HTML을 사용하고 있었어요. 직접 옆자리에서 열어 보면 잘 보이는 문서였지만, 파일로 전달되는 순간 다운로드가 필요했고 이미지가 깨질 수 있었어요.
그래서 처음에는 기존 Git 파이프라인에 연결하면 끝날 일이라고 생각했어요. 문서를 저장소에 올리고 push하면 링크가 생기니, 기술적으로는 이미 답이 있었어요.
하지만 이건 제가 익숙한 방식이었지, 문서를 공유하는 분들에게 익숙한 방식은 아니었어요.
Git을 도입하는 데 드는 시간
Git 계정이 없는 분도 있었고, Git 사용 경험이 없는 분도 있었어요. 계정을 만들고 기본 개념을 설명하고, 문서를 올리고 push하는 흐름을 실제 업무에 익숙하게 만드는 데에는 적어도 이틀 정도의 시간이 필요해 보였어요.
이틀을 들여 한 번 익히면 이후가 편해질 수도 있어요. 하지만 문서 공유가 주된 업무가 아닌 사람에게 Git은 쉽게 잊히는 절차가 될 수 있고, 실수에 대한 부담도 남아요.
여기서 중요한 것은 누군가가 Git을 사용하지 못한다는 사실이 아니었어요.
문서 하나를 빠르게 공유하려는 사람에게 Git은, 얻는 가치보다 먼저 지불해야 할 비용이 큰 도구였어요.
개발자에게 자연스러운 흐름이 모든 직군에게 자연스러운 흐름은 아니었어요.
무엇을 만들지보다, 어디에서 멈추는지 물었다
바로 새 도구를 만들지는 않았어요. 먼저 실제로 HTML을 만드는 분들에게 몇 가지를 물어봤어요.
- HTML 문서를 얼마나 자주 만드는지
- 만든 문서를 누구에게 공유하는지
- 파일을 공유한 뒤 어느 순간이 가장 불편한지
- 기존 방식에서 꼭 유지되어야 하는 것은 무엇인지
문서는 생각보다 자주 만들어지고 있었고, 다른 팀과 공유하는 경우도 많았어요. 직접 만나서 보여줄 때는 문제가 없었어요. 불편함은 파일로 전달되는 순간에 생겼어요.
다운로드해야 하고, 다운로드 폴더에 파일이 쌓이고, 이미지가 깨질 수 있고, 다시 공유하려면 또 파일을 보내야 했어요.
그래서 문제를 다시 이렇게 정의했어요.
기술적으로 멋지게 HTML을 관리하는 것이 아닌, 모두가 익숙한 폴더 구조로 작업 흐름 변경 없이, HTML을 링크로 공유하게 만들자.
퇴근길에 만든 작은 업로더
처음부터 큰 도구를 만들 생각은 없었어요.
퇴근길에 Claude와 대화하다가 "그냥 폴더를 올리고 링크를 복사하면 되지 않을까?"라는 생각으로 동작하는 프로토타입을 만들었어요.
왼쪽에는 업로드된 문서의 폴더 구조를 보여주고, 가운데에는 HTML 파일과 필요한 정적 자원을 폴더째 드래그 앤 드롭으로 올릴 수 있게 했어요. 업로드가 끝나면 해당 문서를 바로 열거나, 링크를 복사할 수 있게 했어요.
예를 들어 아래처럼 만들어진 결과물은 index.html만 올리는 것이 아니라 migration-plan 폴더 전체를 올려요.
migration-plan/
├── index.html
├── images/
│ ├── before.png
│ └── after.png
└── assets/
└── diagram.svg이렇게 하면 index.html 안의 ./images/before.png 같은 상대 경로가 그대로 유지돼요. 파일 하나를 전달하는 방식에서 생기던 이미지 깨짐을 줄일 수 있었어요.
이 도구에 Git은 없었어요. 설치도, 터미널도, commit도, push도 없었어요.
대신 문서를 공유하는 데 꼭 필요한 경험만 남겼어요.
- HTML과 필요한 이미지 파일을 폴더째 올린다.
- 업로드된 문서를 바로 연다.
- 링크를 복사해 Slack에 공유한다.
다음 날에는 보안 조건을 점검했어요. 문서는 사무실 IP에서만 열리도록 하고, 업로더는 필요한 문서 경로에만 접근할 수 있도록 범위를 제한했어요.
사용자에게 사용법을 설명하는 데는 약 5분이면 충분했어요. 물론 처음부터 매끄럽지는 않았어요. 데모 중 드래그 앤 드롭이 고장 나기도 했어요. 데모의 기적은 없었어요.
대신 그 순간이 도움이 됐어요. 제가 당연하다고 생각한 동작이 실제 사용자에게도 당연한지 바로 확인할 수 있었기 때문이에요. 피드백을 반영해 흐름을 더 단순하게 다듬었어요.
이후에는 기획·운영 문서를 급하게 공유해야 하는 상황에서 사용됐고, 빠른 공유가 필요한 개발팀 구성원도 이 도구를 찾기 시작했어요.
같은 문제, 다른 진입점
개발자용 Git 파이프라인과 브라우저 업로더는 서로 경쟁하는 도구가 아니에요. 같은 문제를 다른 사용자의 작업 환경에 맞춰 푼 두 가지 진입점이에요.
| 구분 | 개발자용 문서 흐름 | 브라우저 업로더 |
|---|---|---|
| 업로드 | Git commit / push | 폴더 드래그 앤 드롭 |
| 배포 | CI 자동 배포 | 업로드 즉시 반영 |
| 공유 | 배포 URL 전달 | 링크 복사 |
| 문서 단위 | Git으로 이력을 관리하는 HTML과 정적 자원 | 폴더 구조를 보존해 바로 공유할 HTML 결과물 |
| 잘 맞는 상황 | 이력과 협업 기록이 중요한 개발 문서 | 빠르고 직관적인 문서 공유 |
개발팀에는 Git 이력이 문서를 관리하는 중요한 맥락이에요. 반면 빠른 전달이 중요한 사람에게는 "파일을 올리고 링크를 복사한다"는 경험이 더 중요해요.
처음에는 한 가지 파이프라인을 전사에 확장하려 했어요. 하지만 필요한 것은 모두를 같은 방식으로 일하게 만드는 일이 아니라, 각자가 문서를 가장 적은 비용으로 공유하게 만드는 일이었어요.
더 멋진 기능보다, 지금 덜 불편한 것
개발자로서 아쉬움이 없는 것은 아니에요.
더 예쁜 화면을 만들 수도 있고, 문서별 댓글이나 검색, 즐겨찾기 같은 기능도 떠올랐어요. 하지만 이 도구가 풀어야 할 문제는 사내 문서 플랫폼을 만드는 일이 아니었어요.
다운로드 없이 링크 하나로 문서를 열고, 이미지가 깨질 걱정 없이 내용을 이해하고, 필요한 사람에게 바로 전달하는 것. 그것이면 충분했어요.
AI 덕분에 문서를 만드는 시간은 줄었어요. 대신 예전에는 많지 않아서 보이지 않던 공유 이후의 불편함이 더 자주 보이기 시작했어요.
이번에 만든 것은 거대한 플랫폼이 아니에요. 개발자에게는 Git 기반 자동 배포를, Git이 업무 흐름에 맞지 않는 사람에게는 브라우저 기반 업로드를 제공했어요.
결국 중요한 것은 더 많은 기능을 만들 수 있는가가 아니라, 팀이 오늘 덜 불편하게 일할 수 있는가였어요.
지금 다시 보면
이 글을 쓰면서 다시 찾아보니, Notion에는 Agent가 만드는 대화형 HTML block 기능이 생겼더라고요.
문서의 정본이 Notion에 있고, 댓글·태그·검색·변경 이력처럼 문서 자체를 함께 관리하는 일이 중요하다면 지금은 Notion을 먼저 검토할 것 같아요. 팀이 이미 매일 쓰는 도구 안에서 문서를 만들고, 수정하고, 이야기할 수 있으니까요.
다만 제가 해결하려던 문제와 완전히 같지는 않아요.
당시에는 HTML 파일 하나가 아니라 이미지, CSS, SVG처럼 서로를 참조하는 정적 자원이 함께 만들어졌어요. HTML 파일만 공유하면 상대 경로가 깨질 수 있었고, 그래서 폴더 구조를 그대로 올리고 유지하는 일이 중요했어요.
문서를 Notion 안에서 새로 만들고 관리한다면 Notion이 좋은 정본이 될 수 있어요. 반대로 이미 만들어진 HTML 결과물과 그 안의 파일 관계를 그대로 공유해야 한다면, 폴더 단위로 올려 링크를 만드는 흐름이 여전히 의미 있을 것 같아요.
결국 지속 가능한 도구는 처음 만든 기능의 개수가 아니라, 사람들이 실제로 계속 쓰는지와 기존 도구가 어떻게 발전하는지에 따라 달라지는 것 같아요. 그래서 지금도 이 업로더가 계속 쓰이는지, 문서가 실제로 갱신되는지, 더 자연스러운 대안이 생기지는 않았는지 보려고 해요.