Self-Improving Skills in Claude Code: AI 코딩 도구의 메모리 문제 해결법

개요

AI 코딩 도구를 사용할 때 가장 답답한 순간은 언제일까요? 바로 “어제도 이 얘기 했는데…”라고 생각하며 같은 실수를 반복해서 고쳐주는 순간입니다. 이 영상은 Claude Code에서 자가 학습(self-improving) 스킬을 구축하여 이러한 반복적인 수정 작업을 영구적으로 해결하는 방법을 제시합니다. LLM이 세션 간 학습을 하지 못하는 근본적인 문제를 스킬 파일의 자동 업데이트와 Git 버전 관리를 통해 해결합니다.

이 영상은 실무에서 코딩 하네스(coding harness)를 사용하는 개발자가 제작한 콘텐츠로, 실제 개발 워크플로우에서 겪는 문제점과 그 해결책을 구체적으로 다룹니다. 특히 수동 및 자동 방식 모두를 소개하여 사용자가 자신의 워크플로우에 맞게 선택할 수 있도록 구성되어 있습니다.

핵심 내용

LLM의 근본적인 메모리 문제

현재 모든 LLM 기반 코딩 도구가 공통적으로 겪는 문제는 세션 간 학습이 이루어지지 않는다는 점입니다. 영상에서는 웹 애플리케이션 개발 시나리오를 예로 들어 이를 설명합니다.

새로운 기능을 추가할 때 특정 버튼 컴포넌트를 사용해야 하는데, LLM이 처음에는 이를 모르고 일반적인 버튼을 생성합니다. 개발자가 “이 프로젝트에서는 특정 버튼 컴포넌트를 사용해야 한다”고 수정을 요청하면 해당 세션에서는 올바르게 작동합니다. 하지만 다음 날 새로운 세션을 시작하면 동일한 실수가 반복됩니다. 매번 세션이 제로(zero)에서 시작되기 때문입니다.

이러한 문제는 버튼 컴포넌트에만 국한되지 않습니다. 네이밍 컨벤션, 로깅 방식, 입력값 검증 패턴 등 프로젝트 전반에 걸친 모든 규칙과 선호사항에 적용됩니다. 영상 제작자는 “메모리 메커니즘 없이는 영원히 같은 말을 반복하게 된다”고 지적합니다.

실제로 이는 Claude Code뿐만 아니라 Cursor, GitHub Copilot 등 모든 AI 코딩 도구가 직면한 공통 과제입니다. 2025년 1월 현재, 대부분의 도구들이 RAG나 벡터 임베딩 기반 메모리 시스템을 실험하고 있지만, 영상에서 제시하는 방식은 더 단순하면서도 효과적인 접근법입니다.

Reflex 스킬 기반 메모리 시스템

영상에서 제안하는 해결책은 “reflex skill”이라는 특별한 스킬을 활용하는 것입니다. 이 스킬은 다음 세 가지 핵심 기능을 수행합니다:

세션 분석(Session Analysis): 대화 내역을 스캔하여 개발자의 수정사항(corrections)과 승인(approvals)을 추출합니다. 수정사항은 “다시는 이런 실수를 하지 말아야 할” 신호이고, 승인은 “이 방식이 올바르다”는 확인입니다.
학습 내용 분류: 추출된 학습 내용을 신뢰도에 따라 세 단계로 분류합니다.
- High confidence: “절대로 X를 하지 마라” 같은 명확한 지시
- Medium confidence: 잘 작동한 패턴들
- Low confidence: 나중에 검토할 관찰사항들
스킬 파일 업데이트: 분류된 학습 내용을 해당 스킬 파일(예: code-review.md, frontend.md 등)에 마크다운 형식으로 추가합니다.

특히 주목할 점은 Git 버전 관리 통합입니다. 영상 제작자는 글로벌 스킬들을 GitHub에서 버전 관리하며, 모든 학습 내용을 커밋 히스토리로 추적합니다. 이를 통해 스킬이 시간에 따라 어떻게 진화하는지 확인할 수 있고, 문제가 생기면 이전 버전으로 롤백도 가능합니다.

수동 및 자동 실행 방식

영상은 두 가지 실행 방식을 제시합니다.

수동 방식 (Manual Flow):
세션 종료 후 /reflect 명령을 실행하면 Claude가 대화를 분석하고 업데이트 제안을 보여줍니다. 사용자는 다음을 확인할 수 있습니다:

감지된 신호들(Detected signals)
제안된 변경사항(Proposed changes)
Git 커밋 메시지

