통합 프로젝트 실수 5가지

실수 1: 패키지 버전 충돌

[문제]
RAG 코드: langchain==0.2.16
Agent 코드: langchain==1.0.0
-> ImportError: cannot import name 'xxx' from 'langchain'

[해결]
- 처음부터 하나의 pyproject.toml에서 의존성 통합 관리
- pip install 전에 모든 의존성 호환성 확인
- 가상환경(venv) 반드시 사용

실수 2: 환경변수 하드코딩

# [나쁜 예]
client = OpenAI(api_key="sk-abc123...")  # 코드에 키가!
driver = GraphDatabase.driver("bolt://localhost:7687",
                              auth=("neo4j", "1234"))

# [좋은 예]
from config.settings import settings
client = OpenAI(api_key=settings.openai_api_key)
driver = GraphDatabase.driver(
    settings.neo4j_uri,
    auth=(settings.neo4j_user, settings.neo4j_password)
)

실수 3: 순환 참조 (Circular Import)

# agent/tools.py
from rag.retriever import search  # RAG를 참조

# rag/retriever.py
from agent.tools import get_agent  # Agent를 참조 -> 순환!

# [해결] Service Layer를 통해 간접 참조
# agent/tools.py
class RAGTool:
    def __init__(self, rag_service):  # 의존성 주입
        self.rag = rag_service

실수 4: 에러 핸들링 누락

# [나쁜 예] - Neo4j 연결 실패 시 전체 앱 크래시
driver = GraphDatabase.driver(uri, auth=auth)
result = driver.execute_query(cypher)

# [좋은 예] - 그레이스풀 폴백
try:
    driver = GraphDatabase.driver(uri, auth=auth)
    result = driver.execute_query(cypher)
except Exception as e:
    logger.warning(f"KG 서비스 불가: {e}")
    result = {"error": "Knowledge Graph에 연결할 수 없습니다."}
    # KG 없이도 RAG만으로 답변 시도

실수 5: 전역 상태 의존

# [나쁜 예] - 전역 변수 사용
chroma_client = None  # 전역!

def get_client():
    global chroma_client
    if chroma_client is None:
        chroma_client = chromadb.Client()
    return chroma_client

# [좋은 예] - 의존성 주입 + 팩토리
class RAGService:
    def __init__(self, settings: Settings):
        self.client = chromadb.PersistentClient(
            path=settings.chroma_persist_dir
        )

---

체크리스트

설계를 마치기 전 확인:

• 모든 의존성이 pyproject.toml에 명시됨
• API 키, 비밀번호가 .env에만 있음
• 순환 참조가 없는 의존성 방향
• 외부 서비스 실패 시 폴백 계획 있음
• 전역 상태 대신 의존성 주입 사용