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

- 작성자: [초보 작가](https://community.clauders.ai/member/imported-member-vfo33cm9PK)
- 공간: [바이브 코딩](https://community.clauders.ai/claude-code)
- 게시: 2026-06-04
- 연재: [Claude Code 개발 체계 심화](https://community.clauders.ai/series/advanced-claude-code-harness) 4/5편
- 태그: #클코끝판왕
- 주소: https://community.clauders.ai/claude-code/post/claude-code-%EC%B1%97%EB%B4%87%EC%B2%98%EB%9F%BC-%EC%93%B0%EB%8D%98-claude-code-%ED%95%9C-%ED%8C%80%EC%B2%98%EB%9F%BC-%EC%9D%BC%ED%95%98%EA%B2%8C-%EB%A7%8C%EB%93%A0-%ED%9B%84%EA%B8%B0-842a41d1-1890-80ca-87ea-9f80ff721fe2

---

**📝 한줄 요약**

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

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

- **한 워크스페이스 = 한 프로젝트** 원칙을 지키니 컨텍스트가 안정되면서 답변 품질이 확 올라갔다 (가장 큰 깨달음)
- 매번 설명하던 **팀 컨벤션(폰트 단위, 코드 스타일, 커밋 규칙)을 "방침"으로 고정**하니 AI가 알아서 지킨다
- 기획→설계→개발→리뷰→QA를 **전문 에이전트 6종에게 분업**시키고, PM이 지휘하게 했다
- **승인 게이트**를 둬서 단계마다 멈추니, AI가 제멋대로 진행하는 불안 없이 통제권을 가질 수 있었다
- `CLAUDE.md`·`SKILL.md` 같은 설정 파일은 혼자 A-Z 쓰려 하지 말고 **AI와 한 줄씩 토론하며 채워라**
- 실수로 하네스 파일이 커밋되는 걸 막는 **커밋 차단 훅**까지 달았다

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

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

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

```
현재 클로드를 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. 분기를 제거하면 생기는 미사용 코드(함수·테스트·문자열)를 어떻게 할까요?** → 함께 제거

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

### **Before vs After**

항목

Before

After

AI 사용 방식

챗봇처럼 묻고 답하기

PM + 전문 에이전트 6종 분업

컨벤션 적용

매번 다시 설명

방침으로 고정, 자동 준수

코드 리뷰

컨벤션 확인에 시간 소요

컨벤션 맞아 들어와 시간 단축

컨텍스트

작업 많아지면 엉뚱한 답

한 워크스페이스=한 프로젝트로 안정

커밋

규칙 무시 → 재수정

커밋/프로세스 일관성 확보

### **결과물**

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

구분

항목

에이전트

planner, software-architect, ui-designer, android-developer, code-reviewer, qa

스킬

figma-implementation-plan, commit-review, epic-story

커맨드

/feature (전체 워크플로우)

안전장치

하네스 파일 커밋 차단 훅, 단계별 승인 게이트

### **효과적이었던 것**

1. **한 워크스페이스 = 한 프로젝트.** 여러 프로젝트를 한곳에 넣지 마세요. 워크스페이스가 한 프로젝트만 책임지게 하니 컨텍스트가 안정되면서 답변 품질이 가장 크게 올라갔습니다.
2. **반복 지시는 "방침"으로 고정하세요.** 매번 설명하던 컨벤션·규칙을 설정 파일/메모리에 박아두면 AI가 알아서 지킵니다.
3. **md 파일은 AI와 대화하며 채우세요.** `CLAUDE.md`·`SKILL.md`를 혼자 A-Z 쓰려 하지 말고, "이건 넣을까 뺄까" 토론하며 한 줄씩 채우면 훨씬 수월합니다.
4. **승인 게이트를 두세요.** 전자동보다 단계마다 멈춰 확인받는 구조가 통제권과 안정감을 줍니다.

### **이렇게 하면 안 돼요**

1. **한 워크스페이스에 여러 프로젝트 몰아넣기.** 컨텍스트가 엉켜 엉뚱한 답이 나옵니다. (제가 처음에 한 실수입니다)
2. **설정 파일을 "AI가 알아서 만드는 것"으로 치부하기.** md 파일이야말로 결과물 품질을 좌우하는 핵심입니다. 정밀하게 챙기세요.
3. **설정 파일을 무작정 길게 쓰기.** 너무 길면 AI가 제대로 인식하지 못합니다. 분량을 조절하세요.

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

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

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

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

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

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