[Claude Code] 챗봇처럼 쓰던 Claude Code, '한 팀처럼' 일하게 만든 후기

📝 한줄 요약

AI 코딩 도구를 그냥 "챗봇"처럼 묻고 답하는 용도로만 쓰다가, PM 한 명 + 전문 에이전트 6명이 단계별로 협업하는 멀티에이전트 하네스로 바꿨더니 반복 수정 요청이 확 줄고 답변 품질이 눈에 띄게 좋아졌습니다.

바쁘시면 이것만 읽어도 돼요:

• 한 워크스페이스 = 한 프로젝트 원칙을 지키니 컨텍스트가 안정되면서 답변 품질이 확 올라갔다 (가장 큰 깨달음)

• 매번 설명하던 팀 컨벤션(폰트 단위, 코드 스타일, 커밋 규칙)을 "방침"으로 고정하니 AI가 알아서 지킨다

• 기획→설계→개발→리뷰→QA를 전문 에이전트 6종에게 분업시키고, PM이 지휘하게 했다

• 승인 게이트를 둬서 단계마다 멈추니, AI가 제멋대로 진행하는 불안 없이 통제권을 가질 수 있었다

• CLAUDE.md·SKILL.md 같은 설정 파일은 혼자 A-Z 쓰려 하지 말고 AI와 한 줄씩 토론하며 채워라

• 실수로 하네스 파일이 커밋되는 걸 막는 커밋 차단 훅까지 달았다

🎯 이런 분들께 도움돼요

• AI 코딩 도구를 처음 쓰면서 "챗봇처럼"만 쓰고 있는 개발자

• 기존 팀 코드 컨벤션·커밋 규칙을 AI가 자동으로 지키게 하고 싶은 개발팀

• 멀티에이전트(여러 AI 역할 분업)가 실제로 어떻게 굴러가는지 궁금한 사람

😫 문제 상황 (Before)

처음엔 Claude Code를 거의 챗봇처럼 썼습니다. 궁금한 걸 묻고 답을 받는 식이죠. 그런데 실무에 쓰다 보니 같은 불편이 계속 반복됐습니다.

• 매번 같은 설명을 반복해야 했습니다. 디자인을 가져올 때 우리 디자인 컨벤션대로 안 가져와서 매번 다시 설명하고, 코딩 컨벤션도 안 맞아서 코드 리뷰할 때 일일이 확인하느라 시간이 많이 들었습니다.

• 여러 세션을 돌리고 작업이 많아지면 컨텍스트 관리가 안 됐습니다. 엉뚱한 답을 하는 경우가 종종 있어서, 반복적인 요구사항을 매번 다시 적용해야 했습니다.

• 커밋 메시지도 문제였습니다. 기존 커밋 메시지 방식이 있는데 이를 무시하고 마음대로 커밋해서, 다시 수정하는 수고로움이 많았습니다.

결국 "묻고 답하기"만으로는 한계가 명확했습니다. 반복되는 요구사항을 구조로 고정해야겠다고 마음먹은 게 시작이었습니다.

🛠️ 사용한 도구

• 도구명: Claude Code (멀티에이전트 + 스킬 + 워크플로우 커맨드)

• 앱 런타임: Android (Kotlin, Jetpack Compose + 기존 XML), Clean Architecture · 멀티모듈

• 특이사항: figma-desktop MCP로 디자인을 구현 플랜으로 변환

🔧 작업 과정

표준 구조 도입 - "한 워크스페이스 = 한 프로젝트"라는 깨달음

가장 먼저 부딪힌 게 워크스페이스 구조였습니다. 사실 처음에는 한 워크스페이스에 여러 프로젝트를 욱여넣는 식으로 구성하려고 했습니다. 그런데 그렇게 하니 컨텍스트가 엉키면서 엉뚱한 답이 나오더군요.

표준 구조 가이드를 따라가며 "워크스페이스는 하나의 프로젝트에 대해서만 책임지고 동작해야 한다"는 걸 알게 됐습니다. 이 한 가지를 바꾸자 답변 품질이 확실히 좋아지고, 반복적으로 실수해서 수정 요청하는 일이 눈에 띄게 줄었습니다.

현재 클로드를 05-MIGRATION_GUIDE.md 를 읽어줄래

번호 폴더 구조(00-system ~ 90-archive)로 문서를 정리하고, 코드 모듈은 손대지 않는 "불가침" 영역으로 분리했습니다. 하네스 파일은 전부 로컬 전용으로 두고요.

💡 돌이켜보면 이게 이번 작업에서 가장 큰 인사이트였습니다. 거창한 기능보다 "한 워크스페이스 = 한 프로젝트"라는 단순한 원칙 하나가 품질을 가장 크게 끌어올렸습니다.

전문 에이전트 6종 만들기 - PM이 지휘하는 가상 개발팀

다음은 핵심이었습니다. AI 한 명에게 모든 걸 시키니 역할이 섞이고 결과가 들쭉날쭉했거든요. 그래서 역할을 나눠 맡기기로 했습니다.

