# AX Copilot 기술 및 구현 현황 종합 문서

> **작성일**: 2026-04-03
> **앱 버전**: v1.8.0 (내부 Phase: v2.3)
> **프레임워크**: .NET 8.0 WPF (win-x64)

---

## 1. 프로젝트 개요

AX Copilot은 **AI 기반 업무 자동화 데스크톱 앱**으로, 두 가지 핵심 컴포넌트로 구성됩니다:

| 컴포넌트 | 명칭 | 역할 |
|---------|------|------|
| **런처** | AX Commander | 키보드 기반 명령 실행 (Alfred/Raycast 대응) |
| **AI 대화** | AX Agent | LLM 기반 에이전트 코딩/코워크/채팅 (Claude Code/Cursor 대응) |

### 핵심 수치

| 항목 | 수량 |
|------|------|
| 에이전트 도구 (IAgentTool) | **64개** |
| 런처 핸들러 (IHandler) | **44개** |
| 내장 스킬 (.skill.md) | **40개** |
| 슬래시 명령 (/command) | **15개** |
| 대화 프리셋 | **20개** |
| 테마 | **10개** |
| 윈도우/뷰 | **27개** (+ 컨트롤 4개) |
| NuGet 의존성 | **7개** |
| 훅 이벤트 타입 | **18종** |
| 훅 실행 모드 | **4종** |

---

## 2. 아키텍처

### 2.1 계층 구조

```
┌─────────────────────────────────────────────────────────┐
│  UI 계층 (Views / ViewModels)                            │
│  · ChatWindow (3-Pane: 사이드바 + 채팅 + 설정 패널)       │
│  · LauncherWindow (Alfred/Raycast 스타일 명령 팝업)       │
│  · SettingsWindow, DockBarWindow, CommandPaletteWindow 등 │
├─────────────────────────────────────────────────────────┤
│  서비스 계층 (Services)                                   │
│  · AgentLoopService (에이전트 루프 엔진)                   │
│  · LlmService (LLM API 통합)                             │
│  · McpClientService (MCP stdio 프로토콜)                  │
│  · SkillService, PresetService, HookRunner 등             │
├─────────────────────────────────────────────────────────┤
│  도메인 계층 (Tools / Handlers / Models)                  │
│  · 64개 IAgentTool 구현체                                 │
│  · 44개 IHandler 구현체 (런처 핸들러)                      │
│  · AppSettings, ChatModels, McpSettings                  │
├─────────────────────────────────────────────────────────┤
│  인프라 계층 (External)                                   │
│  · LLM API (Ollama / Gemini / Claude)                    │
│  · MCP 서버 (stdio JSON-RPC 2.0)                         │
│  · LSP 서버 (Language Server Protocol)                    │
│  · 파일 시스템, Git, SQLite                               │
└─────────────────────────────────────────────────────────┘
```

### 2.2 핵심 디자인 패턴

| 패턴 | 적용 위치 | 설명 |
|------|----------|------|
| **Strategy** | IAgentTool, IHookExecutor | 도구/훅 타입별 전략 분리 |
| **Observer** | AgentEventOccurred, HookRunner | 에이전트 이벤트 발행/구독 |
| **Factory** | ToolRegistry.CreateDefault() | 도구 인스턴스 생성 중앙화 |
| **Chain of Responsibility** | PermissionSystem | 권한 규칙 체인 평가 |
| **Command** | ISlashCommand, SlashCommandRegistry | 슬래시 명령 실행 |
| **Repository** | HierarchicalMemoryService | 계층적 메모리 CRUD |
| **Decorator** | IConditionalTool 래핑 | 도구 활성화 조건 동적 평가 |

### 2.3 SOLID 원칙 적용

- **SRP**: 에이전트 도구 1파일 = 1클래스, 카테고리별 폴더 분리
- **OCP**: `IAgentTool` + `ToolRegistry` — 기존 코드 수정 없이 새 도구 등록
- **LSP**: 모든 `IAgentTool` 구현체 교환 가능, `ToolResult.Ok()`/`Fail()` 규약 일관
- **ISP**: `IAgentTool`(Execute/Parameters/Name만), `IConditionalTool`(IsEnabled만) 분리
- **DIP**: `AgentLoopService` → 인터페이스만 의존, `AgentContext.Settings`로 DI

---

## 3. LLM 통합

### 3.1 지원 서비스

