AI 협업 워크플로우 설계기: MATLAB 8,000줄 리팩토링 프로젝트

🔧 AI 협업 워크플로우 설계기: MATLAB 8,000줄 리팩토링 프로젝트

"AI로 코딩을 날로 먹고 싶었는데, MATLAB App Designer 때문에 시스템을 설계하게 된 이야기"

 

🚨 시작: 현실적인 문제에 부딪히다

원래 목표: 그냥 날로 먹고 싶었다

솔직히 말하면, 처음 생각은 간단했습니다.

"AI한테 시켜서 코딩 좀 편하게 하면 안 될까?"

개인적으로 개발해서 회사에서 활용하고 있던 MATLAB App Designer로 만든 8,000줄짜리 프로그램을 일반적인 .m 파일로 변환해야 했는데, 이걸 그냥 Claude나 ChatGPT한테 던져주면 알아서 해줄 거라고 생각했거든요.

첫 번째 벽: App Designer의 현실

하지만 현실은 달랐습니다.

문제점들:

• App Designer 코드는 GUI와 로직이 뒤섞여 있음
• 8,000줄을 한 번에 처리하기엔 토큰 제한
• 단순 복붙으로는 구조 파악 불가능
• 하드웨어 연동 부분은 실제 테스트 필요

"아, 이거 그냥 시킬 수 있는 게 아니구나..."

그래서 시작하게 된 것이 체계적인 AI 협업 워크플로우 설계였습니다.

---

🎯 전략 수립: 문제를 시스템으로 해결하기

핵심 아이디어: 도구의 조합

제가 사용할 수 있는 환경을 정리해봤습니다:

기본 환경:

• Claude MCP: 하드디스크 파일 직접 읽기/쓰기
• GitHub Copilot Pro Plus: VSCode에서 Claude 모델 사용
• 개인 Confluence + Jira: 문서화 및 작업 관리

초기 구상: 역할 분담 시스템

┌─────────────────────────────────────────────────────────────┐
│                   AI 협업 워크플로우                        │
├─────────────────────────────────────────────────────────────┤
│ 1. 전략 기획 (인간)     │ • 전체 방향성 설정                │
│                         │ • 우선순위 결정                    │
│                         │ • 품질 기준 정의                   │
├─────────────────────────┼────────────────────────────────────┤
│ 2. 실행 계획 (Claude)   │ • 모듈 분해 및 의존성 분석         │
│                         │ • 상세 작업 분할                   │
│                         │ • 코딩 가이드라인 작성             │
├─────────────────────────┼────────────────────────────────────┤
│ 3. 실제 구현 분담       │ • Claude MCP: 파일 구조 생성       │
│                         │ • Copilot: 세부 코드 구현          │
│                         │ • 철저한 가이드 기반 작업          │
├─────────────────────────┼────────────────────────────────────┤
│ 4. 연속성 보장          │ • Confluence: 기술 문서화          │
│                         │ • Jira: 진행 상황 추적             │
│                         │ • 중단 후 재시작 가능한 구조       │
└─────────────────────────────────────────────────────────────┘

---

🔨 1단계: 철저한 계획 수립

Claude와의 첫 번째 세션

나: "8,000줄 MATLAB App Designer 코드를 일반 .m 파일로 리팩토링하는 계획을 세워줘"

Claude의 분석 결과:

원본 코드 분석
├── UI 컴포넌트 (2,500줄)
├── DAQ 하드웨어 연동 (2,000줄)  
├── 신호 처리 및 분석 (1,800줄)
├── 데이터 관리 (1,200줄)
└── 유틸리티 함수 (500줄)

리팩토링 전략
├── 모듈별 분리 (7개 독립 모듈)
├── 의존성 최소화
├── AppConstants를 통한 하드코딩 제거
└── 테스트 코드 병행 작성

핵심 결정: 가이드라인 우선 작성

여기서 중요한 선택을 했습니다.

Copilot에게 자유도를 주지 않기로 결정

이유:

• AI는 창의적이지만 일관성이 떨어질 수 있음
• 8,000줄 프로젝트에서는 통일성이 생산성보다 중요
• 나중에 유지보수할 사람(저)을 위한 예측 가능한 코드 필요

