리포트 리뷰·주석·버전 관리 — 리뷰어 가이드

md-log는 AI 코딩 에이전트의 결과물을 사람이 실제로 리뷰할 수 있는 형태로 바꿔 줍니다. 거대한 diff를 훑는 대신, 에이전트가 남긴 마크다운 리포트(무엇을 · 왜 · 어떤 영향)를 읽고 승인 또는 반려하면 됩니다. 이 가이드는 리포트가 어디에 나타나는지, 어떤 기기에서 리뷰하는지, 스타일러스 주석이 어떻게 동작하는지, 불변 버전이 이력을 어떻게 보존하는지를 다룹니다.

리포트는 어디에 나타나나요

에이전트는 MCP를 통해 리포트를 파일 경로 단위로 md-log에 기록합니다(MCP 연결하기 참고). 리포트는 계층형 폴더 트리에 저장되므로, my-project/2026-07-14-auth-refactor.md 같은 경로가 리포트를 기대한 위치에 정확히 놓습니다. 폴더는 저장 시 mkdir -p처럼 자동 생성되어 에이전트가 미리 폴더를 만들 필요가 없고, 이미지나 첨부 자산도 본문과 함께 업로드됩니다.

저장된 리포트는 세 가지 방식으로 찾을 수 있습니다.

• 웹 앱 app.md-log.com이나 모바일 앱에서 폴더 트리를 탐색합니다.
• 리포트 전체를 대상으로 전문(full-text) 검색을 합니다.
• 자주 여는 리포트는 즐겨찾기로 표시해 둡니다.

전체 구성이 어떻게 맞물리는지는 개요에서 확인하세요.

읽고 리뷰하기 — 휴먼 인 더 루프

리뷰 모델은 의도적으로 단순합니다. 리뷰의 대상은 diff가 아니라 리포트입니다. 무엇이 왜 바뀌었는지에 대한 에이전트의 요약을 읽고, 승인할지 반려할지 사람이 판단합니다. md-log는 리뷰 뷰어이자 아카이브이며, 코드를 자동으로 리뷰하거나 사람의 판단을 대체하지 않습니다. 리뷰어는 어디까지나 사람입니다.

리포트는 웹·폰·태블릿에서 깔끔하게 렌더링되므로 리뷰는 비동기로 이루어집니다. 자리를 비운 사이 에이전트가 한 작업을 어디서든 검토할 수 있고, 새 팀원(그리고 새 에이전트)은 쌓인 리포트를 읽으며 온보딩 자료로 활용할 수 있습니다.

펜 지원 태블릿에서의 스타일러스 주석

펜을 지원하는 태블릿에서는 렌더링된 마크다운 위에 직접 필기로 주석을 달 수 있습니다.

• 안드로이드 태블릿의 S펜(네이티브).
• iOS(iPad)의 Apple Pencil.
• 스타일러스가 없는 기기에서는 손가락 필기 폴백.

펜 전용 UI는 펜 지원 기기에서만 표시되므로, 스타일러스가 없는 환경에서는 화면이 깔끔하게 유지됩니다. 획(stroke) 작성은 모바일·태블릿에서 이루어집니다.

주석은 버전에 고정됩니다

각 주석 레이어는 특정 문서 버전 하나에 속합니다. 문서가 바뀌어도 md-log는 필기를 자동으로 재정렬(re-anchor)하거나 이월하지 않습니다. 이렇게 해야 모든 주석이 그릴 당시 보던 정확한 버전에 충실하게 남습니다. 같은 표시를 새 버전에도 남기고 싶다면 명시적인 복사 동작으로 해당 버전에 그대로 복제하면 됩니다.

지금 보는 버전에 획이 그려졌던 텍스트 블록이 더 이상 없으면, 그 고아(orphaned) 획은 페이지 하단에 모입니다(클라이언트 측 처리). 관련 없는 내용 위에 떠 있지 않습니다.

웹 앱의 주석은 읽기 전용입니다

웹 앱은 주석을 렌더링하지만 작성하지는 않습니다. 웹에서는 필기가 주석을 단 버전에 고정된 SVG 오버레이로 표시되어, 노트북으로 보는 리뷰어도 무엇이 표시되었는지 정확히 볼 수 있습니다. 다만 새 획을 그리려면 모바일이나 태블릿 앱을 사용합니다. 이 구분 덕분에 웹 리뷰는 가볍고 정확하게 유지됩니다.

불변 버전과 이력

저장할 때마다 새로운 불변 버전이 만들어집니다. 기존 내용을 덮어쓰지 않으므로 프로젝트의 AI 협업 이력이 시간이 지날수록 쌓입니다.

• 모든 save/update/append에는 버전 이력에 노출되는 커밋 메시지가 함께 저장됩니다.
• 전체 이력을 조회하고 과거 버전을 열어 읽을 수 있습니다.
• 리포트를 이동하거나 이름을 바꿔도 이력과 주석이 보존됩니다.

두 편집이 충돌하면 md-log는 **낙관적 동시성(optimistic concurrency)**을 사용합니다. 충돌하는 쓰기는 서버의 현재 head와 함께 동기화 충돌을 반환하므로 실수로 덮어쓰이지 않습니다. 의도적으로 마지막 쓰기를 우선하려면 force 옵션을 쓸 수 있습니다.

오프라인 우선 모바일, 검색, 즐겨찾기

모바일 앱(iOS + 안드로이드, 폰·태블릿)은 오프라인 우선입니다. 로컬 데이터베이스를 유지하고 온라인 복귀 시 델타만 동기화하므로 이동 중에도 읽고 주석을 달 수 있습니다. 모든 화면에서 전문 검색과 즐겨찾기로 중요한 리포트에 빠르게 돌아갈 수 있습니다.

에이전트를 연결할 준비가 되셨나요? MCP 연결하기로 시작하거나 개요를 먼저 읽어 보세요.