실무에서의 Claude Code 활용법: 개발 플로우 자동화 (confluence, jira, github)

요즘 개발자 대부분이 그렇듯, 나도 Claude Code 같은 에이전트형 도구를 일상적으로 쓰고 있다. 그런데 쓸수록 한 가지 질문이 자꾸 떠올랐다.

결국 개발 업무에서 가장 시간을 잡아먹는 건 '코드를 치는 순간'이 아니잖아?

 

기획서를 읽고, 위키에 개발 문서를 정리하고, 티켓을 쪼개고, 구현하고, PR을 올리고, 리뷰 받고, 다시 문서를 맞추는 이 전체 흐름 안에서 정작 '순수하게 코드를 치는 시간'은 작은 조각일 뿐이다. AI가 코드만 잘 써줘도 개발자는 여전히 앞뒤 맥락을 이어 붙이느라 바쁘다.

 

그래서 이번 글에서는 실제 실무에서 업무를 진행하며 Claude Code의 MCP(Model Context Protocol) 와 Skill 두 가지를 활용해, 기획서에서 시작해 PR 이후 재리뷰까지 이어지는 개발 플로우를 하나의 흐름으로 꿰어본 경험을 공유해 보려고 한다. 

---

우리가 그리려던 개발 플로우

기획서(PRD)
   ↓
개발 문서 (Wiki)
   ↓
Jira 티켓
   ↓
구현 & 커밋
   ↓
PR 생성
   ↓
기획서·개발 문서 재리뷰

각 단계는 이미 팀에서 다 하고 있는 일들이다. 다만 단계 사이에 생기는 '번역 비용'이 생각보다 크다.

기획서를 읽고 개발 관점으로 재해석하는 시간, 개발 문서에 정리한 항목을 다시 티켓으로 쪼개는 시간, 구현이 끝난 뒤에 원래 문서와 달라진 부분을 손보는 시간 같은 것들이다.

이 '번역 비용'을 줄일 수 있다면, 플로우 전체가 훨씬 가벼워질 거라고 생각했다.

---

두 가지 축: MCP와 Skill

이 플로우를 자동화하기 위한 도구로 우리 팀은 Claude Code의 두 가지 기능을 중심으로 사용했다.

MCP 

MCP는 쉽게 말해 Claude가 외부 도구를 직접 읽고 쓸 수 있게 해주는 표준 인터페이스다. 실제로 붙인 건 두가지다.

MCP	하는 일
Atlassian MCP	Confluence Wiki, Jira	https://github.com/atlassian/atlassian-mcp-server
GitHub MCP	리포지토리 탐색, PR 생성, 리뷰 코멘트	https://github.com/github/github-mcp-server

이 두 개만 있어도 "문서 → 티켓 → 코드 → PR"이라는 종축이 완성된다.

즉 Claude가 직접 위키에서 기획서를 읽고, Jira에 티켓을 만들고, GitHub에 PR을 올리는 것까지 한 세션 안에서 가능해진다.

(요즘은 MCP의 느린 속도로 CLI로 많이 갈아타고 있는 추세라고 하던데, 조만간 바꾸어 볼 계획이다.)

Skill 

MCP가 '도구'라면 Skill은 '그 도구를 어떻게 쓸지에 대한 합의' 다. 예를 들어 "개발 문서를 작성한다"는 일은 사람마다 스타일이 다를 수밖에 없는데, 팀에서 합의된 템플릿과 원칙을 Skill로 적어두면 Claude가 그 규칙을 따라 초안을 만들어 준다.

 

한 사람이 고민해서 다듬은 Skill이 팀 전체의 자산으로 쌓이는 구조라는 점도 중요한데, 이 부분은 바로 뒤에서 '플러그인'과 함께 다시 얘기하려고 한다.

---

플러그인 — 팀이 같은 기준선에서 Claude Code를 쓰게 만들기

사실 여기까지 얘기한 MCP와 Skill은 전부 "혼자서도 쓸 수 있는" 도구들이다. 문제는 팀이다.

각자 알아서 MCP를 붙이고, 각자 알아서 프롬프트를 다듬고, 각자 알아서 Skill을 만들면, 같은 회사에서 같은 코드를 만지는데 Claude Code가 뱉어내는 결과가 사람마다 조금씩 다르게 생기기 시작한다. 개인 생산성은 올라가도, 팀 단위의 일관성은 오히려 흔들릴 수 있다.

그래서 팀 단위로 쓰기 시작하면서 가장 먼저 한 일은, Claude Code를 쓰는 방식 자체를 팀 단위로 통일하는 것이었다. 구체적으로는 이런 것들이다.

