연재: AI에게 일자리를 빼앗길 불안에서 시작하는 하네스(Harness) 작성 입문 제2회: 최소 구성의 AI 하네스를 Mermaid로 설계해

연재: AI에게 일자리를 빼앗길 불안에서 시작하는 하네스(Harness) 작성 입문

전 24회 (주 2회 · 12주간) | 제2회 / 24
이 연재는 AI로 인한 커리어 불안을 느끼는 프로그래머·SE를 대상으로, AI 에이전트(AI Agent)를 안전하게 제어·검증·운용하기 위한 「하네스(Harness)」를 만드는 기술을 단계적으로 배우는 시리즈입니다.

이 기사는 연재 「AI에게 일자리를 빼앗길 불안에서 시작하는 하네스 작성 입문」의 제2회입니다.

지난 회차(제1회)에서는 AI 시대의 커리어 불안을 정리하고, 「하네스 작성」이라는 학습 방침을 소개했습니다. 이번에는 그 전체상에서 최소 구성을 추출하여 Mermaid 도표로 시각화하는 테마에 대해 정리합니다.

이 기사에서 다루는 불안은 다음과 같습니다.

AI 하네스의 필요성은 이해했지만, 전체상이 너무 커서 구체적으로 어디서부터 만들기 시작해야 할지 모르겠다.

이러한 불안은 자연스러운 것입니다. 제1회에서 소개한 전체상에는 AI 에이전트(AI Agent), MCP 서버(MCP Server), Knowledge, 로그(Log), 품질 게이트(Quality Gate), Human-in-the-loop 등 많은 요소가 포함되어 있었습니다. 전부를 한꺼번에 만들려고 하면 손이 멈추게 됩니다.

이 기사에서는 「어떤 요소부터 시작할 것인가」의 판단 기준을 제시하고, 최소 구성을 Mermaid 도표로 설계합니다.

• 제1회를 읽고 하네스 개념에 흥미를 느꼈지만, 무엇부터 시작해야 할지 망설여지는 엔지니어
• 「설계도를 그리기 전에 코드부터 쓰기 시작하는」 타입의 프로그래머
• Mermaid 도표로 아키텍처(Architecture)를 시각화하는 경험이 아직 적은 SE

결론부터 말씀드리면, 전체상에서 「AI 에이전트」, 「MCP 서버」, 「task_request / task_result」의 3종 세트를 추출하는 것이 최소 구성의 출발점입니다.

요점은 다음과 같습니다.

• 전부를 한꺼번에 만드는 것이 아니라, 「동작하는 최소 구성」을 먼저 정의한다
• 최소 구성을 Mermaid 도표로 시각화하면, 무엇을 만들고 무엇을 뒤로 미룰지가 명확해진다
• SE·프로그래머의 설계 경험(책임 분리 · 인터페이스 설계)이 그대로 하네스 설계에 활용된다

제1회에서 소개한 전체상을 재게시합니다.

[IMG:1]

이 도표에는 AI 에이전트, MCP 서버, Knowledge / RAG, 로그, 품질 게이트, 리뷰 승인, 입출력 계약 등 많은 요소가 포함되어 있습니다.

이를 한꺼번에 전부 만들려고 하면 무엇부터 손을 대야 할지 알 수 없게 됩니다. 이는 실무에서 대규모 시스템을 설계할 때도 발생하는 문제입니다.

소프트웨어 설계에서는 큰 시스템을 한꺼번에 만드는 것이 아니라, **최소한의 동작 가능한 구성(MVP: Minimum Viable Product)**부터 시작하는 것이 일반적입니다.

AI 하네스도 마찬가지입니다. 전체상 중에서 「이 세 가지만 있으면 최소한으로 동작한다」는 요소를 찾아냅니다.

그 판단 기준은 다음과 같습니다.

판단 기준	설명
AI 에이전트에게 지시를 내릴 수 있는가	태스크(Task)를 위임할 수 없다면 하네스로서 성립하지 않음
...

이 세 가지가 갖춰지면 최소한으로 「AI에게 일을 맡기고 결과를 받기」가 가능해집니다. Knowledge / RAG, 로그, 품질 게이트, Human-in-the-loop는 이 최소 구성이 동작한 이후에 추가합니다.

최소 구성을 설계하는 프로세스는 SE·프로그래머가 실무에서 수행하는 작업과 겹칩니다.

기존 경험	최소 구성 설계에서의 활용 방법
컴포넌트 분할 · 책임 분리	「AI 에이전트」, 「MCP 서버」, 「입출력 계약」을 각각 독립된 역할로 설계한다
...

특히 「큰 시스템을 작게 분할하고 각 컴포넌트의 책임을 명확히 하는」 경험은 AI 하네스 설계에서 그대로 사용할 수 있습니다.

전체상에서 추출한 최소 구성은 다음과 같은 3가지 컴포넌트로 구성됩니다.

컴포넌트	역할	제1회에서의 대응
task_request / task_result	AI에 대한 지시와 결과의 구조화	입출력 계약
AI 에이전트	태스크를 실행하는 존재	AI 에이전트
MCP 서버	AI에게 전달하는 도구 상자	MCP 서버군

다음 요소들은 중요하지만, 최소 구성이 동작한 후에 추가합니다.

요소	미루는 이유	추가 예정
Knowledge / RAG	처음에는 AI의 표준 지식으로 동작시키고, 필요할 때 전용 지식을 추가	제9~10회
...

이것은 "전부 만든 다음 동작시키는" 것이 아니라 "동작시키면서 키워나가는" 접근 방식입니다. 실무에서의 단계적 출시(Gradual Release)와 같은 생각입니다.

