[AI] Claude Code 자가 개선 에이전트를 VS Code에서 구축하는 완전 가이드

목차

• Claude Code 자가 개선 에이전트를 VS Code에서 구축하는 방법
• Claude Code 자가 개선 에이전트가 뭐길래?
• 쉽게 말해서 이런 겁니다
• 일반 Claude Code vs 자가 개선 에이전트 비교
• VS Code 환경 세팅: 사전 준비 단계
• 필요한 것들
• 1단계: Claude Code 설치
• 2단계: API 키 환경 변수 설정
• 핵심 구현: Claude Code 자가 개선 에이전트 만들기
• 3단계: 프로젝트 구조 생성
• 4단계: 스킬 매니저 구현하기
• 5단계: 자가 개선 에이전트 메인 로직 작성
• 6단계: CLAUDE.md로 프로젝트 컨텍스트 설정
• 실전 삽질 모음: 이런 문제 조심하세요
• 문제 1: 스킬 파일이 너무 많아지면 컨텍스트 윈도우 초과
• 문제 2: 스킬 저장 형식이 일관성 없음
• 문제 3: VS Code에서 Claude Code 터미널 권한 문제
• 문제 4: .claude 폴더가 Git에 올라가는 문제
• 결과 확인: 에이전트가 정말 자가 개선되나요?
• 실제 스킬 파일 예시 (에이전트가 스스로 생성)
• 성능 개선 수치 (제 홈랩 기준)
• 한 단계 더: 멀티 에이전트 구조로 확장하기
• 에이전트 역할 분리 예시
• 정리: Claude Code 자가 개선 에이전트 핵심 요약
• 자주 묻는 질문 (FAQ)

Claude Code 자가 개선 에이전트를 VS Code에서 구축하는 방법

솔직히 말씀드리면, 처음에 "자가 개선 에이전트"라는 말을 들었을 때 저도 SF 영화 얘기인 줄 알았거든요. 근데 Claude Code를 VS Code에서 직접 써보면서 생각이 완전히 바뀌었습니다. Claude Code 자가 개선 에이전트는 AI가 자기 자신의 동작 방식을 분석하고, 더 나은 응답을 위한 스킬(Skill)을 스스로 작성·저장·재활용하는 구조를 말해요.

13년 동안 인프라 엔지니어로 일하면서 수많은 자동화 도구를 써봤는데, 이건 좀 다르더라고요. 단순히 "명령 실행"이 아니라, 에이전트가 반복 패턴을 학습해서 다음번엔 더 빠르고 정확하게 처리하는 거거든요. 오늘은 제가 직접 홈랩에서 구축하면서 겪은 삽질과 함께 VS Code에서 Claude Code 자가 개선 에이전트를 만드는 방법을 공유해 드릴게요.

▲ Claude Code 자가 개선 에이전트의 전체 동작 흐름 — 스킬 저장소와 피드백 루프가 핵심입니다.

Claude Code 자가 개선 에이전트가 뭐길래?

쉽게 말해서 이런 겁니다

일반적인 AI 코딩 도구는 매번 처음부터 생각해요. 그런데 자가 개선 에이전트는 달라요. 쉽게 말해 "내가 지난번에 이 문제를 어떻게 풀었는지 기억하고, 다음번엔 그걸 바탕으로 더 잘 풀겠다"는 구조입니다. 마치 당신이 비슷한 작업을 반복할 때 자신의 경험을 활용하는 것처럼요.

구체적으로 세 가지 핵심 요소로 구성돼요:

• 스킬 저장소 (Skill Repository): 에이전트가 성공적으로 처리한 작업 패턴을 마크다운 파일로 저장
• 자기 평가 루프 (Self-Evaluation Loop): 작업 결과를 스스로 채점하고 개선 포인트를 찾는 과정
• 컨텍스트 주입 (Context Injection): 다음 작업 시 관련 스킬을 자동으로 불러와 프롬프트에 포함

처음엔 이게 뭔가 싶었는데, 막상 구현해보니 "아, 이게 그냥 잘 설계된 파일 시스템 + 프롬프트 엔지니어링이구나" 싶더라고요. 복잡해 보이지만 핵심 로직은 생각보다 훨씬 단순합니다.

