에이전트(Agent)의 하네스 구조를 파악하고 나에게 맞는 에이전트 하네스를 구축

에이전트 하네스 1주차 강의안

지피터스 23기 · 에이전트 하네스 스터디 1주차
다루는 런타임: Hermes(헤르메스) / OpenClaw(오픈클로)
1주차 목표: 매번 말로 설명하던 반복 업무를, 에이전트가 읽을 수 있는 "업무 설명서(Skill)"로 바꾸기

0. 1주차 배운 것 (전체 지도)

1장. 에이전트 하네스란 무엇인가

1-1. 하네스가 무엇인지?

이 지구상에서 어떤 사람(에이전트)에게 에펠탑을 찾도록 하는 상황을 가정

① 프롬프트 없는 AI 사용(No Prompt)

해당 에이전트를 대한민국 서울에서부터 에펠탑을 찾으라고 하는 것과 같음

② 프롬프트 엔지니어링(Prompt Engineering)

해당 에이전트를 프랑스 파리에 데려다주고 에펠탑을 찾으라고 하는 것과 같음

③ 컨텍스트 엔지니어링(Context Engineering)

해당 에이전트를 프랑스 파리에 데려다주고 에펠탑의 모양(삼각뿔의 철탑)과 종류(송신탑)를 알려주고 에펠탑을 찾으라고 하는 것과 같음

④ 하네스 엔니지어링(Harness Engineering)

해당 에이전트를 프랑스 파리에 데려다주고 에이전트에게 네비게이션을 통해 에펠탑까지 가는 길을 지시해서 어디에서 직진을 하고, 어디에서 좌회전, 우회전을 하면 되는지를 알려주는 것과 같음

1-2. 에이전트는 무엇인지?

Agent는 대리인을 의미하고 바이브 코딩에서는 claude code, codex 등을 가리키기도 하고, 또 claude code에서 그 명령을 실행하는 main agent와 main agent로부터 서브작업을 위임받아 수행하는 subagent를 지칭하는 경우가 있지만, 여기서 agent라 함은 openclaw와 hermes를 의미. 따라서 앞으로 에이전트는 Openclaw와 Hermes 2종류를 전제하여 진행

1-3. 그렇다면 Agent Harness란?

• Openclaw의 Harness 방식

• Hermes의 Harness 방식

1-4. 따라서 이 스터디(에이전트 하네스)에서는 오픈클로와 헤르메스가 하네스를 어떻게 구축하는지, 그 방식에 대해 알아보는 것이 목적

1-5. Claude code를 쓰면 되는데 왜 Openclaw나 Hermes를 사용할까?

• (X) 봇을 만들어서 사람들에게 자랑하려고

• (X) 남들이 다 쓰는 claude code보다 있어보여서

• (세모) 텔레그램/슬랙 등으로 원격제어가 가능해서

• (O) 자체적으로 하네스를 구축하고 있어서

1-6. 한 줄 정의

하네스(Harness) = 에이전트가 내 일을 안정적으로, 반복 가능하게 수행할 수 있도록 묶어놓은 종합 작업 환경.

말(프롬프트) 한 번으로 시키는 것은 "일회성 지시"입니다. 하네스는 그 지시를 환경 자체에 붙박아 두는 것입니다. 그래서 새 세션을 열어도, 다른 사람이 실행해도 같은 결과가 나옵니다.

1-7. 하네스의 4요소 공식 ★

누가(SOUL) + 무엇을 알고(CONTEXT / MEMORY) + 무엇으로(TOOLS) + 어떤 순서로(SKILL)
= 하네스(Harness)

• 누가: 에이전트의 성격·말투·가치관

• 무엇을 알고: 프로젝트 규칙, 사용자 정보, 과거 기억

• 무엇으로: 사용할 수 있는 도구(웹 검색, 파일 읽기/쓰기, 브라우저 등)

• 어떤 순서로: 실제 업무를 끝내는 절차(Skill)

이 네 가지 중 하나라도 비어 있으면 에이전트는 "똑똑하지만 매번 다르게 일하는" 상태가 됩니다.

1-8. 꼭 구분해야 할 두 단어: 맥락 vs 기억

예시로 보기 — 3주에 걸친 한 장면

1주차 월요일 — 사용자: "나는 표보다 글머리 기호가 읽기 편해."
→ 에이전트가 이 선호를 MEMORY.md에 저장(서랍에 넣음). 이번 대화에서는 더 안 씀.

3주차 금요일, 새 세션 — 사용자: "지난달 실적 정리해줘"

1. 🗄️ 서랍에 있던 것: "이 사람은 글머리 기호를 선호한다"

2. 🔍 검색: 이번 요청이 '정리'와 관련 → 관련 기억을 찾아냄

3. 📄 책상 위로 꺼냄: 그 문장이 이번 대화의 맥락에 포함됨

4. ✅ 결과: 시키지도 않았는데 표가 아닌 글머리 기호로 정리해서 제출

만약 기억이 없었다면? 3주차에도 표로 정리해 오고, 사용자는 매번 "글머리 기호로 해줘"를 반복해야 합니다.

🎯 이 반복을 없애는 것이 하네스의 목적입니다. 1주차 내내 하는 일은 결국
"매번 말로 하던 것을 → 파일에 한 번 적어두기"입니다.

이 구분이 1주차 전체의 기초입니다. 뒤에 나오는 X-Ray는 "책상 위"를 찍는 사진이고, Memory는 "서랍"을 관리하는 방법입니다.

2장. 설정 문서 지도 — 법(法)에 비유하기

에이전트의 설정 문서들은 디지털 법전과 같습니다. 각 문서가 어떤 법적 위계를 갖는지 보면 역할이 선명해집니다.

2-1. AGENTS.md와 SKILL.md는 어떻게 다른가

이 둘의 혼동이 가장 많습니다.

• AGENTS.md = 무대와 규칙 — "이 폴더에서는 이런 규칙을 지켜라." 작업공간에 있는 내내 항상 적용되는 배경 지침.

• SKILL.md = 무대 위의 대본 — "주간 보고서를 쓸 때는 이 순서로 하라." 특정 요청(Trigger)이 들어왔을 때만 활성화되는 절차서.

도구(Tools)가 '손'이라면, Skill은 그 손을 움직이는 '방법'입니다.

실제로 뭐가 달라지나 — 같은 요청, 두 환경

AGENTS.md에 "주간 보고서를 매주 작성한다"는 규칙이 이미 있는 상태에서, 사용자가 똑같이 "주간 보고서 써줘"라고 합니다.

규칙(AGENTS.md)은 "무엇을 지킬지"만 알려줍니다.
"어떻게 할지"는 SKILL.md가 없으면 매번 사람이 입으로 채워야 합니다.
→ 1주차에 Skill을 만드는 이유가 정확히 이것입니다.

3장. 컨텍스트 로딩 순서 — 에이전트는 어떤 순서로 읽는가

에이전트가 정보를 읽어오는 순서를 컨텍스트 로딩 순서(Context Loading Order)라고 합니다. 먼저 읽은 정보일수록 사고의 뼈대가 되고, 나중에 읽은 정보는 그 위에서 행동을 미세 조정합니다. 그래서 순서 자체가 곧 우선순위입니다.

두 런타임 모두 8단계지만, 설계 철학이 다릅니다.

3-1. OpenClaw — 파일 기반 "수직적 주입"

정해진 파일들을 위에서 아래로 순서대로 밀어 넣습니다.

특징: 파일명과 역할이 고정되어 있어, 무엇이 언제 영향을 주는지 직관적이고 예측 가능합니다.

"수직적 주입"이 실제로 만드는 결과 — 눈으로 보기

"위에서 아래로 밀어 넣는다"는 말은 비유가 아니라 문자 그대로입니다. 8개 파일의 내용이 순서대로 이어 붙어 한 덩어리의 긴 글이 되고, 에이전트는 그 글 하나를 읽은 상태로 일을 시작합니다.

━━━ 01 AGENTS.md ━━━
외부 전송 전 반드시 승인받는다. 보고서는 3줄 요약.

━━━ 02 SOUL.md ━━━
확실하지 않으면 먼저 묻는다. 과장하지 않는다.

━━━ 03 TOOLS.md ━━━
파일 검색은 rg를 쓴다. 삭제 명령은 사용자에게 확인받는다.

━━━ 04 IDENTITY.md ━━━
나는 리서치 보조 에이전트다.

━━━ 05 USER.md ━━━
사용자 호칭은 "선생님". 표는 간결하게 선호.

━━━ 06 HEARTBEAT.md ━━━
매일 아침 Inbox 폴더 미분류 문서를 점검한다.

