핸즈온으로 필사한 JavaScript, "작동은 하지만 모르겠다"를 Claude Code로 해결한 이야기 〜"이해를 위한 학습 랩(Lab)"을

• 핸즈온 교재를 보고 필사한 포커 게임.
  작동은 하지만, 모든 처리를 완전히 이해하지는 못함. 특히 「HTML과 JS에 걸친 처리」가 읽기 어려움.
• 그래서 코드를 「설명받는」 것이 아니라, Claude Code에게 「작동시키며 내부를 볼 수 있는 학습 랩(Lab)」을 만들어 달라고 했다.
• 「읽기」가 「직접 만지며 확인하기」로 바뀌면서, 이해의 해상도가 한 단계 높아졌다.
• 이 진행 방식을 범용적으로 정리했다(기사 말미). 소재가 무엇이든 같은 방식으로 "이해용 랩"을 만들 수 있다. CLAUDE.md

핸즈온 형식의 교재를 따라 브라우저에서 작동하는 포커 게임을 필사했습니다. 클래스는 깔끔하게 나누어져 있고, 제대로 작동합니다.

…하지만, 솔직히 말하면 "작동은 시킬 수 있지만, 내부에서 무엇이 일어나고 있는지 설명할 수 없는" 상태였습니다. 특히 걸림돌이 된 점은 다음과 같습니다.

• 「Draw 버튼을 누른다 → 잠시 기다린다 → 상대방이 움직인다 → 승패 결정」으로 진행되는 비동기(Asynchronous) 순서가 머릿속에서 재생되지 않는다.
• 그리고 가장 큰 벽은, 처리가 HTML과 JavaScript에 걸쳐서 넘어다닌다는 것. HTML 파일을 훑어봐도 버튼과 카드의 "틀"만 적혀 있을 뿐, 실제 움직임은 JS 측에 있다. 왔다 갔다 하다 보면 어디서 무엇이 일어나는지 놓치게 된다.

해설문을 읽으면 어느 정도는 이해할 수 있지만, 손에 잡히는 느낌(체감)이 남지 않는다. 이것이 출발점이었습니다.

LLM에게 코드를 설명하게 하면 그 자리에서는 이해한 것 같은 기분이 듭니다. 하지만 스스로 만져보며 확인하지 않았기 때문에 정착되지 않습니다.

반대로, 과정이 보이고·결과가 즉시 돌아오는 것이 있다면 이해는 손으로 기억할 수 있습니다. 그래서 Claude Code에게 이렇게 부탁했습니다.

「이 포커 게임의 코드를

이해할 수 있는 프로덕트를 만들어줘」

나온 것은 해설 텍스트가 아니라 만져보며 배울 수 있는 Web 앱이었습니다.

게임 본체에는 전혀 손을 대지 않고, 별도의 디렉토리에 학습용 Web 앱을 만들어 달라고 했습니다. 탭 구성은 다음과 같습니다.

탭	보이는 내용
① 전체상	파일/클래스의 역할 분담과, 기동·조작 처리 플로우
...

이 랩의 본질은 포커 그 자체가 아니라 **「이해하기 어려운 코드를 종류별로 가시화하는 유형」**에 있습니다. 이 부분이 다른 코드에도 적용되는 핵심입니다.

• 변환 로직 (Transformation Logic) → 슬라이더 + 수식의 단계별 표시. 번호를 움직이면 숫자와 그림이 어떻게 결정되는지 눈으로 쫓을 수 있다.
• 평가/판정 로직 (Evaluation/Judgment Logic) → 입력을 선택하면 판정 과정을 트레이스(Trace). 「정렬 → 강한 족보부터 순서대로 검사 → 처음으로 성립한 것을 채택」이라는 흐름과 "왜 그런 결론인가"가 보인다.
• 비동기/순서 (Asynchronous/Order) → 스텝 넘기기 + 자동 재생. 무엇이·어떤 순서로 일어나는지를 실행 로그로 재생할 수 있다.
• 언어를 넘나드는 처리 (Cross-language processing) → 넘나드는 지점(접점)을 표시한다. 그리고 한 번의 왕복을 스텝으로 재생한다.

특히 4번은 저의 가장 큰 고민이었던 "HTML과 JS에 걸쳐 있어서 읽을 수 없다"는 문제에 직격했습니다.

