Mistral, 에이전트로 40,000줄의 Fortran 마이그레이션 완료 — 문서화 정리가 먼저였다 (2026)

이 글은 도구가 아닌 사람에 대한 문장으로 시작합니다.

"레거시 과학 코드베이스는 수십 년에 걸쳐 축적되며, 원래 작성자가 떠나면 코드에 내재된 지식을 복구하기 어려워집니다."

보고서에서 언급했듯이, Fortran 77은 "이름에서 알 수 있듯이 1977년에 표준화되었으며, 이 언어로 작성된 코드는 모듈 없음, 네임스페이스 없음, 구조화된 타입 없음과 같은 제약 조건을 그대로 반영합니다. 상태는 프로그램 전체에서 공유되는 전역 메모리인 COMMON 블록에 존재합니다." 변수 이름은 최대 6자로 제한됩니다. 이름을 잘못 입력하면 에러가 발생하는 대신 자동으로 새로운 변수가 생성됩니다.

Mistral은 시작하기 전에 세 가지 질문을 던졌습니다. "마이그레이션된 코드베이스가 레거시 코드베이스와 수치적으로 일치하는지 증명하는 방법", "마이그레이션을 관리 가능한 단위로 나누는 방법", 그리고 "프로세스 속도를 높이기 위해 자율 에이전트를 가장 잘 활용하는 방법"입니다. 순서에 주목하십시오. 동등성 증명이 첫 번째였고, 에이전트 전략은 세 번째였습니다.

증명 메커니즘은 패리티 하네스(parity harness)였습니다. 팀은 "Fortran 코드베이스의 상태를 내보낼 수 있는 서브루틴", "체크포인트를 C++로 로드하는 테스트 프레임워크", 그리고 "에이전트가 이를 올바르게 사용하도록 유도하는 Skill.md 파일"을 추가했습니다. 그들의 평가는 다음과 같았습니다. "하네스의 이 부분을 먼저 구축한 것은 프로젝트에 있어 확실한 이득이 되는 투자였습니다. 긴 에이전트 실행을 더 안전하게 만들었고, 수치적 패리티는 코드가 성공적으로 마이그레이션되었음을 보여주는 검증하기 쉽고 설득력 있는 논거가 되기 때문입니다."

그 다음은 문서화 작업이었습니다. 프로젝트의 기존 문서는 "오래된 PDF와 Fortran 자체에 묻혀 있는 주석에 흩어져 있었습니다." Mistral은 "커스텀 파서로 코드베이스를 파싱하여" 호출자-피호출자 트리를 생성한 다음, "Vibe CLI를 사용하여 100개 이상의 에이전트를 띄워 이를 문서화"했습니다. 트리의 리프 노드부터 시작하여 위로 올라가며 각 노드마다 풀 리퀘스트(PR)를 생성했습니다. 그리고 그 결과를 다음과 같이 설명합니다.

"전체 노력의 가장 큰 부수적 성과 중 하나는 이 문서를 정리하여 코드 바로 옆으로 옮긴 것이었습니다."

마이그레이션 자체는 세 번의 시도 끝에 이루어졌습니다. 첫 번째 시도: "우리는 에이전트에게 완전한 자율성을 부여했습니다. Fortran 서브루틴당 하나의 에이전트를 배정하여 일주일 동안 각자의 함수를 독립적으로 C++로 번역하게 했습니다. 결과물은 작동은 했지만 코드 현대화라고 부를 수는 없었습니다. COMMON 블록은 일대일로 전역 구조체가 되었습니다. GOTO 기반의 제어 흐름은 루프나 조기 반환(early return)으로 재구조화되지 않고 그대로 유지되었습니다. 현대화된 코드라기보다는 C++ 구문으로 다시 타이핑한 Fortran처럼 보였습니다."

두 번째 시도에서는 에이전트에게 구조를 부여했습니다. "각 모듈에서 기획자(planner), 코더(coder), 테스터(tester), 코드 품질 검토자(reviewer) 에이전트가 함께 협업하도록" 했습니다. 품질은 향상되었지만, "결국 소스 코드의 복잡성이 에이전트의 발목을 잡았습니다. 에이전트들은 버그를 만나면 몇 가지 수정을 시도하다가 중단되었고, 개입할 수 있는 사람이 아무도 없었습니다."