━━━ 07 BOOTSTRAP.md ━━━
(새 작업공간일 때만 1회 실행)

━━━ 08 MEMORY.md ━━━
지난주에 1주차 강의안 초안을 작성함.

━━━ 여기서부터 사용자 대화 ━━━
"이 문서 요약해서 팀에 공유해줘"

이 그림에서 바로 읽히는 결과가 세 가지입니다.

① 위에 있는 문장이 아래 문장을 이깁니다 (충돌 시)

01 AGENTS.md: "외부 전송 전 반드시 승인받는다"
05 USER.md: "이 사용자는 빠른 처리를 선호한다"
→ 에이전트는 먼저 읽은 승인 규칙을 뼈대로 삼고, 선호는 그 안에서 조정합니다. 결과: 승인은 받되, 승인 요청을 짧고 빠르게 합니다. 승인을 건너뛰지는 않습니다.

② 뒤에 있는 파일은 "규칙"이 아니라 "조정값"으로 작동합니다

같은 문장을 01 AGENTS.md에 쓰면 지켜야 할 기준이 되고, 08 MEMORY.md에 쓰면 참고 정보가 됩니다. → 어느 파일에 쓰느냐가 곧 그 문장의 강도입니다.

③ 파일 하나를 비워두면 그 자리는 그냥 빈칸입니다

04 IDENTITY.md가 없으면 에이전트는 "나는 누구인가"를 모른 채 규칙만 든 상태로 시작합니다. 그래서 말투와 역할이 매번 흔들립니다. → 순서표는 곧 체크리스트이기도 합니다.

한 줄 요약
수직적 주입 = 8개 파일을 순서대로 복사-붙여넣기 해서 만든 한 장짜리 업무 지시서.
위쪽에 쓸수록 "반드시", 아래쪽에 쓸수록 "참고로".

그림 한 장으로: 수직적 주입은 법전 낭독입니다 ★

2장에서 각 문서를 법에 비유했습니다. OpenClaw가 하는 일은 그 법전을 정해진 조문 순서대로 처음부터 낭독하는 것입니다.

폭이 일정하다는 점이 중요합니다. 8개 조문 중 줄어들거나 걸러지는 것은 하나도 없습니다. 전부 그대로 낭독되고, 달라지는 건 읽히는 순서뿐입니다.

📌 이 그림에 안 그려진 것 — 09번째 칸이 하나 더 있습니다
위 8개는 파일만 센 것입니다. 낭독이 끝난 뒤 실행 층(Execution Layer)에서 도구 정의, 도구 실행 결과, 현재 대화가 여기에 결합됩니다. 파일이 아니라서 조문 번호가 없을 뿐, 빠져 있는 게 아닙니다(→ 5장).
Hermes는 같은 정보를 8단계 안에(02·04·05) 번호를 매겨 넣습니다. 차이는 존재 여부가 아니라 배치 위치입니다.

• 조문 번호 = 우선순위 — 먼저 낭독된 조문이 뒤 조문의 해석 기준이 됩니다.

• 낭독 순서는 고정 — 오늘도 내일도 01번부터입니다. 그래서 예측 가능합니다.

• 빠진 조문은 그냥 침묵 — IDENTITY.md가 없으면 "신분증 없이" 일을 시작합니다.

🔍 여기서 한 번 더 보세요: 01이 AGENTS.md(특별법)이고 02가 SOUL.md(헌법)입니다.
법 상식과 거꾸로죠. OpenClaw는 "나는 누구인가"보다 "여기서 뭘 지켜야 하는가"를 먼저 읽습니다.
→ 이 한 줄이 Hermes와의 가장 큰 차이입니다 (→ 3-3절에서 다시).

이 그림에서 실무 규칙 하나가 바로 나옵니다 ★

어떤 문장을 쓸 때 스스로에게 물어보세요 — "이건 몇 번 조문에 넣을 문장인가?"

• 어느 폴더에서든 지켜야 한다 → 앞 조문(AGENTS.md / SOUL.md)

• 이 사람한테만 해당된다 → 뒤 조문(USER.md / MEMORY.md)

• 앞 조문에 넣으면 안 될 문장을 넣으면 → 엉뚱한 폴더에서도 계속 튀어나옵니다 (→ 4-4절 실전 사례)

참고로 Hermes는 낭독이 아니라 '책상 위 3단 트레이'에 가깝습니다. 정해진 순서대로 읽어 내려가는 대신, 성격별로 먼저 분류해 올려놓기 때문입니다(→ 3-2절). ※ 1-8절의 '서랍'은 파일 저장소를 가리키는 다른 비유이니 섞지 마세요.

3-2. Hermes — 3계층 기반 "구조적 조립"

정보를 성격에 따라 안정층 → 작업층 → 변동층으로 먼저 분류한 뒤, 8단계로 조립합니다. 파일뿐 아니라 런타임이 만들어내는 정보도 함께 들어갑니다.

"구조적 조립"이 실제로 만드는 결과 — 눈으로 보기

최종 결과물이 한 덩어리의 긴 글이라는 점은 OpenClaw와 똑같습니다. 다른 건 그 글을 무엇으로 채우느냐입니다.

━━━━━━━━━━ 🟪 안정층 ━━━━━━━━━━

[01] 나는 리서치 보조 에이전트다. 확실하지 않으면 먼저 묻는다.   ← SOUL.md (내가 씀)
[02] 사용 가능한 도구: file_read, file_write, web_search(꺼짐)   ← 런타임이 씀
[03] 사용 가능한 기술: 주간보고서작성, 카드명세서입력            ← SKILL.md 목록만

━━━━━━━━━━ 🟦 작업층 ━━━━━━━━━━

[04] OS: Windows 11 / 작업 폴더: D:\03Gpters\research_harness   ← 런타임이 씀
[05] (호스트가 덧붙인 추가 지시)                                 ← system_message
[06] 보고서는 3줄 요약. 외부 전송 전 반드시 승인.                ← AGENTS.md (내가 씀)

━━━━━━━━━━ 🟩 변동층 ━━━━━━━━━━

[07] 지난주에 1주차 강의안 초안을 작성함                         ← MEMORY.md 검색 결과
[08] 호칭 "선생님" / 현재 시각 2026-07-27 / 모델 claude-opus-5   ← USER.md + 세션 정보

━━━ 여기서부터 사용자 대화 ━━━
"이 문서 요약해서 팀에 공유해줘"

여기서 3-1과 결정적으로 다른 점이 세 가지입니다.

① 절반은 내가 쓴 파일이 아닙니다

← 표시를 보세요. 02, 04, 05는 내가 만든 적 없는데도 들어와 있습니다. → 그래서 "파일만 잘 쓰면 된다"가 성립하지 않습니다. 웹 검색이 꺼져 있다는 사실도 02에 자동으로 들어가고, 에이전트는 그걸 읽고 검색을 포기합니다. (→ 5장에서 자세히)

② 자리를 정하는 건 파일명이 아니라 '성격'입니다

OpenClaw는 AGENTS.md라서 1번이었습니다. Hermes는 AGENTS.md가 "이 프로젝트에서만 유효한 정보"라서 작업층입니다. → 파일 이름이 아니라 얼마나 자주 바뀌는가가 자리를 결정합니다. (→ 4장의 구분 기준)

③ 아래층만 갈아 끼웁니다

다음 대화가 시작되면 🟩 변동층은 통째로 새로 채워지지만, 🟪 안정층은 어제와 똑같은 내용 그대로입니다. 프로젝트를 옮기면 🟦 작업층이 교체되고, 🟪는 여전히 그대로입니다. → 한 번 잘 써두면 계속 재사용되는 게 위층, 매번 다시 만들어지는 게 아래층입니다.

한 줄 요약
구조적 조립 = 정보를 성격별로 분류해 3단 트레이에 올린 뒤, 위 칸부터 순서대로 붙인 업무 지시서.
위 칸일수록 오래 가고, 아래 칸일수록 자주 바뀝니다.

그림 한 장으로: 구조적 조립은 책상 위 3단 트레이입니다

왜 낭독이 아니라 트레이인가

낭독은 정해진 차례대로 읽는 그림이고, 트레이는 올릴 때 칸을 고르는 그림입니다. 그래서 Hermes에서는 "이 문장을 어디에 쓸까?"가 어느 파일이냐가 아니라 어느 칸이냐의 질문이 됩니다.

이 그림에서 실무 규칙 하나가 바로 나옵니다 ★

새 지침을 쓰기 전에 물어보세요 — "이 문장, 6개월 뒤에도 그대로일까?"

• 그렇다 → 🟪 안정층 칸 (SOUL.md)

