[w1오프라인 수업 따라가기] 내 하네스가 워크스페이스를 스스로 개선되게 만들었다

## 📝 한줄 요약

엔지니어H님의 오프라인 수업에서 실습한 내용을 사례글로 정리해보았습니다. (그래서 다 아시는 내용일거에요)
유튜브 세미나를 매일 자동으로 모아 근거가 붙은 노트로 정리하고, 거기서 **"내 워크스페이스의 이 파일 이 줄을 이렇게 고쳐라"** 수준의 변경안을 뽑아내는 파이프라인을 하루 만에 만들었습니다. 노트를 아무리 잘 써도 워크스페이스는 그대로였던 문제를 끊어낸 게 핵심입니다.

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

- Claude Code(Opus 5)로 유튜브 세미나 → 위키 노트 → **워크스페이스 개선 제안서**까지 도는 파이프라인 구축. 세미나 1건 정리 2시간+ → 자동 수집 7.6초

- 핵심 설계는 노트에 **`## 워크스페이스 적용 후보`** 라는 칸을 강제로 만든 것. 노트를 쓰는 시점에 "이건 내 어디에 쓸 수 있다"를 미리 뽑아두니, 나중에 제안을 만들 때 노트 전체를 다시 읽지 않아도 됨 → **노트가 100개가 돼도 비용이 안 늘어남**

- 판단이 필요 없는 일(수집)만 무인 자동화하고, 판단이 필요한 일(노트·제안)은 세션에서. 다 자동화하려다 비용·실패 리스크만 키우는 걸 피함

- AI의 첫 질문이 "무슨 기능 만들까요?"가 아니라 **"최근에 세미나 보고 반영하려다 못 한 순간을 한 장면으로 들려주세요"** 였음. 그리고 "둘 다야"라는 두루뭉술한 답에서 멈추지 않고 한 번 더 파고들어서, 제품 성격이 그 답 하나로 확정됨

- 결국 이 파이프라인이 **내 AGENTS.md에서 실행조차 안 되던 명령어**를 찾아내 제안으로 올림. 내가 만든 문서를 내가 만든 도구가 감사한 셈

- 배운 것: 내 의도를 먼저 파일로 적어둘 것 / 산출물을 "변경안"까지 요구할 것 / "기존 걸 깨뜨리지 마"를 명시적으로 금지 목록에 넣을 것

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

- 이미 CLAUDE.md / AGENTS.md 같은 워크스페이스 규약을 쓰고 있고, 그걸 더 잘 굴리고 싶은 분

- LLM Wiki·PKM을 구축 중인데 "자료는 쌓이는데 시스템이 나아지진 않는" 정체를 겪는 분

- AI 에이전트 하네스를 설계하면서 "지식이 실제 행동 변화로 이어지게" 만들고 싶은 분

## 😫 문제 상황 (Before)

노트를 안 쓴 게 문제가 아니었습니다. **잘 쓴 노트가 아무것도 바꾸지 못하는 게** 문제였습니다.

전날 유튜브 세미나 2개를 정리했습니다. 대충 한 게 아니라 트랜스크립트를 실제로 읽고, 모든 주장에 타임스탬프를 달고, 관련 노트끼리 링크까지 걸었습니다. 73분짜리 세미나 하나에 두 시간 넘게 들었습니다.

그런데 다 쓰고 나니 이상했습니다. 노트 폴더는 두꺼워졌는데 **정작 제 워크스페이스는 어제와 똑같았습니다.** 노트에는 "인박스 / 로우소스 / 위키 3단 분리가 핵심이다" 같은 좋은 내용이 적혀 있는데, 그게 제 AGENTS.md나 스킬 파일로 옮겨가려면 매번 제 머리에서 새로 나와야 했습니다. 노트와 워크스페이스 사이에 다리가 없었습니다.