일반 Claude Code vs 자가 개선 에이전트 비교

항목	일반 Claude Code	자가 개선 에이전트
기억 지속성	세션 내에서만	파일 기반으로 영구 저장
반복 작업 효율	매번 동일한 시간 소요	스킬 재활용으로 점점 빨라짐
오류 처리	즉흥적 대응	과거 실패 패턴 회피
커스터마이징	매 대화마다 설명 필요	프로젝트별 스킬 자동 적용
팀 공유	어려움	스킬 파일 공유로 즉시 가능

VS Code 환경 세팅: 사전 준비 단계

본격적으로 들어가기 전에 환경 세팅을 먼저 해야 해요. 저도 이 부분에서 삽질을 좀 했습니다. 특히 API 키 설정 순서를 잘못 잡아서 에러 잡느라 시간을 꽤 썼거든요.

필요한 것들

• VS Code 최신 버전 (1.85 이상 권장)
• Node.js 18 이상
• Anthropic API 키 (console.anthropic.com에서 발급)
• Claude Code CLI 또는 VS Code 확장 프로그램

1단계: Claude Code 설치

# Claude Code CLI 전역 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# VS Code 확장 프로그램도 함께 설치 (선택사항이지만 강력 추천)
# VS Code 마켓플레이스에서 "Claude" 검색

2단계: API 키 환경 변수 설정

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-여기에_키_입력"

# 영구 적용 (zsh 기준)
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에_키_입력"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-여기에_키_입력"

⚠️ 주의: API 키를 절대 코드에 직접 하드코딩하지 마세요. .env 파일을 쓰더라도 반드시 .gitignore에 추가해야 합니다. 이거 깜빡하고 GitHub에 올렸다가 식은땀 흘렸던 기억이 있어요...

핵심 구현: Claude Code 자가 개선 에이전트 만들기

이제 진짜 핵심입니다. 자가 개선 에이전트의 구조를 직접 코드로 만들어볼 거예요. 제가 실제로 홈랩 프로젝트에서 사용하는 구조를 기반으로 설명드릴게요.

▲ VS Code에서 구성한 자가 개선 에이전트의 프로젝트 폴더 구조 — .claude 디렉토리가 핵심입니다.

3단계: 프로젝트 구조 생성

mkdir my-ai-agent && cd my-ai-agent

# 스킬 저장소 디렉토리 구조 생성
mkdir -p .claude/skills
mkdir -p .claude/memory
mkdir -p .claude/logs

# 프로젝트 초기화
npm init -y
npm install @anthropic-ai/sdk dotenv fs-extra

폴더 구조가 이렇게 됩니다:

my-ai-agent/
├── .claude/
│   ├── skills/          # 학습된 스킬 파일 저장
│   │   ├── code-review.md
│   │   ├── refactoring.md
│   │   └── debugging.md
│   ├── memory/          # 프로젝트별 컨텍스트
│   │   └── project-context.md
│   └── logs/            # 작업 로그 및 평가 결과
├── agent.js             # 메인 에이전트 로직
├── skill-manager.js     # 스킬 저장/로드 관리
└── .env

4단계: 스킬 매니저 구현하기

스킬 매니저는 자가 개선 에이전트의 핵심 부품이에요. 스킬을 저장하고, 관련 스킬을 검색해서 불러오는 역할을 합니다. 이 부분이 잘 작동해야 나중에 컨텍스트 주입이 제대로 됩니다.

// skill-manager.js
const fs = require('fs-extra');
const path = require('path');

class SkillManager {
  constructor(skillsDir = '.claude/skills') {
    this.skillsDir = skillsDir;
    fs.ensureDirSync(skillsDir);
  }

