flex-team/oncall-investigate

온콜 조사 (Investigate)

역할

Triage 결과(또는 직접 입력)를 받아 FE 코드 조사, BE 교차 조사, 원인 분류까지 수행하는 조사 스킬. 이슈 접수/분류는 /oncall-triage, 슬랙 메시지 작성은 /oncall-summarize의 역할이다.

Input

$ARGUMENTS — /oncall-triage의 Output 또는 직접 입력. 아래 정보가 필요하다:

| 필드 | 필수 | 예시 | |------|------|------| | 이슈 유형 | O | 데이터형, 오류형 등 | | FE/BE 판정 | O | FE 이슈, FE-BE 교차 | | 대상 레포 | O | flex-frontend-apps-fins | | 회사 ID | △ | 12345 (opensearch 조회 시 필요) | | 증상 | O | "영수증이 500건까지만 보임" |

• 대화 컨텍스트에 triage 결과가 있으면 그대로 사용한다.
• 직접 호출 시 위 필드를 직접 제공할 수 있다. 대상 레포가 없으면 /oncall-triage를 먼저 안내한다.

코드베이스 위치

• FE 코드 탐색 (읽기 전용): flex-fe/ 하위 각 레포 (서브모듈 — 탐색/grep 전용)
• FE 코드 수정: worktree 경로 — /vscode 스킬이 생성하는 worktree에서만 수정
• BE 코드 + opensearch: flex-support-oncall/ (BE 서브모듈 + brain/ 디렉토리)

진행 상황 표시 규칙

조사 중 발견

[확인] {확인된 사실} — {출처: 코드/로그/DB}
[의심] {의심되는 부분} — {근거}
[추론: {근거}] {추론 내용}

단계 전환 시

단계가 바뀔 때 (특히 FE→BE 교차 조사 전환 시) 명확히 표시:

● FE 코드 추적에서 API 응답 이상 발견. BE 교차 조사로 전환합니다.

  - API: `GET /api/v1/contracts/{id}`
  - 의심 필드: `endDate` — FE 파서 입력에 null로 들어옴
  [다음] opensearch에서 해당 API 실제 응답 확인

결론 도출 시

[결론] {FE 이슈 / BE 이슈 / 데이터 불일치 / 스펙 이슈 / Not a bug}
  - 원인: {한 줄 요약}
  - 근거: {확인된 사실}

조사 도구 가이드

| 도구 | 용도 | 적합한 상황 | 비고 | |------|------|-------------|------| | 코드 검색 (Grep, Glob, Read) | FE/BE 코드 추적 | 모든 이슈 — 화면→컴포넌트→API 경로 추적 | 기본 도구, 항상 사용 가능 | | Sentry (MCP) | FE 런타임 에러 확인 | 오류형 이슈, 콘솔 에러, 화면 깨짐 | 에러 스택트레이스, 발생 빈도, 영향 사용자 수 확인 가능. 별도 설치 필요 | | OpenSearch (os-query-log 스킬) | BE access log 조회 | API 응답 이상, 타임아웃, 500 에러 | customer_id + API path + 시간 범위로 검색. 별도 플러그인 설치 필요 | | GitHub PR/커밋 (gh CLI) | 최근 변경 이력 확인 | 갑작스러운 발생, 배포 직후 이슈 | git log --since, gh pr list 활용 | | Slack (MCP) | 이슈 스레드, 배포 채널 확인 | 맥락 파악, CS 추가 정보, 배포 이력 | 스레드 댓글에 중요 맥락이 있는 경우 많음 | | Chrome DevTools (MCP) | 브라우저에서 직접 재현 | 화면형 이슈, 네트워크 요청 확인 | dev/qa 환경에서 API 요청/응답을 직접 확인 | | Linear (MCP) | 이슈 조회, 상태 업데이트 | 모든 이슈 — 맥락 파악, 연관 이슈 검색 | 기본 연결됨 |

Sentry 활용 가이드

Sentry MCP가 설치되어 있으면, FE 이슈 조사 시 코드 추적 전에 Sentry를 먼저 확인한다:

1. 이슈 키워드(에러 메시지, 화면명, API 경로)로 Sentry에서 관련 이슈 검색
2. 에러 스택트레이스에서 원인 파일/라인을 바로 특정 → 코드 추적 범위를 좁힘
3. 발생 빈도와 영향 사용자 수로 긴급도 판단
4. 최초 발생 시점과 최근 배포 시점을 대조하여 배포 사이드이펙트 여부 확인

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

BE 이슈 조사

BE 이슈로 판단되면 flex-support-oncall/ 레포에서 조사한다. 이 레포에는 BE 서브모듈과 opensearch MCP가 설정되어 있다.