해결책: 초상세 코딩 가이드라인 작성

---

📋 2단계: 코딩 표준 및 가이드라인 구축

START_HERE_FIRST.md 작성

프로젝트의 헌법이 될 문서를 작성했습니다.

주요 내용:

## 🚫 WHAT NOT TO DO
### ❌ DO NOT USE HARDCODED CONSTANTS
- **ABSOLUTELY NO MAGIC NUMBERS**
- Use config/AppConstants.m for all constants
- Document the meaning and source of every constant

## 📁 File Organization Rules
- main_ui.m: UI creation and initialization
- daq_controller.m: DAQ session management  
- signal_processor.m: Signal processing and FFT
- (각 파일의 정확한 역할 정의)

## 🔄 Work Flow Process
### For GitHub Copilot Users:
1. Read this guide ← YOU ARE HERE
2. Study relevant docs in docs/ folder
3. Check existing code in src/ folder  
4. Write/modify code following standards

API 문서 및 모듈 사양서

각 모듈별로 인터페이스 명세서를 작성:

% daq_controller.m API Reference
function handles = initializeDAQ(handles, config)
    % Purpose: Initialize DAQ hardware with specified configuration
    % Input: handles struct, config struct from AppConstants
    % Output: Updated handles with DAQ session
    % Dependencies: Data Acquisition Toolbox
    % Error Handling: Returns error code in handles.status
end

---

🔄 3단계: 작업 관리 시스템 구축

첫 번째 시행착오: Markdown 관리의 한계

처음에는 로컬 하드디스크에 markdown 파일로 작업 리스트를 관리했습니다.

- [ ] RA-1: 개발 환경 구축
- [ ] RA-2: AppConstants 시스템
- [ ] RA-3: 메인 UI 프레임워크
- ...

문제점 발생:

• Copilot이 markdown 파일을 무시하고 자체 판단으로 작업
• 한 시간 동안 시키지도 않은 고급 기능 구현 삽질
• 작업 우선순위와 실제 구현이 따로 놀음

"아, 이렇게 하면 안 되겠구나..."

해결책: Jira 프로젝트 구축

개인 Jira 서버에 RA(Recording & Analysis) 프로젝트를 생성하고:

티켓 구조:

RA-1: 개발 환경 및 문서 구축 (Story Points: 5)
├── 상태: 완료
├── 담당자: Claude
└── 의존성: None

RA-2: AppConstants.m 시스템 구축 (Story Points: 3)  
├── 상태: 완료
├── 담당자: Claude
└── 의존성: RA-1

RA-3: 메인 UI 프레임워크 (Story Points: 8)
├── 상태: 완료  
├── 담당자: Claude
└── 의존성: RA-2
...

Confluence 문서화 시스템

각 모듈별로 기술 문서 작성:

• 원본 코드 분석
• 리팩토링 전략
• 구현 상세사항
• 테스트 방법

---

⚡ 4단계: 실제 구현과 예상치 못한 효과들

Claude MCP의 파워

MCP(Model Context Protocol)로 Claude가 하드디스크 파일에 직접 접근하니까:

장점들:

• 파일 구조 실시간 생성/수정
• 기존 코드 분석 후 즉시 리팩토링
• 여러 파일 간 일관성 유지
• 중간 저장 없이 연속 작업

예상 외 효과:

23:30 작업 중단 → 잠자러 감
07:00 작업 재개 → "continue RA-5" 한 마디로 즉시 재개

Copilot의 역할 재정의

초기 삽질 이후 역할을 명확히 했습니다:

Before: 자유롭게 창의적 구현 After: 가이드라인 내에서 세부 구현만

결과:

• 일관된 코딩 스타일
• 예측 가능한 구현 패턴
• 유지보수 용이한 코드

Jira + Confluence 조합의 마법

작업을 티켓 단위로 관리하니까:

연속성 보장:

새 Claude 세션 시작
→ "resume-project D:\Git\RMD\RA" 
→ Jira 상태 자동 로드
→ 마지막 작업 지점부터 재개