그리고 노트 2개를 직접 써보고 나서 확신이 왔습니다. **손으로는 못 버팁니다.** 2개에 반나절이 갔는데, 구독 채널이 늘고 영상이 쌓이면 이건 유지가 불가능한 구조였습니다. 규모가 커진 다음에 자동화하려면 이미 밀린 것부터 처리해야 하니까, 어차피 할 거면 지금이었습니다.

## 🛠️ 사용한 도구

- **도구명**: Claude Code

- **모델**: Claude Opus 5

- **특이사항**: 플러그인 3종을 이어 붙여 기획 → 계약 → 구현을 한 세션에 연결 (`show-me-the-prd` → goaljaby → /goal)

- **제약**: 맥 기본 파이썬(3.9.6), 새 라이브러리 설치 없이, DB 없이 파일로만

---

## 🔧 작업 과정

### 내가 뭘 원하는지부터 파일로 적었다

작업을 시작하기 전에 USER_PLAN.md라는 파일 하나를 먼저 만들었습니다. (이하 엔지니어H님의 가이드 프롬트)

```

유튜브 세미나 내용이 너무 길고, 봐야하는 게 너무 많아서 관리가 안됨.

스크립트 기반으로 처음 보는 사람도 쉽게 이해할 수 있도록 세미나 내용을 상세하게 정리해서 관리하고 싶어.

도메인별로 내용을 알아서 카테고라이징 해주면 좋겠어.

하네스 엔지니어링 및 개선 관련한 정보들을 주기적으로(cron활용) 다운로드하고, 관리하고 싶어.

내 워크스페이스나 llm-wiki 개선에 필요한 정보를 내 목적과 의도에 맞게 (domain, task별) 엄선해서 정리하고 싶어.

현 디렉토리에서 시너지날 만한 하네스 개선 정보들을 가져와서 흡수하도록 하고 싶어.

```

---

### 첫 질문이 예상과 완전히 달랐다

이 파일을 물려서 기획 플러그인을 실행했습니다.

```

/show-me-the-prd USER_PLAN.md

```

저는 "어떤 기능을 넣을까요? 1번 2번 3번" 같은 객관식이 나올 줄 알았습니다. 그런데 돌아온 건 객관식이 아니라 **과거를 묻는 열린 질문**이었습니다.

> 최근에 유튜브 세미나를 보고 "이건 내 워크스페이스에 반영해야지" 했는데 결국 반영 못 하고 흘려보낸 순간이 있다면, 그 장면을 한 번 구체적으로 들려주세요.

> — 이걸 알아야 이 시스템이 "수집 자동화" 문제인지, "쌓인 노트에서 실제 개선안을 뽑아내는" 문제인지가 갈립니다.

저는 대충 답했습니다.

```

둘 다야 — 수집도 자동화하고 개선안도 뽑아내고 싶어

```

보통 여기서 "네 알겠습니다" 하고 넘어갑니다. 그런데 안 넘어가고 **한 번 더 파고들었습니다.**

> "개선안이 나왔다"는 걸 뭘 보고 판단하실 건가요?

> — **"읽을거리"**인가요 (이번 주 영상 5개 종합 리포트 → 내가 읽고 판단)

> — 아니면 **"바로 적용할 변경안"**인가요 (네 AGENTS.md에 이 줄을 추가해라, 근거는 이 영상 02:33)

>

> 그리고 수집 대상은 지금 어떻게 찾고 계세요? 구독인가요, 검색인가요, 공유받는 건가요?

```

바로 적용할 변경안까지, 채널 구독

```

**이 한 줄로 제품의 성격이 확정됐습니다.** 요약 도구가 아니라 변경안 생성기. 만약 첫 답변("둘 다야")에서 대화가 끝났다면, 저는 아마 예쁜 요약 리포트를 만들어주는 도구를 받았을 겁니다. 그리고 그건 제 원래 문제를 하나도 해결 못 했을 겁니다.

지금 돌아보면 이게 이번 작업에서 가장 값어치 있는 3분이었습니다.

---

### 설계의 핵심: 노트에 "적용 후보" 칸을 강제로 만들기

