ariadne

한 줄 설명: 프론트 API 레이어가 백엔드 REST API와 실제로 맞는지 전체 또는 변경분 기준으로 검증하는 스킬이다.

언제 사용해야 하는지

• 프론트엔드에 구현된 API 함수, 훅, 클라이언트 레이어가 백엔드 REST API와 맞는지 확인해야 할 때
• 프론트 PR에서 API 관련 변경이 들어갔고, 백엔드 기준 브랜치와 비교해 깨진 계약이 없는지 보고 싶을 때
• 백엔드가 별도 레포로 관리되고 있어도, 프론트 레포 안에서 서버 코드 기준 검증 리포트를 만들고 싶을 때
• OpenAPI 문서보다 실제 서버 코드가 더 신뢰할 만해서, 라우트와 DTO 구현을 기준으로 맞춤 검증을 해야 할 때
• 의도적으로 API 규격 차이를 허용한 항목을 파일로 남겨 같은 질문을 반복하지 않도록 관리하고 싶을 때

먼저 읽어야 할 파일

• 설정 파일이나 waiver 형식이 필요하면 references/config-template.md
• .ariadne/ 상태 파일을 만들거나 갱신할 때는 scripts/api_parity_state.py

기본 전제

• 현재 작업 디렉터리는 프론트엔드 레포라고 가정한다.
• 백엔드 truth source는 OpenAPI 문서가 아니라 서버 코드다. OpenAPI 또는 Swagger는 보조 근거로만 사용한다.
• .ariadne/state.json이 없으면 사용자가 check를 요청해도 자동으로 init부터 수행한다.
• .ariadne/ 아래 파일은 로컬 검증 상태로 취급한다.
• 첫 init 때는 .ariadne/를 .gitignore에 추가할지 꼭 묻는다. .gitignore가 없고 사용자가 동의하면 새로 만든다.

입력으로 기대하는 정보

init

• 모노레포가 아니면 백엔드 GitHub 레포 주소
• 초기 기준 브랜치
• .gitignore에 .ariadne/를 추가할지 여부

check

• 이번 검증에 사용할 백엔드 타겟 브랜치
• 사용자가 비워 두면 기본값 develop

입력이 부족할 때 처리 규칙

• 먼저 현재 워크스페이스가 모노레포인지 자동으로 탐지한다.
• 모노레포가 아니고 백엔드 위치를 로컬에서 찾을 수 없으면 그때만 백엔드 GitHub 레포 주소를 묻는다.
• 초기 기준 브랜치는 우선 develop으로 시도한다.
• develop이 실제로 없거나 프론트와 백엔드 기준 브랜치가 다를 가능성이 높을 때만 사용자에게 다시 묻는다.
• check에서는 백엔드 타겟 브랜치를 매번 묻되, 입력이 없으면 항상 develop으로 진행한다.

로컬 파일 계약

• .ariadne/config.yaml
  • 자동 추론된 기준 설정과 수동 override를 저장한다.
• .ariadne/inventory.json
  • 백엔드 엔드포인트, 프론트 호출, 비교 요약 캐시를 저장한다.
• .ariadne/state.json
  • 마지막 분석 SHA, 마지막 실행 시각, 마지막 사용 브랜치, 재분석 트리거 상태를 저장한다.
• .ariadne/waivers.yaml
  • 의도적으로 허용한 불일치 항목을 저장한다.

init 작업 절차

1. 현재 프론트 레포에서 백엔드 디렉터리가 함께 있는지 확인해 모노레포 여부를 판단한다.
2. 모노레포가 아니면 백엔드 GitHub 레포 주소를 받는다.
3. 초기 기준 브랜치는 우선 develop으로 두고, 실제로 없거나 구조가 모호하면 사용자에게 확인한다.
4. .gitignore에 .ariadne/를 추가할지 사용자에게 묻는다.
5. 사용자가 동의하면 .gitignore가 없더라도 새로 만들어 .ariadne/를 추가한다.
6. GitHub 레포 트리와 서버 코드 파일을 읽어 아래 항목을 자동 추론한다.
   • backend_roots
   • backend_route_globs
   • backend_dto_globs
   • path_normalization_rules
   • auth_or_header_conventions
7. 프론트 레포에서는 아래 항목을 자동 추론한다.
   • frontend_roots
   • frontend_client_globs
   • shared_http_globs
8. 추론 결과는 .ariadne/config.yaml에 저장하고, .ariadne/state.json과 .ariadne/inventory.json을 초기화한다.
9. 상태 파일 생성과 기본 메타데이터 기록은 python3 skills/frontend/ariadne/scripts/api_parity_state.py init ...으로 처리한다.
10. 마지막에는 초기화 결과와 남은 수동 확인 항목만 짧게 정리한다.

check 작업 절차

