최근 design.md라는 이름의 GitHub 저장소가 1,400개 이상의 스타(stars)를 쌓으며 트렌드가 되고 있습니다. 개념은 간단합니다. AI 에이전트에게 작업 전반에 걸쳐 참조할 수 있는 지속적인 디자인 문서(design document)를 제공하는 것입니다.

이 접근 방식은 많은 팀이 직면하는 에이전트 개발의 실질적인 과제를 해결합니다.

컨텍스트의 과제 (The Context Challenge)
복잡한 작업을 수행할 때, AI 에이전트는 더 넓은 그림을 이해해야 합니다. 아키텍처(architecture)는 무엇인가? 어떤 제약 사항이 존재하는가? 이전에 어떤 접근 방식들이 시도되었는가?

일반적으로 에이전트는 다음과 같은 곳에서 컨텍스트(context)를 얻습니다:

• 현재 대화 (제한된 윈도우/window)
• 코드 주석 (종종 오래된 정보)
• 문서 (존재하는 경우)

문제는 이 컨텍스트가 파편화되어 있고 일시적이라는 점입니다. 대화가 진행됨에 따라 이전의 컨텍스트는 사라집니다. 문서가 최신 상태가 아니면 에이전트는 잘못된 가정을 하게 됩니다.

design.md는 세션 전반에 걸쳐 지속되는 단일 진실 공급원(single source of truth)을 제공합니다.

design.md에 포함되어야 할 내용
effective한 design.md는 다음 질문들에 답해야 합니다:

1. 무엇을 만들고 있는가?

기능 목록을 넘어 핵심 목적을 문서화하세요. 이 프로젝트는 왜 존재하는가? 어떤 문제를 해결하는가?

2. 주요 아키텍처 결정 사항은 무엇인가?

주요 선택 사항과 그 근거를 문서화하세요:

"금융 트랜잭션에는 ACID 보장이 필요하기 때문에 MongoDB 대신 PostgreSQL을 선택했습니다"
"컴포넌트마다 확장 요구 사항이 다르기 때문에 마이크로서비스 아키텍처(Microservices architecture)를 채택했습니다"

3. 어떤 제약 사항이 존재하는가?

기술적 제약(성능 요구 사항, 브라우저 지원), 비즈니스 제약(예산, 일정), 그리고 규제 제약(GDPR, HIPAA) 등이 있습니다.

4. 이전에 무엇을 시도했는가?

에이전트가 거부된 솔루션을 제안하는 것을 방지하기 위해 실패한 접근 방식들을 문서화하세요.

5. 현재의 과제는 무엇인가?

알려진 이슈, 기술 부채(technical debt), 개선이 필요한 영역을 기록하여 에이전트가 작업의 우선순위를 정하는 데 도움을 줍니다.

에이전트가 design.md를 사용하는 방법
작업을 시작할 때, 에이전트는 다음과 같이 할 수 있습니다:

design.md를 읽어 컨텍스트 (Context) 이해하기
문서화된 아키텍처 (Architecture)에 부합하는 결정 내리기
제약 사항 (Constraints)을 위반하는 솔루션 피하기
추론 (Reasoning) 과정에서 design.md 참조하기

이를 통해 더욱 일관성 있고 통일된 작업이 가능해집니다. 에이전트는 단순히 즉각적인 작업에 반응하는 것이 아니라, 더 넓은 프레임워크 (Framework) 내에서 작동하게 됩니다.

design.md 최신 상태 유지하기
design.md의 주요 위험 요소는 내용이 구식이 되는 것입니다. 효과적인 실천 방법은 다음과 같습니다:

워크플로 (Workflow)의 일부로 만들기

중요한 아키텍처 결정을 내릴 때 즉시 design.md를 업데이트하세요. "나중에" 하겠다고 미루는 것은 결국 하지 않겠다는 의미와 같습니다.

버전 관리 (Version control) 하기

