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에 테마 적용 패턴:

// 팝업 생성 후 부모 창의 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" 분기로 탭별 설정 참조

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

설정값이 코드에서 실제 동작해야 함

설정을 정의만 하고 코드에서 읽지 않는 것은 금지. 설정 체크 패턴:

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 체크를 반드시 연동합니다:

// 핸들러/도구에서 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. 문서 정책