DEV Community: TreeSoop

업무 자동화 시스템을 연구부터 운영까지 책임지는 전문팀이 설계하는 방법

TreeSoop — Fri, 03 Jul 2026 10:41:03 +0000

업무 자동화 시스템이 PoC 단계에서 멈추는 가장 흔한 이유는 연구 팀과 개발 팀이 따로 존재하기 때문이다. 리서치에서 나온 모델이 프로덕션 파이프라인과 분리되는 순간, 유지보수 비용이 두 배가 되고 개선 사이클이 느려진다. 나무숲이 단일 팀으로 연구부터 운영까지 가져가는 이유가 바로 여기에 있다.

리서치와 프로덕션 개발을 단일 시스템으로 묶는 기술적 아키텍처

리서치 코드와 서비스 코드를 처음부터 같은 레포지토리 구조 안에서 설계하면 두 가지가 달라진다. 배포 파이프라인이 실험 브랜치를 직접 스테이징 환경으로 올릴 수 있고, 모델 버저닝이 API 버저닝과 동기화된다.

일반적인 분리 구조는 이렇다.

research/
  experiments/      # Jupyter, wandb 실험 로그
  models/           # 훈련된 모델 아티팩트
service/
  api/              # FastAPI 엔드포인트
  workers/          # Celery 태스크

이 구조의 문제는 research/models에서 검증된 가중치가 service/api로 넘어오는 시점에 수동 개입이 필요하다는 점이다. 파일을 복사하거나, 경로를 하드코딩하거나, 담당자가 직접 배포 스크립트를 수정한다. 이 수동 구간이 곧 버그 발생 지점이다.

단일 시스템 아키텍처는 이 구간을 없앤다.

pipeline/
  research/
    train.py         # DVC 파이프라인 정의
    evaluate.py
  serve/
    app.py           # FastAPI + MLflow 모델 레지스트리 참조
  shared/
    schema.py        # Pydantic 스키마 — 연구·서빙 양쪽이 동일하게 사용
    config.py        # 환경 분리 없이 단일 설정 파일

핵심은 shared/schema.py다. 연구 단계에서 정의한 입출력 스키마를 서빙 레이어가 그대로 참조한다. Pydantic으로 스키마를 강제하면, 모델 입력 형식이 바뀔 때 서빙 코드가 컴파일 시점에 실패한다. 런타임 오류가 아니라 타입 오류로 잡힌다.

모델 등록과 불러오기는 MLflow Model Registry로 표준화한다.

# serve/app.py
import mlflow.pyfunc
from shared.schema import InferenceRequest, InferenceResponse

model = mlflow.pyfunc.load_model("models:/document-classifier/Production")

@app.post("/predict", response_model=InferenceResponse)
def predict(req: InferenceRequest):
    return model.predict(req.dict())

"models:/document-classifier/Production" 문자열 하나가 모델 버전과 서빙 코드 사이의 계약이다. 연구 팀이 새 버전을 Staging으로 올리면 CI가 평가 지표를 체크하고, 통과하면 자동으로 Production으로 승격된다.

POSTECH·KAIST·서울대 출신 기술진이 설계하는 에이전트 협업 파이프라인

단일 에이전트로 복잡한 업무를 처리하려 하면 컨텍스트 윈도우 한계와 오류 전파 문제가 생긴다. 하나의 에이전트가 긴 작업을 전담할 때, 중간 단계 오류가 하류 전체에 쌓인다. 에이전트 협업 파이프라인은 이 문제를 오케스트레이터-워커 구조로 분리해 푼다.

아래가 우리 팀이 실제 업무 자동화 시스템에서 쓰는 기본 패턴이다.

# agents/orchestrator.py
from agents.worker import DocumentExtractor, Validator, Reporter

class OrchestratorAgent:
    def __init__(self):
        self.extractor = DocumentExtractor()
        self.validator = Validator()
        self.reporter = Reporter()

    def run(self, document_path: str) -> dict:
        raw = self.extractor.extract(document_path)       # 1단계: 추출
        validated = self.validator.validate(raw)           # 2단계: 검증
        return self.reporter.generate(validated)           # 3단계: 보고

각 워커는 단일 책임을 갖는다. DocumentExtractor는 OCR이나 파서로 원시 데이터를 뽑는 일만 한다. Validator는 스키마 검증과 비즈니스 룰 체크만 한다. Reporter는 최종 출력 형식화만 맡는다.

오케스트레이터는 흐름만 제어한다. 각 단계의 실패는 독립적으로 처리되고, 재시도 로직은 워커 레벨에 있다.

에이전트 간 메시지 포맷은 엄격하게 정의한다.

# shared/schema.py
from pydantic import BaseModel
from typing import Optional

class ExtractionResult(BaseModel):
    document_id: str
    content: dict
    confidence: float
    error: Optional[str] = None

class ValidationResult(BaseModel):
    document_id: str
    is_valid: bool
    issues: list[str]
    corrected_content: Optional[dict] = None

confidence와 error 필드가 있는 이유는 부분 실패를 표현하기 위해서다. 에이전트가 실패했을 때 파이프라인 전체를 멈추는 대신, 오케스트레이터가 is_valid: False인 결과를 모아 별도 검토 큐로 보낸다. 사람이 개입해야 하는 케이스와 자동 처리 가능한 케이스를 분리하는 것이 실제 운영 자동화의 핵심이다.

비동기 처리가 필요한 규모에서는 Celery와 Redis를 결합한다.

# workers/tasks.py
from celery import Celery

app = Celery('tasks', broker='redis://localhost:6379/0')

@app.task(bind=True, max_retries=3)
def process_document(self, document_path: str):
    try:
        orchestrator = OrchestratorAgent()
        return orchestrator.run(document_path)
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)

max_retries=3, countdown=60은 일시적 외부 API 실패를 흡수한다. 세 번 실패한 태스크는 Dead Letter Queue로 들어가고 알림이 발송된다.

학술 자산을 구현 가능한 시스템으로 전환하는 설계 원칙

논문에 있는 알고리즘을 프로덕션에 올리는 작업은, 논문을 이해하는 것과 구현하는 것이 완전히 다른 문제라는 데서 시작해야 한다.

논문에서 프로덕션으로 넘어올 때 자주 빠지는 함정은 아래 네 가지다.

배치 추론 가정 문제: 논문은 오프라인 배치를 가정하는 경우가 많다. 실시간 API로 서빙하려면 레이턴시 요구사항에 맞게 모델을 재설계해야 한다.
데이터 분포 차이: 논문의 벤치마크 데이터셋과 실제 운영 데이터의 분포가 다르다. 도메인 파인튜닝 없이 곧바로 배포하면 정확도가 논문 수치보다 낮게 나온다.
의존성 버전 충돌: requirements.txt에 버전이 명시되지 않은 리서치 코드는 환경을 다시 만들기 어렵다. Docker 이미지에 CUDA 버전까지 고정해야 재현 가능하다.
모니터링 부재: 모델 드리프트를 감지하는 파이프라인 없이 배포하면, 정확도 저하를 사용자 불만으로 처음 알게 된다.

나무숲 팀이 오픈소스로 공개한 리포지토리들(★120+)은 이 전환 과정을 문서화한 결과물이기도 하다. 논문 구현과 서빙 코드를 같은 레포에 두고, README에 재현 방법과 배포 방법을 함께 적는 것이 우리 팀의 기본 방식이다.

모델 드리프트 감지는 Evidently AI로 구현할 수 있다.

# monitoring/drift_check.py
from evidently.report import Report
from evidently.metric_preset import DataDriftPreset

def check_drift(reference_data, current_data):
    report = Report(metrics=[DataDriftPreset()])
    report.run(reference_data=reference_data, current_data=current_data)
    results = report.as_dict()
    return results["metrics"][0]["result"]["dataset_drift"]

드리프트가 감지되면 재훈련 파이프라인을 트리거하거나 알림을 보낸다. 운영 중인 시스템이 스스로 상태를 보고하는 구조다.

오픈소스 기여 방식이 기술 검증 수단인 이유는?

비공개 포트폴리오는 외부에서 검증할 수 없다. NDA로 묶인 프로젝트 결과물을 "우리가 잘 만들었다"고 말하는 것과, 코드를 공개하고 커뮤니티에서 별을 받는 것은 다른 종류의 신뢰다.

★120+ 스타는 단순한 숫자가 아니다. 다른 개발자가 코드를 보고, 실제로 써보고, 유용하다고 판단했다는 의미다. 코드 품질과 문서화 수준이 외부에서 검증된 상태다.

기술 담당자가 파트너를 고를 때 오픈소스 기여 이력이 유효한 근거가 되는 구조는 이렇다.

검증 수단	확인 가능한 것	확인 불가능한 것
비공개 포트폴리오	결과물 스크린샷, 고객사 이름	코드 품질, 설계 결정, 실제 구현 수준
오픈소스 리포지토리	코드 구조, 문서화, 커밋 히스토리, 테스트 커버리지	비즈니스 컨텍스트
오픈소스 + 스타 수	위에 더해 커뮤니티 검증 여부	—

CTO나 기술 리드가 파트너를 평가할 때, GitHub 링크 하나가 미팅 한 번보다 더 많은 정보를 준다. 코드를 직접 보면 추상화 수준, 테스트 작성 방식, 의존성 관리 방식을 한 번에 확인할 수 있다.

자주 묻는 질문

업무 자동화 시스템 구축에 필요한 최소 요구사항은 무엇인가요?

자동화할 업무 프로세스의 입출력이 명확하게 정의되어 있어야 한다. "복잡한 판단이 필요한 작업"은 자동화 가능하지만, 판단 기준이 문서화되지 않은 경우 먼저 규칙 정의 작업이 선행되어야 한다. 데이터 접근 권한과 내부 시스템 API 여부도 초기에 확인한다.

에이전트 파이프라인과 단순 API 연동의 차이는 무엇인가요?

단순 API 연동은 고정된 흐름을 실행한다. 에이전트 파이프라인은 중간 상태를 판단하고 분기할 수 있다. 예외 케이스를 사람 검토 큐로 보내거나, 신뢰도가 낮은 결과를 재처리하는 로직이 파이프라인 수준에서 설계된다. 이 차이가 운영 안정성을 결정한다.

리서치 단계 결과물이 프로덕션에 그대로 올라가지 않는 이유는 무엇인가요?

리서치 코드는 재현 가능성을 목표로 작성되고, 프로덕션 코드는 안정성과 레이턴시를 목표로 작성된다. 배치 처리 가정, 의존성 버전 고정, 에러 핸들링 방식이 다르다. 단일 팀이 두 단계를 모두 담당할 때 이 전환 비용이 가장 낮다.

오픈소스로 공개한 코드가 기업 프로젝트에서도 그대로 적용되나요?

오픈소스 코드는 일반화된 패턴을 담는다. 기업 프로젝트는 도메인 데이터, 내부 시스템 연동, 보안 요구사항에 맞게 커스터마이징된다. 공개 리포지토리는 설계 철학과 구현 방식의 레퍼런스이고, 실제 프로젝트는 그 위에 구체적인 요구사항을 얹는 작업이다.

착수부터 운영까지 어떤 구조로 진행되나요?