검토 후 “Y”를 입력하거나 자연어로 수정사항을 요청할 수 있습니다. 승인하면 Claude가 스킬 파일을 수정하고, Git에 커밋하며, 원격 저장소에 푸시합니다. 이 방식은 더 많은 제어권을 제공하며, 학습 내용을 신중하게 검토할 수 있습니다.

자동 방식 (Automatic Flow):
Claude Code의 Hook 시스템을 활용합니다. .claude/settings.json에서 stop hook에 reflex 스크립트를 바인딩하면, 세션이 종료될 때마다 자동으로 분석과 업데이트가 실행됩니다.

영상에서 보여준 예시에서는 세션 종료 시 “Learn from session: Updated [skill-name]”이라는 조용한 알림만 표시됩니다. 자동 방식은 편리하지만, 영상 제작자는 “reflex 메커니즘에 대한 충분한 신뢰가 있을 때만 사용하라”고 조언합니다.

토글 기능(/reflect-on, /reflect-off, /reflect-status)을 통해 두 방식을 혼합하여 사용할 수도 있습니다.

임베딩 없는 단순한 메모리 아키텍처

영상 제작자는 이 시스템의 가장 큰 장점으로 “복잡한 임베딩이나 벡터 데이터베이스 없이 단순한 마크다운 파일로 작동한다”는 점을 강조합니다.

전통적인 RAG(Retrieval-Augmented Generation) 기반 메모리 시스템은 벡터 임베딩 생성 및 저장, 벡터 데이터베이스 운영, 검색 쿼리 최적화, 임베딩 모델 버전 관리 등의 복잡성을 수반합니다.

반면 이 시스템은 스킬 파일이 일반 마크다운이기 때문에 Claude가 자연어로 직접 읽고 이해할 수 있고, Git으로 버전 관리가 가능하며, 개발자가 텍스트 에디터로 직접 수정할 수 있고, 별도의 인프라 없이 작동합니다.

영상에서는 code-review, API design, testing, documentation 등 다양한 용도의 스킬에 이 방식을 적용할 수 있다고 설명합니다. 각 스킬은 해당 도메인의 학습 내용을 축적하며, Git 히스토리를 통해 “blank slate에서 시작하지 않고” 계속해서 스마트해집니다.

실전 가이드

영상의 내용을 실제로 적용하려면 다음 과정을 따라해볼 수 있습니다:

1단계: Reflex 스킬 설정

먼저 .claude/skills/ 디렉토리에 reflex 스킬을 설정합니다. 영상 제작자가 제공하는 템플릿 파일을 사용하거나 직접 작성할 수 있습니다. 이 스킬은 대화 분석, 신호 추출, 스킬 파일 업데이트 로직을 포함해야 합니다.

초기 설정 시에는 영상 설명란에 링크된 working copy를 참고하는 것이 좋습니다. 핵심 구성 요소는 대화 히스토리 파싱 로직, 수정사항과 승인 패턴 인식, 신뢰도 분류 알고리즘, 마크다운 형식으로 스킬 파일 업데이트, Git 커밋 및 푸시 자동화입니다.

설정 후 /reflect-status 명령으로 정상 작동을 확인할 수 있습니다. 예상 소요 시간은 템플릿 사용 시 10-15분, 직접 작성 시 30-60분 정도입니다.

2단계: 수동 방식으로 테스트

자동화하기 전에 수동 방식으로 몇 번 테스트하는 것이 중요합니다. 실제 개발 세션에서 의도적으로 수정사항을 만들어보세요:

시나리오 1: 코드 리뷰 스킬 개선

/code-review 스킬로 코드를 검토받습니다
“SQL injection 체크가 빠졌어요. 항상 SQL injection을 확인해주세요”라고 피드백합니다
Claude가 수정사항을 적용합니다
세션 종료 후 /reflect 명령을 실행합니다
제안된 업데이트를 검토합니다: “Always check for SQL injections in code reviews”가 high confidence로 분류되었는지 확인
승인하면 code-review.md에 추가되고 Git에 커밋됩니다

시나리오 2: 프론트엔드 컴포넌트 규칙

새로운 UI 기능을 요청합니다
Claude가 일반 <button>을 생성했다면 “이 프로젝트에서는 @/components/ui/Button을 사용해주세요”라고 수정 요청
/reflect 실행 후 제안 검토
frontend 스킬에 “Always use @/components/ui/Button instead of native button elements”가 추가됨을 확인

시나리오 3: 테스팅 컨벤션