  // 스킬 저장 - 에이전트가 성공한 패턴을 기록
  async saveSkill(skillName, content, metadata = {}) {
    const skillPath = path.join(this.skillsDir, `${skillName}.md`);
    const timestamp = new Date().toISOString();
    
    const skillContent = `---
name: ${skillName}
created: ${timestamp}
updated: ${timestamp}
use_count: ${metadata.useCount || 0}
success_rate: ${metadata.successRate || 100}
tags: ${JSON.stringify(metadata.tags || [])}
---

${content}`;

    await fs.writeFile(skillPath, skillContent, 'utf-8');
    console.log(`✅ 스킬 저장 완료: ${skillName}`);
    return skillPath;
  }

  // 관련 스킬 로드 - 키워드 기반으로 관련 스킬 검색
  async loadRelevantSkills(keywords) {
    const skills = [];
    
    try {
      const files = await fs.readdir(this.skillsDir);
      
      for (const file of files) {
        if (!file.endsWith('.md')) continue;
        
        const content = await fs.readFile(
          path.join(this.skillsDir, file), 
          'utf-8'
        );
        
        // 키워드 매칭으로 관련 스킬 필터링
        const isRelevant = keywords.some(kw => 
          content.toLowerCase().includes(kw.toLowerCase())
        );
        
        if (isRelevant) {
          skills.push({
            name: file.replace('.md', ''),
            content: content
          });
        }
      }
    } catch (err) {
      console.log('스킬 로드 중 오류:', err.message);
    }
    
    return skills;
  }

  // 스킬 사용 횟수 업데이트
  async updateSkillMetrics(skillName, success = true) {
    const skillPath = path.join(this.skillsDir, `${skillName}.md`);
    
    if (await fs.pathExists(skillPath)) {
      let content = await fs.readFile(skillPath, 'utf-8');
      
      // use_count 업데이트
      content = content.replace(
        /use_count: (\d+)/,
        (match, count) => `use_count: ${parseInt(count) + 1}`
      );
      
      await fs.writeFile(skillPath, content, 'utf-8');
    }
  }
}

module.exports = SkillManager;

5단계: 자가 개선 에이전트 메인 로직 작성

// agent.js
require('dotenv').config();
const Anthropic = require('@anthropic-ai/sdk');
const SkillManager = require('./skill-manager');
const fs = require('fs-extra');

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const skillManager = new SkillManager();

// 자가 개선 에이전트 핵심 함수
async function runSelfImprovingAgent(userTask) {
  console.log('🤖 자가 개선 에이전트 시작...');
  
  // 1단계: 작업에서 키워드 추출
  const keywords = extractKeywords(userTask);
  
  // 2단계: 관련 스킬 로드 (컨텍스트 주입)
  const relevantSkills = await skillManager.loadRelevantSkills(keywords);
  
  let skillContext = '';
  if (relevantSkills.length > 0) {
    console.log(`💡 관련 스킬 ${relevantSkills.length}개 발견, 컨텍스트에 주입 중...`);
    skillContext = `\n\n## 참고할 수 있는 이전 학습 스킬:\n` +
      relevantSkills.map(s => `### ${s.name}\n${s.content}`).join('\n\n');
  }
  
  // 3단계: 작업 실행
  const systemPrompt = `당신은 자가 개선 AI 에이전트입니다. 
작업을 완료한 후, 반드시 다음 형식으로 자기 평가를 포함하세요:

[SKILL_SAVE]
스킬명: <영문_스킬명>
설명: <이 작업에서 배운 패턴이나 접근법>
태그: <관련_태그1, 태그2>
[/SKILL_SAVE]

[SELF_EVALUATION]
성공 여부: <성공/부분성공/실패>
개선 포인트: <다음번에 더 잘 할 수 있는 부분>
[/SELF_EVALUATION]${skillContext}`;

  const response = await client.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 4096,
    system: systemPrompt,
    messages: [{
      role: 'user',
      content: userTask
    }]
  });
  
  const responseText = response.content[0].text;
  
  // 4단계: 응답에서 스킬 추출 및 저장 (자가 개선 핵심!)
  await extractAndSaveSkills(responseText);
  
  // 5단계: 작업 로그 저장
  await saveTaskLog(userTask, responseText);
  
  return responseText;
}