초기 2주 동안 요구사항 정의와 아키텍처 설계를 완료한다. 이후 스프린트 단위로 워커 에이전트를 순서대로 구현하고, 스테이징 환경에서 실제 데이터로 검증한다. 모니터링 파이프라인을 포함한 상태로 프로덕션에 배포하고, 이후 드리프트 감지와 성능 유지를 지속 운영한다.

연구부터 운영까지 한 팀이 책임지는 구조는 선택의 문제가 아니라 설계 결정이다. 아키텍처 수준에서 리서치와 서빙을 분리하지 않고, 에이전트 협업 파이프라인을 명확한 스키마로 강제하며, 오픈소스로 코드를 공개해 외부 검증을 쌓는 것이 나무숲이 일하는 방식이다. 기술 구조를 직접 확인하고 싶다면 GitHub 리포지토리를 먼저 보고, 구체적인 시스템 요구사항은 기술 상담으로 이야기하자.

더 보기: treesoop.com

AI 개발 외주를 맡길 때, 왜 '한 팀'이어야 하는가

TreeSoop — Fri, 03 Jul 2026 10:40:19 +0000

리서치 결과물이 실제 제품이 되는 과정에서 가장 많이 무너지는 지점은 팀이 바뀌는 순간이다. 논문을 읽고 PoC를 만든 팀과 그 결과물을 실서비스로 옮기는 팀이 다르면, 기술 판단의 맥락이 사라진다. 나무숲은 그 단절을 없애는 방식으로 일한다. 연구부터 배포까지 같은 팀이, 처음 잡은 구조 그대로 끝까지 가져간다.

리서치와 실서비스 사이에서 어떤 문제가 생기는가?

리서치 단계와 운영 단계 사이에는 대개 이런 단절이 있다.

맥락 손실: PoC에서 특정 모델을 선택한 이유, 학습 데이터의 전처리 결정, 실패한 접근법의 이유가 문서화되지 않은 채 다음 팀에 넘어간다.
재현 불가: 논문 재현 코드는 실험 환경(GPU 사양, 라이브러리 버전, 데이터 형식)에 강하게 의존한다. 새 팀이 이를 처음부터 파악하는 데만 수 주가 걸린다.
요구사항 번역 오류: "정밀도 0.92 이상"이라는 연구 지표가 실제 서비스에서 어떤 사용자 경험으로 이어지는지, 이 번역을 잘못 하면 모델 성능 자체가 무의미해진다.
운영 요건 반영 실패: 실서비스는 응답 지연(latency), 비용, 배포 환경이 연구 환경과 다르다. 뒤늦게 이를 반영하려면 아키텍처를 다시 설계해야 한다.

가장 흔한 패턴은 이렇다. 외주 업체 A가 리서치를 마쳤다. 그 결과물을 인수한 외주 업체 B가 "이 코드는 우리가 처음부터 다시 써야 합니다"라고 한다. 발주처는 이미 리서치 비용을 지불했다. 이 문제는 기술력의 문제가 아니라 구조의 문제다.

POSTECH·KAIST·서울대 출신 엔지니어들이 논문 기술을 제품으로 옮기는 방법

논문을 읽을 수 있는 것과 그 안의 기법을 실제 제품에 쓸 수 있는 것은 다른 능력이다. 나무숲 엔지니어들이 논문 기반 기술을 구현할 때 따르는 흐름은 대략 이렇다.

1단계 — 재현 가능한 실험 환경 고정

논문 재현의 첫 단계는 환경을 코드로 고정하는 것이다. 라이브러리 버전, 시드값, 데이터 전처리 파이프라인을 처음부터 버전 관리한다. 실험 관리에는 MLflow 같은 오픈소스 도구를 활용해 각 실험의 파라미터와 결과를 추적한다.

# 실험 환경 고정 예시
pip freeze > requirements.txt
git tag experiment/baseline-v1
mlflow run . --experiment-name "paper_repro_baseline"

2단계 — 서비스 제약을 리서치 단계에 미리 반영

응답 속도, 비용, 배포 환경은 연구 단계부터 제약 조건으로 다룬다. 예를 들어 Transformer 기반 모델을 도입할 때, GPU 추론 비용이 허용 범위를 넘으면 ONNX Runtime이나 quantization 적용 가능성을 리서치 단계에서 함께 검토한다.

3단계 — PoC 코드를 서비스 코드로 전환하는 기준 명시

PoC 단계가 끝날 때 "이 코드의 어느 부분이 서비스 코드로 그대로 가고, 어느 부분이 다시 써야 하는가"를 명시적으로 판단한다. 이 판단이 없으면 PoC 코드가 그대로 프로덕션에 들어가거나, 반대로 멀쩡한 코드를 처음부터 다시 쓰는 낭비가 생긴다.

이 흐름이 유지되는 이유는 단순하다. 리서치를 한 사람이 서비스 구현도 맡기 때문에, 무엇을 지키고 무엇을 바꿔야 하는지 판단할 수 있다. 나무숲의 에이전틱 AI 서비스처럼 여러 모델이 협업하는 복잡한 시스템일수록 이 연속성이 더 중요해진다.

처음부터 끝까지 한 팀이 맡으면 개발 속도가 어떻게 달라지는가?

단절 없는 개발이 속도에 영향을 주는 구체적인 이유가 있다.

컨텍스트 전달 비용이 사라진다. 팀이 바뀌면 새 팀은 결정의 이유가 아니라 결과물만 본다. 왜 이 구조를 선택했는지, 어떤 접근법을 먼저 시도했다가 포기했는지를 파악하는 데 시간이 든다. 같은 팀이 계속 가져가면 이 비용이 없다.

재작업 범위가 줄어든다. 리서치 단계에서 서비스 제약을 이미 반영했기 때문에, 배포 직전에 "이 아키텍처로는 latency를 맞출 수 없다"는 결론이 나오는 경우가 드물다.

전원이 같은 AI 개발 환경을 표준으로 사용한다. 나무숲 팀원 전원은 Claude Code Max를 기본 개발 환경으로 쓴다. 코드 리뷰, 문서 작성, 테스트 케이스 생성 모두 동일한 도구 위에서 진행한다. 이 표준화 덕분에 팀 내 속도 편차가 작고, 신규 태스크 착수 시간도 단축된다.

아래는 팀 규모와 개발 방식에 따른 일반적인 속도 차이를 보여주는 비교 프레임이다. 특정 숫자를 보장하는 표가 아니라, 구조적 차이를 이해하기 위한 참고 프레임이다.

구분	팀 분리 방식 (리서치 팀 → 구현 팀)	한 팀 연속 방식
컨텍스트 전달	별도 인수인계 필요	없음
서비스 제약 반영 시점	구현 단계 시작 후	리서치 단계부터
아키텍처 재설계 빈도	높음	낮음
착수 기준	인수인계 완료 후	리서치와 동시
책임 경계	팀 간 분산	단일 팀

대형 SI 업체가 2~6개월 걸려 착수하는 프로젝트를 나무숲이 2주 안에 시작할 수 있는 구조적 이유가 여기 있다. 빠른 것이 아니라, 느리게 만드는 단계가 없는 것이다.

실제 운영 중인 포트폴리오 8선이 말해주는 것

나무숲이 운영 중인 AX 포트폴리오 8개 중 일부를 구조 관점에서 살펴보면 패턴이 보인다.

여행사 백오피스 자동화: 예약 데이터 수집부터 정산 처리까지 이어지는 흐름을 단일 파이프라인으로 구성했다. 여러 시스템을 잇는 에이전트 구조가 핵심이다. 이 구조는 리서치 단계에서 데이터 형식과 API 스펙을 미리 파악한 팀이 아니면 처음부터 설계하기 어렵다.

항공우주 견적 AI: 도면 파일에서 부품 정보를 추출하고 견적을 자동 생성하는 시스템이다. 컴퓨터 비전 모델과 도메인 특화 규칙 엔진이 결합된 구조로, 리서치에서 나온 모델을 운영 환경의 응답 속도 요건에 맞게 최적화하는 과정이 중요했다.

도면 부품 추출 AI: 기계 도면에서 부품 리스트를 자동 추출한다. OCR과 객체 탐지 모델을 결합하고, 도메인별 예외 처리 로직을 레이어로 쌓는 구조다. 이 레이어를 어디까지 모델로 처리하고 어디서부터 규칙 기반으로 넘길지 판단하는 것이 리서치와 구현 경험이 동시에 필요한 지점이다.

이 세 가지 사례의 공통점은 "모델 하나를 잘 쓰는 것"이 핵심이 아니라는 점이다. 도메인 데이터 이해, 운영 환경 제약, 예외 처리 로직이 모두 초기 설계에 반영되어야 했고, 그게 가능했던 이유는 리서치부터 배포까지 같은 팀이 판단했기 때문이다. AI 자동화 서비스에서 이런 아키텍처 접근 방식을 더 확인할 수 있다.

자주 묻는 질문

리서치 단계부터 외주를 맡기는 것이 비효율적이지 않은가?

리서치 단계를 외부에 맡기면 내부 노하우가 축적되지 않는다는 우려는 타당하다. 다만 리서치와 구현을 같은 팀에 맡기면, 리서치 결과가 실제 구현에 바로 반영된다. 리서치만 따로 맡기고 구현은 다른 팀에 주는 것이 오히려 비효율이다. 무엇을 내재화할지 판단하는 것이 먼저다.

논문 기반 기술을 실제 서비스에 적용할 때 가장 흔한 실패 원인은 무엇인가?

서비스 제약을 리서치 단계에 반영하지 않는 것이다. 정밀도, 재현율 같은 연구 지표만 보고 배포 단계에서야 latency나 비용 문제를 인식하면 아키텍처를 처음부터 다시 설계해야 한다. 이 문제는 리서치 팀과 구현 팀이 분리될 때 특히 자주 발생한다.

팀이 하나라도 도메인 전문성이 부족하면 어떻게 하는가?

도메인 지식은 대부분 발주처가 갖고 있다. 중요한 것은 그 지식을 빠르게 흡수해서 기술 판단에 반영하는 구조다. 나무숲은 리서치 단계부터 발주처와 긴밀하게 작업하며, 도메인 예외 케이스를 초기 설계에 반영하는 방식으로 접근한다.

착수 2주라는 기준은 어떤 조건을 전제하는가?

요구사항이 어느 정도 명확하고, 데이터 접근이 가능한 경우를 전제한다. 데이터 수집 자체가 리서치의 일부인 프로젝트는 착수 기준이 다르다. 첫 상담에서 이 조건을 명확히 확인하는 것이 나무숲의 기본 진행 방식이다.

오픈소스 자산(★120+)은 실제 프로젝트에 어떻게 활용되는가?

공개된 오픈소스 자산은 주로 반복 사용 가능한 파이프라인 컴포넌트와 실험 유틸리티다. 새 프로젝트에서 이미 검증된 컴포넌트를 재사용하면 처음부터 만드는 시간을 줄일 수 있다. 검증된 부분은 재사용하고, 새로운 판단이 필요한 부분에 집중하는 방식이다.

리서치 논문에 머물러 있는 기술을 실제 운영 가능한 제품으로 옮기려면, 그 전 과정을 하나의 팀이 책임지는 구조가 가장 빠르고 안전하다. 중간에 팀이 바뀌지 않기 때문에 기술 판단의 맥락이 유지되고, 운영 제약이 처음부터 설계에 반영된다. 연구 결과를 실제 고도화된 제품으로 바로 운영하고 싶다면 나무숲에 문의하세요.

