[하네스 엔지니어링] 하네스 엔지니어링을 너무 일찍 적용해보고 깨달은 것

이 글은 AI 코딩 에이전트를 잘 쓰기 위해 하네스를 만들다가, 오히려 하네스가 프로젝트보다 커져버린 경험에 대한 회고입니다. 

들어가며

AI 코딩 도구를 쓰다 보면 어느 순간 이런 생각이 든다.

"이거 매번 설명하기 귀찮은데, 규칙으로 박아두면 되지 않을까?"

"에이전트 역할을 나눠두면 더 체계적으로 돌아가지 않을까?"

"이슈, 브랜치, 리뷰, 커밋 규칙까지 자동화하면 좋지 않을까?"

나도 최근 컴퓨터 비전 프로젝트를 기획하면서 비슷한 생각을 했다.

프로젝트 주제는 최신 SAM 계열 모델을 단순한 2D segmentation 도구로 쓰는 것이 아니라, 3D 공간에서 객체를 추적하고, 측정하고, 배치 가능성까지 판단하는 object prior 생성기로 활용하는 것이었다.

기술적으로 꽤 복잡한 프로젝트였기 때문에 처음부터 Claude와 Codex가 프로젝트를 잘 이해할 수 있는 구조를 만들고 싶었다.

그래서 다음과 같은 것들을 한 번에 구성했다.

CLAUDE.md
.claude/PROJECT.md
.claude/agents/
.claude/skills/
.claude/rules/
.claude/tasks/
.github/ISSUE_TEMPLATE/
.github/PULL_REQUEST_TEMPLATE.md

겉으로 보기에는 꽤 그럴듯했다.

Claude는 진입점을 읽고, 라우터를 통해 역할을 정하고, 이슈를 만들고, 작업을 나누고, PR까지 만들 수 있었다.

그런데 막상 시작하고 보니 이상한 피로감이 생겼다.

코드를 짜기도 전에 운영 문서가 너무 많아졌다.

기능을 만들기도 전에 라우팅 구조를 이해해야 했다.

"무엇을 구현할까?"보다 "어떤 agent가 어떤 skill을 읽어야 하지?"를 먼저 생각하게 됐다.

그때 깨달았다.

하네스는 처음부터 크게 짓는 것이 아니라, 반복되는 고통이 확인된 뒤에 붙여야 한다는 것.

하네스 엔지니어링이란 무엇인가

내가 여기서 말하는 하네스는 AI 코딩 에이전트가 일을 잘하도록 둘러싸는 작업 환경이다.

단순히 프롬프트를 잘 쓰는 것과는 조금 다르다.

예를 들어 하네스에는 이런 것들이 포함된다.

• 에이전트가 처음 읽어야 할 문서
• 프로젝트의 목표와 하지 말아야 할 것
• 작업을 나누는 기준
• 이슈와 브랜치 생성 규칙
• 커밋 메시지 규칙
• PR 템플릿
• 리뷰 기준
• 실패 기록 방식
• 어떤 문서를 언제 읽을지 정하는 context loading 규칙

AI 코딩 에이전트에게는 "무엇을 하라"는 명령만큼이나 "무엇을 보게 할 것인가"가 중요하다.

안드레 카파시는 Software 3.0 시대를 이야기하며, 자연어 prompt가 새로운 형태의 프로그램처럼 작동한다고 설명했다. 관련 정리 글에서는 LLM을 일종의 운영체제에 비유하고, context window를 memory에 비유한다.

이 관점에서 보면 하네스 엔지니어링은 꽤 중요하다.

LLM에게 어떤 context를 제공할지, 어떤 규칙을 고정할지, 어떤 판단은 사람에게 넘길지를 설계하는 일이기 때문이다.

NeoLabHQ의 Context Engineering Kit이나 Muratcan Koylan의 Agent Skills for Context Engineering 같은 프로젝트들도 비슷한 문제의식에서 출발한다. 핵심은 agent가 긴 대화와 많은 문서 속에서 길을 잃지 않도록, 필요한 context만 고르고 관리하게 만드는 것이다.

즉 하네스는 분명히 필요하다.

다만 내가 직접 겪어보니 중요한 질문은 따로 있었다.

