Claude Code 과정을 위한 IntelliJ IDEA의 CodeGym 플러그인

1. 과정 하나, 공부하는 곳 두 군데

시작은 브라우저가 편합니다. 페이지를 열고, 강의를 읽고, 첫 과제를 풀면 됩니다. 에이전트도 거기 있습니다. Claude Code가 브라우저 패널에 바로 연결되어 있어서 첫날부터 에이전트와 함께 과제를 풀 수 있습니다. 제약은 두 가지입니다. 모든 것이 브라우저 안에만 남고, 과제마다 별도의 프로젝트가 만들어집니다.

IDEA는 모든 것이 한곳에 모여 있는 전문가용 도구입니다. 코드, 과제 조건, 터미널, 에이전트가 한 창에 있고, 프로젝트는 여러분의 디스크에 있습니다. 처음에는 닭 잡는 데 소 잡는 칼을 쓰는 것처럼 느껴질 수도 있습니다. 그런데 과제를 몇 개 풀고 나면 IDE 없이는 오히려 불편해집니다. 저라면 바로 IDEA로 넘어가겠습니다. 과제가 쉬울 때 실무 도구에 익숙해지는 편이 부담이 적으니까요.

설치 프로그램을 쓰지 않았다면: 플러그인을 직접 설치하세요

레벨 1의 설치 프로그램이 CodeGym 플러그인과 Claude Code 플러그인을 이미 추가하고 계정 로그인까지 설정해 두었습니다. 설치 프로그램을 실행했다면 이 부분은 건너뛰어도 됩니다. 실행했는지 기억나지 않나요? 플러그인 목록을 열어 보세요. CodeGym과 Claude Code가 이미 있다면 문제없습니다. 다음 섹션으로 넘어가세요.

1. CodeGym 플러그인을 설치합니다. Windows와 Linux에서는 File → Settings → Plugins, macOS에서는 IntelliJ IDEA → Preferences → Plugins를 엽니다. Marketplace 탭의 검색창에 CodeGym을 입력하고 Install을 누릅니다. 아직 IDEA를 재시작하지 마세요. 먼저 두 번째 플러그인을 설치해야 합니다.
2. 공식 Claude Code 플러그인을 설치합니다. Marketplace를 닫지 말고 검색창에 Claude Code를 입력한 다음, Claude Code [Beta]를 선택하고 Install을 누릅니다. 두 플러그인이 모두 설치되면 IDEA를 재시작합니다.
3. 설치가 끝나면 플러그인 상단 바에서 Sign in을 누릅니다. CodeGym 웹사이트에서 설정 → 보안 및 로그인을 열고, 비밀 키를 복사해 IDEA의 로그인 창에 붙여넣습니다.

로그인하면 CodeGym 플러그인이 학습용 프로젝트를 내려받고, 그때부터 IDEA에서 바로 과제를 열 수 있습니다.

2. 과제 목록은 어디에 있나

IDEA 왼쪽 세로 도구 모음에서 Tasks를 누릅니다. 풀 수 있는 과제 목록이 열립니다.

원하는 과제 카드를 찾아 누릅니다. 나타나는 창에서 Open을 선택합니다.

플러그인에서는 웹사이트의 모든 과제를 풀 수 있습니다. 웹사이트에서 이미 풀었고 검사까지 통과한 과제라면, 플러그인이 여러분의 코드를 IDEA 프로젝트로 불러옵니다.

과제 창은 처음에 복잡해 보입니다. 시작할 때 필요한 것은 딱 두 가지입니다.

• Condition - 과제 조건입니다. 무엇을 해야 하고 어떤 요구 사항을 지켜야 하는지 적혀 있습니다.
• 왼쪽의 프로젝트 트리 - 여러분이 작업할 과제 파일이 있습니다. 파일 형식도 이름도 제각각일 수 있습니다. 예를 들어 index.html일 수도, Main.java일 수도, 전혀 다른 이름일 수도 있습니다. 익숙한 이름이 아니라 과제 조건이 요구하는 파일을 찾으세요.

순서는 간단합니다. 먼저 Condition을 읽고, 그다음 프로젝트 트리에서 필요한 파일을 찾아 과제를 풀기 시작하면 됩니다.

3. 에이전트는 파일은 보지만 과제 조건은 보지 못한다

과제를 열면 플러그인이 과제 파일을 디스크에 내려받습니다. Claude Code는 파일을 다루기 때문에 폴더 트리, 코드, 그 밖의 과제 파일을 볼 수 있습니다. 단, 올바른 폴더에서 실행했을 때의 이야기입니다(이건 다음 섹션에서 다룹니다).

