에이전트가 스스로 배운다고? Claude Code로 hermes-agent 내부를 직접 뜯어봤다 (1주차_과제2)

## 📝 한줄 요약

코드를 전혀 못 읽는 상태에서 Claude Code와 함께 자기개선 AI 에이전트의 동작 원리를 하루 만에 파악했고, 앞으로 내가 만들고 싶은 에이전트의 방향이 바뀌었다.

**바쁘시면 이것만 읽어도 돼요:**

- Claude Code로 오픈소스 AI 에이전트(hermes-agent) 코드베이스를 하루 만에 분석
- 에이전트가 "스스로 대화를 복기하고 기억을 업데이트"하는 구조가 실제로 코드에 있다
- 인간이 중간에 개입해서 지시하는 구조만 써봤는데 → 에이전트가 스스로 검토하고 최종물을 가져오는 구조를 원하게 됨
- 코드 까막눈도 쓸 수 있는 5단계 에이전트 분석 프레임워크를 (의도치 않게) 직접 만들었다
- Hermes Agent를 직접 설치해보고, 이 프레임워크로 다른 에이전트도 분석해볼 계획

---

## 🎯 이런 분들께 도움돼요

- 자기개선형 에이전트가 뭔지 궁금하지만 코드를 못 읽는 분
- AI 에이전트를 만들어봤는데 "항상 인간이 중간에서 봐줘야 하나?" 싶은 분
- Claude Code를 코딩이 아닌 학습 도구로도 쓸 수 있다는 걸 몰랐던 분

---

## 😫 문제 상황 (Before)

저는 AI 에이전트를 여러 개 만들어봤습니다. 그런데 제가 아는 구조는 항상 이런 식이었어요.

> 에이전트가 뭔가 하면 → 내가 결과를 보고 → 다시 지시를 내리고 → 에이전트가 수정하고 → 반복

사람이 중간에 계속 개입해서 방향을 잡아주는 구조입니다. 여러 에이전트를 연결할 때도 마찬가지였어요. A가 하면 B에게 넘기고, B가 하면 C에게 넘기는 선형 파이프라인. 인간 오케스트레이터가 없으면 잘 굴러가지 않는 구조였죠.

그러다가 hermes-agent라는 오픈소스를 발견했습니다. 소개 문구가 인상적이었어요.

> "경험에서 스킬을 만들고, 사용하면서 스스로 개선하며, 세션을 넘어 기억을 유지한다"

에이전트가 스스로 배운다고요? 어떻게요? 코드를 보면 알 수 있겠지만 저는 코드를 못 읽습니다. 그래서 Claude Code에게 물어봤습니다.

---

## 🛠️ 사용한 도구

- **도구**: Claude Code
- **모델**: Claude Sonnet 4.6
- **분석 대상**: hermes-agent (Nous Research 오픈소스)

---

## 🔧 작업 과정

### "추측 금지, 코드 인용 필수" — 규칙부터 세웠다

처음부터 한 가지를 못 박았습니다. AI가 그냥 아는 척 설명하는 게 아니라, 실제 코드를 직접 열어서 확인한 것만 얘기해달라고요.

```
지금부터 이 레포지토리의 동작 원리를 너와 함께 공부할 거야.
너는 이 코드베이스를 처음 보는 신규 기여자에게 설명하는 시니어 엔지니어야.

규칙:
1. 절대 기억이나 추측으로 답하지 말고, 먼저 관련 파일을 직접 열어서 읽고 확인해.
2. 모든 핵심 주장 옆에는 근거가 되는 위치를 파일명:라인번호 형식으로 인용해.
3. 코드에서 확인한 사실과 추론을 [확인] / [추론] 태그로 구분해.
4. 모르거나 코드에서 못 찾은 건 솔직히 "확인 불가"라고 말해. 지어내지 마.
5. 각 답변 끝에 핵심 3줄을 STUDY-LOG.md 파일에 누적 기록해.
```

이 규칙 덕분에 Claude Code가 실제로 파일을 열고, 함수를 찾고, 라인 번호를 붙여서 설명하는 방식으로 진행됐습니다. 그냥 "이렇게 동작합니다" 가 아니라 "이 파일 598번째 줄에 이런 코드가 있고, 이 코드가 이런 의미입니다"처럼요.

---

### Q1. 이게 뭔가? — 정체부터

