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

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 연결하기로 시작하거나 개요를 먼저 읽어 보세요.