🤖 [연구AX] '읽기 불편한데?' 한마디로 시작된, 나만의 리더 앱 개발기

[Claude Code / OpenCode] '읽기 불편한데?' 한마디로 시작된, 나만의 리더 앱 개발기

📝 한줄 요약

비개발자 연구자가 Claude에게 "읽기 불편하다"고 말했더니, 내 워크플로우에 최적화된 리더 앱이 이틀 만에 완성됐습니다. 핵심은 해법을 몰라도, 불편함만 말하면 AI가 방법을 제안해준다는 것.

🎯 이런 분들께 도움돼요

• AI 코딩 도구(Claude Code, Cursor 등)를 쓰고 있지만 "뭘 시켜야 할지 모르겠다"는 분

• 연구자, 기획자 등 비개발자인데 업무 도구를 직접 만들어보고 싶은 분

• "버그 잡다가 지쳤다" — AI한테 코드 수정만 시키고 계신 분

😫 문제 상황 (Before)

저는 박사 논문을 쓰는 인문학 연구자입니다. 작업 환경은 마크다운 기반이에요. 논문도 마크다운으로 쓰고, 사료 분석 결과도 마크다운 파일로 관리합니다.

쓰는 건 괜찮았어요. 마크다운 에디터에서 글 쓰는 건 충분히 익숙하니까.

문제는 읽는 것이었습니다. 수십 페이지짜리 한문 사료를 검토하거나, Claude에게 분석시킨 리포트를 정독할 때 — 마크다운 에디터 창은 읽기용이 아니었어요.

• 프리뷰를 매번 켜야 하고 (단축키 한 방이지만 그것도 귀찮고)

• 작업창이 여러 개 띄워져 있으니 시선이 분산되고

• 무엇보다 여러 색깔로 하이라이트하면서 읽고 싶은데, 마크다운에서 형광펜 치려면 문법을 직접 타이핑해야 하고

• 특히 한문(漢文)이 에디터 창에서는 가독성이 정말 떨어졌습니다

저는 이미 PDF용으로는 나름의 시스템이 있었어요. Highlights 앱으로 PDF를 읽으면서 여러 색으로 마킹하고 메모를 달면, 그걸 자동으로 마크다운 파일로 정리해주는 도구를 Claude와 함께 만들어 쓰고 있었거든요.

🤖 [연구AX] PDF 밑줄만 치면 AI가 맥락까지 정리해준다 — 박사과정생의 리딩노트 자동화기

그때 생각했습니다. "사료도 그렇게 읽으면 안 되나?"

🛠️ 사용한 도구

• Claude Code (Day 1): 초기 개발 전체

• OpenCode + OhMyOpenCode (Day 2): 리팩토링 + 추가 개발. OhMyOpenCode는 OpenCode용 플러그인으로, Oracle 같은 전문 에이전트를 활용할 수 있게 해줍니다

• 모델: Claude Opus

🔧 작업 과정

1단계: "읽기가 불편해" — 해법을 몰라도 괜찮았다

처음에 저는 해결책이 뭔지 몰랐습니다. 그냥 불편하다고 말했어요.

사료 파일들을 좀 더 편하게 읽고 마킹하고 메모하고 싶어. VSCode에서는 편하지 않거든. 다만 마킹과 메모가 다시 마크다운으로 통합되어서 잘 관리되어야 해.

Claude가 세 가지 접근법을 비교해줬습니다.

• A. Obsidian 읽기 모드 활용

• B. 커스텀 웹 리더 (로컬에서 돌아가는 웹 앱)

• C. 태블릿 앱

저는 "웹 앱"이라는 발상 자체를 못 했어요. 그런데 Claude가 각각의 장단점을 분석해주면서, 제 마크다운 파일 구조(프론트매터, PROTECTED 블록 등)에는 커스텀 웹 리더가 압도적으로 유리하다고 설명해줬습니다.

이게 이번 개발의 첫 번째 핵심이에요. 내가 해법을 모르더라도, 불편함만 솔직하게 말하면 AI가 방법을 제안해준다는 것.

2단계: "이건 어떻게 작동하는 거야?" — 비개발자를 위한 상의

