Visual Studio Code에서 CodeGPT를 단순한 채팅창으로만 사용할 경우, 복사해 붙여넣은 코드 조각 이상의 프로젝트 맥락을 파악하기 어렵습니다. CodeGPT가 전체 저장소 구조를 이해하고 파일 간 의존성을 고려해 코드를 설명하고 안전하게 리팩터링하도록 만들려면 두 가지 핵심 설정이 선행되어야 합니다. 바로 **커스텀 API 키 연결(BYOK 방식 및 커스텀 엔드포인트)**과 **로컬 워크스페이스 인덱싱(Codebase Indexing)**입니다. 설정을 완료하면 내장된 시맨틱 검색 도구(Semantic Search Tool)와 프로필 모드를 활용하여 에디터 내에서 다중 파일 로직 분석과 정밀한 코드 수정을 수행할 수 있습니다.
1. 커스텀 API 키 연결 (BYOK 및 커스텀 엔드포인트)
CodeGPT는 하이브리드 요금 모델을 제공합니다. 신규 사용자에게는 월 30회의 기본 무료 대화가 주어지지만, 전문적인 개발 환경에서는 대개 BYOK(Bring Your Own Key) 모델이나 팀 요금제를 사용합니다. 자신의 API 키를 연결하면 CodeGPT 플랫폼의 메시지 횟수 제한 없이 자유롭게 대화할 수 있으며, 토큰 사용료는 해당 모델 제공업체에 직접 결제됩니다.
제공업체 및 API 키 설정 단계
- 확장 프로그램 설치 및 계정 동기화: VS Code 확장 프로그램 마켓플레이스에서
DanielSanMedium이 게시한 CodeGPT: AI Coding Agents & Chat을 검색하여 설치합니다. 사이드바의 CodeGPT 아이콘을 클릭하고 Google, GitHub 또는 이메일로 로그인하여 프로필을 동기화합니다. - 제공업체 설정 진입:
- CodeGPT 채팅 사이드바 하단의 Manage Models 버튼을 클릭하고 Providers 탭으로 전환합니다.
- 또는 VS Code 명령 팔레트(Windows/Linux는
Ctrl+Shift+P, macOS는Cmd+Shift+P)를 열고CodeGPT: Set API KEY명령을 실행합니다.
- AI 제공업체 선택:
- CodeGPT는 OpenAI, Anthropic, Google AI Studio, DeepSeek, Mistral, Cohere, Groq, Cerebras, Perplexity뿐만 아니라 로컬에서 실행되는 Ollama와 LM Studio를 기본 지원합니다.
- 제공업체 공식 콘솔에서 발급받은 비밀 API 키를 붙여넣습니다(조직 구분이 필요한 경우 Organization ID도 함께 기재 가능).
- OpenAI 호환 커스텀 엔드포인트 설정 (Custom Provider):
- 기업 내부 프라이빗 모델, 자체 호스팅 인스턴스(vLLM, 원격 Ollama 등) 또는 제3자 프록시를 연결하려면 제공업체 목록에서 Custom을 선택합니다.
- 대상 모델 이름(예:
cognitivecomputations/dolphin3.0-mistral-24b:free또는 자체 모델 식별자)을 입력합니다. - API 키를 입력합니다.
- 완료 인터페이스의 전체 URL(Custom Link,
/chat/completionsHTTP 엔드포인트)을 입력합니다. - Connect를 클릭하여 연결을 완료합니다.
- BYOK 설정 후 필수 확인 사항: 키를 입력한 후에는 채팅창 상단의 모델 선택 드롭다운에서 사용할 모델을 명시적으로 선택해야 합니다. 활성 모델을 선택하지 않고 대화를 전송하면 "You must select a model first" 오류가 발생합니다.
2. 로컬 워크스페이스 컨텍스트 인덱싱 (Augmented Context)
일반적인 대규모 언어 모델은 에디터에 열려 있지 않은 파일이나 다른 디렉터리의 모듈 관계를 알 수 없습니다. CodeGPT의 Codebase Indexing 기능은 로컬에 벡터 인덱스를 구축하여 AI가 전체 저장소 구조를 파악하도록 돕습니다.
코드 강조 선택 vs. 코드베이스 인덱싱 비교
- 코드 강조 선택(Highlighting): 단일 함수 로직 점검, 특정 에러 원인 분석 등 전체 프로젝트 정보가 필요 없는 일회성 작업에 적합합니다.
- 코드베이스 인덱싱(Codebase Indexing): 변경 사항이 여러 모듈에 영향을 미치거나, 인터페이스 정의가 별도 디렉터리에 위치하거나, 프로젝트 고유 아키텍처 규칙을 반영한 리팩터링이 필요한 경우 필수적입니다.
워크스페이스 인덱스 생성 절차
- CodeGPT 사이드바 메인 메뉴의 Augmented Context 영역에서 Codebase 버튼을 클릭합니다.
- Create Codebase Index를 클릭합니다.
- 폴더 선택 창에서 현재 워크스페이스의 프로젝트 루트 폴더를 지정합니다.
- CodeGPT가 프로젝트 내 소스 파일을 스캔하여 로컬 벡터 인덱스를 생성합니다.
- 생성이 완료되면 AI 에이전트가 **Semantic Search Tool(시맨틱 검색 도구)**을 자동으로 사용할 수 있게 됩니다.
대화 중 컨텍스트 주입 방식
- 자동 시맨틱 검색: 질문에 프로젝트 전반의 정보가 필요할 때 CodeGPT가 자동으로 Semantic Search Tool을 호출하여 연관된 코드 조각을 컨텍스트로 불러옵니다.
- 명시적 파일 첨부: 입력창 하단의
+Add Context버튼을 클릭하고#Files를 선택하여 중요 파일을 고정하거나, 입력창에서@기호를 입력해 현재 열린 파일이나 함수를 지정할 수 있습니다. - 작업 파일 자동 포함: CodeGPT 설정(
⚙️아이콘)에서 현재 편집 중인 활성 파일을 모든 프롬프트에 자동으로 포함하는 옵션을 켤 수 있습니다.
3. 워크스페이스 컨텍스트를 활용한 코드 설명
기존 레거시 코드나 방대한 프로젝트를 분석할 때 로컬 문법만 파악해서는 비즈니스 로직과 설계 의도를 파악하기 어렵습니다.
추천 프로필 모드: Search Mode (검색 모드)
CodeGPT 채팅 인터페이스는 작업 성격에 맞춘 3가지 프로필 모드를 제공합니다:
- Chat Mode: 파일 관련 도구를 사용하지 않는 기본 대화 모드로, 일반적인 프로그래밍 질문에 적합합니다.
- Search Mode (코드 설명 추천): 읽기 전용 탐색 모드입니다. 폴더 구조 탐색, 시맨틱 코드 검색, 연관 파일 읽기 도구를 활용하지만 디스크의 파일을 일절 수정하지 않아 안전하게 심층 분석을 진행할 수 있습니다.
- Agent Mode: 파일 생성, 수정, 삭제 및 통합 터미널 명령 실행 권한을 갖는 모드로, 구현 및 리팩터링 작업에 쓰입니다.
코드 설명 실행 흐름
- 설명할 코드 블록 선택: VS Code 에디터에서 구조를 파악하고 싶은 함수, 클래스 또는 복잡한 로직을 드래그하여 강조합니다.
/Explain명령어 실행:- CodeGPT 채팅 입력창에
/Explain을 입력하고 Enter를 누릅니다. - 또는 에디터 선택 영역에서 마우스 우클릭 후 Explain CodeGPT를 선택합니다.
- CodeGPT 채팅 입력창에
- 저장소 맥락을 반영한 분석: 워크스페이스가 인덱싱되어 있으므로, 호출되는 헬퍼 함수가 어디에 정의되어 있는지, 파라미터가 어느 컨트롤러에서 넘어오는지, 어떤 설계 패턴을 따르는지까지 포함하여 구조화된 설명을 제공합니다.
- 추가 심층 질문: Search Mode 상태에서 다음과 같이 저장소 연관 질문을 이어나갈 수 있습니다:
- "이 미들웨어는 워크스페이스 내 어떤 라우트에 등록되어 있는가?"
- "이 엔티티 타입과 데이터 접근 계층 간의 상호작용 흐름을 설명해 달라."
4. 저장소 전반을 고려한 안전한 코드 리팩터링
맥락 없는 리팩터링은 함수 호출 시그니처를 깨뜨리거나 프로젝트 컨벤션과 상충하기 쉽습니다. CodeGPT는 슬래시 명령어와 권한 제어 도구를 통해 일관성 있는 리팩터링을 지원합니다.
리팩터링 실행 절차
- 리팩터링 대상 지정: 가독성 향상이나 모던 문법 전환(예: async/await)이 필요한 코드 블록을 선택합니다.
/Refactor명령어 호출:- 채팅창에
/Refactor와 함께 구체적인 요구사항(예:/Refactor 콜백 체인을 async/await로 변환하고 유효성 검증 로직을 별도 함수로 분리해 줘)을 입력하고 Enter를 누릅니다. - 또는 우클릭 메뉴에서 Refactor CodeGPT를 클릭합니다.
- 채팅창에
- 결과 검토 및 적용:
- Search Mode 또는 Chat Mode인 경우: 채팅창에 리팩터링된 코드 블록과 설명이 출력됩니다. 확인 후 코드 블록 우측 상단의 Insert code(화살표 아이콘)를 클릭하면 에디터의 활성 파일에 바로 반영됩니다.
- Agent Mode인 경우: CodeGPT가 내장
Edit File도구를 호출하여 디스크의 파일을 직접 수정합니다. 설정에서 자동 승인(Auto-Approve)을 꺼두면 파일 쓰기 전 변경 내역을 검토하고 승인할 수 있습니다.
리팩터링 안전성을 높이는 실무 권장사항
- 2단계 워크플로 (Search → Agent): 리팩터링 전 먼저 Search Mode에서 해당 함수 변경 시 영향을 받는 주변 파일을 분석하고, 계획이 검증된 후 Agent Mode로 전환하여 파일 변경을 적용합니다.
- 터미널 테스트 검증: Agent Mode에서 내장
Run Terminal Command도구를 통해 프로젝트의 테스트 명령어(npm test,pytest등)를 실행하도록 지시하여 리팩터링 후 기능 결함이 없는지 확인합니다. - 주기적 인덱스 갱신: 대규모 리팩터링을 마쳤거나 대규모 Git 브랜치 병합을 수행한 후에는 Codebase 메뉴에서 인덱스를 다시 생성하여 벡터 데이터베이스를 최신 상태로 유지해야 합니다.