Millwright-Inspector: AI 코딩 에이전트를 활용한 소프트웨어 개발 방법론

요약 (TL;DR). 두 가지 역할이 존재합니다. AI 에이전트 (Millwright, 정비공)가 워크플로(workflow) 내의 모든 산출물(artifact)을 초안 작성합니다. 인간 (Inspector, 검사관)은 각 산출물을 검토합니다. 각 산출물은 다음 단계의 입력값으로도 사용되는 Markdown 파일입니다. 워크플로는 검사관이 승인할 때만 앞으로 진행됩니다. 이 패턴을 컨텍스트 산출물 릴레이 (Context Artifact Relay)라고 부릅니다.

더 자세한 정보는 웹사이트를 방문하세요: millwright-inspector.dev

Millwright-Inspector란 무엇인가

몇 년 전만 해도 AI가 코드 한 줄을 완성하는 것이 기술의 정점처럼 느껴졌습니다. 하지만 오늘날 동일한 도구들은 사양(spec)을 받아 구현 계획을 세우고, 코드를 작성하며, 거의 감독 없이 풀 리퀘스트(pull request)를 올릴 수 있습니다. 대부분의 팀이 소프트웨어 개발을 구성하는 방식(분석, 설계, 구현, 테스트, 검토)은 실제로 변하지 않았습니다. 변한 것은 타이핑을 누가 하느냐입니다.

Millwright-Inspector는 그 과정에서 발생하는 간극을 메우기 위한 방법론입니다. 이는 여러분이 이미 작업하고 있는 단계들을 대체하지 않습니다. 대신 두 가지 요소에 대해 약간의 구조를 추가합니다: 에이전트의 작업물이 어디에 존재하는지, 그리고 그 작업물이 한 단계에서 다음 단계로 어떻게 이동하는지입니다. 각 단계는 파일을 생성합니다. 인간은 그 파일을 검토합니다. 파일이 승인되면, 그것은 다음 단계의 입력값이 됩니다. 그 외의 것은 앞으로 나아가지 않습니다.

Millwright-Inspector는 AI 에이전트가 소프트웨어 워크플로의 각 산출물을 생성하고, 인간이 이를 검토하며, 그 승인이 다음 단계를 진행시키는 방법론입니다.

이 문장이 전체 메커니즘을 포괄합니다. 이 포스트의 나머지 내용은 각 구성 요소가 어떻게 생겼는지, 그리고 왜 그런 형태를 갖추고 있는지에 대한 설명입니다.

행위자와 그들의 역할

이 방법론은 두 가지 역할을 정의합니다. 이름이 처음에는 다소 생소하게 들릴 수 있는데, 이는 의도된 것입니다.

**Millwright (밀라이트)**는 AI 에이전트입니다. Claude Code, 에이전트 모드의 Cursor, Aider, Codex CLI 등 여러분의 팀이 이미 사용하고 있는 무엇이든 될 수 있습니다. 이 이름은 오래된 공장 현장에서 유래되었습니다. 밀라이트(millwright)는 공장의 생산물을 만들어내는 기계들을 설치, 유지 관리 및 수리하는 사람을 말합니다. 소프트웨어에서 코드베이스(codebase)는 공장이며, 각 기능(feature)은 조립되는 기계입니다. 밀wright는 결과물(artifacts) 생성, 에이전트 소환 및 결과물을 그들의 컨텍스트(context)에 주입하는 것, 그리고 검사자(inspector)가 승인했을 때 워크플로(workflow)를 진행시키는 것을 책임집니다. 기본적으로 기계가 작동하도록 만드는 책임을 집니다.

**Inspector (검사자)**는 인간, 즉 당신입니다. 검사자는 원재료(전사 데이터, 노트, 디자인 핸드오프, 범위 결정 사항 등)를 공급하고, 밀라이트가 생성하는 모든 결과물을 검토하며, 워크플로가 다음 단계로 넘어갈 수 있을 때 신호를 보냅니다. 검사자는 프로덕션 결과물을 직접 작성하지 않습니다. 검사자의 권한은 승인, 프롬프트(prompt)

컨텍스트 아티팩트 (Context artifact)는 가장 중요한 요소 중 하나이자 동시에 가장 단순한 요소 중 하나입니다. 이는 워크플로 (workflow)가 특정 단계에서 생성하는 Markdown 파일입니다. 이것이 유용한 이유는 두 가지 작업을 동시에 수행하기 때문입니다.

첫 번째 작업은 인간의 검토 (human review)입니다. 검사자 (inspector)는 파일을 열어 읽고, 그것이 충분히 괜찮은지 결정합니다.

두 번째 작업은 다음 에이전트 (agent)에게 정보를 제공하는 것입니다. 다음 단계가 실행될 때, 에이전트는 동일한 파일을 읽어 자신의 작업이 무엇인지 파악합니다. 설계 (design) 단계에서 검사자가 승인한 requirements.md는 구현 (implementation) 단계에서 구현자 (implementer)가 읽는 것과 동일한 requirements.md입니다. 리뷰어 (reviewer)가 훑어보는 UML 다이어그램은 나중에 리팩터링 (refactor) 에이전트가 시스템이 이전에 어떤 모습이었는지 이해하기 위해 읽는 다이어그램입니다.

