Claude Code vs Codex: 8만 줄 Python/TypeScript 프로젝트 실전 비교 분석

서론

8만 줄짜리 프로덕션 코드베이스에 새로운 인증 시스템을 도입해야 한다고 상상해보자. 마이크로서비스 아키텍처에 Python FastAPI 백엔드와 TypeScript Next.js 프론트엔드가 얽혀있고, 건드리면 안 되는 레거시 로직이 곳곳에 숨어있다. 이런 환경에서 AI 코딩 에이전트에게 “인증 로직을 JWT에서 OAuth2.0으로 마이그레이션해줘"라고 맡길 수 있을까?

14년 차 시니어 엔지니어가 실제로 이 실험을 수행했다. Claude Code(Opus 4.6)와 Codex(GPT-5.4)라는 두 최신 코딩 에이전트를 동일한 대규모 프로젝트에 투입하고, 각각 약 100시간과 20시간의 실전 작업을 통해 성능과 한계를 비교했다. 이 실험은 벤치마크 점수가 아닌 실제 개발자의 체감 생산성을 기준으로 삼았다는 점에서 의미가 깊다.

코딩 에이전트 시장은 2025년 들어 폭발적으로 성장했다. GitHub Copilot의 코드 완성을 넘어, 자율적으로 코드를 작성하고 리팩토링하며 테스트까지 수행하는 “에이전트” 세대가 도래했다. 하지만 데모 영상과 실전 사이의 간극은 여전히 크다. 이 글에서는 두 에이전트의 아키텍처적 차이를 분석하고, 대규모 코드베이스에서 어떤 전략을 취해야 하는지 실무 관점에서 논의한다.

코딩 에이전트의 아키텍처 비교

동작 원리: ReAct vs 코드 생성

Claude Code와 Codex는 근본적으로 다른 접근 방식을 취한다. Claude Code는 대화형 ReAct(Reasoning + Acting) 루프 기반이다. 터미널에서 실행되며, 파일 시스템에 직접 접근하고, 사용자와 실시간으로 상호작용하면서 작업을 수행한다. 중간에 “이 파일은 수정하지 마세요"라는 지시를 즉시 전달할 수 있다.

반면 Codex는 비동기 배치 처리 모델이다. 클라우드 샌드박스에서 실행되며, 작업을 큐에 제출하면 백그라운드에서 완료된다. 사용자는 다른 작업을 수행하다가 결과를 받아볼 수 있다. 이 차이는 대규모 프로젝트에서 치명적인 트레이드오프를 만든다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
graph LR
    A[사용자 작업 지시] --> B[Claude Code]
    A --> C[Codex]
    B --> D[터미널 내 직접 실행]
    D --> E[실시간 파일 수정]
    E --> F[즉각 피드백 루프]
    F --> G[사용자 개입 가능]
    C --> H[클라우드 샌드박스]
    H --> I[비동기 배치 처리]
    I --> J[완료 후 결과 반환]
    J --> K[후검토만 가능]

컨텍스트 관리 전략의 차이

대규모 코드베이스에서 가장 중요한 요소는 컨텍스트 윈도우 관리다. 8만 줄 프로젝트는 어떤 LLM의 컨텍스트 윈도우에도 한 번에 들어가지 않는다. 두 에이전트는 서로 다른 전략으로 이 문제에 접근한다.

Claude Code는 필요한 파일을 동적으로 탐색한다. grep, find, 파일 읽기를 통해 작업에 필요한 컨텍스트를 실시간으로 수집한다. 이는 빠르지만, 탐색이 불충분하면 중요한 의존성을 놓칠 위험이 있다.

Codex는 사전에 정의된 저장소 인덱싱을 활용한다. 전체 코드베이스를 사전에 분석하여 관련 파일을 자동으로 식별한다. 초기 설정 시간이 필요하지만, 한번 구축되면 더 일관된 컨텍스트를 유지한다.