• 이 프로젝트 끝나면 버릴 것 → 🟦 작업층 칸 (AGENTS.md)

• 다음 주면 달라질 것 → 🟩 변동층 칸 (USER.md / MEMORY.md)

칸을 잘못 고르면 버려야 할 문장이 영원히 따라다닙니다 (→ 4-4절 실전 사례)

자주 나오는 오해: "변동층이면 세션 끝나면 MEMORY.md도 지워지는 거 아냐?" ★

아닙니다. 파일은 그대로 남습니다. 이 오해는 '변동층'을 휘발성(사라짐)으로 읽어서 생깁니다. 정확한 뜻은 유동성(매번 다시 조립함)입니다.

1-8절의 비유를 그대로 가져오면 한 번에 정리됩니다.

핵심: 매 세션 새로 채워지는 건 책상 위(맥락)이지, 서랍(파일)이 아닙니다.
앞의 "🟩 변동층은 통째로 새로 채워진다"는 말도 책상 위 이야기입니다.

그런데 왜 하필 변동층인가 — 파일은 그대로인데도 변동층인 이유는, 매번 꺼내오는 내용이 달라지기 때문입니다. MEMORY.md에 100줄이 쌓여 있어도 07단계에 올라오는 건 이번 요청과 관련된 몇 줄뿐입니다(리트리벌).

같은 파일, 다른 세션

• 월요일 "실적 정리해줘" → 🟩에 올라오는 것: "이 사람은 글머리 기호를 선호한다"

• 화요일 "강의안 이어서 쓰자" → 🟩에 올라오는 것: "지난주에 1주차 강의안 초안을 작성함"

파일은 하나도 안 바뀌었는데 조립 결과는 매번 다릅니다. ← 이게 '변동'의 의미입니다.

여기서 나오는 실무 감각 하나 ★

🟪 안정층은 적을수록 좋고(항상 켜져 있으니까), 🟩 변동층은 쌓여도 괜찮습니다(필요한 것만 꺼내 쓰니까).
그래서 "언젠가 쓸지도 모르는 사실"은 SOUL.md가 아니라 MEMORY.md에 쌓는 것이 맞습니다. 반면에 "항상 쓰는 사실"은 SOUL.md에 쌓는 것이 맞습니다.

3-3. 한눈에 보는 대응표 (Hermes 기준) ★

표에서 읽어야 할 핵심 한 가지

OpenClaw는 AGENTS.md(규칙)를 1번으로 읽고, Hermes는 SOUL.md(정체성)를 1번으로 읽습니다.
→ OpenClaw = "무엇을 지켜야 하는가"를 먼저 / Hermes = "나는 누구인가"를 먼저.

3-4. 자주 나오는 오해: "Hermes에서 AGENTS.md는 위계가 낮은 거 아냐?"

아닙니다. 6단계에 있다는 건 "약하다"가 아니라 "역할이 다르다"는 뜻입니다.

• Hermes에서 AGENTS.md는 헌법이 아니라 특별법/업무 계약서입니다.

• 사고 흐름: "나는 전문가다(안정층) → 이 프로젝트에서는 이 규칙을 지킨다(작업층) → 지금 이 사용자와 대화 중이다(변동층)"

• 즉 실무 판단에서는 AGENTS.md가 가장 구체적인 기준으로 작동합니다. 규칙을 무시하는 구조가 전혀 아닙니다.

4장. 3계층 구분 기준 — 무엇이 어느 층에 들어가나

4-1. 구분 기준은 두 가지

① 변화 주기 (얼마나 자주 바뀌나) + ② 역할의 근본성 (얼마나 뿌리에 가까운가)

여기서 반드시 갈라야 할 것: '층위'와 '범위'는 다른 축입니다 ★

가장 많이 생기는 오해가 여기서 나옵니다. "안정층이니까 어느 폴더에서나 적용되겠네" — 아닙니다.

이 둘은 서로 독립입니다. 안정층이라고 전역이 아니고, 전역이라고 안정층인 것도 아닙니다.

🔑 읽는 법: SOUL.md와 /personality는 같은 층(01단계)에 나란히 들어갑니다. 다른 건 층이 아니라 어디에 저장돼 있느냐입니다.
SOUL.md가 AGENTS.md보다 근본적인 건 맞지만(축 A), 더 멀리까지 따라간다는 뜻은 아닙니다(축 B). 둘 다 그 폴더를 벗어나면 사라집니다.

⚠️ 위 표의 "환경이 바뀌어도 유지되는"은 축 A의 이야기입니다.
세션이 바뀌고 대화가 바뀌어도 그 뼈대가 유지된다는 뜻이지, 폴더를 옮겨도 따라온다는 뜻이 아닙니다.
폴더를 옮겨도 따라오는 정체성을 원한다면 파일이 아니라 /personality(전역)에 넣어야 합니다(→ 6-6절).

4-2. 핵심 원칙: 층위는 '내용'이 아니라 '출처'가 결정한다 ★

같은 문장이라도 어느 파일에 적혀 있느냐에 따라 층위가 달라집니다.

예: "답변은 항상 존댓말로 한다"

• SOUL.md에 적으면 → 안정층 🟪 (에이전트의 인격)

• AGENTS.md에 적으면 → 작업층 🟦 (이 프로젝트만의 규칙)

• 대화 중 "존댓말로 해줘"라고 해서 MEMORY.md에 저장되면 → 변동층 🟩 (기억)

그래서 실제로 뭐가 달라지나 — 존댓말 한 문장의 세 가지 운명 ★

월요일, 사용자가 말합니다. "존댓말로 해줘."
화요일, 새 세션을 열고 말합니다. "이 코드 좀 봐줘."

화요일에 벌어지는 일이 층위마다 다릅니다.

주의 — 여기서 다루는 건 '같은 폴더 안'의 이야기입니다. 위 세 파일은 모두 그 작업공간 안에서만 읽힙니다. 폴더를 옮기면 셋 다 사라지고, 그때까지 따라오는 건 전역 설정인 /personality뿐입니다(→ 4-1절 '층위 vs 범위').

🟩만 다른 이유는 하나입니다 — 자동으로 올라오지 않습니다.

SOUL.md는 읽히는 게 보장돼 있습니다. 반면 MEMORY.md의 문장은 "이 코드 좀 봐줘"라는 요청과 '말투 선호'라는 기억이 관련 있다고 판단돼야 책상 위로 올라옵니다. 판단이 빗나가면 — 파일에는 그대로 있는데 책상 위에는 없습니다. 그래서 어제 말한 걸 오늘 안 지킵니다.

한 문장으로 ★
기억은 '규칙'이 아니라 '습관'입니다.
규칙은 반드시 지켜지고, 습관은 대체로 지켜집니다.

이 차이가 사고로 이어지는 순간

말투라면 놓쳐도 아쉬운 정도입니다. 문장을 바꿔보면 이야기가 달라집니다.

"외부로 보내기 전에 반드시 나한테 승인받아."

이 문장이 🟩 MEMORY.md에만 있으면, "거래처에 메일 보내줘" 요청에서 검색이 그 기억을 못 건져 올리는 순간 — 에이전트는 그냥 보냅니다. 규칙을 어긴 게 아니라, 그 순간 규칙이 책상 위에 없었을 뿐입니다.

판단 기준 ★
"이게 안 지켜지면 아쉬운가, 사고인가?"

• 아쉬운 정도 → 🟩 MEMORY.md로 충분 (말투, 글머리 기호 선호)

• 사고 → 🟪 SOUL.md / 🟦 AGENTS.md로 승격해야 함 (승인 절차, 삭제 금지, 보안 규칙)

실무 동작 하나 — 대화 중에 한 말이 기억에 저장됐다면, 그중 "반드시"에 해당하는 것만 골라 파일로 옮겨 적으세요. 1주차에 가장 자주 하게 될 정비 작업입니다.

반대로, 🟩에 넣었는데 자꾸 안 지켜질 때 원인을 셋으로 갈라내는 방법은 8-6절에서 다룹니다.
(저장이 안 됐나 / 안 꺼내졌나 / 꺼내졌는데 상위 층에 졌나)

우리가 분명히 agent한테 신신당부를 했다고 생각했는데, 그걸 agent가 지키지 않는 데에는 이유가 있습니다. 그게 memory.md나 agents.md에만 있기 때문입니다. 반대로 아무리 열심히 지시했는데도 그걸 지키지 않는다면 그와 반대되는 지시를 soul.md에 넣어놓았을 가능성이 큽니다.