// 응답에서 스킬 블록 추출 및 저장
async function extractAndSaveSkills(responseText) {
  const skillRegex = /\[SKILL_SAVE\]([\s\S]*?)\[\/SKILL_SAVE\]/g;
  let match;
  
  while ((match = skillRegex.exec(responseText)) !== null) {
    const skillBlock = match[1];
    
    const nameMatch = skillBlock.match(/스킬명:\s*(.+)/);
    const descMatch = skillBlock.match(/설명:\s*([\s\S]*?)(?=태그:|$)/);
    const tagsMatch = skillBlock.match(/태그:\s*(.+)/);
    
    if (nameMatch && descMatch) {
      const skillName = nameMatch[1].trim();
      const description = descMatch[1].trim();
      const tags = tagsMatch ? 
        tagsMatch[1].split(',').map(t => t.trim()) : [];
      
      await skillManager.saveSkill(skillName, description, { tags });
      console.log(`🎉 새 스킬 학습 완료: ${skillName}`);
    }
  }
}

// 간단한 키워드 추출
function extractKeywords(text) {
  const stopWords = ['이', '가', '은', '는', '을', '를', '의', '에', '에서'];
  return text
    .split(/\s+/)
    .filter(word => word.length > 2 && !stopWords.includes(word))
    .slice(0, 10);
}

// 작업 로그 저장
async function saveTaskLog(task, result) {
  const logPath = `.claude/logs/${Date.now()}.md`;
  const logContent = `# 작업 로그\n\n**시간**: ${new Date().toISOString()}\n\n## 작업 내용\n${task}\n\n## 결과\n${result}`;
  await fs.writeFile(logPath, logContent, 'utf-8');
}

// 실행 예시
(async () => {
  const result = await runSelfImprovingAgent(
    'Node.js Express API에서 JWT 인증 미들웨어를 구현하고, 보안 취약점을 검토해주세요.'
  );
  console.log('\n=== 에이전트 응답 ===');
  console.log(result);
})();

주의: 위 코드에서 모델명을 최신 버전으로 업데이트했습니다. 2024년 기준 Claude 3.5 Sonnet이 가성비가 좋으니 참고하세요.

6단계: CLAUDE.md로 프로젝트 컨텍스트 설정

여기서 중요한 포인트! Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽어서 프로젝트 컨텍스트로 사용해요. 이걸 잘 활용하면 에이전트가 처음부터 프로젝트를 이해하고 시작합니다.

# CLAUDE.md - 프로젝트 컨텍스트 (Claude Code가 자동으로 읽는 파일)

## 프로젝트 개요
이 프로젝트는 Node.js 기반의 REST API 서버입니다.

## 코딩 규칙
- ESLint + Prettier 사용 (설정: .eslintrc.js)
- 함수명: camelCase, 클래스명: PascalCase
- 비동기 처리: async/await 우선 사용 (callback 금지)
- 에러 처리: 반드시 try-catch 또는 .catch() 사용

## 자가 개선 에이전트 규칙
- 작업 완료 후 반드시 스킬 블록 포함
- .claude/skills/ 디렉토리의 스킬을 우선 참고
- 실패 패턴은 .claude/memory/failures.md에 기록

## 금지 사항
- console.log 프로덕션 코드에 남기지 말 것
- any 타입 사용 금지 (TypeScript 사용 시)
- 하드코딩된 시크릿 절대 금지

실전 삽질 모음: 이런 문제 조심하세요

제가 직접 겪은 문제들이에요. 미리 알았으면 시간을 많이 아꼈을 텐데... 공유해 드릴게요.

문제 1: 스킬 파일이 너무 많아지면 컨텍스트 윈도우 초과

처음에 스킬을 무한정 저장했더니 관련 스킬을 다 불러올 때 토큰 한도를 초과하는 문제가 생겼어요. 해결책은 스킬 파일에 중요도 점수(importance_score)를 추가하고, 상위 3~5개만 로드하도록 제한하는 거였습니다.

// 스킬 로드 시 개수 제한 추가
async loadRelevantSkills(keywords, maxSkills = 5) {
  // ... 기존 코드 ...
  
  // 관련도 점수 계산 후 상위 N개만 반환
  return skills
    .sort((a, b) => b.relevanceScore - a.relevanceScore)
    .slice(0, maxSkills);
}

