ikieEngineeringGet started
All posts

문서편집기MCPiOS

노션처럼 블록으로 쓰고, 저장은 Markdown 그대로 두었어요

일정·할 일에 붙이는 문서를 하루 만에 만들었어요. 편집기는 한 번 만든 것을 버리고 노션식 블록으로 바꿨고, iPhone은 블록 하나가 네이티브 글 칸 하나예요. 그래도 고치지 않은 블록은 글자 하나 바뀌지 않아요. 연결한 Claude가 글 일부를 찾아 바꾸기 때문이에요.

English

시작은 할 일 메모였어요. ikie를 만드는 Claude Code 세션들은 ikie에 연결해 일을 기록해요. 그러다 사람이 직접 해야 하는 콘솔 설정 같은 일이 나오면 ikie를 만드는 사람의 할 일로 만들고, 메모에 따라 하기 가이드를 길게 적었어요. 메모가 길어지자 제목·목록·체크가 글자 그대로 보여서 읽기 어려웠어요. 메모를 Markdown으로 그려 보이게 하려던 참에 한 걸음 더 나가기로 했어요. 문서를 따로 두고 일정·할 일에 붙이고, 나중에는 문서만 따로 다룰 수 있게요.

그날 오후부터 밤까지 PR 15개로 문서가 생겼어요. 웹과 iPhone·iPad, 연결한 Claude(MCP)에서 모두 써요. 시간은 이 결정에서 PR을 합칠 때까지예요.

  1. 0.6시간웹 메모를 Markdown으로 그리기
  2. 0.7시간문서 표·권한·API·연결 도구(MCP)
  3. 1.5시간iPhone 메모 그리기·문서·내 문서 목록
  4. 3.3시간연결 도구를 노션처럼: 찾아 바꾸기·앞에 넣기·글 안 찾기
  5. 3.5시간웹 편집기 B: 살아 있는 Markdown
  6. 4.9시간웹 편집기 A: 노션식 블록(BlockNote)
  7. 5.4시간iPhone·iPad 네이티브 블록 편집기
  8. 6.9시간그냥 적은 주소도 링크로(웹·iPhone)

메모와 문서를 나눴어요

먼저 어떻게 저장할지 정했어요. 세 가지 안을 놓고 골랐어요.

  • 문서 따로: 문서 표를 새로 두고 일정·할 일에 붙여요. 한 문서를 여러 곳에 붙일 수 있어요.
  • 항목 안 문서: 문서를 새 항목 종류로 두고 일정·할 일 안에 넣어요. 권한과 이력은 그대로 쓰지만 한 문서는 한 곳에만 붙어요.
  • 메모만 키우기: 새 표 없이 메모를 그려 보이게만 해요.

Google 캘린더는 Drive 파일을, Notion Calendar는 Notion 페이지를 일정에 붙여요. 둘 다 문서가 따로 서 있어요. 그래서 "문서 따로"로 갔어요.

메모는 그대로 남겼어요. 메모는 Google·Apple 캘린더의 설명 칸과 주고받는 짧은 글이에요. 긴 문서를 메모에 넣으면 그대로 외부 캘린더 설명으로 넘어가요. 그래서 메모는 짧은 진행 기록, 문서는 가이드나 회의록처럼 긴 글로 나눴어요. 메모도 Markdown으로 그려 보이지만, 저장은 글 그대로라 외부 캘린더에서 깨지지 않아요.

문서의 권한은 새로 만들지 않았어요. 붙인 일정·할 일을 따라가요.

  • 보기: 붙인 항목 중 하나라도 볼 수 있으면 봐요.
  • 고치기: 붙인 항목 중 하나라도 고칠 수 있으면 고쳐요. 만든 사람은 늘 보고 고쳐요.
  • 붙이기: 내가 고칠 수 있는 문서만 붙여요. 읽기만 하는 문서를 남에게 넓히지 않게요.
  • 지우기: 만든 사람만 지워요. 다른 사람은 자기 항목에서 떼기만 해요.

문서에는 판(revision)이 있어요. 웹과 iPhone은 손을 멈추고 0.8초 뒤 바뀐 칸만 판과 함께 보내요. 그사이 다른 곳에서 고쳤으면 서버가 거절하고, 화면은 새 글을 불러와 "내 글로 덮기"를 보여요.

Claude는 일부만 고쳐요