하지만 과제 조건과 요구 사항은 Condition 패널에 있습니다. 에이전트는 이 패널을 자동으로 보지 못합니다. 과제가 무슨 뜻인지 이해하고 요구 사항을 골라내는 일은 여러분이 배워야 할 부분이고, 스스로 해 보는 것이 중요합니다.

유혹은 충분히 이해합니다. 과제 조건을 채팅에 복사해 넣고, 무엇을 원하는지는 에이전트가 알아서 파악하게 두는 거죠. 과제 조건을 통째로 복사하지 마세요. 가장 중요한 단계를 건너뛰게 됩니다. 조건을 읽고, 핵심을 찾고, 요구 사항을 이해하는 단계 말입니다.

먼저 과제 조건을 끝까지 읽고 이해하세요. 그다음에는 중요한 부분만 골라 에이전트와의 채팅에 붙여넣어도 됩니다. 목표와 요구 사항을 자기 말로 설명하면 더 좋습니다. 그래야 과제를 제대로 이해하게 되고, Claude Code는 학습을 대신하는 존재가 아니라 도우미로 남습니다.

4. 과제 하나가 곧 프로젝트 하나

마음 편히 읽으실 수 있도록 핵심부터 말씀드리겠습니다. 폴더를 혼자서 챙길 필요는 없습니다. 에이전트는 자신이 엉뚱한 과제에서 작업하고 있다는 걸 알아차리면 그 사실을 알려 주고 올바른 폴더로 옮기자고 제안합니다. 허락하면 직접 옮겨 가기도 합니다.

아래는 같은 일을 IDEA 기능으로 직접 하는 방법입니다. 지금 무슨 일이 일어나는지 이해하고, 에이전트의 안내에 의존하지 않으려면 알아 두는 게 좋습니다.

이제 과정 구조에 관한 가장 중요한 사실입니다. 여기서는 과제 하나하나가 별도의 프로젝트입니다. 공용 프로젝트 안의 파일 하나가 아니라, 독립된 프로젝트입니다. 자기 폴더, 자기 파일, 그리고 .claude에 에이전트용 규칙까지 따로 있습니다. 과정에 과제가 몇 개 있으면 프로젝트도 그만큼 있습니다.

플러그인은 과제마다 창을 따로 열지 않아도 되도록 이 프로젝트들을 모두 codegym-project라는 하나의 트리에 모아 둡니다. 대략 이런 모습입니다.

codegym-project/
└── src/ko/codegym/claude/course/level01/     # 과정의 레벨
    ├── task05/                # 과제 = 별도의 프로젝트
    │   ├── .claude/           # 이 과제의 에이전트 규칙
    │   └── arkanoid.html      # 과제 파일
    └── task09/                # 다른 과제 = 다른 프로젝트
        ├── .claude/           # 이 과제만의 규칙
        ├── arkanoid.html      # 과제 파일, 여러 개일 수도 있음
        ├── clicker.html
        └── tictactoe.html

이게 왜 중요할까요. 보통은 프로젝트 트리 하나가 곧 프로젝트 하나입니다. 안에 있는 파일들이 서로 연결되어 있어서, 에이전트가 전체를 보는 게 도움이 됩니다. 루트에서 에이전트를 실행하면 프로젝트 규칙을 읽고 주변 파일도 보고, 그 모든 것이 여러분에게 유리하게 작용합니다.

그런데 여기서는 그 습관이 발목을 잡습니다. 트리는 하나인데 그 안의 프로젝트는 과제 수만큼 있고, 서로 전혀 연결되어 있지 않습니다. task09는 task05에 대해 아무것도 모르고, .claude 규칙도 과제마다 따로 있습니다. 에이전트 입장에서 프로젝트 루트는 "여러분의 프로젝트"가 아니라, 서로 남남인 프로젝트들을 쌓아 둔 창고입니다. 이웃 과제에는 쓸모 있는 컨텍스트가 없고, 지금 필요한 과제의 규칙도 거기서는 일부만, 그것도 나중에야 가져옵니다. 과제의 지침과 skills는 에이전트가 그 과제의 파일을 열 때에야 로드되고, 과제의 설정은 아예 로드되지 않습니다.

여기서 바로 짚고 넘어가야 할 결론이 나옵니다. 에이전트는 자신이 실행된 위치에서 보이는 것을 봅니다. 프로젝트 루트에서 claude를 입력하면 과정 전체가 시야에 들어옵니다. 다른 과제, 다른 코드, 다른 규칙까지 전부요. 에이전트는 수백 개의 관계없는 파일 사이에서 필요한 파일을 찾게 되고, 최악의 경우 이웃 과제의 파일을 고쳐 버립니다.