결국 배포된 것은 절충안이었습니다. "사람이 코더, 테스터, 검토자 에이전트의 워크플로우를 운영하며 코드베이스를 모듈별로 마이그레이션하는 방식"이었습니다.

그리고 세 가지 교훈은 문자 그대로 다음과 같습니다. 첫째, 패리티 하네스를 먼저 구축하라. "수치적 일치는 모듈이 완료되었음을 증명하는 가장 저렴하고 설득력 있는 방법"이기 때문입니다. 둘째, "에이전트에 의존하기 전에 문서를 먼저 정리하라. 아무도 읽을 수 없는 코드는 마이그레이션할 수 없기 때문"입니다. 셋째, "이러한 규모에서는 사람의 검토 게이트가 있는 구조화된 워크플로우가 완전한 자율성이나 수동 작업 세션 모두를 압도한다"는 것입니다.

에이전트가 레거시 코드를 마이그레이션할 수 없다는 뜻이 아닙니다. 에이전트는 해냈으며, Mistral 스스로도 구문 번역은 "대체로 해결된 과제"라고 규정하고 있습니다. 어려운 부분은 아키텍처적인 것이었습니다. 절차형 코드에서 객체 지향 C++로 전환하는 것은 "확인할 수 있는 라인 대 라인 대응 관계가 없음을 의미하며, 이것이 마이그레이션 검증을 어렵게 만드는 요인"이었습니다.

모든 레거시 시스템에 일반화할 수 있는 것도 아닙니다. Mistral은 다음과 같이 직접 언급합니다. "Fortran 코드베이스는 독립적이고 실행 가능했기 때문에 유리한 시작 조건이었습니다. 외부 시스템에 의존하거나, 실행 가능한 기준선이 없거나, 어디에도 문서화되지 않은 물리학 법칙을 코딩한 마이그레이션은 이 글에서 다루지 않은 추가적인 과제를 안겨줄 것입니다."

마지막 구절을 천천히 읽어보십시오. 어디에도 문서화되지 않은 물리학 법칙. Mistral은 자신들의 방법론의 한계로 지식이 전혀 기록되지 않은 경우를 꼽았습니다. 잘못 기록된 것도 아니고, 오래된 것도 아닌, 아예 존재하지 않는 경우입니다.

이 글이 바꾸는 것은 우선순위입니다. 이 프로젝트의 결정적인 제약 조건은 에이전트의 능력이 아니었습니다. 코드 이면의 이유가 무엇이든 읽을 수 있는 형태로 존재하는지, 그리고 복구된 이유들이 결국 어디에 저장되는지였습니다.

이미 세 가지 해석이 돌고 있으며, 각각 중요한 부분을 놓치고 있습니다.

"레거시 코드베이스에 100개의 에이전트를 띄워라." 100개의 에이전트가 작동할 수 있었던 이유는 커스텀 파서가 이미 에이전트를 할당할 호출자-피호출자 트리를 생성했기 때문이며, Mistral이 절차형 코드의 특성인 "전체 프로그램을 단일 호출자-피호출자 트리로 그릴 수 있다"는 점을 활용할 수 있었기 때문입니다. 그러한 구조가 없다면 작업을 분산할 대상이 없습니다. 에이전트는 첫 번째 단계가 아니라 마지막 단계였습니다.

"문서화는 좋은 부수적 효과였다." Mistral은 이를 "부수적 성과(side-win)"라고 부르지만, 그들의 교훈 목록에서는 이를 전제 조건으로 꼽았습니다. 에이전트에 의존하기 전에 문서를 정리하라는 것입니다. 먼저 만들어야 하는 부수적 효과는 실질적으로는 세련되게 포장된 전제 조건입니다.

