diff --git a/README.md b/README.md index e8c407e..49ba440 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,13 @@ Windows 전용 시맨틱 런처 & 워크스페이스 매니저 개발 참고: Claw Code 동등성 작업 추적 문서 `docs/claw-code-parity-plan.md` +구조 비교 참고 문서 +`docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md` + +- 업데이트: 2026-04-09 10:20 (KST) +- `claude-code`와 AX Agent의 구조/루프/메모리/도구 실행 전략을 한 문서에서 대조할 수 있도록 `docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md`를 추가했습니다. +- 문서는 `claude-code`의 에이전트 루프, Cowork/Code 결과 품질이 잘 나오는 이유, 성능에 영향을 주는 프롬프트 전략과 AX Agent의 현재 구조/강점/남은 차이를 함께 정리합니다. + - 업데이트: 2026-04-07 09:19 (KST) - AX Agent 하단 상태바의 전체 토큰 집계가 유휴 전환 후 사라지지 않도록 conversation aggregate 복원 경로를 추가했습니다. 실행 중 누적 토큰이 0이어도 현재 대화 전체의 prompt/completion 합계를 다시 계산해 상태바에 유지합니다. - 컨텍스트 사용량 팝업이 마지막 실제 압축 결과와 맞지 않던 문제를 수정했습니다. 이제 최근 압축의 실제 before/after 토큰과 자동/수동 여부, 누적 압축 횟수와 절감 토큰을 기준으로 표시합니다. diff --git a/docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md b/docs/CLAUDE_CODE_AX_AGENT_COMPARISON.md new file mode 100644 index 0000000..f1522b1 --- /dev/null +++ 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 적용 위치, 완료 조건, 품질 판정 기준을 같이 적는다 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 403eb22..d84168f 100644 --- 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.