usage-analytics

Files (1)

• SKILL.md

SKILL.md (first lines)

# usage-analytics

`$ARGUMENTS` 요청에 따라 서브에이전트·스킬 사용 데이터를 분석하고 인사이트를 도출한다.

## 데이터 소스

로그 파일: `~/.pi/agent/state/usage-analytics.jsonl`

각 줄은 JSON 객체이며 4가지 타입이 있다:

```jsonc
// epoch는 밀리초. 신규 기록은 sessionId 포함, 과거 continue 시작에는 "_continue"가 있을 수 있음
// 집계: subagent_end 우선, 안전한 식별자가 있고 end가 없는 batch/chain start만 fallback으로 사용
{ "type": "subagent_start", "ts": "ISO8601", "epoch": 1788840000000, "sessionId": "session-uuid", "agent": "worker", "mode": "run", "runId": 42 }

// 완료 시각은 원본 세션 메시지의 시각. 신규 기록은 세션·메시지 식별자와 가능한 경우 startedAt 포함
{ "type": "subagent_end", "ts": "ISO8601", "epoch": 1788840045000, "sessionId": "session-uuid", "sessionEntryId": "entry-id", "startedAt": 1788840000000, "agent": "worker", "runId": 42, "status": "error", "elapsedMs": 45000, "model": "openai-codex/gpt-5.3-codex-spark", "errorClass": "context_overflow", "peakContextTokens": 127196, "lastToolName": "read", "lastToolOutputChars": 9032 }

// 명시적 스킬 호출: `/skill:name`이 확장된 사용자 `<skill>` 메시지가 확정될 때 기록
{ "type": "skill_invoked", "ts": "ISO8601", "epoch": 1234567890, "skill": "picky-cli", "path": "/path/to/SKILL.md" }

// SKILL.md 읽기: 에이전트가 read 도구로 직접 열었을 때 기록하며, 같은 스킬의 10초 내 중복 read는 제외
{ "type": "skill_read", "ts": "ISO8601", "epoch": 1234567890, "skill": "systematic-debugging", "path": "/path/to/SKILL.md" }
```

## 실행 절차

### Step 1: 기간 결정

`$ARGUMENTS`에서 분석 기간을 파악한다. 명시되지 않으면 **최근 7일**을 기본값으로 사용한다.

| 사용자 표현 | 기간 |
|------------|------|
| "최근 일주일", "이번 주" | 최근 7일 |
| "최근 한 달", "이번 달" | 최근 30일 |
| "전체", "처음부터" | 로그 전체 |
| "오늘" | 오늘 하루 |
| 구체적 날짜 범위 | 해당 범위 |

### Step 2: 데이터 로드

```bash
cat ~/.pi/agent/state/usage-analytics.jsonl
```

파일이 없거나 비어있으면 **"아직 수집된 사용 데이터가 없습니다."** 로 종료한다.

### Step 3: 분석 항목 산출

로그 데이터를 파싱해서 아래 항목을 계산한다. 사용자 요청이 특정 항목에 한정되면 해당 항목만 계산해도 된다.

#### 3-A. 서브에이전트 분석

| 지표 | 계산 방법 |
|------|----------|
| **호출 빈도** | `subagent_end` 이벤트 수를 우선 집계하고, 매칭되는 end가 없는 legacy/incomplete batch/chain의 `subagent_start` 이벤트 수만 fallback으로 더함 |
| **성공/실패 건수** | `subagent_end`의 `status` 필드로 집계 |
| **완료 미확인** | fallback으로 더한 시작 이벤트 수. 실패 또는 진행 중이라고 단정하지 않음 |
| **에러율** | `error / (done + error) * 100`. 완료 기록이 없으면 `-`, 완료 미확인은 분모에서 제외 |
| **평균 소요시간** | `subagent_end`의 `elapsedMs` 평균 |
| **최장/최단 소요시간** | `elapsedMs`의 max / min |
| **사용 모델 분포** | `model` 필드별 건수 |
| **호출 모드 분포** | `mode` 필드별 건수 (run/continue/batch/chain) |
| **실패 원인 분포** | `errorClass`별 건수 (`context_overflow`, `overloaded`, `rate_limit`, `tool_error`, `aborted`, `process_error`, `unknown`) |
| **실패 시 컨텍스트·도구** | `peakContextTokens`, `lastToolName`, `lastToolOutputChars`로 실패 직전 상태 분석 |
| **일별 추이** | 날짜별 호출 건수 변화 |

시작/완료 매칭 규칙은 `~/.pi/agent/extensions/usage-analytics/index.ts`의 `getRunAnalyticsKeys`와 동일하게 적용한다.

