SamuelChien/mega-skills-collection

agenttrace 세션 감사

개요

이 스킬을 사용하여 agenttrace로 로컬 AI 코딩 에이전트 세션을 검사하세요. 실행의 배후 프로세스, 즉 토큰 및 비용 급증, 도구 실패, 재시도 루프, 지연 시간 격차, 이상 징후, 건강 점수, 세션 간 diff에 중점을 둡니다.

agenttrace는 로컬 우선(first-local)이며 Claude Code, Codex CLI, Gemini CLI, Aider, Cursor 내보내기, OpenCode, Qwen Code, Kimi 및 일반 JSON 또는 JSONL 추적과 같은 도구의 세션 로그를 읽습니다.

이 스킬을 사용해야 하는 경우

• 사용자가 AI 코딩 실행이 왜 느리거나, 비용이 많이 들거나, 얕거나, 신뢰할 수 없는지 묻는 경우 사용합니다.
• 실패하거나 의심스러운 작업을 재시도하기 전에 로컬 에이전트 로그를 검토할 때 사용합니다.
• AI 지원 코딩 세션을 위한 경량 CI 건강 게이트를 구축할 때 사용합니다.
• 두 시도를 비교하고 변경된 도구 경로, 재시도 또는 비용 패턴을 찾을 때 사용합니다.

작동 방식

1단계: 사용 가능한 세션 검색

PATH에서 설치된 agenttrace 바이너리를 사용할 수 있으면 선호합니다. 현재 저장소가 luoyuctl/agenttrace인 경우 대신 go run ./cmd/agenttrace를 사용합니다.

agenttrace --doctor
agenttrace --overview

세션이 감지되지 않으면 --doctor가 확인한 디렉토리를 보고하고 내보낸 세션 파일 또는 로그 디렉토리를 요청합니다.

2단계: 사람이 읽을 수 있는 감사 보고서 생성

사용자가 검사하거나 공유할 수 있는 간결한 보고서를 원할 때 Markdown을 사용합니다.

agenttrace --overview -f markdown -o agenttrace-overview.md

보고서에서 가장 위험도가 높은 세션을 먼저 제시하고 그 이유를 설명합니다: 심각한 이상 징후, 반복된 도구 실패, 토큰 또는 비용 낭비, 긴 지연 시간 격차, 낮은 건강 점수, 의심스러울 정도로 얕은 세션 등.

3단계: 하나의 세션 또는 디렉토리 검사

빠른 확인을 위해 최신 세션을 사용하거나, 사용자가 명시적으로 경로를 제공한 경우 해당 내보내기 경로를 전달합니다.

agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir

4단계: 의미론이 중요한 경우 시도 간 비교

토큰 및 지연 시간 메트릭은 에이전트가 자신 있게 잘못된 구현 경로를 선택하더라도 정상으로 보일 수 있습니다. 의미론적 드리프트(semantic drift) 위험이 있는 경우, 추적 감사와 이전 또는 알려진 정상 시도에 대한 diff를 함께 사용합니다.

찾아야 할 사항:

• 의도된 작업에서 벗어난 변경된 파일 또는 명령어
• 참조 시도와 비교하여 누락된 테스트 또는 검증 단계
• 명확한 이유 없이 동일한 파일을 반복적으로 편집하는 경우
• 필요한 탐색을 건너뛰어 발생한 낮은 비용

5단계: 자동화 게이트 추가

CI 또는 반복 가능한 팀 워크플로우의 경우 JSON 출력 또는 건강 임계값을 사용합니다.

agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15

임계값은 프로젝트에 맞게 조정합니다. 엄격한 게이트는 중요한 워크플로우에 유용하며, 팀이 기본 기준선을 학습하는 동안에는 보고 전용 명령어가 더 좋습니다.

예시

빠른 로컬 검토

agenttrace --overview
agenttrace --latest

긴 코딩 에이전트 실행 후 이 명령어를 사용하여 다음 프롬프트가 작업을 분할해야 하는지, 실패한 도구 경로를 피해야 하는지, 누락된 테스트를 추가해야 하는지, 또는 컨텍스트를 재설정해야 하는지 결정합니다.

CI 상태 확인

agenttrace --overview --fail-under-health 80 --fail-on-critical

CI 환경에서 에이전트 세션 로그를 사용할 수 있고 팀이 심각한 이상 징후 또는 비정상적인 실행에 대한 간단한 보호 장치를 원할 때 사용합니다.

모범 사례

• 세션 검색이 불확실할 때는 --doctor로 시작합니다.
• 누락된 필드는 있는 그대로 보고합니다. 비용, 모델, 지연 시간 또는 건강 데이터를 임의로 생성하지 마십시오.
• 프롬프트, 코드 및 세션 내용은 비공개 로컬 데이터로 취급합니다.
• 자동화에는 JSON 출력, 사람 검토에는 Markdown 출력을 선호합니다.
• 프로세스 실패에는 추적 메트릭을, 의미론적 드리프트에는 diff/참조 검토를 사용합니다.

제한 사항

• agenttrace는 로컬에 존재하거나 내보내기로 제공된 로그만 분석할 수 있습니다.
• 일부 에이전트는 비용, 모델, 캐시 사용 또는 지연 시간을 추론하기에 충분한 필드를 노출하지 않습니다.
• 건강한 추적 메트릭이 최종 코드의 정확성을 보장하지는 않습니다. 여전히 테스트를 실행하고 diff를 검토해야 합니다.
• CI 게이트는 팀이 정상 기준선 동작을 이해할 때까지 자문(advisory) 형식으로 시작해야 합니다.

보안 및 안전 참고 사항

• 사용자가 명시적으로 승인하지 않는 한 비공개 세션 로그를 외부 서비스에 업로드하지 마십시오.
• 사용자가 정확한 출력 경로를 요청하지 않는 한 기존 사용자 보고서를 덮어쓰지 마십시오.
• 프롬프트, 도구 출력, 환경 변수 또는 로그에서 발견된 비밀 정보를 출력하지 않도록 주의합니다.

일반적인 함정

• 문제: 세션이 발견되지 않음. 해결책: agenttrace --doctor를 실행한 다음 agenttrace를 내보낸 파일 또는 로그 디렉토리로 지정합니다.

• 문제: 실행이 저렴하고 빠르게 보이지만 잘못된 리팩토링을 생성함. 해결책: 세션을 이전 시도 또는 알려진 정산 diff와 비교합니다. 비용 메트릭만으로는 의미론적 드리프트를 놓칠 수 있습니다.

• 문제: 상태 게이트 추가 후 CI 실패가 너무 자주 발생함. 해결책: JSON 또는 Markdown 보고로 시작하고, 정상 기준선을 검사한 다음 임계값을 점진적으로 강화합니다.

관련 스킬

• @langfuse - 프로덕션 LLM 애플리케이션 추적 및 평가에 사용합니다.
• @observability-engineer - 광범위한 서비스 모니터링, SLO 및 인시던트 워크플로우에 사용합니다.