본문으로 건너뛰기

OpenClaw 하네스, AGENTS.md, Skills, MCP, Hooks 공부 가이드

문서 목적​

이 문서는 OpenClaw를 팀에 설명하거나 실제 실무에 적용하기 전에, 하네스와 주요 구성요소를 쉽게 이해할 수 있도록 정리한 공부용 문서입니다.

한 줄 요약​

OpenClaw를 잘 쓰려면 단순히 프롬프트를 잘 쓰는 것만으로는 부족하고, AI가 실제로 일할 수 있는 환경 전체를 설계하는 관점이 필요합니다.

1. 하네스란 무엇인가​

하네스는 쉽게 말하면 AI가 실제로 일할 수 있도록 묶어놓은 실행 환경입니다.

AI가 실무에서 안정적으로 동작하려면 단순한 질문 하나만으로는 부족합니다. 아래 요소들이 같이 필요합니다.

  • 어떤 역할로 일할지
  • 어떤 규칙을 따를지
  • 어떤 문서를 먼저 읽을지
  • 어떤 도구를 사용할지
  • 어떤 외부 시스템과 연결될지
  • 어떤 시점에 자동으로 개입할지

이런 것들을 함께 묶은 구조를 하네스라고 볼 수 있습니다.

쉽게 비유하면​

  • 프롬프트 = “이 일 해줘”라고 요청하는 문장
  • 하네스 = 그 사람이 일할 수 있게 책상, 문서, 도구, 규칙을 다 갖춰준 환경

즉, 프롬프트는 요청이고, 하네스는 작업 환경입니다.

2. AGENTS.md란 무엇인가​

AGENTS.md는 에이전트의 기본 행동 원칙과 작업 방식을 정의하는 문서입니다.

예를 들면 이런 내용이 들어갑니다.

  • 어떤 태도로 응답할지
  • 무엇을 하면 안 되는지
  • 어떤 파일을 먼저 읽을지
  • 민감정보나 권한은 어떻게 다룰지
  • 그룹 채팅과 개인 채팅에서 어떻게 다르게 행동할지

왜 중요한가​

AGENTS.md가 있으면 AI의 응답 스타일과 행동 기준이 흔들리지 않습니다. 사람으로 치면 팀 온보딩 문서 + 업무 수칙에 가깝습니다.

한 줄 정리​

AGENTS.md = 이 AI가 우리 팀에서 어떻게 일해야 하는지 정한 기본 운영 문서

3. Skills란 무엇인가​

Skills는 에이전트가 특정 업무를 할 때 불러오는 전문 작업 매뉴얼입니다.

예:

  • 회의록 정리
  • Slack 운영
  • 코딩 보조
  • 문서 작성
  • 날씨 조회

어떻게 동작하나​

  1. 에이전트는 먼저 skill의 이름과 설명을 봅니다.
  2. 현재 작업과 관련 있다고 판단하면 해당 SKILL.md를 읽습니다.
  3. 그 안의 상세 지침을 따라 작업합니다.

왜 중요한가​

모든 작업 지침을 기본 프롬프트에 넣으면 너무 길고 무거워집니다. Skills를 쓰면 필요할 때만 전문 지침을 불러와서 더 정확하게 일할 수 있습니다.

한 줄 정리​

Skills = 특정 업무를 표준화한 재사용 가능한 작업 지침

4. MCP란 무엇인가​

MCP는 AI가 외부 도구나 시스템과 연결될 수 있도록 도와주는 표준 인터페이스입니다.

OpenClaw에서는 MCP 서버를 관리하고, 필요하면 채널이나 기능을 MCP로 노출할 수 있습니다.

쉽게 말하면​

AI가 다른 프로그램과 대화하는 방식을 일정하게 맞춰주는 규칙입니다.

왜 중요한가​

  • 외부 도구 연결 구조를 표준화할 수 있음
  • 시스템 연동이 쉬워짐
  • 추후 확장성이 좋아짐

한 줄 정리​

MCP = AI와 외부 시스템을 연결하는 표준 통로

5. Hooks란 무엇인가​

Hooks는 특정 시점에 자동으로 개입하는 체크포인트 또는 자동 동작 규칙입니다.

예:

  • 어떤 메시지가 들어왔을 때
  • 어떤 조건을 만족했을 때
  • 작업 전 또는 후에

자동으로 검사, 보조, 정리 같은 작업을 끼워 넣을 수 있습니다.

왜 중요한가​

사람이 매번 직접 하지 않아도 되는 반복 작업을 자동화할 수 있기 때문입니다.

한 줄 정리​