따라서 하나의 정보는 시스템 안에서 단 하나의 층위 소속을 갖습니다. 다만 같은 내용이 여러 파일에 흩어져 있으면 중복 지시(Duplicated instructions)로 진단됩니다(→ 10장 Document Doctor).

4-3. 사용자가 층위를 직접 지정하는 법

층위의 정의는 시스템이 정하지만, 무엇을 어느 파일에 넣을지는 사용자의 권한입니다.

주의사항 2가지

1. 진단 도구는 파일을 자동 수정하지 않습니다. 층위를 옮기려면 사용자가 직접 파일을 열어 내용을 옮겨야 합니다.

2. 안정층에 너무 많이 넣지 마세요. 뼈대가 무거워지면 에이전트의 유연성이 떨어집니다.

4-4. 층위를 잘못 고르면 생기는 일 (실전 사례)

❌ 잘못 배치한 경우

개발자가 "모든 코드에 한국어 주석을 단다"는 지침을, 편하다는 이유로 화면 /personality(안정층·전역)에 적었습니다.

일어난 일: 블로그 글 쓰는 폴더, 가계부 정리하는 폴더에서도 에이전트가 자꾸 코드 주석 이야기를 꺼냅니다.
원인: /personality는 전역 설정이라 어느 폴더로 가든 항상 로딩되기 때문. 코드가 없는 폴더에서도 그 지침은 살아 있습니다.

✅ 고친 경우

/personality에서 그 문장을 지우고, 개발 프로젝트 폴더의 AGENTS.md(작업층)에 옮겨 적음.
→ 개발 폴더에서만 적용되고, 블로그 폴더에서는 깨끗이 사라집니다.

💡 작업공간이 하나뿐이어도 같은 일이 생깁니다. 한 폴더에서 코드도 짜고 글도 쓴다면, SOUL.md에 적힌 "코드 주석" 지침이 글 쓸 때도 계속 켜져 있습니다. 이때도 답은 같습니다 — 그 문장은 SOUL.md(인격)가 아니라 AGENTS.md(업무 규칙)의 자리입니다.

판단은 두 단계입니다 ★ (→ 4-1절의 두 축)

1단계 — 범위: 폴더를 옮겨도 따라와야 하나?

• 그렇다 → /personality (전역) — 예: "항상 존댓말을 쓴다"

• 아니다 → 그 작업공간의 파일로 (아래 2단계)

2단계 — 층위: 이 작업공간 안에서 어떤 성격의 문장인가?

• 나의 근본 태도다 → 안정층 (SOUL.md) — 예: "확실하지 않으면 먼저 묻는다"

• 이 프로젝트의 규칙이다 → 작업층 (AGENTS.md) — 예: "이 프로젝트는 Python 3.11을 쓴다"

• 사람에 따라 다르다 → 변동층 (USER.md) — 예: "이 사용자는 글머리 기호를 선호한다"

5장. 파일이 아닌 정보 — 런타임이 스스로 넣는 것들

"정보의 출처 = 파일"이라고만 생각하면 절반만 맞습니다.

5-0. 먼저 짚고 갈 것 — 이건 Hermes만의 이야기인가? ★

아닙니다. 두 런타임 모두 해당합니다.

3-2절 표에는 런타임 정보가 단계 번호를 달고 들어가 있고(02·04·05), 3-1절 표에는 파일만 적혀 있습니다. 그래서 "런타임 주입은 Hermes만의 것"처럼 보이지만, 차이는 존재 여부가 아니라 배치 위치입니다.

읽는 법: Hermes는 런타임 정보를 계층(Tier)으로 승격시켜 관리하고, OpenClaw는 파일을 먼저 세운 뒤 실행 정보를 붙입니다. 둘 다 넣습니다 — 다만 지도에 그리는 방식이 다릅니다.

애초에 이 정보들이 없으면 에이전트가 작동을 못 합니다. 도구 명세가 없으면 파일을 읽을 수 있다는 사실 자체를 모르고, 현재 시각이 없으면 "오늘 날짜로 저장"을 못 합니다(→ 5-3절). 어느 런타임을 쓰든 누군가는 반드시 넣어주고 있다는 뜻입니다.

👁️ 눈으로 확인하는 법: Context X-Ray를 찍었을 때 🟧 주황색으로 표시되는 영역이 바로 이 정보들입니다(도구·플랫폼 안내). 파일에서 온 게 아닌데 책상 위에 있는 것들이죠(→ 9-3절 색상 범례).

5-1. 출처의 세 종류

그래서 정보의 출처는 세 종류입니다.

1. 문서 파일 (비중 최대) — SOUL.md, AGENTS.md, USER.md, MEMORY.md 등. 사용자가 직접 수정 가능.

2. 런타임/플랫폼 제공 정보 — 파일로 존재하지 않고 시스템이 자동 주입.

3. 세션 메타데이터 — 대화가 일어나는 순간 생성되는 정보.

5-2. "시스템이 자동 주입한다"가 무슨 뜻인가 — 눈으로 보기

말이 어렵지, 실물을 보면 간단합니다. 에이전트가 일을 시작할 때 머릿속에 들어가는 지침은 한 덩어리의 긴 글입니다. 그런데 그 글은 두 사람이 나눠 씁니다.

• 윗부분 — 시스템(런타임)이 자동으로 써 넣음

• 아랫부분 — 내가 파일에 써 둔 것

실제로 들어가는 모습 (예시)

━━━ 시스템이 자동으로 넣은 부분 (내가 쓴 적 없음) ━━━

현재 시각: 2026-07-26 14:02 (Asia/Seoul)
운영체제: Windows 11
현재 작업 디렉토리: D:\03Gpters\research_harness
사용 중인 모델: claude-opus-5

사용 가능한 도구:
  file_read(path)             파일 내용을 읽는다
  file_write(path, content)   파일에 내용을 쓴다
  web_search(query)           웹을 검색한다     ← 현재 꺼져 있음

━━━ 내가 SOUL.md에 쓴 부분 ━━━

친절하고 간결하게 답한다. 확실하지 않으면 먼저 묻는다.

━━━ 내가 AGENTS.md에 쓴 부분 ━━━

보고서는 3줄 요약. 외부 전송 전 반드시 승인.

💡 윗부분을 여러분이 타이핑한 적이 있나요? 없습니다.
그런데 에이전트 머릿속에는 분명히 들어 있습니다. 이것이 '런타임이 자동 주입하는 정보'입니다.
즉 거창한 개념이 아니라, "내 파일 위에 시스템이 자동으로 얹어주는 상황 설명서"입니다.

5-3. 종류별 구체적 예시 — "이게 없으면 어떻게 되나"로 이해하기

가장 쉽게 이해하는 방법은 그게 없다고 상상해 보는 것입니다.

🎯 가장 직관적인 예: 오늘 날짜
AI 모델은 "지금이 몇 시인지" 스스로 알 방법이 없습니다. 훈련이 끝난 시점에 멈춰 있죠.
그런데도 에이전트가 "오늘 날짜로 저장할게요"라고 말할 수 있는 건,
런타임이 매 대화마다 현재 시각을 몰래 적어 넣어주기 때문입니다.
이 한 줄이 없으면 "이번 주 보고서"라는 말조차 계산할 수 없습니다.

5-4. 그렇다면 사용자는 여기에 개입할 수 없나? ★

짧은 답: 파일로는 못 바꿉니다. 하지만 상당수는 화면에서 조종할 수 있고, 전부 눈으로 확인할 수는 있습니다.

정확히는 세 등급으로 나뉩니다.

여기서 얻어야 할 통찰 ★

못 바꾸는 것들은 대부분 '사실'입니다.
오늘 날짜, 내 컴퓨터의 OS, 방금 읽은 파일의 내용 — 이건 취향이 아니라 사실이라 바꿀 이유가 없습니다.
오히려 임의로 바꾸면 에이전트가 틀린 전제 위에서 판단하게 됩니다.

반대로, 바꿀 가치가 있는 것들은 거의 전부 조종 가능합니다.
어떤 도구를 줄지, 어느 폴더에서 일할지, 어떤 모델을 쓸지 — 전부 화면에서 고를 수 있습니다.

→ 그러니 정답은 "개입할 수 없다"가 아니라, "파일로는 못 바꾸고 화면으로 바꾼다"입니다.
그리고 바꿀 수 없는 것조차 X-Ray로 볼 수는 있습니다. 보이면 대응할 수 있으니, 통제 불능은 아닙니다.

실무 매핑 — 바꾸고 싶으면 어디를 건드리나

💡 표에 ❌가 많다는 것이 핵심입니다.
하네스 문제의 상당수는 파일이 아니라 화면에서 풀립니다. 그런데 대부분의 사람은 파일부터 엽니다.
바로 다음 절이 그 이야기입니다.