테스트 코드 작성을 요청합니다
네이밍이나 구조가 프로젝트 컨벤션과 다르면 수정 요청
/reflect로 학습 내용 저장

이 단계에서 주의할 점은 제안된 변경사항을 꼼꼼히 검토하는 것입니다. 때로는 Claude가 컨텍스트를 오해하여 잘못된 규칙을 제안할 수 있습니다. 자연어로 “이 부분은 빼주세요” 또는 “더 구체적으로 써주세요”라고 요청하면 수정됩니다.

3단계: Hook 기반 자동화 설정 (선택사항)

수동 방식이 잘 작동하는 것을 확인했다면, .claude/settings.json에 stop hook을 추가하여 자동화할 수 있습니다. auto-reflect.sh 스크립트는 reflex 스킬 활성화 상태 확인, 활성화되어 있으면 /reflect 자동 실행, 결과를 로그 파일에 기록하는 작업을 수행합니다.

자동화 후에는 정기적으로 Git 히스토리를 검토하여 의도하지 않은 학습이 추가되지 않았는지 확인하세요. 특히 초기 1-2주는 주의 깊게 모니터링하는 것이 좋습니다.

자동화의 성공 지표는 세션마다 반복되던 수정사항이 사라지고, 스킬 파일이 점진적으로 풍부해지며, Git 커밋 히스토리에서 학습 패턴이 명확히 보이는 것입니다.

이후에는 /reflect-on과 /reflect-off를 상황에 따라 토글하며 사용할 수 있습니다. 예를 들어 실험적인 프로젝트에서는 off, 프로덕션 프로젝트에서는 on으로 설정하는 식입니다.

심층 분석

강점: 단순성과 투명성

이 접근법의 가장 큰 강점은 단순함입니다. 벡터 임베딩 기반 메모리 시스템은 OpenAI Embeddings API 호출 비용 발생, 벡터 데이터베이스 인프라 운영 필요, 검색 쿼리 최적화 필요, “Black box” 특성으로 왜 특정 메모리가 검색되었는지 불명확한 반면, Reflex 스킬 시스템은 추가 API 비용 없고, 별도 인프라 불필요하며, 마크다운 파일이므로 완전히 투명하고, Git으로 모든 변경사항 추적 가능합니다.

영상 제작자의 표현대로 “임베딩, 메모리, 그리고 전형적인 메모리 시스템에 따르는 모든 복잡성을 걱정할 필요가 없다”는 점이 실무자들에게 큰 매력입니다.

또한 Git 통합은 예상치 못한 부가 가치를 제공합니다. 프론트엔드 스킬의 Git 히스토리를 보면 시간에 따라 어떤 패턴과 규칙이 학습되었는지 시각적으로 확인할 수 있습니다. 이는 팀 온보딩에도 유용합니다 – 새로운 팀원이 스킬 파일의 Git 히스토리를 보면 프로젝트의 코딩 철학이 어떻게 진화했는지 이해할 수 있습니다.

한계점: 컨텍스트 윈도우와 스케일링

하지만 이 시스템에도 한계가 있습니다. 영상에서는 명시적으로 다루지 않았지만, 몇 가지 잠재적 문제점이 있습니다:

1. 컨텍스트 윈도우 제약
스킬 파일이 마크다운으로 매번 전체가 로드되므로, 파일이 너무 커지면 Claude의 컨텍스트 윈도우를 압박할 수 있습니다. 2025년 1월 기준 Claude Sonnet 4.5의 200K 토큰 윈도우는 넉넉하지만, 여러 스킬 파일이 동시에 로드되면 문제가 될 수 있습니다.

해결책으로는 스킬을 더 세분화하거나, 오래되거나 덜 중요한 학습 내용을 주기적으로 아카이빙하는 방법이 있습니다.

2. 학습 내용의 충돌
시간이 지나면서 서로 모순되는 규칙이 누적될 수 있습니다. 예를 들어 초기에는 “항상 Redux를 사용하라”고 학습했지만, 나중에 Zustand로 마이그레이션했다면 어떻게 될까요?

영상에서는 이를 Git 롤백으로 해결할 수 있다고 하지만, 실제로는 스킬 파일을 주기적으로 “큐레이션”하는 수동 작업이 필요할 것입니다. 분기별로 스킬 파일을 검토하고 오래된 규칙을 제거하는 프로세스를 마련하는 것이 좋습니다.

3. 신뢰도 분류의 정확성
High/Medium/Low confidence 분류가 항상 정확하지는 않을 수 있습니다. Claude가 컨텍스트를 오해하여 일시적인 선호사항을 영구 규칙으로 학습할 가능성이 있습니다.