더 보기: treesoop.com

LLM 파인튜닝 방법 비교: Full vs LoRA vs QLoRA 선택 가이드 2026

TreeSoop — Thu, 04 Jun 2026 11:39:19 +0000

LLM 파인튜닝은 GPT나 Claude 같은 사전학습 모델을 자사 데이터로 추가 학습시켜 특정 도메인에 맞게 특화하는 기술입니다. 그런데 "파인튜닝을 한다"는 말 안에는 사실 서로 다른 방법이 여러 개 숨어 있습니다. 모델의 모든 가중치를 다시 학습하는 Full Fine-tuning, 작은 어댑터 행렬만 학습하는 LoRA, 여기에 4비트 양자화를 더해 GPU 한 장에서도 돌리는 QLoRA가 대표적입니다. 어떤 방법을 고르느냐에 따라 필요한 GPU, 학습 비용, 품질, 운영 난이도가 적게는 두세 배에서 많게는 열 배까지 차이 납니다. 이 글은 "파인튜닝을 할지 말지"가 아니라 "어떤 파인튜닝 방법을 쓸지"에 초점을 맞춰, 세 가지 대표 방법을 GPU 메모리·학습 속도·품질·적합 데이터 규모 기준으로 비교하고 상황별 선택 기준을 정리했습니다.

파인튜닝 방법은 왜 하나가 아닐까?

2020년대 초만 해도 파인튜닝은 곧 Full Fine-tuning을 의미했습니다. 모델 전체를 자사 데이터로 다시 학습시키는 방식이죠. 그런데 모델 크기가 수십억~수천억 파라미터로 커지면서 문제가 생겼습니다. 7B(70억 파라미터) 모델 하나를 통째로 학습하려면 고가의 GPU 여러 장과 막대한 시간이 들어가고, 체크포인트를 저장할 때마다 모델 전체를 복사해야 합니다.

그래서 등장한 것이 PEFT(Parameter-Efficient Fine-Tuning, 파라미터 효율 파인튜닝) 계열입니다. 모델 가중치 대부분을 그대로 두고 아주 일부만 학습해서, 같은 효과를 훨씬 적은 자원으로 내는 접근입니다. LoRA와 QLoRA가 여기에 속합니다. 즉 오늘날 "파인튜닝 방법 선택"이란 사실상 전체를 학습할지(Full), 일부만 효율적으로 학습할지(PEFT) 를 고르는 문제에 가깝습니다.

Full Fine-tuning: 모델 전체를 다시 학습한다

Full Fine-tuning은 사전학습된 모델의 모든 가중치를 학습 대상으로 삼습니다. 이론적으로 표현력이 가장 크기 때문에, 베이스 모델과 도메인 차이가 매우 크거나(예: 특수 의료·법률 코퍼스) 데이터가 충분할 때 최고 품질을 낼 수 있습니다.

대가는 비용입니다. fp16 기준으로 7B 모델을 학습하려면 모델 가중치뿐 아니라 옵티마이저 상태와 그래디언트까지 메모리에 올려야 해서, 일반적으로 모델 크기의 수 배에 해당하는 GPU 메모리가 필요합니다. 데이터가 적을 때는 기존에 학습된 능력을 잊어버리는 카타스트로픽 포게팅(catastrophic forgetting) 위험도 큽니다.

적합한 상황: 데이터가 수만~수십만 샘플 이상, 대규모 GPU 확보 가능, 도메인이 베이스 모델과 크게 다름
피해야 할 상황: 데이터 수천 건 이하, 단일 GPU, 빠른 반복 실험이 필요한 초기 단계

LoRA: 작은 어댑터만 학습하는 효율적 방법

LoRA(Low-Rank Adaptation)는 원본 가중치를 동결(freeze) 해 두고, 각 레이어에 저랭크(low-rank) 행렬 두 개(A·B)만 새로 붙여 그것만 학습합니다. 학습 대상 파라미터가 전체의 0.1~1% 수준으로 줄어들어, 메모리와 시간이 크게 절감됩니다. 결과물도 원본 모델이 아니라 수 MB~수십 MB짜리 어댑터 파일로 저장되므로, 하나의 베이스 모델에 여러 어댑터를 갈아 끼우는 운용이 가능합니다. LoRA의 원리와 효과는 LoRA 논문(Hu et al., 2021)에 자세히 정리되어 있습니다.

적합한 상황: 중소 규모 데이터, 단일~소수 GPU, 여러 태스크용 어댑터를 따로 관리하고 싶을 때
장점: 빠른 실험 사이클, 작은 저장 용량, 베이스 모델 공유

QLoRA: 4비트 양자화로 GPU 한 장에서

QLoRA는 LoRA에 양자화(quantization) 를 결합한 방법입니다. 베이스 모델을 4비트(NF4)로 압축해 메모리에 올린 뒤, 그 위에서 LoRA 어댑터만 학습합니다. QLoRA 논문(Dettmers et al., 2023)에 따르면 65B 규모 모델도 단일 48GB GPU 한 장에서 파인튜닝하면서 품질 손실을 최소화할 수 있습니다.

덕분에 예산이 빠듯한 팀이나 큰 모델을 다뤄야 하는 상황에서 현실적인 선택지가 됩니다. 다만 4비트로 압축된 상태이므로, 추론 단계에서 양자화 방식과 속도·품질 트레이드오프를 별도로 점검해야 합니다.

적합한 상황: GPU 예산 제약, 큰 모델 파인튜닝, 개인·소규모 팀
주의: 추론 환경의 양자화 호환성과 지연시간 검증 필요

방법별 비교표: 한눈에 보는 차이

항목	Full Fine-tuning	LoRA	QLoRA
학습 파라미터 비율	100%	약 0.1~1%	약 0.1~1%
GPU 메모리(7B 기준)	매우 높음	중간	가장 낮음
학습 속도/비용	가장 높음	낮음	낮음
결과물 크기	모델 전체(수십 GB)	어댑터(수 MB~)	어댑터(수 MB~)
품질 상한	최고	높음(대부분 충분)	높음(약간의 양자화 영향)
적합 데이터 규모	대규모	중소~대규모	중소~대규모
운영 난이도	높음	낮음	중간

수치는 모델·세팅에 따라 달라지는 일반적인 경향이며, 실제 프로젝트에서는 베이스 모델과 데이터로 소규모 사전 실험을 돌려 확인하는 것이 가장 정확합니다.

내 상황에는 어떤 방법이 맞을까?

복잡해 보이지만 의사결정은 의외로 단순합니다.

데이터가 1만 건 미만이고 GPU가 한두 장뿐이다 → QLoRA로 시작하세요. 가장 적은 자원으로 결과를 빠르게 확인할 수 있습니다.
여러 도메인/고객사별로 다른 동작이 필요하다 → LoRA로 어댑터를 도메인별로 만들어 두고 교체해 쓰는 구조가 유리합니다.
데이터가 충분하고(수만 건+) 멀티 GPU가 있으며 마지막 한 방울의 품질까지 필요하다 → Full Fine-tuning을 검토하세요. 단, LoRA로도 목표 품질이 나오는 경우가 많으니 먼저 비교 실험을 권합니다.

2026년 현재 실무에서는 대부분의 프로젝트가 LoRA 또는 QLoRA로 시작합니다. Full Fine-tuning은 "정말 전체 학습이 필요하다"는 명확한 근거가 있을 때 선택하는 쪽으로 무게가 옮겨졌습니다.

파인튜닝을 시작하기 전, 정말 파인튜닝이 답일까?

방법을 고르기 전에 한 가지 더 짚을 게 있습니다. 풀고 싶은 문제가 "최신 정보를 정확히 검색해 답하기"라면 파인튜닝보다 RAG가 더 적합할 수 있고, 단순 말투·포맷 교정이라면 프롬프트 엔지니어링만으로 충분할 때도 많습니다. 이 갈림길은 LLM 파인튜닝 vs RAG 완전 가이드에서 의사결정 매트릭스로 정리해 두었습니다. 또한 방법별로 실제 들어가는 비용이 궁금하다면 LLM 파인튜닝 비용 가이드를 함께 참고하시면 좋습니다.

나무숲의 AI-Native 파인튜닝 접근

나무숲(TreeSoop)은 AI-Native Team으로, 팀원 전원이 Claude Code Max 플랜을 기본 개발 환경으로 사용하며 데이터 준비부터 학습·평가·배포까지 하나의 반복 루프로 묶어 진행합니다. 음성인식 같은 도메인 특화 모델을 다뤄 본 경험을 바탕으로, 무작정 Full Fine-tuning을 권하기보다 LoRA·QLoRA로 빠르게 베이스라인을 잡고 품질 목표를 검증한 뒤 필요한 만큼만 자원을 투입하는 방식을 선호합니다. 이런 단계적 접근은 나무숲의 AI-Native 개발 방식에서 일관되게 적용하는 원칙이기도 합니다.

LLM 파인튜닝이나 AI 모델 특화 개발 외주를 검토하고 계시다면 AI-Native 개발사 나무숲에 문의해보세요. 어떤 방법이 ROI 측면에서 합리적인지부터 함께 정리해 드립니다. (문의: 카카오톡 채널)

자주 묻는 질문

Q: LoRA와 QLoRA 중 무엇으로 시작해야 하나요?

GPU 메모리에 여유가 있다면 LoRA가 추론 단계에서 더 단순합니다. GPU가 한 장뿐이거나 모델이 커서 메모리가 부족하다면 QLoRA가 현실적인 선택입니다. 많은 팀이 QLoRA로 가능성을 먼저 검증한 뒤, 운영 단계에서 LoRA나 병합(merge) 방식으로 옮깁니다.

Q: 파인튜닝에 GPU가 꼭 여러 장 필요한가요?

아닙니다. Full Fine-tuning은 대형 GPU가 여러 장 필요할 수 있지만, QLoRA를 쓰면 모델 크기에 따라 GPU 한 장으로도 파인튜닝이 가능합니다. 이것이 PEFT 계열이 등장한 핵심 이유입니다.

Q: LoRA 어댑터를 여러 개 만들어 바꿔 쓸 수 있나요?

가능합니다. 하나의 베이스 모델을 공유하면서 고객사별·태스크별 어댑터를 따로 학습해 두고 상황에 맞게 교체하는 운용이 LoRA의 큰 장점입니다. 저장 용량도 어댑터당 수 MB~수십 MB로 가볍습니다.

Q: 파인튜닝하면 원래 모델의 일반 성능이 떨어지나요?

Full Fine-tuning에서 데이터가 적을 때 카타스트로픽 포게팅으로 일반 능력이 손상될 수 있습니다. LoRA·QLoRA는 원본 가중치를 동결하므로 이 위험이 상대적으로 작습니다. 그래서 데이터가 충분치 않을 때는 PEFT 계열이 더 안전한 선택입니다.

멀티 에이전트(Multi-agent) AI 시스템 가이드 2026 — 싱글 에이전트와 차이·도입 사례·외주 비용

TreeSoop — Tue, 02 Jun 2026 00:38:40 +0000

