화면 모드
하네스란
하네스는 에이전트가 작업하는 환경 전체다. 모델이 무엇을 읽고, 무엇을 실행할 수 있고, 결과를 어떻게 검증할지 정하는 주변 장치를 묶은 것이다. 같은 모델이라도 어떤 하네스를 붙이느냐에 따라 작업 결과가 달라진다.
하네스의 정의
하네스는 다음을 결정하는 환경이다.
- 어떤 컨텍스트를 언제 제공할 것인가.
- 어떤 프롬프트와 함께 전달할 것인가.
- 어떤 도구를 실행할 수 있게 할 것인가.
- 무엇을 금지하고 어떤 권한을 줄 것인가.
- 결과를 어떤 기준으로 검증할 것인가.
모델은 기본 능력이고, 하네스는 그 능력을 작업에 맞게 쓰게 하는 장치다. 프롬프트 한 줄을 잘 다듬는 일보다 필요한 정보와 도구와 검증을 어떻게 배치할지가 결과를 더 크게 좌우한다.
하네스가 비어 있으면 같은 설명을 계속 반복하게 된다.
- 룰이 없으면 같은 주의를 작업마다 다시 말한다.
- 스킬이 없으면 긴 절차를 매번 프롬프트에 붙여 넣는다.
- 검증이 없으면 잘못된 결과를 사람이 직접 찾아야 한다.
맡기고 고치는 순서
하네스를 처음부터 완벽하게 설계하려 들 필요는 없다. 과정을 전부 이해한 뒤 시작하기보다, 지금 할 수 있는 형태로 맡기고 결과를 보고 고치는 편이 빠르다.
- 맡길 작업을 정해 런타임에 그대로 요청한다.
- 결과와 막힌 지점을 확인한다.
- 반복될 내용만 룰·스킬·문서로 남긴다.
- 모든 기능을 미리 익히려 하지 않는다. 도구가 바뀌는 속도가 배우는 속도보다 빠르므로, 필요할 때 확인해 필요한 만큼만 하네스에 반영한다.
같은 지적이 두 번 나오면 문장 하나를 만들어 하네스에 넣는다. 예를 들어 ‘빌드 없이 커밋하지 않는다’는 룰 한 줄로, ‘릴리스 배포 절차’처럼 긴 순서는 스킬 하나로 만든다. 다음 작업부터는 같은 설명을 반복하지 않아도 된다.
런타임에게 하네스 초안 자체를 맡길 수도 있다. 예를 들어 프로젝트 폴더에서 이렇게 요청한다.
text
이 저장소의 빌드·테스트·커밋 절차를 정리해 AGENTS.md 초안을 만들어 줘.
지금 확인한 내용만 적고, 확실하지 않은 항목은 '확인 필요'로 표시해.초안은 그대로 쓰지 않고 검토한다. 확인되지 않은 내용이 사실처럼 남는 것을 막는 절차다.
하네스를 이루는 요소
| 요소 | 하는 일 | 자세히 |
|---|---|---|
| 룰 | 매 작업에 항상 적용되는 짧은 규칙 | 룰 |
| 스킬 | 필요할 때만 읽는 절차 문서 | 스킬 |
| 문서 | 요구사항·설계·결정 기록 | 문서 |
| 메모리 | 세션 사이에 남는 개인 기억 | 메모리 |
| 권한·샌드박스 | 실행 범위와 승인 경계 | 보안, 세팅 |
| 훅 | 이벤트 시점의 자동 실행 | 훅 |
| MCP | 외부 서비스를 도구로 연결 | MCP |
| 서브에이전트 | 작업을 나눠 맡기는 보조 에이전트 | 서브에이전트 |
| 검증 | 테스트·빌드·린트로 결과 확인 | 검증 |
모두 처음부터 갖출 필요는 없다. 반복되는 문제가 생길 때마다 해당 요소를 하나씩 추가한다.
| 반복되는 문제 | 먼저 손볼 요소 |
|---|---|
| 같은 실수를 매번 다시 지적한다 | 룰 |
| 매번 같은 절차를 길게 설명한다 | 스킬 |
| 결정 이유가 사라져 다시 논의한다 | 문서 |
| 깨진 결과가 뒤늦게 발견된다 | 검증 |
요소를 늘리는 것 자체가 목적은 아니다. 문제가 줄어드는지로 효과를 확인한다.
시작 순서
세팅을 먼저 하고, 룰과 검증으로 기본을 잡은 뒤 스킬과 문서를 더한다.
- 세팅: 권한 범위를 좁히고 화면을 정리한다. 사고를 막는 안전장치가 먼저다.
- 룰: 커밋·배포·금지 사항처럼 매번 적용할 것만 짧게 적는다.
- 검증: 타입 오류처럼 테스트로 잡을 수 있는 것은 자동 확인에 맡긴다.
- 스킬: 룰에 넣기엔 긴 절차를 분리한다.
- 문서: 결정과 과정을 기록해 다음 작업이 읽을 양을 줄인다.
이후에는 필요할 때 훅, MCP, 서브에이전트, Effort 같은 심화 요소를 더한다. 작업 순서와 분할은 herdr 오케스트레이션에서 다룬다.
프롬프트보다 환경 구성
프롬프트와 컨텍스트가 없어진 것은 아니다. 매번 사람이 요청 문장을 미세하게 조정하기보다, 룰·스킬·문서·테스트로 필요한 정보를 구조화해 관리하는 비중이 커졌다는 뜻이다. 프롬프트·컨텍스트·모델의 구분은 컨텍스트와 프롬프트에서 다룬다.
보충: 에이전트 프레임워크를 직접 쓰는 경우
LangChain, LangGraph, Pydantic AI, Spring AI 같은 프레임워크로 에이전트를 직접 만들 수도 있다. 이미 있는 코딩 에이전트에 일을 맡기는 경우에는 거의 필요하지 않다. 다만 앱 안에서 RAG, 컨텍스트 관리, 프롬프트 템플릿을 다룰 때는 이런 도구가 여전히 유용하다. RAG는 검색으로 찾은 자료를 컨텍스트에 넣는 방식이다.