들어가며

커밋할 때마다 Asana 열고, PR 올릴 때마다 템플릿 복붙하고, 리뷰 코멘트 하나하나 정리하고. 어느 순간 코드 작성보다 이런 주변 작업에 시간을 더 쓰고 있었습니다.

이 반복 작업들을 Claude Code 커스텀 커맨드로 자동화했고, 지금은 터미널을 떠나지 않고 개발 사이클 전체를 돌리고 있습니다.

문제 인식

하루를 돌아보면, 코드를 작성하는 시간보다 그 주변 작업에 쓰는 시간이 더 많았습니다.

• 커밋: 브랜치명에서 태스크 ID 확인 → Asana 열기 → 커밋 메시지 작성 → Asana 상태 업데이트
• PR: 변경사항 정리 → 태스크 링크 복사 → 템플릿 작성 → 라벨/어사이니 설정
• 리뷰: 코멘트 하나씩 열어보기 → 파일 위치 파악 → 수정 방향 정리
• 버그 수정: Asana 태스크 열기 → 설명 읽기 → 관련 코드 찾기

각각은 5분도 안 걸리지만, 하루에 수십 번 반복되면 꽤 큰 시간입니다.

무엇보다 컨텍스트 스위칭이 문제였습니다. 코드에 집중하다가 Asana 열고, GitHub 열고, 다시 코드로 돌아오면 흐름이 끊깁니다. Asana 상태 업데이트를 깜빡하면 팀원한테 "이거 지금 어디까지 된 거야?"라는 질문도 받게 되고요.

터미널을 떠나지 않고 모든 워크플로우를 처리할 수 있으면 좋겠다는 생각에서 Claude Code 커스텀 커맨드를 만들기 시작했습니다.

Claude Code 커스텀 커맨드란?

~/.claude/commands/ 디렉토리에 마크다운 파일을 만들면, 그 파일이 슬래시 커맨드로 등록됩니다. 마크다운 안에 워크플로우를 자연어로 적어두면, Claude가 읽고 단계별로 실행합니다.

~/.claude/
├── CLAUDE.md              # 글로벌 설정
├── commands/              # 슬래시 커맨드 정의
│   ├── commit.md          # /commit
│   ├── pr.md              # /pr
│   ├── review-code.md     # /review-code
│   └── review-web.md      # /review-web
├── rules/                 # 항상 적용되는 규칙
│   ├── git.md             # Git 컨벤션
│   └── proactive-suggestions.md
└── skills/                # 복잡한 스킬 정의
    ├── pr-done/           # PR 머지 후 정리
    ├── fix-task/          # 태스크 분석
    └── fix-pr/            # PR 리뷰 코멘트 분석

예를 들어 commit.md는 이렇게 생겼습니다:

# /commit 커맨드
 
1. git status로 스테이징된 파일을 확인한다
2. 보호 브랜치(main, develop)면 중단한다
3. 브랜치명에서 태스크 ID를 추출한다
4. 태스크 ID가 있으면 Asana MCP로 태스크 정보를 조회한다
5. 변경사항과 태스크 정보를 기반으로 커밋 메시지를 생성한다
6. 커밋 후 Asana 태스크 상태를 "개발 완료"로 변경한다

이게 끝입니다. 복잡한 코드 없이 자연어로 절차를 적으면 Claude가 그대로 따릅니다. 한 번 잘 만들어두면 매번 같은 품질로 동작하니까, "AI에게 내 워크플로우를 가르친다"고 생각하면 됩니다.

자동화한 워크플로우

Git + 태스크 관리: /commit, /pr, /pr-done

가장 자주 반복되는 커밋과 PR 작업을 자동화했습니다. 이 세 커맨드의 핵심은 Git 작업을 하면 Asana 태스크 상태가 같이 바뀐다는 점입니다.

/commit — 변경사항을 분석해서 커밋 메시지를 만들고, 브랜치명의 태스크 ID로 Asana까지 업데이트합니다.

/commit              # 브랜치명에서 태스크 ID 자동 추출
/commit TASK-1234    # 특정 태스크 지정

실행하면 이런 흐름으로 진행됩니다.