문제 2: 스킬 저장 형식이 일관성 없음

Claude가 매번 다른 형식으로 SKILL_SAVE 블록을 작성해서 파싱이 실패하는 경우가 있었어요. 시스템 프롬프트에 JSON 형식으로 명확히 지정하는 게 훨씬 안정적이더라고요. 아니면 정규표현식을 더 관대하게 설정하는 것도 방법입니다.

문제 3: VS Code에서 Claude Code 터미널 권한 문제

# macOS에서 이런 오류가 뜰 수 있어요
# Error: EACCES: permission denied

# 해결: npm 전역 설치 경로 권한 수정
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 또는 nvm 사용을 강력 권장 (권한 문제 원천 차단)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

문제 4: .claude 폴더가 Git에 올라가는 문제

스킬 파일을 팀과 공유하고 싶은 건 맞는데, API 로그나 민감한 컨텍스트는 올라가면 안 되잖아요. .gitignore를 이렇게 설정했어요:

# .gitignore
.env
.claude/logs/          # 로그는 제외
.claude/memory/        # 개인 메모리는 제외
!.claude/skills/       # 스킬은 공유 (팀 공유 자산)

결과 확인: 에이전트가 정말 자가 개선되나요?

드디어 됐다! 싶었던 순간을 공유해 드릴게요. 처음 에이전트를 실행했을 때와 5번 사용한 후를 비교해봤습니다.

▲ 5회 반복 사용 후 .claude/skills/ 디렉토리에 쌓인 스킬 파일들 — 에이전트가 스스로 지식을 축적하고 있습니다.

실제 스킬 파일 예시 (에이전트가 스스로 생성)

---
name: jwt-authentication-pattern
created: 2024-01-15T09:23:11.000Z
updated: 2024-01-15T14:45:33.000Z
use_count: 7
success_rate: 95
tags: ["JWT", "인증", "보안", "미들웨어", "Express"]
---

## JWT 인증 미들웨어 패턴

### 핵심 구현 포인트
1. Bearer 토큰 추출 시 공백 처리 주의
2. 토큰 만료(exp) 검증은 jsonwebtoken 라이브러리에서 자동 처리
3. 리프레시 토큰은 반드시 httpOnly 쿠키로 전달
4. 토큰 블랙리스트는 Redis TTL 활용 권장

### 자주 발생하는 실수
- Authorization 헤더 대소문자 구분 실수
- 토큰 서명 키를 환경변수로 분리하지 않는 경우

### 검증된 코드 패턴
[실제 에이전트가 작성한 검증된 패턴 포함]

이 스킬 파일이 있으면, 다음에 JWT 관련 작업을 요청할 때 에이전트가 이 파일을 자동으로 참고해서 처음부터 훨씬 정확한 코드를 작성합니다. 실제로 써보니까 3번째 사용부터 확실히 응답 품질이 달라지더라고요.

성능 개선 수치 (제 홈랩 기준)

• ✅ 반복 작업 처리 시간: 평균 40% 단축 (스킬 재활용 덕분)
• ✅ 첫 번째 시도 성공률: 65% → 87% 향상
• ✅ 코드 리뷰 누락 항목: 평균 3.2개 → 0.8개로 감소
• ✅ 스킬 파일 축적 속도: 하루 평균 2~3개 신규 스킬 생성

물론 이건 제 특정 프로젝트 기준이라 절대적인 수치는 아닙니다. 프로젝트 특성에 따라 다를 수 있어요.

한 단계 더: 멀티 에이전트 구조로 확장하기

기본 구조가 완성됐다면 한 단계 더 나아갈 수 있어요. AI 에이전트 개발의 진짜 재미는 여러 에이전트를 조합하는 데 있거든요.

에이전트 역할 분리 예시