```
README와 패키지 설정 파일만 읽고
'이 프로젝트가 한 줄로 무엇인지 + 주 언어/실행 방식'을 알려 줘.
```

Hermes Agent는 Nous Research라는 AI 연구팀이 만든 프레임워크로, 핵심은 딱 세 가지였습니다.

- 대화를 하면서 **스킬(재사용 가능한 노하우 파일)을 자동으로 만든다**
- 세션이 끝나도 **기억이 유지된다** (크로스세션 메모리)
- 사용할수록 **스스로 개선된다**

흥미로운 발견도 있었습니다. 의존성(외부 라이브러리) 버전을 아주 엄격하게 고정해놨는데, 코드 주석에 그 이유가 나와 있었어요. 과거에 누군가 악성 코드를 심은 라이브러리를 배포해서 많은 프로젝트가 피해를 입은 사건이 있었고, 그 대응으로 이렇게 설계했다고요. 코드 주석에 사건 이름까지 적혀 있었습니다.

---

### Q2. 어떻게 돌아가나? — 실행 흐름 추적

```
사용자 메시지 1건이 처리되는 흐름을 실제 함수 호출 순서대로 추적해 줘.
LLM 호출 지점, 도구 실행 지점, 루프 종료 조건도 포함해서.
```

hermes 명령어를 치면 내부에서 6단계의 호출이 이어집니다. Claude Code가 실제로 각 파일을 열어 확인하면서 이 흐름을 추적했어요.

핵심은 `while` 루프가 하나 있다는 겁니다. 이 루프 안에서 LLM에게 물어보고, LLM이 도구를 쓰라고 하면 도구를 실행하고, 결과를 다시 LLM에게 주고, LLM이 "이제 됐다"고 하면(= 도구를 더 안 쓰면) 루프가 끝납니다. 이게 에이전트의 기본 작동 방식이었습니다.

루프가 강제로 끝나는 조건도 4가지로 명확했습니다. 인터럽트, 최대 반복 횟수 초과(기본 90회), 안전장치 발동.

---

### Q3. 무엇을 알고 있나? — 시스템 프롬프트의 조립

```
시스템 프롬프트를 조립하는 함수를 찾아서 열어 줘.
SOUL.md / MEMORY.md / USER.md / skills / AGENTS.md 등이
어떤 순서로 합쳐지는지 알고 싶어.
```

시스템 프롬프트(에이전트가 항상 받는 기본 지시문)가 세 층으로 나뉘어 조립된다는 걸 알게 됐습니다.

1. **고정층**: 에이전트의 신원, 쓸 수 있는 도구 목록, 스킬 목록
2. **프로젝트층**: 현재 작업 중인 프로젝트의 설명 파일
3. **가변층**: 메모리, 사용자 정보, 날짜

이 중 날짜 처리 방식이 흥미로웠습니다. 날짜를 "2026년 5월 24일 14시 32분"처럼 분 단위로 넣지 않고, "2026년 5월 24일"처럼 날짜만 넣어요. 이유가 코드 주석에 적혀 있었는데, 분 단위로 넣으면 시간이 바뀔 때마다 Anthropic 서버의 캐시가 무효화되어 비용이 올라가기 때문이라고요. 실용적인 최적화였습니다.

세션 시작 때 한 번 만들어두고, 세션 내내 같은 것을 재사용합니다. 맥락이 너무 길어져서 압축이 일어날 때만 강제로 다시 만든다고 하고요.

---

### Q4. 무엇을 할 수 있나? — 도구 시스템

```
도구가 등록되고 실행되는 코드를 찾아서 설명해 줘.
비활성 도구가 어떻게 빠지는지,
memory/skill/todo 같은 도구가 따로 처리되는 지점이 있는지 알고 싶어.
```

도구(웹 검색, 파일 읽기, 터미널 실행 등)가 등록되는 방식도 흥미로웠습니다. 각 도구 파일이 불러와질 때 스스로 "나 이런 도구야"라고 등록하는 구조입니다.

더 재미있는 건 환경 체크입니다. Docker가 설치돼 있는지, SSH 서버가 켜져 있는지를 실제로 확인해서, 쓸 수 없는 환경의 도구는 LLM이 애초에 볼 수 없게 목록에서 빼버립니다. LLM이 "Docker로 실행해볼게요"라고 헛소리하는 상황을 원천 차단하는 거죠.

