AI 기반 개발 프로젝트의 복잡도 관리와 생존 전략

문서 성격: AI 개발 프로젝트 진행 시 발생하는 복잡도 증가, 문서화, 인수인계, AI 무한 수정 루프 방지에 대한 종합 가이드 대상: AI 개발자, PM, 팀 리더 (초보~경력) 핵심 문제: 프로젝트가 커질수록 AI의 컨텍스트 붕괴, 무한 수정 루프, 문서-코드 불일치, 인수인계 실패 최종 갱신: 2026-07-08

0. 서론: 왜 AI 프로젝트는 점점 더 어려워지는가?

AI 개발 프로젝트는 초기에는 빠르게 진행되지만, 파일 수가 늘고 소스 라인이 증가할수록 급격히 복잡도가 증가합니다. 이는 다음과 같은 이유 때문입니다:

핵심 통찰: "AI는 강력하지만, 기억력이 짧고 자기 절제가 없다." 따라서 인간이 구조를 설계하고 AI는 그 구조 내에서만 움직이도록 해야 합니다.

1. 프로젝트 복잡도 증가에 따른 3단계 대응 전략

1-1. Phase 1: 초기 단계 (파일 10개 미만, 라인 1,000줄 미만)

1-2. Phase 2: 중간 단계 (파일 10~50개, 라인 1,000~10,000줄)

1-3. Phase 3: 고도화 단계 (파일 50개 이상, 라인 10,000줄 이상)

2. AI 무한 수정 루프 방지 전략

2-1. 루프의 원인

[기획] → [AI 개발] → [수동 테스트] → [버그 발견] → [AI 수정] ↓ [새 버그 발생] ↓ [다시 수정 요청] ↓ (무한 반복)

text

2-2. 해결책: "중간 검증 게이트" 도입

2-3. AI 수정 제한 규칙 (CLAUDE.md에 명시)

## AI 수정 제한 규칙 (필수)

1. **삭제 금지**: 기존 코드를 삭제하지 말고, 반드시 `// DEPRECATED` 주석으로 표시
2. **변경 전 백업**: 수정 전 항상 `cp -r` 백업 실행
3. **영향도 분석 필수**: 수정 전 "이 변경이 영향을 미치는 파일 목록"을 먼저 보고
4. **점진적 수정**: 한 번에 1개 파일만 수정하고 테스트
5. **롤백 준비**: 수정 후 5분 내에 이전 상태로 복구 가능해야 함
3. 문서화 전략: "Living Documentation" 구축
3-1. 문서의 3가지 유형과 목적
문서 유형   목적  작성 주체   업데이트 주기
설계 문서 (AGENTS.md, system.md)    AI에게 프로젝트 구조를 알려줌   PM/리더   변경 시 즉시
운영 문서 (manual.md)   인간 운영자를 위한 매뉴얼  개발자 기능 추가 시
자동 생성 문서 (Swagger, JSDoc)   AI와 인간 모두 참조    AI + 도구 코드 변경 시 자동
3-2. 문서-코드 동기화 파이프라인
text
[코드 변경]
    │
    ▼
[CI/CD] 자동 실행
    ├── AI가 변경사항 분석 → CHANGELOG.md 자동 생성
    ├── API 문서(Swagger) 자동 갱신
    ├── JSDoc/PHPDoc 추출 → 위키 자동 업데이트
    └── 변경 영향도 리포트 생성 (Slack/이메일 전송)
3-3. 인수인계 문서 체크리스트
markdown
# 인수인계 문서 체크리스트

## 1. 시스템 개요
- [ ] 프로젝트 목적 및 범위
- [ ] 전체 아키텍처 다이어그램
- [ ] 기술 스택 및 버전 명세

## 2. 개발 환경
- [ ] 로컬 개발 환경 구축 방법
- [ ] 환경 변수 목록 (.env 예시)
- [ ] 의존성 설치 명령어

## 3. 배포 및 운영
- [ ] 배포 파이프라인 설명 (CI/CD)
- [ ] 서버 구성도 (인프라)
- [ ] 모니터링/알림 설정
- [ ] 백업 및 복구 절차