품질 관리:

• 각 티켓 완료 시 리뷰 프로세스
• Confluence에 기술 문서 업데이트
• 다음 작업자를 위한 인수인계 자료

---

📊 현재 상황: 예상을 뛰어넘는 효율성

진행 현황 (실시간)

✅ RA-1: 개발 환경 구축 (완료)
✅ RA-2: AppConstants 시스템 (완료)  
✅ RA-3: 메인 UI 프레임워크 (완료)
✅ RA-4: DAQ 컨트롤러 (완료)
✅ RA-5: 트리거 시스템 (완료)
🔄 RA-6: 실시간 데이터 표시 (대기)
🔄 RA-7: 통합 테스트 (92% 완료)

전체 진도율: 85%

놀라운 시간 효율성

• 예상 소요 시간: 5일 (40시간)
• 실제 소요 시간: 5시간만에 85% 달성!
• 효율성 향상: 800% (이 글을 쓰는 시점 기준)

하지만 여기서 중요한 건: 단순한 시간 단축이 아닙니다.

---

🎯 핵심 인사이트: 기획이 모든 것을 결정한다

성공 요인 분석

1. 철저한 사전 기획 (80%의 시간 투자)

전체 작업 시간 분배:
├── 기획 및 문서화: 40%
├── 가이드라인 작성: 40%  
├── 실제 구현: 15%
└── 테스트 및 검증: 5%

교훈: AI를 활용할수록 기획이 더 중요해진다

2. 명확한 역할 분담

• 인간: 전략, 우선순위, 품질 기준
• Claude: 구조 설계, 문서화, 복잡한 로직
• Copilot: 반복적 구현, 세부 코딩

3. 연속성 보장 시스템

중단 → 재개 시간: 5분 이내
기존 방식: 30분-1시간 (컨텍스트 파악)

예상치 못한 부가 효과들

1. 문서화 품질 향상

AI가 작성한 문서들이 오히려 더 체계적:

• 일관된 형식
• 빠뜨린 부분 없음
• 지속적 업데이트

2. 코드 품질 향상

가이드라인을 철저히 따르니까:

• 하드코딩 제거율 100%
• 에러 핸들링 누락률 0%
• 주석 커버리지 90% 이상

3. 학습 효과

AI와 협업하면서 자연스럽게:

• 더 나은 기획 방법론 습득
• 체계적 사고 방식 향상
• 문서화 습관 개선

---

🔍 현실적인 한계와 해결 방안

현실적인 한계들

1. MCP 권한 지옥: 해놓고 잘 수는 없다

가장 귀찮은 현실적 문제가 바로 이거였습니다.

MCP(Model Context Protocol)의 현실:

Claude: "파일을 수정하겠습니다"
시스템: [권한 승인 요청]
나: [승인 클릭]

Claude: "다른 파일도 수정하겠습니다"  
시스템: [권한 승인 요청]
나: [또 승인 클릭]

(이 패턴이 수십 번 반복...)

결과:

• 30분마다 한 번씩 깨워짐
• "해놓고 잠자기" 불가능
• 지속적인 모니터링 필요

아직은 완전 자동화된 AI 협업은 어렵습니다.

2. 컨텍스트 제한과 해결책

Claude의 현실적 한계:

• 긴 대화 후 컨텍스트 소진
• "5시간 후에 봐요 오빠~" 하고 가버림 😅
• 세션 재시작 시 컨텍스트 손실

게임 체인저: GitHub Copilot Pro 무제한 혜택 운 좋게도 6월 3일까지 GitHub Copilot Pro에서 무제한 컨텍스트 제공:

• Claude Sonnet 4 ↔ Claude 3.5 교대 사용
• 컨텍스트 걱정 없이 긴 작업 가능
• 이것이 5시간 만에 85% 달성의 핵심!

Claude Sonnet 4 (복잡한 로직) 
    ↓ 컨텍스트 한계 도달
Claude 3.5 (단순 구현)
    ↓ 컨텍스트 한계 도달  
Claude Sonnet 4 (다시 복잡한 작업)

