AX-Copilot-Codex/AGENTS.md

# AX Copilot 개발 지시사항

이 파일은 모든 개발 세션에서 일관된 품질의 결과물을 보장하기 위한 필수 지시사항입니다.
`claude-code`를 기준 레퍼런스로 삼아 기능적으로 동일 품질이 나오도록 구현하되, 복제본으로 인식될 정도로 코드 표현을 그대로 옮기지는 않는다.
실제 저장 폴더명은 `claw-code`이며, 문서/지시문 내 기준 명칭은 `claude-code`로 통일한다.
---

## 0. 연속 작업 원칙

- 작업은 가능한 한 중단 없이 연속 수행하고, 단계별 결과를 빠르게 보고합니다.
- 기능/로직 구현은 `claude-code` 실제 코드 흐름을 우선 참고하여 동등 품질 기준으로 반영합니다. (실제 폴더: `claw-code`)
- `claude-code`와 추후 비교/대조 시 문제 없도록 **기본 로직(동작 순서·예외 처리·검증 흐름)은 유지**하되, 코드 표현(변수명·함수 분해·구조화)은 가독성과 제품 코드 규칙에 맞게 변경하여 반영합니다.
- 작업 완료 후에는 변경사항을 점검하고 **반드시 Git push까지 진행**합니다.
- Git 커밋/푸시 시 커밋 메시지는 **반드시 한국어로 작성**하며, 변경 목적·핵심 수정사항·검증 결과가 드러나도록 **상세하게** 작성합니다.
- 작업 중 오류가 발생해 복구가 되지 않으면, **이전 정상 버전을 다시 받아 기준 상태에서 작업을 재개**합니다.

### 개발 계획 수립 기준 (필수)
- 모든 개발 계획(Phase/마일스톤/백로그)은 **`claude-code` 동등 품질 달성**을 1순위 목표로 수립합니다.
- 계획 수립 시 `claw-code` 내부 코드(`src/*`)를 직접 분석하여 **동일 동작 품질을 내는 구현 경로**를 우선 채택합니다.
- 단순 아이디어 비교가 아니라, `claw-code`의 실제 코드 흐름(순서/검증/예외/복구)을 AX 구조에 맞춰 이식하는 방식으로 계획을 작성합니다.
- 구현 시 `claw-code` 코드를 참고/활용하되, **코드 표현의 직접 복제는 금지**하며 AX 코드 스타일로 재구성합니다.
- 각 계획 항목에는 반드시 아래를 포함합니다:
1. 참조 대상(`claw-code` 파일/모듈)
2. AX 적용 위치(대상 파일/서비스)
3. 완료 조건(테스트/검증 기준)
4. 품질 판정 기준(동등 품질 여부를 판단할 시나리오)
---

## 1. UI/UX 디자인 원칙

### 기본 컨트롤 사용 금지
- **ContextMenu, MenuItem** 사용 금지 → 커스텀 `Popup` (Border + MouseLeftButtonUp, 12px 라운드, 호버, 드롭섀도)
- **MessageBox** 사용 금지 → `CustomMessageBox.Show()` 사용
- **기본 CheckBox** 사용 금지 → `Style="{StaticResource ToggleSwitch}"` 좌우 슬라이드 토글
- **Popup 내부에 Button** 사용 금지 → `Border` + `MouseLeftButtonUp` 패턴 (포커스 캡처 방지)
- 수평 스크롤바 금지 → `WrapPanel` 자동 줄바꿈

### 런처(alt+space)의 테마 통일성
- 색상 하드코딩 금지 — XAML: `{DynamicResource PrimaryText}`, 코드비하인드: `TryFindResource("PrimaryText") as Brush ?? Brushes.White`
- 모든 UI 요소는 현재 적용된 테마 리소스(`LauncherBackground`, `ItemBackground`, `AccentColor`, `PrimaryText`, `SecondaryText` 등)를 사용
- 다크 테마 6종 모두에서 텍스트 가독성 확인 필수

### AX Agent의 테마 통일성
- AX Agent의 경우 별도 테마를 생성하여 사용(codex, claude-code를 모방한 ui/ux를 원함)
- 테마는 시스템, 라이트, 다크로 간단하게 구성