읽기 어려운 정체는, HTML과 JS가 DOM이라는 공유된 칠판을 매개로 대화하고 있는데, 그 통로가 보이지 않는다는 것입니다. 통로는 사실 4가지만 있다고 정리할 수 있습니다.

• ① 이름으로 발견: HTML의 id / class를 JS가 "그 이름의 요소"라고 찾아내어 붙잡는다.
• ② 이벤트 (입력): 클릭 등이 HTML → JS로 넘어가며, 대응하는 처리가 작동한다.
• ③ 속성으로 표시 변경 (출력): JS가 요소의 src나 class를 바꿔 써서 → 화면이 변한다.
• ④ 메타데이터 (연결): JS가 요소에 번호 등을 기입하고, 나중에 "이것은 어떤 데이터인가"를 역조회한다.

랩의 ⑥번 탭에서는 「카드를 선택한다 → 버튼을 누른다」라는 한 번의 왕복을 1스텝씩 재생하며, 지금 HTML→JS인지 JS→HTML인지를 좌우에서 빛나게 하여 보여줍니다.

성공적이었던 협업의 흐름은 대략 다음과 같습니다.

• 먼저 전체 코드를 읽게 하여 「책임 맵 (Responsibility Map)」을 만들게 했다. 어떤 파일이 무엇을 담당하는지, 실행 시점부터의 흐름을 한 장으로 정리했다. -
• 「막히는 지점 (Stumbling Points)」을 특정하게 하고, 각각을 탭에 할당했다. 막연하게 "설명해 줘"라고 하는 대신, 벽의 종류에 따라 UI를 결정한 것이 좋았다. -
• 본체는 수정하지 않았다. 별도의 디렉토리에 「계측 버전 (Instrumented Version)」을 만들게 했다. 원본 코드와 동일한 알고리즘을 중간 과정을 출력할 수 있는 형태로 다시 작성하여, 실제 소스 코드와 대조해 볼 수 있도록 했다. -
• 검증도 맡겼다. 수중에 Node 등의 런타임 (Runtime)이 없는 환경이었기에, macOS에 내장된 JavaScriptCore (osascript -l JavaScript)로 **구문 체크 (Syntax Check)**를 통과시키고, 로직은 대표적인 케이스들로 기대값과 대조하며 확인하도록 했다. -
• "HTML 코드와 대응시키고 싶다" 등, 추가 요구사항으로 심화 학습했다. 한 번에 완벽함을 노리지 않고, 자신의 "이 부분이 모르겠다"를 기점으로 대화를 통해 키워 나간다. 이것이 가장 효과적인 진행 방식이었다.

배운 점은, "설명하게 하는 것"보다 "직접 만져볼 수 있는 교재를 만들게 하여, 막히는 지점을 기점으로 대화하며 키워 나가는 것"이 이해와 기억에 더 오래 남는다는 것이다.

"포커 게임이니까"가 아니라, 어떤 코드라도 동일한 패턴으로 "이해용 랩 (Lab)"을 만들 수 있을 것이다. 그래서 진행 방식을 완전 범용적인 CLAUDE.md로 정리했다. 임의의 프로젝트 직하(또는 ~/.claude/CLAUDE.md)에 두면, Claude Code가 이 방침에 따라 학습 랩을 만들어 준다.

# CLAUDE.md — 미지의 코드를 「이해하기 위한 학습 랩」을 만든다
## 목적
기존 코드(필사한 소재, 인계받은 구현, OSS 등)를 읽는 것으로 끝내지 않고,
...

• 필사하며 "작동은 하지만 모르겠다"가 남는다면, 설명하게 하기보다 "이해용 랩"을 만들게 하는 것이 효과적이었다. -
• 막히는 종류별 시각화 패턴. 특히 「계층을 넘나드는 처리」는, 접점을 유한한 개수로 한정하고 실제 소스와 실행 시점의 차이를 대응시키면 단번에 풀린다. -
• 진행 방식은 완전 범용적으로 분리했다. 소재를 바꿔도 동일한 방식으로 재현할 수 있는 CLAUDE.md.

「읽기」만 하다가 막힌다면, 「만져볼 수 있는 교재를 만들기」로 전환해 보세요. 이해의 깊이가 달라집니다.

도해! JavaScript의 핵심과 요령을 반드시 알 수 있는 책 프로그래밍 실전편