## 4. 유지보수
- [ ] 주요 비즈니스 로직 설명
- [ ] 자주 발생하는 이슈와 해결 방법
- [ ] 외부 의존성 (API, DB) 목록

## 5. 연락처
- [ ] 담당자 목록
- [ ] 외부 협력사 연락처
4. 서버 구조 변경 시 대응 전략
4-1. 변경 사항 문서화 프로세스
text
1. 변경 제안 → 2. 영향도 분석 → 3. 승인 → 4. 구현 → 5. 문서 업데이트 → 6. 검증
실제 적용 예시:

bash
# 1. 변경 제안 (Slack/이슈 트래커)
"API 엔드포인트를 /v1/order → /v2/order로 변경하려고 합니다."

# 2. 영향도 분석 (AI가 자동 생성)
claude "현재 코드베이스에서 /v1/order를 사용하는 모든 파일과 함수를 찾아줘."

# 3. 승인 (PM/리더)
# 4. 구현 (AI가 코드 수정)

# 5. 문서 업데이트 (AI가 자동)
claude "변경된 API 스펙을 기반으로 Swagger 문서를 업데이트해줘."

# 6. 검증 (테스트 통과 확인)
4-2. 버전 관리 전략 (마이그레이션 파일)
sql
-- database/migrations/v1_to_v2_order_api.sql
-- 변경 내용: /v1/order → /v2/order
-- 롤백 방법: 아래 주석 처리된 코드 실행

-- 업그레이드
ALTER TABLE orders RENAME TO orders_v1;
CREATE TABLE orders ( ... new schema ... );

-- 롤백 (문제 발생 시 실행)
-- DROP TABLE orders;
-- ALTER TABLE orders_v1 RENAME TO orders;
5. AI 컨텍스트 관리 고급 전략
5-1. 계층형 컨텍스트 구조
text
🌍 글로벌 계층 (항상 로드)
    ~/.hermes/SOUL.md        # 전역 페르소나
    ~/.hermes/MEMORY.md      # 글로벌 메모리 ([global] 태그)
        │
        ▼
📁 프로젝트 계층 (프로젝트 진입 시 로드)
    AGENTS.md                # 프로젝트 구조, 규칙
    system.md                # 아키텍처 상세
        │
        ▼
📂 모듈 계층 (해당 디렉토리 진입 시 추가 로드)
    src/backend/AGENTS.md    # 백엔드 규칙
    src/frontend/AGENTS.md   # 프론트엔드 규칙
        │
        ▼
📄 파일 계층 (파일 열람 시 헤더 주석 참조)
    /**
     * [AI_DEV_MODE] api/order.php
     * [목적] 주문 처리 API
     * [연관] api/inventory.php, db/order.sql
     */
5-2. 컨텍스트 토큰 최적화
최적화 기법  효과  적용 방법
태그 기반 필터링   불필요한 메모리 제외 MEMORY.md에 [project:xxx] 태그 사용
모듈별 분리  세션당 5,000토큰 절약  모듈별 AGENTS.md로 분리
요약 캐싱   반복 설명 방지    AI가 이해한 내용을 SUMMARY.md로 저장
코드 스니펫 참조   전체 파일 대신 핵심만 전달 "이 함수만 봐줘" 방식
6. AI 과잉 수정 방지: 작업 범위 제한
6-1. "작업 패키지" 개념 도입
AI에게 한 번에 허용되는 작업 범위를 물리적으로 제한합니다:

markdown
## 작업 패키지 #123: 주문 API 리팩토링

### 허용 범위
- 수정 가능 파일: `/api/order.php`, `/api/order_test.php`
- 수정 금지 파일: `/api/inventory.php`, `/database/schema.sql`
- 의존성 확인 필요: `/api/payment.php` (변경 시 통보)

### 제한 조건
- 1회 수정당 변경 라인 50줄 이내
- 삭제 금지 (대신 주석 처리)
- 수정 후 반드시 `phpunit tests/OrderTest.php` 실행

### 롤백 계획
- 문제 발생 시 `git revert`로 즉시 복구
6-2. AI에게 "생각하게 하기" (Chain of Thought)
markdown
## AI 수정 요청 시 필수 질문 (프롬프트 템플릿)

"다음 변경을 수행하기 전에:

