Jamie-BitFlight/transcript-analysis

Transcript Analysis

Claude Code JSONL 세션 기록을 분석하여 안티패턴, 비효율성 및 워크플로우 개선 기회를 탐지합니다.

데이터 위치

트랜스크립트는 ~/.claude/projects/ 아래 프로젝트별 디렉토리(프로젝트 경로를 하이픈으로 슬래시를 대체한 이름)에서 찾을 수 있습니다.

DuckDB의 역할: kaizen-analysis의 get_transcript_jsonl_schema 또는 MCP resources/read kaizen://session-log/schema를 통해 전체 필드/경로 참조를 로드한 다음, kaizen-duckdb **execute_query**를 사용하여 해당 파일에 대해 모든 DuckDB SQL을 실행합니다(예제 및 임의 쿼리 워크플로우는 DuckDB 쿼리 패턴 참조). 세션 기록은 디스크에 JSONL로 저장됩니다. DuckDB MCP의 경로 규칙(절대 경로 사용, SQL에 ~ 사용 불가).

~/.claude/projects/{project-key}/
├── {uuid}.jsonl              # 메인 세션 트랜스크립트
├── agent-{id}.jsonl          # 고아 에이전트 트랜스크립트
└── {uuid}/
    ├── subagents/
    │   └── agent-{id}.jsonl  # 서브에이전트 트랜스크립트
    └── tool-results/
        └── {tool-use-id}.txt # 비동기 작업 출력

JSONL 레코드 유형

각 JSONL 라인은 type 필드로 구분되는 JSON 객체입니다.

분석을 위한 기본 레코드 유형:

• assistant — 도구 호출 및 텍스트를 포함한 LLM 응답 턴
• user — 인간 입력 및 도구 결과
• system — 메타데이터 이벤트(stop_hook_summary, turn_duration, compact_boundary, api_error, local_command)
• progress — 훅 실행 및 서브에이전트 스트리밍
• file-history-snapshot — 파일 편집 추적
• summary — 세션 제목/요약

전체 스키마 세부 정보(각 레코드 유형의 JSON 구조 포함)는 JSONL 스키마 참조를 참조하세요.

신호 카탈로그

아래 각 분석 차원에는 고유한 추출 방법론이 있습니다.

1. 도구 오용 탐지

assistant.message.content[]에서 name == "Bash"인 항목을 추출합니다. input.command를 파싱하여 기본 제공 도구를 사용해야 하는 파일 작업 패턴을 찾습니다. SQL 추출 쿼리는 DuckDB 쿼리 패턴을 참조하세요.

tool_use 블록을 파싱하여 다음 Bash 명령어를 찾습니다:

• grep → Grep 도구를 사용해야 함
• find -name → Glob 도구를 사용해야 함
• cat, head, tail → Read 도구를 사용해야 함
• ls → Glob 또는 설명이 포함된 Bash(ls)를 사용해야 함
• sed, awk → Edit 도구를 사용해야 함

파이프라인(git ... | grep, uv run ... | head)에서의 정당한 사용은 제외합니다.

2. 반복 오류

도구 결과에서 is_error: true인 항목을 추출합니다. 오류 유형 분류:

• "File has not been read yet" — 편집 전 읽지 않음 안티패턴
• "String to replace not found" — 오래된 편집 대상
• "User denied tool use" — 권한/신뢰 문제
• 사전 커밋 후크 실패(종료 코드 1)
• 바이너리 누락 / 명령어를 찾을 수 없음

3. 누락된 도구 사용 기회

세션 간에 반복되는 다단계 수동 워크플로우를 도구 시퀀스 트라이그램 분석을 통해 식별합니다. Bash → Bash → Bash 또는 Read → Read → Read와 같은 고빈도 트라이그램은 누락된 스크립트 또는 스킬이 있음을 시사합니다.

4. 서브에이전트 위임 패턴