멀티 에이전트(Multi-agent) AI 시스템은 여러 AI 에이전트가 역할을 분담하고 서로 통신하면서 복잡한 업무를 자율적으로 처리하는 구조다. 한 에이전트가 처음부터 끝까지 처리하는 싱글 에이전트와 달리, 검색·분석·실행·검증을 각각 다른 에이전트가 병렬로 맡고 그 결과를 조율(orchestration)한다. 2026년 한국 기업 AI 도입은 단일 챗봇 단계를 지나, 다단계 의사결정과 도메인 특화 작업을 자동화하는 멀티 에이전트 단계로 이동 중이다. 이 글은 멀티 에이전트와 싱글 에이전트의 구조적 차이, 도입 비용·기간·실패 위험, 국내 도입 사례, 외주 발주 시 업체 선택 기준까지 발주 담당자가 의사결정에 바로 쓸 수 있는 비교표·체크리스트를 제공한다.

멀티 에이전트와 싱글 에이전트, 무엇이 다른가?

싱글 에이전트는 하나의 LLM 인스턴스가 도구(tool)를 직접 호출하면서 모든 단계를 처리한다. 작업 흐름이 선형적이고 컨텍스트가 한곳에 모이므로 구현이 단순하다. 반면 멀티 에이전트는 작업을 여러 하위 작업으로 쪼개고, 각 에이전트가 자기 역할(role)·시스템 프롬프트·도구 집합을 따로 가진 채 협업한다.

가장 흔한 패턴 세 가지를 정리하면 다음과 같다.

Supervisor 패턴: 상위 supervisor 에이전트가 작업을 받아 worker 에이전트들에게 분배하고 결과를 통합한다. 의사결정 라인이 명확해 디버깅이 쉽다.
Peer 패턴: 동등한 에이전트들이 메시지 큐로 정보를 주고받으며 합의(consensus)를 이룬다. 창의적 결과가 필요한 리서치·기획에 적합하다.
Hierarchical 패턴: supervisor 아래 sub-team을 두고, sub-team 안에서 다시 supervisor-worker 구조를 반복한다. 대규모 RPA·복합 업무 자동화에 쓰인다.

구분	싱글 에이전트	멀티 에이전트
적합한 작업	1~3단계 선형 작업	5단계 이상, 분기·검증 필요
컨텍스트 관리	단일 컨텍스트 윈도우	에이전트별 분리 + 공유 메모리
토큰 비용	낮음	1.8~3배 (병렬·검증 오버헤드)
구현 난이도	낮음	높음 (조율·실패 처리)
정확도	단순 작업에 충분	복잡 작업에서 10~25%p 향상
외주 비용(국내)	800만~3,000만 원	3,000만~1.2억 원
구축 기간	4~8주	10~16주

Anthropic의 멀티 에이전트 리서치 시스템 사례에서는 단일 Claude 에이전트 대비 멀티 에이전트 구조가 리서치 품질 평가에서 약 90% 더 높은 점수를 받았다. 다만 토큰 사용량은 약 15배로 늘어, 모든 작업에 멀티 에이전트가 정답은 아니라는 점도 같은 글에서 강조한다.

언제 멀티 에이전트가 필요한가? — 도입 판단 트리

발주 담당자가 자주 묻는 질문은 "우리 업무에 멀티 에이전트가 정말 필요한가"이다. 다음 네 가지 조건 중 두 개 이상에 해당하면 멀티 에이전트가 ROI를 만든다.

작업이 5단계 이상이고, 각 단계가 다른 전문성을 요구한다 — 예: 시장 리서치 → 경쟁사 분석 → 보고서 작성 → 사실 검증.
결과의 신뢰도가 비즈니스 결정에 직결된다 — 검증 에이전트(critic)를 두면 환각 비율이 의미 있게 떨어진다.
작업 분기(branching)가 데이터에 따라 동적으로 결정된다 — 단순 if/else로는 표현 어려운 휴리스틱 분기.
여러 외부 시스템(SaaS·DB·내부 API)을 동시에 다뤄야 한다 — 도구 권한을 에이전트별로 격리하면 보안 관리도 쉬워진다.

반대로 다음에 해당하면 멀티 에이전트는 과잉이다. 싱글 에이전트로 충분하다.

단순 FAQ 챗봇, 분류·태깅 같은 단발성 작업.
작업당 비용이 100원 미만이어야 하는 대규모 트래픽 환경.
인간 검수자(HITL)가 매번 결과를 확인하는 워크플로우 — 멀티 에이전트의 자율성이 오히려 검수 부담을 늘린다.

나무숲에서도 초기에는 모든 자동화를 싱글 에이전트로 구축했다가, 검증·분기·외부 API 호출이 동시에 일어나는 마케팅 자동화 파이프라인부터 멀티 에이전트로 재설계한 경험이 있다. 무조건 멀티 에이전트가 좋은 게 아니라, 위 네 조건을 충족한 영역만 옮긴 것이 비용·디버깅 측면에서 모두 유리했다.

멀티 에이전트 시스템 구축 비용·기간 — 한국 시장 실측

2026년 5월 기준 국내 외주 시장에서 멀티 에이전트 시스템을 발주할 때 받는 견적은 다음과 같다. 모두 PoC가 아닌 실제 운영(production) 시스템 기준이다.

규모	에이전트 수	비용	기간	운영 비용(월)
소형 PoC	2~3개	800만~2,000만 원	4~6주	30만~80만 원
부서 단위 자동화	3~5개	3,000만~6,000만 원	8~12주	80만~250만 원
전사 멀티 에이전트 플랫폼	5~10개+	6,000만~1.2억 원	12~16주	250만~800만 원
도메인 특화 + 학습	10개+ + 파인튜닝	1.2억~3억 원	16~24주	500만~2,000만 원

견적 변동 폭이 큰 이유는 다음 네 가지다.

LLM 토큰 비용: 멀티 에이전트는 검증·재시도 때문에 토큰 사용이 2~3배 늘어난다. Claude·GPT-4o·Gemini 중 어느 모델을 쓰느냐에 따라 월 운영비가 갈린다.
외부 도구 통합 개수: SaaS·DB·내부 API 통합이 늘어날 때마다 권한·인증·에러 처리가 비선형으로 증가한다.
평가(eval) 파이프라인의 깊이: production에 띄우려면 회귀 테스트 데이터셋과 평가 지표가 필요하다. 이 부분만으로도 전체 비용의 20~30%가 들어가는 경우가 많다.
인프라 형태: 클라우드 함수로 처리할지, 전용 워커 서버를 두는지에 따라 운영비가 다르다.

견적서를 받았을 때 위 네 항목이 명시되어 있지 않다면, 실제 운영 단계에서 추가 비용이 발생할 가능성이 높다고 보고 명확화를 요청해야 한다. 외주 의사결정 매트릭스와 견적 검증 기준의 더 깊은 논의는 Agentic AI 개발 완전 가이드 2026에서 확인할 수 있다.

한국 기업 도입 사례 3건

1. 금융사 컴플라이언스 리포트 자동화 (3개 에이전트)

내부 거래 데이터에서 규제 위반 의심 사례를 매일 추출해 보고서로 정리하는 시스템. supervisor 1 + worker 2(데이터 추출·근거 문서 검색) 구조. 도입 후 컴플라이언스 팀 보고서 작성 시간이 일평균 4시간에서 35분으로 줄었다. 핵심 포인트는 LLM 답변에 항상 근거 문서 링크를 첨부하도록 한 검증 단계였다.

2. 이커머스 상품 데이터 정합성 검사 (5개 에이전트)

상품명·이미지·옵션·가격·재고가 분리된 DB에 흩어져 있는데, 신상품 등록 시 다섯 항목이 모두 정합한지 검증하는 멀티 에이전트. 매일 신상품 1,500건을 자동 검증하면서 등록 거부 비율이 12%에서 2%로 떨어졌다. 멀티 에이전트가 아니었다면 컨텍스트 윈도우 한계로 단일 LLM이 모든 항목을 동시에 보기 어려웠다.

3. 제조 R&D 문헌 리뷰 어시스턴트 (4개 에이전트)

논문 검색 → 핵심 인용 추출 → 한국어 요약 → 사실 검증 4단계. 연구원이 일주일 단위로 받던 외부 문헌 리뷰 비용(건당 80만~150만 원)을 내부 자동화로 대체했다. 검증 에이전트가 환각 인용을 걸러내는 비율이 95% 이상이라, 사람 검수 부담이 크게 줄었다.

위 사례들은 Multi-Agent System Design Patterns 논문과 한국 LLM 기업 사례 컨퍼런스에서 공유된 패턴을 자체 적용한 결과다. 한 가지 공통점은 — 멀티 에이전트 자체가 가치를 만든 게 아니라, 검증 단계를 명시적으로 분리한 설계가 사람 검수 시간을 줄였다는 점이다.

외주 발주 시 업체 선택 6가지 기준

멀티 에이전트 외주는 일반 챗봇 개발보다 발주 리스크가 훨씬 크다. 견적서를 비교할 때 다음 여섯 가지를 반드시 확인한다.

production 운영 레퍼런스 — PoC 만들고 끝난 사례 말고, 6개월+ 운영 사례를 요구한다.
eval 파이프라인 설계 능력 — 회귀 테스트 데이터셋·정답 기준·자동 회귀 검사가 견적에 포함되어 있는가.
관측(observability) 스택 — 에이전트 간 메시지·도구 호출·토큰 사용량을 추적할 수 있는 대시보드가 인도 산출물에 있는가.
장애 복구 정책 — 한 에이전트가 멈췄을 때 전체가 멈추지 않도록 retry·fallback이 설계되어 있는가.
권한 격리 — 에이전트별로 API 키·DB 권한이 분리되어 있는가. 한 에이전트가 탈취돼도 피해 범위가 격리되는지가 보안 감사의 핵심이다.
인수인계 문서 — 운영 매뉴얼·시스템 프롬프트·도구 정의가 내부에서 수정 가능한 형태로 인도되는가.

위 여섯 항목 중 견적서에 명시되지 않은 게 절반 이상이면, 그 업체는 운영 단계의 함정을 모르고 PoC만 만들 가능성이 높다. 발주 전 동일 항목으로 2~3개 업체에 비교 견적을 받는 것을 권한다.

나무숲은 AI-Native Team으로, 팀원 전원이 Claude Code Max를 기본 개발 환경으로 사용하고, Anthropic Superpowers 프레임워크의 Brainstorming·Writing-plans·Subagent·TDD 스킬을 멀티 에이전트 설계에 그대로 적용한다. 멀티 에이전트 외주를 검토 중이라면 나무숲 AI-Native Team 페이지에서 자세한 워크플로우를 확인할 수 있다.

멀티 에이전트 구축 시 가장 흔한 실패 4가지

컨텍스트 폭증 — 에이전트 간 메시지가 누적되며 토큰 비용이 예상 대비 5~10배로 늘어난다. 메시지 요약 단계가 없으면 운영 1개월 만에 비용이 통제 불가능해진다.
검증 단계 누락 — supervisor가 worker 결과를 그대로 통합하면 환각이 한 곳에서 시작해 전체 결과를 오염시킨다. 별도 critic 에이전트가 필요하다.
권한 통합 미스 — 모든 에이전트가 동일한 관리자 API 키를 쓰면, 한 에이전트의 프롬프트 인젝션으로 전체 시스템이 흔들린다.
회귀 테스트 부재 — 시스템 프롬프트 한 줄 수정에 전체 동작이 바뀌는데, 회귀 테스트 데이터셋 없이는 변경 영향도 추적 불가다.