참고: X-Ray 결과에 AGENTS.md 같은 파일명뿐 아니라 system_message, session metadata 같은 출처가 함께 표시되는 이유가 이것입니다. 파일과 런타임 정보를 나란히 놓고 봐야 진짜 원인이 보입니다.

5-5. 왜 이걸 알아야 하나 — 파일만 봐서는 원인을 못 찾는다

증상

AGENTS.md에 "웹에서 최신 자료를 찾아 인용할 것"이라고 분명히 적었는데,
에이전트가 계속 "검색할 수 없습니다"라고만 답합니다.

❌ 파일만 확인하는 접근

AGENTS.md를 열어봄 → 문장 멀쩡함 → 원인 모름
→ "표현이 애매한가?" 하며 문장을 세 번 고쳐 씀 → 여전히 안 됨
→ 하루를 날림

✅ X-Ray를 찍는 접근

🟧 주황색(도구 안내) 영역을 보니 웹 검색 도구가 아예 목록에 없음
→ 원인은 문서가 아니라 화면 설정에서 Tools의 웹 검색이 꺼져 있던 것
→ 해결: 파일 수정이 아니라 화면에서 도구 켜기 (10초)

🎯 교훈: 에이전트의 행동은 내가 쓴 파일 + 런타임이 넣은 정보로 결정됩니다.
내가 쓴 절반만 보면 나머지 절반에서 생긴 문제는 영원히 못 찾습니다.
→ 그래서 문제가 생기면 파일부터 고치지 말고, X-Ray로 실제 들어온 것 전체를 먼저 확인해야 합니다.

5장을 한 문장으로

런타임 정보는 내가 못 쓰는 영역이지만, 못 보는 영역은 아닙니다.
직접 타이핑할 수 없을 뿐 화면으로 조종하고(5-4) X-Ray로 확인할 수 있습니다(9장).
이 두 가지를 알면 "왜 이러는지 모르겠는" 상황이 대부분 사라집니다.

6장. 화면 설정 vs 문서 설정 (Hermes의 하이브리드 구조)

6-1. "화면에서 고르는 설정과 작업공간 문서가 함께 하네스를 이룬다"

Hermes에서는 텍스트 파일만으로 하네스가 완성되지 않습니다. 데스크탑 앱 화면(UI)의 설정과 문서가 조립되어 최종 행동 지침을 만듭니다.

"화면 설정"이란 실제로 이렇게 생긴 것입니다

ℹ️ 실제 화면 구성은 버전마다 다릅니다. 항목의 성격을 보여주기 위한 예시입니다.

5장과 이어 붙이면 화면 설정의 정체가 드러납니다 ★

5-2절에서 본, 시스템이 자동으로 넣어주던 그 텍스트를 기억하시나요?

사용 가능한 도구:
  file_read(path)     파일 내용을 읽는다
  web_search(query)   웹을 검색한다   ← 현재 꺼져 있음

이 문장을 만들어낸 것이 바로 위 화면의 체크박스입니다.
내가 web_search 체크를 풀었기 때문에, 런타임이 그렇게 적어 넣은 것입니다.

🎯 즉 화면 설정 = 런타임이 자동 주입하는 정보를 조종하는 리모컨입니다.
5-4절에서 "🎛️ 간접 조종 가능"이라고 했던 것의 실물이 이 화면입니다.

6-2. 역할 분담 — 왜 둘 다 필요한가

🔪 비유: 화면 설정은 칼을 쥐여주는 것, 문서 설정은 칼 쓰는 법을 가르치는 것입니다.
칼만 주면 위험하고, 사용법만 가르치면 아무 일도 못 합니다.

둘을 교차하면 네 가지 경우가 나옵니다 ★

상황: 사용자가 **"이 고객 데이터, 외부 분석 API로 보내서 처리해줘"라고 요청.

• 화면 축 — send_data(외부 전송) 도구 ON / OFF

• 문서 축 — AGENTS.md에 "외부 전송 전 반드시 승인, 개인정보 포함 시 금지" 규칙 있음 / 없음

🎯 "화면 설정과 문서가 함께 하네스를 이룬다"의 진짜 뜻
네 칸 중 ④번만 하네스입니다. 나머지 셋은 각각 무능(①) · 헛수고(②) · 위험(③)일 뿐입니다.
그래서 하네스를 점검할 땐 문서만 보지 말고 화면과 문서를 짝지어 봐야 합니다.

실무에서 사람을 잡는 건 ②번과 ③번입니다.

• ②번 — 문서를 붙잡고 몇 시간을 고쳐도 안 되는 이유 (→ 5-5절 웹 검색 사례가 정확히 이 경우)

• ③번 — 사고가 터지고 나서야 "규칙을 안 써뒀네"를 깨닫는 경우

6-3. 중요: 화면 설정은 특정 층위가 아니다

자주 나오는 오해입니다. 화면 설정은 층위(Tier)가 아니라 입력 방식(Interface)입니다. 따라서 세 층 모두에 걸쳐 있습니다.

• 안정층: /personality, Tools 활성화

• 작업층: Workspace(cwd) 선택 → 어떤 AGENTS.md를 읽을지 결정

• 변동층: 사용할 모델·제공자 선택 → 세션 메타데이터로 주입

버튼마다 조종하는 층이 다릅니다 — 클릭 한 번의 결과

🎯 화면은 층위가 아니라 리모컨입니다.
리모컨에 채널 버튼과 볼륨 버튼이 따로 있듯, 버튼마다 조종하는 층이 다릅니다.
그래서 "화면 설정 = 작업층"이라고 외우면 반드시 틀립니다.

6-4. AGENTS.md는 문서 설정인가, 화면 설정인가?

형식은 문서, 작동은 화면에 좌우됩니다.

즉 AGENTS.md가 06단계에 주입되려면, 화면에서의 작업공간 지정이 반드시 선행되어야 합니다.

실전에서 가장 많이 나오는 사고 ⚠️

증상: ~/work/client-A/AGENTS.md에 규칙을 20줄이나 정성껏 써놨는데,
에이전트가 하나도 안 지킵니다. 문장을 고쳐 써도, 더 강하게 써도 소용없습니다.

X-Ray를 찍어보면

• 🟦 파란색(작업층 06) 영역이 텅 비어 있음

• 🟧 환경 안내(04) 행의 cwd가 ~/Downloads로 잡혀 있음

원인: 파일은 완벽했지만, 에이전트는 그 파일이 있는 방에 있지도 않았습니다.
해결: 화면에서 Workspace를 ~/work/client-A로 지정 — 파일은 한 글자도 고칠 필요 없음

🏢 비유: 아무리 잘 만든 사규도, 직원이 그 회사 건물로 출근하지 않으면 아무 효력이 없습니다.
AGENTS.md를 쓰는 것은 사규를 만드는 일이고, Workspace를 지정하는 것은 출근시키는 일입니다.
둘 중 하나만 해서는 규칙이 작동하지 않습니다.

6-5. cwd와 AGENTS.md — 새 폴더에 파일이 없다면?

에이전트는 cwd를 하나의 독립적인 작업공간으로 인식합니다. 폴더마다 다른 AGENTS.md를 두면, 폴더를 옮길 때마다 "그 구역의 특별법"에 맞춰 모드가 전환됩니다.

AGENTS.md가 없으면?

• 에이전트는 멈추지 않습니다. 상위 층위(안정층)의 정체성·도구 정보는 그대로 살아 있습니다.

• 다만 프로젝트별 구체적 가이드라인이 비어, 시스템 기본 지침으로만 움직입니다.

• X-Ray를 찍으면 파란색(🟦) 영역이 비어 있거나 not_checked로 나타납니다.

• → 해결: AGENTS.md를 직접 작성해 운영 범위 · 승인 절차 · 완료 기준을 명시하세요. 이게 1주차 실습의 핵심입니다.

같은 에이전트, 같은 요청, 다른 폴더 — 실전 대비

사용자 요청 (양쪽 완전 동일): "이 데이터 외부 API로 보내서 처리해줘"

에이전트도 같고, 요청도 같습니다. 바뀐 건 폴더 하나뿐입니다.

🎯 cwd를 옮기는 것은 단순히 파일 경로를 바꾸는 게 아니라,
에이전트를 다른 법이 적용되는 구역으로 데려가는 것입니다.
그래서 작업을 시작하기 전 "지금 내가 어느 폴더에 서 있는가"를 확인하는 습관이 중요합니다.

6-6. /personality와 SOUL.md의 관계

/personality는 SOUL.md 파일을 수정하지 않습니다.