• 어떤 MCP 서버를 붙일지, 어떤 설정 값을 쓸지
• 어떤 Skill과 커맨드를 제공하여 워크플로우를 맞출지
• 팀의 코딩 스타일·아키텍처 원칙·PR 템플릿을 Claude가 참조할 수 있는 CLAUDE.md 와 .claude/rules/* 형태로 어떻게 떨굴지

이걸 각자 로컬에 복붙해 두는 대신, Claude Code의 플러그인이라는 포장 단위로 묶어서 팀에 배포했다.

내부 규칙이 바뀌면 리포지토리에 푸시하는 것만으로 팀 전체에 반영된다.

버전이 하나로 맞춰지니, 같은 질문을 같은 커맨드로 던지면 누가 실행하든 거의 같은 품질의 결과가 나온다.

 

플러그인 안에는 /setup 같은 초기화 커맨드도 넣어두었다.

새 프로젝트에서 이 커맨드를 한 번 실행하면, 언어·프레임워크를 자동으로 감지해서 해당 스택에 맞는 Claude Code 컨벤션 파일을 CLAUDE.md와 .claude/rules/ 밑에 떨군다.

예를 들어 Kotlin/Spring 프로젝트면 Kotlin 코드 스타일, Spring 구조, API 컨벤션, 테스트 컨벤션 같은 문서가 각각 떨어지고, 각 문서에는 paths로 "어떤 파일을 편집할 때 이 문서를 같이 로드할지"가 선언되어 있다. 덕분에 컨트롤러를 수정할 때는 API 컨벤션이, 테스트 파일을 수정할 때는 테스트 컨벤션이 자동으로 Claude의 컨텍스트에 들어온다. 사람은 "이 컨벤션 좀 지켜줘"라고 매번 얘기할 필요가 없다.

 

여기서 한 가지 짚고 가자면, 이걸 "팀의 컨벤션을 정의한다"라고 부르는 건 엄밀히 말해 조금 어색하다. 코딩 컨벤션 자체는 이미 팀에 존재하던 것이고, 플러그인이 한 일은 그 컨벤션을 Claude가 읽을 수 있는 형태로 박제하고, 동시에 Claude Code를 쓰는 방식 자체를 팀 단위로 묶어내는 것에 더 가깝다. 말하자면 플러그인은 "우리 팀의 Claude Code 사용 설명서"를 코드로 옮겨 둔 결과물인 셈이다. 새로 합류한 팀원이 따로 튜토리얼 없이도 첫날부터 팀의 기준선 위에서 Claude Code를 쓸 수 있다는 것, 이 점이 생각보다 큰 효과였다.

---

단계별로 살펴보기

이제 앞에서 그린 플로우를 단계별로 따라가 보자.

1단계. 기획서 → 개발 문서

가장 먼저 맞닥뜨리는 단계이자, 사실 가장 '개발자의 뇌'가 많이 갈려 나가는 단계다.

기획서는 기획자의 언어로 쓰여 있고, 개발자는 그걸 읽으면서 머릿속으로 API, 도메인, 예외 케이스, 배치 여부 같은 걸 재구성해야 한다.

이 단계를 Skill로 표준화했다. 대략 이런 식으로 돌아간다.

1. 기획서의 Confluence 링크를 전달한다.
2. Claude가 Confluence MCP로 해당 페이지를 읽는다.
3. 필요한 경우 관련된 기존 문서·코드·API 스펙도 같이 읽는다.
4. 개발 문서 작성 스킬의 템플릿에 따라 구현 항목 단위로 정리한다.
5. 결과를 다시 Confluence의 지정된 공간에 문서로 생성한다.

중요한 규칙이 하나 있는데, 기획서에 없는 내용은 Claude가 임의로 채우지 않도록 강제했다는 점이다.

판단이 필요한 부분은 [확인 필요] 같은 태그로 표시해 '검토 필요 항목' 섹션에 모아둔다. 개발자는 이 섹션만 한 번 훑어보면, 기획자에게 물어볼 것들을 한 번에 정리할 수 있다.

경험적으로, 이 단계에서 가장 크게 얻은 건 생각의 누락을 줄여준다는 점이었다.

사람은 익숙한 패턴을 무의식적으로 당연하게 여기기 쉬운데, 템플릿 기반의 Skill은 "이 항목의 예외 케이스는?" "트랜잭션 경계는?" 같은 질문을 빠뜨리지 않고 던져 준다.

 

2단계. 개발 문서 → Jira 티켓

개발 문서의 구조를 "구현 항목 하나 = 티켓 하나"가 되도록 설계해 둔 게 여기서 빛을 발한다.

개발 문서의 #### 섹션 하나가 곧 Jira 티켓 하나에 대응하기 때문에, 각 항목을 읽고 Jira MCP로 티켓을 만드는 일이 매우 단순해진다.

• 제목: 구현 항목의 제목을 그대로
• 본문: 해당 섹션의 스펙·로직·예외 처리
• 에픽/상위 이슈: 개발 문서 전체를 대표하는 상위 이슈에 연결
• 라벨/컴포넌트: 개발 문서 메타에서 추출

여기서 포인트는 티켓과 문서의 추적성이다. 티켓 본문에는 개발 문서 링크가, 개발 문서에는 티켓 번호가 각각 박혀 있기 때문에, 어느 쪽에서 들어가도 반대쪽을 찾아갈 수 있다. 나중에 구현이 끝난 뒤 재리뷰를 할 때 이 링크가 결정적인 역할을 한다.

 

3단계. 티켓 → 구현 → PR

구현 단계는에서는 Jira 티켓 번호 하나를 던지면 대략 이런 순서로 흘러간다.

1. 티켓 읽기 — Jira MCP로 이슈 타입과 상세 내용 확인
2. 브랜치 생성 — 이슈 타입에 맞는 prefix로 브랜치 생성
3. 구현 계획 수립 — 영향 범위, 도메인 설계, API 설계, 테스트 계획을 먼저 제시하고 사용자 승인
4. 구현 — 팀의 아키텍처 원칙에 맞게 레이어 단위로 Bottom-Up 구현
5. 테스트 & 빌드 검증
6. 자체 코드 리뷰 — 코드 리뷰 Skill의 체크리스트를 스스로 돌려보기
7. 커밋 & PR 생성 — GitHub MCP로 PR 본문 템플릿에 맞게 생성

여기서 주의 깊게 설계한 부분이 몇 가지 있다.

 

① 계획을 먼저 보여주고 멈추기. 바로 코드로 뛰어들게 두면 기대와 다른 방향으로 가기 쉽다. 그래서 3단계에서 반드시 사람의 승인을 받고 넘어가게 했다. 이 한 단계만 넣어도 "어... 그거 말고요..." 하면서 뒤집는 일이 거의 사라진다.

② 애매하면 물어보기. 어떠한 구현에 있어서 조금이라도 애매한 부분은 무조건 개발자의 확인을 받도록 지시했다. 그렇지 않고 그대로 진행하게 둔다면, 또 예상치 못한 방향으로 개발이 된다.

③ Skill이 컨벤션을 자동 주입하도록 하기. 파일을 편집할 때 어떤 컨벤션 문서가 로드될지를 파일 경로 기준으로 미리 지정해 두었다.(.claude/rules) 예를 들어 컨트롤러를 수정할 때는 API 컨벤션 문서가, 테스트 파일을 수정할 때는 테스트 컨벤션이 자동으로 Claude의 컨텍스트에 들어간다. 덕분에 "우리팀 컨벤션에 맞춰줘"라고 매번 얘기할 필요가 없다.

④ 실패하면 즉시 멈추기. 테스트가 깨지거나 빌드가 실패하면 다음 단계로 절대 넘어가지 않도록 했다. 자동화에서 가장 위험한 건 '반쯤 된 결과를 끝까지 밀고 나가는' 것이라, "멈추고 보고하는" 지점을 명시적으로 박아두는 게 생각보다 중요하다.

 

4단계. PR 이후, 기획서·개발 문서와 재리뷰

이 단계가 사실 이 플로우의 핵심이자 가장 소홀해지기 쉬운 부분이다. 구현이 끝나면 많은 팀이 PR 리뷰는 꼼꼼히 해도, "원래 기획과 실제 구현이 정말 같은 방향을 보고 있는지" 는 별로 확인하지 않는다. 시간이 없기 때문이다.

여기서도 Skill이 한 몫을 한다. 개발 문서 동기화 스킬은 대략 이런 일을 한다.

1. 원본 개발 문서(Confluence)를 읽는다.
2. 현재 브랜치의 git diff를 읽는다.
3. 두 가지를 항목 단위(#### 섹션)로 매칭한다.
4. 각 항목에 대해 다음 중 하나로 리포트한다.
   • 일치 — 개발 문서와 구현이 동일
   • 구현만 존재 — 개발 문서엔 없는데 코드에 있음 → 개발 문서 보강이 필요한가?
   • 개발 문서만 존재 — 개발 문서엔 있는데 구현이 없음 → 빠뜨린 건가, 의도적 제외인가?
   • 차이 있음 — 시그니처·로직·예외 처리 중 어디가 어떻게 다른지
5. 사용자 판단에 따라 개발 문서를 업데이트한다 (코드는 건드리지 않는다).

포인트는 이 Skill이 코드를 직접 수정하지 않는다는 것이다.

동기화의 목적은 "문서가 거짓말을 하지 않게 만드는 것"이지, 구현을 뒤집는 게 아니기 때문이다. 구현을 바꿀지 말지는 사람이 결정할 영역으로 남겨둔다.

이 단계를 넣고 나서 가장 큰 변화는, 개발 문서가 오래되지 않는다 는 점이었다.

이전에는 개발이 끝나는 순간 개발 문서가 과거형 문서가 되어버렸는데, 이제는 구현과 맞춰진 최신 상태로 남게 된다. 이후에 합류하는 팀원이나, 같은 도메인을 다시 건드릴 때의 비용이 확연히 줄어들었다.

---

이 플로우를 굴려보고 느낀 것들

두세 달 굴려 보면서 가장 크게 체감한 것은 세 가지다.

 

① '반복'과 '판단'을 분리하게 된다.
이전에는 '문서 정리', '티켓 쪼개기', 'PR 본문 쓰기' 같은 반복 작업이 판단 작업과 뒤엉켜 있었다. Skill로 반복을 묶어내고 나니, 사람은 "이걸 할지 말지", "이 설계가 맞는지"라는 판단에만 집중할 수 있게 됐다. 같은 하루를 써도 뇌가 훨씬 덜 피곤하다.

② 자동화의 진입점이 분산되면 안 된다.
처음에는 기능별로 이것저것 커맨드를 만들었는데, 쓰다 보니 "어떤 커맨드를 언제 써야 하지?"가 오히려 인지 부하가 됐다. 그래서 가능한 한 한 커맨드로 전체 플로우를 꿰고, 그 안에서 Skill이 각자의 역할을 하도록 정리했다. 사용자의 머릿속에 있어야 할 건 "이 작업의 진입점은 어디였지?" 하나 뿐이다.

③ 자동화는 '멈추는 지점'을 잘 넣는 것이 반이다.
계획 승인, 테스트 실패 시 중단, 개발 문서 갱신 전 확인 — 이런 사람 개입 지점을 빠뜨리지 않는 게, 역설적으로 자동화를 신뢰할 수 있게 만드는 핵심이었다. "알아서 다 해주는 자동화"가 아니라, "믿고 맡길 수 있는 지점에서만 알아서 해주는 자동화"를 만드는 게 목표가 되어야 한다.

한계와 앞으로

물론 아직 매끄럽지 않은 부분도 많다.

• 기존 히스토리를 읽는 영역에서는 부족하다. 클로드가 '코드'만 보고 기존 비즈니스 로직에 대한 히스토리를 파악하기란 쉽지 않다. 따라서, (기획서 driven이 아닌) 기존 동작하는 기능을 수정할 때에는 비즈니스 로직을 해치지는 않는지 꼭 사람이 확인하는 과정을 거쳐야하더라.
• 기획서의 구조가 팀마다 달라서, 개발 문서 Skill이 모든 PRD에 똑같이 잘 먹히지는 않는다. PRD 포맷 자체를 조금씩 정돈해 나가야 한다.
• 재리뷰 단계에서 Claude가 '의도적 제외'와 '누락'을 완벽히 구분하진 못한다. 결국 판단은 사람이 해야 하고, Skill은 그 판단을 놓치지 않게 떠올려 주는 역할에 머무르는 게 적절한 것 같다.

앞으로는 이 플로우를 더 다양한 포지션(프론트엔드, 데이터, QA)에도 맞춰 보고 싶다.

마치며

Claude Code 같은 에이전트 도구의 힘은 결국 '혼자 잘하는 것'이 아니라 '플로우 안에 녹아드는 것' 에 있다고 생각한다.

기획서 한 장에서 출발해 PR이 머지되는 순간, 그리고 그 이후 문서가 다시 최신 상태로 돌아오는 순간까지 — 그 긴 호흡을 사람 혼자 놓치지 않고 끌고 가기란 쉽지 않다.

그 틈을 MCP가 연결하고, Skill이 반복을 다듬어 주면, 개발자는 정말로 재밌는 '판단'과 '설계'에 시간을 쓸 수 있게 된다.

비슷한 고민을 하고 계신 분들께 이 글이 작은 참고라도 되었으면 좋겠다.

각자 팀의 문화와 툴 스택은 다르겠지만, "플로우 전체를 한 줄로 꿰어 본다" 는 관점 자체는 어디에서든 해볼 만한 시도라고 생각한다.