그리고 메모리, 스킬, 할 일 관리 같은 도구는 일반 도구와 처리 경로 자체가 다릅니다. 에이전트의 내부 상태와 직접 연결돼야 하는 도구들이라, 별도 경로로 처리됩니다.

---

### Q5. 어떻게 성장하나? — 자기개선 루프의 실체

```
이 에이전트가 스스로 배워 가는 흐름을 코드로 추적해 줘.
MEMORY.md / USER.md가 언제 갱신되는지,
skill 파일이 생성되는 조건이 어디 있는지 알고 싶어.
```

이게 가장 흥미로웠던 부분입니다. 그리고 동시에 가장 이해하기 어려웠던 부분이기도 합니다.

10번의 대화가 오가면, 에이전트가 백그라운드에서 조용히 "복습"을 합니다. 별도의 에이전트 인스턴스가 데몬 스레드로 실행되면서 지금까지의 대화를 돌아보고, 기억 파일과 스킬 파일을 업데이트합니다. 사용자는 전혀 모르게요.

이 복습 에이전트는 철저히 제한됩니다. 메모리와 스킬 도구만 쓸 수 있고, 최대 16번의 대화만 허용되고, 출력은 아무 데도 안 나타납니다. 그리고 비용 절감을 위해 부모 에이전트가 이미 만들어놓은 시스템 프롬프트를 그대로 물려받습니다. 실제로 이렇게 하면 비용이 약 26% 절감된다는 게 코드 주석에 나와 있었고, 심지어 그걸 측정한 이슈 번호까지 적혀 있었습니다.

이 부분은 흐름은 이해했지만, 세부 동작이 완전히 손에 잡히지는 않았습니다. 자기개선 루프 에이전트를 직접 써본 적이 없어서, 아직은 "이런 절차가 있구나" 정도의 감각입니다.

---

### Q6. 내가 이해한 게 맞나? — 검증과 퀴즈

```
이전 답변 중 [추론]으로 표시했던 부분만 다시 모아,
코드로 재확인하거나 여전히 불확실하면 "확인 불가"로 정리해줘.
신규 기여자 관점에서 추천 코드 읽기 순서도 정리하고,
내 이해도를 점검하는 퀴즈 3문제 출제해줘.
```

26% 비용 절감, Mini Shai-Hulud 웜 사건, 날짜 포맷 이유 등 핵심 수치와 주장들을 전부 코드에서 재확인했습니다. 모두 코드 주석에 직접 명시되어 있었습니다.

퀴즈는 3문제를 받았고, 1.5점을 받았습니다.

- **Q1 (날짜 포맷)**: "거짓"은 맞혔는데, 왜 거짓인지 설명 못 함
- **Q2 (도구 실행 경로)**: 완전히 몰라서 "모른다"고 답함
- **Q3 (보안 검사 실패 시)**: "나에게 물어보는 거 아닌가?"라고 답했는데, 실제로는 자동으로 롤백함

틀린 건 창피하지 않습니다. 이게 내가 아직 손에 안 잡힌 부분이라는 걸 정확하게 알게 됐으니까요.

---

## ✅ 결과 (After)

### Before vs After

| 항목                        | Before                     | After                                  |
| --------------------------- | -------------------------- | -------------------------------------- |
| 자기개선 에이전트           | "그런 게 있다더라" 수준    | 어떤 구조로 동작하는지 흐름 파악       |
| 코드 분석 방법              | 엄두도 못 냄               | 5단계 질문으로 접근하는 법을 앎        |
| 앞으로 만들고 싶은 에이전트 | 인간 개입형 오케스트레이션 | 스스로 검토하고 최종물을 가져오는 구조 |

### 핵심 변화

하루 종일 코드를 읽었지만 이해한 건 60% 정도입니다. 나머지 40%는 여전히 까막눈입니다. 그게 솔직한 후기입니다.

그런데 그 60%가 바꿔놓은 게 있습니다. 지금까지 "에이전트 = 인간이 중간에서 지시하는 구조"라고만 생각했는데, "에이전트가 스스로 돌아보고 기억하고 개선하는 구조"가 실제로 코드로 구현될 수 있다는 걸 눈으로 확인했습니다.

---

## 💬 이 과정에서 배운 AI 활용 팁

### 효과적이었던 것