🔍 Git 상태 확인 (보호 브랜치 체크, 스테이징 파일 확인)
  ↓
🔗 Asana MCP로 태스크 조회 (브랜치명에서 태스크 ID 추출)
  ↓
📝 커밋 메시지 생성 (팀 컨벤션 자동 적용)
  ↓
💾 커밋 실행
  ↓
🔗 Asana 태스크 상태 → "개발 완료" 자동 업데이트

마지막 단계가 핵심입니다. 내가 커밋하는 순간 Asana 보드에 태스크 상태가 바뀌니까, PM이나 팀원이 "이 태스크 개발 다 됐나요?"라고 물어볼 필요가 없습니다.

그리고 커맨드에 태스크 ID 중복 방지 규칙도 넣어뒀습니다.

# 브랜치: feat/TASK-1234-login-page
 
# ❌ 브랜치에 이미 TASK-1234가 있는데 커밋에도 넣으면 지저분함
FEAT: 로그인 페이지 구현 (TASK-1234)
 
# ✅ 브랜치에 태스크 ID가 있으면 커밋 메시지에서 생략
FEAT: 로그인 페이지 구현

사람이면 가끔 까먹는 규칙인데, 커맨드에 한 번 정의해두니까 실수할 일이 없어졌습니다.

/pr — 브랜치 분석, 태스크 연동, 변경사항 요약, 템플릿 적용, 라벨 설정을 한 번에 처리합니다.

/pr develop    # develop 기준 PR 생성

Asana MCP로 태스크 정보를 가져와서 PR 본문에 태스크 링크와 작업 내용을 채워주고, 브랜치 prefix에 따라 라벨도 붙여줍니다.

코드에 TODO, QA 테스트, mock 같은 패턴이 있으면 참고사항에 자동으로 포함시켜서, 테스트 코드가 섞여 있어도 리뷰어가 바로 알 수 있게 했습니다.

/pr-done — PR 머지 후 base 브랜치 최신화, 로컬/원격 브랜치 삭제를 한 번에 처리합니다. PR이 아직 머지 안 됐으면 중단하니까, 실수로 브랜치를 날리는 사고도 방지됩니다.

정리하면:

코드 품질 검증: /review-code, /review-web

커밋 전에 코드 품질을 자동으로 검증하는 커맨드입니다. 정적 분석과 런타임 검증, 두 단계로 나눴습니다.

/review-code — 팀 코드 컨벤션, 빌드, 린트를 한 번에 검사합니다.

/review-code                           # staged 파일 기준 리뷰
/review-code src/components/Button.tsx  # 특정 파일만 리뷰

매직 넘버, console.log, 순차 await 같은 문제를 잡아내는데, "이거 고쳐"가 아니라 Bad/Good 예시를 같이 보여줍니다.

// ❌ Bad — 순차 실행
const user = await fetchUser()
const posts = await fetchPosts()
 
// ✅ Good — 병렬 실행
const [user, posts] = await Promise.all([fetchUser(), fetchPosts()])

팀에서 매번 나오는 리뷰 코멘트가 있잖아요. 그런 패턴을 커맨드에 정의해두면 PR 리뷰 전에 미리 잡아낼 수 있어서, 리뷰어 시간도 아끼고 같은 피드백이 반복되는 것도 줄어듭니다.

/review-web — 런타임 레벨 검증입니다. Chrome DevTools MCP로 실제 브라우저에서 페이지를 열어서, 콘솔 에러부터 접근성까지 검사합니다.

/review-code로 코드를, /review-web으로 런타임을 잡으면 커밋 전에 왠만한 문제는 걸러집니다.

태스크 분석: /fix-pr, /fix-task

GitHub이나 Asana와 연동되는 작업도 자동화했습니다.

/fix-pr — PR 리뷰 코멘트를 모아서 심각도별로 분류하고, 수정 가이드까지 정리해줍니다.

/fix-pr 315    # PR 번호만 치면 됩니다

여러 파일에 흩어진 코멘트를 한눈에 파악할 수 있고, "수정해줘"라고 하면 바로 코드 수정 → /commit까지 이어집니다.

/fix-task — Asana 버그 태스크를 분석해서 관련 코드를 찾아줍니다.