### 코드비하인드 팝업/다이얼로그 테마 규칙
- **코드비하인드에서 생성하는 모든 팝업 Window/다이얼로그**도 현재 테마를 따라야 함
- 배경: `TryFindResource("LauncherBackground")`, 텍스트: `TryFindResource("PrimaryText")`, 보조 텍스트: `TryFindResource("SecondaryText")`
- 테두리: `TryFindResource("BorderColor")`, 아이템 배경: `TryFindResource("ItemBackground")`, 액센트: `TryFindResource("AccentColor")`
- 호버 효과 배경: `TryFindResource("ItemHoverBackground")`
- `#1A1B2E`, `Brushes.White` 등 고정 색상을 팝업에 직접 사용하는 것은 **금지** — 라이트/다크 테마 전환 시 색상 불일치 발생
- 팝업 Window에 테마 적용 패턴:
```csharp
// 팝업 생성 후 부모 창의 Resources를 팝업에 전달
popup.Resources.MergedDictionaries.Add(this.Resources);
// 또는 직접 리소스 조회
var bg = TryFindResource("LauncherBackground") as Brush ?? Brushes.White;
var fg = TryFindResource("PrimaryText") as Brush ?? Brushes.Black;
```

### 인터랙티브 요소
- 클릭 가능 영역 최소 36px, FontSize 최소 12px, Padding 최소 6px
- 호버/클릭 효과 필수 — 테마 리소스 기반 호버 배경(`ItemHoverBackground` 우선) + 핸드 커서
- 팝업은 `PopupAnimation="Fade"` 기본 적용
- 메뉴 항목 FontSize 13px 이상

### 아이콘 색상
- Segoe MDL2 Assets 아이콘은 가능한 한 **의미에 맞는 색상**을 적용 (단색 `SecondaryText` 지양)
- 메뉴 항목: 아이콘 + 라벨에 동일 색상 적용 (예: Ask=파랑, Auto=앰버, Deny=빨강)
- 하단 바: 각 버튼 아이콘에 기능별 색상 (포맷=보라, 파일=앰버, 권한=파랑, 데이터=녹색)
- 활성 상태 항목: `AccentColor` 또는 해당 기능 고유 색상으로 강조

### 설정 UI 패턴
- 켜기/끄기: ToggleSwitch 스타일 (Grid 좌: 라벨, 우: 토글)
- 선택형: 커스텀 Popup 드롭다운 (`[라벨: 현재값 ▾]`)
- AI/고급 설정 항목 옆에 `?` 도움말 아이콘 + 커스텀 다크 툴팁 (`HelpTooltipStyle`)
- 설정 저장 시 `CustomMessageBox`로 완료 알림

### 헬프 화면 (HelpDetailWindow) 규칙
- **버전 정보 금지** — 헬프에 버전별 신기능(예: "v1.6.0 신기능") 항목을 넣지 않으며, 앞으로도 추가하지 않음
- **영역별 핵심 기능만 표시** — 개요, AI, 업무 보조 등 영역별로 사용자가 "무엇을 할 수 있는지"만 간결히 설명
- **기술 보호 (IP 보호)** — 설명에서 내부 기술·구현 방식을 유추할 수 없어야 함. 아래 용어를 헬프에 직접 노출하는 것은 **금지**:

| 사용 금지 (내부 기술) | 대신 사용 (사용자 관점) |
|---------------------|----------------------|
| SSE, Server-Sent Events | "실시간 응답" |
| AES-256-GCM, DPAPI, 암호화 알고리즘명 | "암호화 저장", "안전하게 보호" |
| OpenXML, python-docx, openpyxl | "문서 생성", "파일 생성" |
| MCP, JSON-RPC, stdio | "외부 도구 연결" |
| LINQ, TF-IDF, LCS, Mustache | 기능 설명으로 대체 |
| Ollama, vLLM, Gemini, Claude (모델명) | "AI 서비스", "AI 모델" |
| OWASP, CVE | "보안 점검", "취약점 분석" |
| system_prompt.txt, 클래스명, 파일명 | 기능 설명으로 대체 |

---

## 2. 설정값 관리 원칙

