MRDR에 대해 이야기하려면 먼저 MADR에 대해 알아야 하는데, 이들은 정말 멋집니다:
https://adr.github.io/madr/
프로젝트와 함께 MADR 문서를 구축하고 발전시키는 것은 핵심 아키텍처 결정을 포착하는 훌륭한 방법입니다. 여기에는 '왜' 그런지, 그리고 대안들까지 포함됩니다. 따라서 나중에 프로젝트 디자인에 무슨 일이 벌어지고 있는지 궁금해하며 되돌아볼 필요가 없어집니다. 또한 에이전트 컨텍스트를 위한 훌륭한 참고 자료가 되어 코드 생성 및 기타 세션 활동이 특정 결정에 의해 '고정'되도록 도울 수 있습니다.
하지만 MADR은 아키텍처 결정, 즉 디자인의 특정 지점만을 포착합니다. 또 다른, 더 일시적인 아티팩트가 계속해서 등장하는데요. 이것은 믿을 수 없을 만큼 유용하지만, 저는 이와 유사한 표준이 등장하는 것을 본 적이 없으며, 여러 에이전트, 하네스, 툴체인 전반에 걸쳐 암묵적으로 경쟁하는 몇 가지 관습들이 사용되고 있습니다. 그래서 고전적인 XKCD의 오류를 추가할 위험을 감수하고, 여기서 하나를 제안하려고 합니다.
저는 특별히 '계획(plans)' 또는 '로드맵(roadmaps)'에 대해 이야기하고 있습니다. 이것들은 에이전트 개발(많은 하네스가 자체적인 암묵적이거나 버전 관리되는 구조를 가지고 있음)과 인간의 아키텍팅 모두의 초석입니다. 즉, '디자인'과 '개발' 사이의 간극을 메워 아이디어를 가져와 실제로 코딩을 시작할 수 있게 해줍니다. 저는 이 아티팩트를
로드맵이나 계획에는 무엇이 들어가야 할까요? 만약 저희가 MADR의 유사체를 정의하고 싶거나(혹은 반복되는 패턴으로부터 자연스럽게 도출되도록 하고 싶다면), 그것은 무엇을 해야 할까요? 최상위 목적은 표준적인 계획 아티팩트 스킴을 제공하는 것이지만, 저는 MRDR 표준이 충족해야 하는 여섯 가지 구체적인 요구사항이 있다고 생각합니다(여기서 'shall'은 RFC 2119의 의미로 사용되었습니다):
-
MRDR은 인간과 에이전트 모두가 평문(plaintext)으로 접근할 수 있어야 합니다.
-
MRDR은 반복 및 검토(버전 관리, version-controlled) 대상이 되어야 합니다.
-
MRDR은 작업이 완료되면 압축되어야 하며, 나중에 '어떻게 여기까지 왔는지'에 대한 질문을 위해 접근 가능성을 유지해야 합니다.
-
MRDR은 작업을 체계적인 추상화(organized abstractions)로 분해해야 합니다.
-
MRDR은 수행되어야 할 구체적인 변경 사항의 특정 순서를 제공해야 합니다.
-
MRDR은 수정 없이 에이전트와 하니스(harnesses) 전반에서 사용 가능해야 합니다.
이 요구사항들은 사소해 보이지만 중요합니다. 다행스럽게도, 지난 1년간 제가 경험한 다양한 도구링(tooling) 경험들을 통해 정의하거나 활용하기 어렵지 않은 기존 접근 방식들의 '최소 스패닝 세트(minimal spanning set)'가 있음을 알게 되었습니다.
스킴 (Scheme)
이것은 제가 에이전트 엔지니어링 프로젝트에서 등장하고 유용하다고 느낀 스킴입니다. 물론 여러분의 경험에 따라 다를 수 있습니다.
-
각 파일은 고수준 기능(high-level feature)을 가지며, conventional commit tags 기반의 고유한 MRDR 식별자(예: FEAT-LOGGER)를 가집니다.
-
MRDR 파일은 짧고 고수준의 '의도(intent)'로 시작합니다 (이는 일반적으로 해당 작업 항목, 태스크 또는 이슈가 처음에 노력의 목적을 포착했던 제목입니다). 다른 유용한 최상위 콘텐츠에는 다음이 포함될 수 있습니다:
-
관련 MADR에 대한 참조(링크) (저는 보통 이들이 같은 저장소 내에 존재한다고 가정하지만, 단순히 Markdown 링크일 뿐이므로 엄격하게 필요하지 않습니다)
-
MRDR 파일이 포착하거나 다루려고 하지 않는 것에 대한 명시적인 목록
-
MRDR 파일에는 **고유한 번호가 매겨진 단계(unique numbered phases)**로 나누는 **하위 섹션(subsections)**이 있습니다.
-
각 단계는 목표와/또는 **테스트 가능한 '완료의 정의(Definition of Done, DOD)'**를 가집니다.
-
단계의 나머지 하위 섹션은 순서가 지정된 체크박스로 구성됩니다: 고유한 R.P.N 식별자를 가진 서브태스크이며, 각 서브태스크는 구현해야 할 특정 수정 사항을 설명합니다 (가능하다면 특정 파일을 참조).
-
R은 고유 MRDR 식별자입니다.
-
P는 문서 내의 단계 번호입니다.
-
N은 해당 단계 내의 서브태스크 번호입니다.
-
서브태스크는 강하게 순서가 지정되어 있고(strongly ordered), 단계는 약하게 순서가 지정되어 있습니다(weakly ordered). 즉, 서브태스크는 순서대로 처리해야 하지만, 단계는 가능한 경우 더 병렬적으로 처리될 수 있습니다.
-
작업 항목(Work items), 브랜치 및 머지 요청(merge requests)은 일반적으로 특정 MRDR에 범위가 지정되는 반면, 특정 커밋(commits)과 에이전트/하네스 세션(agent/harness sessions)은 개별 단계에 더 많이 범위가 지정될 가능성이 높습니다.
예시
현재 진행 중인 프로젝트의 로드맵을 위한 MRDR의 첫 번째 부분입니다.
# Roadmap: Shell (Ebiten IDE chrome)
Map-first desktop shell: window, panels, camera, and visual units. No live Sprites required.
...
이것은 각 단계를 완료하는 데 필요한 작업들을 명확하게 제시하고 열거하여, 에이전트 세션으로의 인계(handoff)가 매우 깔끔합니다("docs/roadmaps/FEAT-SHELL.md에 있는 MRDR을 기반으로 Phase 1부터 반복해 주세요..."). 또한 계획과 디자인 과정을 투명하게 만듭니다. MRDR을 작성한 후에는, 다른 에이전트들에게 내용을 구체화하거나(fleshing out), 적대적 검토(adversarial review) 등을 위해 인계하기에 매우 유용한 파일입니다. 활성 MADR은 버전 관리가 가능하고 세션 간에도 지속될 수 있으며, 미래의 (초안) MADR은 개발이 진행되는 동안 동시에 존재할 수 있습니다.
사후 처리 (After The Fact)
MADR과 MRDR 사이의 주요 차이점 중 하나는 로드맵(roadmap) 자체가 정의상 다소 일시적(ephemeral)이라는 것입니다. 구현 및 검증이 완료되어 병합 요청(merge request)이 들어가면, 더 이상 모든 변경 사항에 대한 초세밀한 기록이 필요하지 않으며, 크기가 큰 MRDR들이 쌓이면 프로젝트의 컨텍스트를 오염시킬 수 있습니다.
stay commited
대신, 저는 완료된 MRDR들을 정기적으로, 보통 주간 스프린트나 릴리스 주기(release cycle)의 일부로 "압축"합니다. 이는 이전에 완료된 MRDR들의 요약본을 집계하는 docs/roadmaps/historical.md와 같은 파일을 유지한다는 의미입니다: 각 항목의 짧고 높은 수준의 의도(intent), 그리고 개발된 단계들(phases)에 대한 글머리 목록 정도만 포함합니다. 예를 들면:
## FEAT-LOGGER
레벨 및 JSON 출력을 사용한 구조화 로깅, 다음을 포함:
- 핵심 API
...
핵심은 릴리스 노트나 프로젝트 추적 시스템이 이미 기록하고 있는 내용을 중복하지 않으면서도, 인간과 에이전트 모두에게 "어떻게 여기까지 오게 되었는지"에 답할 수 있을 만큼의 정보만 포함하는 것입니다.
원문 기사 작성 후 anthropic/sonnet-5.5를 사용하여 가벼운 편집 검토(editorial pass)를 수행했습니다