"에이전트는 유실된 지식을 재구성할 수 있다." 에이전트는 여전히 존재했던 PDF와 코드 주석으로부터 문서를 재구성했습니다. 아무것도 존재하지 않는 곳에 대해 Mistral은 범위 외로 분류했습니다. 이는 다른 두 벤더가 자신들의 언어로 정의한 경계와 동일합니다. Cline은 자사의 Memory Bank를 "Cline을 상태가 없는(stateless) 어시스턴트에서 지속적인 개발 파트너로 전환하는 문서화 방법론"으로 설명합니다. 즉, 도구가 도출해내는 것이 아니라 사람이 수행하는 방법론이라는 뜻입니다. OpenHands는 이 둘을 명확히 구분합니다. "리포지토리에서 작업하는 모든 에이전트에게 전달할 지침은 AGENTS.md에 보관하고, 메모리는 에이전트가 스스로 학습한 내용을 위한 것입니다." 세 개의 독립적인 벤더가 작성된 의도(written intent)와 도출된 지식(derived knowledge)은 서로 다른 성격의 것임을 세 가지 방식으로 말하고 있습니다.

이는 그들 중 누구를 비판하려는 것이 아닙니다. 문제의 본질이 그러하기 때문입니다.

이미 다루었던 인접 사례를 원하신다면, "사람이 떠날 때 지식도 함께 떠난다"의 일반적인 버전은 사람이 떠날 때 AI 컨텍스트는 어떻게 되는가에서, 기존 문서를 에이전트가 실제로 참조할 수 있는 형태로 변환하는 메커니즘은 프로젝트 문서를 AI 메모리로 전환하기에서 확인할 수 있습니다. 이 글은 두 가지보다 더 좁은 범위인 마이그레이션이 생성하는 기록과 그 기록이 마이그레이션 이후에도 살아남는지에 대해 다룹니다.

Mistral의 문서화 작업은 코드와 PDF에 여전히 남아 있던 내용을 복구했습니다. 복구할 수 없었던 범주(그리고 스스로 한계라고 명시한 범주)야말로 미리 계획할 가치가 있는 범주입니다. 시작하기 전에 이 둘을 구분하는 방법은 다음과 같습니다.

1단계: 파서가 재생성할 수 있는지 여부에 따라 지식 분류하기

하나의 모듈을 선택하고 새로운 엔지니어에게 필요한 모든 것을 나열하십시오. 그런 다음 리포지토리만 읽는 도구가 각 항목을 생성할 수 있는지 여부를 표시하십시오.

콜 그래프(call graph), 타입 시그니처, 어떤 함수가 어떤 함수를 호출하는지, 서브루틴이 기계적으로 무엇을 하는지 등은 재생성 가능합니다. Mistral은 대규모 환경에서 이를 증명했습니다. 커스텀 파서와 에이전트가 중앙 집중식 문서가 없는 코드베이스에서 정확히 이러한 종류의 지식을 재구축했습니다.

이제 다른 쪽 열을 보겠습니다. 왜 명백한 대안 대신 이 솔버(solver)를 선택했는가. 저류층 엔지니어들이 이 두 루프 중 어느 것이 비트 단위까지 동일하게 유지되어야 한다고 말했는가. 2019년에 이전 포팅 시도가 중단된 이유는 무엇인가. "클라이언트의 저류층 엔지니어들이 지적한 중간 지점" 중 어느 것이 중요하고 어느 것이 부수적인가 — Mistral은 이러한 체크포인트가 코드가 아닌 엔지니어들로부터 나왔다고 언급했습니다. 리포지토리의 그 어떤 것도 이를 말해주지 않습니다.

두 번째 열이 여러분의 진짜 자산입니다. 첫 번째 열의 모든 것은 빌드 아티팩트(build artifact)에 불과합니다.

2단계: 이유가 언급되는 그 순간에 포착하기

두 번째 열의 이유들은 작업 전이 아니라 작업 중에 드러납니다. 검토 주석, 도메인 전문가와의 통화, 에이전트가 멈췄을 때 누군가 뱉은 문장 속에서 나타납니다. Mistral의 두 번째 시도에서 이 점이 가장 잘 드러납니다. 에이전트들은 "버그를 만나면 몇 가지 수정을 시도하다가 중단되었고, 개입할 수 있는 사람이 아무도 없었습니다." 중단을 해결하는 개입은 정확히 두 번째 열의 사실이며, 이는 커밋되는 것이 아니라 구두로 전달됩니다.