문서를 처음 붙였을 때 연결한 Claude는 글 전체를 다시 써서 저장했어요. 체크 하나를 바꾸려 해도 글 전체를 다시 보내야 했고, 그사이 사람이 고친 것을 덮을 위험도 있었어요. 노션 MCP가 이 일을 잘 풀고 있어서, 노션 MCP처럼 바꿨어요.

  • 찾아 바꾸기(edit_doc): 글에 있는 그대로의 한 곳을 찾아 바꿔요. 체크는 - [ ] 할 것을 - [x] 할 것으로 바꾸면 돼요.
  • 앞이나 끝에 넣기(append_doc): 글을 읽지 않고 더해요.
  • 글 안까지 찾기(list_docs): 제목뿐 아니라 글에서 찾고, 찾은 줄을 함께 돌려줘요.

찾아 바꾸기는 판이 필요 없어요. 서버가 그 문서 행을 잠근 채 지금 글에 바꾸기를 적용해요. 바꾸기 여러 개를 한 번에 보내면 차례로 적용하는데, 하나라도 맞지 않으면 아무것도 바꾸지 않아요. 맞는 곳이 없으면 edit_unmatched, 여러 곳이면 edit_ambiguous와 몇 번째 바꾸기인지를 돌려줘요. Claude는 그 하나만 고쳐서 다시 보내면 돼요.

메모도 같은 까닭으로 칸 하나만 고치는 길(edit_item)을 더했어요. 전에는 메모 한 줄을 바꾸려 해도 날짜·반복·알림까지 든 초안 전체를 보내야 했어요.

찾아 바꾸기는 글이 글자 그대로 남아 있어야 맞아요. 편집기가 저장할 때마다 글을 다시 쓰면, Claude가 방금 읽은 줄을 찾지 못해요.

이 원칙이 다음 결정을 거의 다 정했어요.

추천을 뒤집은 결정

처음 만든 문서 화면은 고칠 때 #, - [ ] 같은 기호가 그대로 보였어요. 디자인과 사용성이 중요한 화면이라 두 안을 한 화면에 나란히 그려서 고르게 했어요.

  • A 노션식 블록: 기호가 보이지 않고, 블록마다 손잡이로 끌어 옮겨요.
  • B 살아 있는 Markdown: Bear처럼 모양을 그리고, 쓰는 줄에만 기호가 흐리게 보여요.

만드는 쪽 Claude Code 세션은 B를 추천했어요. 저장한 글과 보이는 글이 같으니 찾아 바꾸기와 어긋날 일이 없고, iPhone은 네이티브 글 칸 하나로 만들 수 있다고 봤어요. A는 iPhone에서 웹 화면을 띄워야 한다고 적었어요. 답을 기다리는 동안 B로 웹 편집기(CodeMirror 6)를 만들어 합쳤어요.

고른 것은 A였고, iPhone에서도 네이티브로 할 수 없느냐는 물음이 붙었어요. 다시 보니 A도 네이티브로 돼요. Craft가 그렇게 해요. 블록 하나를 iOS 글 칸 하나로 두고 목록으로 쌓으면 돼요. 카드에 웹 화면이라고 적은 것은 그쪽이 손이 덜 가서였어요. 그래서 A로 갔고, B 편집기는 합친 지 한 시간 반이 안 돼 블록 편집기로 바뀌었어요.

남은 걱정은 B를 추천한 까닭 그대로였어요. 블록 편집기는 글을 블록으로 바꿨다가 저장할 때 다시 글로 써요. 그때 * 별이 - 별이 되는 식으로 모양이 바뀌면 원칙 1이 깨져요.

고치지 않은 블록은 글자 그대로

그래서 Markdown과 블록 사이를 잇는 블록 모델을 직접 정했어요. 편집기에 딸린 변환을 쓰지 않고, 앱 정책 패키지에 한 번 선언해서 웹과 iOS가 같이 써요.

  • 글을 블록으로 나눌 때 블록마다 받은 원문(raw)과 앞 블록과의 사이(lead)를 함께 들고 있어요.
  • 편집기에서 돌아온 블록의 모양(종류·단계·체크·깊이·글 토막)이 받을 때와 같으면 원문을 그대로 써요.
  • 고친 블록만 정한 모양으로 다시 써요.
  • 블록 편집기가 나누지 못하는 것(목록이 든 인용 같은)은 한 블록에 원문 글로 담아요. 링크 정의 같은 블록 사이의 글은 사이(lead)에 남아요.

블록을 모두 다시 쓰면

