에이전트의 작업은 Markdown 파일로 돌아옵니다.

에이전트를 만드는 사람들이 하는 말

쓰인 그대로 인용하고, 우리의 해석은 그 뒤에 적습니다.

• Anthropic의 “Building Effective Agents”(Erik S., Barry Zhang, 2024년 12월)는 에이전트를 만드는 세 가지 핵심 원칙을 제시합니다. 그중 하나는 “에이전트의 계획 단계를 명시적으로 보여 줌으로써 투명성을 우선하라”입니다. 이 글은 에이전트를 만드는 사람을 위해 쓰였습니다. 여러분 쪽에서 보면 그 투명성은 결국 여러분이 읽게 되는 계획입니다.
• 같은 글에서: “그러면 에이전트는 체크포인트에서 또는 장애물을 만났을 때 사람의 피드백을 받기 위해 멈출 수 있다.” 동사에 주목하세요. 할 수 있다입니다.
• Chip Huyen은 “Agents”(2025년 1월)에서 계획을 실행과 분리해야 하는 이유를 이렇게 설명합니다. “감독이 없으면 에이전트는 그 단계들을 몇 시간 동안 실행하며 API 호출에 시간과 돈을 낭비할 수 있고, 여러분은 그제야 그것이 아무 데도 가지 못하고 있음을 깨닫는다.” 또 “에이전트가 작업을 끝내지 않았는데도 끝냈다고 확신하는” 실패도 설명합니다. 50명을 호텔 객실 30개에 배정하라고 하면 40명만 배정하고 다 했다고 우깁니다.
• Andrew Ng은 The Batch(2024년 4월)에서 계획 설계 패턴에 대해 이렇게 말합니다. “한편으로 계획은 매우 강력한 능력이지만, 다른 한편으로는 결과를 덜 예측 가능하게 만든다.” 이는 예측 가능성에 관한 지적이지 사람의 검토를 요구하는 말이 아니며, 그는 계획 능력이 빠르게 나아질 것으로 봅니다.

그들의 말이 아니라 우리의 추론입니다. 에이전트가 계획을 펼쳐 보이고 체크포인트에서 멈춘다면, 누군가는 그 체크포인트에서 계획을 읽어야 하고, 대개 그 사람은 여러분입니다. 에이전트가 끝나지 않았는데도 끝났다고 생각할 수 있다면, ‘완료’ 보고에도 읽는 사람이 필요합니다. 이 저자들 중 누구도 MarsDawn을 언급하거나 MarsDawn 또는 다른 Markdown 도구를 추천하지 않습니다.

보기보다 읽기 어려운 이유

파일은 길고, 중요한 부분은 위쪽에 있는 경우가 드뭅니다. 소스로는 따라가기 어려운 Mermaid 다이어그램과 수식이 들어 있습니다. 여러분이 절반쯤 읽는 동안에도 에이전트가 파일을 고쳐 쓰고 있을 수 있습니다. 여러 파일 중 하나인 경우가 많고, 때로는 여러 브랜치나 워크트리에 흩어져 있습니다. 그리고 문제를 발견했을 때 “캐시 부분이 좀 이상해”라고 하면 에이전트는 짐작할 수밖에 없지만, “docs/plan.md:42에서 백필이 끝나기 전에 이전 테이블을 삭제함”이라고 하면 그렇지 않습니다.

MarsDawn이 돕는 부분

• 긴 파일: 사이드바의 개요 탭(⌃⌘S)에 제목이 나열됩니다. 하나를 클릭하면 두 패널이 모두 그곳으로 이동합니다.
• 다이어그램과 수식: Mermaid와 KaTeX가 소스 옆 미리보기에 그려지고(⌘2), 두 패널이 함께 스크롤됩니다.
• 읽는 동안 고쳐 쓰일 때: 에이전트가 파일을 고쳐 쓰면 MarsDawn이 다시 불러오고 읽던 위치를 유지합니다. 여러분이 저장하지 않은 편집이 없는 한 그렇습니다.
• 여러 파일: 파일 ▸ 폴더 열기…(⇧⌘O)로 에이전트의 폴더를 여세요. 새 파일은 약 1초 안에 파일 탭에 나타나고, git 체크아웃이라면 헤더에 브랜치나 워크트리 이름이 표시됩니다.
• 정확한 피드백: 편집 ▸ 참조 복사(⌥⌘C)는 현재 위치를 docs/plan.md:42 형식으로 복사합니다. AI용으로 복사(⌃⌥⌘C)는 그 아래에 선택한 텍스트를 덧붙입니다. 어느 쪽이든 에이전트와의 채팅에 붙여 넣으세요.