FE 온콜 담당자의 BE 조사 제약:

• DB 직접 조회 불가 — FE 개발자에게 DB 쿼리 권한이 없다. db:db-query 등 DB 스킬을 사용하지 않는다.
• opensearch access log만 활용 — os-query-log 스킬로 API 요청/응답 로그를 확인한다.
• DB 확인이 필요한 경우, 확인이 필요한 테이블/컬럼을 특정하여 BE 제보 메시지에 "DB 확인 필요" 항목으로 포함한다.

opensearch 로그 검색

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

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

opensearch MCP(os-query-log 스킬)를 활용하여 로그를 검색한다.

기본 필터링 조건:

• customer_id: CS 메시지에서 확인한 회사 ID
• authentication.email: 문의자/대상자 이메일
• 시간 범위: 이슈 인입 시간 기준 전후 1시간
• ipath: 문제 화면에서 호출하는 API 경로
• responseStatus: 에러코드가 명확하면 직접 필터링 (400, 500 등)

ipath(API 경로) 파악 방법:

1. 에러코드가 명확하면 → responseStatus로 바로 검색
2. 이슈 맥락의 화면을 브라우저에서 직접 접근 → 네트워크 탭에서 API 확인
3. 이슈에서 언급된 UI 텍스트의 번역키로 FE 코드베이스 검색 → 해당 컴포넌트에서 호출하는 API 확인
4. 해당 remote app 코드베이스에서 관련 도메인 코드 탐색

로그 분석 심화 가이드:

• 타임아웃/성능 이슈: responseStatus뿐 아니라 응답시간(duration)이 긴 요청을 함께 확인. exception trace에서 timeout, InterruptedIOException 등의 키워드 검색
• 간헐적 실패: 동일 API의 성공/실패 요청을 비교하여 차이점 파악 (요청 파라미터, 시간대, 동시 요청 수 등)
• 트랜잭션 정합성: 연관된 여러 API 호출이 있는 경우, 각각의 성공/실패 여부를 시간순으로 추적

조사 결과 정리 시 포함할 것:

• 문제가 된 API 경로와 request/response
• 에러 로그 또는 비정상 응답 내용
• 관련 trace ID (있으면)

FE 이슈 조사

FE 이슈로 판단되면 flex-fe/ 하위 해당 레포에서 탐색한다.

triage에서 특정된 대상 레포 내에서만 탐색한다. 대상 레포가 없으면 /oncall-triage를 먼저 실행하도록 안내한다.

⚡ FE 이슈 확정 즉시 — worktree 생성 (vscode 스킬)

FE 이슈로 판단되는 즉시 (코드 수정 여부와 무관하게) /vscode 스킬로 worktree를 생성한다. worktree가 있어야 개발자가 코드 diff 확인, dev server 재현, 수정 작업을 즉시 시작할 수 있다.

/vscode {ticket-id}

• /vscode 스킬이 worktree 생성 + 환경 초기화 + VSCode 열기를 모두 처리한다
• 유저에게 yarn dev:standalone으로 dev server를 띄워 재현 확인할 수 있음을 안내
• 코드 수정은 반드시 /vscode 스킬이 생성한 worktree 안에서만 한다
  • flex-fe/ 하위 서브모듈에서 직접 수정하면 안 됨

재현 시도 순서

1. Sentry: 에러 로그가 있다면 Sentry에서 잡힌 이슈/에러 메시지 상세 확인
2. dev/qa 환경 재현: 해당 서비스의 테스트 계정으로 문제 화면까지 직접 재현
3. 델리 요청: 재현이 안 되면 CS팀에 권한위임(델리) 요청 → 실제 고객사 케이스 직접 확인

코드 추적 — 데이터 흐름 우선

FE 버그 분석 시 가장 흔한 실수는 컴포넌트 로직, effect 의존성, 스키마 구조 등 FE 코드 내부 로직에 먼저 매몰되는 것이다. 실제로는 서버가 잘못된/불완전한 데이터를 내려주거나, 파싱 과정에서 데이터가 누락되는 경우가 많다.

반드시 이 순서를 따른다:

1. 해당 화면에서 호출하는 API 찾기 (query options, mutation, remote)
2. API 응답 데이터의 파싱/변환 로직 확인 (parser 함수)
   → 서버가 생성해야 할 데이터를 안 만들어서 파서 결과에 빠지는 경우 특히 주의
3. 파싱된 데이터가 폼/상태에 어떻게 들어가는지 확인 (useForm defaultValues, reset)
4. 검증 로직 확인 (Zod 스키마) — 저장 실패 시
   → 스키마가 모든 에러를 동일 메시지로 표시하는 경우 주의 (실제 에러 ≠ 표시 메시지)