실전 성능 비교 분석

체감 시간 기반 작업 완료 비교

원본 리뷰에서 가장 주목할 만한 점은 시간 차이다. Claude Code는 약 100시간, Codex는 약 20시간이 소요되었다. 하지만 이 단순 비교는 오해의 소지가 있다.

Claude Code의 치명적 문제점

실전에서 Claude Code는 몇 가지 심각한 문제를 보였다. 첫째, 지시 무시다. “이 파일은 수정하지 마세요"라는 명시적 지시를 무시하고 핵심 설정 파일을 덮어쓰는 경우가 빈번했다. 이는 Claude의 instruction following 능력이 코드 생성 능도에 비해 상대적으로 약하다는 것을 시사한다.

둘째, 작업 미완료 문제다. 복잡한 리팩토링 작업의 경우, 중간에 “이 작업은 너무 복잡합니다"라고 선언하고 포기하거나, 부분적으로만 완료한 채 종료하는 현상이 관찰되었다.

셋째, 기존 파일 훼손이다. 동적으로 파일을 수정하는 과정에서 기존에 정상 작동하던 코드를 의도치 않게 망가뜨리는 경우가 있었다. 이는 로컬 파일 시스템에 직접 쓰기 권한이 있다는 아키텍처적 특성에서 기인한다.

Codex의 안정성 우위

Codex는 상대적으로 안정적인 성능을 보였다. 클라우드 샌드박스에서 실행되기 때문에 로컬 파일 시스템에 직접적인 영향을 주지 않으며, 작업 완료 후 결과를 검토하고 승인하는 워크플로우를 제공한다.

하지만 Codex에도 한계는 있다. 디버깅이 어렵고, 중간 과정에서 개입할 수 없으며, 실시간 피드백이 불가능하다. 특히 복잡한 아키텍처 결정이 필요한 작업에서는 대화형 접근이 더 유리할 수 있다.

실전 적용 가이드: 안전한 코딩 에이전트 활용법

Step-by-Step: 안전한 워크플로우 구축

코딩 에이전트를 프로덕션 환경에서 안전하게 사용하려면 체계적인 가드레일이 필요하다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# coding_agent_guardrail.py
import os
import hashlib
import subprocess
from pathlib import Path
from dataclasses import dataclass, field
from typing import List, Optional
import json
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("AgentGuardrail")

@dataclass
class FileSnapshot:
    """파일 상태 스냅샷 - 변경 감지용"""
    path: str
    original_hash: str
    original_content: str

@dataclass 
class AgentWorkspace:
    """코딩 에이전트 안전 작업 공간"""
    project_root: str
    protected_paths: List[str] = field(default_factory=list)
    snapshots: dict = field(default_factory=dict)
    
    def __post_init__(self):
        self.protected_paths = [
            os.path.abspath(p) for p in self.protected_paths
        ]
    
    def is_protected(self, file_path: str) -> bool:
        """보호 대상 파일인지 확인"""
        abs_path = os.path.abspath(file_path)
        for protected in self.protected_paths:
            if abs_path.startswith(protected):
                return True
        return False
    
    def snapshot_file(self, file_path: str) -> None:
        """파일 스냅샷 생성"""
        abs_path = os.path.abspath(file_path)
        if not os.path.exists(abs_path):
            return
        
        content = Path(abs_path).read_text(encoding='utf-8')
        file_hash = hashlib.sha256(content.encode()).hexdigest()
        
        self.snapshots[abs_path] = FileSnapshot(
            path=abs_path,
            original_hash=file_hash,
            original_content=content
        )
        logger.info(f"Snapshot created: {abs_path}")
    
    def verify_integrity(self, file_path: str) -> dict:
        """파일 무결성 검증"""
        abs_path = os.path.abspath(file_path)
        
        if abs_path not in self.snapshots:
            return {"status": "unknown", "message": "No snapshot exists"}
        
        snapshot = self.snapshots[abs_path]
        current_content = Path(abs_path).read_text(encoding='utf-8')
        current_hash = hashlib.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
