[시리즈] 하네스 엔지니어링
AI 코딩 시대에 사람 엔지니어가 해야할 일은?
- [AI코딩] 하네스(Harness) 엔지니어링이란 뭘까?
- [AI코딩] 하네스 엔지니어링에서 사람 개발자의 역할은?
- ▶ [AI코딩] 하네스 엔지니어링 repository 구조
개인적인 해석이 많이 포함된 글입니다. 학술적으로나 기술적으로 정확한 정의와 거리가 멀 수도 있으므로 읽으면서 유의하시기 바랍니다.
하네스 엔지니어링을 위한 리포지토리 구조
1. 리포지토리 구조는 왜 중요한가
이전 포스팅에서는 하네스 엔지니어링이 무엇인지, 그리고 하네스 엔지니어링의 핵심 요소가 무엇인지, 하네스 엔지니어링에서의 사람 엔지니어의 역할은 무엇인지 알아보았다. 그러면 하네스 엔지니어링을 이용한 프로젝트를 시작하려면 무엇부터 해야할까?
나는 어떤 프로젝트를 수행할 때의 가장 첫 순서는 “기획과 요구사항 정의”로 시작한다. 이 단계가 끝난 뒤에는 항상 “디렉터리 세팅”을 수행한다. 디렉터리 세팅은 그 프로젝트의 구조와 방향성, 협업 스타일 등을 담고 있다고 생각한다. 무엇을 더 중점적으로 생각하는지, 어떤 식으로 협업하고 지식을 공유하는지 등이 나타나는 것이다.
하네스 엔지니어링에서도 디렉터리 구조(리포지토리 구조)는 중요한 것 같다. 바로 “AI와의 협업”이 필요하기 때문이다. 하네스 엔지니어링에서 리포지토리 구조는 단순한 폴더 정리가 아니라, AI 에이전트가 읽고, 판단하고, 실행하고, 검증할 수 있도록 지식을 배치하는 작업인 것이다.
2. OpenAI 엔지니어링 팀에서 사용한 디렉터리 구조
일단 뭐가 됐든, OpenAI 엔지니어링 팀에서 사용한 디렉터리 구조를 보고 가자. 이 구조에 대해서는 다음 섹션들에서 차근차근 살펴보겠다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
2. AGENTS.md 파일은 백과사전이 아닌 지도여야 한다.
하네스 엔지니어링 관점에서 프로젝트를 구성할 때 가장 먼저 떠올릴 수 있는 파일은 AGENTS.md이다. 이름 그대로 AI 에이전트가 프로젝트를 이해하기 위해 먼저 읽는 문서라고 볼 수 있다. 그렇다면 AGENTS.md에는 무엇을 적어야 할까?
처음에는 이 파일에 프로젝트의 모든 규칙과 지식을 넣고 싶어진다. 프로젝트 소개, 아키텍처 설명, 코딩 컨벤션, 테스트 방법, 배포 방식, 제품 요구사항, 보안 규칙, 기술 부채까지 모두 한 파일에 넣으면 에이전트가 한 번에 모든 내용을 볼 수 있을 것처럼 느껴진다.
하지만 OpenAI 엔지니어링 팀은 이 지점에서 실패를 겪었다.
OpenAI에서는 초기에 “하나의 큰 AGENTS.md 방식으로 접근했다고 한다. 하지만 이 거대한 지침 파일은 그 자체가 복잡해지면서 AI 코딩 에이전트가 주요 제약조건을 놓치거나, 잘못된 제약조건을 따르는 문제를 발생시켰다고 한다.
이는 AGENTS.md가 너무 커지면서 오히려 AI 에이전트가 중요한 정보를 놓칠 가능성이 커졌기 때문이다. 모든 내용이 한 곳에 들어가 있으면 사람이 보기에도 복잡해지고, 에이전트 입장에서도 어떤 정보가 지금 작업에 중요한지 판단하기 어려워진다.
즉, AGENTS.md는 프로젝트의 모든 지식을 담는 백과사전이 아니라, 에이전트가 어디를 읽어야 하는지 알려주는 지도에 가까워야 한다.
예를 들어 에이전트가 프론트엔드 컴포넌트를 수정해야 한다면 docs/FRONTEND.md를 읽도록 안내하고, 인증 관련 코드를 수정해야 한다면 docs/SECURITY.md와 docs/ARCHITECTURE.md를 먼저 읽도록 안내하는 방식이다.
이렇게 보면 AGENTS.md의 역할은 다음과 같이 정리할 수 있다.
1
2
3
4
5
6
7
AGENTS.md의 역할
1. 이 프로젝트가 무엇인지 짧게 설명한다.
2. 주요 디렉터리의 역할을 알려준다.
3. 작업 유형별로 읽어야 할 문서를 안내한다.
4. 반드시 지켜야 할 핵심 규칙만 적는다.
5. 작업 후 실행해야 할 검증 명령어를 알려준다.
예를 들어 작은 프로젝트라면, 다음과 같이 작성해볼 수 있을 것이다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# AGENTS.md
## Project Overview
이 프로젝트는 사용자의 학습 기록을 관리하는 웹 애플리케이션이다.
## Repository Guide
- `src/`: 애플리케이션 소스 코드
- `tests/`: 테스트 코드
- `docs/`: 설계 문서, 제품 스펙, 실행 계획, 의사결정 기록
- `scripts/`: 검증 및 자동화 스크립트
## Read First
작업을 시작하기 전에 작업 유형에 따라 아래 문서를 먼저 읽는다.
- 전체 구조를 이해해야 하는 경우: `docs/ARCHITECTURE.md`
- 제품 요구사항을 확인해야 하는 경우: `docs/PRODUCT.md`
- 프론트엔드 작업을 하는 경우: `docs/FRONTEND.md`
- 보안, 인증, 권한 관련 작업을 하는 경우: `docs/SECURITY.md`
- 현재 진행 중인 작업 계획을 확인해야 하는 경우: `docs/PLANS.md`
## Validation
작업 후 아래 명령어를 실행한다.
npm run lint
npm run typecheck
npm test
## Hard Rules
- 인증, 권한, 결제 관련 코드는 명시적 요청 없이 구조를 변경하지 않는다.
- 테스트가 있는 영역을 수정했다면 관련 테스트를 함께 실행한다.
- 기존 아키텍처 레이어를 우회하지 않는다.
- 문서와 코드가 충돌하면 사용자에게 확인하거나 문서를 함께 수정한다.
3. docs는 에이전트를 위한 지식 저장소다.
AGENTS.md가 지도라면, docs/는 실제 지식이 저장되는 장소다.
하네스 엔지니어링에서 중요한 점은 AI 에이전트가 사용할 수 있는 지식을 프로젝트 안에 배치하는 것이다. 사람 개발자는 회의에서 들은 내용, 팀의 암묵적인 규칙, 과거 의사결정의 배경을 기억할 수 있다. 하지만 AI 에이전트는 기본적으로 현재 주어진 컨텍스트와 접근 가능한 파일을 기반으로 판단한다.
따라서 사람의 머릿속, 외부 메신저, 종이 회의록, 흩어진 문서에만 프로젝트에 대한 내용이 존재한다면 에이전트 입장에서는 그 지식이 알 수가 없다. 따라서 적절한 문서와 구조로 프로젝트에 대한 지식을 에이전트가 알 수 있도록 해야하며, 여기서 docs/ 디렉터리는 단순한 문서 보관함이 아니라, 에이전트가 판단에 사용할 수 있는 지식 저장소가 된다.
OpenAI의 하네스 엔지니어링 글에서는 리포지토리 지식을 “기록 시스템”으로 만든다고 설명한다. 이때 핵심은 AGENTS.md를 거대한 백과사전처럼 쓰지 않는 것이다. OpenAI는 초기에 하나의 큰 AGENTS.md 방식을 시도했지만, 컨텍스트 낭비, 지침 과다, 오래된 규칙 누적, 검증 어려움 같은 문제가 생겼다고 말한다. 그래서 AGENTS.md는 목차처럼 짧게 유지하고, 실제 지식은 구조화된 docs/ 디렉터리에 둔다.
예를 들어 다음과 같은 문서들이 docs/에 들어갈 수 있다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
각 문서/디렉터리의 역할은 다음과 같이 나눌 수 있다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
AGENTS.md
= 에이전트가 처음 읽는 지도
ARCHITECTURE.md
= 시스템 전체 구조를 이해하기 위한 상위 지도
docs/design-docs/
= 설계 원칙과 설계 문서
docs/exec-plans/
= 현재 작업 계획, 완료된 계획, 기술 부채
docs/generated/
= 시스템에서 생성된 참조 문서
docs/product-specs/
= 제품 요구사항과 기능 명세
docs/references/
= 외부 도구, 라이브러리, 디자인 시스템 참고 자료
docs/*.md
= 보안, 신뢰성, 프론트엔드, 품질 등 프로젝트 운영 원칙
결국 docs는 사람을 위한 부가 문서보다는, 에이전트가 작업을 수행하기 위해 읽는 지식 저장소다. 좋은 docs 구조는 에이전트에게 다음 질문에 답할 수 있게 해준다.
- 이 프로젝트는 어떤 제품인가?
- 어떤 설계 원칙을 따라야 하는가?
- 지금 진행 중인 계획은 무엇인가?
- 과거에 어떤 의사결정을 했는가?
- 알려진 기술 부채는 무엇인가?
- 보안, 신뢰성, 품질 기준은 무엇인가?
- 외부 도구나 라이브러리는 어떻게 사용해야 하는가?
4. 좋은 리포지토리 구조의 조건
하네스 엔지니어링 관점에서 좋은 리포지토리 구조는 단순히 보기 좋은 구조가 아니다. AI 에이전트가 프로젝트를 이해하고, 안전하게 수정하고, 스스로 검증할 수 있는 구조여야 한다.
따라서, 하네스 엔지니어링에서 좋은 리포지토리 구조의 조건을 말해보라면 다음과 같이 정리해볼 수 있을 것 같다.
1
2
3
4
5
1. 찾기 쉬워야 한다.
2. 작업 규칙이 명확해야 한다.(누가 봐도!)
3. 검증 방법이 코드화되어 있어야 한다.
4. 계획과 기록이 남아야 한다.
5. 오래된 문서가 방치되지 않아야 한다.
(1) 찾기 쉬워야 한다.
AI 에이전트는 작업을 수행할 때 필요한 파일을 찾아야 한다. 이때 디렉터리와 문서의 이름이 명확하면 에이전트가 훨씬 안정적으로 작업할 수 있을 것이다.
예를 들어 misc/, temp/, backup/, new/ 같은 이름은 사람에게도 모호하고 에이전트에게도 모호하다. 반면 product-specs/, design-docs/, exec-plans/, references/ 같은 이름은 그 안에 어떤 정보가 있을지 예측하기 쉽다.
(2) 작업 규칙이 명확해야 한다.
에이전트에게 “알아서 잘 해줘”라고 맡기면 결과가 매번 달라질 수 있다. 따라서 프로젝트 안에는 작업 전후에 지켜야 할 규칙이 있어야 한다. 예를 들어 다음과 같은 규칙이다.
1
2
3
4
5
- 새 기능을 추가할 때는 관련 테스트를 추가한다.
- API 응답 형식을 변경할 때는 문서를 함께 수정한다.
- 인증 관련 코드는 SECURITY.md를 먼저 확인한다.
- 데이터베이스 스키마 변경 시 마이그레이션 파일을 작성한다.
- 기존 레이어 구조를 우회하지 않는다.
(3) 검증 방법이 실행 가능해야 한다.
하네스 엔지니어링에서 중요한 것은 에이전트가 작업을 끝낸 뒤 스스로 검증할 수 있는 환경을 제공하는 것이다. 이를 위해 테스트, 린트, 타입 체크, 빌드 명령어가 명확해야 한다. 예를 들어 다음과 같은 스크립트가 있으면 좋다.
1
2
3
4
npm run lint
npm run typecheck
npm test
npm run build
또는 검증 코드들을 하나의 실행 스크립트에 묶을 수도 있을 것이다.
1
./scripts/check.sh
이렇게 하면 에이전트에게 “작업 후 ./scripts/check.sh를 실행하라”고 지시할 수 있다. 검증 절차가 명확하면 에이전트의 작업 결과도 더 안정적이 된다.
(4) 계획과 기록이 남아야 한다.
AI 에이전트는 한 번에 큰 작업을 수행할 수도 있지만, 복잡한 작업일수록 계획과 중간 기록이 중요하다. 한 번에 “제대로” 처리할 수 있는 작업량에는 한계가 있기 때문에, 큰 계획은 작은 계획으로 나누고, 이 계획들이 완료된 것인지, 지금 할 것인지, 나중에 할 것인지도 명시해둬야 한다.
따라서 현재 진행 중인 작업과 완료된 작업을 분리해서 관리하는 게 필수적이다. 예를 들면 다음과 같은 구조를 그려볼 수 있을 것이다.
1
2
3
4
5
6
7
docs/
└── exec-plans/
├── active/
│ └── add-user-profile-page.md
├── completed/
│ └── 2026-05-17-refactor-auth-flow.md
└── tech-debt-tracker.md
이 구조에서는 현재 진행 중인 계획(작업)은 active에 두고, 완료된 계획(작업)은 completed로 옮긴다. 이를 통해 사람과 에이전트 모두 현재 작업 상태를 쉽게 파악할 수 있게 하는 것이다.
(5) 오래된 문서가 방치되지 않아야 한다
문서가 많아지면 반드시 생기는 문제가 있다. 코드는 바뀌었는데 문서는 그대로 남는 문제다.
이 경우 에이전트는 오래된 문서를 신뢰하고 잘못된 작업을 할 수 있다. 따라서 문서에는 가능한 한 마지막 수정일, 관련 코드 위치, 적용 범위를 적어두는 것이 좋다. 예를 들어 다음과 같은 형식이다.
1
2
3
4
5
6
7
8
9
10
# SECURITY.md
Last updated: 2026-05-17
Related files:
- src/auth/
- src/middleware/auth.ts
- src/lib/session.ts
Scope:
이 문서는 인증, 세션, 권한 처리 방식에 대한 규칙을 설명한다.
이런 작은 정보만 있어도 에이전트는 문서의 적용 범위와 신뢰도를 더 잘 판단할 수 있을 것이다.
5. 작은 프로젝트에서 시작해보기
그렇다면 모든 프로젝트가 처음부터 복잡한 docs/ 구조를 가져야 할까? 그렇지는 않다고 한다. 오히려 작은 프로젝트에서 처음부터 너무 많은 문서를 만들면 관리 비용만 커질 수 있다. 중요한 것은 문서의 개수가 아니라, 에이전트가 작업에 필요한 맥락을 찾을 수 있느냐이다.
작은 프로젝트라면 다음 정도의 구조로도 충분히 시작할 수 있을것이다.
1
2
3
4
5
6
7
8
9
10
11
12
AGENTS.md
README.md
docs/
├── ARCHITECTURE.md
├── PRODUCT.md
├── RULES.md
├── PLANS.md
└── DECISIONS.md
src/
tests/
scripts/
└── check.sh
각 파일의 역할은 다음과 같다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
AGENTS.md
- 에이전트가 처음 읽는 지도
- 주요 문서와 검증 명령어 안내
README.md
- 사람이 프로젝트를 이해하기 위한 기본 설명
- 설치, 실행, 배포 방법
docs/ARCHITECTURE.md
- 전체 구조와 의존성 방향
- 주요 설계 원칙
docs/PRODUCT.md
- 제품 목적
- 사용자
- 주요 기능과 요구사항
docs/RULES.md
- 코딩 규칙
- 작업 시 주의사항
- 변경하면 안 되는 영역
docs/PLANS.md
- 현재 작업 계획
- 앞으로 할 일
- 우선순위
docs/DECISIONS.md
- 중요한 의사결정 기록
- 특정 기술이나 구조를 선택한 이유
scripts/check.sh
- 테스트, 린트, 타입 체크 등을 한 번에 실행하는 검증 스크립트
이 정도만 있어도 에이전트가 프로젝트를 이해하고 작업을 수행하는 데 필요한 기본적인 하네스가 만들어질 것이고, 여기서 프로젝트가 커지면 문서를 조금씩 분리하는 것이다.
예를 들어 프론트엔드 규칙이 많아지면 docs/FRONTEND.md를 만들고, 여기서 세부 컴포넌트별 규칙이 더 많아진다면 그때는 docs/frontend 디렉터리를 만들어 분화하는 것이다.
작은 프로젝트에서도 AGENTS.md, docs/, scripts/check.sh 정도는 충분히 가치가 있을 것이다. 이 세 가지가 있으면 에이전트에게 다음과 같이 지시할 수 있기 때문이다.
1
2
3
1. 먼저 AGENTS.md를 읽어라.
2. 작업에 필요한 문서를 docs/에서 찾아라.
3. 작업이 끝나면 scripts/check.sh를 실행해라.
이 정도만 되어도 단순히 “코드를 수정해줘”라고 말하는 것보다 훨씬 안정적인 협업이 가능해질 것이다.
6. 정리
이번 글에서는 하네스 엔지니어링 관점에서 리포지토리 구조를 어떻게 바라볼 수 있는지 정리해보았다.
일반적인 개발에서도 리포지토리 구조는 중요하다. 하지만 하네스 엔지니어링에서는 그 중요성이 더 커진다고 생각된다. 리포지토리 구조가 사람 개발자뿐 아니라 AI 에이전트가 프로젝트를 이해하고 작업하는 방식에도 직접적인 영향을 주기 때문이다.
하네스 엔지니어링에서 리포지토리 구조는 단순한 폴더 정리가 아니며, AI 에이전트가 프로젝트를 이해하고, 필요한 지식을 찾고, 안전하게 코드를 수정하고, 작업 결과를 검증하기 위한 작업 환경의 가장 기초적인 부분이라고 생각된다.
Reference
하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기
[시리즈] 하네스 엔지니어링
AI 코딩 시대에 사람 엔지니어가 해야할 일은?
- [AI코딩] 하네스(Harness) 엔지니어링이란 뭘까?
- [AI코딩] 하네스 엔지니어링에서 사람 개발자의 역할은?
- ▶ [AI코딩] 하네스 엔지니어링 repository 구조
Comments