방향이 잡히고 나서 나온 설계 중에 하나가 유독 눈에 띄었습니다. 모든 노트에 이런 칸을 **필수로** 두는 겁니다.

> **## 워크스페이스 적용 후보**

> - {무엇을} → {어느 파일/영역에} (근거 {분:초})

별것 아닌 것 같지만 이게 이 시스템의 핵심입니다.

노트가 "요약"에서 끝나면, 나중에 개선안을 뽑을 때 **노트 전체를 처음부터 다시 읽어야 합니다.** 노트가 10개면 어떻게든 되지만 100개가 되면 불가능합니다. 그런데 노트를 쓰는 그 시점에 "이건 내 어디에 쓸 수 있다"를 미리 한 줄로 뽑아두면, 나중 작업은 "전수 재독"이 아니라 **"후보 목록 취합"** 으로 줄어듭니다.

노트가 늘어도 제안을 뽑는 비용이 비례해서 늘지 않습니다. 이게 이 설계의 전부입니다.

실제로 기존 노트에 이 칸을 채워 넣으니 이런 게 나왔습니다.

> - 캡처 시점의 "왜 캡처했는지" 한 줄을 필수 필드로 → TEMPLATE_youtube-note.md 및 AGENTS.md ④ 핵심 원칙 (근거 06:41-07:15)

> - AI 작성물과 사람 작성물의 명시적 분리 → 노트 frontmatter의 status 필드로 구현 (근거 10:38-11:04)

"좋은 내용이었다"가 아니라 **"어느 파일에 무엇을"** 까지 적혀 있으니, 다음 단계가 자동으로 이어집니다.

---

### 판단이 필요 없는 일만 무인으로

또 하나 갈림길이 있었습니다. 매일 도는 자동화를 어디까지 AI에게 맡길 것인가.

- **전부 무인**: 매일 새벽 AI가 알아서 수집하고 노트까지 쓰고 제안까지 만든다

- **2단 분리**: 수집만 무인, 노트·제안은 내가 세션 열었을 때

저는 2단 분리를 골랐습니다. 이유는 단순합니다. **수집은 판단이 필요 없고, 노트와 제안은 판단이 필요합니다.** 판단이 필요한 일을 무인으로 돌리면 매일 비용이 나가고, 실패해도 늦게 알게 됩니다.

결과적으로 이렇게 나뉘었습니다.

> **무인 (매일 오전 9시, 사람 개입 0)**

> 구독 채널 확인 → 새 영상 감지 → 관련 없는 건 걸러내고 → 트랜스크립트 저장 → 대기열에 올림

>

> **세션에서 (내가 한마디 하면)**

> "밀린 거 정리해줘" → 대기열의 영상들에 노트 작성

> "이번 주 개선 제안" → 제안 리포트 생성

---

### 만들어는 줬는데, 어떻게 실행하지?

여기서 한 번 막혔습니다.

기획 문서 5종이 나오고, 검증 기준 문서 5종이 나오고, 구현 명령까지 파일로 준비됐는데 — **정작 그걸 어떻게 실행하는지 몰랐습니다.** 문서 안에 명령어가 들어 있다는 건 알겠는데, 그걸 복사해서 어디에 붙여야 하는지가 안 잡혔습니다.

그래서 그냥 물어봤습니다.

```

goal 실행하려면 어떤 명령어를 넣어? --> 스킬을 깔아놔도 안써보면 이렇게 됩니다.

```

돌아온 답은 간단했습니다. 명령 본문이 이미 파일 하나에 통째로 들어 있으니 그걸 클립보드로 복사해서 붙여넣으면 된다는 것. 한 줄짜리 짧은 버전도 알려줬는데, **긴 버전을 권한다**고 덧붙였습니다. 짧은 버전은 "원본 수정 금지" 같은 안전장치가 참조로만 걸려 있어서, 작업이 길어지면 흘릴 수 있다는 이유였습니다.

돌아보면 이게 AI 도구를 쓰면서 제일 자주 겪는 구간입니다. **결과물은 다 나왔는데 그걸 어떻게 쓰는지 모르는 구간.** 이럴 때 헤매지 말고 그냥 물어보는 게 제일 빠릅니다.

