모델을 에이전트로 만드는 요소

/model로 모델을 바꾸고 같은 작업을 다시 요청했더니 답변이 달라졌습니다. 하지만 에이전트는 여전히 CLAUDE.md를 읽고, 명령을 실행하기 전에 똑같이 권한을 묻고, hook도 이전처럼 작동합니다. 결국 이런 요소는 모델 자체에 포함된 것이 아닙니다.

모델과 모델을 둘러싼 프로그램의 경계를 살펴보겠습니다. 에이전트가 실수할 때 무엇을 확인해야 할지 알 수 있습니다.

모델과 하네스

모델은 전달받은 컨텍스트를 처리해 답변하거나 도구 호출을 요청합니다. 예를 들어 어떤 파일을 읽고 어떤 명령을 실행할지 선택합니다. 이런 작업을 실행하려면 모델 주변에 프로그램이 필요합니다. 이 프로그램이 파일에 접근하고 명령을 실행한 뒤 그 결과를 모델에 돌려줍니다.

영어 자료에서는 이런 프로그램을 harness라고 부릅니다. 원래 뜻은 "마구"(네, 말에 채우는 바로 그 장비)인데, 한국어로는 그대로 하네스라고 부르는 편이 편합니다. Anthropic 문서의 설명도 분명합니다. Claude Code는 하네스이고, Claude는 그 안에서 작동하는 모델입니다. 에이전트 전반을 다루는 글에서도 자주 나오는 용어니 기억해 두세요.

그림의 하네스는 컨텍스트를 모으고 권한을 확인하며 모델의 도구 호출을 실행합니다. 모델 아래의 화살표는 루프를 나타냅니다. 도구 결과가 컨텍스트로 돌아오면 모델은 다음 단계를 선택하거나 답변을 마칩니다. 답변이 끝났다고 해서 작업이 완료된 것은 아니므로 결과를 확인해야 합니다.

이미 설정해 본 구성 요소

Claude Code에서 하네스의 각 부분은 다음과 같이 드러납니다. 오른쪽 열의 파일과 명령을 통해 프로젝트나 세션에서 각 메커니즘을 찾을 수 있습니다.

CLAUDE.md와 skills는 모델에 지침을 제공합니다. 모델은 규칙을 잘못 이해하거나 놓칠 수 있습니다. 권한 확인과 설정된 hooks의 명령은 프로그램으로 실행되므로, 결과는 지정된 조건과 명령 자체에 따라 달라집니다.

Plugins는 표에서 빠졌습니다. 별도의 구성 요소가 아니라 여러 skills, 명령 또는 hooks를 한 번에 설치하는 묶음이기 때문입니다.

같은 모델, 다른 동작

프로젝트나 터미널에 연결되지 않은 웹 채팅을 생각해 보세요. 이런 채팅에도 나름의 하네스가 있습니다. 대화 기록과 인터페이스, 때로는 웹 검색이나 파일 업로드 기능입니다. 이런 채팅에서는 모델이 수정 방법을 설명하고 코드를 보여 줄 수 있지만, 프로젝트에 접근할 수 있는 Claude Code는 실제 파일을 수정할 수 있습니다. 모델은 같아도 주변 프로그램이 다르면 할 수 있는 일이 달라집니다.

/model은 반대 상황입니다. 모델은 바뀌지만 하네스는 그대로이므로 규칙, 도구, 권한 요청은 계속 유지됩니다.

작업을 어떻게 이해하고 어떤 도구를 고르며 그 결과를 어떻게 평가하는지는 모델에 달려 있습니다. 하네스는 컨텍스트를 모으고 도구를 제공하며 권한을 확인합니다. 예를 들어 모델이 필요한 파일을 요청하면 하네스가 파일을 읽고 내용을 돌려줄 수 있습니다.

에이전트가 실수할 때 손볼 부분

한 번의 실수라면 "그 파일이 아니야, src/utils.js를 봐 줘"라고 한마디로 바로잡으면 됩니다. 같은 실수가 세션마다 반복된다면 지침과 사용 가능한 데이터를 확인해 보세요. 필요한 규칙을 매번 새로 설명해야 하는 상황일 수 있습니다.

실제로는 대략 이런 식으로 원인을 찾을 수 있습니다.

• 에이전트가 세션마다 프로젝트 규칙을 잊습니다. 예를 들어 테스트는 npm test로 실행한다는 규칙을 잊는다면 CLAUDE.md에 적어 두세요. 중요한 규칙은 대화 중에 다시 알려 주기보다 파일에 명시하는 편이 확실합니다.
• 같은 절차를 벌써 세 번째로 설명하고 있습니다. 이제 skill로 옮길 때입니다. 에이전트가 작업에 맞는 지침을 불러올 수 있습니다. 작업 중 skill이 호출됐는지 확인하고, 호출되지 않았다면 실제 이름을 넣어 /skill-name으로 직접 실행하세요.
• 에이전트가 갖고 있지 않은 데이터를 추측합니다. 필요한 데이터를 전달하세요. @로 파일을 컨텍스트에 추가하거나 MCP로 외부 서비스를 연결할 수 있습니다. 추측을 설득으로 고칠 수는 없습니다.
• 에이전트가 검증을 실행하지 않고 "완료"라고 합니다. Stop 이벤트의 hook이 모델 판단 없이 테스트를 실행하도록 설정할 수 있습니다. 결과는 보고서가 아니라 명령 출력으로 확인하고, 최종 판단은 직접 내리세요.
• 필요한 데이터에 접근했고 실제로 읽었는데도 에이전트가 복잡한 추론에서 헷갈립니다. /model로 다른 모델을 선택해 같은 작업의 결과를 비교해 보세요.