그래서 규칙은 간단합니다. 지금 풀고 있는 과제의 폴더에서 에이전트를 실행하세요.

과제 폴더에서 에이전트를 실행하는 방법

1. 왼쪽 프로젝트 트리에서 과제 폴더를 찾습니다.
2. 폴더를 마우스 오른쪽 버튼으로 클릭하고 Open In - Terminal을 선택합니다. 이미 그 폴더 위치로 이동한 터미널 탭이 열립니다.
3. claude를 입력합니다.

괜한 단계를 하나 더 거치는 것처럼 들릴 수 있습니다. 실제로는 오른쪽 클릭 한 번이고, 과제마다 한 번만 하면 됩니다.

이 클릭 뒤에 특별한 마법은 없습니다. IDEA가 선택한 폴더로 이동하는 cd 명령을 대신 입력해 줄 뿐입니다. 이미 열려 있는 터미널에서 직접 해도 결과는 같습니다.

cd src/ko/codegym/claude/course/level01/task09
claude

함정이 하나 있습니다. IDEA는 프로젝트 트리에서 패키지를 점으로 이어진 한 줄로 보여 줍니다. ko.codegym.claude.course.level01처럼요. 하지만 디스크에서는 중첩된 폴더입니다. 화면에 보이는 대로 경로를 입력해 봐야 소용없습니다. 실제 경로는 그렇게 생기지 않았으니까요. 복사하는 편이 간단합니다. 과제 폴더를 오른쪽 클릭하고 Copy Path/Reference를 선택하세요.

이렇게 한 줄로 합쳐 보여 주는 방식에는 뒷이야기가 있고, 이쪽은 더 이상 무해하지 않습니다. IDEA는 안에 다른 폴더 하나만 있고 그 밖에는 아무것도 없는 폴더들의 연결을 모두 한 줄로 합쳐 보여 줍니다. 아직 .claude만 있는 과제라면 이 폴더도 같은 줄에 들어갑니다. 겉보기에는 과제 폴더지만, 마우스 오른쪽 클릭은 그 연결의 가장 깊은 폴더에 적용됩니다.

가장 확실한 방법은 합쳐 보기를 아예 끄는 것입니다. 프로젝트 트리 위의 점 세 개 버튼을 클릭하고 Appearance를 연 다음 Compact Middle Packages의 체크를 해제하세요. 그러면 트리에서 폴더마다 별도의 줄에 표시되고, 오른쪽 클릭이 노린 폴더에 정확히 적용됩니다.

터미널이 이미 열려 있고 경로가 .claude로 끝난다면 cd ..로 한 단계 위로 올라간 다음에 에이전트를 실행하세요.

다음 과제로 넘어갔다면

작업 폴더는 실행할 때 정해지고, 여러분을 따라 저절로 옮겨 가지 않습니다. 그렇다고 복잡한 일을 할 필요도 없습니다. 에이전트가 과제가 바뀐 것을 알아차리고 그 과제의 폴더로 옮기자고 제안합니다.

직접 하고 싶다면 새 과제의 폴더로 이동해서 거기서 claude를 실행하세요. 똑같이 오른쪽 클릭을 써도 되고, cd 명령을 써도 됩니다. 새 과제용으로 터미널 탭을 하나 더 열어 두면 두 탭을 바로 오갈 수 있습니다.

에이전트가 자기 위치를 알려 준다

이걸 일일이 직접 확인할 필요는 없습니다. Claude Code 학습 프로필은 채팅 아래 상태 표시줄에 지금 어떤 과제에서 작업 중인지 표시합니다. JR · claude.course · task02처럼요.

그리고 IDE에 다른 과제가 열려 있으면 같은 자리에 노란색 경고가 나타나, IDE에 task01이 열려 있다고 알려 줍니다. 여러분은 한 파일을 보고 있는데 에이전트는 다른 폴더에서 작업하고 있다는 뜻입니다. 이런 경고가 보이면 멈추고 정확히 무엇이 어긋났는지 확인하세요. 에이전트를 엉뚱한 폴더에서 실행했거나, 여러분이 다른 과제의 파일을 연 것입니다.

학습 세션 로그

과제 폴더에서 에이전트를 실행해야 하는 이유가 하나 더 있습니다. 이건 솔직하게 말씀드려야 할 부분입니다.

