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 적용 위치, 완료 조건, 품질 판정 기준을 같이 적는다