1. **규칙을 먼저 세우기**: "추측 금지, 코드 인용 필수, 모르면 확인 불가라고 해"라고 못 박았더니 헛소리가 없었음
2. **누적 기록 요청하기**: 매 답변 끝에 핵심 3줄을 파일에 쌓도록 했더니 나중에 복기가 편했음
3. **퀴즈로 마무리하기**: 내가 뭘 이해했고 뭘 모르는지를 퀴즈로 명확히 확인할 수 있었음

### 이렇게 하면 안 돼요

1. **"설명해줘"만 반복하기**: 맥락 없이 설명을 요청하면 AI가 아는 척 지어낼 수 있음 — 파일을 먼저 열어서 읽게 해야 함
2. **이해 안 된 채 넘어가기**: 이 세션에서 Q5(자기개선 루프)는 흐름만 알고 세부는 놓쳤는데, 그냥 넘어가지 말고 "이 부분을 더 쉽게 설명해줘"라고 했어야 했음

---

## 🌍 다른 업무에 적용한다면?

이번에 (의도치 않게) 만들어진 **5단계 에이전트 분석 프레임워크**는 어떤 AI 에이전트 코드베이스에도 그대로 쓸 수 있습니다.

1. **정체** — 이게 뭔가? (README + 패키지 설정)
2. **실행 흐름** — 어떻게 돌아가나? (진입점부터 루프까지)
3. **입력 구성** — 무엇을 알고 있나? (시스템 프롬프트)
4. **행동 범위** — 무엇을 할 수 있나? (도구 시스템)
5. **성장 메커니즘** — 어떻게 개선되나? (메모리·스킬 루프)

이 5가지 질문 순서대로 Claude Code에게 물어보면, 어떤 에이전트 코드베이스든 하루 안에 윤곽을 잡을 수 있습니다.

---

## 🚀 앞으로의 계획

1. **Hermes Agent 직접 설치**: 메모리와 스킬이 실제로 쌓이는 걸 직접 경험해보고 싶다. 코드로 읽은 것과 실제로 써본 건 다를 것 같으니까.
2. **이 프레임워크로 다른 에이전트 분석**: OpenCode, 다른 오픈소스 에이전트도 같은 5단계 질문으로 비교 분석해볼 계획.
3. **내 프로젝트에 자기개선 루프 도입**: 지금까지 인간이 중간에서 다 봐줘야 하는 구조로만 만들었는데, 에이전트가 스스로 검토하고 최종물을 가져오는 구조를 직접 설계해보고 싶다.

---

## 📋 재사용 가능한 프레임워크

### 에이전트 코드베이스 5단계 분석 프롬프트

> 지금부터 이 레포지토리의 동작 원리를 너와 함께 공부할 거야.
> 너는 이 코드베이스를 처음 보는 신규 기여자에게 설명하는 시니어 엔지니어야.
>
> **규칙:**
>
> 1. 절대 기억이나 추측으로 답하지 말고, 먼저 관련 파일을 직접 열어서 읽고 확인해.
> 2. 모든 핵심 주장 옆에는 근거가 되는 위치를 파일명:라인번호 형식으로 인용해.
> 3. 코드에서 확인한 사실과 추론을 [확인] / [추론] 태그로 구분해.
> 4. 모르거나 코드에서 못 찾은 건 솔직히 "확인 불가"라고 말해. 지어내지 마.
> 5. 각 답변 끝에 핵심 3줄을 STUDY-LOG.md 파일에 누적 기록해.
>
> Q1: README와 패키지 설정 파일만 읽고 이 프로젝트가 무엇인지, 주 언어와 실행 방식을 알려 줘.
> Q2: 사용자 메시지 1건이 처리되는 흐름을 함수 호출 순서대로 추적해 줘. LLM 호출 지점, 도구 실행 지점, 루프 종료 조건 포함.
> Q3: 시스템 프롬프트를 조립하는 함수를 찾아서 열어 줘. 각 파일이 어떤 순서로 합쳐지는지, 세션 중간에 바뀌는지 확인해.
> Q4: 도구가 등록되고 실행되는 코드를 찾아서 설명해 줘. 비활성 도구가 어떻게 빠지는지, 특별히 처리되는 도구가 있는지 확인해.
> Q5: 에이전트가 스스로 배워 가는 흐름을 코드로 추적해 줘. 기억이 언제 갱신되고, 스킬이 어떤 조건에서 만들어지는지 확인해.
>
> [분석할 레포지토리 경로나 이름]을 바꿔서 쓰세요.