// 전문화된 서브 에이전트 구성 예시
const agents = {
  codeReviewer: new SelfImprovingAgent({
    skillDir: '.claude/skills/review',
    systemRole: '코드 리뷰 전문가. 보안, 성능, 가독성 중심으로 분석'
  }),
  
  refactorer: new SelfImprovingAgent({
    skillDir: '.claude/skills/refactor', 
    systemRole: '리팩토링 전문가. SOLID 원칙과 디자인 패턴 적용'
  }),
  
  testWriter: new SelfImprovingAgent({
    skillDir: '.claude/skills/testing',
    systemRole: '테스트 코드 작성 전문가. TDD 방식으로 접근'
  })
};

// 오케스트레이터가 작업을 적절한 에이전트에 라우팅
async function orchestrate(task) {
  const taskType = await classifyTask(task);
  return agents[taskType].run(task);
}

이 구조는 나중에 별도 글에서 더 자세히 다룰 예정이에요. AI 코딩 자동화의 실제 적용 사례도 함께 다뤄보겠습니다.

정리: Claude Code 자가 개선 에이전트 핵심 요약

▲ Claude Code 자가 개선 에이전트 구축 전체 흐름 요약 — 스킬 저장, 컨텍스트 주입, 자기 평가의 선순환 구조.

오늘 내용을 정리해 드릴게요:

1. 스킬 저장소 구축: .claude/skills/ 디렉토리에 마크다운 형식으로 학습 내용 저장
2. 컨텍스트 주입: 새 작업 시 관련 스킬을 자동으로 시스템 프롬프트에 포함
3. 자기 평가 루프: SKILL_SAVE 블록으로 에이전트가 스스로 학습 내용 생성
4. CLAUDE.md 활용: 프로젝트 컨텍스트를 파일로 관리해서 일관성 확보
5. 점진적 개선: 사용할수록 스킬이 쌓이고 응답 품질이 향상

제가 이 시스템을 한 달 정도 써보면서 느낀 건, "AI 코딩 자동화"의 진짜 가치는 단순 코드 생성이 아니라 프로젝트의 맥락과 패턴을 기억하는 것이라는 점이에요. 처음 세팅이 좀 귀찮긴 한데, 한번 자리 잡으면 진짜 편하더라고요.

다음 글에서는 이 에이전트를 CI/CD 파이프라인에 통합하는 방법을 다뤄볼 예정입니다. GitHub Actions와 연동해서 PR(풀 리퀘스트)이 올라올 때 자동으로 자가 개선 에이전트가 코드 리뷰를 하는 구조인데, 이게 또 꽤 재밌거든요. 기대해 주세요! 🎉

혹시 구현하다가 막히는 부분 있으시면 댓글로 남겨주세요. 제가 겪은 삽질이 여러분의 시간을 아껴드릴 수 있다면 그게 제일 보람있는 일이니까요.

---

자주 묻는 질문 (FAQ)

Q. Claude Code 자가 개선 에이전트를 사용하려면 Claude Pro 구독이 필요한가요?
A. 아니요, Anthropic API 키만 있으면 됩니다. 다만 API 사용량에 따라 비용이 발생하니, 초기엔 claude-haiku 모델로 테스트하고 만족스러우면 sonnet이나 opus로 업그레이드하는 걸 권장해요.

Q. 스킬 파일이 많아지면 성능에 영향이 있나요?
A. 네, 있어요. 스킬 파일이 50개 이상 쌓이면 검색 및 로드 시간이 늘어납니다. 주기적으로 사용 횟수가 낮은 스킬을 아카이빙하거나, 벡터 데이터베이스(예: ChromaDB)로 전환하는 것을 고려해 보세요.

Q. 팀에서 같이 스킬을 공유할 수 있나요?
A. 네! .claude/skills/ 폴더를 Git으로 관리하면 됩니다. 팀 전체가 공통 스킬 베이스를 공유하고, 각자가 개선한 스킬을 PR로 기여하는 방식이 효과적이에요.

📚 함께 읽으면 좋은 글

• OpenClaw와 Claude 연동 중단: 대안 LLM 설정 가이드
• 사용자 네임스페이스 GA: UID/GID 매핑으로 컨테이너 보안 강화하기
• Proxmox VE 9.1 업그레이드 가이드: Debian 13 기반 단계별 진행 및 트러블슈팅
• Claude 3.5 Sonnet API 실전 활용 가이드: 최신 버전 기능과 가격 비교