전형적인 워크플로는 다음과 같은 몇 가지 아티팩트를 생성하며 마무리됩니다:

• 무엇을 구축할지에 대한 requirements.md.
• 어떻게 검증할지에 대한 manual-test-plan.md.
• 시퀀스 및 컴포넌트 다이어그램 (.puml 파일).
• 코드 리뷰 (code review) 결과가 담긴 inspector-review.md.
• 다음 사이클이 읽을 change-summary.md.

에이전트를 위한 두 번째 형식과 인간을 위한 첫 번째 형식이 따로 존재하는 것이 아닙니다. 그들은 동일한 파일을 읽습니다.

컨텍스트 아티팩트 릴레이 (The Context Artifact Relay)

컨텍스트 아티팩트 릴레이. 밀라이트 (millwright)가 초안을 작성하고, 검사자가 승인하며, 아티팩트가 이동합니다.

이 지점에서 이 방법론의 이름이 유래되었습니다.

잠시 전기 릴레이 (electrical relay)를 생각해 보십시오. 이는 기본적으로 열려 있는 스위치입니다. 아무것도 통과하지 못합니다. 별도의 작은 제어 신호가 코일 (coil)에 에너지를 공급하면 스위치가 닫히고, 마침내 메인 회로에 전류가 흐를 수 있게 됩니다. 신호가 없다면 릴레이는 그저 그 자리에 가만히 있을 뿐입니다.

워크플로(Workflow)의 매 단계마다 millwright는 산출물(Artifact)을 초안 작성합니다. 그것은 requirements.md일 수도 있고, 일련의 다이어그램(Diagrams)일 수도 있으며, 리뷰 결과(Review-findings) 파일일 수도 있습니다. 산출물은 디스크에 기록되고 나면... 아무 일도 일어나지 않습니다. 다음 단계가 자동으로 실행되지 않습니다. 산출물은 그곳에 머물며 기다립니다.

inspector의 승인이 제어 신호(Control signal)가 됩니다. 그들이 승인하면 릴레이(Relay)가 닫히고, 산출물은 다음에 실행될 프로세스로 이동합니다.

millwright는 페이로드(Payload)를 채우고, inspector는 스위치를 던집니다.

이런 방식으로 작업을 조직화하면 몇 가지 유용한 이점이 생깁니다.

첫째, 내구성이 있습니다 (Durable). 산출물은 디스크에 저장된 Markdown 파일이므로, 세션에 어떤 일이 발생하더라도 살아남습니다. AI 에이전트의 컨텍스트 윈도우(Context window)가 초기화되거나, 사이클 중간에 모델을 교체하거나, 금요일에 워크플로를 멈췄다가 월요일에 다시 돌아오더라도 파일은 여전히 그 자리에 있습니다. 워크플로는 기다립니다.

둘째, 계층적입니다 (Layered). 한 단계에서 다음 단계로 흐르는 것은 워크플로가 축적한 모든 것을 통째로 쏟아붓는 것이 아닙니다. 다음 단계에 실제로 필요한 것만을 담은 압축된 브리핑(Briefing)입니다. 방대한 배경 지식을 가지고 있으면서도 각 단계의 입력값은 작게 유지할 수 있습니다.

셋째, 연쇄 반응이 일어납니다 (Cascades). 하나의 승인이 여러 자동화된 단계들을 사슬처럼 연결할 수 있습니다. 설계를 승인하면 요구사항 재생성, 다이어그램 업데이트, 구현 계획 수립이 한 번에 트리거(Trigger)될 수 있습니다.

이를 구체화하기 위해 실제 사이클의 서로 다른 부분에서 가져온 두 개의 릴레이를 살펴보겠습니다.

요구사항 파일 생성 중. 컨텍스트(Context): 승인된 TODO 리스트. 출력(Output): 승인된 requirements.md.

millwright는 선택된 TODO 항목들을 읽고, requirements.md를 작성한 뒤 멈춥니다. inspector는 초안을 열어 수정을 요청하거나(또는 요청하지 않거나), 승인합니다. 승인된 파일은 다음에 오는 어떤 릴레이의 입력값이 됩니다.

풀 리퀘스트(Pull Request)를 검토하는 중. 컨텍스트(Context): 코드베이스, 프로젝트의 교훈(lessons-learned), 워크플로우의 UML 다이어그램. 출력: 승인된 결과 파일(findings file).

형태는 같지만 내용은 매우 다릅니다. Millwright는 프로젝트에 축적된 교훈 및 기존 UML 다이어그램과 대조하여 코드베이스를 읽고, 그 결과(findings)를 구조화된 inspector-review.md 파일로 작성합니다. Inspector는 이를 검토하여 유지할 가치가 있는 것은 남기고, 나머지는 보류하거나 승인합니다. 이 결과 파일은 다음 루프(수정 및 재검토 루프)가 읽게 되는 데이터가 됩니다.

