맥락에서 재사용 가능한 템플릿 만들어보기

개요

Claude Code와 대화하면서 작성한 유튜브 자막 추출 코드를, 대화 맥락만을 활용하여 AI가 자동으로 재사용 가능한 스킬(Skill) 템플릿으로 변환할 수 있는지 테스트했다.

핵심 목표:

• 대화 맥락에서 핵심 정보 추출

• 재사용 가능한 스킬 템플릿 자동 생성

• Claude Code, Cursor, Windsurf 등 다양한 AI 도구에서 활용 가능한 형식 제공

부가 목표:

• 유튜브 자막 추출 기능 복원

• 영어 자막 → 한국어 자동 번역 기능 추가

문제 1: Windows에서 한글과 이모지가 깨지는 문제

무슨 일이 있었나?

프로그램을 실행했더니 이런 에러가 났다:

UnicodeEncodeError: 'cp949' 코덱으로 이모지를 표시할 수 없습니다

쉽게 말하면:

• 프로그램이 "🔍 자막 찾는 중..." 같은 메시지를 보여주려고 했다

• 하지만 Windows 명령창은 기본적으로 옛날 한글 방식(CP949)을 사용한다

• 이모지와 최신 한글은 UTF-8이라는 새로운 방식을 써야 한다

• 그래서 명령창이 "이게 뭔지 모르겠어요!" 하고 에러를 낸 것

어떻게 해결했나?

Windows에서 프로그램을 실행할 때마다 "UTF-8 방식으로 글자를 보여줘"라고 설정을 바꿔줬다.

해결 방법:

# Windows인지 확인
if sys.platform == 'win32':
    # 화면에 글자를 보여주는 방식을 UTF-8로 변경
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

무엇을 한 건가?

• Windows에서 실행 중인지 확인

• 그렇다면 명령창의 "글자 표시 방식"을 현대적인 UTF-8로 바꿈

• 이제 한글, 이모지, 외국어 모두 잘 보임

결과

✓ 이모지와 한글이 명령창에서 깨지지 않고 정상적으로 나타남

문제 2: 유튜브 자막 가져오는 라이브러리가 작동 안 함

무슨 일이 있었나?

자막을 가져오려고 했더니 이런 에러가 났다:

'YouTubeTranscriptApi'에 'get_transcript'라는 기능이 없습니다
'YouTubeTranscriptApi'에 'list_transcripts'라는 기능이 없습니다

쉽게 말하면:

• 인터넷에서 찾은 코드 예제가 최신 버전용이었다

• 하지만 내 컴퓨터에 설치된 건 구버전(1.2.3)이었다

• 구버전은 사용법이 달라서 "그런 기능 없어요!" 하고 에러를 냈다

마치 최신 아이폰 설명서를 보고 예전 아이폰을 조작하려니 버튼 위치가 다른 것과 같다.

어떻게 해결했나?

1단계: 실제로 어떤 기능이 있는지 확인

# 이 라이브러리가 가진 기능 목록을 보여줘
print(dir(YouTubeTranscriptApi))
# 결과: fetch, list 두 가지 기능이 있음

2단계: 올바른 사용법 찾기

구버전은 이렇게 사용해야 했다:

# ① 유튜브 자막 도구를 준비
api = YouTubeTranscriptApi()

# ② 이 영상에 어떤 자막들이 있는지 목록 확인
transcript_list = api.list(video_id)

# ③ 한국어 자막 찾기
transcript = transcript_list.find_transcript(['ko'])

# ④ 실제 자막 내용 가져오기
fetched_transcript = transcript.fetch()

3단계: 자막 텍스트 추출 방식 변경

구버전은 자막 데이터를 주는 방식도 달랐다:

# 기존 (신버전): item['text'] - 딕셔너리에서 꺼냄
# 변경 (구버전): snippet.text - 객체에서 꺼냄

# 모든 자막 조각들을 하나로 합치기
full_text = ' '.join([snippet.text for snippet in fetched_transcript.snippets])

결과

✓ 유튜브 영상의 자막을 성공적으로 가져올 수 있게 됨

문제 3: 영어 영상을 한국어로 보고 싶다

