연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스(Harness) 제작 입문 제6회 - 하네스용 디렉터리 구성과 README 만들기

연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스(Harness) 제작 입문

전 24회 (주 2회 · 12주간) | 제6회 / 24

이 연재는 AI에게 일자리를 빼앗길지도 모른다는 불안을 '하네스(Harness, AI 에이전트 제어 메커니즘)'를 직접 만드는 행동으로 바꾸는 시리즈입니다.

"하네스를 만들고 싶지만, 어디서부터 손을 대야 할지 모르겠다" —— 이 비명은 많은 엔지니어에게 공통된 고민입니다.

지난 회차(제5회)에서는 SE(System Engineer) 경험이 AI 하네스 설계에 전용될 수 있음을 확인했습니다. 하지만 "전용할 수 있다는 것을 알았다"는 것만으로는 아직 움직일 수 없습니다. 이번에는 그 첫걸음으로서 "프로젝트의 골격을 만드는 것"에 집중합니다.

SE 경험이 있는 분이라면 "프로젝트의 초기 구조"는 익숙한 작업일 것입니다. 그 경험을 살려 AI 하네스 프로젝트의 디렉터리 구성(Directory Structure)과 README를 설계합니다.

• SE · 프로그래머 경험 3년 이상인 분
• "만들고 싶지만 어디서부터"라며 멈춰 있는 분
• Git / GitHub의 기본 조작이 가능한 분
• 지난 연재를 읽어온 분 (읽지 않았어도 OK)

하네스 프로젝트의 디렉터리 구성은 SE가 일상적으로 수행하는 "프로젝트 초기 설계" 그 자체입니다. 이번에 제시하는 구성안을 베이스로 하여, 자신의 프로젝트에 맞춰 커스터마이징하면 당일 안에 골격이 완성됩니다.

프로젝트의 디렉터리 구성은 "수수하지만 중요한 토대"입니다. SE라면 경험적으로 알고 있겠지만, 초기 구성이 나쁘면 나중에 확장이 어려워집니다.

AI 하네스 프로젝트에서는 특히 다음과 같은 이유로 초기 구성이 중요합니다.

MCP 서버가 복수 존재함: 각 서버의 코드 저장소를 명확히 할 필요가 있음 -
설정 파일이 많음: 프롬프트(Prompt), 스키마(Schema), 환경 변수(Environment Variable) 등이 분산되기 쉬움 -
문서가 중요함: AI 에이전트 자체가 README나 문서를 읽고 동작하는 경우가 있음

SE 경험	하네스 프로젝트로의 활용
프로젝트 초기 설정 경험	디렉터리 설계 판단 기준을 그대로 사용할 수 있음
...

이하는 AI 하네스 프로젝트의 디렉터리 구성안입니다. 그대로 사용할 필요는 없으며, 자신의 프로젝트에 맞춰 조정하십시오.

ai-harness/
├── README.md # 프로젝트 개요 · 셋업 절차
├── LICENSE # 라이선스 파일
...

README.md는 "프로젝트의 얼굴"입니다. SE라면 "읽는 사람이 가장 먼저 알고 싶은 것"을 생각하는 데 능숙할 것입니다. 다음과 같은 구조를 제안합니다.

# 🧰 AI Harness - AI 에이전트 제어 프레임워크
## 이 프로젝트는 무엇인가
AI 에이전트를 제어하기 위한 "하네스"를 구축하는 프레임워크입니다.
...

주의점	이유	대책
처음부터 완벽을 목표로 하지 않는다	구성은 프로젝트의 성장과 함께 변함	최소한의 구성으로 시작하여 필요에 따라 확장
...

• 위의 디렉터리 구성을 베이스로, 자신의 프로젝트 이름으로 디렉터리를 생성한다
• README.md를 위의 구조로 작성한다 (내용은 임시로 작성해도 OK)

.gitignore에 .env, pycache, .venv를 추가한다 -
.env.example을 작성하여 필요한 환경 변수를 리스트업한다

git init을 수행하고 첫 번째 커밋을 한다 -
(발전) GitHub에 푸시한다

이번에는 AI 하네스 프로젝트의 디렉터리 구성과 README 설계를 수행했습니다.

키포인트

• 디렉터리 구성은 SE의 "프로젝트 초기 설계" 경험을 그대로 사용할 수 있다
• 처음부터 완벽을 목표로 하지 말고, "확장 가능한 최소 구성"으로 시작한다
• README는 프로젝트의 "얼굴". "무엇이", "왜", "어떻게 사용하는지"를 명확히 한다
• .env 관리, 테스트 디렉터리 준비는 첫날에 한다

"만들고 싶지만 어디서부터"에 대한 답은 이 디렉터리 구성을 만드는 것입니다. 오늘 안에 골격을 만들어 봅시다.

**제7회 「MCP 서버를 『도구 상자』로서 분할하는 사고방식」**에서는 디렉터리 구성 중의 mcp_servers/에 초점을 맞춥니다.

• MCP 서버의 책임 분할 사고방식 ("1 MCP = 1 책임" 원칙)

• 마이크로서비스(Microservices)적인 분할 vs 모놀리스(Monolith)적인 구성의 트레이드오프(Trade-off)

• 실제 하네스에서 어떤 MCP 서버가 필요한가

• MCP 책임표 (각 MCP의 역할과 입출력을 정리한 표)

• 이번에 만든 디렉터리 구성인 mcp_servers/에 자신이 사용하고 싶은 MCP 서버의 이름을 임시로라도 적어둡니다. - 평소 사용하는 도구들을 「기능별」로 그룹화해 봅니다 (이것이 MCP 분할의 힌트가 됩니다).

회차	제목	상태
제1회	「AI에게 일을 빼앗긴다」는 불안의 정체를 분해하기	✅
...

연재: AI에게 일을 빼앗길 불안으로부터 시작하는 하네스(Harness) 제작 입문

저자: @and-and-and ｜ 주 2회 업데이트

다음 회차는 「MCP 서버를 『도구 상자』로서 분할하는 사고방식」을 예정하고 있습니다.