Task tool_use 블록에서 추출합니다. subagent_type, description, model을 추적합니다. 전문화된 에이전트가 존재하는 곳에 general-purpose가 사용된 경우 플래그를 지정합니다.

5. 단축 경로 분석

동일한 목표에 대한 성공 및 실패 시도를 비교합니다. 목표 진술(사용자 턴)과 성공적인 결과(최종 assistant 턴) 사이의 도구 호출 횟수를 측정합니다. 유사한 목표에 대한 세션 간 높은 변동성은 낭비된 단계를 나타냅니다.

6. 레드 헤링 탐지

중단된 조사 분기를 추적합니다. 신호: 주제에 대한 Read/Grep/Bash 호출 시퀀스 후 해결 없이 compact_boundary 또는 방향 전환이 발생한 경우. 동일한 중단된 경로의 교차 세션 빈도는 체계적인 레드 헤링을 드러냅니다.

7. 시스템 프로세스 중단

system.compact_boundary, system.api_error 및 훅 관련 progress 이벤트를 추출합니다. 활성 작업 기준으로 해당 위치를 매핑하여 시스템 프로세스가 올바른 실행 경로를 이탈시킨 시점을 식별합니다.

8. 누락된 훅

세션 간에 반복되는 수동 수정을 식별합니다. 동일한 수정이 3회 이상 나타나면 PreToolUse 훅(거부 + 리디렉션) 또는 SubagentStart 훅(컨텍스트 주입)을 통한 자동화된 예방 대상이 됩니다.

9. DuckDB SQL 쿼리

kaizen-analysis get_transcript_jsonl_schema 또는 리소스 **kaizen://session-log/schema**를 사용하여 전체 경로 참조를 가져온 후, kaizen-duckdb **execute_query**를 사용하여 JSONL에 대한 모든 SQL(절대 경로와 함께 read_ndjson_auto 사용)을 실행합니다. 제공된 쿠키북 쿼리에 제한되지 않습니다.

임의 쿼리 워크플로우 및 예제는 DuckDB 쿼리 패턴을 참조하세요.

프로세스 마이닝 방법론

SQL로 표현할 수 없는 분석을 위해 kaizen-analysis MCP 서버 도구를 사용하세요:

• extract_tool_sequences — JSONL → 세션별 정렬된 도구 호출 배열 변환
• discover_process_model — 도구 호출 시퀀스에 대한 경량 전이 모델
• check_conformance — 참조 프로세스 모델과 세션 비교
• find_frequent_patterns — PrefixSpan 순차 패턴 마이닝
• cluster_sessions — 행동 유사성에 의한 추적 클러스터링

분석 워크플로우

flowchart TD
    Start([분석 작업 수신]) --> Scope{범위 지정됨?}
    Scope -->|--project 플래그| Project[프로젝트 트랜스크립트로 필터링]
    Scope -->|플래그 없음| Default[현재 프로젝트 사용]
    Project --> Discover[SQL — 세션 수, 날짜 범위, 레코드 유형 카운트]
    Default --> Discover
    Discover --> Dimensions{어떤 차원?}
    Dimensions -->|모두| RunAll[모든 차원 실행]
    Dimensions -->|지정됨| RunSelected[선택된 차원 실행]
    RunAll --> Aggregate[결과 집계]
    RunSelected --> Aggregate
    Aggregate --> Write[.planning/kaizen/analysis-DATE.md에 쓰기]

출력 형식

분석 결과를 .planning/kaizen/에 구조화된 마크다운으로 작성하며, 다음을 포함합니다:

• 각 분석 결과에 대한 세션 ID 및 날짜
• 심각도 (치명적 / 경고 / 정보)
• 증거 — 정확한 JSON 필드 경로 및 값
• 빈도 — 해당 패턴을 보여주는 세션 수
• 권장 유형 — 훅, 스킬 패치, 에이전트 프롬프트 수정, CLAUDE.md 업데이트