반복 과정에 쓸 것이 두 가지 더 있습니다. 에이전트는 marsdawn open plan.md:42를 실행해 여러분이 가장 먼저 봤으면 하는 42번째 줄에서 MarsDawn으로 파일을 열 수 있고, 검토를 마친 파일은 앱에서 또는 무료 marsdawn export 명령으로 PDF로 내보낼 수 있습니다.

MarsDawn 안에는 AI 모델이 없습니다. 계획을 요약하거나, 평가하거나, 무엇이 틀렸는지 알려 주지 않습니다. 읽는 것은 여러분이고, MarsDawn은 길고 계속 바뀌는 파일을 읽기 좋게 유지하며 정확한 줄을 가리킬 수 있게 해 줍니다.

에이전트의 계획을 5분 만에 검토하기

어떤 편집기에서든 쓸 수 있는 방법입니다.

1. 제목만 읽으세요. 개요가 요청한 내용과 맞나요? 빠진 섹션은 대개 빠진 작업을 뜻합니다.
2. 무언가가 완료되었다, 통과했다, 확인했다고 말하는 곳을 모두 찾아 하나는 직접 확인하세요. 파일을 열고, 테스트를 실행하고, 행을 세어 보세요.
3. 되돌릴 수 없는 단계를 찾으세요. 데이터 삭제, 마이그레이션, 강제 푸시, 무언가를 보내거나 결제하거나 게시하는 모든 것. 이런 단계는 여러분의 명시적인 승인을 기다려야 합니다.
4. 다이어그램을 렌더링된 상태로 읽고, 화살표 하나하나를 본문과 대조하세요.
5. 계획이 건드리는 파일과 시스템을 나열하세요. 요청하지 않은 것이 있으면 실행되기 전에 물어보세요.
6. 피드백은 위치, 문제, 해결책 순서로 쓰세요. “plan.md:88: 백필이 삭제 다음에 실행됨. 4단계와 5단계를 바꿀 것.” 한 줄에 문제 하나씩.

시간이 없다면 2단계만 하세요. 끝났다고 착각하는 에이전트는 거기서 잡힙니다. 실제 예시를 곁들인 긴 버전: 에이전트의 계획을 5분 만에 검토하기.

사용해 보기

MarsDawn은 Mac App Store에 있습니다. 무료 marsdawn 명령줄 도구도 있습니다.

brew install redtear1115/tap/marsdawn

앱 없이 Markdown을 PDF로 내보내며, marsdawn open을 쓰면 에이전트가 여러분 대신 MarsDawn에서 파일을 열 수 있습니다.

명령줄 · 에이전트를 위한 marsdawn · 구입 전에 알아 두세요: MarsDawn이 하지 않는 일

다음

• AI의 결과물을 왜 읽어야 하는지 짧게: AI의 결과물에 여전히 사람 독자가 필요한 이유.
• 검토하는 동안 에이전트의 컨텍스트를 작게 유지하기: 토큰을 아끼는 검토.
• 에이전트가 애초에 계획을 펼쳐 보이는 이유: Anthropic은 에이전트가 투명해야 한다고 말합니다. 그럼 펼쳐 놓은 것은 누가 읽을까요?
• 위 체크리스트를 예시와 함께 단계별로: 에이전트의 계획을 5분 만에 검토하기.
• 여러 종류의 에이전트가 건네는 문서: 네 가지 에이전트 설계 패턴과 각각이 건네는 문서.

출처

• Erik S., Barry Zhang, “Building Effective Agents”, Anthropic, 2024년 12월 19일: https://www.anthropic.com/engineering/building-effective-agents (2026-09-26 기준 온라인 버전에서 인용. 현재 이 글에는 설명된 도구 중 상당수가 2024년 12월 이후 바뀌었다는 안내가 붙어 있습니다.)
• Chip Huyen, “Agents”, 2025년 1월 7일: https://huyenchip.com/2025/01/07/agents.html
• Andrew Ng, “Agentic Design Patterns Part 4, Planning”, The Batch, 2024년 4월 10일: https://www.deeplearning.ai/the-batch/agentic-design-patterns-part-4-planning/