design.md를 리포지토리 (Repository)에 보관하세요. PR (Pull Request) 리뷰 과정에서 design.md의 업데이트가 필요한지 확인하십시오.

정기적으로 검토하기

문서가 현재의 실제 상황을 반영하고 있는지 확인하기 위해 정기적인 검토(매월 또는 매 분기) 일정을 잡으세요.

에이전트의 도움 받기

에이전트는 다음과 같은 방식으로 design.md 유지 관리를 도울 수 있습니다:

불일치를 발견했을 때 업데이트 제안하기
최근 커밋 (Commit)의 변경 사항 요약하기
오래된 정보에 플래그 (Flag) 표시하기

에이전트 워크플로에서의 관찰 가능성 (Observability)

훌륭한 design.md가 있더라도, 에이전트가 실제로 무엇을 하는지 관찰하는 것은 중요합니다. 이는 복잡한 인터페이스와 상호작용하는 GUI 에이전트에게 특히 중요합니다.

"이 양식을 작성하고 제출하세요"라는 과업을 맡은 GUI 에이전트를 가정해 봅시다. 에이전트는 다음과 같은 과정을 수행해야 합니다:

양식 필드 찾기
정확한 데이터 입력하기
유효성 검사 오류 (Validation errors) 처리하기
양식 제출하기
성공 여부 확인하기

각 단계는 다양한 방식으로 실패할 수 있습니다. 관찰 가능성 (Observability)이 없다면, 최종 결과인 성공 또는 실패만을 볼 수 있을 뿐입니다. 실패의 원인은 알 수 없는 상태로 남게 됩니다.

관찰 가능한 워크플로 구축하기

좋은 관찰 가능성에는 다음이 포함됩니다:

1. 단계별 로깅 (Step-by-step logging)

각 작업을 기록합니다:

무엇이 관찰되었는가 (스크린샷, DOM 상태)
어떤 결정이 내려졌는가
실제로 어떤 일이 일어났는가
기대치와 일치했는가

1. 성능 지표 (Performance metrics)

다음 사항을 추적합니다:

작업 유형별 성공률
완료까지의 평균 단계 수
단계별 소요 시간
실패 모드 (Failure modes)

1. 오류 범주화 (Error categorization)

문제가 발생했을 때, 오류를 다음과 같이 분류합니다:

인지 오류 (Perception errors) (에이전트가 올바른 요소를 보지 못함)
의사결정 오류 (Decision errors) (에이전트가 잘못된 행동을 선택함)
실행 오류 (Execution errors) (외부 요인으로 인해 행동이 실패함)
이 데이터는 개선이 필요한 지점을 식별하는 데 도움이 됩니다.

체계적인 벤치마킹 (Systematic Benchmarking)
CUA Benchmark는 다음과 같은 체계적인 관측 가능성 (observability)을 제공합니다:

5개의 서로 다른 웹 애플리케이션에 걸친 100개의 테스트 케이스
표준화된 작업 정의 (Standardized task definitions)
자동화된 결과 검증
상세한 성능 지표 (performance metrics)
CUA Benchmark를 통해 에이전트를 실행하면 다음과 같은 정량적 데이터를 얻을 수 있습니다:

전체 성공률
작업 유형별 성공률
작업당 평균 단계 (Average steps per task)
공통적인 실패 지점
이 데이터는 반복적인 개선 (iterative improvement)에 매우 가치 있습니다. 무엇을 최적화할지 추측하는 대신, 에이전트가 어려움을 겪는 특정 영역을 식별하고 해결할 수 있습니다.

실제 사례: Mano-AFK
Mano-AFK는 이러한 원칙들을 보여주는 오픈 소스 자율 애플리케이션 빌더 (autonomous application builder)입니다. 워크플로우는 다음과 같습니다:

