스캐폴드는 하네스와 뭐가 다른가

ai-agentllmharness

안녕하세요! 재니미입니다.

지난 글 「에이전트와 하네스, 뭐가 다른가」에서 위키피디아를 인용하면서 에이전트 하네스를 “또는 에이전트 스캐폴딩”이라고 병기하고 그냥 넘어갔습니다. 그런데 그 글에서 같이 인용했던 OpenAI의 글을 다시 읽다가 걸리는 대목을 발견했습니다. 이 글이 “스캐폴드”를 쓰는 방식이, 지난 글에서 정리한 “하네스”랑 딱 겹치지가 않습니다. 이번 글에서는 이 둘이 어떻게 다른지 짚어봤습니다.

OpenAI가 말하는 스캐폴드

사람 손을 거의 안 대고 대규모 코드베이스를 만든 사례를 소개한 OpenAI의 글에는 이런 문장이 나옵니다.

“The initial scaffold—repository structure, CI configuration, formatting rules, package manager setup, and application framework—was generated by Codex CLI using GPT-5, guided by a small set of existing templates.”

초기 스캐폴드(저장소 구조, CI 설정, 포맷팅 규칙, 패키지 매니저 설정, 애플리케이션 프레임워크)는 몇 가지 기존 템플릿을 참고해 GPT-5 기반 Codex CLI가 생성했다.

읽어보면 스캐폴드가 하네스보다 훨씬 구체적이고 좁은 걸 가리킵니다. 에이전트가 실제 기능을 짜기 시작하기도 전에 먼저 깔아두는 판입니다. 저장소 안내를 적은 README, 작업 규칙을 적은 AGENTS.md, 자주 쓰는 지시를 담은 프롬프트 템플릿처럼, 실제 작업 내용이 아니라 작업이 일어날 자리를 잡아두는 파일들이 여기 해당합니다. 저도 개인 LLM 위키를 구축할 때 비슷한 걸 먼저 깔아뒀습니다. 첫 커밋에서 한 일은 실제 지식 문서를 쓰는 게 아니라, 수신함과 지식 백과를 나눈 2단계 폴더 구조를 잡고, 문서 종류별 템플릿 4종을 만들고, AGENTS.md에 운영 지침을 적고, 검색용 CLI 도구를 붙이는 것이었습니다. 그때 첫 커밋에 들어간 구조를 그대로 옮기면 이렇습니다.

.
├── README.md            # 저장소 안내
├── AGENTS.md             # 작업 규칙
├── bin/                   # 검색 CLI 실행 스크립트
├── raw/                   # 1단계: 아직 정리 안 된 수신함
│   ├── logs/
│   └── memos/
├── wiki/                  # 2단계: 정리된 지식 백과
│   ├── adr/
│   ├── infra/
│   ├── opensource/
│   ├── runbooks/
│   └── troubleshooting/
└── templates/             # 문서 종류별 템플릿 4종
    ├── adr_template.md
    ├── opensource_template.md
    ├── runbook_template.md
    └── troubleshooting_template.md

문서 한 줄 없이도, 이 구조만 보면 “여기엔 아직 정리 안 된 메모가 쌓이고, 저기엔 정리된 지식이 쌓이고, 문서는 이 네 가지 틀 중 하나를 따른다”는 규칙이 이미 정해져 있습니다. 그때 짜둔 것들이 딱 스캐폴드였던 셈입니다.

스캐폴드는 건설 현장에서 건물을 짓는 동안만 세워두고, 완성되면 걷어내는 임시 구조물입니다. 소프트웨어에서도 비슷하게, 그 위에 진짜 기능 코드가 쌓일 수 있게 미리 짜둔 뼈대입니다.

그럼 같은 글에서 하네스는 뭘까요. 이 글은 하네스가 스캐폴드와 피드백 루프, 문서, 아키텍처 제약을 전부 기계가 읽을 수 있는 형태로 담아내고, Codex 에이전트는 그걸 보고 코드 작성부터 테스트, 관측까지 실제 작업을 해나간다고 설명합니다. 이 글 안에서는 스캐폴드가 하네스 안에 들어가는 한 조각인 셈입니다. 하네스가 에이전트를 둘러싼 환경 전체라면, 스캐폴드는 그 환경 안에서 에이전트가 채워나갈 코드베이스의 뼈대입니다.

그럼 위키피디아는 왜 같은 말처럼 썼을까

지난 글로 다시 돌아가 보면, 제가 인용한 위키피디아 정의는 “에이전트 하네스(또는 에이전트 스캐폴딩)“라고 병기하고 있었습니다. 이게 틀린 건 아닙니다. 업계에서 실제로 이 두 단어가 그렇게까지 엄격하게 구분되지 않고 섞여 쓰이는 경우가 많다는 뜻에 가깝습니다. “이 에이전트 스캐폴딩이 잘 짜여 있다”는 말이, 코드 뼈대만이 아니라 도구 호출 루프나 가드레일까지 포함한 시스템 전체를 가리킬 때도 흔합니다.

그래서 저는 두 단어 사이에 무슨 절대적인 경계선이 있다고 보기보다는, 지금 저자가 코드베이스의 뼈대를 말하는 건지 그걸 감싸는 시스템 전체를 말하는 건지를 문맥으로 가려 읽는 쪽이 더 실용적이라고 생각합니다. OpenAI처럼 좁게 쓰는 경우도, 위키피디아처럼 하네스의 동의어로 넓게 쓰는 경우도 둘 다 있다는 것만 알아두면, 다음에 이 단어를 만났을 때 덜 헷갈릴 것 같습니다.

감사합니다.

참고 자료