sha256(
            current_content.encode()
        ).hexdigest()
        
        if current_hash == snapshot.original_hash:
            return {"status": "unchanged", "message": "File intact"}
        
        return {
            "status": "modified",
            "message": "File has been modified",
            "original_hash": snapshot.original_hash,
            "current_hash": current_hash
        }
    
    def rollback(self, file_path: str) -> bool:
        """파일 롤백"""
        abs_path = os.path.abspath(file_path)
        
        if abs_path not in self.snapshots:
            logger.warning(f"No snapshot for {abs_path}")
            return False
        
        snapshot = self.snapshots[abs_path]
        Path(abs_path).write_text(
            snapshot.original_content, encoding='utf-8'
        )
        logger.info(f"Rolled back: {abs_path}")
        return True
    
    def safe_execute(
        self,
        task_description: str,
        target_files: List[str],
        agent_command: str,
        dry_run: bool = True
    ) -> dict:
        """안전한 에이전트 실행 래퍼"""
        # 1. 보호 파일 검사
        for f in target_files:
            if self.is_protected(f):
                return {
                    "status": "blocked",
                    "message": f"Protected file: {f}"
                }
        
        # 2. 스냅샷 생성
        for f in target_files:
            self.snapshot_file(f)
        
        if dry_run:
            return {
                "status": "dry_run",
                "message": "Snapshots created, no execution"
            }
        
        # 3. 에이전트 실행
        try:
            result = subprocess.run(
                agent_command,
                shell=True,
                capture_output=True,
                text=True,
                timeout=600  # 10분 타임아웃
            )
            
            # 4. 실행 후 무결성 검증
            integrity_report = {}
            for f in target_files:
                integrity_report[f] = self.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
verify_integrity(f)
            
            # 5. 보호 파일 변경 감지 시 자동 롤백
            violations = [
                f for f, report in integrity_report.items()
                if report["status"] == "modified" and self.is_protected(f)
            ]
            
            if violations:
                for v in violations:
                    self.rollback(v)
                return {
                    "status": "violation",
                    "rolled_back": violations,
                    "agent_output": result.stdout
                }
            
            return {
                "status": "success",
                "integrity": integrity_report,
                "agent_output": result.stdout
            }
            
        except subprocess.TimeoutExpired:
            return {"status": "timeout", "message": "Agent timed out"}
        except Exception as e:
            return {"status": "error", "message": str(e)}

# 사용 예시
if __name__ == "__main__":
    workspace = AgentWorkspace(
        project_root="/path/to/project",
        protected_paths=[
            "/path/to/project/config/",
            "/path/to/project/.env",
            "/path/to/project/core/auth.py"
        ]
    )
    
    # 작업 전 스냅샷 생성
    target_files = [
        "src/api/routes.py",
        "src/services/user_service.py",
        "tests/test_routes.py"
    ]
    
    result = workspace.safe_execute(
        task_description="OAuth2.0 마이그레이션",
        target_files=target_files,
        agent_command='claude-code "Migrate auth to OAuth2.0"',
        dry_run=True
    )
    
    print(json.dumps(result, indent=2, ensure_ascii=False))

에이전트 선택 의사결정 프레임워크

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
graph TD
    A[작업 요청] --> B{작업 복잡도}
    B -->|단순 반복| C[Claude Code]
    B -->|복잡 리팩토링| D{안전 요구사항}
    B -->|아키텍처 변경| E{리스크 수준}
    D -->|낮음| C
    D -->|높음| F[Codex]
    E -->|낮음| C
    E -->|높음| F
    C --> G[실시간 모니터링]
    F --> H[사후 코드 리뷰]
    G --> I[수동 검증]
    H --> I

작업 유형별 최적 에이전트 선택

출처: https://news.hada.io/topic?id=28538