코드 독해의 인지 부하를 줄이기 위한 Skill + Neovim 플러그인을 만들었다

AI에게 코드의 동작을 설명하게 할 때, Neovim 내에서 일련의 흐름을 재생하는 메커니즘을 만들었습니다.

디버거(Debugger)의 브레이크포인트(Breakpoint)를 따라가는 듯한 UX로 코드를 추적할 수 있습니다.

모티베이션 (Motivation)

버그 조사 시에 어떤 코드 경로(Code path)에서 문제가 발생하는지 검증하고 싶을 때가 자주 있습니다.

Claude Code에게 그 설명을 시키면, 긴 문장과 코드 발췌가 뒤섞인 텍스트를 출력합니다.

Claude Code에게 코드 경로 설명을 시켰을 때의 답변 예시

이를 읽고 이해하는 것은 다음과 같은 이유로 불필요하게 시간이 걸립니다.

• 인용된 코드의 주변 맥락을 알 수 없어 결국 에디터로 가서 확인해야 함
• 텍스트 속에 흩어져 있는 파일 경로를 찾아 여는 것이 번거로움
• 동일한 이름의 파일이 다른 위치에 있어 어느 것을 가리키는지 모호함
• Claude Code의 답변 문장과 에디터 사이를 시선이 계속 왔다 갔다 하게 됨

그래서 인지 부하(Cognitive load)를 줄이기 위해 다음과 같은 UX로 구성했습니다.

• 에디터 내에서 열리며, 주변 코드 확인이나 정의 점프(Definition jump)도 가능함
• 고정된 핫키(Hotkey)만으로 전후 단계로 이동하며 해당 위치로 바로 갈 수 있음

메커니즘 (Mechanism)

Neovim 플러그인은 아래 형식의 JSON 파일을 읽어서 재생합니다.

/walkthrough

Skill을 통해 AI에게 이 JSON을 작성하게 하고, Neovim에서 열도록 지시하고 있습니다.

{
"steps": [
{
...

코드는 모두 이 커밋에 정리되어 있으므로, 선호하는 에디터에 맞춰 설정해 보세요.