이 네 가지는 DeepMind의 multi-agent 안전성 연구 계열 글에서도 반복적으로 지적되는 항목이다. 외주 업체가 이 함정을 사전에 설명하지 못한다면, 운영 단계에서 비용·사고가 누적될 가능성이 높다.

FAQ

Q: 멀티 에이전트와 AI 에이전트, 무엇이 다른가요?

A: AI 에이전트는 일반 용어로, 환경을 인식하고 도구를 사용해 목표를 달성하는 모든 자율 시스템을 가리킨다. 멀티 에이전트는 그 안에서 여러 에이전트가 협업하는 특정 구조다. 즉 모든 멀티 에이전트는 AI 에이전트지만, 모든 AI 에이전트가 멀티 에이전트인 건 아니다. 챗봇 1개도 AI 에이전트이지만 멀티 에이전트는 아니다.

Q: 멀티 에이전트가 싱글 에이전트보다 항상 정확한가요?

A: 아니다. Anthropic 리서치에 따르면 복잡한 리서치·분석 작업에서는 10~25%p 정확도가 향상되지만, 단순 분류·요약 작업에서는 멀티 에이전트의 통신·검증 오버헤드가 오히려 노이즈를 추가한다. 작업 복잡도가 낮으면 싱글 에이전트가 더 빠르고 안정적이다.

Q: 멀티 에이전트 시스템 구축에 얼마나 걸리나요?

A: 부서 단위 자동화 기준 8~12주, 전사 플랫폼 기준 12~16주가 평균이다. 다만 production 안정화까지는 3~6개월의 추가 운영 기간이 필요하다. 6주 안에 끝낸다고 약속하는 업체는 PoC 수준의 결과물만 인도할 가능성이 높다.

Q: 직접 만드는 것과 외주, 어느 쪽이 유리한가요?

A: 사내에 LLM·RAG·observability를 모두 다뤄본 시니어 개발자 2명 이상이 있다면 직접 구축이 장기적으로 유리하다. 그렇지 않다면 외주로 시작해 운영 단계에서 인수인계받는 방식이 안전하다. AI-Native 개발 외주는 AI 개발 외주 완전 가이드 2026에서 비용·기간 기준을 정리해두었다.

Q: 멀티 에이전트 운영 중 가장 자주 발생하는 사고는 무엇인가요?

A: 토큰 비용 폭증과 환각 인용 두 가지다. 토큰 폭증은 메시지 요약 + 컨텍스트 윈도우 관리로, 환각 인용은 별도 검증 에이전트와 출처 강제 첨부로 막을 수 있다. 두 항목 모두 운영 시작 후 1~2개월 안에 드러나므로, 외주 계약 시 운영 안정화 기간을 명시해두는 것이 안전하다.

결론 — 멀티 에이전트는 도구이지, 목적이 아니다

멀티 에이전트는 "더 멋진 AI"를 만드는 트렌드가 아니라, 검증·분기·도구 통합이 동시에 필요한 작업에서 사람 검수 시간을 줄이는 도구다. 작업이 단순하면 싱글 에이전트가 더 빠르고 저렴하다. 발주 담당자는 위에서 정리한 도입 판단 트리(4가지 조건)·비용표·업체 선택 6가지 기준을 동일한 잣대로 2~3개 업체에 적용한 뒤 의사결정하길 권한다.

멀티 에이전트 외주를 검토 중이라면 AI-Native 개발사 나무숲에 카카오톡으로 사전 상담을 받아볼 수 있다. PoC 견적 전, 작업이 정말 멀티 에이전트가 필요한지부터 함께 점검하는 방식이다.

GitHub Copilot git 활용법 2026 — 커밋·PR·코드리뷰 자동화 가이드

TreeSoop — Tue, 02 Jun 2026 00:38:03 +0000

GitHub Copilot을 git에 붙인다는 것은 자동완성 도구를 코드 작성에만 쓰는 단계를 넘어, 커밋 메시지 작성·PR 설명·코드 리뷰 코멘트처럼 git 일상 작업까지 AI에게 맡기는 것을 뜻한다. copilot git 조합의 핵심은 변경된 diff를 Copilot이 읽고, 사람이 손으로 쓰던 반복 문장을 대신 만들어 주는 데 있다. 2026년 현재 Copilot은 IDE 확장과 CLI 양쪽에서 git을 보조하며, 커밋 단위 요약과 PR 리뷰 초안까지 만들어 낸다. 다만 멀티 파일에 걸친 자율 리팩터링이나 전체 저장소 맥락이 필요한 작업은 여전히 한계가 있어, 어디까지 Copilot에 맡기고 어디서부터 사람이 개입할지 기준을 정해 두는 것이 실무에서 가장 중요하다. 이 글은 그 경계를 실전 예시로 정리한다.

copilot git 연동이 바꾸는 것은 무엇인가?

git을 쓰는 개발자의 하루는 코드를 짜는 시간만큼이나 "이 변경을 어떻게 설명할까"에 쓰인다. 커밋 메시지를 고민하고, PR 본문을 채우고, 남의 PR을 리뷰하며 코멘트를 단다. GitHub Copilot의 git 연동은 바로 이 설명·요약 노동을 줄이는 데 초점이 있다.

구체적으로 세 지점에서 작동한다. 첫째, IDE 확장의 채팅에서 스테이징된 diff를 근거로 커밋 메시지 초안을 만든다. 둘째, GitHub 웹과 CLI에서 PR을 열 때 변경 요약 초안을 제안한다. 셋째, Copilot 코드 리뷰 기능이 PR의 변경분을 훑어 잠재적 버그·스타일 이슈를 코멘트로 남긴다. 셋 다 "사람이 쓰던 문장"을 대체하는 작업이라, 도입 즉시 체감 효과가 크다.

커밋 메시지와 브랜치 네이밍을 어떻게 자동화하나?

가장 빠르게 효과를 보는 영역이 커밋 메시지다. 변경을 스테이징한 뒤 Copilot Chat에 "스테이징된 변경으로 Conventional Commits 형식 커밋 메시지를 써 줘"라고 요청하면, feat:·fix:·refactor: 같은 접두사와 한 줄 요약, 본문 설명을 함께 제안한다.

실전에서는 다음 두 가지를 같이 정해 두면 품질이 안정된다.

컨벤션을 프롬프트에 명시: 팀이 Conventional Commits를 쓴다면 매번 형식을 알려 주는 대신, 저장소 루트에 커밋 규칙을 적은 가이드 파일을 두고 Copilot이 참조하게 한다.
브랜치 네이밍도 함께 요청: 이슈 번호와 작업 성격을 주면 feature/1234-add-oauth 같은 네이밍을 일관되게 뽑아 준다.

주의할 점은 Copilot이 diff의 "무엇"은 잘 요약해도 "왜"는 모른다는 것이다. 비즈니스 맥락(왜 이 값을 바꿨는지)은 사람이 한 줄 덧붙여야 한다.

PR 설명과 코드 리뷰 코멘트는 어디까지 자동화되나?

PR 본문은 Copilot이 특히 강한 영역이다. 변경 파일 목록과 diff를 근거로 "무엇을 바꿨고, 어떤 영향이 있는지"를 단락으로 정리해 준다. 리뷰어 입장에서 PR을 빠르게 파악하게 해 주므로 팀 전체의 리뷰 속도가 올라간다.

코드 리뷰 자동화는 보조선으로 보는 게 맞다. Copilot 리뷰는 명백한 null 체크 누락, 오타 수준의 버그, 일관성 없는 네이밍을 잘 잡는다. 반면 도메인 규칙 위반이나 아키텍처 적합성처럼 맥락 판단이 필요한 리뷰는 여전히 사람 몫이다. 실제로 GitHub은 Copilot 코드 리뷰를 "사람 리뷰를 대체가 아니라 보완"하는 도구로 설명한다(GitHub Docs).

Copilot이 git에서 못하는 일은 무엇인가? (한계)

Copilot을 git 자동화의 만능 도구로 기대하면 실망한다. 다음은 2026년 현재 명확한 한계다.

여러 파일·여러 커밋에 걸친 자율 작업: "이 기능을 3개 파일에 나눠 구현하고 각각 커밋해 줘" 같은 멀티스텝 자율 실행은 Copilot의 기본 채팅보다 에이전트형 도구가 낫다.
전체 저장소 맥락 추론: 큰 모노레포에서 변경의 파급 효과를 끝까지 추적하는 일은 한계가 있다.
git 히스토리 기반 의사결정: "이 버그가 언제 들어왔는지 bisect 해 줘" 같은 작업은 사람이 git 명령을 직접 다루는 게 빠르다.

이 경계를 표로 정리하면 도구 선택이 명확해진다.

Copilot만으로 부족할 때 — 어떤 도구로 넘어가야 하나?

git 작업의 자율성 수준에 따라 적합한 도구가 다르다. 아래 표는 같은 git 작업을 세 가지 AI 코딩 도구가 어디까지 처리하는지 비교한 것이다.

작업 유형	GitHub Copilot	Claude Code	Codex
커밋 메시지·PR 요약	◎ 강점	○ 가능	○ 가능
단일 파일 코드 보조	◎ 강점	◎ 강점	◎ 강점
멀티 파일 자율 구현	△ 제한적	◎ 강점	◎ 강점
터미널·git 명령 자율 실행	△ 제한적	◎ 강점	◎ 강점
도입 난이도	낮음(IDE 즉시)	중간	중간
적합 단계	개인·일상 git 작업	팀 단위 자율 개발	팀 단위 자율 개발

정리하면, 일상적인 커밋·PR·리뷰 보조는 Copilot이 가성비 최고다. 반면 여러 파일을 자율로 고치고 git 명령까지 스스로 실행하는 에이전트형 워크플로우가 필요해지면 Claude Code나 Codex 같은 도구로 확장하는 것이 자연스럽다. 두 도구 사이를 옮길 때 무엇을 자동 변환하고 무엇을 다시 설정해야 하는지는 Claude Code → Codex 마이그레이션 실전 가이드에서 단계별로 다뤘다.

나무숲은 AI-Native 개발 방식을 표방하는 팀으로, 팀원 전원이 일상 git 작업은 Copilot으로, 멀티 파일 자율 개발은 에이전트형 도구로 나눠 쓰는 하이브리드 루프를 실제 프로젝트에 적용하고 있다. 도구를 하나로 고집하기보다 작업 성격에 맞게 갈아 끼우는 것이 핵심이다.

사내 코드 유출은 어떻게 막나? (보안)

git에 AI를 붙일 때 가장 먼저 점검할 것이 코드 유출 위험이다. Copilot for Business·Enterprise는 입력 코드를 모델 학습에 쓰지 않는다고 명시하지만, 조직 정책상 외부 전송 자체를 막아야 하는 코드가 있을 수 있다(GitHub Docs). 다음 세 가지는 도입 전에 반드시 정한다.

콘텐츠 제외 설정: 특정 파일·경로를 Copilot 컨텍스트에서 제외(content exclusion)로 지정한다.
요금제 구분: 개인 요금제와 기업 요금제의 데이터 처리 정책이 다르다는 점을 팀에 공지한다.
온프레미스가 필요한 영역: 규제 산업이나 기밀 코드는 외부 SaaS 대신 사내 모델 운영을 검토한다.

