# AX Agent 품질 계획

업데이트: 2026-04-15 18:20 (KST)

## 1. 범위
- 명령 처리 흐름
- 권한 / hook 계약
- plan / run 내구성
- 세션 / 로그 관리
- 도구 / 스킬 운영 정합성

## 2. 현재 상태 요약
- 루프 가드와 검증 게이트는 주요 경로에 반영됨
- 병렬 도구 실행, Plan Mode, unknown-tool 복구는 기본 동작 확보
- 세션 재개와 이벤트 replay는 수치 기반 관리 단계로 진입

## 3. 단계별 품질 게이트

### P1 Hook 계약 고도화
- `updatedInput`, `updatedPermissions`, `additionalContext`를 AX 실행 루프에 반영
- 설정 토글로 위험 기능 제어

### P2 세션 / 이벤트 내구성
- run 상태 영속화와 resume 기준 고정
- jsonl 이벤트 필드 표준화와 재생 가능성 확보

### P3 실패 복구 표준화
- unknown-tool, 권한거부, 파라미터 오류를 유형화
- 유형별 복구 프롬프트와 다음 액션 우선순위 고정

### P4 완료 품질 정렬
- 코드/문서 작업별 완료 체크리스트 표준화
- 증거 없는 완료 응답 방지

## 4. 운영 점검 스냅샷
- 도구 레지스트리 등록 수: 65개
- `IAgentTool` 구현 수: 65개
- 내장 스킬 파일 수: 40개
- `allowed-tools` 적용 스킬: 40/40
- 레거시 도구명 `process_run`, `grep_tool` 참조: 0건
- 내부 모드 차단 정책: `http_tool` 전면 차단, `open_external` 외부 URL 차단

## 5. 즉시 보완 항목
1. 스킬 frontmatter 확장 유지: `when_to_use`, `argument-hint`, `model`, `disable-model-invocation`, `user-invocable`, `context`, `agent`, `effort`, `paths`, `shell`
2. `paths` 기반 조건부 활성화 유지
3. 도구 별칭 정규화와 runtime hook filter 적용 유지
4. 위험 자동허용 가드(`process`, `spawn_agent`, `snippet_runner`) 강제 승인 정책 유지

## 6. 내부 벤치마크 기준

| 시나리오 | 기준 테스트 | 합격 기준 |
|---|---|---|
| 기본 Agentic loop | `AgentLoopE2ETests.RunAsync_ExecutesToolCall_AndCompletesWithFinalText` | ToolCall/ToolResult/Complete 이벤트 순서 유효, 최종 응답에 결과 포함 |
| unknown-tool 복구 | `AgentLoopE2ETests.RunAsync_UnknownTool_RecoversAndCompletes` | 오류 후 완료까지 수렴, 반복 실패 루프 없음 |
| Plan Mode 실행 연결 | `AgentLoopE2ETests.RunAsync_PlanModeAlways_EmitsPlanningThenExecutesTool` | 계획 응답 뒤 실제 도구 호출과 최종 결과 생성 |
| 권한 Ask 거부 처리 | `AgentLoopE2ETests.RunAsync_AskPermissionDenied_EmitsPermissionEvents_AndCompletes` | PermissionRequest/PermissionDenied 이벤트 기록 후 안전 종료 |
| Hook 입력 변형 | `AgentLoopE2ETests.RunAsync_PreHookInputMutation_ChangesToolArguments` | pre-hook `updatedInput`이 실제 도구 입력에 반영 |
| Runtime 정책 강제 | `AgentLoopE2ETests.RunAsync_DisallowedTool_ByRuntimePolicy_EmitsPolicyRecoveryError` | 비허용 도구 차단과 정책 복구 경고 후 종료 |
| Hook filter 정합성 | `AgentLoopE2ETests.RunAsync_HookFilters_ExecuteOnlyMatchingHookForToolAndTiming` | 지정 hook만 실행되고 비매칭 hook는 미실행 |
| 별칭 정규화 | `AgentLoopE2ETests.RunAsync_EnterPlanModeAlias_ResolvesAndExecutes` | CamelCase 도구명이 내부 snake_case 도구로 매핑되어 실행 |
| 혼합 복구 내구성 | `AgentLoopE2ETests.RunAsync_MixedRecovery_UnknownToolAndPermissionDenied_TerminatesSafely` | 반복 한도 안에서 안전 종료 |

## 7. replay 안정성 기준

| 시나리오 | 기준 테스트 | 합격 기준 |
|---|---|---|
| 실행 이벤트 정렬/압축 복원 | `ChatSessionStateServiceTests.LoadOrCreateConversation_NormalizesHistoryOrderAndCompactsSize` | ExecutionEvents 400개 상한과 시간순 정렬 유지 |
| run 이력 중복 정규화 | `ChatSessionStateServiceTests.LoadOrCreateConversation_NormalizesAgentRunDuplicatesByRunId` | 동일 `RunId`는 최신 상태 1건으로 축약 |
| terminal 우선 판정 | `TaskRunServiceTests.RestoreRecentFromExecutionEvents_PrefersTerminalEventsWhenTimestampsEqual` | 동시각 이벤트는 terminal 상태 기준으로 복원 |
| active 복원 | `TaskRunServiceTests.RestoreRecentFromExecutionEvents_RebuildsActiveTasksFromNonTerminalEvents` | 중단 후 재개 시 active task 재구성 |
| dangling 정리 | `TaskRunServiceTests.RestoreRecentFromExecutionEvents_CompleteClearsDanglingRunScopedActiveTasks` | Complete 뒤 run 스코프 dangling active task 0건 |

## 8. 배포 체크리스트
1. `dotnet build` 경고 0 / 오류 0
2. `dotnet test` 전체 통과
3. 내부 벤치마크 시나리오 전건 통과
4. `Suite=ReplayStability` 전건 통과
5. `scripts/release-gate.ps1` 실행 결과 기록