---

### 그리고 실제로 굴러가기 시작했다

구현 루프를 돌리자 다섯 단계가 순서대로 진행됐습니다. 기존 데이터에 필드를 추가하고, 수집기를 만들고, 매일 도는 스케줄에 등록하고, 노트 형식을 바꾸고, 제안 스킬을 만들었습니다.

중간에 두 가지 사고가 있었는데 둘 다 그대로 기록에 남겼습니다.

**하나. 채널을 잘못 찾아냈습니다.** 패스트캠퍼스 채널을 등록하려는데, 웹페이지에서 채널 ID를 긁는 과정에서 **추천 채널의 ID**가 잡혔습니다. 2023년에 업로드가 멈춘 엉뚱한 채널이었습니다. 검증 단계에서 발견해서 고쳤고, 다시는 같은 실수가 안 나도록 "등록한 채널명과 실제 피드의 작성자명이 다르면 아예 건드리지 않는다"는 안전장치를 코드에 넣었습니다.

**둘. 자동 수집 1호가 광고였습니다.** 매일 도는 수집기가 처음으로 잡아온 영상은 68초짜리 **강의 홍보 광고**였습니다. 60초 미만은 거르게 해뒀는데 8초 차이로 통과한 겁니다. 이걸 조용히 지우지 않고, 노트에 그대로 기록하고 "적용 후보: 없음 — 광고성 영상이라 검증된 주장이 없음"이라고 명시했습니다. 그리고 **"키워드 하나만으로는 광고를 못 거른다"** 는 걸 다음 주 개선 제안으로 올렸습니다.

---

### 파이프라인이 내 문서의 버그를 찾아왔다

마지막 단계에서 제안 리포트가 나왔습니다. 9장짜리였는데, 첫 장을 보고 좀 놀랐습니다.

> **제안 W30-01 [중요도 高]**

> **대상**: AGENTS.md → ⑥ 워크플로우

> **현재**: wiki_index.py --rebuild로 색인

> **제안**: wiki_index.py --workspace .로 색인

> **근거**: 실측 — --rebuild 옵션이 존재하지 않는다. 실행하면 즉시 에러가 난다

> **영향**: 문서대로 따라 하면 색인 단계가 매번 실패한다

제가 어제 직접 쓴 워크스페이스 규약 문서였습니다. 거기 적힌 명령어가 **실행조차 되지 않는 상태**였습니다. 저는 몰랐고, 문서를 다시 읽어봤어도 못 찾았을 겁니다. 실제로 실행해봐야 아는 거니까요.

제안 9장 중에 3장을 골라 적용했습니다. 그런데 여기서도 작은 사건이 있었습니다. 승인한 3장을 반영하는 과정에서 **승인하지 않은 제안의 문장 하나가 딸려 들어갔습니다.** 그걸 발견하고 그 문장만 다시 걷어냈습니다. "적용은 내가 판단한다"는 규칙을 스스로 어긴 셈이라, 조용히 넘어가지 않고 되돌린 게 맞다고 봅니다.

## ✅ 결과 (After)

### Before vs After

| 항목 | Before | After |

|------|--------|-------|

| 세미나 1건 정리 | 2시간 이상 (73분 영상 기준, 되감기 포함) | 자동 수집 **7.6초** + 노트 작성은 세션에서 |

| 새 영상 확인 | 채널 들어가서 직접 확인 → 자주 놓침 | 매일 오전 9시 자동 (15건 훑어 1건 선별, **내 개입 0**) |

| "그거 어디서 봤더라" | 73분 영상을 처음부터 다시 재생 | 노트에서 **"12분 04초"** 로 바로 점프 |

| 워크스페이스 개선 | "언젠가 정리해야지" (막연함) | **제안 9장 중 골라서 체크** (그중 1장은 몰랐던 버그) |