1. 이 변경이 영향을 미치는 파일은 무엇인가?
2. 기존 기능이 중단될 위험이 있는가?
3. 이 변경을 되돌리려면 어떻게 해야 하는가?
4. 테스트는 어떻게 할 것인가?

위 질문에 대한 답변을 먼저 작성하고, 변경을 시작하세요."
7. 복잡도 관리 도구 스택
도구  용도  비용
Git + GitHub    소스 버전 관리, PR 리뷰 무료
Dependabot  의존성 자동 업데이트 무료 (GitHub)
Swagger/OpenAPI API 문서 자동 생성    오픈소스
JSDoc/PHPDoc    코드 내 문서화    오픈소스
Sentry  에러 모니터링 무료 티어
Logtail 로그 중앙화  무료 티어
Mermaid 다이어그램 자동 생성 오픈소스
mkdocs  정적 문서 사이트   오픈소스
8. 실전 가이드: 프로젝트 단계별 복잡도 관리
8-1. 0~2주: 기획 및 초기 개발
액션  도구/방법
프로젝트 구조 설계  AGENTS.md, system.md, design.md 작성
개발 환경 구축    VS Code + Hermes + Claude Code
기본 CI/CD 설정 GitHub Actions (자동 테스트)
문서 템플릿 생성   README.md, CONTRIBUTING.md
8-2. 3~8주: 핵심 기능 개발
액션  도구/방법
모듈별 AGENTS.md 분리    각 디렉토리에 규칙 파일 추가
API 문서 자동화  Swagger 도입
테스트 커버리지 70% 목표 PHPUnit/Jest
변경 이력 자동 기록 CHANGELOG.md 자동 생성 (AI)
8-3. 9~12주: 통합 및 최적화
액션  도구/방법
전체 영향도 분석   AI가 변경 전 영향도 리포트 생성
성능 테스트  k6, Lighthouse
보안 감사   AI + Snyk
인수인계 문서 완성  Living Documentation
9. 결론: AI 개발자 생존 수칙
번호  수칙  설명
1   문서를 코드보다 먼저 코드 수정 전에 문서를 먼저 업데이트하라
2   AI에게 범위를 정해줘라   "전체를 수정해" 하지 말고 "이 함수만 수정해" 하라
3   다른 모델로 검증하라 Claude가 작성했으면 Gemini/DeepSeek로 리뷰하라
4   변경은 점진적으로   한 번에 1개 파일, 50줄 이내로 제한하라
5   롤백을 항상 준비하라 수정 전에 git branch와 백업을 생성하라
6   자동화된 문서화를 구축하라  수동 문서는 결국 구버전이 된다
7   AI의 과신을 경계하라    AI가 "완벽해요"라고 해도 직접 테스트하라
8   인수인계를 처음부터 준비하라 프로젝트 시작부터 인수인계 문서를 함께 작성하라
🎯 최종 메시지: "AI는 강력한 도구이지만, 구조를 잡고 방향을 제시하는 것은 인간의 몫입니다. 문서화는 선택이 아닌 필수이며, 복잡도 관리는 생존의 조건입니다."

부록: 추천 문서 템플릿 모음
🔹 AGENTS.md (프로젝트 루트)
markdown
# 프로젝트명: [프로젝트명]

## 프로젝트 개요
- 목적: [프로젝트 목적]
- 기술 스택: [언어/프레임워크/DB]

## 디렉토리 구조
/src/ # 소스 코드
/tests/ # 테스트 코드
/docs/ # 문서

text

## AI 수정 제한 규칙
1. 기존 코드 삭제 금지
2. 1회 수정당 50줄 이내
3. 수정 전 영향도 분석 필수
🔹 system.md (아키텍처)
markdown
# 시스템 아키텍처

## 전체 구성도
[다이어그램 - Mermaid 사용]

## 데이터 흐름
[데이터 흐름 설명]

## 의존성 그래프
[모듈 간 의존성 목록]
🔹 CHANGELOG.md (변경 이력)
markdown
# Changelog

## [v1.2.0] - 2026-07-08
### Added
- 주문 취소 API 추가
### Fixed
- 재고 차감 버그 수정
### Changed
- API 응답 포맷 통일