Claude Code 커맨드 파일로 작업을 위임하는 방법

커맨드 파일이 뭔가

Claude Code에는 슬래시 커맨드 기능이 있다. .claude/commands/ 디렉토리에 .md 파일을 넣으면 /파일명으로 호출할 수 있다.

.claude/
  commands/
    new-blog-post.md
    redesign-site.md
    add-sitemap.md

터미널에서 /new-blog-post 주제명 식으로 호출하면 Claude Code가 해당 파일을 읽고 그 지시에 따라 작업을 시작한다.

대화로 요청하는 것과 뭐가 다른가

대화로 요청하면 매번 컨텍스트를 다시 설명해야 한다. “이 프로젝트는 Next.js App Router고, 블로그 글은 이 경로에 있고, 톤은 이렇게 해줘.” 이걸 요청마다 반복하면 길어지고 헷갈린다.

커맨드 파일에 한 번 정리해두면 호출할 때마다 같은 기준이 적용된다. 내가 잊어버려도 파일이 기억하고 있다.

실제로 쓰는 커맨드 파일 구조

사이트맵 추가용 커맨드 파일을 예로 들면 이렇다.

# 사이트맵 추가

## 사용법
/add-sitemap [도메인]

## 처리 조건
- App Router 프로젝트면 app/sitemap.ts로 생성
- 정적 export 방식이면 public/sitemap.xml로 생성
- 어느 방식인지 먼저 확인하고 맞는 방법 선택

## 완료 후
- 생성된 파일 경로 출력
- 포함된 URL 목록 출력

이 파일이 있으면 /add-sitemap charades.cyh-lab.com이라고 호출하는 것만 으로 프로젝트 구조를 확인하고 알맞은 방식으로 사이트맵을 만들어준다.

작업 순서가 있는 경우

여러 파일을 수정하거나 순서가 중요한 작업은 파일 안에 단계를 명시해둔다.

## 작업 순서
1. 프로젝트 구조 파악 (package.json, app/ 디렉토리 확인)
2. 네비게이션 컴포넌트 수정
3. 메인 페이지 재작성
4. About 페이지 내용 교체
5. /blog 라우트 생성
6. 완료 후 변경된 파일 목록 출력

사이트 리디자인 작업을 이 방식으로 넘겼을 때, 컴포넌트 경로나 기존 스타일 방식을 따로 알려주지 않아도 프로젝트 파일을 직접 읽고 맞게 처리해줬다. 내가 모든 파일 경로를 기억할 필요가 없었다.

판단이 필요한 부분은 조건으로 명시한다

“알아서 해줘”는 잘 안 된다. Claude Code가 판단해야 하는 경우라면, 그 판단 기준을 파일에 써넣는다.

사이트맵 추가 커맨드를 만들 때는 이렇게 했다.

## 처리 방식
- 프로젝트가 App Router면 app/sitemap.ts로 생성
- 정적 export 방식이면 public/sitemap.xml로 생성
- 어느 방식인지 먼저 확인하고 맞는 방법 선택

조건 분기를 파일에 넣어두면 내가 매번 확인하지 않아도 된다.

반복 작업에 특히 유용하다

한 번 잘 만들어진 커맨드 파일은 계속 재사용된다. 블로그 글 하나 추가할 때마다 어떤 형식으로 써야 하는지 다시 생각하지 않아도 되고, 사이트맵에 URL 추가할 때도 매번 파일 구조를 확인하지 않아도 된다.

처음 커맨드 파일 하나 만드는 데 10분 정도 걸리는데, 그 이후에는 같은 작업을 요청할 때마다 그 시간이 줄어든다.