claude.md를 보고 agent 생성을 같이 해보자

이렇게 6개의 전문 에이전트를 만들었습니다.

• planner — 요구사항·에픽·스토리 정의

• software-architect — 아키텍처·데이터 모델·화면 흐름 설계

• ui-designer — 디자인 명세·디자인 생성 프롬프트

• android-developer — Kotlin 구현 (신규는 Compose, 기존 화면은 기존 방식)

• code-reviewer — 커밋 전 코드 리뷰

• qa — 테스트 작성·검증 (실패 케이스 위주)

그리고 저는 직접 코딩하지 않고 PM 역할을 맡아 각 단계를 에이전트에게 위임합니다. 이게 생각보다 강력했습니다. 나중에 실제로 돌려보니 제가 일일이 단계를 쪼개지 않아도 PM이 알아서 planner→developer→reviewer 순으로 넘기며 진행하더군요. "오, 이게 되네?" 싶었습니다.

반복 지시를 "방침"으로 고정하기

매번 설명하던 것들을 아예 규칙으로 박아두는 작업을 했습니다. 폰트 크기 단위, UI 구현 방식 같은 것들이요.

폰트 크기는 .dp 이고, 색상이나 그런 건 디자인 시스템을 참조하고 없으면 추가하도록 요청하고
agent와 스킬에 compose를 구현하게 되어있는데, 기존 화면을 수정하는 경우는 기존 방식대로
(xml이면 xml) 진행하고, 새로운 화면이 추가되는 경우 compose를 우선으로 개발하도록 해줘

폰트는 시니어 가독성을 위해 dp(고정)로, 신규 화면은 Compose 우선·기존 화면은 기존 방식 유지로 정했습니다. 한 번 정해두니 다음부터는 안 알려줘도 에이전트가 알아서 지킵니다. 매번 설명하던 걸 안 해도 되니 정말 편했습니다.

자주 쓰는 작업을 스킬로 묶기

반복되는 복합 작업은 스킬(트리거 발화로 발동하는 기능)로 만들었습니다.

리뷰 스킬 만들어보자
기획을 기반으로 에픽 스토리를 만드는 스킬을 만들어보자

• figma-implementation-plan — 디자인을 구현 플랜으로 변환

• commit-review — 커밋 전 code-reviewer·qa·ui-designer 3명이 병렬로 리뷰

• epic-story — 기획을 에픽·스토리로 분해

이 과정에서 막힌 부분도 있었습니다.

skill md 파일 내용이 너무 긴데? 너무 길면 클로드 너가 인식 못 하는 거 아닌가

설정 파일이 너무 길면 AI가 제대로 인식하지 못할 수 있어서 분량을 조절했습니다.

/feature 워크플로우 + 커밋 차단 훅 - 안전장치 달기

기획부터 QA까지 한 번에 흐르는 워크플로우 커맨드를 만들되, 각 단계마다 멈춰 제 승인을 받도록 했습니다.

이제 워크 플로우를 만들어볼까
훅을 만드려고 하는데 무엇부터 만들면 좋은지

/feature 커맨드는 기획→설계·디자인→개발→리뷰→QA를 단계별 게이트로 진행합니다. 전자동이 아니라 단계마다 확인받는 구조라, AI가 제멋대로 진행해버리는 불안 없이 통제권을 가질 수 있었습니다. 이 안정감이 의외로 컸습니다.

여기에 하나 더, 하네스 파일이 실수로 git에 커밋되는 걸 막는 pre-commit 훅도 달았습니다. (staged 목록에 하네스 경로가 있으면 차단)

가장 어려웠던 부분 - "md 파일을 직접 쓰는 게 너무 어려웠다"

솔직히 고백하면, 가장 힘들었던 건 기술이 아니라 설정 파일(CLAUDE.md, SKILL.md)을 직접 작성하는 일이었습니다.

구조를 이해하려고 직접 써보기도 했는데, "무엇을 지시해야 내가 원하는 대로 동작할지"가 도무지 떠오르지 않았습니다. A부터 Z까지 제가 다 작성하려니 막막하기만 했죠.

결국 방식을 바꿨습니다. 혼자 다 쓰지 않고, 각 파일마다 AI와 대화하면서 "무엇을 넣으면 좋을지, 뺄지" 토론하며 한 줄 한 줄 채워나갔습니다. 그제서야 풀리기 시작했습니다.

💡 이때 깨달은 게 있습니다. 예전엔 AI가 생성한 md 파일을 "그냥 AI가 만드는 영역"으로 치부했는데, 알고 보니 이 파일이 내가 원하는 결과물을 얻기 위한 아주 중요한 역할을 하더군요. 그래서 설정 파일을 만들 때는 대충 넘기지 않고 정밀하게 대화하며 내 지침이 제대로 반영되게 챙기게 됐습니다.

실전 적용 - 만든 하네스로 실제 기능 개발하기