언제부터, 얼마나 적용할 것인가?

내가 겪은 문제: 프로젝트보다 하네스가 먼저 커졌다

내가 만든 구조는 기능적으로는 돌아갔다.

예를 들어 Claude에게 이런 식으로 명령할 수 있었다.

CLAUDE.md를 기준으로 시작해.
.claude/PROJECT.md와 command-router를 읽어.
No-Training MVP를 8개 작업으로 나눠줘.
Issue-first, worktree-first 흐름으로 진행해.

그러면 Claude는 작업을 잘 나눴다.

T1 입력 영상/프레임 샘플링
T2 SAM/SAM2 segmentation adapter
T3 depth/pose adapter mock 또는 interface
T4 masked back-projection
T5 object point cloud fusion
T6 oriented bbox 및 크기 측정
T7 evaluation log
T8 Open3D/Rerun visualization

문제는 첫 번째 구현 작업이 사실 그렇게 거창하지 않았다는 점이다.

T1은 단순히 입력 영상에서 프레임을 샘플링하고, 후속 단계가 사용할 manifest를 만드는 작업이었다.

이 정도라면 처음에는 아래 정도 구조로도 충분했다.

README.md
docs/PLAN.md
docs/DECISIONS.md
src/
tests/

그런데 나는 처음부터 agents, skills, rules, tasks, worktree, PR orchestration까지 붙였다.

그러다 보니 프로젝트 초반부터 이런 비용이 생겼다.

• 문서를 이해하는 데 시간이 든다.
• Claude가 읽어야 할 파일이 많아진다.
• 토큰 사용량이 커진다.
• 실제 구현보다 운영 구조를 관리하는 시간이 늘어난다.
• 내가 직접 프로젝트를 이해하기도 전에 자동화 구조를 이해해야 한다.

하네스가 나쁜 것은 아니었다.

하네스를 너무 일찍, 너무 많이 붙인 것이 문제였다.

자동화는 반복된 뒤에 붙여야 한다

이번 경험을 통해 기준을 하나 세웠다.

자동화는 반복되는 고통이 확인된 뒤에 붙인다.

자동화를 붙이기 좋은 순간은 대략 이런 경우다.

1. 같은 일을 3번 이상 반복했다.
2. 실수했을 때 비용이 크다.
3. 형식이 거의 고정되어 있다.
4. 사람이 매번 판단하지 않아도 된다.
5. 여러 작업자가 동시에 움직여 충돌 위험이 생겼다.

예를 들어 PR 템플릿은 초반부터 있어도 괜찮다.

PR을 만들 때마다 작업 요약, 관련 이슈, 변경 내용, 리뷰 포인트, 체크리스트를 적는 일은 반복적이고 형식도 고정되어 있기 때문이다.

반면 multi-agent orchestration은 처음부터 크게 넣을 필요가 없었다.

실제로 병렬 작업이 생기고, 같은 파일을 두 agent가 건드리고, 병합 순서를 고민해야 하는 상황이 왔을 때 도입해도 늦지 않았다.

실패 기록 시스템도 마찬가지다.

처음부터 거대한 failure memory 구조를 만들기보다, 같은 실패를 두세 번 반복했을 때 그때 durable note로 남기는 편이 더 자연스럽다.

다음 프로젝트에서는 어떻게 시작할 것인가

다음 프로젝트에서는 처음부터 큰 하네스를 만들지 않을 생각이다.

처음에는 아주 얇게 시작할 것이다.

README.md
CLAUDE.md
docs/
  PLAN.md
  DECISIONS.md
  LOG.md
src/
tests/

그리고 CLAUDE.md에는 딱 이 정도만 적을 것 같다.

# 작업 원칙

1. README.md와 docs/PLAN.md를 먼저 읽는다.
2. 현재 목표를 한 문장으로 확인한다.
3. 작업 범위를 작게 잡는다.
4. 파일을 만들기 전에 기존 구조를 확인한다.
5. 테스트 가능한 단위로 끝낸다.
6. 반복되는 절차가 3번 이상 나오면 자동화 후보로 docs/DECISIONS.md에 기록한다.
7. 새 agents/skills/rules 폴더는 사용자 승인 전 만들지 않는다.