| 서비스 | 프로토콜 | 특징 |
|--------|---------|------|
| **Ollama** | REST API (로컬) | 사내망 LLM 서버, 무제한 호출 |
| **vLLM** | OpenAI 호환 API | 고성능 로컬 추론 서버 |
| **Google Gemini** | REST API (클라우드) | 무료 티어 지원, 이미지 입력 |
| **Anthropic Claude** | REST API (클라우드) | SSE 스트리밍, 고급 추론 |

### 3.2 LlmService 핵심 API

```csharp
// 동기 호출
Task<string> SendAsync(List<ChatMessage> messages, CancellationToken ct);

// SSE 스트리밍 (실시간 토큰 출력)
IAsyncEnumerable<string> StreamAsync(List<ChatMessage> messages, CancellationToken ct);

// Function Calling (도구 사용)
Task<(string Response, List<ContentBlock> ToolCalls)> SendWithToolsAsync(
    List<ChatMessage> messages, List<ToolDefinition> tools, CancellationToken ct);

// 토큰 사용량 추적
TokenUsage? LastTokenUsage { get; }
```

### 3.3 모델 라우팅

- **ModelRouterService**: 작업 유형(코딩/문서/분석)에 따라 최적 모델 자동 선택
- **FallbackModels**: 주 모델 실패 시 대체 모델 목록 순차 시도
- **FreeTierMode**: 무료 API 제한 시 자동 지연 (4초 쿨다운)

### 3.4 컨텍스트 관리

| 기능 | 구현 |
|------|------|
| **토큰 추정** | TokenEstimator — CJK 가중치 적용 로컬 추정 |
| **자동 압축** | AutoCompactMonitor — 임계치(80%) 초과 시 자동 컨텍스트 요약 |
| **컨텍스트 축소** | ContextCondenser — 대화 내 도구 결과/중복 제거 60% 목표 |
| **출력 예산** | ToolResultSizer — 도구 결과 4,000자 자동 절삭 |

---

## 4. 에이전트 시스템

### 4.1 AgentLoopService (핵심 에이전트 루프)

```
사용자 입력 → 시스템 프롬프트 조립 → LLM 호출 → 도구 호출 파싱
    ↓
도구 실행 (권한 확인 → 훅 실행 → 도구 Execute → 결과 검증)
    ↓
결과를 메시지에 추가 → LLM 재호출 (반복)
    ↓
종료 조건: 도구 미호출 / 최대 반복 / 사용자 중단
```

**핵심 파라미터**:

| 상수 | 기본값 | 설명 |
|------|--------|------|
| MaxIterations | 25 | 최대 에이전트 반복 횟수 |
| MaxRetryOnError | 3 | 도구 오류 시 재시도 |
| MaxTestFixIterations | 5 | 테스트-수정 루프 최대 반복 |
| AutoCompactThresholdPercent | 80 | 컨텍스트 자동 압축 임계치 |
| ToolResultTruncateLength | 4,000 | 도구 결과 최대 길이 |

### 4.2 에이전트 도구 (64개)

#### 파일 시스템 (11개)
| 도구 | 설명 |
|------|------|
| FileReadTool | 파일 읽기 (라인 범위 지정) |
| FileWriteTool | 파일 생성/덮어쓰기 |
| FileEditTool | 정확한 문자열 치환 편집 |
| FileInfoTool | 파일 메타데이터 조회 |
| FileManageTool | 복사/이동/삭제/이름변경 |
| MultiReadTool | 여러 파일 동시 읽기 |
| FolderMapTool | 디렉토리 트리 구조 |
| GlobTool | 파일 패턴 검색 |
| GrepTool | 정규식 콘텐츠 검색 |
| FileWatchTool | 파일 변경 감시 |
| ZipTool | 압축/해제 |

#### 코드 개발 (8개)
| 도구 | 설명 |
|------|------|
| GitTool | Git 명령 실행 (status, diff, commit 등) |
| LspTool | LSP 분석 (정의/참조/진단) |
| CodeReviewTool | AI 코드 리뷰 |
| CodeSearchTool | 의미론적 코드 검색 (TF-IDF) |
| BuildRunTool | 빌드/테스트 실행 |
| TestLoopTool | 자동 테스트-수정 반복 |
| DiffTool | 파일 비교 |
| DiffPreviewTool | Diff 미리보기 UI |

