🧰 “컨텍스트는 에이전트의 연료다. 아껴 쓰는 자가 멀리 간다.”
에이전트가 한 번에 담을 수 있는 정보량은 정해져 있다. 컨텍스트 윈도우가 아무리 커져도, 복잡한 프로젝트를 한 번에 처리하기엔 항상 부족하다. 하네스 엔지니어링의 핵심은 이 한계를 어떻게 극복하느냐에 있다.
개념과 실전 사례를 살펴봤다면, 이 글에서는 당장 쓸 수 있는 3가지 도구와 이걸 조합해서 코드 리뷰를 자동화하는 파이프라인을 만드는 방법을 다룬다.
flowchart TB A["메인 에이전트<br/>(작업 지시·통합)"] -->|"상황별 참조"| B["스킬<br/>(지침·매뉴얼)"] A -->|"작업 위임"| C["서브 에이전트<br/>(코드 리뷰·QA)"] A -->|"맥락 복제"| D["포크<br/>(문서화·세부작업)"] style A fill:#ff6b35,color:#fff style B fill:#4ecdc4,color:#fff style C fill:#45b7d1,color:#fff style D fill:#96ceb4,color:#fff
1. 스킬(Skill): 에이전트의 사내 매뉴얼
무엇인가
스킬은 에이전트가 작업할 때 참고해야 할 지침, 라이브러리 사용법, 주의사항을 저장해두는 기능이다. 상황에 따라 동적으로 불러와지는 프롬프트라고 생각하면 된다.
어떻게 작동하나
프로젝트에서 사용하는 API 스펙을 스킬로 정의해두면, 관련 작업을 할 때 자동으로 참조된다. 매번 API 문서를 프롬프트에 복사해 넣을 필요가 없다. 에이전트가 필요한 순간에 필요한 지침만 스스로 찾아서 읽는다.
언제 쓰나
- 프로젝트 코딩 컨벤션을 에이전트에게 알려줘야 할 때
- 특정 라이브러리의 사용 규칙이 있을 때
- 팀 내 암묵적 규칙을 명시화할 때
3가지 도구 중 가장 단순하게 작동한다. 복잡한 설정 없이 마크다운 파일 하나로 시작할 수 있다.
2. 서브 에이전트(Sub-agent): 일 잘하는 부하직원
무엇인가
특정 작업을 하위 에이전트에게 위임하는 구조다. 메인 에이전트가 지시하면, 하위 에이전트는 별도 세션에서 작업을 수행하고 결과만 전달한 뒤 소멸한다.
왜 중요한가
메인 세션의 컨텍스트를 소모하지 않는다. 이게 핵심이다.
메인 에이전트가 직접 코드 리뷰를 하면, 리뷰 내용이 메인 세션의 컨텍스트를 차지한다. 나중에 다른 작업을 할 때 리뷰 내용이 방해가 될 수 있다. 서브 에이전트에게 리뷰를 맡기면, 결과(리뷰 요약)만 받고 서브 에이전트는 사라진다. 메인 세션은 깨끗하게 유지된다.
코드 리뷰에 특히 적합
서브 에이전트는 제3자의 시선으로 코드를 평가한다. 구현할 때의 맥락(왜 이렇게 했는지)에 얽매이지 않고, 코드 자체만으로 판단한다. 이건 사람 코드 리뷰어가 다른 사람의 코드를 리뷰할 때와 같은 원리다.
한계
“설명하느니 차라리 내가 하는 게 낫겠다” 싶을 때가 있다. 짧은 지시만으로 맥락을 충분히 전달하기 어려운 고관여 작업에는 서브 에이전트가 부적합하다. 이럴 땐 포크를 쓴다.
서브 에이전트를 RAG처럼 활용하는 팁
서브 에이전트에게 단순히 “리뷰해줘”라고만 하면 결과가 좋지 않다. 대신:
- 서브 에이전트가 작업 설계를 분석하여 관련 ADR(Architecture Decision Record) 항목만 추출
- 코드 컨벤션과 합쳐서 작업 특화 평가 기준 문서 자동 생성
- 구현 에이전트와 리뷰 에이전트가 같은 기준으로 코드를 생성하고 평가
이렇게 하면 근거 없는 취향 리뷰가 아니라, 팀이 합의한 기준에 기반한 일관된 리뷰가 가능해진다.
3. 포크(Fork): 기억을 복제하는 분신술
무엇인가
현재 대화 세션의 컨텍스트를 그대로 복제하여 새로운 분기를 만드는 기능이다. 동일한 이해도를 가진 상태에서 시작하기 때문에, 이전 맥락을 다시 설명할 필요 없이 곧바로 작업에 착수할 수 있다.
왜 필요한가
설계를 깊이 논의하거나 리서치를 진행한 뒤, 그 양질의 맥락을 보존한 채 후속 작업을 진행해야 할 때가 있다. 서브 에이전트는 맥락을 다시 전달해야 하지만, 포크는 복제이므로 전달 비용이 0이다.
적합한 작업
- 코드 리뷰 반영: 리뷰 피드백을 이해한 상태에서 수정
- 설계 의도 문서화: 설계 논의의 맥락을 보존한 채 문서 작성
- UX 세부 논의: 기획 맥락을 유지하면서 세부 사항 조정
절대 하면 안 되는 것
⚠️ 리뷰 반영 시 새 세션을 열지 마라.
많은 개발자가 리뷰를 반영할 때 새 세션을 연다. 절대 금물이다. 리뷰 반영은 반드시 보존된 메인 세션에서 해야 한다. 작업에 대해 가장 깊이 이해한 상태의 컨텍스트이기 때문이다. 새 세션을 열면 이 맥락이 유실되어, 정확한 판단이 어려워진다.
3가지 도구 선택 가이드
| 상황 | 선택 | 이유 |
|---|---|---|
| 일상적 지침 참조 | 스킬 | 가장 단순, 자동 참조 |
| 코드 리뷰, QA | 서브 에이전트 | 제3자 시선, 컨텍스트 절약 |
| 설계 문서화, 리뷰 반영 | 포크 | 맥락 보존하면서 분기 |
| 핵심 리뷰 반영 | 메인 세션 직접 | 가장 깊이 이해한 상태 유지 |
실전: 코드 리뷰 자동화 파이프라인
3가지 도구를 조합하면, 사람의 개입을 최소화한 코드 리뷰 파이프라인을 만들 수 있다.
파이프라인 구조
flowchart LR A["구현 에이전트<br/>코드 작성"] --> B["서브 에이전트<br/>평가 기준 생성"] B --> C["리뷰 에이전트<br/>코드 평가"] C -->|"피드백"| D["메인 세션<br/>리뷰 반영"] D -->|"확인"| E["완료"]
Step 1. 평가 기준 자동 생성 서브 에이전트가 작업 설계를 분석하여 관련 ADR 항목을 추출하고, 코드 컨벤션과 합쳐서 작업 특화 평가 기준 문서를 자동으로 만든다. RAG처럼 작동하는 셈이다.
Step 2. 구현·리뷰 에이전트가 같은 기준 사용 구현 에이전트는 이 기준으로 코드를 작성하고, 리뷰 에이전트는 같은 기준으로 코드를 평가한다. 기준이 명확하니까 “이건 제 취향인데요” 같은 논쟁이 사라진다.
Step 3. 피드백은 메인 세션에서 반영 리뷰 결과는 반드시 메인 세션에서 반영한다. 작업에 대해 가장 깊이 이해한 컨텍스트가 있기 때문이다.
AI 코드 리뷰가 부족한 이유
대부분의 AI 코드 리뷰가 아직 사람 수준에 못 미치는 이유는 두 가지 맥락 공백 때문이다:
- 깔끔한 코드 기준이 문서화되지 않음: 팀이 암묵적으로 공유하지만 명시적으론 없는 기준
- 설계자의 구체적 의도 불명확: 여러 구현 방법 중 왜 이 방식을 선택했는지
이 두 가지를 문서화하면 AI 코드 리뷰의 품질이 극적으로 향상된다.
필요한 문서 2가지
① 코드 컨벤션 (code-convention.md) 변수명 규칙, 에러 처리 방식, 파일 구조 등 조직의 코딩 스타일 지침. 프레임워크 표준을 따르는 뻔한 내용은 빼고, 조직 고유의 규칙만 기록한다.
② ADR (Architecture Decision Record) 어떤 상황에서 어떤 아키텍처 결정을 했고, 그 이유는 무엇인지를 기록. 개인 개발자도 AI를 위해 ADR을 작성하는 게 좋다. 에이전트가 “왜 이렇게 했지?”를 이해하면 리뷰 품질이 달라진다.
튜닝 목표
“개발자가 AI 리뷰와 사람 리뷰를 구분하지 못할 때까지 반복적으로 파이프라인을 튜닝한다.”
이 수준에 도달하면 사람은 코드 리뷰에서 완전히 벗어나, 문제 정의와 설계에만 집중할 수 있다. 개발 프로세스의 가장 큰 병목이 사라지는 것이다.
세션 관리의 황금 규칙
도구를 아는 것과 제대로 쓰는 것은 다르다. 세션 관리의 핵심 원칙을 정리한다.
-
메인 세션은 티켓(기능) 단위로 생성하고 관리한다. 영원히 유지되는 세션이 아니라, 하나의 기능 단위로 만들고 끝내면 정리한다.
-
1차 구현 완료 시 메인 세션 컨텍스트 40% 소모가 이상적이다. 너무 많이 쓰면 나중에 리뷰 반영할 여유가 없고, 너무 적게 쓰면 충분히 깊이 작업하지 못한 것이다.
-
부수 작업은 포크하여 별도로 진행한다. 작업 명세 작성, QA, 문서화는 포크로 분기해서 메인 세션의 컨텍스트를 보호한다.
-
메인 세션의 컨텍스트는 리뷰 검토 및 반영을 위해 보존한다. 이게 가장 비싼 자원이다. 함부로 소모하지 않는다.
입문자를 위한 조언
이 모든 걸 당장 적용할 필요는 없다.
하네스 구축보다 **“무엇을 만들 것인가”**가 더 중요하다. 아이디어가 아직 모호하거나 검증되지 않은 단계라면, 하네스에 시간을 쓰지 말고 결과물을 빠르게 만들어 피드백을 받아라. Replit이나 Lovable 같은 서비스는 이미 하네스가 내장되어 있어, 복잡한 설정 없이도 바로 시작할 수 있다.
하지만 크고 복잡한 작업을 높은 품질로 완수해야 한다면, 이 도구들을 조합한 하네스가 생산성을 몇 배로 끌어올려준다. 개발자는 문제 정의와 설계에 집중하고, 구현과 검증의 반복은 에이전트에게 맡기는 세계. 하네스 엔지니어링이 그 세계를 현실로 만든다.
전체 개요 → 하네스 엔지니어링 가이드
참고