이 혜택 없었다면: 아마 3-4배 더 오래 걸렸을 것

3. 여전히 인간이 필요한 영역

창의적 판단

AI: "이 방법과 이 방법 중 어느 것이 좋을까요?"
인간: "이 프로젝트의 목적상 A 방법을 선택하자"

2. 실제 환경 테스트

• 하드웨어 연동 확인
• 사용자 시나리오 검증
• 성능 병목 지점 발견

3. 비즈니스 맥락 이해

• 왜 이 기능이 필요한가?
• 사용자가 실제로 원하는 것은?
• 우선순위 결정의 근거는?

겪었던 실제 문제들과 해결책

문제 1: MCP 권한 승인의 연속성 문제

상황: 30분마다 권한 승인으로 작업 중단 해결: 작업을 더 작은 단위로 분할, 승인 피로도 최소화

문제 2: AI들 간의 소통 단절

상황: Claude는 A 방식으로, Copilot은 B 방식으로 구현 해결: 더 상세한 가이드라인과 예제 코드 제공

문제 3: 컨텍스트 손실

상황: 세션 재시작 시 이전 작업 내용 기억 못함
해결: Jira 티켓에 상세한 진행 상황 기록

문제 4: 과도한 최적화

상황: AI가 필요 이상으로 복잡한 구조 제안 해결: "Simple is Better" 원칙을 가이드라인에 명시

---

🚀 확장 가능성과 응용 분야

다른 프로젝트에 적용 가능한 패턴

1. 레거시 시스템 마이그레이션

• 대용량 코드베이스 분석
• 점진적 리팩토링 계획
• 자동화된 문서화

2. 데이터 분석 프로젝트

• 복잡한 데이터 파이프라인 구축
• 반복적 분석 작업 자동화
• 결과 보고서 자동 생성

3. 문서 작업 프로젝트

• 대량 기술 문서 작성
• 다국어 번역 및 현지화
• 일관된 스타일 가이드 적용

개발자가 아닌 분들에게도...

업무 프로세스 자동화

기획서 작성 → AI가 구조화된 문서 생성
데이터 분석 → AI가 차트와 인사이트 제공  
보고서 작성 → AI가 템플릿 기반 자동 작성

학습 프로젝트 관리

• 개인 스터디 계획 수립
• 진도 관리 및 점검
• 학습 자료 정리 및 요약

---

💡 실무자를 위한 구현 가이드

시작하기 전 체크리스트

□ 명확한 목표 설정 (무엇을, 언제까지, 어떤 품질로)
□ 사용 가능한 AI 도구 파악 (Claude, ChatGPT, Copilot 등)
□ 작업 관리 도구 준비 (Jira, Notion, Linear 등)
□ 문서화 플랫폼 선택 (Confluence, Notion, GitBook 등)
□ 기본 프로세스 설계 (역할 분담, 품질 기준, 리뷰 방법)

단계별 구현 방법

Phase 1: 기반 구축 (전체 시간의 50%)

1. 프로젝트 분해: 큰 작업을 작은 단위로
2. 가이드라인 작성: AI가 따라야 할 규칙 정의
3. 템플릿 준비: 반복 작업을 위한 템플릿
4. 품질 기준 설정: 완료 조건 명확화

Phase 2: 파일럿 테스트 (20%)

1. 작은 모듈부터: 리스크가 낮은 부분 먼저
2. 문제점 파악: 예상치 못한 이슈들 발견
3. 프로세스 개선: 발견된 문제점 해결
4. 가이드라인 보완: 부족한 부분 추가

Phase 3: 본격 실행 (25%)

1. 병렬 작업: 여러 AI 도구 동시 활용
2. 지속적 모니터링: 품질과 진도 체크
3. 중간 점검: 방향성 재확인
4. 유연한 조정: 필요시 계획 수정

Phase 4: 검증 및 마무리 (5%)

1. 통합 테스트: 전체 시스템 동작 확인
2. 품질 검증: 설정한 기준 달성 여부
3. 문서 정리: 향후 유지보수를 위한 자료
4. 교훈 정리: 다음 프로젝트를 위한 인사이트

---

