Sparks 플러그인 리팩토링을 통해 정립한 커맨드 .md 작성 원칙을 정리한다.

배경: 8개 파일 → 1개 파일

Sparks 플러그인은 8개 서브커맨드(add, blog, log, learn, search, list, stats, init)를 각각 별도 파일로 관리했다. spark.md 라우터가 서브커맨드를 파싱한 뒤 spark-commands/{서브커맨드}.md를 Read해서 실행하는 구조였다.

문제는 두 가지였다:

  • Read 오버헤드: 매 실행마다 라우터 + 서브커맨드 파일, 총 2번의 파일 읽기가 필요했다
  • 비표준 디렉토리: spark-commands/는 플러그인 표준 구조(commands/, skills/, agents/, hooks/)에 속하지 않는 임의 디렉토리였다

결과: 8개 파일 1,666줄 → 단일 파일 199줄. 약 90% 감소.

원칙 1: 도메인 고유 지식만 기술한다

커맨드 .md에 들어갈 내용의 기준은 단순하다: Claude가 이미 아는 것은 쓰지 않는다.

생략 가능한 것:

  • AskUserQuestion의 JSON 문법
  • Git 명령어 (git add, git commit, git push)
  • 파일 읽기/쓰기 방법
  • 에러 핸들링 보일러플레이트

기술해야 하는 것:

  • 파일 형식과 frontmatter 스키마
  • 비즈니스 로직 (Leitner box interval, 점수 계산 규칙)
  • 워크플로 분기 조건 (스타일 결정 순서, 파일 존재 여부에 따른 분기)
  • 도메인 특화 규칙 (README 앵커 패턴, 에피소드 append 방식)

원칙 2: 서브커맨드는 단일 파일에 통합한다

서브커맨드가 8개든 3개든, 하나의 command .md 파일에 모두 담는다. 별도 디렉토리를 만들지 않는다.

이 원칙의 핵심은 표준 디렉토리만 사용하는 것이다. commands/, skills/, agents/, hooks/ — 이 4가지 외에 workflows/, sub-commands/, spark-commands/ 같은 커스텀 디렉토리는 만들지 않는다.

단일 파일 구조:

  1. 라우터 (서브커맨드 파싱 + 분기)
  2. 공통 패턴 (Git 감지, frontmatter 스키마 등)
  3. 각 서브커맨드 요약 (10-30줄씩)

원칙 3: 가이드라인은 Do 중심으로 쓴다

~/.claude/CLAUDE.md에 원칙을 추가할 때, Don't보다 Do를 강조한다.

변경 전:

"AskUserQuestion JSON 문법, Git 명령어 등 일반 지식은 생략"

변경 후:

"Command .md는 도메인 고유 지식 중심으로 기술 — 파일 형식, 비즈니스 로직, 워크플로 분기 등 Claude가 추론할 수 없는 것에 집중"

같은 내용이지만 "하지 마라"가 아니라 "이것에 집중하라"로 표현하면 더 명확하고 행동 지향적이다.

최종 반영

~/.claude/CLAUDE.md의 작성 원칙 섹션에 두 줄 추가:

5. Command .md는 도메인 고유 지식 중심으로 기술
   - 파일 형식, 비즈니스 로직, 워크플로 분기 등 Claude가 추론할 수 없는 것에 집중
6. 서브커맨드가 여러 개여도 하나의 command .md 파일에 모두 기술한다

숫자 기준(줄 수 제한)은 의도적으로 넣지 않았다. 원칙이 명확하면 적절한 분량은 자연스럽게 따라온다.