무슨 일이 있었나?

영어 영상의 자막을 가져오니 당연히 영어로만 나왔다.

원하는 것:

• 한국어 자막이 있는 영상 → 한국어 자막 그대로 사용

• 영어 자막만 있는 영상 → 한국어로 번역해서 보여주기

어떻게 해결했나?

1단계: 번역 기능이 있는지 확인

# 영어 자막에 어떤 기능들이 있는지 확인
en_transcript = transcript_list.find_transcript(['en'])
print(dir(en_transcript))
# 결과: translate (번역하기) 기능이 있음!

2단계: 단계별로 시도하는 로직 만들기

try:
    # ① 먼저 한국어 자막이 있는지 찾아보기
    transcript = transcript_list.find_transcript(['ko'])
    fetched_transcript = transcript.fetch()
    print("✓ 한국어 자막을 찾았어요!")

except:
    # ② 한국어 자막이 없네? 그럼 영어 자막 가져오기
    en_transcript = transcript_list.find_transcript(['en'])

    # ③ 이 영어 자막이 번역 가능한지 확인
    if en_transcript.is_translatable:
        # ④ 번역 가능하면 한국어로 번역
        ko_transcript = en_transcript.translate('ko')
        fetched_transcript = ko_transcript.fetch()
        print("✓ 영어 자막을 한국어로 번역했어요!")

이게 어떻게 작동하나?

1. 한국어 자막 찾기 → 있으면 사용 (최선)

2. 없으면 영어 자막 가져오기

3. 유튜브 자체 번역 기능으로 한→영 번역 (차선)

4. 그것도 안 되면 영어 원문 (최후)

비유:

• 식당에서 한국어 메뉴판 요청

• 없으면 영어 메뉴판을 번역기로 번역

• 그것도 안 되면 영어 메뉴판 그대로 보기

결과

✓ 영어 영상의 자막을 유튜브 번역 기능으로 한국어로 변환 성공

테스트 결과:

• 원본 영어 자막: 11,446자 (A4 용지 약 6장)

• 한국어 번역 완료

• AI로 30%만 추려낸 요약: 4,935자 (A4 용지 약 2.5장)

배운 점: 맥락 기반 스킬 템플릿 자동생성로직 이해

문제 해결 후, 대화 맥락만을 활용하여 Claude Code가 자동으로 재사용 가능한 스킬 템플릿을 생성하도록 요청했다.

맥락 기반 생성의 핵심 논리

기존 방식 (문서 작성):

문제 해결 → 별도로 문서 작성 → 정리 → 공유

• 시간 소요: 2배 이상 (코딩 + 문서화)

• 누락 위험: 해결 과정의 디테일을 기억해서 다시 작성

• 진입 장벽: 문서 작성 능력 필요

새로운 방식 (맥락 활용):

문제 해결 (대화) → AI가 대화 내용 분석 → 자동 템플릿 생성

• 시간 절약: 추가 작업 없이 자동 생성

• 정확성: 실제 대화 내용을 그대로 활용

• 접근성: 대화만 하면 누구나 가능

맥락에서 템플릿을 만드는 방법 (정리)

1단계: 충분한 맥락 쌓기

• 문제 상황과 에러 메시지, 그리고 시도한 해결 방법과 결과를 대화로 남김 (별도로 기록할 필요는 X)

• 최종 작동하는 코드까지 완성

2단계: 템플릿 생성 요청

"지금까지의 대화 맥락을 바탕으로
재사용 가능한 스킬 템플릿을 만들어줘"

3단계: AI의 자동 추출

• 대화에서 문제 상황 → 문제 정의로 변환

• 해결 과정 → 구현 가이드로 변환

• 에러와 해결책 → 에러 처리 가이드로 변환

• 테스트 과정 → 사용 예제로 변환

왜 이것이 가능한가?

• AI는 전체 대화 이력을 기억하고 있음

• 문제-해결의 흐름을 이미 이해하고 있음

• 표준 포맷(skill.md, rules, examples)을 알고 있음

• 단지 "정리해달라"고 요청하면 자동으로 구조화

(참고) 생성된 스킬 구조

