요새 나는 IDE 켜놓고 마크다운 에디터로 작업한다. 논문도 마크다운으로 쓰고, 사료 분석 결과도 마크다운 파일로 관리한다.
쓰는 건 괜찮았다. 문제는 읽는 것이었다. 수십 페이지짜리 한문 사료를 검토하거나, Claude에게 분석시킨 리포트를 정독할 때 — 마크다운 에디터 창은 읽기용이 아니었다.
- 프리뷰를 매번 켜야 하고 (단축키 한 방이지만 그것도 귀찮고)
- 작업창이 여러 개 띄워져 있으니 시선이 분산되고
- 무엇보다 여러 색깔로 하이라이트하면서 읽고 싶은데, 마크다운에서 형광펜 치려면 문법을 직접 타이핑해야 하고
- 특히 한문(漢文)이 에디터 창에서는 가독성이 정말 떨어졌다
이 글은 “읽기가 불편하다”는 한마디에서 시작해, Claude(Opus)와 이틀 만에 연구용 리더 앱 Gloss를 만든 과정이다. 이 과정에서 확인한 것: 해법을 몰라도 불편함만 솔직하게 말하면 AI가 방법을 제안한다는 것, 그리고 버그를 하나씩 잡는 것보다 전체를 점검하게 하는 것이 훨씬 효과적이라는 것.
마크다운 에디터는 쓰기용이지, 읽기용이 아니다
이미 PDF용으로는 나름의 시스템이 있었다. Highlights 앱으로 PDF를 읽으면서 여러 색으로 마킹하고 메모를 달면, 그걸 자동으로 마크다운 파일로 정리해주는 도구를 Claude와 함께 만들어 쓰고 있었다.
그때 생각했다. “사료도 그렇게 읽으면 안 되나?"
"읽기가 불편해” — 해법을 몰라도 괜찮았다
처음에 나는 해결책이 뭔지 몰랐다. 그냥 불편하다고 말했다.
사료 파일들을 좀 더 편하게 읽고 마킹하고 메모하고 싶어. VSCode에서는 편하지 않거든. 다만 마킹과 메모가 다시 마크다운으로 통합되어서 잘 관리되어야 해.
Claude가 세 가지 접근법을 비교해줬다.
- A. Obsidian 읽기 모드 활용
- B. 커스텀 웹 리더 (로컬에서 돌아가는 웹 앱)
- C. 태블릿 앱
나는 “웹 앱”이라는 발상 자체를 못 했다. 그런데 Claude가 각각의 장단점을 분석해주면서, 내 마크다운 파일 구조(프론트매터, PROTECTED 블록 등)에는 커스텀 웹 리더가 압도적으로 유리하다고 설명해줬다.
이게 이번 개발의 첫 번째 전환점이었다. 내가 해법을 모르더라도, 불편함만 솔직하게 말하면 AI가 방법을 제안해준다는 것.
”이건 어떻게 작동하는 거야?” — 비개발자를 위한 상의
플랜이 나왔지만, 나는 인문학 전공자다. “Flask 앱”, “API 라우트” 같은 말이 이해가 안 됐다.
계획을 좀 더 상세히 설명해줘. 지금대로면 인문학 전공자인 내가 어떤 기능들이 구현되는지 이해하기 어려워.
Claude가 개발 용어 없이, 사용자 경험 중심으로 다시 설명해줬다. “파일을 고르면 → 오른쪽에 예쁘게 표시되고 → 드래그하면 색칠되고 → 메모를 달 수 있고 → 저장은 자동으로.” 이렇게.
그 위에 내가 세부 취향을 얹었다.
서체는 애플 고딕 계열을 좋아해. 메모는 해당 단락 아래에 둘 거야? 문장 바로 아래에? 텍스트 선택 없이 바로 메모를 추가하고 싶을 때는?
이런 식으로 한 번에 다 정하는 게 아니라, 대화하면서 점점 구체화해 나갔다. Claude는 내 요청마다 “이건 이래서 좋고, 저건 저래서 마크다운 구조가 깨질 수 있다”고 솔직하게 의견을 줬다.
구현 — 10분 만에 앱이 나왔다
플랜이 확정되고 “진행해”라고 했더니, 정말 10~15분 만에 앱이 돌아갔다.
웹 브라우저에서 내 마크다운 파일들을 탐색하고, 한문 원문은 명조체로 예쁘게 표시되고, 텍스트를 드래그하면 6가지 색깔로 하이라이트가 쳐지고, 메모도 달 수 있는 — 내 워크플로우에 딱 맞는 리더 앱이었다.
하이라이트나 메모를 달면 원본 마크다운 파일에 바로 저장되기 때문에, VSCode에서 열어도 그대로 보이고, 검색도 된다. 별도 데이터베이스가 필요 없는 구조.
여기까지는 순탄했다.
잔버그와의 전쟁 — “고쳐줘”만으로는 한계가 있다
문제는 실제로 쓰면서 나타났다.
사료를 읽다 보면 간헐적으로 이상한 일이 벌어졌다. 한 줄만 하이라이트했는데 전체 단락이 칠해진다든지, 하이라이트를 삭제하려고 클릭했는데 “찾을 수 없습니다”라고 뜬다든지. 그때마다 Claude에게 “이거 고쳐줘”라고 했고, 고쳐지긴 했는데 — 다음날 또 다른 상황에서 비슷한 문제가 나왔다.
하루 정도 이랬다. 사료 읽다가 버그 → 수정 요청 → 고침 → 다시 읽다가 또 버그. 읽기 흐름이 계속 끊겨서 짜증이 났다.
이때 깨달은 게 있다. 버그를 하나씩 잡아달라고 하는 건 비효율적이다. 근본적으로 코드 구조를 봐야 한다.
”A급 개발자 관점에서 전체를 봐줘” — Oracle의 등장
마침 이날 OpenCode(Claude Code의 오픈소스 대안)를 설치했고, OhMyOpenCode라는 플러그인도 붙였다. 이 플러그인의 핵심 기능 중 하나가 Oracle 에이전트 — 고난도 문제에 특화된 상담 전문 AI다.
전략을 바꿨다.
지금 리더 앱을 종합적으로 점검해봐. A급 개발자 입장에서 이 앱의 현재 상태로 예상되는 버그들을 예상하고, 그에 맞게 최적으로 리팩토링해봐.
이전에 Claude Code에서도 비슷한 요청을 한 적이 있었다. 그때도 리팩토링을 해줬지만, 잔버그가 계속 나왔다.
그런데 이번에는 달랐다. Oracle과 상담한 뒤 나온 리팩토링 플랜은 근본 원인 5가지를 정확히 짚었고, 추가로 예측 버그 8개까지 선제적으로 발견했다. 이걸 3단계로 나눠서 체계적으로 수정한 뒤 — 잔버그가 확 줄었다.
같은 “전체적으로 봐줘”라는 요청인데, 누가(어떤 에이전트가) 보느냐에 따라 퀄리티가 이렇게 다를 수 있다는 걸 확인했다.
”읽다가 수정도 하고 싶어” — 또 상의, 또 제안
안정화 이후, 실제로 사료를 읽다 보니 새로운 니즈가 생겼다.
읽다 보면 메모 말고, 본문을 약간만 수정하고 싶을 때가 있어. 그때마다 다시 에디터 창으로 돌아가야 하거든. 리더 앱에 편집 기능을 추가하는 거에 대해 어떻게 생각해?
이번에도 “만들어줘”가 아니라 **“어떻게 생각해?”**라고 물었다.
Claude의 답이 인상적이었다. “찬성이다. 이미 하이라이트와 메모가 원본 파일을 수정하고 있어서 기반은 갖춰져 있다. 단, 전면 편집으로 가면 scope이 커지니까, 단락 편집 모달로 제한하는 게 좋겠다”고.
단락에 마우스를 올리면 연필 버튼이 뜨고, 누르면 그 단락의 원본 마크다운을 수정할 수 있는 방식. 전체 에디터를 만드는 게 아니라, “읽다가 살짝 고치기”에 딱 맞는 범위.
이것도 내가 구체적 구현 방식을 지정한 게 아니다. 니즈만 말했고, 방식은 Claude가 제안한 것이다.
UX가 마음에 안 들어 — 디자이너한테 물어봐줘
바로가기(즐겨찾기) 기능을 넣었는데, 쓸수록 UX가 직관적이지 않았다.
보이긴 하는데 UX가 직관적이지 않네. 웹 디자이너 관점에서 컨설팅 받아서 수정해줄래?
여기서 다시 Oracle이 등장한다. UX 컨설팅을 받은 뒤, 기존의 + 버튼 방식에서 ☆/★ 핀 토글 방식으로 전면 전환. 폴더 탐색 중에 별표를 누르면 즐겨찾기에 추가되고, 다시 누르면 해제. 훨씬 직관적이 됐다.
”친구한테 공유하고 싶어” — 니즈를 말하면 된다
앱이 만족스러워지니까 욕심이 생겼다.
공유용으로 만들어줄 수 있어? 지금은 내 프로젝트 경로가 하드코딩되어 있잖아. 친구한테 줄 수 있게 설정 파일로 빼줘.
Claude가 내부 경로를 전부 외부 설정 파일(YAML)로 분리해서, 누구든 자기 환경에 맞게 설정만 바꾸면 쓸 수 있는 공유용 버전을 만들어줬다. 경로, 바로가기 목록, 포트 번호까지 설정 파일 하나로 관리.
이것도 역시 — “친구한테 공유하고 싶어”라는 니즈만 말했을 뿐, 설정 파일 분리 방식이나 YAML 같은 기술적 결정은 Claude가 한 것이다.
결과
| 항목 | BEFORE | AFTER |
|---|---|---|
| 사료 읽기 | 마크다운 에디터에서 원본 텍스트로 읽음 | 웹 브라우저에서 렌더링된 화면으로 정독 |
| 하이라이트 | <mark> 태그 직접 타이핑 | 드래그 → 6색 중 선택 → 자동 저장 |
| 메모 | 마크다운 문법 직접 작성 | 팝업에서 입력, 드래그로 위치 이동 |
| 한문 가독성 | 에디터 고정폭 폰트 | 명조체 + 별도 배경 |
| 간단한 수정 | 에디터 창으로 전환 | 연필 버튼 → 제자리에서 수정 |
| 잔버그 | 하루 종일 하나씩 수정 | Oracle 리팩토링 이후 안정화 |
| 공유 | 불가 (내 환경 하드코딩) | 설정 파일 하나만 수정하면 누구나 사용 |
최종 완성된 앱 이름은 Gloss. 텍스트에 주석(gloss)을 다는 행위에서 따왔다.
- 마크다운 파일 브라우징 및 렌더링
- 6색 하이라이트 (드래그로 즉시 적용)
- 메모 3가지 방식 (텍스트 선택 메모 / 하이라이트 메모 / 단락 메모)
- 단락 편집 (연필 버튼 → 모달)
- 사이드바 리사이즈 + 즐겨찾기 핀 토글
- 원본 마크다운 파일에 직접 저장 (별도 DB 없음)
협업 관찰
이 앱은 이틀에 걸쳐 만들어졌다. Day 1에는 Claude Code로 초기 개발 전체를, Day 2에는 오마이오픈코드의 Oracle을 활용해 리팩토링과 추가 개발을 진행했다.
Claude가 한 것: 커스텀 웹 리더라는 접근법 제안, 사용자 경험 중심의 비개발자용 설명, 10~15분 만에 앱 구현, 단락 편집 모달이라는 scope 제한 제안, UX 개선(핀 토글), 공유용 설정 파일 분리.
내가 한 것: 불편함과 니즈 설명, “이해가 안 된다”고 솔직하게 말하기, 세부 취향 지정(서체, 메모 위치, 색상 체계), “어떻게 생각해?”로 기능 상의, 버그 리포트, “전체적으로 봐줘”로 전략 전환, Oracle 활용 결정.
키를 잡은 건 Claude였다 나는 “로컬 웹 앱을 만들어줘”라고 한 적이 없다. “읽기가 불편해”라고 했을 뿐이다. 편집 기능도 “모달 방식으로 구현해줘”가 아니라 “읽다가 수정하고 싶을 때가 있는데 어떻게 생각해?”였다. 기술적 지시를 내리지 않고 니즈와 불편함을 설명하자, Claude가 상황에 맞는 방법을 제안했고, 그 제안의 질이 높았다.
배움 포인트
해법을 몰라도, 불편함만 솔직하게 말하면 AI가 방법을 제안한다. 기술적 지시를 내릴 필요가 없었다. 불편함, 니즈, 상황을 설명하면 Claude가 접근법을 비교해주고, 구현 방식을 제안했다. 비개발자인 내가 이틀 만에 맞춤 도구를 가질 수 있었던 건 이 방식 덕분이다.
버그를 하나씩 잡는 것보다, 전체를 점검하게 하는 것이 효과적이다. “이거 고쳐줘”를 반복하면 하나 고칠 때 다른 데서 터진다. “A급 개발자 입장에서 전체를 점검하고 리팩토링해줘”라고 전략을 바꾸자, 근본 원인을 찾아 체계적으로 수정할 수 있었다.
같은 요청이라도, 어떤 에이전트가 보느냐에 따라 결과가 달라진다. 일반 모드에서의 리팩토링과 Oracle을 거친 리팩토링은 품질 차이가 분명했다. Oracle은 근본 원인을 정확히 짚고, 아직 발생하지 않은 잠재 버그까지 선제적으로 발견했다.