Claude Code로 command palette를 만드는 실무 가이드

먼저 문제 범위를 정하기

Claude Code로 command palette를 만드는 실무 가이드의 목적은 Claude Code에게 멋진 코드를 한 번에 만들게 하는 것이 아닙니다. 상호작용, 레이아웃, 접근성, 모바일 표시, 매출 동선을 같은 체크리스트에서 확인하는 것입니다. 초보자는 데스크톱 화면만 보고 끝내기 쉽지만, 실제 운영에서는 긴 텍스트, 코드 블록, 광고, CTA, 키보드 조작, 오류 상태가 더 중요합니다.

함께 볼 글은 claude code keyboard shortcuts, claude code accessibility, claude code search functionality 입니다. 공식 자료는 React useDeferredValue, React useMemo, WAI-ARIA practices 를 참고하세요. Claude Code에게는 목표, 수정 금지 범위, 유지할 디자인 규칙, use case, pitfall을 명확히 전달해야 합니다.

Claude Code 프롬프트

가장 작은 안전한 변경으로 이 UI 개선을 구현해 주세요.
기존 라우트, 컴포넌트 구조, design token, 주요 CTA를 유지해 주세요.
복사해서 실행 가능한 코드, use case, pitfall, 모바일 확인, rollback 방법을 주세요.
마지막에 사람이 확인할 review checklist를 작성해 주세요.

Use case checklist

콘텐츠 사이트: 관련 글, 검색, 상담 버튼, 다운로드 링크를 더 쉽게 찾게 합니다.
SaaS 화면: 조작 경로를 줄이되 키보드, 모바일, 오류 상태를 유지합니다.
상품 페이지: 가격, 구매 버튼, 광고, 폼을 가리지 않습니다.
팀 개발: Claude Code가 코드와 review checklist를 함께 남겨야 합니다.

구현 예시

import { useDeferredValue, useMemo, useState } from "react";

type Command = {
  id: string;
  label: string;
  keywords: string[];
  run: () => void;
};

export function CommandPalette({ commands }: { commands: Command[] }) {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);

  const results = useMemo(() => {
    const text = deferredQuery.trim().toLowerCase();
    if (!text) return commands.slice(0, 8);
    return commands
      .filter((command) =>
        [command.label, ...command.keywords].some((value) => value.toLowerCase().includes(text)),
      )
      .slice(0, 8);
  }, [commands, deferredQuery]);

  function onKeyDown(event: React.KeyboardEvent) {
    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
      event.preventDefault();
      setOpen((value) => !value);
    }
    if (event.key === "Escape") setOpen(false);
  }

  return (
    <div onKeyDown={onKeyDown}>
      <button type="button" aria-haspopup="dialog" aria-expanded={open} onClick={() => setOpen(true)}>
        Open commands
      </button>
      {open ? (
        <div role="dialog" aria-modal="true" aria-label="Command palette" className="palette">
          <input
            autoFocus
            value={query}
            onChange={(event) => setQuery(event.target.value)}
            aria-label="Search commands"
            placeholder="Search actions..."
          />
          <ul role="listbox" aria-label="Available commands">
            {results.map((command) => (
              <li key={command.id}>
                <button type="button" onClick={() => { command.run(); setOpen(false); }}>
                  {command.label}
                </button>
              </li>
            ))}
          </ul>
        </div>
      ) : null}
    </div>
  );
}

.palette {
  position: fixed;
  inset: 1rem;
  max-width: 40rem;
  margin: auto;
  padding: 1rem;
  background: canvas;
  color: canvastext;
  border: 1px solid color-mix(in srgb, canvastext 20%, transparent);
}

커맨드 정의는 “실행 내용”과 “검색어”를 나눈다

커맨드 정의는 UI에서 떼어 둡니다. 이렇게 해 두면 권한, 라우팅, 확인 다이얼로그, 측정 이벤트를 나중에 붙이기 쉽습니다. 특히 publish, delete, send처럼 외부 부작용이 따르는 조작은 커맨드 팔레트 본체가 아니라 커맨드 쪽에서 확인합니다. 각 커맨드에는 id, label, 그리고 검색을 위한 keywords를 두고, run은 실제로 수행할 동작만 담습니다. 화면에 보이는 라벨과 검색어를 분리하면 한국어 라벨에 영어 키워드를 함께 넣어 “post”, “draft”로도 찾을 수 있게 만들 수 있습니다.

3가지 이상 실용 유스케이스