### 신규 기능 → 설정 검토 필수
신규 기능 추가 시 사용자/개발자가 제어할 수 있는 설정값을 반드시 검토하고 추가합니다:
1. `AppSettings.cs`에 프로퍼티 + JsonPropertyName + 기본값 추가
2. `SettingsViewModel.cs`에 바인딩 프로퍼티 + Load/Save 매핑
3. `SettingsWindow.xaml`에 적절한 탭에 UI 컨트롤 배치
4. 도구(Tool) 클래스에서 설정값을 실제로 체크하여 동작에 반영

### Cowork / Code 설정 분리 원칙
에이전트 동작 설정은 **공통(LlmSettings)에 넣지 말고, Cowork/Code 각각에 배치**합니다:
- **Cowork 전용 설정**: `LlmSettings`에 직접 프로퍼티 추가 → SettingsWindow의 `AgentPanelCowork` 패널에 배치
- **Code 전용 설정**: `CodeSettings` 클래스에 프로퍼티 추가 → SettingsWindow의 `AgentPanelCode` 패널에 배치. XAML 바인딩은 `{Binding Code.PropertyName}`
- **진짜 공통인 경우만** `AgentPanelCoworkCode` 패널에 배치 (예: MaxAgentIterations, MaxRetryOnError)
- 검증 강제, 출력 형식, 폴더 데이터 활용 등 **탭마다 다르게 동작하는 기능**은 반드시 분리
- AgentLoopService에서 `ActiveTab == "Code"` 분기로 탭별 설정 참조

```csharp
// 탭별 설정 참조 패턴
var shouldVerify = ActiveTab == "Code"
    ? llm.Code.EnableCodeVerification
    : llm.EnableCoworkVerification;
```

### 설정값이 코드에서 실제 동작해야 함
설정을 정의만 하고 코드에서 읽지 않는 것은 금지. 설정 체크 패턴:
```csharp
var app = System.Windows.Application.Current as App;
var enabled = app?.SettingsService?.Settings.Llm.Code.EnableLsp ?? true;
if (!enabled) return ToolResult.Ok("비활성 상태입니다. 설정에서 활성화하세요.");
```

---

## 3. 버전 관리 및 배포

### 버전 번호 규칙
- **소규모 배포** (버그 수정, 설정 추가, UI 개선): `+0.0.1` (예: 1.4.0 → 1.4.1)
- **대규모 기능 배포** (Phase 완료, 새 에이전트 도구, 핵심 기능): `+0.1.0` (예: 1.4.0 → 1.5.0)

### 버전 변경 시 반드시 수정할 파일 (체크리스트)

| # | 대상 | 파일 경로 | 수정 내용 |
|---|------|----------|----------|
| 1 | 앱 버전 | `src/AxCopilot/AxCopilot.csproj` → `<Version>` | 버전 번호 |
| 2 | 인스톨러 프로젝트 | `src/AxCopilot.Installer/AxCopilot.Installer.csproj` → `<Version>` | 동일 |
| 3 | 인스톨러 표시 | `src/AxCopilot.Installer/SetupForm.cs` → `AppVer` | 동일 |
| 4 | MCP 클라이언트 | `src/AxCopilot/Services/McpClientService.cs` → `clientInfo.version` | 동일 |
| 5 | 개발 문서 | `docs/DEVELOPMENT.md` | 버전 이력 추가 |
| 6 | 로드맵 문서 | `docs/AGENT_ROADMAP.md`, `docs/LAUNCHER_ROADMAP.md`, `docs/NEXT_ROADMAP.md` | 버전 번호/계획 갱신 |

### 문서 갱신 기준
- 개발 진행 중 기본 갱신 대상은 `.md` 문서만 사용합니다.
- 버전/계획/로드맵 변경은 `docs/*.md`에만 반영합니다.
- HTML/HTM/ENC 문서는 사용자의 명시적 요청이 있을 때만 갱신합니다.

### 사용자 노출 문서 작성 원칙 (사용가이드 · 헬프)

사용자 가이드와 헬프 화면은 **내부 기술이 노출되지 않도록** 작성합니다:

| 구분 | 사용 금지 (내부 기술) | 대신 사용 (사용자 관점) |
|------|---------------------|----------------------|
| 프로토콜 | MCP, JSON-RPC, stdio, P/Invoke, DPAPI | "외부 도구 연결", "암호화 저장" |
| 클래스명 | McpClientService, TokenEstimator, DiffService | 기능 설명으로 대체 |
| 내부 구조 | FallbackModels, SettingsViewModel, ParentId | "자동 전환", "설정", "분기" |
| 코드 패턴 | CJK 가중치, SWE-bench, LCS, TF-IDF | "더 정확한 분석", "검색 개선" |

**원칙**: 사용자에게는 "무엇을 할 수 있는지"만 전달합니다.

---

## 4. 코드 품질

### 빌드 기준
- 모든 변경 후 `dotnet build` 실행 → **경고 0, 오류 0** 필수
- CS8603 (nullable) 경고 즉시 수정

### 리소스 관리
- `IDisposable` 구현 객체는 반드시 해제 (PerformanceCounter, LspClientService 등)
- P/Invoke 메모리: `Marshal.AllocHGlobal` 후 `finally`에서 `FreeHGlobal`
- WinEvent 훅: `UnhookWinEvent` 보장

### 에이전트 도구 등록
- 새 `IAgentTool` 구현 시 `ToolRegistry.CreateDefault()`에 `Register()` 추가 필수
- 도구의 `Parameters` 스키마가 LLM function calling 명세에 정확히 맞는지 확인

---

## 5. AI 차단 버전 (클로드 버전) 패턴

AI 기능이 필요 없는 환경에 배포하거나, AI 기능 문의를 차단해야 할 때 사용하는 패턴입니다.

### 활성화/비활성화 제어 방법

`AppSettings.AiEnabled` (기본값 **`false`**) 한 곳만 바꾸면 전체 AI 기능이 제어됩니다.

| 조건 | 동작 |
|------|------|
| `AiEnabled = false` | **기본값 (배포 기본)** — AI 전체 차단 |
| `AiEnabled = true` | AI 활성화 — 비밀번호 인증 후 설정 가능 |

### AI 활성화 비밀번호

- 설정 창 > 일반 탭 > AI 기능 토글 ON 시 비밀번호 다이얼로그 표시
- 비밀번호: **`axgo123!`**
- 비밀번호 틀리거나 취소 시 토글 자동 복구 (OFF 유지)
- 비활성화(OFF)는 비밀번호 없이 즉시 적용
- 구현 위치: `SettingsWindow.xaml.cs` `AiEnabled_Changed()`

### 비밀번호 통일 원칙
- 설정 창의 관리자/개발자/보안 관련 모든 비밀번호 검증은 단일 값 **`axgo123!`** 로 통일합니다.

### AI 차단 시 적용되는 항목

| 항목 | 구현 위치 | 설명 |
|------|----------|------|
| `!` prefix 배지 숨김 | `LauncherViewModel.cs` `ActivePrefix`/`HasActivePrefix` | `!` prefix 인식 안 함 |
| `!` 입력 시 결과 없음 | `ChatHandler.cs` `GetItemsAsync` | 빈 리스트 반환 (항목 자체 미표시) |
| `!` 실행 차단 | `ChatHandler.cs` `ExecuteAsync` | 실행 불가 |
| 트레이 메뉴 항목 숨김 | `App.xaml.cs` `Opening` 이벤트 | "AX Agent 대화하기" 항목 `Collapsed` |
| AX Agent 설정 탭 숨김 | `SettingsWindow.xaml.cs` `ApplyAiEnabledState()` | 설정 창의 AX Agent 탭 `Collapsed` |

### 설정 토글 UI

- 위치: 설정 창 > 일반 탭 > **AI 기능** 섹션 > "AX Agent (AI 기능) 활성화" 토글
- 저장 위치: `%APPDATA%\AxCopilot\settings.dat` → `"ai_enabled": true/false`

### 신규 AI 기능 추가 시 체크리스트

AI 관련 기능을 새로 추가하면 `AiEnabled` 체크를 반드시 연동합니다:

```csharp
// 핸들러/도구에서 AI 차단 체크 패턴
var settings = (System.Windows.Application.Current as App)?.SettingsService?.Settings;
if (settings?.AiEnabled == false) return; // 또는 빈 결과 반환
```

