AX-Copilot-Codex/docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md

claude-code / AX Agent 구조 비교 문서

업데이트: 2026-04-09 10:20 (KST)

이 문서는 AX Agent를 claude-code 동등 품질 기준으로 유지·검증하기 위한 비교 기준 문서입니다. 실제 비교 대상 저장 폴더명은 claw-code이지만, 문서 표기는 claude-code로 통일합니다.

1. claude-code 구조, 특징 기능, 에이전트 루프

1-1. 구조 핵심

claude-code는 크게 아래 축으로 나뉩니다.

1. 부트스트랩/세션 상태
   • src/bootstrap/state.ts
   • src/bridge/initReplBridge.ts
   • src/bridge/sessionRunner.ts
2. 메인 REPL/대화 화면
   • src/screens/REPL.tsx
   • src/components/Messages.tsx
   • src/components/VirtualMessageList.tsx
   • src/components/StatusLine.tsx
3. 도구 실행 계층
   • src/services/tools/toolOrchestration.ts
   • src/services/tools/StreamingToolExecutor.ts
4. 메모리/컨텍스트/권한
   • 04_작동원리.md
   • 05_메모리와컨텍스트.md
   • 06_권한시스템.md
   • 15_스킬.md

1-2. 특징 기능

claude-code의 강점은 기능 개수보다 실행 품질에 있습니다.

