AI 기반 개발 완전 정복: 나의 실전 워크플로우 & 협업 철학
문서 성격: AI 개발 프로젝트를 진행하며 쌓은 실전 노하우의 총결산 핵심 내용: 헤더 기반 컨텍스트 관리, 메인+보조 AI 협업 구조, 문서 최소화 전략, 테스트 시스템화 과제 목적: 이제 이 방식으로 교육하고, 팀에 전파하고, 모든 프로젝트에 적용한다. 최종 갱신: 2026-07-08
0. 내가 발견한 AI 개발의 3대 원칙
| 원칙 | 내용 |
|---|---|
| ① 헤더 우선주의 | PRD보다 헤더. 문서는 나중에, 헤더는 지금. |
| ② 메인+보조 구조 | 메인 AI(Claude)는 만들고, 보조 AI(Gemini/DeepSeek)는 감시하고 검증한다. |
| ③ 문서화 최소화 | 관리 포인트를 늘리지 말고, 소스 코드 헤더에 모든 정보를 녹여라. |
1. 헤더 기반 컨텍스트 관리 시스템
1-1. 핵심 철학
"MD 문서는 선택적 컨텍스트, 소스 헤더는 강제적 컨텍스트. AI가 무조건 보는 헤더에 모든 걸 담아라."
1-2. 표준 헤더 템플릿 (5줄)
/**
* [AI_MODE] 파일명 - 역할 - v버전 (날짜)
* [목적] 이 파일이 존재하는 이유 (한 줄)
* [핵심] 주요 함수/흐름 (3~5개 키워드)
* [연관] 의존 파일/API/테이블 (쉼표 구분)
* [변경] 최근 수정 이력 (날짜-내용)
*/
1-3. 적용 효과
효과 설명
강제 컨텍스트 AI가 파일을 읽으면 헤더를 무조건 보게 됨
자기 동기화 코드 수정 시 함께 갱신되어 문서-코드 불일치 해소
인수인계 용이 파일만 봐도 역할/의존성/이력을 바로 파악
관리 비용 제로 별도 문서 관리 불필요
1-4. 실천 규칙
신규 파일 생성 시: 헤더 템플릿을 붙여넣고 시작
파일 수정 시: 헤더의 [변경] 항목에 변경사항 추가
AI 요청 시: 작업 전 헤더를 먼저 읽도록 지시
코드 리뷰 시: 헤더가 최신 상태인지 함께 확인
2. 메인 + 보조 AI 협업 구조
2-1. 협업 아키텍처
text
┌─────────────────────────────────────────────────────────────────────────┐
│ AI 협업 구조 (완성형) │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 🧠 메인 개발 AI (Claude Opus) │
│ ├── 역할: 설계, 아키텍처, 핵심 코드 생성 │
│ ├── 특징: 가장 뛰어난 추론 능력, 자기 코드에 대한 편향 존재 │
│ └── 한계: 자신이 만든 코드의 문제를 스스로 발견하지 못함 │
│ │
│ 👀 보조 AI (Gemini / DeepSeek / Codex) │
│ ├── 역할: 감시, 체크, 크로스체크, 테스트 생성, 보안 검증 │
│ ├── 특징: 다른 관점에서 바라보는 "제3자" 역할 │
│ └── 목적: 메인 AI의 맹점을 발견하고 보완 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2-2. 모델별 역할 분담
모델 역할 담당 업무
Claude Opus 메인 개발 설계, 아키텍처, 복잡한 로직 구현, 최종 검토
Codex 보조 개발 단일 파일 구현, 반복 작업, CI/CD 스크립트
Gemini QA/감시 보안 취약점, 크로스체크, 엣지 케이스 분석
DeepSeek 테스트/대량 처리 테스트 코드 생성, 일괄 작업, 스캐폴딩
Kimi K2 문서/초안 장문 기술 문서, 메뉴얼 초안 작성
2-3. 보조 AI 감시 체크리스트
보조 AI에게 요청할 감시 항목:
markdown
🔍 보조 AI 감시 영역
1. 보안 취약점 (SQL Injection, XSS, 인증 우회)
2. 성능 병목 (N+1 쿼리, 메모리 누수, 캐시 누락)
3. 코드 일관성 (코딩 스타일, 패턴, 헤더 포맷)
4. 테스트 커버리지 (누락된 테스트, 엣지 케이스)
5. 영향도 분석 (변경이 다른 파일에 미치는 영향)
3. 실전 개발 워크플로우
3-1. 전체 프로세스 (순환형)
text
[시작] 서버 구조 정의 (파일 설명)
↓
[설계] 사이트맵 + 서비스 흐름도
↓
📌 [핵심] 헤더 작성 ([AI_MODE] + 목적 + 핵심 + 연관 + 변경)
↓
┌─────────────────────────────────────────────────────────────┐
│ 🔄 개발 루프 (완성될 때까지 반복) │
│ │
│ 🧠 메인 AI (Claude) → 코드 생성 │
│ ↓ │
│ 👀 보조 AI (Gemini) → 보안/QA 크로스체크 │
│ ↓ │
│ 👀 보조 AI (DeepSeek) → 테스트 생성 │
│ ↓ │
│ 🔧 내가 검토 + 헤더 업데이트 │
│ ↓ │
│ (부족하면 루프 반복) │
└─────────────────────────────────────────────────────────────┘
↓
[완료] ZIP 압축 (스냅샷 저장)
↓
[UI] 디자인 개선 (안 이쁘면 수정)
↓
(다시 루프 또는 배포)
3-2. 실제 프롬프트 템플릿
메인 AI 요청
markdown
"api/order.php 파일을 수정하려고 해.
헤더의 [목적]과 [핵심]을 먼저 읽고, [연관]된 파일들의 영향을 고려해줘.
수정 후에는 헤더의 [변경]에 변경사항을 기록해줘."
보조 AI 감시 요청
markdown
"내가 작성한 코드를 다른 관점에서 검토해줘.
1. 보안 취약점이 있는가?
2. 성능 문제가 있을 수 있는가?
3. 코딩 스타일이 일관성 있는가?
4. 누락된 테스트는 없는가?
5. 이 변경이 다른 파일에 영향을 미칠 수 있는가?
발견한 문제가 있으면 구체적으로 지적해주고, 해결 방안을 제시해줘."
3-3. 스냅샷 저장 (ZIP)
bash
# 일정 수준 개발 완료 시 전체 압축
zip -r project_backup_$(date +%Y%m%d_%H%M).zip . -x "*.git*" "*.env" "config.php"
4. 아직 해결하지 못한 과제: 자동 테스트 시스템화
4-1. 현재 상태
text
내가 지금 하는 테스트:
├── 기능이 동작하는지 직접 클릭
├── 콘솔에 에러가 없는지 확인
├── 모바일에서 깨지는지 확인
└── (이게 전부다...)
4-2. 목표
text
내가 만들고 싶은 것:
┌─────────────────────────────────────────────────────────────┐
│ 🤖 AI 기반 자동 테스트 시스템 │
│ │
│ 1. 변경사항이 생기면 AI가 자동으로 테스트 시나리오 생성 │
│ 2. 전체 서비스에 대한 통합 테스트 실행 │
│ 3. 실패 시 원인 분석 및 수정 제안 │
│ 4. CI/CD에 통합되어 배포 전 자동 검증 │
└─────────────────────────────────────────────────────────────┘
4-3. 접근 방안 (단계적)
단계 내용 상태
1단계 AI가 단위 테스트 코드 자동 생성 🟡 진행 중
2단계 생성된 테스트 CI/CD 자동 실행 🔴 미시작
3단계 통합(E2E) 테스트 자동화 🔴 미시작
4단계 AI가 테스트 결과 분석 및 수정 제안 🔴 미시작
5. 일관된 AI 협업을 위한 문서 구조
5-1. 최소 문서 세트
파일 용도 업데이트 주기
CLAUDE.md 프로젝트 공통 규칙, AI 협업 가이드 변경 시
system.md 전체 시스템 아키텍처 주요 변경 시
CHANGELOG.md 버전별 변경 이력 배포 시
소스 헤더 파일별 상세 정보 파일 수정 시마다
5-2. 문서보다 헤더에 집중하는 이유
text
📄 문서의 함정:
문서가 많아질수록 관리가 안 되고, 방향성을 잃는다.
PRD → 설계 → 가이드 → 매뉴얼 → ... (무한 증가)
✅ 헤더의 강점:
파일 하나에 모든 정보를 5줄로 담는다.
AI가 무조건 보게 되고, 코드와 함께 갱신된다.
6. 전체 시스템 다이어그램
text
┌─────────────────────────────────────────────────────────────────────────────────┐
│ AI 개발 완전 정복 시스템 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 📁 프로젝트 루트 │
│ ├── CLAUDE.md # 공통 규칙 │
│ ├── system.md # 아키텍처 │
│ ├── CHANGELOG.md # 변경 이력 │
│ ├── api/ # API 로직 │
│ │ └── order.php # [AI_MODE] 헤더 포함 │
│ ├── admin/ # 관리자 페이지 │
│ │ └── ai_archive.php # [AI_MODE] 헤더 포함 │
│ └── ... │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ AI 협업 계층 │ │
│ │ │ │
│ │ 🧠 메인 AI (Claude) │ │
│ │ ├── 설계 + 핵심 구현 │ │
│ │ └── 출력: 코드 생성 + 헤더 업데이트 │ │
│ │ │ │
│ │ 👀 보조 AI (Gemini) │ │
│ │ ├── 보안 검증 + QA 크로스체크 │ │
│ │ └── 출력: 취약점 리포트 + 개선 제안 │ │
│ │ │ │
│ │ 👀 보조 AI (DeepSeek) │ │
│ │ ├── 테스트 생성 + 대량 처리 │ │
│ │ └── 출력: 테스트 코드 + 실행 결과 │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 🔄 개발 루프 = 메인 생성 → 보조 감시 → 내가 검토 → 헤더 업데이트 → 반복 │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
7. 교육 및 팀 전파를 위한 핵심 포인트
7-1. 신규 팀원이 반드시 숙지해야 할 5가지
번호 내용
1 헤더를 먼저 써라 - 파일 생성 시 헤더 템플릿부터 붙여넣기
2 메인+보조를 기억하라 - Claude로 만들고, Gemini로 검증하라
3 문서를 늘리지 마라 - 헤더로 충분하다, 별도 문서는 최소화
4 변경은 헤더에 기록하라 - 수정할 때마다 [변경] 항목 추가
5 ZIP으로 스냅샷을 남겨라 - 어느 정도 완성되면 전체를 압축 보관
7-2. 첫 프로젝트 진행 시 체크리스트
text
[ ] 서버 구조 정의 (디렉토리 및 파일 설명)
[ ] 사이트맵 + 서비스 흐름도 작성
[ ] 핵심 파일 헤더 작성 ([AI_MODE] 5줄)
[ ] 메인 AI로 첫 기능 개발
[ ] 보조 AI로 검증 및 테스트
[ ] 헤더 업데이트 및 변경 기록
[ ] ZIP 스냅샷 저장
[ ] UI 점검 및 개선
[ ] (반복)
8. 결론: 이제 이 방식으로 간다
"AI와의 개발은 문서가 아니라 헤더로 한다.
메인 AI가 만들고, 보조 AI가 감시한다.
이 구조가 완성되면, 어떤 프로젝트라도 방향성을 잃지 않는다.
이제 이 방식으로 교육하고, 팀에 전파하고, 모든 프로젝트에 적용한다."
부록: 빠른 참조 카드
헤더 템플릿 (복사용)
php
/**
* [AI_MODE] 파일명 - 역할 - v버전 (날짜)
* [목적] 이 파일이 존재하는 이유
* [핵심] 주요 함수/흐름
* [연관] 의존 파일/API/테이블
* [변경] 최근 수정 이력
*/
AI 협업 요청 템플릿
markdown
# 메인 AI 요청
"헤더를 먼저 읽고, [연관] 파일을 고려해서 작업해줘."
# 보조 AI 감시 요청
"보안, 성능, 일관성, 테스트, 영향도 순으로 검토해줘."
필수 명령어
bash
# 스냅샷 저장
zip -r backup_$(date +%Y%m%d).zip . -x "*.git*" "*.env" "config.php"
# 헤더 검증
grep -r "AI_MODE" --include="*.php" --include="*.py" .
댓글 0