컨텍스트 아티팩트 저장소 (The Context Artifact Repository)

아티팩트(Artifacts)는 어딘가에 저장되어야 합니다. Millwright-Inspector에서 아티팩트는 코드베이스와 나란히 위치하는 세 개의 폴더에 저장됩니다.

폴더	포함 내용
Journal	시작점이 된 가공되지 않은 입력값들. 회의 녹취록, 노트, 사양서(specs), PDF, Figma로부터 전달된 디자인 핸드오프(design hand-offs).
...

이것이 저장소의 전부입니다. 세 개의 폴더와 그 안의 순수한 마크다운(Markdown) 파일들로 구성됩니다.

짚고 넘어갈 만한 두 가지 결과가 있습니다. 첫 번째는 워크플로우가 실시간 채팅 세션에 의존하지 않게 된다는 점입니다. 모든 중요한 정보가 디스크에 저장되어 있으므로, 컨텍스트 윈도우 압축(context-window compaction), 모델 전환(model switches), 작업 세션 사이의 긴 휴지기 등이 워크플로우를 중단시키는 문제가 되지 않습니다. 금요일에 작업을 중단하고 2주 후에 다시 시작하더라도, 폴더를 열기만 하면 상태가 그대로 남아 있습니다.

두 번째는 코드베이스가 네 번째 아티팩트가 된다는 점입니다. 이전에는 개발자만이 코드베이스를 실제로 읽었습니다. 하지만 에이전트(Agents)가 등장하면서, 에이전트를 사용하는 사람이라면 누구나 코드에 대해 근거 있는(grounded) 질문을 던질 수 있습니다. 그들에게는 읽기 권한만 있으면 됩니다.

나란히 비교하기

익숙한 단계들은 그대로 유지됩니다. Millwright-Inspector는 각 단계에 릴레이(relay)와 공유 저장소(shared repository)를 추가합니다.

대부분의 팀이 업무를 구성하는 방식(분석, 설계, 구현, 테스트)은 변하지 않습니다. Millwright-Inspector는 각 단계에 릴레이(relay)를 추가하고, 위 섹션에서 설명한 검사 및 승인(inspect-and-approve) 패턴을 더하며, 릴레이들이 쓰고 읽을 수 있는 공유 저장소(shared repository)를 추가합니다. 그게 전부입니다. 단계는 동일합니다. 그 주변의 구조가 새로워진 것입니다.

이것이 효력을 발휘하기 시작하는 지점

위의 형태는 단일 기능(single feature)을 예측 가능하게 유지해주며, 그 자체로도 훌륭합니다. 하지만 팀이 이를 사용하는 순간, 몇 가지 다른 이점들이 부수적으로 따라옵니다.

한 명의 검사자, 동시에 진행 중인 여러 워크플로(workflows). 각 릴레이(relay)가 산출물(artifact)을 디스크에 보관하고 대기하기 때문에, 검사자(inspector)는 워크플로를 머릿속에 계속 담아두고 있을 필요가 없습니다. 오전 10시에 워크플로 A의 요구사항을 승인하고, A의 다음 단계가 실행되는 동안 10시 30분에 전환하여 워크플로 B의 다이어그램을 검토할 수 있습니다. 다시 돌아왔을 때, A의 다음 릴레이가 당신을 위해 준비되어 있을 것입니다. 워크플로 간 전환 비용은 대략 다른 폴더를 여는 비용 정도에 불과합니다.

검사자들이 서로를 검토할 수 있습니다. 생성된 requirements.md는 그저 파일일 뿐입니다. inspector-review.md도 마찬가지입니다. 풀 리퀘스트(pull request)를 보내는 것과 같은 방식으로, 동료에게 자신의 워크플로 설계를 보여주어 제3자의 시각으로 검토를 요청할 수 있습니다. 그들은 이를 읽고, 의견을 남기고, 승인합니다. 검사자 간 검토(Cross-inspector review)는 따로 추가해야 하는 새로운 기능이 아닙니다. 산출물(artifacts)이 파일일 때 자연스럽게 발생하는 현상입니다.

태스크(Tasks)는 누구나 질의할 수 있는 대상이 됩니다. TODO 항목들이 Jira나 Linear에만 머물지 않고 워크플로우의 나머지 부분과 함께 리포지토리(repository) 내에 존재하게 되면, 에이전트(agent)를 사용하는 사람이라면 누구나 이에 대해 질문할 수 있습니다. PM(Product Manager)은 다음과 같은 질문을 던질 수 있습니다: "이번 주에 무엇이 배포되었는가", "어떤 워크플로우가 한 시간 이상 차단(blocked)되어 있는가", "로열티(loyalty) 기능이 완료되었는가". PM은 답변을 얻기 위해 팀의 업무를 중단시킬 필요가 없습니다.