자주 묻는 질문 (FAQ)

Q: copilot git 연동은 어떻게 시작하나요?

IDE(VS Code 등)에 GitHub Copilot 확장을 설치하고 GitHub 계정으로 로그인하면 바로 시작됩니다. 변경을 스테이징한 뒤 Copilot Chat에 커밋 메시지나 PR 요약을 요청하면 diff를 근거로 초안을 만들어 줍니다. 별도의 git 플러그인 없이 기본 git 워크플로우 위에서 동작합니다.

Q: Copilot이 자동으로 git commit이나 push까지 해 주나요?

기본 채팅 환경에서는 메시지·설명 "초안"을 만들 뿐, 실제 커밋과 푸시는 사람이 확인 후 실행하는 것이 안전합니다. 터미널 명령을 스스로 실행하는 수준의 자율 작업이 필요하면 Claude Code나 Codex 같은 에이전트형 도구가 더 적합합니다.

Q: Copilot 커밋 메시지 품질을 높이려면?

저장소에 커밋 컨벤션 가이드를 두고, 프롬프트에 "왜 바꿨는지"의 비즈니스 맥락을 한 줄 덧붙이세요. Copilot은 diff의 '무엇'은 잘 요약하지만 '왜'는 추론하지 못하므로, 이 한 줄이 메시지 품질을 좌우합니다.

Q: Copilot과 Claude Code를 같이 써도 되나요?

네. 일상적인 커밋·PR·리뷰 보조는 Copilot으로, 여러 파일에 걸친 자율 구현은 에이전트형 도구로 나눠 쓰는 하이브리드가 실무에서 가장 효율적입니다. 작업 성격에 맞춰 도구를 선택하면 됩니다.

Q: 사내 보안 정책상 외부 AI 도구를 못 쓰면 어떻게 하나요?

콘텐츠 제외 설정으로 민감 경로를 차단하거나, 규제·기밀 영역은 사내에서 운영하는 모델로 분리하는 방법이 있습니다. 도입 범위를 팀 정책으로 먼저 정한 뒤 단계적으로 확대하는 것을 권합니다.

클로드로 한글파일(HWP) 변환·자동화하는 법 2026 — 요약·표 추출·일괄 처리 실전

TreeSoop — Tue, 02 Jun 2026 00:37:09 +0000

클로드로 한글파일(HWP) 변환·자동화하는 법 2026 — 요약·표 추출·일괄 처리 실전

한글파일을 Claude로 다루려는 한국 기업 실무자가 가장 먼저 부딪히는 벽은 "읽기는 됐는데, 그래서 뭘 어떻게 자동화하지?"다. HWP-MCP를 설치해 Claude가 한글 문서를 읽게 만드는 것까지는 HWP-MCP 도입 가이드에서 다뤘다. 이 글은 그 다음 단계 — 실제 업무에서 한글파일을 요약·변환·일괄 처리하는 구체적 방법을 실전 예시로 보여준다.

한글파일 AI 자동화의 핵심은 "한컴 오피스 라이선스 없이, 사람 손을 거치지 않고, 반복 작업을 Claude에게 위임하는 것"이다. 계약서 100건 요약, 요구사항서의 표를 CSV로 추출, 폴더 안 HWP 일괄 변환 — 이런 작업이 자동화 대상이다.

한글파일 자동화로 풀 수 있는 업무 3가지

업무	수동 작업 시간	자동화 후	적용 키워드
문서 요약	1건당 10~15분	50건 30초	claude 한글파일 요약
표 → 데이터 추출	1표당 5분 (재입력)	표 자동 CSV 변환	hwp 표 추출
일괄 변환·정리	100건 8시간	100건 1시간 20분	한글파일 일괄 처리

세 업무 모두 "사람이 한글파일을 열어 읽고, 내용을 옮겨 적는" 반복 작업이다. Claude + HWP-MCP 조합은 이 중간 단계를 없앤다.

전제: HWP-MCP 연결 확인

자동화에 들어가기 전, Claude가 한글파일을 읽을 수 있는 상태인지 확인한다. (설치 절차는 HWP-MCP 도입 가이드 참조.)

# Claude Desktop 설정에서 hwp-mcp 서버가 연결됐는지 확인
# MCP 도구 목록에 hwp_read, hwp_extract_tables 등이 보여야 함

연결이 확인되면 아래 3가지 워크플로우를 바로 쓸 수 있다.

워크플로우 1: 한글파일 요약 자동화

계약서·보고서·요구사항서처럼 길이가 긴 한글 문서를 Claude에게 요약시키는 패턴이다.

단일 문서:

"이 한글파일을 읽고 다음 3가지로 요약해줘:
 1. 핵심 내용 5줄
 2. 의사결정이 필요한 항목
 3. 누락되거나 모호한 조항"

여러 문서 일괄 요약:
폴더 경로를 주고 "이 폴더의 모든 .hwp 파일을 각각 위 형식으로 요약하고, 결과를 하나의 마크다운 표로 정리해줘"라고 지시하면, Claude가 HWP-MCP로 파일을 순회하며 처리한다. 50개 문서 기준 약 30초.

요약 품질을 높이는 팁: "요약 기준"을 구체적으로 명시할수록 결과가 좋다. "계약 금액·기간·위약 조항 중심으로" 같은 도메인 컨텍스트를 주면 일반 요약보다 실무 적합도가 크게 오른다.

워크플로우 2: 표 → CSV 데이터 추출

한글파일의 표는 복사-붙여넣기로 옮기면 서식이 깨지는 게 가장 큰 골칫거리다. HWP-MCP의 표 추출 기능을 쓰면 구조를 유지한 채 데이터만 뽑는다.

"이 한글파일에 있는 모든 표를 추출해서 CSV로 변환해줘.
 표가 여러 개면 각각 별도 파일로, 헤더 행을 포함해서."

활용 시나리오:

견적서·정산표: 한글 견적서의 항목·단가·합계를 회계 시스템에 올릴 CSV로
요구사항 명세: 기능 목록 표를 이슈 트래커(Jira/Linear) import 형식으로
설문·조사 결과: 한글 보고서의 통계 표를 분석용 데이터프레임으로

표 안에 병합 셀이 있으면 Claude에게 "병합 셀은 상위 값으로 채워줘(forward fill)"라고 미리 지시하는 게 데이터 정합성에 좋다.

워크플로우 3: 폴더 일괄 처리

가장 ROI가 큰 패턴. 수백 개 한글파일이 쌓인 폴더를 통째로 처리한다.

"./contracts 폴더의 모든 .hwp 파일에 대해:
 1. 계약 상대방·금액·시작일·종료일을 추출
 2. 하나의 CSV로 통합 (파일명을 첫 열에)
 3. 종료일이 30일 이내인 계약은 ⚠️ 표시"

100건 기준 수동 8시간 작업이 약 1시간 20분으로 줄어든다(실측). 핵심은 추출 스키마를 먼저 정의하는 것 — 무엇을 뽑을지 명확할수록 일괄 처리 정확도가 높다.

python-docx·한컴 API와 무엇이 다른가

방식	한글파일(.hwp) 지원	자동화 난이도	AI 통합
한컴 오피스 자동화 (COM)	✅ 완전	높음 (Windows 전용, COM 지식 필요)	❌ 수동
python-docx	❌ (.docx만)	중간	❌
HWP-MCP + Claude	✅	낮음 (자연어 지시)	✅ 네이티브

핵심 차이: HWP-MCP는 코드를 짤 필요 없이 자연어로 자동화한다. "이 폴더 처리해줘"라고 말하면 끝. 한컴 COM 자동화는 강력하지만 Windows 전용 + 프로그래밍 비용이 크고, python-docx는 애초에 한글파일(.hwp)을 못 읽는다.

자동화 도입 시 흔한 실패 3가지

스키마 미정의로 일괄 처리 결과 들쑥날쑥 → 추출할 필드를 표로 먼저 정의하고 1~2개 파일로 검증한 뒤 일괄 실행.
대용량 폴더를 한 번에 → 수백 건은 50건 단위로 나눠 실행하면 컨텍스트 한계·중단 위험이 줄어든다.
민감 문서를 검증 없이 자동 처리 → 계약서 등은 자동 추출 결과를 사람이 최종 확인하는 단계를 워크플로우에 포함.

읽기를 넘어 자동화로

HWP-MCP로 한글파일을 "읽는" 것은 시작일 뿐이다. 진짜 가치는 요약·표 추출·일괄 처리를 사람 손 없이 돌리는 자동화에서 나온다. 위 3가지 워크플로우는 한국 기업의 한글파일 의존 업무(계약·견적·요구사항·보고)에 그대로 적용된다.

자동화 범위를 더 넓히려면 — 한글파일 처리 결과를 다시 다른 시스템(회계·이슈 트래커·DB)으로 흘려보내는 에이전트 워크플로우가 다음 단계다. 이는 Agentic AI 개발 가이드의 멀티 스텝 자동화 패턴과 연결된다.

관련 자료

HWP-MCP으로 Claude에 한글 파일 읽기 해결 — 설치·연결·도입 가이드 (이 글의 전제)
Agentic AI란? 일반 AI 에이전트와 뭐가 다른가 — 한글파일 자동화를 멀티스텝 워크플로우로 확장
AI-Native 팀 방법론 — 문서 자동화를 조직 운영에 통합하는 방식

FAQ

Q1. 한컴 오피스 라이선스 없이도 클로드로 한글파일을 다룰 수 있나요?
네. HWP-MCP는 한컴 오피스 설치 없이 .hwp 파일을 읽고 텍스트·표를 추출합니다. 한컴 COM 자동화와 달리 Windows 전용도 아니며, 자연어 지시만으로 요약·변환·일괄 처리가 가능합니다.

Q2. claude로 한글파일 표를 CSV로 추출하면 서식이 깨지지 않나요?
HWP-MCP의 표 추출 기능은 행·열 구조를 유지한 채 데이터를 뽑습니다. 병합 셀이 있으면 "병합 셀은 상위 값으로 채워줘"라고 미리 지시하면 데이터 정합성을 확보할 수 있습니다.

Q3. 한글파일 일괄 처리는 몇 건까지 가능한가요?
수백 건 처리 사례가 있으나, 컨텍스트 한계와 중단 위험을 줄이려면 50건 단위로 나눠 실행하는 것을 권장합니다. 100건 기준 수동 8시간 작업이 약 1시간 20분으로 단축됩니다.

Q4. 한글파일 자동화로 가장 ROI가 큰 업무는?
반복적인 문서 요약(계약서·보고서)과 표 데이터 재입력(견적서·명세서)입니다. 사람이 "열어서 읽고 옮겨 적는" 중간 단계가 큰 업무일수록 자동화 효과가 큽니다.

Q5. 자동화 결과를 그대로 신뢰해도 되나요?
계약서 등 민감 문서는 자동 추출 결과를 사람이 최종 확인하는 단계를 워크플로우에 포함하는 것을 권장합니다. 추출 스키마를 먼저 1~2개 파일로 검증한 뒤 일괄 실행하면 정확도가 높습니다.

Claude Code Codex 마이그레이션 가이드 2026 — 7단계 절차·도구 비교

TreeSoop — Tue, 02 Jun 2026 00:37:08 +0000

Claude Code에서 Codex로 옮길 때 — 실전 마이그레이션 가이드 2026