01단계에서 시스템은 SOUL.md와 /personality 설정을 함께 고려하여 최종 인격을 조립합니다. 하지만 화면 설정이 파일에 자동 기록(Overwrite)되지는 않습니다.

/personality 사용 시 내부 작용 4단계

1. 고른 설정값이 01단계(정체성) 정보로 입력됨

2. SOUL.md(있는 경우)와 결합되어 안정층 형성

3. 이후 도구 안내(02) → 프로젝트 규칙(06) → 사용자 정보(08)와 계층적으로 연결

4. 새 세션을 열었을 때 바뀐 정체성이 적용된 상태로 나타남

정교한 정체성을 원하면 화면 설정에 의존하지 말고 SOUL.md를 직접 편집하세요. 여러 줄의 원칙, 예외 조항, 그렇게 정한 이유까지 문장으로 담을 수 있는 건 파일뿐입니다.

⚠️ 여기서 헷갈리기 쉬운 것 — "그럼 SOUL.md가 더 오래 가는 건가?" ★
두 가지가 각각 다른 의미로 강합니다. 섞으면 모순처럼 보입니다.

무엇이 강한가

이긴 쪽

이유

얼마나 멀리 가나 (범위)

/personality

전역 설정이라 작업공간을 옮겨도 따라옴

얼마나 깊이 쓰나 (밀도)

SOUL.md

길고 구조화된 서술 + 공유·버전관리 가능

→ 그래서 실전 배치는 이렇게 갈립니다.
"어느 폴더에서 일하든 나의 에이전트는 이래야 한다" → /personality
"이 프로젝트에서는 이런 인격으로 일한다" → 그 폴더의 SOUL.md

SOUL.md가 AGENTS.md보다 근본적인 건 맞지만(층위), 그게 더 멀리 따라간다는 뜻은 아닙니다(범위). 둘 다 그 폴더 안에서만 삽니다(→ 4-1절).

둘이 충돌하면? → 시스템이 자동으로 덮어쓰지 않고, Context Document Doctor가 충돌·중복을 감지해 수정 후보를 제안합니다(10장).

그래서 언제 화면을 쓰고, 언제 파일을 쓰나 ★

🎯 한 문장 기준: 화면 설정은 "나 혼자, 지금만" / 파일 설정은 "팀 전체, 계속".

권장 워크플로우
화면에서 이것저것 실험해 본다 → 마음에 드는 설정이 확정되면 → SOUL.md에 문장으로 옮겨 적는다.
그래야 새 세션에서도, 다른 팀원의 컴퓨터에서도 같은 에이전트가 됩니다.
화면에만 남겨두면, 그 설정은 내 노트북을 떠나지 못합니다.

6-7. 6장을 한 문장으로

화면은 "할 수 있는가"를, 문서는 "어떻게 해야 하는가"를 정합니다.

그래서 하네스 문제를 만나면 습관적으로 파일부터 열지 말고,
"이건 능력 문제인가(화면), 규범 문제인가(문서)"를 먼저 물으세요.
이 질문 한 번이 5-5절의 하루를 10초로 줄여줍니다.

7장. Hermes vs OpenClaw — 결정적 차이

7-1. 설계 철학 비교

⚠️ 오해 주의: "Hermes는 안정성이 낮다"가 아닙니다. Hermes도 안정층이라는 뼈대를 먼저 세운 뒤 유연한 층을 덧입힙니다. 다만 정책으로 '강제'하기보다 '조립'과 '연결'에 무게를 둘 뿐입니다.

7-2. 극명한 대비 예시 — "주간 보고서 작성" 업무

실험 설계

두 런타임에 완전히 똑같은 파일을 주고, 똑같은 요청을 합니다. 변수는 오직 하나, 읽는 순서뿐입니다.

⚠️ 여기가 핵심입니다. 이 두 문서는 정면으로 충돌합니다.

• AGENTS.md는 "3줄을 넘기지 마라, 형식을 바꾸지 마라"

• SOUL.md는 "사용자가 원하는 걸 최대한 들어줘라"

• 그런데 사용자는 지금 5장을 요구했습니다. 둘 다 만족시킬 방법이 없습니다.

충돌을 푸는 원리 ★

먼저 읽은 정보가 '전제'가 되고, 나중에 읽은 정보는 그 전제 안에서만 허용됩니다.
즉 충돌하면 먼저 읽은 쪽이 이깁니다.

그래서 읽는 순서가 정반대인 두 런타임은, 같은 파일을 가지고도 정반대 행동을 합니다.

① OpenClaw — 규칙이 전제 → 요청을 기각한다

사고 흐름

1. (01) "3줄 초과 금지, 형식 변경 금지." → 이것이 세계의 법칙으로 확정

2. (02) "친절해야 한다." → 하지만 이미 법칙이 정해짐. 친절함은 거절을 부드럽게 전하는 용도로만 쓰임

실제 응답

사본

이번 주 보고서입니다.

- 매출: 전주 대비 +12%
- 신규 가입: 340명 (목표 달성)
- 리텐션: 61%로 3주째 하락

죄송하지만 이 작업공간 규칙(AGENTS.md)상 보고서는 3줄로 제한되어 있고
승인 없이 형식을 변경할 수 없어, 5장 분량으로는 작성이 어렵습니다.
상세본이 필요하시면 AGENTS.md를 수정해 주세요.

결과: 사용자는 원하던 5장을 못 받았습니다. 규칙이 사용자 요청을 이겼습니다.

② Hermes — 인격이 전제 → 방법을 찾아 되묻는다

사고 흐름

1. (01) "나는 사용자가 원하는 걸 최대한 들어주는 비서다." → 이것이 세계의 법칙으로 확정

2. (06) "이 프로젝트엔 3줄 규칙이 있네." → 규칙은 지켜야 할 계약이지만, 전제는 여전히 "요청을 살린다"

3. → 규칙을 어기지 않으면서 요청을 살릴 경로를 탐색

실제 응답

사본

팀장님 보고용이시군요! 규칙을 지키면서도 쓰실 수 있게 준비했습니다 🙂

[보고서 — 규칙에 맞춘 3줄]
- 매출: 전주 대비 +12%
- 신규 가입: 340명 (목표 달성)
- 리텐션: 61%로 3주째 하락

다만 이 작업공간 규칙상 '보고서'는 3줄을 넘길 수 없습니다.
대신 5장 상세본을 별도 문서(weekly-detail.md)로 빼서 함께 드릴까요?
그러면 보고서 형식은 그대로 두면서 팀장님 보고에도 쓰실 수 있습니다.
진행할까요?

결과: 사용자는 5장을 받을 길이 생겼습니다. 인격이 규칙의 빈틈(=별도 문서)을 찾아냈습니다.

결정적 차이 한눈에 ★

🎯 한 문장 요약
같은 파일, 같은 요청인데 OpenClaw는 "안 됩니다"라고 하고, Hermes는 "이렇게 하면 될까요?"라고 합니다.
이 차이를 만든 건 파일 내용이 아니라 읽은 순서 하나입니다.

반대로, 차이가 안 나는 경우도 알아두기

만약 요청이 "이번 주 보고서 써줘"(규칙과 충돌 없음)였다면?

→ 양쪽 다 3줄 요약을 냅니다. 인사말 유무 정도의 톤 차이만 남습니다.

즉 로딩 순서의 차이는 '충돌이 일어날 때만' 드러납니다.
평소엔 두 런타임이 비슷해 보이다가, 규칙과 성격이 부딪히는 순간 완전히 다른 에이전트가 됩니다.
그래서 하네스를 설계할 때 "충돌 상황에서 무엇이 이기길 원하는가"를 먼저 정해야 합니다.

Hermes만의 추가 변수: 화면 설정

위 조건에서 파일은 하나도 건드리지 않고, Hermes 화면에서 /personality만 "규칙을 엄격히 준수하는 감사관"으로 바꿔봅시다.

01단계 전제가 교체됨 → Hermes가 OpenClaw처럼 "규칙상 불가합니다"라고 답하기 시작합니다.
파일은 그대로인데 행동이 반대로 뒤집힙니다.

OpenClaw에서 같은 변화를 만들려면 SOUL.md를 직접 열어 고치고 새 세션을 열어야 합니다.
→ 7-1표의 "유연성: 보통 vs 매우 높음"이 실제로 체감되는 지점입니다.

7-3. 언제 무엇을 쓰나

• OpenClaw: 정해진 규칙을 철저히 지켜야 하는 엄격한 관리형 업무

• Hermes: 사용자 개입과 상황 변화가 잦은 창의적·동적 업무