/fix-task TASK-1234

🔗 Asana MCP로 태스크 조회 (제목, 설명, 댓글)
  ↓
🔍 키워드 추출 (화면명, 컴포넌트명, URL 경로)
  ↓
🔍 관련 코드 탐색 (코드베이스 자동 검색)
  ↓
📝 버그 분석 보고서 + 수정 방향 제안

QA에서 버그가 등록되면 태스크 ID만 입력하면 됩니다. 태스크 설명을 읽고, 코드에서 원인을 찾고, 수정 방향을 제안하는 데까지 한 흐름으로 진행됩니다. 수정 후 /commit을 치면 태스크 상태도 같이 바뀌니까, QA 팀은 Asana 보드만 보고 수정됐는지 확인하면 됩니다.

전체 파이프라인

이 커맨드들은 따로 써도 되지만, 실제로는 하나의 파이프라인으로 이어집니다.

일반 개발 흐름:

코드 작성 → /review-code → /review-web → /commit → /pr → /fix-pr → /commit → /pr-done

버그 수정 흐름:

/fix-task TASK-1234 → 코드 수정 → /review-code → /commit → /pr develop

코드 작성 외의 반복 작업이 전부 슬래시 커맨드로 처리되고, 각 단계마다 Asana 태스크 상태가 자동으로 바뀝니다. 팀원들은 따로 물어보지 않아도 보드만 보면 각 태스크가 어디까지 진행됐는지 알 수 있습니다.

설계 시 신경 쓴 점

안전장치 우선

모든 커맨드에 보호 브랜치(main, develop) 체크를 넣었습니다. 그리고 CLAUDE.md에 이런 규칙도 정의해뒀습니다.

## 절대 규칙: 커밋/푸시 금지
 
사용자가 명시적으로 `/commit`, `커밋해줘` 등을 입력하기 전까지
절대로 git commit, git push를 실행하지 않는다.

"빌드 통과했으니 커밋하겠습니다" 같은 Claude의 자의적 판단을 막기 위해서입니다. 자동화 범위가 넓어질수록 이런 브레이크가 꼭 필요하다고 느꼈습니다.

점진적 자동화

처음부터 전부 만들려고 하지 않았습니다. 반복 작업이 보일 때마다 하나씩 만들었습니다.

1. 커밋 메시지 작성이 번거롭다 → /commit
2. PR 템플릿 복붙이 귀찮다 → /pr
3. 브랜치 정리를 까먹는다 → /pr-done
4. 리뷰 코멘트 정리가 번거롭다 → /fix-pr

가장 귀찮은 작업 하나부터 시작하면 됩니다.

결과

커스텀 커맨드 도입 후 가장 크게 달라진 점들입니다.

• 컨텍스트 스위칭 감소: Asana, GitHub 웹을 열 필요 없이 터미널에서 다 끝남
• 태스크 상태 자동 동기화: Git 작업을 하면 Asana가 같이 업데이트되니까, "이 태스크 어디까지 개발 됬나요?" 같은 질문이 사라짐
• 실수 방지: 보호 브랜치 커밋, 태스크 상태 업데이트 누락, PR 템플릿 빠짐 같은 실수가 없어짐
• 코드 품질 향상: 커밋 전 자동 리뷰로 매번 반복되던 리뷰 코멘트 패턴을 사전에 차단

마무리

결국 커스텀 커맨드의 본질은 "내 워크플로우를 AI에게 가르치는 것" 이라고 생각합니다.

처음에는 /commit 하나로 시작했는데, 지금은 커밋, PR, 코드 리뷰, 버그 분석까지 워크플로우 전체가 슬래시 커맨드로 돌아가고 있습니다. 여기에 MCP로 프로젝트 관리 도구까지 연결하니까, 나 혼자 편해지는 게 아니라 팀 전체가 태스크 현황을 실시간으로 공유하게 되었습니다.

반복 작업이 귀찮다면, 가장 자주 하는 작업 하나만 마크다운으로 정리해보세요.

참고

• Claude Code 공식 문서
• Claude Code 커스텀 슬래시 커맨드
• Model Context Protocol 공식 문서