.skills/youtube-transcript/
├── skill.md                          # 스킬 정의
├── README.md                         # 전체 문서
├── INSTALL.md                        # 설치 가이드
├── youtube_summarizer.py             # 실행 코드
├── rules/
│   ├── rule-implementation.md        # 구현 가이드
│   ├── rule-error-handling.md        # 에러 처리
│   └── rule-output-format.md         # 출력 형식
└── examples/
    └── example-usage.md              # 사용 예제

생성된 스킬의 특징

1. 맥락 기반 자동 생성:

   • 대화 중 해결한 모든 에러(인코딩, API 사용법)가 자동으로 문서화됨

   • 코드 수정 이력이 구현 가이드로 변환됨

   • 테스트 과정이 사용 예제로 정리됨

2. 표준화된 구조:

   • Claude Code, Cursor, Windsurf 등 다양한 AI 도구에서 사용 가능

   • skill.md, rules, examples 등 표준 포맷 준수

3. 즉시 재사용 가능:

   • 복사만 하면 다른 프로젝트에서 바로 작동

   • 별도의 수정이나 설정 없이 완전한 패키지로 제공

사용 방법

"이 유튜브 영상의 자막을 추출하고 한글로 번역해줘:
https://www.youtube.com/watch?v=GFM8cK4-BoM"

AI 도구가 자동으로 스킬을 인식하고 실행한다.

교훈 및 인사이트

1. 맥락 기반 자동화의 가능성

대화 맥락만으로도 AI가 재사용 가능한 템플릿을 생성할 수 있다는 것을 확인했다. 이는:

• 별도의 문서 작성 없이도 지식 자산화 가능

• 문제 해결 과정 자체가 곧 문서가 됨

• 대화형 개발의 새로운 활용 방안 제시

2. 대화 이력의 가치

단순히 문제를 해결하고 끝나는 것이 아니라:

• 해결 과정이 에러 처리 가이드가 됨

• 시행착오가 베스트 프랙티스로 변환됨

• 테스트 과정이 사용 예제가 됨

3. AI 도구 간 호환성

표준화된 스킬 포맷을 사용하면:

• Claude Code, Cursor, Windsurf 등 다양한 도구에서 활용 가능

• 한 번 만들면 여러 환경에서 재사용

• 팀 전체가 동일한 지식 베이스 공유 가능

4. 재사용 가능한 템플릿을 만드는 조건

맥락에서 좋은 템플릿이 나오려면 대화 중에 이런 것들이 있어야 한다:

필수 요소:

• 실제로 겪은 에러: "이런 에러가 났어요" + "이렇게 해결했어요"

  • 예: Windows에서 한글 깨짐, 라이브러리 버전 차이

• 작동하는 코드: 중간 과정이 아닌 최종적으로 돌아가는 완성 코드

• 테스트 결과: "실제로 해봤더니 이렇게 됐어요"

  • 예: 11,446자 영어 자막 → 한국어 번역 성공

• 단계별 흐름: 처음 → 에러 → 시도 → 실패 → 다시 시도 → 성공

왜 이게 중요한가?

• 에러 없이 바로 성공한 코드 → 다른 사람도 같은 에러를 겪을 수 있음

• 시행착오 과정 → 미리 문제를 예방하는 가이드가 됨

• 테스트 결과 → "이게 진짜 작동한다"는 증거

비유: 요리 레시피를 만들 때

• ❌ "재료를 섞어서 구우면 됨" (너무 간단)

• ✓ "이렇게 했더니 타서 실패 → 온도를 낮췄더니 성공" (실전 팁)

시사점

이 접근 방식은 단순히 "문제 해결"을 넘어:

• 대화형 개발의 새로운 패러다임: 코딩 과정 자체가 지식 자산화

• AI 시대의 문서화 방법: 별도 문서 작성 없이 대화 맥락 활용

• 팀 협업의 새로운 형태: 개인의 문제 해결 경험을 팀 전체가 공유

결국 AI와 대화하면서 문제를 해결하는 과정 자체가, 다른 사람들도 활용할 수 있는 재사용 가능한 자산이 될 수 있음을 증명했다.