Claude Code 기반 워크플로우를 OpenAI Codex CLI로 옮기려는 팀이 늘고 있다. 모델 가격, 멀티 벤더 리스크 분산, 특정 코딩 워크로드의 성능 차이 등 이유는 다양하다. 그런데 두 도구는 같은 "AI 코딩 에이전트"라는 카테고리에 속해도 컨벤션·확장 메커니즘이 다르다. 무작정 옮기면 자동화 파이프라인의 절반이 깨진다.

이 가이드는 Claude Code → Codex 마이그레이션을 실제로 끝내본 팀이 어떤 순서로 무엇을 옮기고, 무엇을 포기하고, 무엇을 대체했는지 정리한다. 자동 변환 툴(claude2codex)을 어디서 쓰고 어디서 안 쓰는지, 일주일 점검 체크리스트, 양쪽을 분기 사용하는 하이브리드 패턴까지 다룬다.

마이그레이션 전 의사결정 — 옮길지 말지부터

옮기는 게 모두에게 정답은 아니다. 다음 세 질문에 모두 "예"여야 본격 마이그레이션을 권한다.

현재 Claude Code 비용의 60% 이상이 일상적인 코드 편집·리뷰에서 발생하는가? (Codex의 GPT-5-codex가 단가 우위를 보이는 영역) — 만약 디자인·기획·문서 분량이 큰 워크플로우라면 Claude를 유지하는 게 합리적이다.
Skills·Hooks·서브에이전트 같은 Claude 고유 기능에 의존하지 않는가? 의존도가 높다면 마이그레이션 비용이 비용 절감을 초과한다.
하나의 벤더 락인을 줄이는 게 중요한 전략적 우선순위인가? 멀티 벤더 운영은 그 자체로 관리 비용이 든다.

세 질문 중 하나라도 "아니오"라면, 통째 마이그레이션 대신 하이브리드 분기 사용(아래 5절)이 더 낫다.

Claude Code와 Codex의 핵심 차이 비교

영역	Claude Code	OpenAI Codex CLI	마이그레이션 난이도
메인 모델	claude-opus-4-7 / sonnet-4-6 / haiku-4-5	GPT-5 / GPT-5-codex / o1 계열	낮음 (모델 교체)
컨벤션 파일	`CLAUDE.md`	`AGENTS.md` (멀티 벤더 표준)	낮음 (rename + 어조 조정)
확장 메커니즘	Skills (markdown SKILL.md + 메타데이터)	별도 표준 없음, 수동 컨텍스트 로딩	높음 (가장 큰 갭)
자동화 훅	Hooks (PreToolUse, SessionStart, UserPromptSubmit 등)	라이프사이클 이벤트 미지원	높음 (외부 wrapper 필요)
슬래시 커맨드	`/명령` 형태 + 인자 파싱	CLI 인자로 대체	중간
MCP 서버	1급 지원, 자동 도구 노출	일부 지원, 설정 형식 다름	중간
서브에이전트	Agent tool (subagent_type)	외부 오케스트레이션 필요	높음
권한 모드	acceptEdits / plan / dontAsk 등	--auto / --confirm 류	낮음

가장 큰 갭 세 곳: Skills · Hooks · 서브에이전트. 이 세 가지에 깊이 의존하는 팀은 마이그레이션 ROI가 마이너스로 나올 수 있다.

마이그레이션 절차 — 7단계

1단계: 자산 인벤토리 (1일)

.claude/ 디렉토리, CLAUDE.md, 프로젝트 루트의 slash command 정의, hook 설정, MCP 서버 목록을 전부 추출한다.

find . -path "*/.claude/*" -type f > migration/inventory.txt
ls .claude/skills/ .claude/hooks/ .claude/commands/ 2>/dev/null >> migration/inventory.txt
cat .claude/settings.json | jq '.mcpServers // {}' > migration/mcp.json

이 파일들이 모두 변환되거나, 대체되거나, 폐기되는지 명시적으로 매핑되어야 한다. "그냥 옮기면 되겠지"는 거의 항상 일주일 후 장애로 돌아온다.

2단계: `claude2codex` 자동 변환 적용 (반나절)

오픈소스 claude2codex 마이그레이션 툴이 자동으로 처리하는 것:

CLAUDE.md → AGENTS.md (어조·헤더·도구 참조 조정)
슬래시 커맨드 정의 → CLI 별칭 또는 스크립트
MCP 서버 설정 → Codex 호환 포맷

자동 변환의 한계: Skills와 Hooks는 1:1 대응되는 개념이 Codex에 없으므로 변환 안 함. 다음 단계에서 수동 대체.

3단계: Skills 대체 전략 결정 (2~3일)

Claude의 Skills는 "필요할 때 자동 로드되는 작업 패턴 가이드"다. Codex에는 동등한 기능이 없으므로 세 가지 옵션 중 선택한다.

옵션 A — 수동 컨텍스트 로딩: Skill 내용을 AGENTS.md의 부록 섹션으로 옮긴다. 항상 로드되니 토큰 비용 증가. 자주 쓰는 핵심 3~5개 Skill에만 적용.
옵션 B — 외부 prompt 라이브러리: Skill markdown을 prompts/ 디렉토리에 두고, 작업 시작 시 사용자가 명시적으로 --load-prompt skill-name으로 주입. 토큰 효율적이나 호출이 강제되지 않음.
옵션 C — 트리거 wrapper 스크립트: 사용자 입력을 가로채는 사전 처리 스크립트로 Skill을 자동 주입. 가장 Claude 같은 경험이지만 구현 비용 큼.

대부분 팀은 A+B 조합이 현실적이다. Tier-0 핵심 워크플로우는 A로 항상 로드, 나머지는 B로 on-demand.

4단계: Hooks 대체 (2일)

Claude의 PreToolUse, SessionStart, UserPromptSubmit 등은 Codex에 없다. 대체 방법:

Hook 용도	Codex 대체
세션 시작 시 컨텍스트 로딩	쉘 별칭으로 Codex 호출 전 `cat context.md`
도구 호출 전 권한 검사	Codex의 `--require-approval` 정책 활용
사용자 입력 검증/주입	외부 wrapper CLI에서 입력 가공 후 Codex에 전달
자동 commit / push	Codex 종료 후 별도 git hook 또는 CI 스크립트

핵심은 "Codex 안에서 처리"가 아니라 "Codex 호출 전후에 외부에서 처리"로 패러다임을 옮기는 것. 자동화 보장 수준은 약간 떨어지지만 멀티 벤더 호환성은 높아진다.

5단계: 하이브리드 분기 패턴 (선택)

전부 옮기지 말고 워크로드별로 도구를 나누는 게 실측상 가장 큰 비용·품질 개선을 낸다. AI-Native 개발팀의 실제 분기 예시:

Claude Code 유지: 아키텍처 설계, 멀티파일 리팩토링, Skills·Hooks 의존 워크플로우, 한국어 문서 작성
Codex로 전환: 일상적 코드 편집·디버깅, 단위 테스트 생성, 짧은 함수 작성, 대량의 단순 작업

분기 운영의 관리 비용을 줄이려면 한 가지 규칙으로 정렬한다 — "3,000 토큰 이하의 단순 작업 = Codex, 그 외 = Claude" 같은 단순한 휴리스틱이 실측에서 의사결정 비용을 가장 적게 만든다.

6단계: 일주일 점검 체크리스트

마이그레이션 직후 일주일은 거의 확실히 무언가 깨진다. 다음 항목을 매일 확인한다.

자동화 파이프라인(예: 일일 빌드, 코드 리뷰 자동화, 문서 생성)이 의도대로 끝까지 실행되는가?
비용 모니터링: 예상 절감이 실제로 나오는가? (Codex의 토큰 단가 × 사용량 vs 직전 Claude 사용량)
Skill 의존하던 작업의 품질이 떨어지지 않았는가? (대체 옵션 재조정 필요)
팀원의 "그냥 Claude로 돌아가고 싶다" 빈도 — 3회 이상 발생하면 하이브리드 비율 재조정.

7단계: 롤백 가능 상태 유지

.claude/ 디렉토리는 삭제하지 말고 압축 보관한다. 마이그레이션이 ROI 마이너스로 판명되면 즉시 되돌릴 수 있어야 한다.

tar -czf migration/claude-config-backup-$(date +%Y%m%d).tar.gz .claude/

마이그레이션 후 흔한 실패 4가지

"Skills 없어도 되겠지" → 일주일 안에 컨벤션 일관성 깨짐. 핵심 3~5개는 반드시 AGENTS.md에 포함.
Hooks 의존 자동화 방치 → 자동 커밋·자동 검증 등이 조용히 빠지면서 디버깅 가능 정보 손실. 5단계 외부 wrapper 패턴 적용 필수.
MCP 서버 호환성 가정 → 일부 MCP 서버는 Claude 전용 API 패턴 사용. 마이그레이션 전 각 MCP 서버의 Codex 호환성 개별 확인.
"Codex가 더 싸니까 더 막 쓰자" → 호출 빈도 증가로 결과적으로 더 비싸짐. 1단계 인벤토리에서 의도한 사용량 시나리오를 유지.

마이그레이션 = 도구 교체가 아니라 패러다임 이동

Claude Code에서 Codex로의 마이그레이션은 단순한 "CLI 교체"가 아니다. 확장 메커니즘이 도구 안(Skills/Hooks)에 있느냐, 도구 밖(외부 wrapper)에 있느냐의 패러다임 차이다. 이 차이를 인지하고 옮기면 실패율이 크게 떨어진다.

자동 변환 툴은 첫 절반의 작업(컨벤션·MCP·슬래시 커맨드)을 빠르게 끝내준다. 나머지 절반(Skills·Hooks·서브에이전트 대체)은 각 팀의 워크플로우 분석이 필요한 본질적 작업이다. 이걸 두 번째 변환 툴이 처리해주길 기대하지 말고, 위 7단계로 한 번에 끝내는 게 빠르다.

관련 자료

Claude Code → Codex 마이그레이션 툴 오픈소스 공개 — 자동 변환 툴 소개와 release 노트
Claude Code·Codex·Gemini로 비디오 전사 자동화 — 멀티 벤더 분기 운영 실제 사례
AI-Native 팀 방법론 — 멀티 도구 운영의 조직 구조

FAQ

Q1. claude2codex 자동 변환 툴만 돌리면 마이그레이션 끝나나요?
아니오. 자동 변환은 컨벤션 파일(CLAUDE.md → AGENTS.md), MCP 설정, 슬래시 커맨드 매핑 등 약 절반을 처리합니다. Skills·Hooks·서브에이전트 의존 워크플로우는 수동 대체 전략(3·4·5단계)이 별도로 필요합니다.

Q2. 단순한 일부 워크로드만 Codex로 옮기는 게 더 안전한가요?
대부분의 팀에 그렇습니다. 전체 마이그레이션보다 하이브리드 분기 운영(5단계)이 실측 ROI가 더 큽니다. "3,000 토큰 이하 단순 작업 = Codex, 그 외 = Claude" 같은 단순 휴리스틱 하나만 도입해도 비용 20~30% 절감 사례가 있습니다.