| 노트가 늘어날 때 | 정리 시간이 비례해서 증가 | 제안 생성 비용은 **거의 그대로** |

### 결과물

- 매일 자동으로 도는 수집기 (맥 스케줄러에 등록 완료 — 다음 날 오전 9시부터 알아서 돔)

- 위키 노트 3건 (모든 주장에 타임스탬프 근거)

- 첫 주간 개선 제안서 9장 — 각 카드에 대상 파일 / 위치 / 복붙 가능한 변경 문구 / 근거 / 영향 / 판정 체크박스

- 무결성 검사기 — 원본 트랜스크립트가 수정됐는지, 기존 데이터 필드가 사라졌는지, 승인 없이 분류 체계가 늘었는지 자동 검사

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

### 효과적이었던 것

1. **내 의도를 먼저 파일로 적어둘 것.** 빈 상태에서 AI에게 물으면 대화가 헛돕니다. 정제되지 않은 불만 목록이라도 파일 하나로 만들어 물려주면, AI가 던지는 질문의 질이 달라집니다. 실제로 파일 없이 시작했다가 중단하고 파일부터 만들었는데, 그게 제일 잘한 판단이었습니다.

2. **산출물을 "변경안"까지 요구할 것.** "정리해줘"에서 멈추면 읽을거리만 쌓입니다. **"어느 파일 어느 줄을 어떻게 고쳐라"** 까지 나오게 해야 실제로 적용됩니다. 이 차이 하나가 "노트는 쌓이는데 아무것도 안 바뀌는" 정체를 끊습니다.

3. **"기존 걸 깨뜨리지 마"를 명시적인 금지 목록으로 만들 것.** "원본 트랜스크립트 수정 금지", "기존 필드 제거·개명 금지", "참고용 외부 자료 수정 금지" 같은 걸 문서에 적어두고, 그걸 **검사하는 스크립트**까지 만들어두면 AI가 기존 시스템에 증축 작업을 해도 안심할 수 있습니다. 실제로 이번에 데이터 구조를 바꿨는데, 백업본과 대조해서 "사라진 필드 0건, 값 변경 0건"을 확인하고 넘어갔습니다.

4. **판단이 필요 없는 일만 무인으로 돌릴 것.** 다 자동화하고 싶은 유혹이 있는데, 판단이 필요한 작업을 무인으로 돌리면 비용은 매일 나가고 실패는 늦게 발견됩니다. 수집(판단 불필요)과 정리·제안(판단 필요)을 나눈 게 결과적으로 옳았습니다.

### 이렇게 하면 안 돼요

1. **두루뭉술한 답변을 그대로 받아들이지 마세요.** 제가 "둘 다야"라고 답했을 때 AI가 그냥 넘어갔다면 엉뚱한 걸 만들었을 겁니다. 반대로 여러분이 AI에게 요청할 때도, AI가 애매한 답을 주면 한 번 더 파고들어야 합니다.

2. **결과가 이상해도 조용히 지우지 마세요.** 자동 수집 1호가 광고였을 때, 그냥 지웠으면 "왜 광고가 걸렸는지"가 기록에 안 남았을 겁니다. 실패를 기록으로 남기니까 그게 다음 개선 제안이 됐습니다.

3. **승인 범위를 넘어선 변경을 방치하지 마세요.** 3개만 적용하라고 했는데 4번째 내용이 섞여 들어간 걸 발견했습니다. "어차피 좋은 내용이니까"로 넘어가면 승인 절차 자체가 무의미해집니다.

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

이 구조는 유튜브에만 쓸 수 있는 게 아닙니다. **"정보가 들어오는데 그게 내 시스템 개선으로 안 이어지는" 모든 상황**에 같은 뼈대를 쓸 수 있습니다.

- **사내 문서·회의록** → "우리 팀 위키의 어느 문서를 어떻게 고쳐야 하는지" 주간 제안

- **경쟁사 릴리스 노트 / 업계 뉴스레터** → "우리 제품 스펙 문서에 반영할 항목" 목록