#### 문서 생성 (9개)
| 도구 | 설명 |
|------|------|
| DocxSkill | Word 문서 생성 (OpenXML) |
| ExcelSkill | Excel 스프레드시트 생성 |
| PptxSkill | PowerPoint 프레젠테이션 생성 |
| HtmlSkill | HTML 페이지 생성 |
| MarkdownSkill | Markdown 문서 생성 |
| CsvSkill | CSV 파일 처리 |
| DocumentPlannerTool | 다중 패스 문서 설계 |
| DocumentAssemblerTool | 문서 조립/병합 |
| DocumentReaderTool | 문서 파싱 (PDF/DOCX) |

#### 데이터 처리 (7개)
| 도구 | 설명 |
|------|------|
| JsonTool | JSON 파싱/변환/쿼리 |
| XmlTool | XML 처리 |
| SqlTool | SQLite 쿼리 실행 |
| DataPivotTool | 데이터 피벗/집계 |
| ChartSkill | 차트 생성 |
| RegexTool | 정규식 매칭/치환 |
| FormatConvertTool | 형식 변환 |

#### 에이전트/자동화 (10개)
| 도구 | 설명 |
|------|------|
| SubAgentTool | 서브 에이전트 위임 실행 |
| PlaybookTool | 워크플로우 자동 실행 |
| SkillManagerTool | 스킬 관리 (목록/재로드) |
| MemoryTool | 에이전트 메모리 CRUD |
| ProjectRuleTool | 프로젝트 규칙 관리 |
| TaskTrackerTool | 작업 추적/체크리스트 |
| CheckpointTool | 체크포인트 생성/복원 |
| SuggestActionsTool | 다음 행동 추천 |
| UserAskTool | 사용자 질문/확인 |
| NotifyTool | 사용자 알림 발송 |

#### 유틸리티 (10개)
| 도구 | 설명 |
|------|------|
| HttpTool | HTTP 요청 (GET/POST) |
| McpTool | MCP 서버 도구 호출 |
| ProcessTool | 셸 명령 실행 |
| ClipboardTool | 클립보드 읽기/쓰기 |
| ImageAnalyzeTool | 이미지 분석 (멀티모달) |
| Base64Tool | Base64 인코딩/디코딩 |
| HashTool | 해시값 계산 |
| EncodingTool | 파일 인코딩 감지/변환 |
| MathTool | 수학 연산 |
| DateTimeTool | 날짜/시간 계산 |

#### 기타 (9개)
| 도구 | 설명 |
|------|------|
| DocumentReviewTool | 문서 품질 검토 |
| DevEnvDetectTool | 개발 환경 감지 |
| EnvTool | 환경변수 관리 |
| TemplateRenderTool | Mustache 템플릿 렌더링 |
| TextSummarizeTool | 텍스트 요약 |
| SnippetRunnerTool | 코드 스니펫 실행 |
| OpenExternalTool | 외부 프로그램 열기 |
| BatchSkill | 대량 파일 처리 |
| DelegateAgentTool | 특정 작업 위임 |

### 4.3 Plan 모드

| 모드 | 동작 |
|------|------|
| **Off** | 즉시 실행 (계획 없이) |
| **Auto** | 복잡한 작업 시 자동 계획 수립 |
| **Always** | 모든 작업에 계획 수립 후 사용자 승인 |

Plan 모드에서는 `document_plan` 도구로 단계별 실행 계획을 생성하고, PlanViewerWindow에서 시각화합니다.

### 4.4 권한 시스템 (PermissionSystem)

| 모드 | 설명 |
|------|------|
| **Ask** | 모든 파일 작업에 사용자 승인 요청 |
| **AcceptEdits** | 파일 편집은 자동 승인, bash/위험 도구는 확인 |
| **Auto** | 모든 도구 자동 실행 |
| **Deny** | 위험 도구 차단 |

**패턴 기반 규칙**: `Bash(git *)` 형태로 특정 명령만 허용/차단
**차단 경로**: 시스템 디렉토리, `.env` 등 민감 파일 패턴 차단

---

## 5. 훅 시스템

### 5.1 훅 이벤트 (18종)

| 카테고리 | 이벤트 |
|---------|--------|
| **도구 실행** | PreToolUse, PostToolUse, PostToolUseFailure |
| **세션** | SessionStart, SessionEnd, UserPromptSubmit |
| **에이전트** | AgentStop, Stop, SubagentStart, SubagentStop |
| **컨텍스트** | PreCompact, PostCompact, CwdChanged, ConfigChange |
| **파일** | FileChanged |
| **스킬** | PreSkillExecute, PostSkillExecute |
| **권한** | PermissionRequest |

### 5.2 훅 실행 모드 (4종)