7-4. 오픈클로 vs 헤르메스 모델 연결

오픈클로에게는 다소 멍청한 모델을 연결해도 크게 문제가 되지 않을 수 있다. 왜냐하면 오픈클로는 정해진 규칙에 따라서 행동하기 때문이다. 그런데 헤르메스는 사용자의 상황에 따라 알잘딱깔센으로 유연하게 움직인다. 그런데 헤르메스에게 멍청한 모델을 연결했다면? 갑자기 말을 못 알아듣고 눈치없는 행동을 하는 것을 볼 수 있다.

8장. Memory — 에이전트가 기억하는 방식

8-1. 기억이란

지금 당장 필요하진 않지만 나중에 다시 꺼내 쓰기 위한 저장소입니다. 저장 대상: 사실, 사용자 선호도, 과거의 결정.

(1장 복습) 맥락 = 책상 위 / 기억 = 서랍 안. 서랍에 있다고 항상 읽는 게 아니라, 필요할 때만 꺼내서 맥락에 넣습니다.

8-2. 기억이 작동하는 4단계

1. 저장하기 — 다음에도 필요한 정보를 남긴다

2. 찾기(검색) — 지금 하는 일과 관련된 기억이 있는지 찾는다

3. 불러오기 — 찾은 기억을 이번 대화의 맥락에 포함시킨다

4. 확인하기 — 결과물이 정말 기억을 반영했는지 검토한다

8-3. 어디에 저장되나

8-4. MEMORY.md의 구조와 위치

담는 내용

• 대화가 끝나도 유지되어야 할 지속 정보 요약

• 사용자의 호칭, 선호도, 변하지 않는 안정적 사실

• 과거에 내린 중요한 결정 사항

로딩 위치

• OpenClaw: 8번째(가장 마지막) — 지속 정보를 요약해 주입

• Hermes: 변동층 07단계 — '불러온 기억'으로 조립

참고: MEMORY.md는 SKILL.md처럼 줄 단위 템플릿이 엄격히 정의된 문서는 아닙니다. 핵심은 "사용자의 선호와 과거 결정을 저장하는 장기 기억 장치"라는 역할입니다.

8-5. 기억이 잘 반영됐는지 확인하는 법

① 결과물로 검증 (Outcome Verification)

• 최종 결과물이 이전에 저장한 사실·선호·결정을 따르고 있는가?

• 첫 실행 로그: 예상 결과 vs 실제 결과를 비교해 pass / partial / fail로 기록

② Context X-Ray로 시각 확인

• 초록색(🟩)으로 표시된 부분이 곧 기억·사용자 정보에서 온 내용

• 그 초록색 영역에 내가 의도한 데이터가 들어 있는지 확인

③ 런타임별 확인

• Hermes: 새 세션에서 이전 저장 내용이 다시 나타나는지 / USER.md·MEMORY.md가 변동층에 잘 로드됐는지

• OpenClaw: MEMORY.md·HEARTBEAT.md가 유지되는지 / 로딩 순서에 맞게 주입됐는지

8-6. 기억이 작동 안 할 때 — 원인은 셋 중 하나다 ★

증상: MEMORY.md에 "사용자는 존댓말을 선호함"이라고 저장해 뒀는데, 새 세션에서 반말이 나온다.

❌ 흔한 오진: "기억 기능이 고장났다" → 저장을 또 하고, 또 안 되고, 반복

✅ X-Ray를 찍으면 원인이 셋 중 하나로 갈립니다.

🎯 핵심: "저장됐는가" / "꺼내졌는가" / "이겼는가"는 전부 다른 문제입니다.
셋을 구분하지 않으면 엉뚱한 곳만 계속 고치게 됩니다.
특히 ③번은 4장에서 배운 "충돌하면 먼저 읽은 층이 이긴다"가 그대로 적용되는 사례입니다.

9장. Context X-Ray — 에이전트의 책상을 찍는 사진

9-1. 아주 쉽게

Context X-Ray는 에이전트가 지금 이 작업을 하려고 머릿속에 어떤 정보를, 어떤 순서로 펼쳐놨는지를 보여주는 진단 도구입니다.

한 줄 비유: "에이전트가 책상 위에 어떤 자료를 어떤 우선순위로 올려두었는지 보여주는 작업 환경 리포트"

9-2. 특징 4가지

1. 진짜 '내용'을 본다 — 파일 이름 나열이 아니라, 현재 세션에 실제 로딩된 시스템 프롬프트 전체를 읽어서 보여줌

2. 출처를 색으로 구분 — 어떤 정보가 어디서 왔는지 한눈에

3. 시각화 결과물 제공 — context-xray.html(색상 시각화) + context-xray.md(텍스트 백업)

4. 왜 필요한가 — 내 지침이 제대로 전달됐는지, 정보가 너무 많아 에이전트가 혼란스럽지 않은지 엑스레이 찍듯 진단

9-3. 색상 범례 (Color Legend) ★

9-4. 어떻게 만들어졌나 — 5가지 설계 원리

① 실제 데이터 수집 (Evidence Priority) — '실제성' 최우선, 다음 순서로 수집:

1. Snapshot — 현재 세션에 실제 로딩된 시스템 프롬프트 스냅샷

2. Runtime Parts — 런타임이 제공하는 프롬프트 조립 부품 (build_system_prompt_parts() 등)

3. Reconstruction — 스냅샷 접근이 불가하면, 로딩된 소스 파일 + 런타임 우선순위 규칙으로 재구성

② 정보의 계층화 (Tiers) — 안정층 / 작업층 / 변동층으로 분류 (4장 참조)

③ 시각적 분류 (Color Legend) — 위 9-3 색상 코드 부여

④ 결과물 생성 및 전달 (Artifacts & Delivery) — HTML + Markdown 생성 후, 반드시 채팅창에 직접 전달(Delivery Gate)해야 다음 단계로 진행 가능

⑤ 보안 설계 — API 키·토큰·비밀번호는 절대 포함하지 않고, 마스킹된 정보는 빨간색으로 표시

요약: 실제 로딩 데이터 추출 → 계층 분류 → 색상 부여 → 시각화 파일 생성

9-5. 실행 결과 확인하는 법

① 산출물 확인

• context-xray.html — 계층별 배경색으로 시각화

• context-xray.md — 색상 이모지(🟪🟦…)를 쓴 텍스트 대체본

② 전달(Delivery) 방식 확인 ★

• 파일 첨부 지원 시: 두 파일을 채팅창에 직접 첨부 + 응답에 파일명 명시

• 파일 첨부 미지원 시: 응답 안에 ## Context X-Ray 헤드라인을 만들고 결과 전체를 인라인 텍스트로 반환

• ❌ "파일을 만들었습니다"라고만 말하거나 경로만 남기는 것은 전달 실패로 간주

③ 실행 품질(Status) 확인

학습 과정에서는 X-Ray 결과가 사용자에게 실제 전달됨(delivered_inline 또는 delivered_attachment)이 확인되어야만 다음 Station으로 진행합니다. 못 받았다면 다시 출력을 요청하세요.

9-6. 실제 리포트는 이렇게 생겼다 (샘플)

ℹ️ 아래는 이해를 돕기 위한 예시입니다. 실제 값과 항목은 환경마다 다릅니다.

context-xray.md 출력 예시

이 리포트에서 반드시 읽어내야 할 4가지 ★

🎯 X-Ray를 보는 습관: 예쁜 색깔 구경이 아닙니다.
"내가 넣은 게 다 들어왔나(누락)", "넣은 적 없는 게 들어왔나(오염)", "비밀이 새고 있나(보안)" 이 세 가지를 확인하는 것입니다.

10장. Context Document Doctor — 설정 문서 건강검진

10-1. 하는 일

실제 파일을 수정하기 전에 컨텍스트 내부를 감사(Audit)해 다음을 찾아냅니다.

• Conflicting rules — 서로 충돌하는 규칙

• Duplicated instructions — 중복된 지시 (예: /personality의 말투와 SOUL.md의 말투가 겹쳐 컨텍스트 낭비)

• 오래되어 유효하지 않은 내용

10-2. 진단 결과 3분류

10-3. 안전장치 ★

• 도구는 파일을 자동 수정하지 않습니다. 제안만 합니다.

• 실제 문서 수정(Live overwrite)에는 사용자의 명시적 승인 + 변경 전후 Diff 확인이 반드시 필요합니다.

10-4. X-Ray와의 역할 분담

10-5. 이 도구들은 기본 기능인가?

네. 이 문서에서만 쓰는 개념이 아니라, 에이전트 하네스 환경(Hermes/OpenClaw)에 내장된 진단 기능입니다. 별도 소프트웨어 설치가 아니라, 에이전트가 자기 상태를 점검하는 역량(Capability)으로 작동합니다.

