첫 주에 배운 건 기능이 아니라 '구조'였다 — 에이전트·하네스·스킬 기초
2026.07.26
📝 한줄 요약
AI를 1년 넘게 써왔는데도 매번 같은 설명을 반복하고 있었습니다. 원인은 프롬프트를 못 써서가 아니라 에이전트 / 하네스 / 스킬이라는 세 층을 구분하지 못했기 때문이었습니다. 이 글은 그 세 가지를 비개발자 기준으로 정리한 OT용 입문 글입니다.
바쁘시면 이것만 읽어도 돼요:
에이전트 = 목표를 받아 스스로 도구를 골라 실행하고 결과까지 확인하는 실행자
하네스 = 그 에이전트가 일하는 판 — 무엇을 보여줄지, 뭘 쓰게 할지, 어디까지 허용할지
스킬 = 반복되는 일의 순서를 문서로 고정해 매번 같게 만드는 장치
가장 중요한 구분: "아는 것"과 "하는 순서"는 다르다. 규칙을 아무리 잘 적어놔도 순서가 없으면 매번 사람이 빈칸을 채우게 된다
결과가 안 좋을 때 프롬프트부터 고치지 말고 세 층 중 어디가 비었는지 먼저 볼 것
🎯 이런 분들께 도움돼요
ChatGPT·Claude를 매일 쓰지만 "에이전트"가 정확히 뭐가 다른지는 설명 못 하시는 분
같은 지시를 매번 다시 설명하고 있다고 느끼시는 분
"스킬 만들어보세요"라는 말은 들었는데 그게 왜 필요한지 모르겠는 분
비개발자인데 AI 자동화를 제대로 시작해보고 싶은 분
😫 문제 상황 (Before)
저는 AI에게 일을 시킬 때 늘 이런 식이었습니다.
작업 규칙을 문서로 아주 잘 정리해뒀습니다. 분량도 꽤 됩니다. 설정 파일에 "작업 전에 반드시 이 문서를 먼저 읽을 것"이라고 지시까지 걸어놨습니다.
그런데도 실제로 일을 시키면 매번 같은 설명을 다시 하고 있었습니다.
"이건 이렇게 분류해야 한다니까"
"아니 그 순서가 아니라"
"끝났다고 하기 전에 합계 맞는지 확인해야지"
문서를 더 자세히 쓰면 나아질 줄 알았는데, 자세히 써도 똑같았습니다. 뭔가 근본적으로 잘못 이해하고 있다는 느낌만 남았습니다.
1주차에 배운 건, 이게 글을 못 써서가 아니라 구조를 몰라서 생기는 현상이라는 것이었습니다.
🛠️ 사용한 도구
도구명: Claude Code
모델: Claude Opus
특이사항: 이 글은 특정 도구 사용법이 아니라, 어느 도구를 쓰든 통하는 개념 정리입니다
🔧 세 층으로 나눠 보기
1층. 에이전트 — "시키면 알아서 끝까지 가는 실행자"
챗봇과 에이전트의 차이는 지능이 아니라 범위입니다.
챗봇 | 에이전트 | |
|---|---|---|
하는 일 | 물으면 답을 준다 | 목표를 받으면 실행한다 |
도구 | 없음 (말로만) | 파일 읽기·쓰기, 검색, 외부 서비스 호출 |
끝나는 시점 | 답을 뱉으면 끝 | 결과를 확인하고 안 되면 다시 시도 |
나의 역할 | 질문자 | 의뢰인 겸 검수자 |
"엑셀 정리하는 방법 알려줘"는 챗봇에게 하는 말이고, "이 폴더 엑셀 3개 열어서 합치고, 합계 안 맞으면 어디가 틀렸는지 찾아줘"는 에이전트에게 하는 말입니다.
핵심은 에이전트는 중간에 스스로 판단한다는 점입니다. 그래서 잘 되면 정말 편하고, 잘못되면 엉뚱한 곳까지 혼자 가 있습니다. 그걸 통제하는 게 다음 층입니다.
2층. 하네스 — "에이전트가 일하는 판"
하네스(harness)는 원래 말에 씌우는 마구, 즉 힘을 방향에 맞게 쓰도록 잡아주는 장치입니다.
AI에서 하네스는 에이전트 본체가 아니라 그 주변을 둘러싼 환경 전체를 말합니다.
무엇을 보여줄까 — 이 에이전트가 지금 볼 수 있는 정보 (컨텍스트)
무엇을 쓰게 할까 — 파일, 검색, 외부 서비스 등 도구
어디까지 허용할까 — 삭제해도 되는지, 결제해도 되는지 같은 권한 경계
어떻게 시작하고 멈출까 — 실행 명령, 승인 절차, 중단 조건
같은 모델이라도 하네스가 다르면 결과가 완전히 달라집니다. "AI가 멍청하다"고 느껴지는 순간의 상당수는 모델이 아니라 하네스 문제입니다. 그 정보를 애초에 안 줬거나, 그 도구를 못 쓰게 해뒀거나, 언제 멈춰야 하는지를 안 정해준 겁니다.
비유하자면 — 에이전트가 신입 직원이라면, 하네스는 그 사람의 책상·사내 문서 접근권·출입증·결재선입니다. 사람이 아무리 유능해도 자료 접근이 막혀 있으면 일을 못 합니다.
3층. 스킬 — "일하는 순서를 문서로 고정하기"
여기가 제가 1주차에 가장 크게 걸린 부분입니다.
저는 규칙 문서를 잘 써두면 그게 곧 자동화라고 생각했습니다. 아니었습니다.
"아는 것"과 "하는 순서"는 다른 것이다.
컨텍스트(아는 것) — "A는 이렇게 분류한다", "B는 예외다" 같은 지식
스킬(하는 순서) — "① 파일 연다 → ② 이 조건으로 거른다 → ③ 이 규칙으로 매핑한다 → ④ 중복 확인한다 → ⑤ 합계가 맞아야 끝난 것으로 친다"
제 문서에는 ①번(지식)만 잔뜩 있었고 ②번(절차)이 통째로 비어 있었습니다. 그래서 에이전트는 매번 "무엇을 아는지"는 받지만 "어떤 순서로 일하고 언제 끝난 걸로 치는지"는 못 받았고, 그 빈칸을 매번 제가 말로 채우고 있었던 겁니다.
스킬은 그 빈칸을 문서 하나로 고정합니다. 최소한 이 네 가지가 들어갑니다.
언제 쓰나 — 이 스킬이 발동하는 상황 (그리고 쓰면 안 되는 상황)
뭐가 필요한가 — 없으면 진행하지 말고 되물어야 할 입력값
어떤 순서로 — 판단이 충돌할 때의 우선순위까지 포함
언제 끝인가 — 무엇이 확인돼야 완료로 치는지
특히 4번이 중요합니다. 완료 기준이 없으면 에이전트는 "다 했습니다"라고 말하고 멈춥니다. 검증까지가 절차에 들어가 있어야 진짜로 끝납니다.
세 층이 어떻게 맞물리나
[ 스킬 ] ← 이 일은 이런 순서로 한다
↓
[ 에이전트 ] ← 순서대로 실행하고 결과를 확인한다
↓
[ 하네스 ] ← 그러기 위해 뭘 보고, 뭘 쓰고, 어디까지 할 수 있나그래서 결과가 마음에 안 들 때 물어볼 질문은 "프롬프트를 어떻게 고치지?"가 아니라 이겁니다.
증상 | 의심할 층 |
|---|---|
필요한 정보를 모르는 채로 추측함 | 하네스 — 애초에 안 보여줬다 |
할 수 있을 것 같은데 안 함 | 하네스 — 도구·권한이 없다 |
매번 방식이 달라짐 / 같은 설명 반복 | 스킬 — 순서가 고정 안 됐다 |
다 했다는데 확인해보면 안 됨 | 스킬 — 완료 기준이 없다 |
엉뚱한 데까지 혼자 감 | 하네스 — 경계를 안 정했다 |
✅ 결과 (After)
인식이 바뀐 지점
항목 | Before | After |
|---|---|---|
결과가 나쁠 때 | 프롬프트를 다시 씀 | 세 층 중 어디가 비었는지 먼저 봄 |
규칙 관리 | 문서를 더 길게 씀 | 지식과 절차를 분리해서 씀 |
"다 했습니다" | 그대로 믿음 | 완료 기준을 미리 정해둠 |
반복 업무 | 매번 말로 설명 | 한 번 절차로 고정 |
제일 크게 남은 문장
문서를 더 자세히 쓴다고 자동화가 되지 않는다. 자세한 지식과 고정된 순서는 다른 물건이다.
💬 이 과정에서 배운 AI 활용 팁
효과적이었던 것
범위를 좁게 잡기 — 첫 스킬은 "전부 자동화"가 아니라 "이 한 건 처리"로 시작하는 게 낫습니다. 완료 기준이 선명해야 실패가 빨리 보입니다.
완료 기준을 먼저 정하기 — "무엇이 확인되면 끝인가"를 지시에 넣으면 결과 검수가 절반으로 줍니다.
막히면 그냥 물어보기 — AI가 멈춰 있으면 "지금 뭐가 부족해서 못 하고 있어?"라고 물으면 대개 정확히 대답합니다.
AI가 못 하는 구간은 내가 한 번만 해주기 — 자동화가 안 되는 지점에서 붙잡고 있기보다, 그 한 단계만 사람이 하고 나머지를 넘기는 게 훨씬 빠릅니다.
이렇게 하면 안 돼요
규칙을 길게 쓰면 알아서 될 거라고 기대하기 — 지식만 늘어나고 절차는 여전히 비어 있습니다.
민감한 데이터로 처음부터 시험하기 — 첫 실행은 반드시 가짜/샘플 데이터로. 저도 실제 금융 데이터는 아예 접근 대상에서 뺐습니다.
한 번에 다 자동화하려 하기 — 어디서 틀렸는지 알 수 없게 됩니다.
"저장했으니 알아서 쓰겠지" — 저장·발견·호출은 각각 다른 사건입니다. 만들어두는 것과 실제로 불려 나가는 것은 별개예요.
🌍 다른 업무에 적용한다면?
세 층 구분은 도구를 가리지 않습니다. 이렇게 바꿔 물으면 됩니다.
주간 보고서 — 매번 설명하는 형식·톤·필수 항목이 있다면 → 그건 스킬로 고정할 후보
데이터 정리 — 매번 "이 컬럼은 이렇게"를 반복한다면 → 매핑 규칙 + 검증 순서를 절차로
고객 문의 응대 — 답변 톤은 컨텍스트, 에스컬레이션 조건은 스킬
자료 조사 — 어디까지 찾고 언제 멈출지가 안 정해져 있으면 그건 하네스 문제
🚀 앞으로의 계획
매주 최소 1개, 실제로 반복하는 업무를 스킬로 옮기기
만든 스킬이 실제로 자동 호출되는지까지 확인하기 (만드는 것과 불리는 것은 다름)
완료 기준을 늘 문서 안에 넣어서, 검수를 사람이 매번 하지 않아도 되게 만들기
📋 재사용 가능한 프롬프트
프롬프트 1: 내 세션에 뭐가 실제로 들어와 있는지 보기 (하네스 점검)
지금 이 대화에서 네가 실제로 참고하고 있는 정보의 출처를 전부 나열해줘. 각각이 (1) 항상 들어오는 것인지 (2) 누가 읽어와야만 들어오는 것인지 구분해서 표로 보여줘. 추측하지 말고, 확실하지 않은 건 "모름"이라고 표시해줘.
프롬프트 2: 반복 업무를 스킬 후보로 바꾸기
내가 반복하는 업무는 [업무 이름]이야. 이걸 매번 설명하지 않으려면 어떤 절차 문서가 필요할지 아래 4개로 정리해줘. ① 언제 쓰는가 / 쓰면 안 되는 경우 ② 없으면 진행하면 안 되는 필수 입력값 ③ 실행 순서 (판단이 충돌할 때의 우선순위 포함) ④ 무엇이 확인되어야 "끝"인가 내가 안 알려준 부분은 지어내지 말고 질문으로 남겨줘.
프롬프트 3: 결과가 안 좋을 때 원인 층 찾기
방금 결과가 기대와 달랐어. 프롬프트를 고치기 전에 원인을 먼저 분류해줘. (A) 필요한 정보를 못 봤다 (B) 필요한 도구·권한이 없었다 (C) 순서가 정해져 있지 않았다 (D) 완료 기준이 없었다 어느 쪽인지 근거와 함께 말해주고, 그 층을 고치는 방법을 알려줘.
프롬프트 4: 안전 경계 먼저 긋기
이 작업을 시작하기 전에, 네가 절대 하면 안 되는 것부터 정하자. [예: 실제 데이터 조회, 파일 삭제, 외부 전송] 은 하지 말고, 필요하면 나에게 물어봐. 첫 실행은 샘플 데이터로만 진행해줘.
로그인하고 댓글을 남겨 주세요
AI를 이제 막 배우는 초보인 저도 이해가 쏙쏙 됐어요!!
특히 에이전트·하네스·스킬을 역할로 나눠 설명해주신 부분이 정말 와닿았습니다. 앞으로 결과가 아쉬울 때 무작정 프롬프트부터 고치지 않고, 어디가 비어 있는지 먼저 살펴봐야겠어요.
정성스러운 글 감사합니다!
유피테르님 글을 읽고 저도 모르게 무릎을 탁 쳤습니다. 저 역시 프롬프트에 규칙이나 지식만 잔뜩 채워 넣고서 왜 자꾸 삐걱대는지 답답해하던 참이었거든요. 특히 '아는 것'과 '하는 순서'는 완전히 다르다는 지적을 보는데 진짜 머리를 한 대 맞은 느낌이네요. 문제가 생겼을 때 무작정 프롬프트만 고칠 게 아니라 세 층 중 어디가 빠졌는지 찾아야 한다는 해결 실마리가 확실히 잡힙니다. 당장 제 작업 문서들 열어서 실행 순서랑 완료 기준부터 다시 정리해 봐야겠습니다.
에이전트를 실행자, 하네스를 일하는 판, 스킬을 고정된 일의 순서로 설명한 구분이 초보자 관점에서 아주 명확했어요. 특히 자세한 규칙을 많이 적는 것과 필수 입력·우선순위·완료 기준을 포함한 절차를 만드는 것은 다르다는 지점이, 왜 같은 설명을 반복하게 되는지 잘 풀어줬습니다.
이번 글은 개념과 진단 기준을 세운 단계라 실제 스킬의 호출과 검증 결과는 아직 남아 있어요. 다음에는 민감정보가 없는 반복 업무 한 건을 골라 네 가지 항목으로 스킬을 만든 뒤, 새 세션에서 자동으로 발견되는지와 일부러 필수 입력을 뺀 경우 완료하지 않고 질문하는지를 함께 보여주시면 세 층의 차이가 실행 증거로 이어질 것 같아요.
에이전트·하네스·스킬을 각각 실행자, 환경, 절차로 나눠 설명해주셔서 개념이 명확하게 정리됐습니다. 특히 지식과 실행 순서를 분리해야 한다는 부분이 반복 업무를 자동화할 때 가장 중요한 기준이라는 생각이 들었습니다.

"결과가 안 좋을 때 프롬프트부터 고치지 말고 세 층 중 어디가 비었는지 먼저 볼 것" — 이 한 문장이 이 글의 핵심이고, 처음 배우는 분들이 가장 자주 빠지는 함정을 짚어주고 있어요.
에이전트/하네스/스킬을 기능이 아니라 역할로 구분하셨고, 챗봇과 에이전트 차이를 "지능이 아니라 범위"라고 정리하신 부분도 정확해요. 같은 모델이라도 하네스가 다르면 결과가 달라진다는 것도요. 1주차에 이 구조를 이 정도 언어로 정리해두시면 나중에 막힐 때마다 여기로 돌아오게 될 거예요.
비개발자 기준으로 쓴 입문 글이라고 하셨지만, 개발자한테도 읽힐 만한 글이에요. 꼬리 탁! 치고 응원하고 갈게요 🐈⬛