Q3. Skills 대체로 가장 효과적인 방법은?
"Tier-0 핵심 워크플로우 3~5개는 AGENTS.md에 항상 포함(옵션 A), 나머지는 prompts/ 디렉토리에 두고 on-demand 로딩(옵션 B)" 조합이 가장 실용적입니다. 모든 Skill을 AGENTS.md에 넣으면 토큰 비용이 폭증합니다.

Q4. 마이그레이션 후 며칠 안에 ROI 평가가 가능한가요?
최소 2주입니다. 첫 1주는 깨진 자동화 복구로 소요되고, 2주차에 비로소 안정 운영 비용이 측정됩니다. 이 시점에서 예상 절감이 실측과 30% 이상 차이나면 6단계 체크리스트로 원인 추적이 필요합니다.

Q5. Claude로 다시 돌아갈 수 있나요?
네. 7단계의 .claude/ 백업을 유지하면 언제든 롤백 가능합니다. AI-Native 팀의 약 20%는 한 번 Codex로 전환했다가 Skills·Hooks 부재의 불편함 때문에 6주 안에 Claude로 돌아오거나 하이브리드로 재구성합니다.

claude2codex: migrate Claude Code config to OpenAI Codex in one command

TreeSoop — Fri, 17 Apr 2026 14:30:13 +0000

Our team pays ~$700/month for Claude Code Max (3 accounts). We're Claude-native. But between Claude's recent reliability issues and Codex's cost advantages for simpler workloads, we've been moving some work to Codex.

Migrating turned out to be annoying — plugins, MCP servers, memory files, harness configs all live in different places with different formats.

We wrote a CLI to automate it and open sourced it.

📚 Full writeup: https://treesoop.com/blog/claude2codex-migration-tool-open-source-2026
🔧 GitHub: https://github.com/treesoop/claude2codex

What it migrates

Claude Code	→	Codex
`~/.claude/CLAUDE.md`		`~/.codex/config.md` (format converted)
`~/.claude/settings.json`		`codex.toml`
`~/.claude/skills/*.md`		`~/.codex/prompts/*.md`
`~/.claude/user_profile.md`		Codex profile
MCP server registrations		Codex-compatible config block
Harness trigger logic		Best-effort port with warnings

Install

npx claude2codex init
npx claude2codex migrate --dry-run  # preview
npx claude2codex migrate            # execute

Who should care

Teams running both Claude Code and Codex in hybrid mode
Anyone hitting Claude Code session limits or reliability issues
Teams evaluating Codex but not wanting to set up from scratch

Results in our team

Nine team members migrated their setups using this tool. ~95% of settings auto-converted and worked in Codex on first try. The remaining 5% were flagged in a conflict report and manually adjusted.

Why hybrid, not replacement

We still default to Claude Code Max for anything requiring strong reasoning or long-horizon planning. Codex picks up:

Short repetitive tasks (doc generation, test writing)
Tasks where token cost matters more than depth
Fallback when Claude adaptive thinking underallocates

Details

MIT licensed
Your original Claude config is preserved (not modified)
Codex unsupported features get warnings in a report

More from TreeSoop: ai-news-mcp, hwp-mcp, whisper_transcription

Blog: https://treesoop.com/blog

Local Whisper pipeline beats paid Korean transcription services

TreeSoop — Fri, 17 Apr 2026 14:29:35 +0000

We were paying for Notta to transcribe Korean meetings. The Korean accuracy on technical terms was consistently bad — we were spending more time fixing transcripts than just writing notes by hand.

So we built a local Whisper pipeline. Turns out it beats the paid service on Korean accuracy.

📚 Full writeup: https://treesoop.com/blog/whisper-transcription-local-korean-stt-2026
🔧 GitHub: https://github.com/treesoop/whisper_transcription

Setup

Audio → ffmpeg preprocessing → Whisper (large-v3) → sentence boundary post-processing → markdown

Key decisions:

Whisper large-v3 for Korean technical vocabulary accuracy. base/small/medium all struggle with domain-specific terms.
ffmpeg preprocessing — 16kHz sample rate, light noise filter. Measurable accuracy bump.
Sentence boundary post-processing — Whisper outputs long monologues. We re-chunk using commas, conjunctions, and timestamps.

Results (30-min Korean meeting)

Technical term accuracy: noticeably better than paid service
Processing speed on M1 Pro: faster than realtime
Cost: zero
Security: entirely local, no cloud transmission

Why local matters

Most of our use cases can't legally send audio to cloud:

Customer meeting recordings (NDA)
Legal/medical meetings (privacy laws)
Strategy meetings (trade secrets)
R&D discussions (IP)

Local-only pipeline removes all of that concern.

About VibeVoice

We tested it. Didn't run stably on Apple Silicon when we tried. Skipped for this release. Will revisit if they fix Apple Silicon compatibility.

TreeSoop context

We also have a commercial Korean STT product called Asimula with domain-specific fine-tuning for medical/legal. This OSS pipeline is a good starting point if you want to validate basic Whisper quality before investing in domain tuning.

MIT licensed
macOS Silicon optimized (M1/M2/M3/M4)
See repo for setup

More from TreeSoop: ai-news-mcp, hwp-mcp, claude2codex

Blog: https://treesoop.com/blog

Stop burning tokens on DOM noise: a Playwright MCP optimizer layer

TreeSoop — Fri, 17 Apr 2026 14:21:00 +0000

If you've used Playwright MCP for AI browser automation, you know the pain. Every page navigation dumps the full DOM tree into the model context. Simple flows like "order 5 items from this shop" can burn hundreds of thousands of tokens on navbar/sidebar/footer noise that has nothing to do with the task.

We built a small MCP layer that sits in front of Playwright and only forwards the relevant bits. Open sourced it.

📚 Full writeup: https://treesoop.com/blog/playwright-mcp-optimizer-token-saving-2026
🔧 GitHub: https://github.com/treesoop/claude-native-plugin

The problem

Playwright MCP serializes the full DOM:

AI ← {ENTIRE_DOM_JSON} ← Playwright MCP

This works for QA where you need to see everything. For "browse and take an action" it's 5-10× the tokens you actually need.

The optimizer

AI ← {relevant_only} ← Optimizer ← {full DOM} ← Playwright MCP

Three filter rules:

Interactive elements first: button, input, a — not decorative div/span
Semantic grouping: navigation / main / form / footer regions, so the model knows where it is
Task-aware skipping: if the current task is "checkout", skip sidebar recommendations and ad banners

Measured impact

On a "cart → checkout" flow with GPT-4: tokens dropped substantially, and round-trip latency improved as a side effect (smaller payloads → faster agent decisions).

Not a silver bullet. For QA tasks where you need full DOM accuracy, use vanilla Playwright MCP. For general browsing / automation agents, this is the cheaper + faster path.

Tool comparison (our testing)

Tool	Strength	Use for
playwright-mcp (default)	Full DOM accuracy	QA, complex validation
playwright-optimizer (this)	Token efficiency	Automation agents, browsing
vercel-browser-agent	Code generation speed	Simple browsing
claude-chrome-extension	Uses logged-in session	Tasks needing auth state

We use all four for different jobs.

Install

npm install -g @treesoop/playwright-optimizer
claude mcp add playwright-opt -- playwright-optimizer

MIT licensed
Configurable per-site presets
--log-tokens flag for measurement

More OSS from TreeSoop: ai-news-mcp, hwp-mcp, whisper_transcription, claude2codex

Blog: https://treesoop.com/blog

ai-news-mcp: 17 AI trend sources auto-scraped, served via MCP

TreeSoop — Fri, 17 Apr 2026 14:19:24 +0000

Keeping up with AI news means scraping the same sources as everyone else — HackerNews, Reddit (r/MachineLearning, r/LocalLLaMA), ArXiv, GitHub Trending, Dev.to, Lobsters, and about 10 more. Everyone builds their own version. Seems silly.

So we built one and open sourced it.

📚 Full writeup: https://treesoop.com/blog/ai-news-mcp-17-sources-auto-scraping-2026
🔧 GitHub: https://github.com/treesoop/ai-news-mcp

What it does

17 sources scraped every 6 hours by a Mac mini in our office. Results exposed via Model Context Protocol so any MCP-compatible AI tool can query it.

Sources include:

HackerNews, Reddit (4 AI subs), Dev.to, Lobsters
ArXiv AI, ArXiv ML
GitHub Trending
OpenAI, Anthropic, Google AI, Meta AI blogs
TechCrunch AI, VentureBeat AI, The Verge AI

Install

claude mcp add ai-news -- npx -y @treesoop/ai-news-mcp

Works in Claude Code, Cursor, Claude Desktop, ChatGPT — anywhere MCP is supported.

Example queries

"Show me HackerNews top AI posts from today with 100+ points"
"Summarize ArXiv AI papers about RAG from the last 24 hours"
"What's trending on r/LocalLLaMA about Qwen3?"

Why bother

Our blog agent at treesoop.com uses this MCP to decide what to write about each day. Before it existed, we were scraping manually in 5 different scripts. Now it's one call.

If you run a dev newsletter, slack bot, or content agent, this probably saves you an afternoon.

Details

MIT licensed, commercial use OK
Data stored in our Supabase instance (free for public use)
Self-host option in README if you want your own cadence

More TreeSoop OSS: hwp-mcp, whisper_transcription, claude2codex.

Blog: https://treesoop.com/blog

Introducing hwp-mcp: Korean document support for Claude via MCP

TreeSoop — Fri, 17 Apr 2026 14:15:48 +0000

Korean office documents (.hwp / .hwpx) are everywhere in Korean government, enterprise, and legal workflows. Until now, Claude, ChatGPT, and Cursor couldn't read them natively — a real blocker for anyone building AI systems for Korean organizations.

We (TreeSoop) just released hwp-mcp, an open source MCP server that fixes this.

📚 Full writeup: https://treesoop.com/blog/hwp-mcp-korean-document-ai-claude-2026
🔧 GitHub: https://github.com/treesoop/hwp-mcp

What it does

hwp-mcp exposes these tools via the Model Context Protocol:

Extract text from .hwp / .hwpx files
Parse tables into structured data
Pull out embedded images
Find-and-replace within documents
Fill template variables (name, company, date)

Works on macOS and Windows. No Hancom Office license required.

Install in one line

claude mcp add hwp-mcp -- uvx --from hwp-mcp hwp-mcp

Works with Claude Code, Claude Desktop, VS Code Copilot, Cursor — anywhere that supports MCP.

Why this matters for Korean AI adoption

If you're building RAG systems, internal search, or document automation for Korean companies, 60–80% of the source documents will be HWP. Before hwp-mcp the options were:

Manual conversion (doesn't scale)
Hancom API licensing (Windows-only, paid)
Convert everything to Word org-wide (non-starter)

Now you just install the MCP and Claude reads HWP natively.

What we're using it for

TreeSoop uses hwp-mcp in:

Corporate RAG chatbots ingesting HWP knowledge bases
Government RFP automation (RFPs are distributed as HWP)
Legal contract review (Korean law firm contracts = HWP)
Meeting-note template auto-fill

MIT licensed

Commercial use is fine. Contributions welcome.

GitHub: https://github.com/treesoop/hwp-mcp
Docs: included in repo README

TreeSoop is an AI-Native dev agency from Korea. POSTECH/KAIST team. We're building production AI agents, RAG systems, and MCP tools. More OSS: ai-news-mcp, whisper_transcription, claude2codex.

Blog: https://treesoop.com/blog