| 모드 | 설명 | 예시 |
|------|------|------|
| **Command** | 외부 스크립트 실행 | `cmd /c lint.bat` |
| **Http** | HTTP POST 웹훅 | `https://hooks.slack.com/...` |
| **Prompt** | LLM 검사 (경량 모델) | "이 코드에 보안 이슈가 있나요?" |
| **Agent** | 미니 에이전트 루프 | 자동 코드 포맷팅 서브루프 |

### 5.3 훅 출력 기능

| 출력 타입 | 설명 |
|----------|------|
| `additionalContext` | LLM 컨텍스트에 추가 정보 주입 |
| `permissionDecision` | 권한 요청에 대한 자동 판단 |
| `updatedInput` | 사용자 입력 자동 수정 |

---

## 6. 스킬 시스템

### 6.1 SKILL.md 표준 형식

```markdown
---
name: report-writer
description: 보고서 자동 작성
tools: [file_write, file_read, grep]
model: gemini-2.0-flash
context: fork
paths: ["docs/**", "reports/**"]
arguments:
  topic:
    description: 보고서 주제
    required: true
---

# 시스템 프롬프트
당신은 보고서 작성 전문가입니다...
```

### 6.2 스킬 기능

| 기능 | 설명 |
|------|------|
| **context:fork** | 서브에이전트로 격리 실행 |
| **paths: glob** | 특정 경로에서만 자동 활성화 |
| **model: override** | 스킬별 최적 모델 지정 |
| **arguments** | 매개변수 치환 (`{{topic}}`) |
| **inline commands** | 인라인 명령 처리 |
| **namespacing** | 스킬 이름 충돌 방지 |

### 6.3 내장 스킬 (40개)

| 카테고리 | 스킬명 | 설명 |
|---------|--------|------|
| **문서** | report-writer, meeting-minutes, weekly-report, prd-generator, changelog, release-note, email-draft | 보고서/회의록/주간보고/PRD/변경이력/릴리즈노트/이메일 |
| **코드** | code-scaffold, refactor, gen-test, commit-review, security-audit, perf-audit, dependency-audit | 스캐폴딩/리팩터링/테스트생성/커밋리뷰/보안점검/성능감사/의존성감사 |
| **데이터** | data-visualize, data-visualize-adv, xlsx-analyzer, csv-to-xlsx, data-convert, yield-analysis, sql-report | 시각화/분석/변환/수율분석/SQL보고서 |
| **변환** | docx-creator, pptx-creator, markdown-to-doc, json-schema, diagram-generator | 문서생성/프레젠테이션/스키마/다이어그램 |
| **분석** | paper-review, log-analyze, impact, ocr-extract, image-processor | 논문리뷰/로그분석/영향분석/OCR/이미지처리 |
| **유틸** | batch-rename, compare, env-setup, regex-helper, translate, api-docs, adr-writer, db-schema | 일괄이름변경/비교/환경설정/정규식/번역/API문서/ADR/DB스키마 |

---

## 7. MCP (Model Context Protocol) 통합

### 7.1 클라이언트 구현

```
App ──stdio──> MCP 서버 프로세스
     <──JSON-RPC 2.0──
```

- **프로토콜**: JSON-RPC 2.0 over stdio
- **서버 관리**: 프로세스 생명주기 관리 (시작/종료/재연결)
- **도구 검색**: `tools/list` 요청으로 서버 제공 도구 자동 등록
- **도구 실행**: `tools/call` 요청으로 원격 도구 호출

### 7.2 SDK 서버 (내장)

AX Copilot 자체가 MCP 서버로 동작하여 외부 MCP 클라이언트에 에이전트 도구를 제공:

| 컴포넌트 | 파일 | 역할 |
|---------|------|------|
| SdkProtocol | SdkProtocol.cs | JSON-RPC 프로토콜 정의 |
| AgentSdkServer | AgentSdkServer.cs | stdio 서버 실행 |
| AgentTypeRegistry | AgentTypeRegistry.cs | 도구 타입 등록 |
| SdkHookCallbackHandler | SdkHookCallbackHandler.cs | 훅 이벤트 외부 전달 |

---

## 8. 메모리 시스템

### 8.1 계층적 메모리 (4-Layer)