체크 하나 누르기모든 블록을 정한 모양으로
* 별 → - 별1) 번호 → 1. 번호~~~ → ```

Claude가 읽은 줄을 찾지 못해요

고친 블록만 다시 쓰면

체크 하나 누르기그 블록만 정한 모양으로
- [ ] 할 것 → - [x] 할 것나머지 블록은 받은 원문

글자 하나 다르지 않아요

이 약속은 시나리오 파일로 지켜요. "고치지 않으면 글자 하나 다르지 않다"는 사례에는 별 목록, 1) 번호, 빈 줄이 든 인용, 밑줄 제목, 참조 링크 정의, 글 없는 체크가 들어 있어요. 웹(TypeScript)과 iOS(Swift)의 블록 모델이 같은 사례로 시험받아요. 한쪽만 바꾸면 다른 쪽 시험이 깨져요.

웹은 BlockNote, iPhone은 블록마다 글 칸

웹은 오픈소스 BlockNote를 썼어요. 블록 끌기, 나누기, 합치기, 들여쓰기, Markdown 붙여 넣기까지 노션처럼 맞춘 편집기가 이미 있었어요. 우리가 만든 것은 블록 모델과 BlockNote 블록을 잇는 부분, / 넣기 목록과 서식 막대를 고른 것뿐이에요. 잇는 부분은 받은 블록마다 id와 모양을 적어 두고, 돌아온 블록의 모양이 같으면 원문을 써요.

iPhone·iPad는 웹 화면을 띄우지 않았어요. 문서 한 장이 목록(UICollectionView) 하나이고, 블록 하나가 UITextView 하나예요. 긴 문서도 보이는 칸만 만들어요. 블록 모델은 Swift로 같은 뜻으로 옮겼고, 블록 안 글의 위치는 cmark-gfm으로 읽어요.

플랫폼마다 다르게 둔 것도 있어요.

웹iPhone·iPad
블록 넣기줄 맨 앞 / 목록키보드 위 막대
서식글을 고르면 뜨는 막대, ⌘B·⌘I키보드 위 막대, 고르기 메뉴
옮기기손잡이로 끌기블록을 길게 눌러 끌기

iOS 키보드에는 / 목록을 고를 마우스나 단축키가 없고, 키보드 위 막대가 관례예요. 고르지 않은 블록은 고칠 수 없게 둬서, 길게 누르면 글 고르기가 아니라 블록 끌기가 돼요. Craft와 같아요. 체크는 누르면 짧은 스프링으로 튕기고 햅틱이 와요. 한글을 조합하는 중에는 글 칸의 글을 다시 쓰지 않아요. 다시 쓰면 조합이 끊겨요.

주소는 알아서 링크로

다 만들고 나서 하나가 더 보였어요. 링크는 저절로 누를 수 있어야 했어요. 메모 보기는 이미 https://…를 링크로 그렸는데, 블록 편집기는 그냥 적은 주소를 글로 읽고 있었어요.

블록 모델에서 고쳤어요. 글 토막을 읽을 때 주소 그대로, <주소>, www.…, 메일 주소도 링크로 읽어요. 다시 쓸 때는 글이 곧 주소인 링크를 [글](주소)로 바꾸지 않고 주소 그대로 써요. 다시 읽어서 같은 링크가 나오지 않을 때만 [글](주소)로 써요. 그래서 이것도 원칙 1을 지켜요. README.md 같은 파일 이름은 링크가 되지 않아요. 메모 보기와 같은 규칙이에요.

배운 것

  • 추천은 틀릴 수 있어요. B를 추천한 까닭(저장한 글과 보이는 글이 같다)은 맞았지만, A가 네이티브로 안 된다는 전제가 틀렸어요. 까닭을 지키는 장치(블록 모델)를 만들자 A의 좋은 점을 다 가질 수 있었어요.
  • 저장 모양은 편집기에 맡기지 않아요. 편집기는 바뀔 수 있어요. 이번에도 하루 만에 한 번 바뀌었어요. 저장하는 글은 Markdown 그대로 두고, 둘 사이는 우리 블록 모델이 정해요.
  • 고치지 않은 것은 건드리지 않아요. 사람과 Claude가 같은 글을 고치면, 글자 그대로 남는 것이 협업의 바닥이에요.
  • 인터랙션은 플랫폼 관례를 따라요. 쓰임새는 같게, 생김새와 조작은 그 플랫폼답게 두고, 다르게 둔 까닭은 적어 둬요.

웹과 iOS가 같은 시나리오로 정책을 시험하는 방식은 원칙 글의 6번에 있어요.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.