플랜이 나왔지만, 저는 인문학 전공자입니다. "Flask 앱", "API 라우트" 같은 말이 이해가 안 됐어요.

계획을 좀 더 상세히 설명해줘. 지금대로면 인문학 전공자인 내가 어떤 기능들이 구현되는지 이해하기 어려워.

Claude가 개발 용어 없이, 사용자 경험 중심으로 다시 설명해줬습니다. "파일을 고르면 → 오른쪽에 예쁘게 표시되고 → 드래그하면 색칠되고 → 메모를 달 수 있고 → 저장은 자동으로." 이렇게요.

그 위에 제가 세부 취향을 얹었습니다.

서체는 애플 고딕 계열을 좋아해. 메모는 해당 단락 아래에 둘 거야? 문장 바로 아래에? 텍스트 선택 없이 바로 메모를 추가하고 싶을 때는?

이런 식으로 한 번에 다 정하는 게 아니라, 대화하면서 점점 구체화해 나갔어요. Claude는 제 요청마다 "이건 이래서 좋고, 저건 저래서 마크다운 구조가 깨질 수 있다"고 솔직하게 의견을 줬습니다.

3단계: 구현 — 10분 만에 앱이 나왔다

플랜이 확정되고 "진행해"라고 했더니, 정말 10~15분 만에 앱이 돌아갔습니다.

웹 브라우저에서 제 마크다운 파일들을 탐색하고, 한문 원문은 명조체로 예쁘게 표시되고, 텍스트를 드래그하면 6가지 색깔로 하이라이트가 쳐지고, 메모도 달 수 있는 — 제 워크플로우에 딱 맞는 리더 앱이었어요.

하이라이트나 메모를 달면 원본 마크다운 파일에 바로 저장되기 때문에, VSCode에서 열어도 그대로 보이고, 검색도 됩니다. 별도 데이터베이스가 필요 없는 구조.

여기까지는 순탄했습니다.

4단계: 잔버그와의 전쟁 — "고쳐줘"만으로는 한계가 있다

문제는 실제로 쓰면서 나타났어요.

사료를 읽다 보면 간헐적으로 이상한 일이 벌어졌습니다. 한 줄만 하이라이트했는데 전체 단락이 칠해진다든지, 하이라이트를 삭제하려고 클릭했는데 "찾을 수 없습니다"라고 뜬다든지. 그때마다 Claude에게 "이거 고쳐줘"라고 했고, 고쳐지긴 했는데 — 다음날 또 다른 상황에서 비슷한 문제가 나왔어요.

하루 정도 이랬습니다. 사료 읽다가 버그 → 수정 요청 → 고침 → 다시 읽다가 또 버그. 읽기 흐름이 계속 끊겨서 짜증이 났어요.

이때 깨달은 게 있습니다. 버그를 하나씩 잡아달라고 하는 건 비효율적이다. 근본적으로 코드 구조를 봐야 한다.

5단계: "A급 개발자 관점에서 전체를 봐줘" — Oracle의 등장

마침 이날 OpenCode(Claude Code의 오픈소스 대안)를 설치했고, OhMyOpenCode라는 플러그인도 붙였습니다. 이 플러그인의 핵심 기능 중 하나가 Oracle 에이전트 — 고난도 문제에 특화된 상담 전문 AI입니다.

전략을 바꿨습니다.

지금 리더 앱을 종합적으로 점검해봐. A급 개발자 입장에서 이 앱의 현재 상태로 예상되는 버그들을 예상하고, 그에 맞게 최적으로 리팩토링해봐.

이전에 Claude Code에서도 비슷한 요청을 한 적이 있었어요. 그때도 리팩토링을 해줬지만, 잔버그가 계속 나왔거든요.

그런데 이번에는 달랐습니다. Oracle과 상담한 뒤 나온 리팩토링 플랜은 근본 원인 5가지를 정확히 짚었고, 추가로 예측 버그 8개까지 선제적으로 발견했어요. 이걸 3단계로 나눠서 체계적으로 수정한 뒤 — 잔버그가 확 줄었습니다.