내 환경에서 작동하는지 확인하는 3단계

1. 역량 진단(Capability Probe) 실행 — "1주차 학습 시작해줘" 또는 /w1-learning-guide 입력
   → 에이전트가 파일 쓰기 가능 여부, 런타임 프롬프트 접근 가능 여부를 스스로 확인합니다. 권한이 없으면 unknown/not_checked로 표시하고, 결과를 전부 채팅창 텍스트로 주겠다고 안내합니다.

2. Station 도달 확인 — Station 2에서 X-Ray, Station 5에서 Document Doctor가 실제로 실행되는지

3. 산출물 확인 — context-xray.html/.md, context-document-doctor.md가 실제로 생성·전달되는지

런타임별 확인 팁

• Hermes: build_system_prompt_parts() 등으로 프롬프트 구조에 접근해 안정층/작업층/변동층 정보를 가져오는지

• OpenClaw: 작업공간의 SKILL.md를 인식하고 openclaw skills list로 스킬 목록이 정상 출력되는지

10-6. 실제 진단 리포트는 이렇게 생겼다 (샘플)

ℹ️ 이해를 돕기 위한 예시입니다.

context-document-doctor.md 출력 예시

리포트를 받았을 때 할 일 3단계

1. candidate 항목을 검토하고 직접 파일을 수정 — 도구는 절대 대신 고쳐주지 않습니다

2. 수정 후 X-Ray를 다시 찍어 중복·충돌이 사라졌는지 눈으로 확인

3. hold는 판단 보류로 남겨두고 나중에 정리

🎯 2번째 행이 이 도구의 진짜 가치입니다.
사용자는 "존댓말로 해달라"고 기억까지 저장했는데 계속 반말이 나오는 상황(8-6절 ③번)에서,
범인이 SOUL.md라는 걸 짚어주는 것이 Document Doctor입니다.
X-Ray가 "무엇이 들어왔나"를 보여준다면, Doctor는 "들어온 것들끼리 누가 이기고 있나"를 알려줍니다.

11장. SKILL.md 만들기 — 1주차의 최종 목표

11-1. SKILL.md란 (아주 쉽게)

인공지능 친구와 함께 일할 때 쓰는 '공부 안내서' 또는 '업무 계획표'입니다. "이런 순서로 나를 도와줘"라고 부탁하는 가이드북.

11-2. 학습용 SKILL.md에 담긴 것 (예: W1 학습가이드)

1. 인사와 약속 — 자료를 무단 배포·수정하지 않겠다는 동의를 먼저 받습니다. 동의해야 학습이 시작됩니다.

2. 시작 명령(Trigger) — "1주차 학습 시작해줘" 또는 /w1-learning-guide

3. 8단계 코스 (39페이지 정본 덱 기준)

   • 1~2단계: 목표 설정 + 에이전트의 작업 환경 이해

   • 3~5단계: 정보를 어떻게 읽고(Context) 어떻게 기억하는지(Memory)

   • 6~8단계: 실제 업무 설명서(Skill)를 만들고 작동 확인

4. 나만의 Skill 만들기 — 아래 4가지 질문에 답하기

5. 비밀 지키기 — 주소·비밀번호·회사 기밀은 절대 넣지 않기

11-3. 내 Skill을 만드는 4가지 질문 ★

이 네 가지를 채우면 재사용 가능한 업무 계약이 됩니다.

11-4. 첫 실행 기록 (First Run Log)

Skill을 만들었으면 반드시 한 번 돌려보고 기록합니다.

• 예상 결과를 먼저 적는다

• 실제 결과와 비교한다

• 상태를 pass / partial / fail로 기록한다

• 에이전트가 지침을 잘 지켰는지 관찰하고, 어긋난 부분을 Skill에 반영한다

11-5. 완성된 SKILL.md 예시 — 그대로 베껴 써도 되는 뼈대

"주간 보고서" 업무를 Skill로 만든 완성본입니다. 6개 블록으로 되어 있습니다.

---
name: weekly-report
description: 매주 금요일 주간 보고서를 규칙에 맞춰 작성한다
---

# 주간 보고서 작성

## 1. 언제 (Trigger)
- "주간 보고서 써줘", "이번 주 보고서", "/weekly-report"
- 매주 금요일 17:00 (Cron 예약 시)

## 2. 준비물 (Input)
- `data/sales.csv` — 매출 원본 (필수)
- `data/signup.csv` — 신규 가입 (필수)
- `reports/` 폴더의 지난주 보고서 (있으면 비교용)
- 권한: 파일 읽기, 파일 쓰기

## 3. 순서 (Procedure)
1. 이번 주 월~금 날짜 범위를 계산한다
2. sales.csv에서 해당 범위 합계를 구하고 전주 대비 증감률을 계산한다
3. signup.csv에서 신규 가입 수와 목표 달성 여부를 확인한다
4. 지난주 보고서가 있으면 3주 연속 하락한 지표가 있는지 확인한다
5. AGENTS.md의 형식 규칙(3줄 요약)에 맞춰 작성한다
6. reports/{이번 주 금요일 날짜}.md 로 저장한다
7. 저장한 내용을 채팅창에 그대로 출력한다

## 4. 결과 (Output)
- 파일: `reports/YYYY-MM-DD.md`
- 형식: 글머리 기호 3줄 (매출 / 신규 가입 / 주의 지표)
- 채팅창에 전문 출력 — 경로만 남기면 실패로 간주

## 5. 하지 말 것 (Guardrail)
- 원본 CSV를 수정하지 않는다
- 데이터가 없는 항목은 추측하지 않고 "데이터 없음"으로 표기한다
- 외부로 데이터를 전송하지 않는다

## 6. 완료 기준 (Done)
- [ ] 파일이 생성되었다
- [ ] 3줄 규칙을 지켰다
- [ ] 채팅창에 내용이 출력되었다
- [ ] 숫자가 원본 CSV와 일치한다

💡 11-3절의 4가지 질문에 2개를 더 붙인 형태입니다.
5. 하지 말 것과 6. 완료 기준은 실무에서 사고를 막아주는 부분이라 꼭 넣으시길 권합니다.
(특히 "원본을 수정하지 않는다" 한 줄이 데이터를 여러 번 살립니다.)

11-6. 잘 쓴 Skill vs 못 쓴 Skill

같은 업무를 두 사람이 Skill로 적었습니다. 무엇이 다른지 보세요.

🎯 판별법 한 문장
그 Skill을 오늘 입사한 신입에게 종이로 건네주고 시켰다고 상상해 보세요.
되묻지 않고 혼자 끝낼 수 있으면 잘 쓴 Skill입니다.
신입이 되물을 지점이 있다면, 에이전트도 정확히 그 지점에서 흔들립니다.

12장. 1주차 실습 코스와 산출물 체크리스트

12-1. 진행 흐름

동의 → 역량 진단(Capability Probe) → 런타임 판별(Hermes/OpenClaw)
  → Station 1~2: 목표 설정 + Context X-Ray 실행
  → Station 3~4: Memory 이해 및 확인
  → Station 5: Context Document Doctor 실행
  → Station 6~8: 나만의 SKILL.md 작성 + 첫 실행 기록
  → 사례글 작성 → Watchdog 제출

12-2. 필수 산출물 체크리스트

• context-xray.html — 계층별 색상 시각화 리포트

• context-xray.md — 텍스트 기반 대체본

• context-document-doctor.md — keep/candidate/hold 진단 리포트

• 나만의 SKILL.md — Trigger / Input / Procedure / Output 4항목 완비

• 첫 실행 기록 — 예상 vs 실제, pass/partial/fail

• 업무 사례글 — 위 결과를 정리한 글

• Watchdog 제출

12-3. 자주 걸리는 지점 3가지

1. 전달 실패 — 파일을 만들고 "만들었습니다"라고만 하면 실패. 반드시 첨부하거나 인라인으로 출력할 것.

2. AGENTS.md 부재 — 새 폴더에서 작업하면 파란색(🟦)이 텅 비어 있음. 직접 작성해야 함.

3. 민감 정보 유출 — API 키·비밀번호·회사 기밀은 절대 문서에 넣지 말 것.

부록 A. 한 장 요약 — 컨텍스트 조립 지도

한 문장 요약: 에이전트는 "누가(성격) → 무엇으로(도구·기술) → 어떤 규칙으로(프로젝트 문서) → 무엇을 기억하며(기억·사용자)" 순서로 정보를 흡수해 판단 근거를 완성합니다.

부록 B. 용어집