마지막으로 구축한 하네스를 실제 기능 개발에 처음 적용해봤습니다.

/feature (기능 개선 요구사항 입력)
승인 다음단계로

planner부터 qa까지 단계별 게이트를 거치며 화면 기능을 추가했고, 디자인 시안과 실제 화면을 비교해 문구·줄바꿈까지 맞췄습니다. 중간에 이런 결정도 에이전트가 먼저 물어봤습니다.

Q. 분기를 제거하면 생기는 미사용 코드(함수·테스트·문자열)를 어떻게 할까요? → 함께 제거

제가 일일이 챙기지 않아도 에이전트가 정리할 것까지 먼저 제안하니, 확실히 손이 덜 갔습니다.

✅ 결과 (After)

Before vs After

결과물

PM 한 명이 지휘하고 6개 전문 에이전트가 기획→설계→개발→리뷰→QA를 분담하는 멀티에이전트 하네스가 완성됐습니다.

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 한 워크스페이스 = 한 프로젝트. 여러 프로젝트를 한곳에 넣지 마세요. 워크스페이스가 한 프로젝트만 책임지게 하니 컨텍스트가 안정되면서 답변 품질이 가장 크게 올라갔습니다.

2. 반복 지시는 "방침"으로 고정하세요. 매번 설명하던 컨벤션·규칙을 설정 파일/메모리에 박아두면 AI가 알아서 지킵니다.

3. md 파일은 AI와 대화하며 채우세요. CLAUDE.md·SKILL.md를 혼자 A-Z 쓰려 하지 말고, "이건 넣을까 뺄까" 토론하며 한 줄씩 채우면 훨씬 수월합니다.

4. 승인 게이트를 두세요. 전자동보다 단계마다 멈춰 확인받는 구조가 통제권과 안정감을 줍니다.

이렇게 하면 안 돼요

1. 한 워크스페이스에 여러 프로젝트 몰아넣기. 컨텍스트가 엉켜 엉뚱한 답이 나옵니다. (제가 처음에 한 실수입니다)

2. 설정 파일을 "AI가 알아서 만드는 것"으로 치부하기. md 파일이야말로 결과물 품질을 좌우하는 핵심입니다. 정밀하게 챙기세요.

3. 설정 파일을 무작정 길게 쓰기. 너무 길면 AI가 제대로 인식하지 못합니다. 분량을 조절하세요.

🌍 다른 업무에 적용한다면?

이 경험 이후로 일하는 방식 자체가 바뀌었습니다.

• AI 생성물을 저장하는 폴더 구조도 어떻게 잡을지 고민하게 됐습니다. 예전엔 그냥 쌓아뒀는데, 이제는 체계를 먼저 생각합니다.

• 평소 반복하는 지시들을 보면 "이건 스킬로 만들까, 워크플로우로 만들까?" 하고 자연스럽게 자동화를 떠올리게 됐습니다.

개발이 아니더라도, 반복되는 업무가 있고 "매번 같은 설명을 한다"면 그 설명을 규칙으로 고정하는 발상은 어디든 적용할 수 있습니다.

🚀 앞으로의 계획

1. 하네스 지속 개선 — 실제로 쓰면서 부족한 에이전트·스킬·컨벤션을 계속 다듬어 고도화

2. 반복 지시를 스킬/워크플로우화 — 평소 반복하는 작업을 더 많이 자동화

3. 폴더 구조 체계화 — AI 생성물을 담는 구조를 더 정밀하게 정립

4. 팀 단위 표준화·공유 — 혼자 쓰는 하네스를 팀 전체가 쓸 수 있는 표준으로 발전

📋 재사용 가능한 프롬프트

프롬프트 1: 전문 에이전트로 역할 나누기

우리 프로젝트의 CLAUDE.md를 보고, 기획→설계→개발→리뷰→QA를 각각 맡을 전문 에이전트를 같이 만들어보자. PM은 직접 작업하지 않고 각 단계를 전문 에이전트에 위임하고, 단계마다 내 승인을 받는 구조로 해줘. [우리 프로젝트의 작업 단계]는 본인 상황에 맞게 변경하세요.

프롬프트 2: 반복 지시를 방침으로 고정하기

내가 매번 반복해서 설명하는 [폰트는 dp 고정 / 신규 화면은 Compose 우선 / 커밋 메시지는 OO 형식] 규칙을 앞으로 항상 지키도록 방침으로 고정해줘. 설정 파일과 메모리 어디에 두는 게 좋을지도 같이 정하자. [대괄호 안 규칙]은 본인 팀 컨벤션으로 변경하세요.

프롬프트 3: 설정 파일을 대화로 채우기

CLAUDE.md(또는 SKILL.md)를 만들고 싶은데, 한 번에 다 쓰지 말고 항목을 하나씩 제안해줘. 각 항목마다 "왜 필요한지, 넣을지 뺄지" 같이 토론하면서 한 줄씩 채워나가자.