Claude Code 학습 프로필에는 작업 기록 기능이 설정되어 있습니다. 과제를 푸는 동안 그 과제 폴더에 .codegym이 생기고, 작업 흐름이 거기에 기록됩니다. 여러분이 에이전트에게 보낸 요청, 에이전트 응답의 앞부분, 에이전트가 수정한 파일, 실행한 명령.

작업을 해 본 과제 폴더는 이런 모습입니다.

task09/
├── .claude/                  # 이 과제의 에이전트 규칙
├── .codegym/
│   ├── cc-transcript.txt     # 작업 로그, 일반 텍스트
│   └── cc-transcript.json
├── arkanoid.html             # 과제 자체의 파일
├── clicker.html
└── tictactoe.html

왜 필요한가: 플랫폼은 이 로그로 과제 풀이를 검사합니다. 여러분의 "풀이 노트"인 셈입니다. 결과뿐 아니라 거기까지 어떻게 왔는지가 보입니다. 좀 꺼림칙하게 들린다는 거, 압니다. 하지만 로그가 없으면 플랫폼은 마지막에 나온 결과밖에 볼 수 없습니다.

로그는 과제 옆, 여러분의 디스크에 남습니다. 파일을 열어서 읽어 볼 수도 있습니다. 그리고 로그는 에이전트를 실행한 위치에 만들어집니다. 프로젝트 루트에서 실행했다면 로그도 루트에 생기고, 과제 폴더에는 생기지 않습니다. cd를 건너뛰지 말아야 할 이유가 하나 더 생긴 셈입니다.

5. 풀이를 검사받으려면

풀이가 끝나면 과제 창에서 Verify 버튼을 누릅니다. 플러그인이 현재 버전의 풀이를 CodeGym 서버로 보냅니다.

검사가 끝나면 결과가 같은 자리, 과제 화면에 표시됩니다. 결과는 둘 중 하나입니다.

• 풀이 통과 - 요구 사항을 충족했고, 과제가 완료로 인정됩니다.
• 풀이 미통과 - 플러그인이 검사 메시지를 보여 줍니다. 그 메시지를 보고 과제 조건으로 돌아가 풀이를 고치면 됩니다.

통과하지 못했다고 프로젝트가 망가진 것은 아닙니다. 평범한 피드백일 뿐입니다. 메시지를 읽고, Condition을 다시 열어 풀이와 비교한 다음, 분명한 문제 하나를 고치세요. 한꺼번에 전부가 아니라 하나만요. 그래야 무엇이 효과가 있었는지 보입니다.

풀이는 몇 번이든 다시 보낼 수 있습니다. 검사가 있는 이유가 바로 그겁니다. 시도하고, 결과를 받고, 고치고, 다시 보내는 것.

6. 알아 두면 좋은 플러그인 설정

과제 동기화: 웹사이트와 플러그인

플러그인은 활성 과정의 과제를 보여 줍니다. 활성 과정은 웹사이트에서 여러분이 선택해 둔 과정입니다. 과정은 여러 개일 수 있지만, 활성 과정은 언제나 하나입니다.

과제 목록과 과제 상태는 저절로 갱신됩니다. 대략 5분에 한 번, 그리고 풀이 제출이 완료될 때마다 갱신됩니다. 웹사이트에서 푼 과제는 플러그인에서도 이미 푼 상태로 나타납니다.

지금 바로 갱신하고 싶다면 오른쪽 위의 아바타를 누르고 Sync tasks를 선택하세요. 활성 과정을 바꾼 뒤에는 이 단계를 반드시 거쳐야 합니다. 동기화하거나 IDEA를 재시작하기 전까지 플러그인은 이전 과정의 과제를 계속 보여 줍니다.

플러그인 내비게이션 바를 숨기는 방법

이상하게 들리겠지만 순서는 이렇습니다. 먼저 바를 나타나게 해야 합니다. 이 바는 Beginner Mode를 꺼야만 나타납니다. Beginner Mode는 일부 기능을 숨긴 플러그인의 간소화된 화면입니다. 그리고 바를 숨기는 체크박스는 바로 그 바 위, 톱니바퀴 아이콘 아래에 있습니다.

1. 오른쪽 위의 아바타를 누르고 Settings - Beginner Mode를 선택해 끕니다.
2. 플러그인 위쪽에 내비게이션 바가 나타납니다. 바에서 Settings (⚙️)를 누르고 "Show plugin navigation bar" 체크박스를 해제합니다.

저는 이 바를 바로 숨깁니다. 버튼 몇 개보다 화면 공간이 더 소중하니까요.