1. `batchId + stepIndex` 또는 `pipelineId + stepIndex`를 우선한다. 그룹이 다르면 `runId`가 같아도 다른 실행이다.
2. 그룹 정보가 없을 때만 `sessionId + runId`를 사용한다. 숫자 `runId` 단독 매칭은 금지한다.
3. 그룹 정보가 불완전하거나 sessionId 없는 과거 독립 실행은 임의로 연결하지 않는다. 안전한 키 없는 시작과 `_continue` 플레이스홀더는 fallback에서 제외한다.
4. 총 호출은 성공 + 실패 + 완료 미확인으로 표시한다. 모드 분포는 별도로 `subagent_start` 이벤트를 분모로 쓰며, batch 명령 횟수가 아닌 작업별 시작 건수다.

완료 복구는 시작/완료 매칭과 별도다. 그룹·단계 키, 또는 `sessionId + runId + startedAt`(없으면 `sessionId + sessionEntryId + runId`)로 중복을 막는다. 같은 runId의 다른 `continue` 완료를 합치지 않는다. sessionId 없는 과거 독립 실행은 기록 시각이 실제 완료 시각과 다를 수 있어 자동 연결하지 않는다. 해당 runId의 과거 완료가 존재하고 같은 세션·runId의 신규 시작 기록 이전인 복구 후보는 보수적으로 건너뛴다. 복구된 과거 완료 시각을 신규 계측 시작점으로 쓰지 않는다. 이 미확인 구간을 완전한 복구나 실패 0건으로 해석하지 않는다.

#### 3-B. 스킬 분석

`skill_invoked`와 `skill_read`는 의미가 다르므로 합산하지 않고 반드시 분리한다.

| 지표 | 계산 방법 |
|------|----------|
| **명시적 호출 빈도** | `skill_invoked` 이벤트 수를 skill별로 집계. 실제 `/skill:name` 호출의 기본 지표로 사용 |
| **직접 읽기 빈도** | `skill_read` 이벤트 수를 skill별로 집계. 에이전트가 SKILL.md를 직접 로드한 활동으로 별도 표시 |
| **일별 추이** | 날짜별 `skill_invoked`와 `skill_read` 건수를 각각 계산 |
| **마지막 호출일** | 가장 최근 `skill_invoked`의 `ts` |
| **마지막 읽기일** | 가장 최근 `skill_read`의 `ts` |

> `skill_invoked`는 이벤트 도입 이후부터 forward-only로 기록된다. 과거 데이터는 백필되지 않았으므로, 도입 전 기간의 호출 0회를 미사용 근거로 해석하지 않는다.

### Step 4: 인사이트 도출

산출된 수치를 바탕으로 아래 관점에서 인사이트를 도출한다.

#### 서브에이전트 인사이트

- **과다 사용**: 전체 호출의 40% 이상을 차지하는 에이전트 → 세분화(역할 분리) 검토 필요
- **미사용/저사용**: 분석 기간 내 0회 또는 1회만 호출된 에이전트 → 불필요 여부 검토
- **높은 에러율**: 에러율 20% 이상인 에이전트 → 프롬프트/설정 개선 필요
- **비효율**: 평균 소요시간이 다른 에이전트 대비 2배 이상인 에이전트 → 태스크 범위 축소 검토
- **continue 비율**: continue 모드 비율이 높으면 → 한 번에 완료하지 못하는 태스크가 많다는 신호
- **컨텍스트 초과**: `errorClass=context_overflow`이고 `peakContextTokens`가 모델 한도에 근접하면 → 태스크 분할·탐색 출력 제한·guard 조정 검토
- **도구 출력 과다**: 실패 직전 `lastToolOutputChars`가 크면 → 검색 limit·read range·대상 경로 축소 검토

#### 스킬 인사이트

- **미사용**: 계측 적용 기간 내 `skill_invoked`와 `skill_read`가 모두 0회인 스킬 → 삭제 또는 통합 검토
- **명시적 과다 호출**: 전체 `skill_invoked`의 50% 이상을 차지 → 해당 스킬의 명시적 호출 패턴 검토
- **과다 읽기**: 전체 `skill_read`의 50% 이상을 차지 → 반복 로드 또는 지나치게 넓은 트리거 검토
- **최근 미사용**: 마지막 호출과 마지막 읽기가 모두 30일 이상 전 → 여전히 필요한지 재평가

### Step 5: 보고서 출력

아래 형식으로 보고서를 작성한다.

```
## 📊 사용 통계 분석 (기간: YYYY-MM-DD ~ YYYY-MM-DD)

### 🤖 서브에이전트

From Jonghakseo/my-pi, MIT.

More from Jonghakseo/my-pi