---

## 6. 프로젝트 명칭 체계

| 구분 | 명칭 | 용도 |
|------|------|------|
| 앱 전체 | **AX Copilot** | 제품명, 설정, 정보 |
| 런처 | **AX Commander** | 명령 입력창 |
| AI 대화 | **AX Agent** | Chat/Cowork/Code 대화 |

---

## 7. 사내 환경 개발 원칙

### 운영 모드(필수)
- `operationMode` 설정을 기준으로 동작합니다.
- 값: `internal`(사내), `external`(사외)
- 기본값: `internal`

| 모드 | 정책 |
|------|------|
| `internal` | 정보 유출 가능 기능 차단 (웹 검색, 외부 URL 열기, 외부 HTTP 호출, 외부 API 스킬, **외부 LLM 호출**) |
| `external` | 모든 기능 허용 |

### 외부 의존 최소화
- **외부 서버/클라우드 접속 금지** — 모든 기능은 앱에 자체 내장하여 개발. 외부 API 호출이 필수인 경우(LLM 서비스)를 제외하고 외부 서비스에 의존하지 않음
- **데이터 로컬 저장** — 설정, 대화, 클립보드, 인덱스, 로그 등 모든 데이터는 `%APPDATA%\AxCopilot\` 로컬에 저장. 클라우드 동기화 없음
- **플러그인 설치** — URL 기반 다운로드 금지. 로컬 zip 파일 기반 설치만 허용
- **코드 검색/인덱싱** — 외부 임베딩 API 사용 금지. 로컬 TF-IDF 또는 로컬 임베딩 엔진(ONNX) 사용
- **업데이트 확인** — 외부 서버 자동 업데이트 체크 금지. 인스톨러를 통한 수동 업그레이드만 지원
- **텔레메트리** — 사용 통계를 외부로 전송하지 않음. 모든 통계는 로컬 파일에만 기록

### 허용되는 외부 접속
- `internal` 모드: 사내망/온프레미스 LLM(Ollama/vLLM)만 허용, 퍼블릭 LLM(Gemini/Claude) 호출 금지
- `external` 모드: 설정된 LLM 서비스(Ollama/vLLM/Gemini/Claude) 호출 허용
- MCP 서버 연결 (사내 서버만, 설정에서 명시적 등록)
- 사용자가 의도한 웹 검색 (? 프리픽스) **단, `external` 모드에서만 허용**

---

## 8. 문서 관리 원칙

### 기본 원칙: .md 파일이 마스터
- **모든 로드맵·계획 문서는 `.md` 파일로 관리**합니다. 기본 작업(기능 개발·계획 수립·완료 기록)은 항상 `.md` 파일만 업데이트합니다.
- **HTML 웹 문서는 명시적으로 요청할 때만 업데이트**합니다. ("웹 문서도 업데이트해줘" 또는 "HTML 문서 갱신해줘" 요청 시에만 작업)
- HTML 문서는 `.md` 마스터를 기반으로 생성되는 **파생 문서**입니다. 자동으로 동기화하지 않습니다.

### 문서 체계

| 문서 (.md 마스터) | HTML (파생) | 관리 대상 | .md 업데이트 시점 |
|-----------------|------------|----------|-----------------|
| `docs/AGENT_ROADMAP.md` | `docs/AGENT_ROADMAP.html` | **대화 서비스** Phase별 기능, 완료 이력, 기술부채 | Phase 완료 시, 기능 추가 시 |
| `docs/LAUNCHER_ROADMAP.md` | `docs/LAUNCHER_ROADMAP.html` | **런처** Phase별 기능, 완료 이력, 경쟁 비교 | Phase 완료 시, 기능 추가 시 |
| `docs/NEXT_ROADMAP.md` | `docs/NEXT_ROADMAP.html` | **종합** 경쟁 분석, 기술 동향, 차기 계획 | 분기별 또는 대규모 계획 변경 시 |
| `docs/DEVELOPMENT.md` | — | **개발 상세** 아키텍처, 핸들러, 버전 이력, 코드 패턴 | 매 버전 배포 시 |

### 문서 업데이트 규칙
- **기능 개발 완료 시**: 해당 영역 .md 로드맵(AGENT/LAUNCHER)에 완료 표시 + 구현 내용 기록
- **배포 시**: DEVELOPMENT.md 버전 이력 추가, 사용자 가이드/헬프 갱신
- **차기 계획 수립 시**: NEXT_ROADMAP.md 업데이트 (경쟁 분석 반영)
- **HTML 동기화 요청 시에만**: 해당 .md 내용을 기반으로 HTML 파일 갱신 (열고/닫기 토글, badge 스타일 done/plan/hold 통일)

---

## 9. 고도화 계획 수립 원칙

### 외부 동향 기반 계획 수립
고도화 계획(Phase)을 수립할 때는 **내부 개발 필요성만이 아닌 외부 동향**을 종합적으로 반영합니다:

| 관점 | 검토 사항 |
|------|----------|
| **경쟁 서비스** | claude-code, Cursor, Windsurf, GitHub Copilot, Raycast 등 최신 기능/UX 비교 |
| **최신 논문/기술** | Agentic Coding Survey, SWE-Agent, CodeAct, Reflexion 등 에이전트 코딩 연구 동향 |
| **업계 표준** | MCP 프로토콜, SKILL.md 오픈 포맷, LSP, DAP 등 표준 프로토콜 채택 여부 |
| **사내 환경** | 네트워크 제한, 보안 정책, Python/Node 설치 현황, 사용 빈도가 높은 워크플로우 |
| **커뮤니티 스킬** | Claude 공식 스킬, 오픈소스 프롬프트 엔지니어링 기법, 검증된 에이전트 패턴 |

### 앱 크기 관리
배포 앱(인스톨러)의 크기가 과도하게 커지지 않도록 관리합니다:

- **기본 배포 크기 목표**: 인스톨러 **150MB 이하** 유지 (현재 ~80MB)
- **대형 의존성 추가 시**: ONNX 모델, 임베딩 엔진, 사전 데이터 등은 **별도 선택적 다운로드** 또는 **로컬 zip 설치** 방식 검토
- **스킬 파일**: 내장 스킬(`.skill.md`)은 텍스트 기반이므로 크기 부담 없음 (수십 KB 단위). 적극 번들 가능
- **NuGet 패키지**: 새 패키지 추가 시 DLL 크기 확인. 단일 기능에 10MB+ 패키지는 대안 검토
- **런타임 의존**: Python/Node 스크립트 기반 기능은 사용자 PC 런타임에 의존 → 앱 크기 증가 없음
- **리소스 파일**: 이미지/아이콘은 SVG 또는 시스템 폰트(Segoe MDL2 Assets) 우선. 대형 비트맵 금지

---

## 10. 관련 문서

| 문서 | 경로 | 설명 |
|------|------|------|
| 개발 문서 | `docs/DEVELOPMENT.md` | 아키텍처, 핸들러, 버전 이력, 개발 원칙 상세 |
| AX Agent 로드맵 | `docs/AGENT_ROADMAP.md` | 대화 서비스 고도화 계획 (Phase별) — HTML은 요청 시만 갱신 |
| 런처 로드맵 | `docs/LAUNCHER_ROADMAP.md` | 런처 고도화 계획 (Phase별) — HTML은 요청 시만 갱신 |
| 차기 종합 계획 | `docs/NEXT_ROADMAP.md` | v1.6.1~v2.0 경쟁 분석 + 전체 계획 — HTML은 요청 시만 갱신 |
| 사용자 가이드 | `src/AxCopilot/Assets/AX Copilot 사용가이드.htm` | 단축키/예약어 가이드 |
| 브랜딩 가이드 | `src/AxCopilot/Assets/BRANDING_가이드.md` | 아이콘/색상/명칭 규칙 |

---

## 11. 정책 충돌 해석 우선순위

규칙 충돌 시 아래 우선순위를 따릅니다.
1. 보안/운영 모드 정책 (`operationMode`, 정보 유출 방지)
2. 코드 품질/검증 정책 (빌드, 테스트, 검증 게이트)
3. 기능 동등 품질 정책 (`claude-code` 로직 기준)
4. UI/UX 정책
5. 문서 정책