Which-Key로 발견 가능한 Keymap 설계하기

Which-Key Keymaps 정리

Which-Key는 외워야 할 keymap을 팝업으로 옮겨 놓는 플러그인에 그치지 않는다. prefix를 누른 뒤 지금 할 수 있는 동작과 다음 키의 의미를 탐색하는 인터페이스다. LazyVim에서는 <leader> 아래에 기능 영역이 모여 있어, 정확한 키를 잊어도 먼저 목적에 맞는 그룹으로 들어갈 수 있다.

현재 LazyVim의 전체 keymap과 활성 Extra에 따라 달라지는 키는 devkit LazyVim Cheatsheet에서 관리한다. 이 글은 키 목록을 다시 복사하지 않고, Which-Key가 잘 안내할 수 있는 keymap을 어떻게 설계할지에 집중한다.

Prefix는 명령이 아니라 의도를 먼저 말한다

좋은 prefix는 첫 키만 보고도 다음 선택지의 범위를 예상할 수 있다. 예를 들어 <leader>g를 Git 작업으로 정했다면 사용자는 세부 키를 기억하지 못해도 “Git과 관련된 일은 여기에서 찾는다”고 생각할 수 있다. Which-Key는 그 순간 하위 동작을 보여 주며 기억을 보완한다.

이 구조에서는 개별 keymap보다 그룹의 의미가 먼저다.

하고 싶은 일
  → 의미가 분명한 prefix 선택
    → Which-Key에서 하위 동작 확인
      → 명령 실행

따라서 같은 기능 영역의 동작은 같은 prefix 아래에 두는 편이 낫다. 파일 검색과 문자열 검색처럼 경계가 겹치는 동작은 “어떤 도구를 호출하는가”보다 “사용자가 무엇을 찾으려 하는가”를 기준으로 나눈다. 내부 구현이 바뀌어도 사용자의 탐색 경로는 유지되기 때문이다.

반대로 한 그룹에 서로 무관한 동작을 모으면 prefix가 더는 힌트가 되지 않는다. 빈 키를 재활용하기 위해 임시로 넣은 mapping은 당장은 편해 보여도, 시간이 지나면 팝업을 읽고도 위치를 추론할 수 없는 구성이 된다.

발견 가능한 그룹을 만드는 기준

그룹 이름은 짧으면서도 범위를 설명해야 한다. tools, misc, actions처럼 무엇이든 들어갈 수 있는 이름보다 git, search, debug처럼 작업 영역이 드러나는 이름이 좋다. 하위 동작의 설명도 구현 이름보다 사용자가 얻는 결과를 적는다. 플러그인 함수 이름을 그대로 노출하면 설정을 작성한 사람에게만 의미가 통한다.

그룹을 추가할 때는 다음 기준을 확인한다.

1. 첫 prefix만으로 작업 영역을 예상할 수 있는가? 기존 그룹과 의미가 겹치면 새 그룹보다 기존 위치가 낫다.
2. 같은 그룹의 항목이 한 문장으로 묶이는가? 공통 목적을 설명하기 어렵다면 너무 많은 동작을 섞은 것이다.
3. 설명이 동작의 결과를 말하는가? Run picker보다 프로젝트 파일 찾기가 발견하기 쉽다.
4. 현재 mode와 문맥에서 실제로 쓸 수 있는가? 특정 buffer나 mode에서만 유효한 mapping은 그 범위를 명확히 해야 한다.
5. 설정 없이도 이미 발견 가능한가? LazyVim이나 플러그인이 등록한 그룹과 설명을 중복해서 선언할 필요는 없다.

키를 한 번에 많이 설계하기보다 실제 작업 중 반복해서 찾는 동작부터 묶는 편이 안정적이다. 그룹이 작아야 한다는 뜻은 아니다. prefix를 눌렀을 때 다음 선택지가 예측 가능하고, 이름만으로 차이가 드러나는지가 더 중요하다.

Custom mapping을 추가할 때와 추가하지 않을 때

custom mapping은 반복되는 작업에 안정적인 진입점을 만들 때 가치가 있다. 같은 명령을 자주 실행하고, 기존 그룹 안에서 자연스러운 위치를 찾을 수 있으며, 기본 mapping과 충돌하지 않는다면 추가할 이유가 충분하다. 팀이나 여러 장비에서 같은 설정을 공유할 때도 의미 있는 이름과 일관된 prefix는 기억 비용을 줄인다.

다음 경우에는 mapping을 서둘러 추가하지 않는 편이 낫다.

• 한두 번만 실행할 명령이다.
• 기존 LazyVim keymap이나 picker로 이미 쉽게 찾을 수 있다.
• 어느 그룹에 둘지 설명하기 어렵다.
• plugin 또는 Extra가 활성화된 때만 우연히 동작하지만 조건을 설정에 표현하지 않았다.
• 짧은 키를 확보하려고 Vim의 기본 동작을 덮어써야 한다.

특히 “명령이 있으니 keymap도 있어야 한다”는 기준은 피하는 것이 좋다. 모든 기능에 단축키를 붙이면 실행은 한 단계 빨라질 수 있지만, 선택지는 늘어나고 의미 구조는 흐려진다. 자주 쓰지 않는 기능은 command나 picker로 남겨 두는 것이 오히려 발견 가능성을 높인다.

설정 코드

Which-Key 설정을 통째로 복사할 필요는 없다. 기본 구성을 유지한 채, 실제로 필요한 그룹과 mapping만 plugin spec에 보태면 된다. 아래 예시는 프로젝트 작업이라는 의도를 가진 그룹 하나와 동작 하나만 등록한다.

return {
  "folke/which-key.nvim",
  opts = {
    spec = {
      { "<leader>p", group = "project" },
    },
  },
  keys = {
    {
      "<leader>pb",
      "<cmd>make<cr>",
      desc = "Build project",
    },
  },
}

여기서 중요한 부분은 Lua 형식보다 이름 사이의 관계다. <leader>p는 작업 영역을 알리고, b는 그 안에서 build 동작을 선택하며, desc는 팝업에서 결과를 설명한다. 실제 설정에서는 project가 기존 그룹과 겹치지 않는지, :make가 프로젝트에서 올바른 build를 실행하는지, mapping의 mode가 맞는지 먼저 확인해야 한다.

Which-Key를 잘 쓰는 기준은 팝업에 얼마나 많은 키가 보이는지가 아니다. 정확한 키를 잊었을 때도 의도에 맞는 prefix에서 출발해 원하는 동작을 다시 찾을 수 있는가가 기준이다. 새 mapping을 추가할 때마다 이 탐색 경로가 더 선명해지는지 확인하면 설정이 커져도 외워야 할 목록은 늘어나지 않는다.