1. .ariadne/state.json이 없으면 자동으로 init로 전환한다.
2. 이번 검증에 사용할 백엔드 타겟 브랜치를 사용자에게 묻는다.
3. 사용자가 비워 두면 저장된 값과 무관하게 develop을 사용한다.
4. 프론트 변경분은 PR 문맥이 있으면 PR base 기준으로 계산하고, 없으면 frontend_base_branch 기준 git diff로 계산한다.
5. 백엔드 변경분은 이번에 받은 타겟 브랜치 기준으로 최신 변경 파일과 영향받은 라우트, DTO만 다시 읽는다.
6. 아래 항목이 바뀌면 증분 검증 대신 전체 재분석으로 폴백한다.
   • 공통 HTTP 래퍼
   • 경로 조립 규칙
   • .ariadne/config.yaml
   • 이번 check의 백엔드 타겟 브랜치
   • 백엔드 분석 신뢰도가 낮은 경우
7. 신규 불일치가 나오면 의도적 예외인지 확인하고, 사용자가 원할 때만 .ariadne/waivers.yaml에 저장한다.
8. 이미 저장된 waiver와 일치하는 항목은 다시 묻지 않고 waived 상태로 표시한다.
9. 실행 결과는 python3 skills/frontend/ariadne/scripts/api_parity_state.py record-run ...으로 상태 파일에 기록한다.

비교 기준

• 비교 단위는 HTTP method + normalized path다.
• 서버 코드 기준으로 아래 항목을 비교한다.
  • path params
  • query params
  • request body shape
  • success response envelope
  • error response envelope
  • 프론트 호출 존재 여부
• OpenAPI 문서가 있으면 시그니처 보조 증거로만 사용하고, 서버 코드와 충돌하면 서버 코드 쪽을 우선한다.

결과 분류

• matched
• backend-only
• frontend-only
• signature-mismatch
• schema-mismatch
• manual-review
• waived

반드시 지켜야 하는 출력 형식

항상 아래 순서의 마크다운 리포트로 작성한다.

# Ariadne API Parity Report

## 검증 컨텍스트
- 실행 모드: init / check
- 프론트 기준 브랜치:
- 백엔드 타겟 브랜치:
- 프론트 변경분 기준:
- 백엔드 변경분 기준:
- 전체 재분석 여부:

## 요약 표
| 상태 | 개수 |
| --- | ---: |
| matched | 0 |
| backend-only | 0 |
| frontend-only | 0 |
| signature-mismatch | 0 |
| schema-mismatch | 0 |
| manual-review | 0 |
| waived | 0 |

## 불일치 상세 표
| method | path | issue_type | backend_evidence | frontend_evidence | suggested_owner | suggested_fix |
| --- | --- | --- | --- | --- | --- | --- |
| GET | /example | signature-mismatch | ... | ... | frontend | ... |

## waiver 적용 항목
| method | path | issue_type | reason | owner |
| --- | --- | --- | --- | --- |

## 수정 후보
- frontend: ...
- backend: ...

## 가정 / 수동 확인 필요 항목
- ...

출력 규칙

• backend_evidence와 frontend_evidence에는 가능한 한 파일 경로, 심볼명, 라인 근거를 짧게 적는다.
• suggested_owner는 frontend, backend, shared, manual 중 하나로 통일한다.
• manual-review는 자동 추론 신뢰도가 낮은 항목만 사용한다.
• waived는 불일치가 없다는 뜻이 아니라, 이미 합의된 예외라는 뜻으로만 사용한다.
• 수정 후보는 바로 티켓이나 후속 작업으로 옮길 수 있을 정도로 행동 단위로 적는다.

Waiver 처리 규칙

• 새 불일치를 발견해도 자동으로 waiver를 만들지 않는다.
• 사용자가 의도된 차이라고 명시적으로 확인한 경우에만 .ariadne/waivers.yaml에 기록한다.
• 같은 method + path + issue_type 조합이 기존 waiver와 일치하면 다시 묻지 않는다.
• 만료일이 지난 waiver는 자동 신뢰하지 말고 다시 검토 대상으로 올린다.

품질 체크리스트

• 현재 워크스페이스가 프론트 레포라는 전제를 확인했는가
• check에서 백엔드 타겟 브랜치를 실제로 다시 물었는가
• 미입력 시 기본값을 develop으로 사용했는가
• 모노레포 여부를 먼저 판단하고 불필요한 질문을 줄였는가
• 서버 코드 기준 비교와 OpenAPI 보조 근거를 구분했는가
• 전체 재분석 트리거를 놓치지 않았는가
• waiver 적용 항목과 실제 미해결 불일치를 섞지 않았는가
• 리포트가 검증 컨텍스트 -> 요약 -> 상세 -> waiver -> 수정 후보 -> 가정 순서를 지켰는가
• 수정 후보가 프론트와 백엔드 중 누가 봐도 바로 이해할 수 있는 행동 단위인가

예시 요청

• ariadne로 지금 프론트 API 계층이 백엔드 develop 기준과 맞는지 init부터 설정해줘.
• 이 PR에서 바뀐 API 호출이 백엔드 release/2026-04 기준으로 안전한지 ariadne check 해줘.
• 백엔드 레포는 github.com/example/backend 야. ariadne init으로 자동 설정부터 잡아줘.
• 의도적으로 무시한 에러 응답 차이가 있는데 ariadne waiver로 저장해서 다음부터는 묻지 않게 해줘.