따라서 그 순간에 포착하십시오. 사람이 에이전트의 중단을 해결할 때, 에이전트가 내린 결론은 무엇이었고, 실제 사실은 무엇이었으며, 그 이유는 무엇인지 한 줄로 기록하십시오. 도메인 전문가가 디자인에 거부권(veto)을 행사할 때, 일주일 후에 닫힐 풀 리퀘스트 스레드가 아니라 해당 디자인 바로 옆에 거부권과 그 이유를 기록하십시오.

이는 벤더 자체의 설명이 덜 신뢰할 수 있게 될 때 기록해야 하는 것에서 설명한 것과 동일한 원칙입니다. 영구적인 아티팩트는 의사결정과 그 정당성이지, 그것을 도출해낸 대화 기록이 아닙니다.

3단계: 프로젝트 외부의 공간에 기록 보관하기

Mistral의 문서는 "코드 바로 옆"으로 이동했으며, 이는 올바른 첫 단계입니다. 원본 리포지토리에 풀 리퀘스트를 보내고 크론(cron) 일정에 따라 에이전트가 검토하도록 하는 것입니다. 리포지토리 파일은 영구적이고 버전이 관리되며 이동이 가능합니다.

하지만 마이그레이션은 수명이 다른 두 가지 종류의 기록을 생성합니다. 모듈 문서는 코드를 설명하므로 코드와 함께 보관되며, 코드가 다시 교체되면 함께 사라집니다. 반면 의사결정(왜 이 아키텍처를 선택했는지, 어떤 제약 조건이 타협 불가능했는지, 도메인 전문가가 무엇을 배제했는지)은 Fortran과 C++ 모두보다 오래 살아남습니다. 이는 다음 프로젝트가 던질 질문에 대한 답입니다.

이러한 정보는 단일 리포지토리 내부의 디렉토리가 아닌 다른 곳에 보관되어야 합니다. 스킬 파일은 절차를 담기에 좋은 수단이며, 이것이 Mistral이 "에이전트가 이를 올바르게 사용하도록 유도하기 위해 Skill.md 파일을 작성한" 이유입니다. 하지만 절차는 이유가 아닙니다. 이 점은 에이전트 스킬이 메모리가 아닌 이유에서 자세히 설명한 바 있습니다. 그리고 지침 파일은 고유한 범위를 가집니다. 코딩 에이전트가 실제로 읽는 것에서 확인했듯이, 에이전트는 여러분의 문서 트리가 아니라 자신들의 지침 파일을 읽습니다.

공유 의사결정 레이어는 특정 리포지토리에 종속되지 않는 요소입니다. MemoryLake는 두 번째 열의 사실들(결정 사항, 제약 조건, 폐기된 접근 방식과 그 이유)을 보관하여 마이그레이션을 수행하는 모든 에이전트가 동일한 세트를 읽을 수 있도록 하고, 프로젝트가 종료된 후에도 해당 세트가 유지되도록 합니다. 설정은 세 단계로 진행됩니다. 여기에서 시작하세요.

1단계: API 키 생성하기

마이그레이션을 위한 워크스페이스를 생성하고 API 키를 발급받습니다. 단일 리포지토리가 아닌 전체 프로그램으로 워크스페이스 범위를 지정하십시오. 소스 트리와 타겟 트리는 서로 다른 두 개의 리포지토리이며, 의사결정은 두 곳 모두에 적용되기 때문입니다.

2단계: 첫 번째 메모리 업로드하기

개입 사례부터 시작하십시오. 사람이 에이전트의 중단을 해결할 때마다, 그 대화에는 코드가 명시하지 않은 사실이 포함되어 있습니다. 그 다음으로 도메인 전문가의 결정 사항을 추가하고, 체크포인트 목록과 각 체크포인트가 선택된 이유를 추가하십시오. PDF, 회의록, 검토 스레드는 마크다운으로 먼저 변환할 필요 없이 직접 업로드할 수 있습니다.

3단계: AI 및 에이전트 연결하기

실제로 작업을 수행하는 에이전트(코더, 테스터, 검토자)를 연결합니다. 각 에이전트는 동일한 의사결정 세트를 읽으므로, 검토자 에이전트는 코더가 보지 못한 제약 조건에 위배되는 변경 사항을 감지해낼 수 있습니다. 이는 사람이 개입하는 구조화된 워크플로우가 수동으로 해결하던 공백입니다. 공유 레이어는 사람이 개입하기 전에 이 공백의 일부를 미리 메워줍니다.