🎯 결론: 새로운 협업 패러다임

이 실험에서 얻은 핵심 교훈

1. AI는 도구가 아니라 팀원이다

기존 관점: "AI한테 시켜서 결과물 받기" 새로운 관점: "AI와 함께 문제 해결하기"

2. 기획이 곧 생산성이다

• 체계적인 기획 = AI 효율성 극대화
• 명확한 가이드라인 = 일관된 결과물
• 지속적 문서화 = 연속성 보장

3. 인간의 역할은 더 중요해진다

AI가 발전할수록:

• 전략적 사고의 중요성 증가
• 품질 기준 설정 능력 필요
• 창의적 문제 해결 역량 요구

앞으로의 가능성

단기적 효과

• 개인 생산성 2-3배 향상
• 반복 작업 자동화
• 문서화 품질 개선

장기적 변화

• 1인 기업의 경쟁력 향상
• 소규모 팀의 대형 프로젝트 수행 가능
• 새로운 직업군 등장 (AI 협업 전문가)

누구나 시작할 수 있는 첫 걸음

1. 작은 프로젝트부터: 일주일 내 완료 가능한 작업
2. 명확한 목표 설정: 무엇을, 언제까지, 어떻게
3. 단순한 도구부터: ChatGPT + 노션 조합으로 시작
4. 점진적 확장: 성공 경험을 바탕으로 시스템 고도화

---

📈 에pilogue: 진행 중인 실험

이 글을 쓰는 지금도 RA 프로젝트는 진행 중입니다.

• 현재 진도: 85% 완료
• 예상 완료: 내일(5/29) 오후
• 최종 결과: 실시간 업데이트 예정

가장 중요한 깨달음:

"AI와의 협업에서 성공의 핵심은 기술이 아니라 기획이다"

여러분도 한 번 시도해보시기 바랍니다. 단, 충분한 계획을 세우고 시작하세요.

---

"미래는 AI가 인간을 대체하는 것이 아니라, AI와 협업하는 인간이 그렇지 않은 인간을 대체하는 것이다."

---

📊 부록: 실제 데이터 및 도구

사용된 도구 스택

• AI 플랫폼: Claude 3.5 Sonnet (MCP), GitHub Copilot Pro Plus
• 프로젝트 관리: Self-hosted Jira
• 문서화: Self-hosted Confluence
• 개발 환경: MATLAB R2023b, VSCode
• 버전 관리: Git

프로젝트 통계 (5시간 작업 기준)

• 총 코드 라인: 8,000줄 → 6,500줄 (리팩토링으로 20% 축소)
• 모듈 수: 1개 → 7개 독립적 모듈
• 문서 페이지: 15개 (Confluence)
• Jira 티켓: 7개 (완료 5개, 진행 2개)
• 실제 작업 시간: 5시간 (85% 완료)
• MCP 권한 승인: 약 40회 (평균 7.5분마다 1회)
•  

특별한 조건들

• GitHub Copilot Pro 무제한 컨텍스트 (6월 3일까지 한정)
• Claude Sonnet 4 ↔ 3.5 모델 로테이션 활용
• MCP 실시간 파일 접근 (권한 승인 필요)

중요한 인프라: 무제한 컨텍스트의 힘

이 실험이 성공할 수 있었던 숨겨진 핵심 요소:

GitHub Copilot Pro 무제한 혜택 (6월 3일까지)

• 일반적인 상황: Claude 대화 몇 시간 후 컨텍스트 소진
• 현재 상황: 무제한 컨텍스트로 연속 작업 가능
• 모델 로테이션: Sonnet 4 ↔ 3.5 번갈아가며 최적 활용

이것이 없었다면:

예상 시나리오:
2시간 작업 → 컨텍스트 소진 → 재시작 → 컨텍스트 복구 30분
→ 1시간 작업 → 또 소진 → 재시작 → 복구...

실제 결과: 5시간 연속 작업으로 85% 달성! 🚀

이 혜택 종료 후에는 작업 방식을 다시 조정해야 할 것 같습니다.

이 실험은 현재진행형이며, 실제 진행 상황을 바탕으로 작성되었습니다.