Kord/Docs/WorkDone/2026-03-30_HierarchicalRefactor.md

Gathered Command UI Refactoring (2026-03-30)

작업 개요 (Work Summary)

디스코드 슬래시 명령어의 자동완성 목록이 파편화되는 문제를 해결하기 위해, 모든 명령어를 **2단계 계층 구조(Command -> Subcommand)**로 일원화하고 상세 동작은 **옵션(Option Choices)**으로 선택하는 '모아보기(Gathered UI)' 형태로 전면 리팩토링했습니다.

주요 변경 사항 (Key Changes)

1. 개발 규칙 업데이트

• 파일: .agents/rules/kord_routine.md
• 변경: Subcommand Group 대신 Subcommand -> Option Choices 패턴을 사용하여 자동완성 목록을 오염시키지 않도록 규칙 수정.

2. /setup 명령어 독립 (Standalone Wizard)

• 개요: 봇의 초기 환경 설정을 위한 '마법사' 기능을 상징적인 중요도에 따라 별도의 최상위 명령어로 분리했습니다.
• 구조: /setup (세부 옵션 없음)

3. /config 명령어 리팩토링 (Gathered UI)

• 구조: /config [subcommand] action:[choices] [options...]
• 세부 사항:
  • /config system action:language locale:[en/ko] (서버 전체 언어 설정)
  • /config features target:[mimic/emoji] enable:[bool] (각 기능 활성화 여부)
  • 비고: 기존의 setup 과정은 독립된 /setup 명령어를 통해 제공됩니다.

4. /audit 명령어 리팩토링 (Gathered)

• 구조: /audit [subcommand] action:[choices] [options...]
• 세부 사항:
  • /audit channel action:set channel:[#channel] (채널 지정)
  • /audit channel action:clear (채널 해제)
  • /audit channel action:status (상태 확인)
  • /audit channel action:filter category:[...] enable:[bool] (필터링)
  • /audit bot action:permissions (권한 진단)

5. /voice 명령어 리팩토링 (Gathered)

• 구조: /voice [subcommand] action:[choices] [options...]
• 세부 사항:
  • /voice generator action:set/create [...] (생성기 설정)
  • /voice settings action:name/limit/status [...] (채널 설정)

의사 결정 (Decisions Made)

• 2단계 고정: 디스코드 입력창에 /voice만 쳤을 때 generator와 settings만 딱 나타나게 하여 시각적 복잡도를 최소화함.
• 동적 옵션 처리: 특정 action을 골랐을 때만 필요한 옵션(예: locale)이 뒤따라 수동으로 안내되도록 로직 구성 (필수 옵션 미입력 시 에러 메시지 처리).

결과 및 테스트 (Results & Testing)

• yarn build 성공 (Type safety 확인)
• 모든 interaction.options.getSubcommand() 분기 처리 완료.
• 주의: 명령어 스키마가 변경되었으므로, 디스코드가 전역 명령어를 갱신(최대 1시간 소요)할 때까지 대기하거나 봇을 재구동해야 함.