Oncall Triage

슬랙 스레드 정보 캡처: Slack URL로 접수한 경우 slack_read_thread 호출 시 사용한 channel_id와 message_ts를 Output에 포함한다. Linear 티켓으로 접수한 경우에도 티켓에 Slack 링크가 첨부되어 있으면 URL에서 channel_id와 message_ts를 추출하여 포함한다. 이 정보는 /oncall-summarize에서 슬랙 초안을 스레드에 답장으로 생성할 때 사용된다.

코드베이스 위치

• FE 코드: flex-fe/ 하위 각 레포 (flex-frontend-apps-performance-management, flex-frontend-apps-time-tracking 등)
• BE 코드 + opensearch: flex-support-oncall/ (BE 서브모듈 + brain/ 디렉토리)

진행 상황 표시 규칙

각 단계를 실행할 때, 사용자가 현재 어디에 있는지 알 수 있도록 아래 포맷으로 진행 상황을 표시한다.

단계 진입 시

● {단계 요약 한 줄}

  {구체적 내용 — 무엇을 확인하는지, 어디를 보는지}

분류/판단 결과

[분류] {유형} ({영문}) — {근거 한 줄}
[첫 번째 액션] {다음에 할 일}

Step 1: 이슈 접수 및 맥락 파악

CS팀이 슬랙에 올린 이슈 메시지에서 다음 정보를 추출한다:

• 회사 ID / 회사명: CS 메시지에 포함됨
• 문의자 / 이슈 대상자: 이메일 등
• 서비스 영역: 어떤 기능(비용관리, 평가, 근태 등)에서 발생했는지
• 구체적 상황: 어떤 화면에서 어떤 조작을 했을 때 발생하는지
• 증상: 에러가 나는지, 화면이 안 보이는지, 데이터가 이상한지 등
• 긴급도: rotating_light(긴급) / red_circle(상) / large_orange_circle(중)

슬랙 메시지 URL이 제공되면 Slack MCP로 스레드 내용을 읽어 맥락을 파악한다. CS팀이 스레드에 추가 맥락을 남기는 경우가 많으므로 스레드 댓글도 반드시 확인한다.

Step 2: Triage — 이슈 유형 분류

긴급도 기반 분기

먼저 긴급도를 확인한다:

• rotating_light(긴급) + 광범위 영향 (다수 회사/전체 서비스 영향): 상세 조사보다 즉각 escalation이 우선. 크리티컬 채널(#critical 등)에 이미 올라갔는지 확인하고, 안 올라갔으면 유저에게 크리티컬 채널 escalation을 제안한다. 조사는 escalation 후 병행한다.
• red_circle(상): 빠르게 triage → 조사 → 결과 공유 진행
• large_orange_circle(중): 일반 워크플로우 진행

스펙 이슈 사전 판별

이슈 유형 분류 전에, CS가 보고한 증상이 기존 스펙(의도된 동작)과 일치하는지 먼저 확인한다:

1. 증상이 "원래 이런 건가요", "정상인가요" 류가 아니더라도, "A인데 B로 보인다" (표시 불일치) 또는 "X를 했는데 Y가 안 된다" (기대와 다른 동작) 패턴이면 스펙 이슈 가능성을 먼저 체크
2. 해당 도메인의 기존 스펙/정책 문서가 있으면 확인 (PM 노션, 코드 내 상수/enum 정의 등)
3. 동일 도메인의 최근 이슈 스레드에서 비슷한 문의가 있었는지 확인

스펙 이슈 의심 패턴 — 아래 중 하나라도 해당하면 버그 조사 전에 "이것이 의도된 동작일 수 있는 이유"를 반드시 먼저 검토한다:

CS 표현 신뢰도 주의: CS의 "타입: 버그"나 "수정 요청" 같은 표현을 이슈 유형 판단의 결정적 근거로 사용하지 않는다. CS는 고객 요구를 그대로 전달하는 경우가 많으므로, CS의 타입 지정보다 증상의 구체적 내용을 기반으로 판단한다.

판별 결과에 따른 분기:

• 의도된 동작 확인됨 → "스펙 이슈"로 최종 분류. /oncall-summarize의 "스펙 이슈 / Not a bug 포맷"으로 결과 작성. 버그 조사 진행하지 않음.
• 의도된 동작이 아님 확인됨 → 즉시 버그 경로로 전환. "이슈 유형 분류" 테이블에서 유형을 재지정하고 조사로 진행.
• 판단 불가 (스펙 문서 없음, 담당자 확인 필요) → 두 가능성을 모두 열어둔 채 최소한의 코드 확인만 진행. 슬랙 메시지에 "스펙 이슈 가능성이 있어 담당자 확인이 필요합니다"를 명시.

이슈 유형 분류

flex-support-oncall 레포의 brain/triage-signals.md에 정의된 분류 기준을 따른다:

복합 신호 처리:

• 명확한 장애 신호(500, 타임아웃)가 있으면 해당 타입 우선
• 모호하면 스펙질문형으로 시작 — 의도된 동작인지 먼저 확인
• "안 보여요"는 데이터형/화면형 중복 → API 응답이 정상이면 화면형으로 재분류

FE vs BE 판단

로그 선확인 (데이터형/오류형/판단 모호 시)

키워드만으로 FE/BE 판단이 어려운 경우, triage 단계에서 로그를 먼저 확인하여 판정 정확도를 높인다. 특히 데이터형 이슈는 API 응답을 확인해야 FE/BE를 구분할 수 있으므로, investigate로 넘기기 전에 반드시 로그를 본다.

대상: 아래 조건 중 하나라도 해당하면 로그 선확인을 진행한다:

• 데이터형으로 분류된 이슈 (누락, 불일치, 값이 다르다)
• 오류형으로 분류된 이슈 (500, 400, 에러)
• FE/BE 판단이 "판단 불가"인 이슈

확인 절차:

⛔ [MUST] curl로 OpenSearch를 직접 호출하지 않는다. 로그 조회는 반드시 opensearch:os-query-log 스킬을 통해서만 수행한다.

• MCP 도구(mcp__opensearch-prod__search_documents 등)가 세션에 없으면, curl로 우회하지 않는다.
• 대신 유저에게 ~/.mcp.json opensearch MCP 서버 설정 + uvx 설치 + Claude Code 재시작을 안내한다.
• curl fallback은 유저가 명시적으로 허가한 경우에만 사용한다.

1. 이슈 맥락에서 관련 API 경로를 추정한다 (CS 메시지의 화면명/기능명 → 해당 API)
2. /os-query-log로 access log를 조회한다:
   • 회사 ID + API 경로 + 이슈 발생 시점 기준으로 검색
   • HTTP 상태코드, 응답 시간, 응답 바디(가능한 경우)를 확인
3. 로그 결과에 따라 FE/BE 판정을 확정하거나 보강한다:

● 로그 선확인 — 데이터형 이슈, API 응답 확인
  /os-query-log: {API 경로}, company_id={id}, 시점={발생 시각 전후}
  → API 200, 응답 정상 → [판정] FE 이슈로 업데이트

Step 3: 기존 이슈/PR 이력 선조회

오류형/성능형 이슈 전용 — 최근 배포 선체크: 오류형 또는 성능형으로 분류된 이슈는, 로그 조회 전에 아래를 먼저 확인한다:

1. 해당 서비스의 최근 24-48시간 배포 이력 확인 (이슈 도메인뿐 아니라 인프라/공통 모듈 포함)
   • #alarm-deploy-prod 또는 #release-hq 슬랙 채널에서 최근 배포 확인
   • 이슈가 "갑자기 발생" 패턴이면 배포 시점과 이슈 발생 시점을 대조
2. 배포가 있었다면 → 해당 배포의 변경 내용을 먼저 확인하고, 사이드이펙트 가능성 판단
3. 배포가 없었다면 → 트래픽 증가, 데이터 증가 등 환경 변화 가능성 확인 후 로그 조사

코드를 깊이 파기 전에, 아래 3가지를 병렬로 조회한다. 이미 해결되었거나 관련 수정이 진행 중인 경우가 많다.

3-A. git log / PR 이력

1. git log 검색: 해당 도메인 디렉토리의 최근 1-2주 커밋/PR 이력 확인
   • git log --oneline --since="2 weeks ago" -- <도메인 디렉토리>
2. 관련 PR 검색: GitHub에서 해당 도메인 키워드로 최근 merged/open PR 확인
3. 슬랙 스레드 이력: 동일 도메인의 최근 이슈 스레드에서 유사한 문의/핫픽스 이력 확인

3-B. Linear 유사 이슈 검색 (CI 팀)

목적: 동일하거나 유사한 이슈가 이미 접수/해결된 적이 있는지 확인하여 중복 조사를 방지하고, 기존 해결 방법을 참고한다.

검색 방법: mcp__linear__list_issues로 CI 팀 하위 이슈를 검색한다. 검색 정확도를 높이기 위해 2-3개 키워드 조합을 병렬로 시도한다:

mcp__linear__list_issues(team: "CI", query: "{증상 키워드}", limit: 5)
mcp__linear__list_issues(team: "CI", query: "{서비스영역 + 기능}", limit: 5)

2-3개 검색을 병렬 호출하여 시간을 절약한다. 각 검색은 limit: 5로 제한.

결과 해석:

Output에 반영: 유사 이슈가 발견되면 Triage 결과에 아래를 추가한다:

### 유사 이슈
- {CI-XXXX} ({상태}) — {제목} : {유사점 한 줄}
- {CI-YYYY} ({상태}) — {제목} : {유사점 한 줄}

3-C. 결과 종합

이력에서 관련 변경을 찾으면:

• 해당 PR/커밋의 변경 내용을 우선 분석 — 사이드이펙트인지 확인
• 이미 수정 배포된 건이면 → "이미 해결됨 (Not a bug)" 경로로 빠르게 결론

Linear에서 유사 이슈를 찾으면:

• 동일 이슈(Done)면 → regression 여부 확인 후 "이미 해결됨" 또는 "재발" 판정
• 진행 중 이슈면 → 중복 여부를 유저에게 알리고 합류/신규 결정 요청
• 유사 이슈의 해결 방향이 현재 이슈에 참고가 되면 → investigate 단계에 컨텍스트로 전달

Sentry 확인 (오류형/화면형 이슈)

Sentry MCP가 설치되어 있으면, 오류형 또는 화면형 이슈에서 Sentry를 먼저 확인하여 FE/BE 판별 근거를 강화한다:

1. 이슈 키워드(에러 메시지, 화면명, API 경로)로 Sentry에서 관련 이슈 검색
2. 에러가 잡혀 있으면 → FE 이슈 확정 근거 (스택트레이스에서 원인 파일/라인 특정 가능)
3. 에러가 없으면 → FE 런타임 에러는 아님 → BE/데이터 이슈 가능성 높음
4. 발생 빈도와 영향 사용자 수로 긴급도 재평가
5. 최초 발생 시점과 최근 배포 시점을 대조하여 배포 사이드이펙트 여부 판단

[확인] Sentry에서 동일 에러 발견 — TypeError: Cannot read property 'endDate' of null
  - 최초 발생: 2026-04-05 14:30 (배포 v2.2026-04-05.1 직후)
  - 영향: 3개 회사 7명
  - 스택트레이스: ContractDetail.tsx:142 → useContractQuery
  → FE 이슈 확정, 대상 파일까지 특정됨

Step 4: 대상 레포 특정 (FE 이슈인 경우)

FE 이슈로 판정되면 서비스 영역을 기반으로 대상 레포를 특정한다.

서비스 영역 → 레포 매핑

CS 메시지에서 backtick으로 감싼 서비스 영역 태그(예: `비용관리`, `근태관리`)를 확인하고, 아래 매핑 테이블로 후보 레포를 선정한다:

grep으로 후보 레포 검증

후보 레포가 맞는지 확인하기 위해, 이슈 맥락에서 추출한 핵심 키워드(API 경로, UI 텍스트, 기능명 등)로 후보 레포에서 grep을 1회 실행한다.

• 히트 있음 → 후보 레포 확정
• 히트 없음 → 매핑이 잘못된 것. 다른 후보 레포로 확장하여 재검색

주의사항

• 이 스킬에서는 코드를 깊이 파고들지 않는다. 코드 조사는 /oncall-investigate의 역할이다.
• 이슈 분석 중 추가 정보가 필요하면, 유저에게 확인을 요청한다. 특히 증상의 범위("저장도 안 되나요?")는 반드시 묻는다.