첫 번째 스프린트에서 단 세 사람의 머릿속에만 존재하는 지식이 생성되는 일이 없어집니다. 모듈이 새로운 에이전트 워크플로우에 전달될 때, 제약 조건도 함께 전달됩니다.

두 번째 시도의 실패 모드를 해결하는 비용이 저렴해집니다. 에이전트들은 수치적 규칙, 암묵적 계약, 물리학적 가정 등 동일한 종류의 문제에서 반복적으로 멈춥니다. 첫 번째 멈춤에는 사람의 개입 비용이 들지만, 동일한 사실로 인한 후속 멈춤은 비용이 들지 않습니다. 이제 그 사실을 읽을 수 있기 때문입니다.

그리고 기록은 프로젝트보다 오래 살아남습니다. Mistral의 첫 번째 스프린트는 300,000줄 중 40,000줄을 다루었으므로, 앞으로 아마도 다른 사람들과 함께 진행할 다섯 번의 스프린트가 더 남아 있음을 의미합니다. 여섯 번째 스프린트가 기존의 이유들을 바탕으로 시작할지, 아니면 이를 처음부터 다시 찾아내야 할지는 지금 그 기록을 어디에 두느냐에 따라 결정됩니다.

마이그레이션 코드를 작성하기 전에 패리티 하네스를 먼저 작성하십시오. Mistral의 가장 강력한 주장은 수치적 일치가 "모듈이 완료되었음을 증명하는 가장 저렴하고 설득력 있는 방법"이라는 것입니다. 하네스는 또한 "올바름"이 무엇을 의미하는지에 대한 서면 기록이기도 하며, 프로젝트가 생성할 가장 재사용성이 높은 문서입니다.

재생성 가능한 지식과 재생성 불가능한 지식을 서로 다른 곳에 보관하십시오. 이 둘을 섞으면 재생성할 때마다 재생성할 수 없는 부분이 덮어써질 위험이 있습니다. 이는 대규모 증명 작업 동안 에이전트가 이미 사실인 내용을 기록한 방법에서 설명한 것과 동일한 함정입니다. 영구적인 가치는 실행 결과가 아니라 작성된 기록에 있었습니다.

의사결정뿐만 아니라 거부권(veto)도 기록하십시오. "우리는 PetSc를 선택했다"는 "이러한 이유로 두 가지 대안을 배제한 후 PetSc를 선택했다"보다 힘이 약합니다. 배제된 옵션들이야말로 다음 에이전트가 이를 다시 제안하는 것을 막아주는 역할을 합니다.

도메인 사실에 날짜를 기입하십시오. 9월에 설정된 저류층 엔지니어의 제약 조건은 3월에 대체될 수 있습니다. 날짜가 없는 제약 조건은 영원히 준수되거나 완전히 무시됩니다.

사람의 검토 게이트를 단순한 통제 수단이 아닌 정보원으로 취급하십시오. Mistral의 세 번째 교훈은 검토 게이트가 완전한 자율성을 압도한다는 것입니다. 각 게이트는 또한 사람이 리포지토리에 없는 내용을 언급하는 순간이기도 하므로, 그 순간을 포착하여 기록하십시오.

Mistral의 보고서는 에이전트가 레거시 코드를 마이그레이션하는 이야기로 읽힐 것이며, 어느 정도는 사실입니다. 하지만 그들이 제시한 세 가지 교훈은 에이전트 전략보다 하네스와 문서화 작업을 우선순위에 두고 있으며, 자신들의 방법론에 대해 그어둔 경계는 "어디에도 문서화되지 않은 물리학 법칙을 코딩한" 코드입니다.

에이전트는 기계적인 작업을 저렴하게 만들었습니다. 하지만 문서화되지 않은 의도까지 복구해 주지는 못했으며, Mistral 역시 그렇지 않다고 주장합니다. 마이그레이션은 끝날 것입니다. C++ 역시 결국에는 레거시가 될 것입니다. 앞으로 이어지는 것은 누군가가 기록하기로 선택한 부분과 그것을 어디에 두었는가입니다.