5. 마지막에 렌더링/UI 로직 확인

화면 → 코드 찾기 체크리스트

이슈에서 언급된 화면의 코드를 찾을 때, 다음 순서로 효율적으로 탐색한다:

| 단계 | 방법 | 찾는 것 | |------|------|---------| | 1. 번역키/라우트 | UI 텍스트 → locales/ko/translation.json 검색, 또는 URL → web-pages/ 라우트 매칭 | 페이지/컴포넌트 진입점 | | 2. 페이지 컴포넌트 | 찾은 진입점에서 import 트리를 따라감 | 문제 화면의 메인 컴포넌트 | | 3. useQuery/useMutation | 해당 컴포넌트에서 사용하는 데이터 훅 확인 | API 엔드포인트, query key | | 4. 핸들러/로직 | onSubmit, onClick 등 이벤트 핸들러 확인 | 실제 동작 로직 |

탐색 중 길을 잃으면:

• src/domains/ 하위에서 관련 도메인 디렉토리를 직접 탐색
• remote app 이름으로 web-applications/remotes-* 디렉토리 탐색

가설 기반 조사 (소거법)

코드 추적 중 원인 후보가 보이면, 가설 테이블을 만들고 한 번에 하나씩 소거한다.

가설 테이블 초기화 — 처음에는 가장 유력한 1-2개만 세운다:

| # | 가설 | 확인 방법 | 상태 |
|---|------|----------|------|
| 1 | pageSize 하드코딩 | getReceiptsQueryOptions에서 상수 확인 | ⏳ 조사 중 |

소거 루프 — 가설이 확정되거나 모두 소거될 때까지 반복:

1. 현재 가설에 필요한 코드/로그만 확인 — 다른 가설을 위한 코드는 아직 읽지 않는다
2. 판정 + 테이블 즉시 업데이트:
   • ⏳ 조사 중 → ✅ 확정 (근거 1줄) → 루프 종료
   • ⏳ 조사 중 → ❌ 소거 (근거 1줄) → 다음 가설 추가
3. 중간 결과 표시:

   [확인] DEFAULT_PAGE_SIZE = 500 발견 — src/query/receipt/getReceiptsQueryOptions.ts:12
   → 가설 1 ✅ 확정
   

4. 소거된 경우, 조사 과정에서 발견한 단서로 다음 가설을 세운다

종료 조건:

• 가설 1개가 ✅ 확정
• 또는 3회 반복해도 확정 못함 → 현재까지의 사실/추론을 구분하여 "추정 원인"으로 결론

100% 확정이 아니어도 "추정 원인" 수준의 결론을 내리는 것이 미완료보다 훨씬 낫다.

증상 심각도에 따른 분석 방향

| 증상 | 의미 | 분석 방향 | |------|------|-----------| | "화면에 뭔가 이상하게 보인다" | UI 표시 문제 | FE 렌더링 로직 중심 | | "저장/제출/진행이 안 된다" | 데이터 또는 검증의 실질적 실패 | 데이터 흐름 중심 | | "둘 다" | 높은 확률로 데이터 문제가 근본 원인 | 데이터 흐름 중심 |

"저장이 안 된다"는 단순 UI 표시 문제가 아니다. 이 증상이 있으면 반드시 데이터 흐름부터 추적한다. 유저에게 증상의 범위를 반드시 확인한다.

FE↔BE 교차 조사 (Cross-Investigation)

FE 코드 추적에서 API 응답 데이터가 의심될 때 (파서 입력이 예상과 다른 경우, API 응답 필드 누락 등), BE 확인 요청 메시지를 작성하기 전에 BE 쪽을 직접 탐색하여 의심 지점을 좁힌다. 목표는 BE 개발자가 바로 작업에 착수할 수 있을 만큼 구체적인 제보를 만드는 것이다.

진입 조건

FE 조사 중 다음 중 하나에 해당하면 이 단계로 진입:

• API 응답 파싱 결과가 예상과 다름 (파서는 정상이나 입력 데이터가 이상)
• FE 코드는 정상이나 화면에 표시되는 데이터가 잘못됨
• 특정 API endpoint의 응답 구조/값이 의심됨

진입 시 반드시 단계 전환을 표시한다:

● FE 코드 추적에서 API 응답 이상 발견. BE 교차 조사로 전환합니다.

  - API: `{method} {endpoint}`
  - 의심 필드: `{필드명}` — {왜 의심하는지}
  [다음] opensearch에서 해당 API 실제 응답 확인

조사 순서

1. FE에서 API 정보 수집

   • endpoint path, HTTP method, request parameters 확인
   • 어떤 response 필드가 문제인지 특정
   • FE 코드가 정상임을 확인한 근거 정리 (파서, 폼 바인딩, 렌더링 확인 완료)