다음은 최소 구성의 AI 하네스(Harness)를 Mermaid로 표현한 아키텍처 도입니다. 이것이 이번 회차의 가장 중요한 결과물입니다.

이 도의 흐름은 다음과 같습니다.

인간이 태스크를 지시: task_request JSON으로 "무엇을 해주길 원하는지"를 구조화하여 전달 -
AI 에이전트가 수신: task_request 내용에 따라 태스크를 시작 -
MCP 서버의 도구를 호출: 필요에 따라 도구를 사용하여 실제 처리를 실행 -
도구로부터 결과를 수신: 각 도구의 처리 결과를 AI 에이전트가 통합 -
task_result로서 출력: 구조화된 결과를 반환 -
인간이 결과 확인: 현시점에서는 모든 결과를 인간이 육안으로 확인

전체상과 최소 구성의 차이를 명확히 합니다.

요소	전체상	최소 구성
task_request / task_result	✅	✅
...

AI 에이전트에 대한 "계약"입니다. "무엇을 해주길 원하는지"와 "무엇이 돌아오는지"를 JSON으로 구조화합니다.

{
"task_request": {
"task_id": "harness_design_001",
...

API 설계나 인터페이스 정의 경험이 있는 사람에게 이 "입력과 출력을 명확히 정의하는" 작업은 익숙한 것입니다. task_request / task_result의 상세 내용은 제4회에서 확장합니다.

task_request를 받아 MCP 서버의 도구를 사용하며 태스크를 실행하고, task_result를 반환하는 존재입니다.

최소 구성에서는 다음을 결정하는 것으로 충분합니다.

• 어떤 LLM을 사용할 것인가 (외부 API 또는 로컬)
• 어떤 MCP 서버에 접속할 것인가

모델 선택의 판단 기준은 제11~12회에서 자세히 다룹니다. 현시점에서는 "우선 동작하는 것"을 우선합니다.

AI 에이전트에게 전달하는 "도구 상자"입니다. 도구를 통해 AI가 실제로 처리를 실행할 수 있습니다.

최소 구성에서는 MCP 서버를 1개, 도구를 2~3개부터 시작합니다. 예를 들어, 이 연재 자체에서 사용하고 있는 note-qiita-article-mcp가 그 한 예입니다.

MCP 서버의 분할 설계에 대해서는 제7~8회에서 자세히 다룹니다.

주의점	이유	대책
Mermaid 도만으로 만족하지 말 것	도는 설계의 출발점이며, 구현하지 않으면 검증할 수 없음	다음 회차 이후 각 컴포넌트를 구현한다
...

• 위의 최소 구성 Mermaid 도를 자신의 GitHub 리포지토리의 README.md에 붙여넣기
• 자신의 업무에서 AI에게 맡기고 싶은 태스크를 하나 결정하고, task_request의 JSON을 작성해 보기
• 전체상과 최소 구성의 차이점 표를 살펴보며, "다음에 추가하고 싶은 요소"를 하나 결정하기

이 기사에서는 제1회에서 소개한 AI 하네스의 전체상에서 최소 구성을 추출하여, Mermaid 도로 설계했습니다.

중요한 것은, 전부를 한꺼번에 만들려고 하지 않는 것입니다. "AI 에이전트", "MCP 서버", "task_request / task_result"의 3종 세트가 있다면 최소한의 하네스는 동작합니다. 거기서부터 Knowledge, 로그, 품질 게이트(Quality Gate), Human-in-the-loop를 단계적으로 추가해 나가는 것이 이 연재의 로드맵입니다.

SE·프로그래머의 "컴포넌트 분할", "인터페이스 설계", "MVP 개발" 경험은 이 설계 프로세스에서 그대로 활용됩니다.

제3회: AI에게 코드를 쓰게 하는 것만으로는 부족한 이유 (화요일 공개 예정)

다음 회차에서는 AI를 "사용하는 것"과 AI를 "운용하는 것"의 차이를 정리합니다.

다음 회차에서 다룰 내용:

• AI 단독 이용과 하네스 운용의 차이를 여러 관점에서 비교
• "코드 생성"만으로는 업무 성과로 연결할 수 없는 이유
• "운용"이라는 관점에서 보았을 때 필요하게 되는 설계 요소

다음 회차의 결과물:

역할 비교표 (AI 단독 이용 vs 하네스 운용)

다음 회차까지 시도해 보면 좋은 것:

• 이번 Mermaid 다이어그램을 살펴보며, 「다음에 추가하고 싶은 요소」를 하나 결정해 두기
• 자신의 업무에서 AI에게 「코드를 작성하게 했던」 경험이 있다면, 그때 「무엇이 부족했는지」를 되돌아보기

회차	제목	상태
1	AI에게 일자리를 빼앗길 불안에서 「하네스(Harness) 작성」을 배우는 이유	✅
2	최소 구성의 AI 하네스를 Mermaid로 설계해 보기 (이 글)	📖
3	AI에게 코드를 작성하게 하는 것만으로는 부족한 이유	차회
4	task_request / task_result로 AI 에이전트(AI Agent)의 업무를 계약화하기	─
5	SE의 설계 경험을 AI 에이전트 제어에 전용하기	─
...

연재 정보

• 연재명:
  AI에게 일자리를 빼앗길 불안에서 시작하는 하네스(Harness) 작성 입문 - 총 24회 (12주, 주 2회)
• 게시 요일: 화요일 (커리어·설계·개념) / 금요일 (구현·검증·템플릿)