첫 번째는 SaaS 관리 화면입니다. 사용자 검색, 청구 화면, 감사 로그, 초대 메일 발송처럼 메뉴가 깊어지기 쉬운 기능을 가로질러 이동할 수 있습니다. 다만 “사용자 삭제”, “플랜 변경”, “청구서 재발송”은 즉시 실행하지 말고 확인 화면으로 이동시키는 설계로 둡니다.

두 번째는 미디어 사이트나 블로그 CMS입니다. 글 작성, 이미지 라이브러리, 카테고리 편집, 공개 전 점검, 검색 인덱스 재생성을 커맨드로 만들 수 있습니다. 글 편집에서 OGP 이미지 확인, 내부 링크 점검으로 이동하는 단축키를 만들면 매일의 갱신 작업이 꽤 짧아집니다.

세 번째는 문서 사이트나 개발자용 도구입니다. API 레퍼런스, 설정 예시, CLI 명령, 트러블슈팅을 가로질러 검색할 수 있습니다. 단순 전문 검색과 달리 “현재 페이지 복사”, “샘플 열기”, “이슈 템플릿 만들기” 같은 액션도 후보로 둘 수 있습니다.

네 번째는 사내 운영 도구입니다. 티켓 생성, 고객 레코드 표시, Slack 알림, CSV 내보내기를 커맨드로 만들 수 있습니다. 여기서는 권한 확인이 중요합니다. 표시할 커맨드만 넘기는 데 그치지 말고, 실행 시점에도 서버 측에서 권한을 확인해야 합니다.

Pitfall checklist

예쁜 스크린샷만 보고 판단하지 않습니다.
후보 항목으로 DOM 포커스를 옮기지 않습니다. li에 직접 포커스를 주면 입력란에서 포커스가 빠져 검색을 이어 가기 어렵습니다. 포커스는 input에 남기고 aria-activedescendant로 선택 중인 후보를 전달합니다.
한국어·일본어 입력 중의 Enter를 놓치기 쉽습니다. IME 변환을 확정하는 Enter와 커맨드를 실행하는 Enter는 다릅니다. event.nativeEvent.isComposing을 확인하지 않으면 변환 확정하려다 publish나 delete를 실행할 위험이 있습니다.
검색 처리를 매번 무겁게 하지 않습니다. 수십 건이면 괜찮지만 수천 건의 후보나 권한 필터가 섞이면 입력이 끊깁니다. useDeferredValue와 useMemo로 입력 응답성과 후보 계산을 분리하고, 규모가 크면 API 측에서 페이징합니다.
단축키 충돌을 확인합니다. Cmd+K/Ctrl+K는 일반적이지만, 입력 폼이나 리치 에디터 위에서 어떻게 다룰지는 제품마다 정해야 합니다.
375px 모바일, 키보드 조작, 느린 네트워크, 오류 상태를 확인합니다.

검증 방법

build 후 모바일 폭에서 overflow를 확인합니다. 코드 블록이 스크롤되는지, CTA가 보이는지, 폼과 광고가 가려지지 않는지 봅니다. Claude Code에게 두 번째 review pass를 요청해 변경 파일, 위험, 삭제 가능한 코드, rollback 방법을 받습니다.

수익화 관점

이 주제는 광고 viewability, 상담 버튼, 상품 카드, 가격표, lead form과 연결됩니다. 팀 프로세스로 만들고 싶다면 Claude Code 교육과 상담에서 구현, review, 배포 확인을 반복 가능한 흐름으로 만들 수 있습니다.

추가 확인

배포 전 스크린샷, 키보드 조작, 모바일 폭, 느린 네트워크, 오류 상태, CTA 위치를 같은 checklist에 넣습니다. 이렇게 해야 Claude Code의 결과가 코드뿐 아니라 실제 비즈니스 결과와 연결됩니다. Claude Code가 방금 작성한 코드라도 삭제할 수 있는 복잡도는 삭제하는 편이 좋습니다.

실전 검증 메모

글 관리용 작은 관리 화면에 이 구성을 넣었더니, 자주 쓰는 “새 글”, “이미지 라이브러리”, “공개 전 점검”으로의 이동이 두 번 클릭에서 Ctrl+K → 두세 글자 입력 → Enter로 바뀌었습니다. 체감 차이가 컸던 부분은 검색 속도 자체보다, 키보드만으로 헤매지 않고 다음 작업으로 넘어갈 수 있다는 점이었습니다. 반대로 공개 커맨드를 곧바로 실행하게 만든 초기안은 위험했기에 확인 화면으로 이동하도록 바꿨습니다. 커맨드 팔레트는 속도를 만드는 UI지만, 너무 빨라서 사고가 나는 동선은 설계 실수입니다. 구현과 리뷰를 분리해서 Claude Code에 맡기는 방식이 diff가 작고 안정적이었습니다.