이 정도면 초반 MVP에는 충분하다.

처음 한두 기능은 사람이 직접 흐름을 경험해야 한다.

그래야 진짜 병목이 보인다.

• 매번 테스트 명령을 까먹는가?
• PR 설명 작성이 반복되는가?
• 실험 로그 형식이 흔들리는가?
• 데이터 경로가 자주 꼬이는가?
• 리뷰 기준이 매번 달라지는가?

이런 고통이 실제로 확인되면 그때 자동화하면 된다.

하네스를 없애자는 뜻은 아니다

그렇다고 하네스를 만들지 말자는 뜻은 아니다.

오히려 AI 에이전트를 오래 쓰려면 하네스는 필요하다.

다만 하네스를 처음부터 완성형으로 만들 필요는 없다.

나는 앞으로 하네스를 이렇게 바라보려고 한다.

하네스는 프로젝트를 시작하기 위한 선행 조건이 아니다.
하네스는 프로젝트가 자라면서 생기는 반복 문제를 해결하는 장치다.

즉 처음부터 모든 것을 자동화하지 않는다.

먼저 직접 해본다.

반복되는 부분을 찾는다.

그 부분만 작게 자동화한다.

그리고 다시 프로젝트를 진행한다.

이 과정을 반복하면서 하네스가 자라게 둔다.

지금 프로젝트에 적용한다면?

현재 진행 중인 컴퓨터 비전 프로젝트에는 이미 꽤 큰 .claude/ 하네스가 만들어져 있다.

처음에는 이걸 아예 폐기할까도 생각했다.

하지만 지금은 완전 삭제보다 다른 방식이 더 낫다고 생각한다.

기존 하네스는 보관한다.
기본 작업 흐름에서는 읽지 않는다.
필요할 때만 꺼내 쓴다.

즉 .claude/는 고급 하네스 archive처럼 둔다.

기본 작업은 더 가볍게 간다.

프로젝트/
├── .claude/
│   ├── agents/          # 에이전트 정의 파일
│   │   ├── analyst.md
│   │   ├── builder.md
│   │   └── qa.md
│   └── skills/          # 스킬 파일
│       ├── analyze/
│       │   └── SKILL.md
│       └── build/
│           ├── SKILL.md
│           └── references/

그리고 필요할 때 폴더나 문서를 추가하면 된다.

• 같은 작업을 3번 이상 반복할 때, skills에 해당 스킬을 만들어 자동화한다.
• PR 충돌이나 병합 순서를 판단해야 할 때, agents에 PR충돌 전용 agent를 명시한다.
• 리뷰 기준이 흔들릴 때, 리뷰 기준을 하나씩 추가한다.

이렇게 하면 지금까지 만든 하네스를 버리지 않으면서도, 초반 MVP의 속도를 잃지 않을 수 있다.

결론: 좋은 하네스는 작게 시작한다

이번 경험으로 하네스 엔지니어링을 조금 다르게 보게 됐다. 하네스의 목적은 멋진 agent 시스템을 만드는 것이 아니다. 문서를 많이 만드는 것도 아니다. 처음부터 모든 과정을 자동화하는 것도 아니다.

하네스의 목적은 인간의 집중력을 지키는 것이다. AI가 코드를 빠르게 만들 수 있게 되면서 병목은 코딩 속도에서 검증, 맥락 관리, 의사결정으로 옮겨가고 있다. 그래서 context를 설계하는 일은 분명 중요하다. 하지만 중요한 것과 처음부터 크게 하는 것은 다르다.

내가 얻은 결론은 이렇다.

처음에는 수동으로 작게 만든다.
반복되는 고통을 관찰한다.
그 고통만 자동화한다.
구조는 필요해질 때 자라게 둔다.

하네스 엔지니어링은 자동화를 많이 붙이는 기술이 아니라, 언제 자동화하지 않을지를 아는 기술에 더 가깝다.

참고 자료

• Notes: Software Is Changing (Again)
• NeoLabHQ Context Engineering Kit
• Agent Skills: Context Engineering Framework for AI Agents
• Vibe coding과 Karpathy의 문제 제기

태그

AI코딩 ClaudeCode Codex ContextEngineering 하네스엔지니어링 VibeCoding 개발회고