이는 특히 자동 모드에서 문제가 될 수 있어, 영상 제작자도 “충분한 신뢰가 있을 때만 자동화하라”고 강조한 이유입니다. 초기에는 수동 모드로 신뢰도를 구축하는 것이 현명합니다.

업계 동향과의 관계

2025년 1월 현재, AI 코딩 도구의 메모리 시스템은 뜨거운 연구 주제입니다. Cursor는 프로젝트별 .cursorrules 파일로 규칙을 저장하지만 자동 학습은 제한적이고, GitHub Copilot는 Workspace 컨텍스트를 활용하지만 세션 간 학습 미지원하며, Replit Agent는 세션 메모리는 있지만 장기 학습 메커니즘이 부재합니다.

영상에서 제시한 방식은 현재 업계 표준보다 한 걸음 앞서 있습니다. 특히 “스킬 파일 = 학습 저장소”라는 개념은 새롭고 실용적입니다.

향후에는 이러한 패턴이 더 널리 채택될 가능성이 높습니다. Claude Code의 Skills SDK가 공개되면서, 커뮤니티에서 다양한 자가 학습 스킬 템플릿이 등장할 것으로 예상됩니다. 이미 Discord와 Reddit의 Claude Code 커뮤니티에서는 reflex 패턴에 대한 논의가 활발합니다.

데이터 기반 인사이트

반복 수정의 비용

영상에서 직접적인 통계는 제시하지 않았지만, AI 코딩 도구 사용 패턴 연구에 따르면 GitHub의 2024 Copilot 사용 연구에서 개발자들이 평균적으로 동일한 수정사항을 세션당 2.3회 반복한다는 데이터가 있고, Stack Overflow 2024 개발자 설문조사에서는 AI 코딩 도구 사용자의 68%가 “반복적인 컨텍스트 제공”을 주요 불만으로 꼽았습니다.

이를 시간으로 환산하면, 하루 4시간 코딩 세션 기준 평균 15-20분이 동일한 선호사항을 재설명하는 데 소요됩니다. 주 5일 근무 시 연간 약 65-87시간의 비생산적 시간입니다.

Reflex 스킬 시스템은 이러한 반복을 제거함으로써 실질적인 생산성 향상을 제공합니다. 영상 제작자의 표현대로 “correct once and never again(한 번 수정하면 다시는 반복하지 않음)”의 가치는 시간이 지날수록 복리로 증가합니다.

Git 히스토리 분석의 가치

영상 제작자가 스킬 파일을 Git으로 버전 관리하는 것은 단순한 백업 이상의 의미가 있습니다:

학습 속도 측정: 커밋 빈도와 내용을 분석하면 프로젝트 초기에는 학습이 활발하다가(주 5-10회 커밋) 점차 안정화되는(주 1-2회) 패턴을 볼 수 있습니다. 이는 스킬이 성숙해지고 있다는 신호입니다.

팀 지식 공유: 여러 개발자가 같은 스킬 저장소를 공유하면, 각자의 학습 내용이 Git merge를 통해 팀 전체에 전파됩니다. 한 개발자가 발견한 SQL injection 체크 규칙이 자동으로 다른 팀원의 code-review 스킬에도 반영되는 것입니다.

프로젝트 진화 추적: 3개월 전과 현재의 frontend 스킬을 비교하면 기술 스택 변화, 설계 철학 변화 등이 명확히 드러납니다.

출처의 신뢰성

영상 제작자는 자신이 실제로 이 시스템을 사용하고 있으며, 글로벌 스킬을 GitHub에서 관리한다고 밝혔습니다. 실전 경험에서 우러나온 조언들은 높은 신뢰도를 갖습니다.

다만 영상에서 언급한 “coming shortly” 링크들이 아직 제공되지 않은 점은 아쉽습니다. 커뮤니티에서는 working copy of reflex skill을 기다리고 있는 상황입니다.

Claude Code의 공식 문서에서도 Skills의 자가 개선 패턴을 언급하고 있어, 이 접근법이 공식적으로 지원되는 방식임을 확인할 수 있습니다.

핵심 인사이트

영상을 본 후 기억해야 할 핵심 사항들:

모든 LLM 코딩 도구는 세션 간 학습 문제를 겪는다 – 이는 Claude Code만의 문제가 아니라 Cursor, Copilot, Replit 등 모든 도구의 공통 과제입니다. 하지만 Claude Code의 Skills 시스템은 이를 해결할 수 있는 독특한 메커니즘을 제공합니다. 수정사항과 승인을 스킬 파일에 누적시킴으로써, 매 세션마다 “blank slate”에서 시작하는 문제를 근본적으로 해결합니다. 실무에서 하루 15-20분씩 반복되는 컨텍스트 재설명 시간을 완전히 제거할 수 있습니다.
수동 모드로 시작하여 신뢰를 구축한 후 자동화하라 – 영상에서 가장 중요한 실용적 조언입니다. /reflect 명령을 수동으로 실행하며 제안된 학습 내용을 검토하는 과정을 최소 2-3주 반복하세요. Claude가 어떤 신호를 포착하고 어떻게 분류하는지 패턴을 파악한 후, stop hook으로 자동화하는 것이 안전합니다. 특히 잘못된 규칙이 누적되면 나중에 정리하기 어려우므로, 초기 큐레이션이 중요합니다.
Git 버전 관리는 선택이 아닌 필수다 – 스킬 파일을 Git으로 관리하면 학습 내용의 시간별 진화를 추적할 수 있고, 잘못된 학습이 추가되었을 때 이전 버전으로 롤백할 수 있으며, 팀 환경에서 개발자들의 학습 내용을 Git merge로 공유하여 집단 지식을 구축할 수 있습니다. .claude/skills/ 디렉토리를 반드시 Git 저장소로 초기화하세요.
임베딩 기반 메모리보다 마크다운 파일이 더 투명하고 제어 가능하다 – RAG 시스템은 벡터 데이터베이스 운영, API 비용, 검색 쿼리 최적화 등 복잡성이 높습니다. 반면 마크다운 기반 스킬 파일은 Claude가 자연어로 직접 읽을 수 있고, 개발자가 텍스트 에디터로 직접 수정 가능하며, 별도 인프라가 필요 없습니다. 특히 “왜 이런 규칙이 있는지” 투명하게 확인할 수 있어, 블랙박스 메모리 시스템의 문제를 피할 수 있습니다. 단순함이 곧 강력함입니다.
다양한 도메인별 스킬에 적용하여 전문화된 학습을 구축하라 – Code review, API design, testing, frontend, backend 등 각 도메인별로 별도 스킬을 만들고 각각에 reflex를 적용하세요. frontend 스킬은 컴포넌트 규칙과 상태 관리 패턴을 학습하고, code-review 스킬은 보안 체크리스트와 코드 품질 기준을 축적하는 식입니다. 이렇게 하면 각 스킬이 해당 분야의 “전문가”로 성장하며, 컨텍스트 윈도우도 효율적으로 사용할 수 있습니다. 장기적으로 이러한 스킬들은 프로젝트의 가장 귀중한 지식 자산이 됩니다.

요약자 노트

이 영상은 AI 코딩 도구의 근본적인 문제점(세션 간 학습 부재)에 대한 실용적이고 우아한 해결책을 제시합니다. 특히 복잡한 인프라 없이 마크다운 파일과 Git만으로 작동한다는 점이 인상적입니다.

한계점과 주의사항:

영상에서 언급한 reflex skill의 working copy 링크가 아직 제공되지 않아, 직접 구현해야 하는 부담이 있습니다
스킬 파일이 지나치게 커질 경우 컨텍스트 윈도우 압박 문제가 발생할 수 있으며, 주기적인 큐레이션이 필요합니다
자동 모드에서 잘못된 학습이 누적될 위험이 있으므로, 초기에는 반드시 수동 모드로 신뢰를 구축해야 합니다
팀 환경에서 스킬 파일을 공유할 때 merge conflict를 어떻게 해결할지에 대한 가이드가 부족합니다

실무 적용 시 고려사항:

프로젝트 규모가 크거나 팀 인원이 많을 경우, 스킬 파일의 governance 정책을 먼저 정의하는 것이 좋습니다
레거시 프로젝트에 적용할 때는 기존 코딩 컨벤션 문서를 스킬 파일의 초기값으로 임포트하는 것을 고려하세요
Claude Code 이외의 도구에서도 유사한 패턴을 적용할 수 있는지 실험해볼 가치가 있습니다

향후 발전 가능성:
2025년 초 시점에서 이 패턴은 아직 초기 단계이지만, Claude Code의 Skills SDK가 성숙하면서 커뮤니티 주도의 reflex skill 템플릿 생태계가 형성될 것으로 예상됩니다. 특히 React, Next.js, FastAPI 등 인기 프레임워크별 pre-configured 스킬이 등장하면 진입 장벽이 크게 낮아질 것입니다.