LangGraph 프로덕션에서 AI 에이전트 코드 품질이 들쑥날쑥한 이유 — Act Operator로 팀 표준 잡기 (github.com)

한줄 요약

LangGraph 에이전트 팀 표준화를 원한다면, 프롬프트보다 개발 환경 설계가 핵심이다.

어떤 상황에서 필요한가?

LangGraph 기반 에이전트를 팀으로 개발하다 보면 반드시 마주치는 상황이 있다. 숙련 개발자가 Claude Code에 워크플로우 구현을 요청하면 꽤 괜찮은 코드가 나오는데, 신규 팀원이 똑같은 모델에 똑같은 요청을 하면 결과물이 제각각이다. 모델이 문제가 아니다.

더 골치 아픈 건 세션 단절 문제다. 어제 설계한 아키텍처를 오늘 새 세션에서 에이전트가 기억하지 못한다. 팀 컨벤션이 코드베이스가 아닌 특정 개발자의 머릿속에만 존재하는 한, 에이전트도 그 지식에 접근할 방법이 없다. AI 도구를 팀 단위로 프로덕션에 적용하려는 조직이라면 이 문제가 매우 친숙할 것이다.

핵심 구현 방법

Act Operator는 이 문제를 "하네스(Harness)" 개념으로 접근한다. 하네스란 통제되지 않은 대상을 올바른 방향으로 이끄는 외부 환경 설계를 뜻한다. 전선 묶음(Wiring Harness), 테스트 하네스, CI/CD 파이프라인이 모두 같은 원리다. Act Operator는 이 개념을 AI 에이전트 개발에 적용해 세 개 레이어로 구현한다.

레이어 1 — 스캐폴딩(Scaffolding)

uvx --from act-operator act new 명령 하나로 프로젝트 뼈대를 생성한다. 모듈 컨벤션과 베이스 클래스가 처음부터 구조에 내장된다. 프로젝트(Act)와 그래프 단위(Cast)의 개념을 분리해, 하나의 Act 안에 여러 Cast를 모노레포 형태로 관리할 수 있다. StateGraph 하나가 Cast 하나에 대응하는 구조다.

레이어 2 — 실행 가능한 단일 진실 공급원(Executable SSOT)

컨벤션을 문서가 아닌 살아있는 파일로 관리하는 게 핵심이다. 세 가지 형태로 구현된다.

• Act Template: CI 워크플로우, 베이스 클래스, 테스트 구조, 설정 파일 등 프로젝트 컨벤션 전체
• Agent Skills: 에이전트가 이 구조 안에서 올바르게 추론할 수 있도록 설계된 50개 이상의 패턴 모음. .claude/skills/ 디렉토리에 위치하며, 스킬 이름을 언급하는 것만으로 활성화된다
• Drawkit: 팀이 아키텍처 다이어그램을 공통 시각 언어로 소통할 수 있는 도구

레이어 3 — 피드백 루프(Feedback Loop)

CLAUDE.md 파일이 세션 간 영속적 메모리 역할을 한다. 아키텍처 다이어그램, 노드 스펙, 개발 명령이 이 파일에 누적된다. 에이전트는 다음 세션에서 이 파일을 읽어 이전 설계를 이어받는다. 세션이 바뀌어도 아키텍처 지식이 증발하지 않는다.

실제 사용 흐름

# 프로젝트 생성 (Python 3.11+ 필요)
uvx --from act-operator act new

# 의존성 설치
uv sync

# Claude Code로 시작
claude
# 또는 OpenCode 사용 시
opencode .

Claude Code 외에 Cursor, Gemini CLI 등 스킬 디렉토리를 지원하는 다른 AI 도구도 사용 가능하다. 다만 이 경우 .claude 디렉토리를 해당 도구의 컨벤션에 맞게 이름을 바꿔줘야 한다.

실전에서 주의할 점

• 컨벤션은 코드베이스에 내재화되어야 한다. 팀 위키나 노션 문서에 컨벤션을 쌓아봐야 에이전트는 읽지 못한다. CLAUDE.md처럼 에이전트가 런타임에 직접 참조할 수 있는 형태여야 의미가 있다.

• 스킬 활성화는 명시적으로 해야 한다. .claude/skills/의 스킬은 자동으로 적용되지 않는다. @architecting-act 같이 스킬 이름을 직접 언급해야 활성화된다. 팀원들이 이 사실을 모르면 스킬 레이어가 있으나 마나가 된다.

• 프로토타입 구조를 프로덕션에 그대로 쓰지 마라. Act Operator는 명시적으로 "프로토타입이 아닌 실제 제품을 위해 설계"되었다고 밝힌다. 기존에 빠르게 만든 LangGraph 프로젝트를 이 구조로 마이그레이션할 때는 Cast 단위 분리와 베이스 클래스 상속 구조를 처음부터 재검토해야 한다.

• OpenCode 사용 시 환경변수 설정을 확인하라. langgraph.json에서 env: ".env"로 설정이 구성되며, 프로젝트 루트의 .env 파일을 읽는다. 이 경로가 어긋나면 에이전트 실행 시 환경변수 누락 오류로 디버깅 시간을 낭비하게 된다.