| 계층 | 범위 | 저장 위치 |
|------|------|----------|
| **Global** | 앱 전체 | `%APPDATA%\AxCopilot\memory\global.json` |
| **Project** | 프로젝트(폴더)별 | `{WorkFolder}\.ax\memory.json` |
| **Session** | 대화 세션별 | `%APPDATA%\AxCopilot\sessions\{id}\memory.json` |
| **Agent Type** | 에이전트 타입별 | `%APPDATA%\AxCopilot\memory\{type}.json` |

### 8.2 메모리 도구 (MemoryTool)

| 액션 | 설명 |
|------|------|
| `save` | 새 규칙/선호도 저장 |
| `search` | 키워드로 메모리 검색 |
| `list` | 모든 메모리 항목 목록 |
| `delete` | 특정 항목 삭제 |

### 8.3 @include 지시문

프로젝트 규칙 파일에서 외부 파일 참조:
```markdown
# AX.md
@include docs/coding-style.md
@include docs/api-conventions.md
```
- 최대 5단계 중첩 포함
- 순환 참조 자동 감지/방지

---

## 9. 슬래시 명령 (15개)

| 명령 | 설명 |
|------|------|
| `/compact` | 대화 컨텍스트 수동 압축 |
| `/clear` | 대화 초기화 |
| `/memory` | 에이전트 메모리 관리 |
| `/model` | 현재 모델 변경 |
| `/plan` | Plan 모드 전환 (off/auto/always) |
| `/commit` | Git 커밋 자동 생성 |
| `/review` | 코드 리뷰 실행 |
| `/mcp` | MCP 서버 상태/관리 |
| `/permissions` | 권한 모드 변경 |
| `/hooks` | 훅 등록/목록/삭제 |
| `/config` | 설정값 조회/변경 |
| `/skills` | 스킬 목록/실행 |
| `/help` | 명령어 도움말 |
| `/init` | 프로젝트 초기화 (AX.md 생성) |
| `/review` | PR/변경사항 리뷰 |

---

## 10. 런처 시스템 (AX Commander)

### 10.1 프리픽스 명령 체계