- **고객 피드백** → "FAQ 어느 항목을 어떻게 수정할지" 변경안

- **논문·기술 블로그 구독** → "우리 코딩 컨벤션 문서에 추가할 규칙" 제안

핵심은 도메인이 아니라 **"요약 다음에 한 칸을 더 두는 것"** 입니다. 요약 → **적용 후보** → 변경안. 이 한 칸이 지식과 행동 사이의 다리입니다.

## 🚀 앞으로의 계획

1. **승인하면 자동 반영 (다음 단계)** — 지금은 제안서까지만 나오고 적용은 손으로 합니다. 체크박스만 표시하면 스크립트가 파일을 고치도록 만들 예정입니다. 다만 이건 **실전 제안 데이터가 좀 쌓인 뒤에** 할 생각입니다. 지금 만들면 샘플이 하나뿐인 상태에서 편집 로직을 설계하게 되니까요.

2. **도메인 확장** — 지금은 관심 도메인이 "하네스 엔지니어링" 하나뿐입니다. 폴더를 새로 만드는 게 아니라 분류 항목만 추가하는 방식으로 넓혀볼 예정입니다.

3. **소스 확장** — 유튜브 채널 말고도 키워드 검색, 커뮤니티에서 공유받은 링크, 논문까지 같은 파이프라인으로 받는 것. 이건 노이즈가 확 늘어나는 작업이라 걸러내는 정확도가 검증된 다음에 할 생각입니다.

## 📋 재사용 가능한 프롬프트

### 프롬프트 1: 노트를 "변경안"으로 바꾸는 칸 만들기

> 앞으로 [자료 종류: 세미나 노트 / 회의록 / 아티클 스크랩]를 정리할 때, 요약 아래에 반드시 이 섹션을 추가해줘.

>

> ## 적용 후보

> - {무엇을} → {어느 파일/영역에} (근거 {출처 위치})

>

> 규칙:

> - 적용할 게 없으면 섹션을 지우지 말고 "없음 — {이유}"라고 명시할 것

> - 근거 위치(타임스탬프/페이지/줄 번호)가 없는 항목은 아예 쓰지 말 것

> - 이 섹션은 나중에 개선 제안을 만들 때의 유일한 입력이 된다

### 프롬프트 2: 쌓인 노트에서 실제 변경안 뽑기

> [노트 폴더 경로]의 노트들에서 ## 적용 후보 섹션만 모아서, [대상 파일 목록]에 대한 개선 제안서를 만들어줘.

>

> 반드시 지킬 것:

> 1. 제안을 쓰기 전에 **대상 파일의 현재 내용을 실제로 읽고** 대조할 것. 이미 반영된 건 제안하지 말 것

> 2. [수정하면 안 되는 폴더/파일]은 제안 대상에서 아예 빼줄 것

> 3. 파일을 직접 고치지는 말 것. 산출물은 제안서까지다

> 4. 각 제안은 이 항목을 다 갖출 것: 대상 파일 / 위치 / 현재 상태 / 복붙 가능한 변경 문구 / 근거 / 영향 / 적용·보류·기각 체크박스

> 5. 근거가 없는 제안은 버릴 것

### 프롬프트 3: 기존 시스템에 증축할 때 거는 안전장치

> 지금부터 [기존 프로젝트/워크스페이스]에 새 기능을 추가할 건데, 기존 걸 깨뜨리지 않는 게 최우선이야.

>

> 절대 하지 마:

> - [원본 데이터 폴더]의 파일을 수정·삭제하지 마

> - 기존 데이터의 필드를 제거하거나 이름을 바꾸지 마. **추가만** 해

> - [참고용 외부 자료 폴더]는 읽기만 해

> - 새 라이브러리를 설치하지 마

>

> 그리고 작업 시작 전에, 위 규칙이 지켜졌는지 **자동으로 검사하는 스크립트**를 먼저 만들어줘.

> 각 작업 단계가 끝날 때마다 그 검사를 돌리고, 통과 못 하면 다음 단계로 넘어가지 마.