AI 하네스란
AI 하네스(에이전트 하네스)는 모델의 답을 실제 일로 바꾸는 주변 소프트웨어입니다. 모델은 다음 할 일을 정하고, 하네스는 모델에 도구를 쥐여 주고 맥락을 넣어 주고 권한을 쥐고 행동을 검사하고 일어난 일을 기록합니다. Claude Code, Codex, Gemini CLI가 하네스이고, azet 에이전트도 하네스입니다. 이 글은 하네스의 구성과 고르는 기준을 설명합니다.
1. 모델과 하네스는 어떻게 다른가요?
모델은 글을 받아 글을 내놓습니다. 혼자서는 파일을 열거나 테스트를 돌리거나 버튼을 누르지 못합니다. 하네스가 반복 고리를 돌립니다. 모델에 과제와 현재 상태를 보여 주고, 도구를 부르게 하고, 그 도구를 실행해 결과를 보여 주고, 일이 끝나거나 사람이 정해야 할 때까지 되풀이합니다. 같은 모델을 써도 제품마다 크게 다른 이유는 하네스가 모델이 볼 것과 할 수 있는 것을 정하기 때문입니다. 이름은 말의 힘을 원하는 방향으로 쓰게 하는 마구(harness)에서 왔습니다.
2. 에이전트 하네스의 구성
| 구성 | 하는 일 | AZET에서는 |
|---|---|---|
| 도구 | 모델이 부를 수 있는 파일·터미널·브라우저·외부 서비스 | azet 에이전트가 실제 브라우저를 열고 조작(열기·클릭·입력·업로드·다운로드)하고, GitHub·데이터베이스·Notion 같은 MCP 서버를 연결 |
| 맥락과 기억 | 단계마다 모델이 보는 것과 작업 사이에 남기는 것 | azet 에이전트는 기억을 고칠 수 있는 일반 파일로 남기고, 비밀번호는 남기지 않음 |
| 권한 | 묻지 않고 해도 되는 범위 | azet 에이전트는 작업마다 읽기 전용·먼저 묻기·전체 권한, azet은 결제·게시가 승인을 기다림 |
| 가드레일 | 실행 전에 행동마다 검사 | Claude Code·Codex CLI 훅에 붙는 azet-guard |
| 검증 | 주장을 믿지 않고 결과를 확인 | 테스트를 안 돌리고 통과라고 하면 azet-guard가 되돌려 보냄 |
| 기록 | 무엇을 정하고 했는지 남김 | azet-guard의 덧붙이기 전용 감사 로그, azet 에이전트의 브라우저 단계별 화면 |
| 분업 | 일을 나눠 동시에 돌림 | azet 에이전트가 scout·planner·reviewer·worker 하위 에이전트에 나눠 맡기고, 일정에 맞춰 작업 시작 |
| 비용 관리 | 반복되는 맥락을 싸게 | azet 에이전트는 반복 입력을 공급사 캐시 가격으로 청구하고 작업마다 캐시 적중률을 보여 줌 |
3. 하네스 여러 개를 한 창에서
이미 하네스 구독을 여러 개 쓰는 사람이 많습니다. azet 에이전트는 자기 작업을 나란히 돌리면서 같은 프로젝트 폴더에 Claude Code, Codex, Gemini CLI, azet용 실제 터미널을 열어, 가진 구독을 한곳에 모읍니다. AZET Desktop은 이를 폰에서 합니다. Mac에 Claude Code나 Codex가 로그인돼 있으면 내 구독으로 돌리고, 작업 중 AZET 크레딧이 떨어지면 로그인돼 있고 여유가 있는 다른 AI가 이어서 합니다.
4. 이미 쓰는 하네스에 가드레일 붙이기
Claude Code와 Codex CLI는 훅(hook)을 열어 둡니다. 도구 호출 전후에 외부 코드가 그 호출을 검사할 수 있는 지점입니다. azet-guard가 이 훅을 씁니다. pipx install azet-guard로 설치한 뒤 모든 Claude Code 프로젝트에는 azet-guard install, 저장소 하나에는 azet-guard install --project .(팀과 공유하도록 커밋할 수 있는 설정 파일), Codex에는 azet-guard install --codex를 실행합니다. 규칙마다 거부·묻기·경고로 바꿀 수 있고, mode = "monitor"로 두면 막지 않고 할 일만 기록합니다.
5. 하네스 엔지니어링: 사람이 여전히 하는 일
하네스 엔지니어링은 에이전트가 일하는 환경을 설계하는 일입니다. 줄 도구, 따를 규칙, 실수를 잡을 검사를 정합니다. 실제로는 에이전트가 읽을 프로젝트 규칙을 적어 두고, 에이전트가 돌릴 수 있게 테스트와 타입 검사를 빠르게 유지하고, 어떤 행동에 사람이 필요한지 정하고, 문제가 생기면 기록을 읽는 일입니다. 모델은 알아서 좋아지지만, 하네스는 내가 다룰 수 있는 부분입니다.
6. AI 하네스를 고르는 기준
- 단계마다 보이나요? 브라우저 단계마다 화면을 보여 주는 하네스가 바로잡기 쉽습니다.
- 권한을 작업마다 정하나요? 조사는 읽기 전용, 수정은 먼저 묻기.
- 비밀값이 맥락에서 빠지나요? 가림 처리와 별도 계정이 있는지 보세요.
- 자기 주장을 확인하나요? 통과했다는 말보다 실제로 돈 테스트가 낫습니다.
- 모델을 바꿀 수 있나요? azet 에이전트는 AZET 크레딧으로 28개 모델을 쓰거나 Claude·GPT·Gemini·Grok 등 내 키를 넣어 씁니다.
자주 묻는 질문
에이전트 하네스가 뭔가요?
AI 모델 둘레에서 에이전트 고리를 돌리는 소프트웨어입니다. 모델에 도구·맥락·권한을 주고, 모델이 고른 행동을 실행하고 검사하고 기록합니다. Claude Code, Codex, Gemini CLI, azet 에이전트가 에이전트 하네스입니다.
하네스 엔지니어링이 뭔가요?
에이전트가 일하는 환경을 설계하는 일입니다. 도구와 규칙, 실수를 잡는 검사, 사람이 정할 지점을 정합니다.
하네스와 프레임워크는 같은 건가요?
조금 다릅니다. 프레임워크는 코드로 에이전트를 만드는 라이브러리이고, 하네스는 모델 둘레에서 실제로 돌아가는 시스템으로 코딩 에이전트처럼 완성된 앱인 경우가 많습니다. 프레임워크로 하네스를 만들기도 합니다.
Claude Code와 Codex를 한곳에서 쓸 수 있나요?
네. azet 에이전트는 자기 작업 옆에 Claude Code·Codex·Gemini CLI용 실제 터미널을 열고, AZET Desktop은 Claude Code나 Codex를 내 구독으로 돌리면서 폰에서 일을 보내게 합니다.
Claude Code에 가드레일을 붙이려면?
훅으로 붙입니다. azet-guard는 Claude Code와 Codex CLI용 무료 오픈소스 훅 묶음으로, 파괴적 명령을 막고 API 키를 모델에서 빼고 위험한 행동 전에 묻고 감사 로그를 남깁니다.
궁금한 점이 있나요? hello@azet.io로 보내 주시면 AZET 팀이 답합니다.