문서: claude-code와 AX Agent 구조 비교 기준 문서 추가

- claude-code 구조, 특징 기능, 에이전트 루프, Cowork/Code 결과 품질 요인, 프롬프트 전략을 정리한 비교 문서 추가 - AX Agent 구조, 실행 계층, 메모리/도구/transcript 구조와 현재 강점·약점을 정리 - README와 DEVELOPMENT 문서에 신규 비교 문서와 업데이트 이력 반영 - 검증: dotnet build src/AxCopilot/AxCopilot.csproj -c Release -v minimal -p:OutputPath=bin\\verify\\ -p:IntermediateOutputPath=obj\\verify\\ (경고 0 / 오류 0)
2026-04-09 01:09:21 +09:00
parent 0ceca202e9
commit 4f3c19c15c
3 changed files with 246 additions and 0 deletions
--- a/docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md
+++ b/docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md
@@ -0,0 +1,238 @@
+# 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 적용 위치, 완료 조건, 품질 판정 기준을 같이 적는다
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -5558,3 +5558,4 @@ ow + toggle ?쒓컖 ?몄뼱濡??ㅼ떆 ?뺣젹?덈떎.
 - [AgentLoopService.cs](/E:/AX%20Copilot%20-%20Codex/src/AxCopilot/Services/Agent/AgentLoopService.cs)
  - 루프 finally 단계에서 `run_summary` 성능 로그를 남기도록 보강했다.
  - iteration 수, tool 호출 수, 토큰 사용량, post-compaction suppression 수치가 함께 기록돼 사내 모델에서 `느린데 왜 느린지`를 나중에 역추적할 수 있다.
+- Document update: 2026-04-09 10:20 (KST) - Added `docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md` as a new baseline document for architecture and parity reviews. It summarizes `claude-code` structure, loop, transcript/tool orchestration, prompt-quality strategy, AX Agent structure and loop, and a current comparison between both implementations.