• 대화, 도구 실행, 권한, 상태줄이 한 흐름으로 이어진다.
• transcript가 단순 채팅 로그가 아니라 실행 관측 UI 역할을 한다.
• 도구 호출이 응답 후처리가 아니라 루프 자체의 핵심 경로다.
• read-only 도구는 병렬화하고, non-concurrent 도구는 직렬화해 체감 반응성을 높인다.
• 메모리 구조가 managed / user / project / local 계층으로 명확하다.
• CLAUDE.md, .claude/rules/*.md, paths: frontmatter, @include 같은 규칙 기반 메모리 주입이 강하다.
• 권한 시스템이 default / acceptEdits / plan / bypassPermissions와 allow/deny rule로 분리되어 있다.
• skill 시스템이 단순 프롬프트 스니펫이 아니라 재사용 가능한 워크플로우 레이어다.

1-3. 에이전트 루프 구조

claude-code의 기본 루프는 다음 순서에 가깝습니다.

1. 사용자 메시지 수신
2. 시스템 컨텍스트 조립
   • Git 상태
   • 메모리 계층
   • 현재 날짜/환경
   • 사용 가능한 도구/권한 상태
3. 모델 호출
4. tool_use block 감지
5. 권한 판단
6. 도구 실행
7. tool_result를 다시 모델에 투입
8. 필요 시 추가 도구 호출
9. 최종 텍스트 응답 커밋

중요한 점은, 이 루프가 단순히 "LLM 호출 후 도구 실행"이 아니라 도구를 전제로 설계된 루프라는 점입니다.

1-4. Cowork/Code에서 결과가 잘 나오는 이유

1. 도구 우선 오케스트레이션

• toolOrchestration.ts가 tool call을 배치로 나누고
• StreamingToolExecutor.ts가 스트리밍 도중에도 도구 실행 준비를 진행합니다.
• read-only/concurrency-safe 도구는 병렬 실행해 첫 반응 시간을 줄입니다.

2. 실행 중 관측성이 높음

• Messages.tsx
• VirtualMessageList.tsx
• StatusLine.tsx

이 구조 덕분에 사용자는 "지금 무엇을 읽고, 무엇을 실행하고, 어디서 멈췄는지"를 계속 볼 수 있습니다. 긴 작업에서도 멈춘 것처럼 느껴지지 않는 이유가 여기 있습니다.

3. 긴 세션을 버티는 transcript 구조

• transcript는 전체 렌더를 계속 다시 그리지 않습니다.
• VirtualMessageList.tsx 기준으로 가시 영역 중심 렌더와 스크롤/탐색 보조 구조가 분리되어 있습니다.
• 긴 세션, 많은 도구 호출, 많은 중간 상태에서도 UI 부하가 상대적으로 낮습니다.

4. 메모리와 규칙 주입이 명시적

• CLAUDE.md
• .claude/rules/*.md
• paths:
• @include

이 구조 때문에 프로젝트/경로/사용자/관리자 규칙이 프롬프트에 일관되게 들어갑니다. 결과가 흔들릴 때도 "왜 그런 성향이 나왔는지" 추적이 쉽습니다.

1-5. 주요 성능과 품질에 영향을 주는 프롬프트 전략

1. 도구를 먼저 쓰게 만드는 직접적인 지시
2. 컨텍스트를 계층화해서 넣음
3. 권한과 도구 사용 범위를 명확히 분리
4. 실행 중간 상태를 계속 보여줘 재시도/복구가 자연스러움
5. read-only tool 병렬화로 초기 탐색 시간을 줄임
6. transcript/상태줄이 실제 실행 관측 수단으로 동작

2. AX Agent 구조, 특징 기능, 에이전트 루프

2-1. 구조 핵심

현재 AX Agent는 다음 축으로 구성됩니다.

1. 에이전트 실행
   • src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs
   • src/AxCopilot/Services/Agent/AgentLoopService.cs
   • src/AxCopilot/Services/Agent/StreamingToolExecutionCoordinator.cs
2. 루프 정책 분리 계층
   • src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs
   • src/AxCopilot/Services/Agent/AgentLoopTransitions.Verification.cs
   • src/AxCopilot/Services/Agent/AgentLoopTransitions.Documents.cs
   • src/AxCopilot/Services/Agent/AgentLoopCompactionPolicy.cs
   • src/AxCopilot/Services/Agent/AgentLoopRuntimeThresholds.cs
3. 메모리 구조
   • src/AxCopilot/Services/AgentMemoryService.cs
   • src/AxCopilot/Services/Agent/MemoryTool.cs
4. transcript/UI 구조
   • src/AxCopilot/Views/ChatWindow.xaml.cs
   • src/AxCopilot/Views/ChatWindow.TranscriptHost.cs
   • src/AxCopilot/Views/ChatWindow.TranscriptRendering.cs
   • src/AxCopilot/Views/ChatWindow.TranscriptRenderPlanner.cs
   • src/AxCopilot/Views/ChatWindow.TranscriptRenderExecution.cs
   • src/AxCopilot/Views/ChatWindow.TranscriptVirtualization.cs
5. 성능/검증 로그
   • src/AxCopilot/Services/AgentPerformanceLogService.cs

2-2. 특징 기능

• Chat / Cowork / Code를 한 창에서 운영
• 등록 모델별 실행 프로파일 지원
• Cowork/Code 전용 agent loop 사용
• 문서 생성 계열 fallback 및 verification gate 지원
• IBM/vLLM/OpenAI 호환 tool-use 경로 대응
• 계층형 메모리 구조 지원
• /memory 계열 도구와 설정 UI에서 메모리 관리 가능
• transcript/진행 표시/UI 구조를 claude-code 기준으로 계속 분해해온 상태

2-3. 에이전트 루프 구조

현재 AX Agent의 루프는 대략 아래 순서입니다.

1. 실행 컨텍스트 구성
2. 사용자 메시지와 시스템 지시 조립
3. LLM 호출
4. tool call 감지
5. StreamingToolExecutionCoordinator를 통한 조기 도구 실행/prefetch
6. 도구 결과 재투입
7. verification/document fallback/compact 정책 수행
8. 최종 결과 커밋
9. transcript/status/perf 로그 반영

2-4. 현재 구조적 강점

1. 모델 프로파일 기반 제어
2. 계층형 메모리 구조
3. Cowork/Code용 별도 실행 정책
4. 성능 계측 로그

2-5. 현재 구조적 약점

1. ChatWindow.xaml.cs 책임이 여전히 큼
2. transcript가 아직 완전한 데이터 기반 가상화는 아님
3. 루프 정책이 여전히 서비스 중심
4. tool streaming executor가 독립 계층으로 강화되었지만 결합이 남음

3. claude-code와 AX Agent 비교

3-1. 전체 비교 요약

항목	claude-code	AX Agent 현재 상태
메모리 계층	매우 강함	많이 근접
tool orchestration	매우 강함	많이 강화됨
transcript 가상화	강함	부분 근접
진행 관측성	강함	많이 근접
모델 프로파일성	단단함	프로파일 시스템 도입 완료
문서 fallback	비교적 단순/직접적	더 많은 정책 보유
루프 응집도	모듈 분리 우수	개선 중, 많이 나아짐

3-2. AX Agent가 이미 따라잡은 부분

1. 메모리 계층 구조
2. 진행 표시 UX
3. 모델별 실행 성향 제어
4. 도구 호출 강화

3-3. AX Agent가 아직 더 개선할 수 있는 부분

1. transcript의 진짜 가상화
2. UI 렌더의 data-template화
3. tool executor의 독립성
4. Cowork/Code 실사용 로그 기반 검증 체계

3-4. 성능과 결과 품질에 직접 영향이 큰 구조 요소 비교

claude-code 쪽 핵심

• read-only tool 병렬화
• streaming executor
• transcript 가상화
• 상태줄/메시지/도구 실행 분리
• 명시적 메모리 계층
• 권한 시스템과 루프의 강한 연결

AX Agent 쪽 핵심

• 모델 프로파일
• document/verification/compact 정책 분리
• IBM/vLLM 도구 호출 보강
• transcript host/windowing/virtualization 보강
• WPF 환경 특화 성능 대응

3-5. 현 시점 결론

현 시점 AX Agent는 claude-code 대비 다음 상태로 보는 것이 적절합니다.

• 구조적 방향성: 거의 동일한 방향
• 메모리/도구/진행 표시: 상당 부분 근접
• transcript/렌더 구조: 아직 한 단계 차이 존재
• 장기 세션 성능: 실제 로그 기반 추가 검증 필요

즉 AX Agent는 더 이상 "기본 구조가 부족한 상태"는 아니고, 이제부터는 실사용 검증 기반으로 남은 구조 차이를 줄이는 단계입니다.

4. AX 개발 시 이 문서를 어떻게 쓸지

1. Cowork/Code 품질 이슈가 생기면 먼저 claude-code 기준 흐름과 비교
2. 구조 리팩터링이 필요할 때 transcript / tool executor / loop policy / memory 중 어디를 건드리는지 먼저 분류
3. 실사용 성능 검증 시 %APPDATA%\\AxCopilot\\perf 로그와 loop elapsed, transcript render elapsed, no-tool loop, verification/fallback/compact 비율을 함께 본다
4. 계획 수립 시 항상 참조 파일, AX 적용 위치, 완료 조건, 품질 판정 기준을 같이 적는다