무엇을 만들지에 대한 자연어 설명 수신
PRD (제품 요구 사항 문서, Product Requirements Document) 생성
코드 작성
테스트 환경에 배포
테스트 실행 (lint, API, E2E)
발생한 문제 자동 수정
최종 애플리케이션 전달
이 과정 전반에 걸쳐, 에이전트는 프로젝트 전반의 일관성을 유지하기 위해 rules.md 및 preferences.md 파일을 참조합니다. 이 파일들은 의사결정을 안내하는 지속적인 컨텍스트 (persistent context)를 제공합니다.

Mano-AFK에 대한 CUA Benchmark 결과:

W8A16 양자화 (quantization): 58.0% 정확도
W8A8 양자화 (Cider): 54.0% 정확도, 하지만 더 빠른 추론 (inference) (~1,453 tok/s prefill)
이 수치들은 W8A8 버전이 정확도는 약간 낮지만 훨씬 더 빠르다는 것을 보여줍니다. 사용 사례에 따라 하나를 다른 하나보다 선호할 수 있습니다.

체계적인 벤치마킹이 없다면 이러한 데이터는 존재하지 않았을 것입니다.

에이전트 코드를 작성하기 전에 아키텍처(architecture), 제약 사항(constraints), 그리고 주요 결정 사항들을 문서화하세요. 이 문서는 인간 개발자와 AI 에이전트 모두를 안내합니다.

1. 첫날부터 관측 가능성(observability) 구축하기

나중에 로깅(logging)을 추가하지 마세요. 에이전트 워크플로(workflows)를 처음부터 관측 가능한 상태로 설계해야 합니다. 모든 단계는 검사할 수 있는 형태의 출력을 생성해야 합니다.

1. 벤치마크(benchmarks) 활용하기

초기에 벤치마크 제품군(benchmark suite)을 구축하세요. 정기적으로 실행하고, 시간에 따른 지표(metrics)를 추적하세요. 이는 변경 사항이 개선인지 아니면 퇴보(regressions)인지에 대한 객관적인 데이터를 제공합니다.

1. 데이터에 기반한 반복(iterate)

성공률이 낮게 관찰되면 실패 모드(failure modes)를 조사하세요. 광범위한 변경을 시도하는 대신, 구체적인 실패 패턴을 식별하고 이를 직접적으로 해결하세요.

1. 컨텍스트(context)를 지속적으로 유지하기

design.md, rules.md 또는 기타 메커니즘을 통해서든, 에이전트가 지속적인 컨텍스트에 접근할 수 있도록 보장하세요. 대화 기록(conversation history)은 복잡한 프로젝트를 다루기에 너무 일시적(ephemeral)입니다.

앞으로 나아가며
AI 에이전트 엔지니어링은 여전히 초기 단계에 있습니다. 모범 사례(best practices)는 여전히 정립되어 가는 중이지만, 두 가지 사항은 명확해지고 있습니다:

• 에이전트가 훌륭한 작업을 수행하려면 지속적인 컨텍스트가 필요합니다 (design.md)
• 에이전트 워크플로가 개선되려면 체계적인 관측 가능성이 필요합니다 (벤치마크 및 로깅)

이것들은 고급 기술이 아닙니다. 다른 모든 것들이 더 잘 작동하게 만드는 기초적인 관행(foundational practices)입니다.

이러한 원칙이 실제로 어떻게 적용되는지 보고 싶다면, Mano-AFK (https://github.com/Mininglamp-AI/Mano-AFK)를 확인해 보세요. 이는 지속적인 컨텍스트 파일과 체계적인 벤치마킹을 사용하여 에이전트의 신뢰성을 향상시키는 오픈 소스 자율 애플리케이션 빌더(autonomous application builder)입니다.

GUI 에이전트를 연구하는 분들을 위해, Mano-P (https://github.com/Mininglamp-AI/Mano-P)는 생각-행동-검증(think-act-verify) 루프와 온라인 강화학습 (online reinforcement learning)을 구현하여, OSWorld 벤치마크(특화 모델 카테고리)에서 58.2%의 성공률을 달성했습니다.

두 프로젝트 모두 Apache 2.0 라이선스를 따릅니다. 스타(Stars)와 기여(contributions)를 환영합니다.