1. 채팅창 밖으로 나간 AI

지금까지 다룬 프롬프트와 컨텍스트는 모두 사람이 채팅창에 무언가를 입력하면, AI가 그 입력을 보고 글로 답하는 구조 안에서의 이야기였습니다. 모델은 보고만 있을 뿐 직접 손을 움직이지 않습니다.

그런데 2024년 후반부터 분위기가 바뀝니다. AI가 파일을 직접 읽고, 코드를 직접 고치고, 터미널 명령을 직접 실행하기 시작했습니다. Claude Code, Cursor의 Agent 모드, OpenAI Codex CLI, Devin 같은 도구들이 차례로 등장하면서 "AI에게 시키면 알아서 한다"는 말이 실제 풍경이 되었습니다.

이때 AI가 일을 잘하느냐 못하느냐를 결정하는 변수는 더 이상 단일 프롬프트나 컨텍스트가 아닙니다. AI가 어떤 도구를 가지고 있는지, 일이 잘못됐을 때 어떻게 되돌리는지, 사람이 어디서 개입할 수 있는지 같은 환경 전체의 설계가 결과를 좌우합니다. 이걸 통칭하는 단어가 하네스 엔지니어링입니다.

1장에서 "하네스 = 말 장구" 비유와 Mitchell Hashimoto, Birgitta Bockeler의 이야기를 다뤘으니, 여기서는 비유는 건너뛰고 곧바로 실제로 어떤 부품들이 모여 하네스를 이루는지 들여다봅니다.

2. 프롬프트·컨텍스트와의 관계

세 가지를 회사 안에서 사람이 일하는 모습에 빗대보면 관계가 한눈에 잡힙니다.

세 가지는 배타적이지 않고 포함 관계에 가깝습니다. 하네스 안에 컨텍스트가 들어가고, 그 안에 매번의 프롬프트가 들어갑니다.

ChatGPT의 채팅창만 쓸 때는 사실상 프롬프트만 다룹니다. CLAUDE.md를 깔고 RAG를 붙이면 컨텍스트 영역까지 손이 닿습니다. 그리고 AI가 도구를 호출하면서 자율적으로 일을 풀어가게 만들면, 그때부터 하네스 엔지니어링의 영역입니다.

3. 하네스가 다섯 부품으로 이루어지는 이유

위 그림의 다섯 부품(도구·워크플로우·가드레일·오케스트레이션·평가)은 한 사람이 만들어낸 분류가 아니라, 현장에서 자율 에이전트를 만들다가 빠짐없이 부딪치는 다섯 가지 문제에 가깝습니다. 하나씩 짧게 봅니다.

3.1 도구 (Tools)

AI 혼자서는 외부 세계를 보지 못합니다. 그래서 함수 호출(Function Calling) 또는 그것을 표준화한 MCP(Model Context Protocol)를 통해 외부에 손을 뻗을 도구를 쥐여줍니다.

도구는 무엇이든 될 수 있습니다.

도구를 무엇을, 얼마나 위험한 수준까지 쥐여줄지 결정하는 일 자체가 하네스 설계의 핵심 의사결정입니다. 5-2와 5-3에서 자세히 다룹니다.

3.2 워크플로우 (Workflow)

작업이 한 번의 도구 호출로 끝나지 않을 때 필요합니다. "코드 작성 → 테스트 실행 → 실패하면 다시 작성"처럼 순서, 분기, 반복을 정해두는 일입니다. Anthropic이 2024년 12월에 발표한 Building Effective Agents 가이드는 자주 쓰이는 워크플로우 패턴을 5가지로 정리했는데, 5-2에서 살펴봅니다.

3.3 가드레일 (Guardrails)

AI가 자유롭게 도구를 호출하기 시작하는 순간 사고의 종류와 비용이 바뀝니다. 잘못된 SQL이 운영 DB에서 돌면 끝이고, 잘못된 명령이 운영 서버에서 돌아도 끝입니다. 가드레일은 그 사고를 줄이거나 막는 장치들입니다.

• 입력 단: 프롬프트 인젝션 차단, 길이·민감정보 검증
• 출력 단: JSON 스키마 검증, 유해 내용 차단, 사실 검증
• 실행 단: 위험 명령 사람 승인, 비용·횟수 상한, 타임아웃

3.4 오케스트레이션 (Orchestration)

한 AI가 모든 일을 다 하기 시작하면 곧 한계가 옵니다. 컨텍스트가 너무 길어지거나, 너무 다양한 일을 시켜서 품질이 떨어집니다. 그래서 전문화된 여러 에이전트를 두고 한 명이 다른 에이전트들을 부르며 일을 진행시키는 구조가 자주 쓰입니다. 5-2에서 단일 vs 멀티 에이전트 트레이드오프를 짧게 정리합니다.

3.5 평가·모니터링

이건 가장 자주 빠뜨리는 부품인데, 빠뜨리는 순간 시스템이 망가져도 망가진 줄을 모르게 됩니다. 도구 호출 로그, 비용·지연 지표, "이번 답이 좋았는지"를 사람이 라벨링할 수 있는 자리. 이 세 가지를 처음부터 같이 깔아두는 일이 장기적으로 가장 중요합니다.

4. 가까운 사례, Claude Code

이론보다 실물을 한 번 보는 게 빠릅니다. Claude Code는 위 다섯 부품이 모두 들어 있는 가장 손에 닿는 하네스 사례입니다. (이 책의 코드 예시 검증에도 사실 Claude Code가 쓰였습니다.)

• 도구. 파일 읽기·쓰기·편집, Bash 명령, 웹 검색, Glob·Grep 같은 코드 탐색 도구.
• 컨텍스트. 4장에서 본 CLAUDE.md를 매 세션에 자동 로드, 추가로 git 상태와 작업 디렉토리.
• 가드레일. 파일 수정 권한 확인, rm -rf처럼 위험한 명령은 실행 전 사용자에게 묻기, 토큰 비용 표시.
• 워크플로우. "Plan 모드에서 먼저 계획을 보여주고 사용자 승인을 받은 뒤 구현" 같은 패턴이 내장.
• 오케스트레이션. 큰 작업을 받으면 자체적으로 서브 에이전트를 호출(예: 코드 탐색 전용 Explore 에이전트).

Cursor의 Agent 모드, OpenAI Codex CLI, JetBrains의 AI Assistant도 부품 이름과 구성은 조금씩 달라도 같은 다섯 부품을 갖춰가고 있습니다. 그러니까 "이 도구가 좋은가 나쁜가"를 판단할 때 우리는 위 다섯 칸을 채점표로 쓸 수 있게 됩니다.

이어서 이 다섯 부품 중 도구·워크플로우·가드레일·오케스트레이션을 어떻게 직접 설계하는지, Anthropic의 5가지 워크플로우 패턴을 곁들여 자세히 다룹니다.