Claude Code로 생산성을 높이는 나만의 워크플로우

TL;DR Highlight

Claude Code의 병렬 에이전트 워크플로우와 인프라 자동화는 6주 실무 적용으로 개발자 역할을 AI 매니저로 전환한다.

Who Should Read

Claude Code나 유사한 AI 코딩 에이전트를 도입해서 실제 개발 워크플로우에 통합하고 싶은 풀스택 개발자. 특히 여러 작업을 병렬로 처리하고 싶지만 환경 충돌이나 컨텍스트 스위칭 비용 때문에 고민 중인 개발자에게 유용하다.

Core Mechanics

저자는 6주 만에 커밋 수가 눈에 띄게 늘었는데, 이를 단순한 코드 생산량 증가가 아니라 '나는 구현자가 아니라 에이전트를 관리하는 매니저'라는 역할 전환의 부산물로 설명한다. 매니저처럼 반복적인 grunt work(잡일)를 자동화하는 게 첫 번째 패러다임 전환이었다.
첫 번째 자동화로 /git-pr이라는 Claude Code 커스텀 커맨드(슬래시 명령어)를 만들었다. 이 커맨드 하나로 스테이징, 커밋 메시지 작성, PR 설명 생성, 푸시, GitHub PR 생성까지 전부 처리한다. PR 설명은 diff 전체를 읽고 요약하기 때문에 사람이 직접 쓰는 것보다 더 꼼꼼하게 나온다고 한다.
서버 빌드 시간을 1분에서 1초 이하로 줄이기 위해 빌드 도구를 SWC로 교체했다. 1분이라는 대기 시간이 짧은 것 같아도 집중력이 끊기고 다른 일을 하기에도 애매한 '죽은 시간'이었는데, 서브 세컨드 재시작으로 바뀌자 저장하자마자 미리보기가 올라오는 끊김 없는 흐름이 만들어졌다.
Chrome 확장이 계속 크래시 나자 Claude Code의 내장 preview 기능으로 전환했다. 에이전트가 UI 변경 사항을 직접 미리보기로 확인하고 검증까지 하도록 워크플로우를 설계했다. '코드가 완성됐다'는 기준을 에이전트가 UI를 직접 눈으로 확인한 이후로 잡으니, 사람이 중간에 개입하지 않아도 에이전트가 훨씬 오래 자율적으로 돌아갈 수 있게 됐다.
병렬 작업의 가장 큰 걸림돌은 포트 충돌이었다. 프론트엔드와 백엔드가 각자 포트가 필요한데, git worktree(같은 저장소를 여러 디렉터리로 체크아웃하는 기능)를 여러 개 띄우면 환경 변수가 동일해서 모두 같은 포트를 바인딩하려고 충돌했다. 이를 해결하기 위해 worktree 생성 시 자동으로 고유한 포트 범위를 할당하는 시스템을 직접 구축했다.
포트 충돌 문제를 해결하자 동시에 5개 worktree를 운영하는 게 가능해졌다. 워크플로우가 바뀌었다: 여러 에이전트를 각각 별도 worktree에서 동시에 실행하고, 에이전트들이 스스로 UI 검증까지 마치면 저자는 코드 리뷰만 하면 된다. 기획 단계에 집중적으로 개입하고, 구현 중에는 빠지고, 리뷰 때 돌아오는 패턴이다.
저자의 역할이 '복잡한 문제를 직접 해결하는 엔지니어'에서 '에이전트들이 효과적으로 일할 수 있는 인프라를 구축하는 사람'으로 바뀌었다고 고백한다. UI를 직접 구현하는 즐거움은 줄었지만, 에이전트 운영 인프라를 설계하는 것 자체가 새로운 재미가 됐다고 한다.

Evidence

커밋 수를 생산성 지표로 쓰는 것에 대한 비판이 많았다. '코드 라인 수로 품질 판단하던 90년대 관행을 재포장한 것'이라는 날카로운 지적이 있었다. 더 흥미로운 포인트는 '개발자들이 관리자가 그런 지표를 쓸 때는 반대했는데, 막상 자기가 고를 수 있게 되자 똑같은 방식을 선택했다'는 비판이었다. 품질, 버그, 유지보수 부담에 대한 언급이 전혀 없다는 것도 지적받았다.
멀티 에이전트 병렬 작업의 실용성에 의문을 제기하는 의견도 있었다. 에이전트가 여러 파일에 걸친 큰 기능을 만들면 결국 사람이 줄 단위로 다 읽어야 하는데, 코드를 쓰는 것보다 다른 사람(또는 기계)이 쓴 코드를 읽는 게 더 어렵기 때문에 생산성 이득이 상쇄된다는 주장이었다. '이제 AI가 쓴 코드는 그냥 배포하고 깨지면 에이전트가 고치면 된다는 단계로 넘어간 건가?'라는 반어적 질문도 나왔다.
비슷한 워크플로우를 도입했지만 자기 자신이 병목이 된다는 공감 댓글이 있었다. 특히 PM 역할을 겸하는 한 사용자는 하루의 90%를 Claude Code로 일하고 있는데, 에이전트 2개만 관리해도 고립 유지가 어렵고 두뇌 용량이 병목이라고 토로했다. 에이전트 5개를 돌리려면 더 똑똑한 두뇌나 더 나은 도구가 필요하다고 했다.
Opus 4.6 같은 고성능 모드가 처음엔 놀라웠다가 점점 평범해지는 경험을 공유한 댓글도 있었다. 단일 에이전트 세션도 계속 감시해야 하고 조금이라도 방심하면 압도된다는 실사용 경험으로, 여러 에이전트를 병렬로 돌리는 것이 모든 환경에서 잘 되는 게 아닐 수 있다는 점을 시사했다.
AI가 PR 설명을 쓰는 것에 대한 반감도 있었다. 'PR 설명은 한 사람이 무엇을 왜 바꿨는지 다른 사람에게 전달하기 위한 것인데, 그걸 AI에게 위임하는 게 의미 있는 건지 모르겠다'는 직접적인 비판이 있었다. 코드 리뷰의 본질적인 커뮤니케이션 가치가 희석된다는 우려였다.