같은 "전체적으로 봐줘"라는 요청인데, 누가(어떤 에이전트가) 보느냐에 따라 퀄리티가 이렇게 다를 수 있구나 — 이게 제가 말하는 "Oracle 미라클"입니다.

6단계: "읽다가 수정도 하고 싶어" — 또 상의, 또 제안

안정화 이후, 실제로 사료를 읽다 보니 새로운 니즈가 생겼습니다.

읽다 보면 메모 말고, 본문을 약간만 수정하고 싶을 때가 있어. 그때마다 다시 에디터 창으로 돌아가야 하거든. 리더 앱에 편집 기능을 추가하는 거에 대해 어떻게 생각해?

이번에도 "만들어줘"가 아니라 "어떻게 생각해?"라고 물었어요.

Claude의 답이 인상적이었습니다. "찬성이다. 이미 하이라이트와 메모가 원본 파일을 수정하고 있어서 기반은 갖춰져 있다. 단, 전면 편집으로 가면 scope이 커지니까, 단락 편집 모달로 제한하는 게 좋겠다"고.

단락에 마우스를 올리면 연필 버튼이 뜨고, 누르면 그 단락의 원본 마크다운을 수정할 수 있는 방식. 전체 에디터를 만드는 게 아니라, "읽다가 살짝 고치기"에 딱 맞는 범위.

이것도 제가 구체적 구현 방식을 지정한 게 아니에요. 니즈만 말했고, 방식은 Claude가 제안한 겁니다.

7단계: UX가 마음에 안 들어 — 디자이너한테 물어봐줘

바로가기(즐겨찾기) 기능을 넣었는데, 쓸수록 UX가 직관적이지 않았어요.

보이긴 하는데 UX가 직관적이지 않네. 웹 디자이너 관점에서 컨설팅 받아서 수정해줄래?

여기서 다시 Oracle이 등장합니다. UX 컨설팅을 받은 뒤, 기존의 + 버튼 방식에서 ☆/★ 핀 토글 방식으로 전면 전환. 폴더 탐색 중에 별표를 누르면 즐겨찾기에 추가되고, 다시 누르면 해제. 훨씬 직관적이 됐습니다.

8단계: "친구한테 공유하고 싶어" — 니즈를 말하면 된다

앱이 만족스러워지니까 욕심이 생겼어요.

공유용으로 만들어줄 수 있어? 지금은 내 프로젝트 경로가 하드코딩되어 있잖아. 친구한테 줄 수 있게 설정 파일로 빼줘.

Claude가 내부 경로를 전부 외부 설정 파일(YAML)로 분리해서, 누구든 자기 환경에 맞게 설정만 바꾸면 쓸 수 있는 공유용 버전을 만들어줬습니다. 경로, 바로가기 목록, 포트 번호까지 설정 파일 하나로 관리.

이것도 역시 — "친구한테 공유하고 싶어"라는 니즈만 말했을 뿐, 설정 파일 분리 방식이나 YAML 같은 기술적 결정은 Claude가 한 겁니다.

✅ 결과 (After)

Before vs After

결과물: Gloss

최종 완성된 앱 이름은 Gloss. 텍스트에 주석(gloss)을 다는 행위에서 따왔습니다.

• 마크다운 파일 브라우징 및 렌더링

• 6색 하이라이트 (드래그로 즉시 적용)

• 메모 3가지 방식 (텍스트 선택 메모 / 하이라이트 메모 / 단락 메모)

• 단락 편집 (연필 버튼 → 모달)

• 사이드바 리사이즈 + 즐겨찾기 핀 토글

• 원본 마크다운 파일에 직접 저장 (별도 DB 없음)

💬 이 과정에서 배운 AI 활용 팁

1. 불편함을 참지 말고 AI한테 말해봐라

가장 중요한 팁입니다. 저는 "로컬 웹 앱을 만들어줘"라고 한 적이 없어요. "읽기가 불편해"라고 했을 뿐입니다. 편집 기능도 "모달 방식으로 구현해줘"가 아니라 "읽다가 수정하고 싶을 때가 있는데 어떻게 생각해?"였고요.

