📝 한줄 요약
HWP 파일을 마크다운으로 변환하는 앱이 없어서, AI 코딩 도구(Codex CLI)에게 시켜서 웹앱 + 데스크톱 앱을 하루 만에 만들었습니다.
바쁘시면 이것만 읽어도 돼요:
Codex CLI(GPT-5 기반)에게 "HWP를 마크다운으로 바꿔주는 앱 만들어줘" 한 마디로 시작
14분 만에 웹앱 초안이 나왔고, 테스트→수정→GUI→배포까지 하루 만에 완료
기존 변환 도구들은 표가 깨지는 게 문제 — AI가 한국 워드프로세서(HWPX)의 테이블 구조를 직접 분석해서 해결
"마크다운 아니라 HTML인데?" 같은 짧은 피드백만으로도 원인 파악 + 대안 제시
결과물: 드래그앤드롭으로 HWP → 마크다운 변환하는 macOS 앱 (GitHub 공개)
🎯 이런 분들께 도움돼요
HWP 파일을 자주 다루는 직장인/공무원 — 한컴 문서를 다른 형식으로 옮기는 게 늘 불편했던 분
옵시디언/노션 등 PKM(개인지식관리) 도구를 쓰는 분 — HWP 문서를 자기 시스템에 넣고 싶은데 방법을 모르는 분
AI 코딩 도구로 뭘 할 수 있는지 궁금한 분
😫 문제 상황 (Before)
옵시디언으로 문서를 관리하는데, 받는 파일 중에 HWP가 꽤 많습니다. 전시 신청서, 보고서, 가이드 문서... 한국에서 일하면 피할 수 없는 포맷이죠.
문제는 HWP를 마크다운으로 깔끔하게 변환해주는 도구가 마땅히 없다는 겁니다. 특히 표가 문제였습니다. 기존 변환 도구들은 표 구조를 제대로 못 살려서, 결국 한컴오피스를 열고 내용을 수동으로 복사해서 옮기는 수밖에 없었습니다.
그래서 생각했습니다 — 없으면 만들면 되지 않나?
🛠️ 사용한 도구
Codex CLI: OpenAI의 AI 코딩 도구 (GPT-5 기반, Antigravity 익스텐션에서 실행)
모드: danger-full-access (파일 생성/수정/명령어 실행을 자유롭게 허용)
🔧 작업 과정
"앱 만들어줘" — 14분 만에 나온 첫 결과물
처음에는 거창한 계획 없이, 한 마디로 시작했습니다.
hwp 파일을 읽어서 마크다운으로 변환하는 앱을 만들고 싶어 특히 표같은게 완벽하게 변환 되어야해
Codex는 바로 작업에 들어갔습니다. 먼저 컴퓨터에 어떤 변환 도구가 설치되어 있는지 확인하고, HWP 파일의 표 구조를 어떻게 파싱할지 분석했습니다. 흥미로웠던 건, 한국에서 만든 HWPX 파서 라이브러리(Java)의 소스코드를 직접 열어서 테이블의 행/열 병합 구조(rowSpan, colSpan)를 파악했다는 점입니다.
14분 후, 13개 파일로 구성된 웹앱이 완성됐습니다. 브라우저에서 HWP 파일을 업로드하면 마크다운으로 변환해주는 앱이었습니다.
"테스트해봐" — 실패에서 배우기
앱이 만들어졌으니 실제 파일로 테스트를 시켜봤습니다.
테스트해봐
Codex가 컴퓨터에서 HWP 파일들을 찾아서 직접 변환을 시도했는데, .hwpx 파일은 성공했지만 .hwp 파일은 전부 실패했습니다. LibreOffice라는 변환 도구가 이 컴퓨터에서 HWP 포맷을 지원하지 않는 게 원인이었습니다.
솔직히 이 부분은 아쉬웠습니다. 처음 만들 때 미리 확인했으면 좋았을 텐데, 실제로 테스트를 해봐야 알 수 있었던 문제였습니다. 하지만 문제를 파악한 뒤 대안을 요청하면 바로 해결해주는 점은 좋았습니다.
hwp용 대체 개발
7분 만에 pyhwp라는 다른 변환 도구를 찾아서 연결했고, 이번에는 실제 HWP 파일이 정상적으로 변환됐습니다.
진짜 파일로 검증 — 에러와의 싸움
좀 더 까다로운 파일로 테스트해봤습니다. 전시 지원금 신청서 HWP 파일을 던져줬더니, 이번에는 변환 결과가 0바이트(빈 파일)로 나왔습니다.
Codex가 원인을 추적하니, 변환 도구 내부의 문서 검증 단계에서 막히는 거였습니다. 이걸 우회하는 래퍼를 만들어서 해결했는데, 변환은 됐지만 이번에는 결과물에 이미지 데이터가 글자로 섞여 나오는 새로운 문제가 생겼습니다.
이것도 파서가 이미지 데이터를 본문 텍스트로 읽는 게 원인이라 바로 필터를 추가해서 해결. 에러가 나고 → 원인을 찾고 → 고치는 과정이 대화 한두 턴 만에 끝나니까, 흐름이 크게 끊기지 않았습니다.
"마크다운이 아니라 HTML인데?" — 짧은 피드백의 힘
변환 결과물을 열어봤는데, 마크다운 파일이라면서 안에 HTML 코드가 들어있었습니다.
마크다운이 아니라 html로 저장되는듯한데?
Codex가 바로 확인하더니, 병합 셀이 있는 복잡한 표를 마크다운으로는 표현이 안 돼서 의도적으로 HTML 테이블로 넣은 거라고 설명했습니다. 그리고 3가지 대안을 제시했습니다.
저는 그냥 "수정해줘"라고만 했고, 병합 셀을 펼쳐서 순수 마크다운 표로 만드는 방식으로 바꿔줬습니다.
결과적으로 변환 결과물은 이중으로 제공되는 구조가 됐습니다. 편집과 옵시디언 활용에 적합한 마크다운 파일(result.md)과, 원본 표 구조를 최대한 보존한 HTML 미리보기(preview.html)가 함께 저장됩니다. 마크다운에서 표가 완벽하지 않더라도 HTML 버전에서 원본에 가까운 형태를 확인할 수 있어서, 용도에 따라 골라 쓸 수 있습니다.
"GUI로 만들어줘" — 데스크톱 앱 + 아이콘 + 배포까지
웹앱으로 쓰기엔 매번 서버를 켜야 해서 불편할 것 같았습니다.
gui로 편리하게 사용하게 만들어줘 패키징도 고려해서
13분 후, 데스크톱 GUI 앱이 나왔습니다. 파일을 드래그앤드롭하면 변환되고, 결과를 더블클릭하면 폴더가 열리는 방식이었습니다. macOS 앱 번들(.app)로 패키징까지 해줬습니다.
여기서 끝이 아니었습니다. "앱 아이콘이랑 배포용 서명 흐름까지 붙여드릴게요"라고 제안하길래 승인했더니, SVG 아이콘 디자인, 아이콘 변환 스크립트, macOS 앱 서명 자동화 스크립트까지 한 번에 만들어줬습니다.
"GUI 만들어줘" 한 마디에서 데스크톱 앱 + 앱 아이콘 + macOS 배포 파이프라인이 나온 겁니다.
GitHub 배포
최종 결과: https://github.com/DECK6/hwp-markdown-app (공개 저장소)
✅ 결과 (After)
Before vs After
항목
Before
After
HWP → 마크다운
한컴오피스 열고 수동 복붙
드래그앤드롭으로 자동 변환
표 처리
깨져서 직접 다시 그리기
마크다운 표로 자동 변환 (한계 있음)
소요 시간
파일당 수 분~수십 분
수 초
도구
없음 (마땅한 변환기 부재)
웹앱 + macOS 데스크톱 앱
결과물
웹앱: 브라우저에서 파일 업로드 → 변환 → 미리보기/다운로드
데스크톱 앱: macOS 앱 번들, 드래그앤드롭 지원
변환 결과 이중 제공: 편집용 마크다운(result.md) + 표 구조를 정확히 보존한 HTML 미리보기(preview.html) + 원본 파일 보관
GitHub 공개 저장소로 누구나 사용 가능
아직 남은 한계
표 변환은 단순한 표는 잘 되지만, 복잡한 병 합 셀이 많은 표는 아직 완벽하지 않습니다. 병합된 셀을 펼쳐서 마크다운으로 만드는 방식이라 원본과 모양이 다를 수 있습니다. 이 부분은 계속 개선할 예정입니다.
💬 이 과정에서 배운 AI 활용 팁
효과적이었던 것
짧은 피드백이 통한다 — "마크다운이 아니라 HTML인데?" 같은 한 줄이면 충분했습니다. AI가 대화 맥락을 기억하고 있어서 긴 설명이 필요 없었습니다.
에러를 두려워하지 않아도 된다 — 에러가 나면 그 자체가 다음 대화의 입력이 됩니다. "테스트해봐" → 실패 → "대체 개발" → 성공, 이런 흐름이 자연스러웠습니다.
점진적으로 요청하기 — 처음부터 "웹앱 + GUI + 패키징 + GitHub 배포" 다 말한 게 아니라, 단계별로 요청하면서 결과를 확인하고 다음 단계를 정했습니다.
이렇게 하면 안 돼요
AI가 만든 결과를 테스트 없이 믿지 마세요 — 처음에 LibreOffice 기반으로 만들었는데 실제 파일에서 실패했습니다. 꼭 실제 데이터로 검증해야 합니다.
저장소 구조를 미리 설명하세요 — GitHub 배포할 때 상위 저장소에 커밋되는 삽질이 있었는데, 프로젝트 구조를 미리 알려줬으면 방지할 수 있었습니다.
🌍 다른 업무에 적용한다면?
이번 경험에서 얻은 패턴은 이렇습니다: "기존 도구가 내 상황에 안 맞으면, AI에게 맞춤형 도구를 만들어달라고 하기"
예를 들어:
회사에서 쓰는 특정 엑셀 양식 → 자동으로 보고서 형태로 변환
PDF 계약서에서 핵심 조항만 추출해서 정리
반복적으로 하는 파일 포맷 변환 자동화
"변환"이 필요한 모든 업무에 같은 방식을 적용할 수 있습니다.
🚀 앞으로의 계획
표 변환 정확도를 더 높이는 게 가장 큰 과제입니다. 현재는 병합 셀을 펼쳐서 마크다운으로 만드는 방식인데, 원본의 표 구조를 더 정확하게 살리는 방법을 찾아볼 예정입니다.