How to Apply

PR 생성 과정을 자동화하고 싶다면, .claude/commands/ 폴더에 git-pr.md 파일을 만들어 'diff를 읽고 커밋 메시지와 PR 설명을 작성한 뒤 GitHub에 PR을 생성하라'는 지시를 담은 커스텀 커맨드를 만들면 된다. /git-pr 한 줄로 PR 생성까지 완료되니 컨텍스트 스위칭 비용이 줄어든다.
여러 에이전트를 병렬로 돌릴 때 포트 충돌이 문제라면, git worktree 생성 스크립트에 포트 범위 자동 할당 로직을 추가하면 된다. 예를 들어 worktree 인덱스에 따라 프론트엔드는 3000+n, 백엔드는 8000+n 식으로 할당하면 여러 개를 동시에 띄워도 충돌이 없다.
에이전트가 UI 변경을 스스로 검증하게 만들고 싶다면, 에이전트 워크플로우 지시사항에 'UI 변경 후 preview를 띄우고 스크린샷을 확인하기 전까지 완료로 처리하지 말 것'이라는 조건을 명시하면 된다. 이렇게 하면 에이전트가 자체 검증을 마친 후에야 사람이 리뷰하는 구조가 되어 감독 없이 돌아갈 수 있는 시간이 늘어난다.
병렬 에이전트 운영이 처음이라면 단일 에이전트부터 시작해서 에이전트가 스스로 검증하고 완료 기준을 충족하는 워크플로우를 먼저 안정화하는 게 낫다. 여러 댓글 경험담을 보면 2개 이상을 동시에 관리하는 것 자체가 새로운 인지 부하를 만들기 때문에, 인프라 자동화 없이 병렬화하면 오히려 더 지칠 수 있다.

Code Example

snippet

# .claude/commands/git-pr.md 예시 구조
# 이 파일을 만들면 Claude Code에서 /git-pr 커맨드로 사용 가능

## git-pr

1. `git diff --staged` 또는 `git diff HEAD`로 전체 변경 사항을 읽는다
2. 변경 내용을 바탕으로 conventional commit 형식의 커밋 메시지를 작성한다
3. PR 제목과 설명을 작성한다 (What changed / Why / How to test 섹션 포함)
4. `git add -A && git commit -m "[메시지]"` 실행
5. `git push origin HEAD` 실행
6. `gh pr create --title "[제목]" --body "[설명]"` 실행

---
# worktree 포트 자동 할당 스크립트 예시 (bash)

create_worktree() {
  local branch=$1
  local index=$2  # worktree 인덱스 (0, 1, 2...)
  
  local frontend_port=$((3000 + index))
  local backend_port=$((8000 + index))
  
  git worktree add ../worktree-$index $branch
  
  # 각 worktree에 고유 포트가 담긴 .env.local 생성
  cat > ../worktree-$index/.env.local <<EOF
FRONTEND_PORT=$frontend_port
BACKEND_PORT=$backend_port
EOF

  echo "Worktree created: frontend=$frontend_port, backend=$backend_port"
}

Terminology

git worktree하나의 git 저장소를 여러 디렉터리에 동시에 체크아웃할 수 있는 기능. 브랜치를 바꿀 때 stash/checkout 없이 여러 브랜치를 동시에 켜놓을 수 있다.

SWCRust로 만들어진 JavaScript/TypeScript 컴파일러로, Babel보다 훨씬 빠르다. Next.js에서는 설정 한 줄로 교체 가능하며 빌드 속도를 수십 배 개선할 수 있다.

Claude Code skill (커스텀 커맨드)Claude Code에서 /명령어 형태로 호출할 수 있는 커스텀 지시사항. .claude/commands/ 폴더에 마크다운 파일로 정의하며, 반복 작업을 자동화하는 데 사용한다.

grunt work반복적이고 기계적인 작업을 뜻하는 표현. 코드 작성과 직접 관련 없지만 반드시 해야 하는 PR 작성, 스테이징, 브랜치 관리 같은 잡일들을 말한다.

worktree 포트 충돌여러 git worktree에서 각각 개발 서버를 실행하면 모두 동일한 환경 변수(포트 번호)를 참조해 같은 포트를 열려고 시도하면서 실패하는 문제.

agentic workflowAI 에이전트가 단순히 코드를 제안하는 수준을 넘어서, 태스크를 받으면 파일을 읽고 수정하고 명령을 실행하고 결과를 검증하는 것까지 자율적으로 처리하는 작업 방식.