Hooks = AI 동작 흐름 중간에 자동으로 들어가는 보조 규칙

6. 네 가지 관계를 한 번에 보면​

  • AGENTS.md = 기본 행동 원칙
  • Skills = 업무별 전문 매뉴얼
  • MCP = 외부 도구 연결 방식
  • Hooks = 자동 개입 규칙
  • Harness = 이 모든 것을 묶어 AI가 실제로 일하게 하는 운영 구조

7. 발표할 때 이렇게 설명하면 좋다​

AI를 팀에서 제대로 쓰려면 질문만 잘 쓰는 걸로는 부족합니다. 역할을 정의하는 AGENTS.md, 특정 업무를 표준화하는 Skills, 외부 도구를 연결하는 MCP, 자동 개입 규칙인 Hooks가 필요합니다. 그리고 이 전체를 실제로 일하는 구조로 묶는 것이 Harness입니다.

8. 먼저 보면 좋은 자료​

핵심 문서​

  • AGENTS.md
  • docs/agent-docs-index.md
  • docs/agent-routing-guide.md
  • docs/openclaw-agent-ops.md

Skills 이해용​

  • paperclip/docs/guides/agent-developer/writing-a-skill.md

동작 구조 이해용​

  • paperclip/docs/guides/agent-developer/how-agents-work.md
  • paperclip/docs/agents-runtime.md
  • paperclip/docs/api/agents.md

운영 관점 자료​

  • docs/agent-session-design.md
  • docs/agent-known-issues-and-checklist.md

명령 참고​

  • openclaw mcp --help
  • openclaw hooks --help

9. 공부 추천 순서​

  1. 하네스 개념 이해
  2. AGENTS.md 읽기
  3. Skills 구조 이해
  4. Agent 라우팅 문서 보기
  5. MCP와 Hooks 역할 이해
  6. 실제 팀 업무에 어떻게 붙일지 생각해보기

10. 계속 이어서 볼 수 있는 공부 체크리스트​

아래 순서대로 보면, 중간에 끊겼다가 다시 와도 어디까지 봤는지 확인하기 쉽습니다.

1단계. 큰 개념 잡기​

  • 하네스가 무엇인지 이해하기
  • 프롬프트와 하네스의 차이 이해하기
  • AGENTS.md, Skills, MCP, Hooks를 한 번에 구분하기

2단계. AGENTS.md 이해하기​

  • AGENTS.md가 기본 운영 문서라는 점 이해하기
  • 무엇을 먼저 읽을지, 무엇을 하면 안 되는지 정하는 구조 이해하기
  • 우리 팀용 AGENTS.md에는 어떤 항목이 필요할지 생각해보기

3단계. Skills 이해하기​

  • Skills가 필요한 이유 이해하기
  • SKILL.md의 name, description 역할 이해하기
  • 반복 업무를 Skill로 빼면 좋은 사례 떠올려보기

4단계. MCP와 Hooks 이해하기​

  • MCP가 외부 시스템 연결용이라는 점 이해하기
  • Hooks가 자동 개입 규칙이라는 점 이해하기
  • 둘의 차이를 실무 예시로 설명할 수 있게 정리하기

5단계. 영빈님 업무에 연결하기​

  • Slack 역할별 채널을 에이전트 구조로 설명해보기
  • 회의록 정리, 주간보고 자동화, 메디사이트 전환을 어떤 Skill로 나눌지 적어보기
  • 인수인계, 문서화, 월별 피드백 흐름과 연결해보기

11. 다음에 다시 공부할 때 추천 시작점​

다음에 이 문서를 다시 열면 아래 순서로 이어서 보면 좋습니다.

  1. 하네스 개념 다시 읽기
  2. AGENTS.md와 Skills 차이 다시 보기
  3. MCP와 Hooks를 실무 예시로 연결해보기
  4. 마지막에 "우리 팀에서 어떤 에이전트를 만들 수 있나"로 정리하기

12. 영빈님 업무와 연결하면​

이 개념은 아래 흐름에 바로 연결할 수 있습니다.

  • Slack 역할별 채널 운영
  • 회의록 정리 에이전트
  • 주간보고 정리 에이전트
  • 문장 정리 보조 채널
  • 메디사이트 전환 보조 채널
  • 인수인계와 문서화 자동화

같이 보면 좋은 문서​

한 줄 정리​

OpenClaw를 잘 쓴다는 것은 질문을 잘하는 것에서 끝나지 않고, AI가 역할, 규칙, 연결, 자동화 흐름 속에서 실제로 일하게 만드는 구조를 설계하는 것에 가깝습니다.