lacvet
9344cf83d6
- README와 DEVELOPMENT, 로드맵 문서에서 비교·모사 뉘앙스가 강한 문구를 AX 기준 설명으로 정리함 - 비교/패리티 성격의 문서를 AX Agent 구조 리뷰, 실행 개선 계획, 품질 계획, 런타임 품질 계획, 도구 커버리지 문서로 재구성함 - 회귀 프롬프트와 보조 개발 문서의 용어를 공통 핵심 명령과 운영 기준 중심으로 정리함 - 검증: dotnet build src/AxCopilot/AxCopilot.csproj -c Release -v minimal -p:OutputPath=bin\\verify_docs_cleanup\\ -p:IntermediateOutputPath=obj\\verify_docs_cleanup\\ (경고 0 / 오류 0)
79 lines
4.6 KiB
Markdown
79 lines
4.6 KiB
Markdown
# 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` 실행 결과 기록
|