Challenging Point Of Orchestration & Claude Code의 해결책
1. 오케스트레이션 흐름 및 제어 (Orchestration Flow & Control)
Q. 도구 함수의 호출 결과 자체가 전체 응답을 반환하는 경우도 있고, 중간 응답이 있는 경우도 있는데 Orchestrator 관점에 있어서 무엇이 제일 효과적인가?
- Claude Code의 해결책: 비동기 제너레이터(Generator) 패턴을 활용한 스트리밍 쿼리 루프를 사용합니다. 모든 결과를 기다렸다가 한 번에 반환하지 않고, API 응답이 글자 단위로 도착하는 즉시 화면에 표시하며, 도구 사용(Tool Use) 블록이 감지되면 즉시 실행하고 결과를 다시 API에 던지는 루프(Turn)를 반복합니다. 즉, 중간 응답을 실시간 스트리밍으로 쪼개서 처리하는 것이 속도와 사용자 경험 면에서 가장 효과적이라고 판단했습니다.
Q. 여러개의 함수 호출이 필요할 때 병렬이 가능한 것과 순차 실행이 가능한 것은 어떻게 구별하는가?
- Claude Code의 해결책: 도구별로 isConcurrencySafe() 속성을 정의하고 '파티셔닝 알고리즘'을 사용합니다. 읽기(Read), 검색(Grep) 등 안전한 도구는 최대 10개까지 배치를 묶어 병렬 실행하고, 편집(Edit), 셸 실행(Bash) 등 비안전 도구를 만나면 새 배치를 시작해 해당 도구만 순차적으로 단독 실행하여 충돌을 막습니다.
Q. 피드백 루프 진행 중 중지를 수행할 경우, 어떻게 다음 흐름을 진행하는가?
- Claude Code의 해결책: 쿼리 루프 시작 직전(사용자 메시지 입력 직후)에 대화 기록(Transcript)을 디스크에 우선 저장하는 'Interruption Resilience(중단 회복성)' 패턴을 씁니다. 중간에 프로세스가 강제 종료(Ctrl+C 등)되더라도 다음 실행 시 디스크에서 마지막 메시지를 읽어와 복구할 수 있습니다.
Q. 각 단계의 중간 검토를 어떤 방식으로 수행하는가?
- Claude Code의 해결책: 코디네이터(Coordinator) 모드와 훅(Hook) 시스템을 결합합니다.
- 리더(Leader) 에이전트가 작업을 분배하고, 워커(Worker)들이 병렬 처리 후 결과를 가져오면 리더는 "반드시 워커의 결과를 직접 읽고 이해(Synthesis)"하여 검토합니다. (AI의 자체 위임 불가 원칙)
- PreToolUse, PostToolUse 훅(Hook)을 통해 시스템적으로 차단(Block)하거나, 오류 발생 시 실패 메시지를 그대로 흐름에 주입해 스스로 고치게(Ralph Loop) 유도합니다.
2. 도구(Tool) 시스템 설계 (Tool System Design)
Q. Tool의 공통 포맷은 어떻게 구성되어 있나?
- Claude Code의 해결책: 모든 도구는 오케스트레이션과 제어를 위해 동일한 인터페이스(Zod 기반 구조)를 따릅니다.
- 핵심 동작 속성: name, inputSchema(파라미터 검증), description()(AI에게 용도 설명), call()(실제 실행 함수).
- 안전성 및 제어 속성: checkPermissions()(실행 권한 확인), validateInput()(의미론적 검증).
- 상태 및 오케스트레이션 속성: isConcurrencySafe()(병렬 실행 안전 여부), isReadOnly()(상태 변경 여부), maxResultSizeChars(결과 크기 디스크 저장 임계치).
3. UI 및 사용자 경험 (UI & UX)
Q. 특별한 UI 처리(multi select, select, graph 등)는 어떻게 처리하는가?
- Claude Code의 해결책: 터미널 환경임에도 React 기반의 자체 TUI 프레임워크(Ink)를 사용하여 선언적으로 처리합니다. 웹 UI처럼 Select나 Autocomplete 같은 복잡한 상호작용은 컨텍스트 기반 키바인딩 시스템(상황에 따라 Tab, Esc, Up/Down 키 매핑 전환)과 결합하여 구현하며, 진행 상태나 파일 변경(Diff) 화면도 React 컴포넌트로 분리하여 상태(State)가 변할 때 터미널의 필요한 부분만 다시 렌더링(Reconciliation)하도록 설계했습니다.
Q. 함수의 중간 응답을 어떻게 효과적으로 보여주는가? 일반 응답이 아닌 다른 유형으로 접기/펼치기 형식으로 보여주는가?
- Claude Code의 해결책: React 기반의 TUI 환경을 적극 활용합니다. 도구 실행 시 [Read] auth.ts, [Edit] auth.ts와 같이 진행 상태를 가시적으로 보여주며, 내부적으로는 토큰과 화면 공간 절약을 위해 'Microcompact' 기능을 통해 도구 사용 블록을 인라인으로 축소(접기/요약)하여 터미널 히스토리를 효과적으로 관리합니다.
4. 컨텍스트 및 메모리 관리 (Context & Memory)
Q. 도구 함수의 호출 결과가 너무 길 경우, History의 문맥을 오염시키는데 어떻게 해결하는가?
- Claude Code의 해결책: 두 가지 전략을 혼합하여 사용합니다.
- 점진적 공개 및 파일 참조: 도구 실행 결과가 임계치(MaxResultSize)를 초과하면 전체 텍스트를 LLM에 넘기지 않고 디스크 파일로 저장한 뒤 그 참조(Reference)만 넘깁니다.
- 자동 압축(Auto-Compact): 토큰 한계(Context Window - 13,000)에 근접하면 전체 대화를 백그라운드 서브에이전트가 요약하게 한 뒤, 오래된 메시지를 통째로 지우고 요약본으로 대체합니다(Snip Compact).
Q. 며칠이 지나도 사용자의 선호도나 프로젝트 룰을 AI가 잊지 않게 하려면 어떻게 해야 하는가?
- Claude Code의 해결책: 단발성 세션 컨텍스트와 별개로 영속적인 메모리(Memory) 시스템을 구축합니다. .claude/projects/.../memory/ 폴더에 MEMORY.md를 인덱스로 하여 사용자 역할, 프로젝트 피드백, 참조 정보 등을 마크다운으로 분리 저장합니다. 다음 세션 시작 시 이 메모리를 자동으로 컨텍스트에 주입하여 맥락을 지속 유지합니다.
5. 안정성, 통제 및 예외 처리 (Safety, Control & Error Handling)
Q. AI가 위험한 시스템 명령(rm -rf 등)을 임의로 실행하지 못하게 하려면 어떻게 통제해야 하는가?
- Claude Code의 해결책: 세밀한 권한(Permission) 시스템을 적용합니다. 자동 모드에서는 2단계 AI 분류기(Fast + Thinking)를 통해 위험도를 평가하고 안전한 것만 통과시킵니다. 특히 셸(Bash) 명령어의 경우 Tree-sitter 파서로 AST 구조를 분석하여 허용 목록에 있는 구문만 통과시키는 "기본 거부(fail-closed)" 방식을 채택해 보안을 강화했습니다.
Q. API 토큰 한도 초과(413 Error 등)나 Rate Limit이 발생했을 때 에이전트 프로세스가 뻗지 않게 하려면?
- Claude Code의 해결책: 에러를 사용자에게 바로 노출하지 않고 내부적으로 **'에러 보류와 복구(Error Withholding & Recovery)'**를 시도합니다. 413 에러 시 즉시 컨텍스트 축소 및 자동 압축을 시도하고, 최대 출력 토큰 초과 시 한도를 8K에서 64K로 에스컬레이션하며 재시도합니다. Rate Limit의 경우 대기 후 재시도하거나 다른 모델로 폴백(Fallback)하는 유연한 전략을 가집니다.
출처
별첨 91. 클로드 코드 소스 코드 분석서 - 클로드 코드 가이드
최근댓글