| 프리픽스 | 기능 | 핸들러 |
|---------|------|--------|
| `!` | AI 대화 시작 | ChatHandler |
| `?` | 웹 검색 | WebSearchHandler |
| `>` | 시스템 명령 | SystemCommandHandler |
| `=` | 계산기 | CalculatorHandler |
| `#` | 색상 변환 | ColorHandler |
| `@` | 퀵링크 | QuickLinkHandler |
| `$` | 환경변수 | EnvHandler |
| `/` | 즐겨찾기 | FavoriteHandler |
| `%` | 프로세스 관리 | ProcessHandler |
| `:` | 이모지 | EmojiHandler |
| `+` | 노트 | NoteHandler |
| `-` | 일괄 텍스트 처리 | BatchTextHandler |
| `~` | 별칭 | AliasHandler |
| `*` | 서비스 관리 | ServiceHandler |
| `^` | 클립보드 이력 | ClipboardHistoryHandler |
| `` ` `` | 코드 스니펫 | SnippetHandler |

### 10.2 주요 기능

| 기능 | 설명 |
|------|------|
| **퍼지 검색** | 앱/파일/설정 퍼지 매칭 |
| **파일 인덱싱** | 로컬 파일 TF-IDF 인덱스 |
| **클립보드 이력** | DPAPI 암호화 저장, 원본 이미지 품질 |
| **독 바** | 하단 퀵 액세스 바 |
| **셸 통합** | Windows Explorer 우클릭 메뉴 |
| **커맨드 팔레트** | VS Code 스타일 Ctrl+Shift+P |
| **AI 스니펫** | 프롬프트 기반 자동 텍스트 생성 |

---

## 11. UI/UX 시스템

### 11.1 AX Agent 3-Pane 레이아웃 (Claude.ai 스타일)

```
┌────────────────────────────────────────────────────────────────┐
│ [좌측 사이드바]  │  [메인 채팅 영역]       │ [우측 설정 패널]  │
│ 260px           │  가변                    │ 300px (토글)     │
│                 │                          │                  │
│ Chat│Cowork│Code│  세션 헤더 바             │  ⚙ 모델 & 서비스 │
│ ─────────────── │  (모델▾ Plan▾ 권한▾)      │  에이전트 동작    │
│ 프리셋 목록      │                          │  탭 전용 설정     │
│ ─────────────── │  메시지 스트림             │  도구 관리        │
│ [+ 새 대화]      │  (마크다운 렌더링)         │  MCP 서버        │
│ ─────────────── │                          │  프리셋            │
│ 대화 이력        │  입력 영역                │  고급              │
│ (날짜별 그룹)     │  (@멘션 /스킬 📎)         │                  │
└────────────────────────────────────────────────────────────────┘
```

### 11.2 테마 시스템 (10종)

| 테마 | 스타일 |
|------|--------|
| Dark | 기본 다크 테마 |
| OLED | 순흑 배경 AMOLED |
| Nord | 북극빛 색상 |
| Monokai | 개발자 인기 테마 |
| Catppuccin | 파스텔 다크 |
| Codex | OpenAI Codex 스타일 |
| Alfred | Alfred 앱 스타일 |
| Alfred Light | Alfred 라이트 변형 |
| Light | 기본 라이트 테마 |
| Sepia | 따뜻한 세피아 톤 |

### 11.3 커스텀 UI 규칙

- **기본 컨트롤 사용 금지**: ContextMenu → 커스텀 Popup, MessageBox → CustomMessageBox
- **테마 리소스 필수**: `ThemeResourceHelper.Primary(this)` 패턴으로 색상 조회
- **PopupMenuHelper**: 팝업 메뉴 생성 통합 헬퍼
- **ToggleSwitch 스타일**: 기본 CheckBox 대신 좌우 슬라이드 토글
- **아이콘**: Segoe MDL2 Assets 글리프 + 기능별 색상

### 11.4 애니메이션

| 동작 | 구현 | 시간 |
|------|------|------|
| 사이드바 접기/펼치기 | Width 260→48px | 180ms |
| 우측 패널 슬라이드 | TranslateTransform X | 200ms |
| 탭 전환 | Opacity + TranslateY | 120ms |
| 메시지 등장 | Opacity + TranslateY | 120ms |
| 스트리밍 커서 | Opacity 깜빡임 | 500ms |
| 도구 블록 펼치기 | Height 애니메이션 | 150ms |

---

## 12. 보안 시스템

### 12.1 데이터 보호

| 항목 | 방법 |
|------|------|
| API 키 | AES-256-GCM + DPAPI 이중 암호화 |
| 클립보드 이력 | DPAPI 암호화 저장 |
| 가이드 문서 | AES-256-CBC 암호화 (.enc) |
| 설정 파일 | 로컬 저장 (`%APPDATA%\AxCopilot\`) |

### 12.2 AI 기능 제어

| 설정 | 기본값 | 설명 |
|------|--------|------|
| `AiEnabled` | `false` | AI 기능 전체 차단/허용 (비밀번호 보호) |
| `InternalModeEnabled` | `true` | 사내 모드 — 외부 인터넷 차단 |

### 12.3 감사 로그 (AuditLogService)

모든 에이전트 도구 실행, 파일 변경, 권한 결정을 JSON 형식으로 기록:
```json
{
  "timestamp": "2026-04-03T14:30:00",
  "event": "tool_execution",
  "tool": "file_write",
  "path": "src/main.cs",
  "permission": "auto",
  "result": "success"
}
```

---

## 13. 세션 관리

### 13.1 세션 기능

| 기능 | 설명 |
|------|------|
| **자동 저장** | 대화별 자동 저장/복원 |
| **포크** | 현재 세션 분기하여 별도 대화 |
| **태그** | 세션에 라벨 태그 |
| **카테고리** | 작업 유형별 자동 분류 |
| **고정** | 중요 대화 상단 고정 |
| **검색** | 대화 이력 전문 검색 |

### 13.2 멀티에이전트

| 기능 | 구현 |
|------|------|
| **서브에이전트** | SubAgentTool — 독립 컨텍스트에서 작업 위임 |
| **Worktree 격리** | Git worktree 기반 서브에이전트 독립 작업 |
| **백그라운드 실행** | BackgroundAgentService — 비동기 실행 + 완료 알림 |
| **코디네이터** | 계획 수립 → 서브에이전트 분배 → 결과 병합 |

---

## 14. 외부 의존성

### 14.1 NuGet 패키지 (7개)

| 패키지 | 버전 | 용도 | 크기 |
|--------|------|------|------|
| DocumentFormat.OpenXml | 3.2.0 | Office 문서 생성 (DOCX/XLSX/PPTX) | ~5MB |
| Markdig | 0.37.0 | Markdown 파싱/렌더링 | ~1MB |
| Microsoft.Data.Sqlite | 8.0.0 | SQLite 로컬 DB | ~2MB |
| Microsoft.Web.WebView2 | 1.0.2903.40 | 내장 브라우저 | ~3MB |
| System.Security.Cryptography.ProtectedData | 8.0.0 | DPAPI 암호화 | <1MB |
| System.ServiceProcess.ServiceController | 8.0.1 | Windows 서비스 관리 | <1MB |
| UglyToad.PdfPig | 1.7.0-custom-5 | PDF 파싱/텍스트 추출 | ~2MB |

### 14.2 시스템 의존성

| 의존성 | 용도 |
|--------|------|
| .NET 8.0 Runtime | 앱 실행 (self-contained) |
| WebView2 Runtime | HTML 렌더링, 가이드 뷰어 |
| Segoe MDL2 Assets | 시스템 아이콘 폰트 |
| Windows 10+ | WPF, DPAPI, P/Invoke |

---

## 15. 코드 품질 리팩터링 이력 (Phase 33~36)

### 15.1 Phase 33 — AgentLoopService 구조 개선

| 작업 | 내용 |
|------|------|
| 매직 넘버 상수화 | 16개 `Defaults` 상수 클래스 |
| RunAsync 분해 | `ProcessSingleToolCallAsync` 250줄 추출 (27% 감소) |
| 중복 제거 | AutoCompactMonitor + ContextCondenser 통합 |
| 레이스 컨디션 | ActiveTab 스냅샷 패턴 적용 |
| 에러 핸들링 | bare catch → `catch (Exception)` + 주석 |

### 15.2 Phase 34 — ChatWindow God Class 분해

| 작업 | 내용 |
|------|------|
| ThemeResourceHelper | `TryFindResource` 190건 → 헬퍼 메서드 |
| FontFamily 캐싱 | 54건 `new FontFamily()` → 정적 필드 |
| PopupMenuHelper | 팝업 생성 패턴 통합 헬퍼 |
| RunAgentLoopAsync | Cowork/Code 70줄 중복 → 40줄 통합 |

### 15.3 Phase 35 — 코드 품질 심층 정리

| 작업 | 영향 범위 |
|------|----------|
| bare catch 전량 정리 | 109개 파일 |
| ColorConverter 헬퍼 | 81건 → `HexBrush()`/`HexColor()` |
| `_settings.Settings.Llm` 캐싱 | 92건 → `Llm` 프로퍼티 |
| AgentContext.Settings DI | 11개 도구 서비스 로케이터 제거 |

### 15.4 Phase 36 — 서비스 로케이터 제거 + PopupMenuHelper 적용

| 작업 | 영향 범위 |
|------|----------|
| `Application.Current as App` 일원화 | 15개 파일, 39건 → `CurrentApp` |
| PopupMenuHelper 실제 적용 | 4개 팝업 메서드, 169줄 감소 |

---

## 16. 빌드 및 배포

### 16.1 빌드 구성

```xml
<PropertyGroup>
  <OutputType>WinExe</OutputType>
  <TargetFramework>net8.0-windows</TargetFramework>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <SelfContained>true</SelfContained>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>