내가 해법을 모르더라도 괜찮습니다. AI한테 기술적 지시를 내릴 필요가 없어요. 불편함, 니즈, 상황을 솔직하게 말하면 AI가 방법을 제안해줍니다. 그리고 그 제안이 꽤 좋습니다.

2. 버그 하나씩 잡지 말고, 전체적으로 봐달라고 시켜라

앱이 만들어진 뒤 잔버그가 계속 났을 때, 저는 처음에 "이거 고쳐줘", "이것도 안 돼" 식으로 하나씩 시켰어요. 이러니까 하나 고치면 다른 데서 터지고, 끝이 없었습니다.

전환점은 "A급 개발자 입장에서 전체를 점검하고 리팩토링해줘"라고 요청한 순간이었어요. 개별 증상이 아니라 근본 원인을 찾아서 체계적으로 수정하니까, 잔버그가 한꺼번에 사라졌습니다.

3. 역할을 부여하면 퀄리티가 달라진다

같은 "전체적으로 봐줘"라는 요청인데, "A급 개발자 관점에서"라는 역할을 붙이니 결과가 확연히 달랐어요.

저는 OpenCode에서 OhMyOpenCode 플러그인의 Oracle 에이전트를 활용했는데, 일반 모드에서의 리팩토링과 Oracle을 거친 리팩토링은 품질 차이가 분명했습니다. Oracle은 사용자 보고 이슈의 근본 원인을 정확히 짚고, 아직 발생하지 않은 잠재 버그까지 선제적으로 발견해줬어요.

이렇게 하면 안 돼요

1. "고쳐줘"만 반복하기 — 근본 원인을 안 보고 증상만 고치면 끝이 없습니다. 몇 번 반복되면 "전체적으로 봐줘"로 전략을 바꾸세요.

2. 기술적 지시를 억지로 하기 — "Flask로 만들어", "REST API로" 같이 모르는 걸 지정하면 오히려 결과가 나빠질 수 있어요. 니즈만 말하고 방법은 AI한테 맡기세요.

🌍 다른 업무에 적용한다면?

이 경험의 핵심은 "리더 앱을 만들었다"가 아니라, "불편함을 말했더니 맞춤 도구가 나왔다"는 점입니다.

• 매번 엑셀에서 수작업으로 정리하는 데이터가 있다면 → "이 작업이 반복적인데 자동화할 수 있을까?"

• 회의록을 특정 포맷으로 매번 정리해야 한다면 → "이 포맷으로 자동 정리해주는 도구를 만들 수 있을까?"

• 여러 출처의 자료를 비교 검토해야 한다면 → "두 문서를 나란히 보면서 메모할 수 있으면 좋겠는데"

포인트는, 해법을 지정하는 것이 아니라 불편함과 니즈를 구체적으로 설명하는 것. AI가 상황에 맞는 방법을 제안해줄 겁니다.

🚀 앞으로의 계획

현재로서는 Gloss로 충분합니다. 사료 읽기와 정독 작업에 잘 쓰고 있어요. 필요한 기능이 생기면 그때 또 "이런 게 필요한데"라고 말하면 되니까요.

📋 재사용 가능한 프롬프트

프롬프트 1: 불편함에서 시작하는 도구 제안 받기

[현재 작업 상황]을 하고 있는데, [구체적인 불편함]이 있어. [기존에 시도한 방법]은 [왜 안 되는지]. 이걸 해결할 수 있는 방법을 추천해줘. 각 방법의 장단점도 비교해줘.

프롬프트 2: 비개발자를 위한 상세 설명 요청

계획을 좀 더 상세히 설명해줘. 개발 용어 없이, 내가 사용자로서 어떤 경험을 하게 되는지 중심으로.

프롬프트 3: 전체 리팩토링 요청

지금 [앱/도구]를 종합적으로 점검해봐. A급 개발자 입장에서 현재 상태로 예상되는 버그들을 예상하고, 그에 맞게 최적으로 리팩토링해봐.

프롬프트 4: 니즈 중심 기능 상의

[상황 설명]. [새로운 니즈] 하고 싶은데, [앱/도구]에 이 기능을 추가하는 거에 대해 어떻게 생각해?