2. BE access log 확인 (반드시 /os-query-log 스킬 사용 — curl 직접 호출 금지)

   • FE에서 확인한 API path + customer_id + 시간 범위로 로그 검색
   • 실제 response status, duration 확인
   • 가능하면 동일 API의 정상 요청과 비교하여 차이점 파악

3. BE 코드 탐색 (flex-support-oncall/ 서브모듈)

   • API endpoint에 해당하는 controller → service 코드 확인
   • 문제 필드의 데이터 생성/조회 로직에서 의심 지점 식별
   • DB 직접 조회는 불가 — FE 개발자에게 DB 쿼리 권한이 없음. DB 확인이 필요한 경우 BE 제보 시 "DB 확인 필요" 항목으로 포함

4. 의심 지점 정리 → BE 제보용 요약 작성

   • FE는 정상임을 확인한 근거 + BE 쪽 의심 지점을 정리
   • /oncall-summarize의 **"BE 제보 포맷"**으로 슬랙 메시지 작성

주의사항

• BE 코드를 깊이 파고들어 근본 원인까지 찾을 필요는 없다. 의심 지점을 좁히는 것이 목표다.
• BE 코드 탐색도 3단계 이내로 제한: controller → service → repository/query 수준까지.
• 로그에서 명확한 에러가 보이면 BE 코드 탐색 없이 바로 제보해도 된다.

원인 분류

분석 결과를 다음 중 하나로 분류한다:

• BE 이슈: 서버가 데이터를 잘못 내려주거나, 생성해야 할 데이터를 생성하지 않음
• FE 이슈: 파싱 로직 버그, 검증 로직 오류, 렌더링 버그 등
• 데이터 불일치: FE와 BE 간 데이터 계약(contract)이 맞지 않음
• 스펙 이슈: 의도된 동작이지만 유저 기대와 다름 → "버그가 아니라 기존 스펙의 한계"임을 명시하고, 개선이 필요한지 판단
• Won't fix (구조적 한계): 원인은 파악되었으나, 수정하려면 BE API 구조 변경/검색 엔진 재설계 등 대규모 작업이 필요하고, 영향 범위가 제한적인 경우. "개선 사항으로 접수" 또는 "VoC로 전환"을 권고
• Not a bug: 이미 수정 완료된 이슈, 사용자 착각, 또는 일시적 환경 문제

코드 수정 시 동일 패턴 전수 검사

원인이 되는 코드(상수, 파라미터, 로직 패턴)를 찾아 수정할 때, 해당 값/패턴이 레포 내 다른 곳에도 존재하는지 반드시 grep으로 전수 검사한다.

• 같은 상수(예: DEFAULT_PAGE_SIZE = 500)가 다른 파일에도 중복 정의되어 있을 수 있다
• 같은 API를 호출하는 다른 query options/hooks가 존재할 수 있다
• 한 곳만 수정하고 다른 곳을 놓치면 동일 이슈가 다른 경로에서 재발한다

PR 작성 규칙

온콜 이슈로 PR을 생성할 때는 제목 끝에 반드시 티켓 번호를 병기한다:

• 형식: type(scope): 설명 [TICKET-ID]
• 예: fix(electronic-approval): 지출결의서 영수증 조회 제한 500 → 1000으로 증가 [CI-4334]

Output

[결론] {FE 이슈 / BE 이슈 / 데이터 불일치 / 스펙 이슈 / Won't fix / Not a bug}
  - 원인: {한 줄 요약}
  - 근거: {확인된 사실}
  - 관련 파일: {파일경로:라인}

### 가설 테이블
| # | 가설 | 확인 방법 | 상태 |
|---|------|----------|------|
| 1 | ... | ... | ✅ 확정 / ❌ 소거 |

### 재현 경로
1. ...

### 다음 단계
- 슬랙 메시지 작성: `/oncall-summarize`
- 코드 수정이 필요하면: worktree에서 직접 수정 후 PR

주의사항

• 코드 참조 시 파일 경로와 라인 번호를 포함한다.
• 재현 경로는 누구나 따라할 수 있을 정도로 상세하게 작성한다.
• BE 확인 요청 시, BE 개발자가 어떤 API/로직을 확인해야 하는지 구체적으로 명시한다.
• 이슈 분석 중 추가 정보가 필요하면, 유저에게 확인을 요청한다. 특히 증상의 범위("저장도 안 되나요?")는 반드시 묻는다.
• 코드 탐색에 매몰되지 않는다. 3단계 탐색 후에도 원인을 못 찾으면, 현재까지의 분석으로 결론을 내고 /oncall-summarize로 슬랙 메시지를 작성한다.