```

### 16.2 배포 체계

| 항목 | 설명 |
|------|------|
| **인스톨러** | AxCopilot.Installer (WinForms 기반) |
| **업데이트** | 수동 인스톨러 실행 (자동 업데이트 없음) |
| **배포 크기** | 목표 150MB 이하 (현재 ~80MB) |
| **데이터** | `%APPDATA%\AxCopilot\` 로컬 저장 |

### 16.3 가이드 문서 체계

```
개발자 가이드 (.htm) → 암호화 → guide_dev.enc → 앱 내장 뷰어
                     ↓
사용자 가이드 (.htm) → 암호화 → guide_user.enc → 앱 내장 뷰어
(버전이력 제거)
```

---

## 17. 프로젝트 파일 구조

```
E:\AX Copilot\
├── docs/
│   ├── AGENT_ROADMAP.md          # AI 에이전트 로드맵
│   ├── LAUNCHER_ROADMAP.md       # 런처 로드맵
│   ├── NEXT_ROADMAP.md           # 종합 차기 계획
│   ├── DEVELOPMENT.md            # 개발 문서
│   └── TECHNOLOGY_OVERVIEW.md    # ← 이 문서
├── src/
│   ├── AxCopilot/                # 메인 앱
│   │   ├── Services/             # 서비스 계층 (43+ 파일)
│   │   │   └── Agent/            # 에이전트 서비스
│   │   │       ├── 64 tool files # IAgentTool 구현체
│   │   │       ├── SlashCommands/ # 15개 슬래시 명령
│   │   │       └── Sdk/          # MCP SDK 서버
│   │   ├── Handlers/             # 런처 핸들러 (44개)
│   │   ├── Views/                # UI 윈도우 (27개)
│   │   │   └── Controls/        # 재사용 컨트롤 (4개)
│   │   ├── ViewModels/           # MVVM ViewModel
│   │   ├── Models/               # 데이터 모델
│   │   ├── Themes/               # 10개 테마 XAML
│   │   ├── Assets/               # 정적 리소스
│   │   │   └── Presets/          # 20개 프리셋
│   │   ├── skills/               # 40개 내장 스킬
│   │   └── Core/                 # 핵심 유틸리티
│   ├── AxCopilot.Installer/      # 인스톨러 프로젝트
│   ├── AxCopilot.SDK/            # 외부 SDK
│   └── AxCopilot.Tests/          # 단위 테스트
└── CLAUDE.md                     # AI 개발 지시사항
```

---

## 18. 완료된 Phase 전체 목록

### AI 에이전트 (Phase 2.5 ~ 36)

| Phase | 제목 | 버전 | 상태 |
|-------|------|------|------|
| 2.5-7 | 에이전트 루프, 마크다운, Code 탭 | v1.1-1.2.1 | ✅ |
| 7.5 | 레인보우 글로우, 테마 개선 | v1.2.2 | ✅ |
| 8 | MCP, 모델 폴백, 분기, 토큰 관리 | v1.5.0 | ✅ |
| 9 | LSP, 병렬 에이전트, 코드 검색, 테스트 루프 | v1.5.0 | ✅ |
| 10 | 모델 라우터, 메모리, 훅, 멀티모달 | v1.5.0 | ✅ |
| 11 | 스킬 시스템, 코드 리뷰, 드래그 앤 드롭 | v1.5.0 | ✅ |
| 12 | 도구 관리 UI, SKILL.md, 스킬 에디터/갤러리 | v1.5.x | ✅ |
| 15 | 문서 엔진, PPT, 피벗, 16 내장 스킬 | v1.6.0 | ✅ |
| 16 | Plan 모드, 프로젝트 규칙, 병렬 실행 | v1.7.0 | ✅ |
| 16.5 | 검증 강제, 후처리 검증, 피드백 학습 | v1.7.1 | ✅ |
| 16.8 | 컨텍스트 압축, 이력 복원, 속도 개선 | v1.7.2 | ✅ |
| 17-UI | 3-Pane 채팅 화면 재설계 | v1.8.0 | ✅ |
| 17-A~G | Reflexion, 태스크 상태, 훅, 스킬, 메모리, 권한, Diff | v1.8.0 | ✅ |
| 18-A~C | 멀티에이전트, 리플레이, 플러그인 갤러리 | v2.0 | ✅ |
| 19~19-G | CC 동등성 달성 (메모리, 권한, 훅, 스킬, 세션) | v2.1 | ✅ |
| 22~29 | 슬래시 명령 14개, 최종 통합 검증 | v2.1 | ✅ |
| 30 | 아키텍처 정제, 계층적 메모리 | v2.1 | ✅ |
| 31 | SDK 제어 프로토콜 (JSON 스트리밍) | v2.2 | ✅ |
| 32 | 3-Pane Claude.ai UI 구조 | v2.3 | ✅ |
| 33 | AgentLoopService 코드 품질 리팩터링 | v2.3 | ✅ |
| 34 | ChatWindow God Class 분해 | v2.3 | ✅ |
| 35 | 코드 품질 심층 정리 (bare catch, 색상, DI) | v2.3 | ✅ |
| 36 | 서비스 로케이터 제거 + PopupMenuHelper | v2.3 | ✅ |

### 런처 (Phase L1 ~ L2+)

| Phase | 제목 | 버전 | 상태 |
|-------|------|------|------|
| L1 | 44 핸들러, 퍼지 검색, 10 테마, 플러그인 | v1.5.0 | ✅ |
| L1+ | 셸 확장, 스토리지, 독 바 | v1.5.0 | ✅ |
| L2 | 클립보드 강화, UX 개선 | v1.5.3 | ✅ |
| L2+ | 독 바 정렬, 가이드 뷰어, 정보 업데이트 | v1.5.3 | ✅ |

---

> **Claude Code 동등성**: 37/37 핵심 기능 구현 완료
> **코드 품질 리팩터링**: Phase 33~36, 4차 반복 완료
> **빌드 상태**: 경고 0, 오류 0