📄 [Docs] CLAUDE.md 레퍼런스 보강 — Cygnus 서버 · PR 제목 컨벤션 (#1243)

[JEONG-J]

✨ PR 유형

Docs — 문서 레퍼런스 보강 2건.

1. CLAUDE.md 상세 레퍼런스에 백엔드(서버) 레포 참고 경로·사용 규칙 추가
2. PR 제목 컨벤션({이모지} [Type] {내용} (#이슈번호))을 문서에 명문화

Closes #1243

📷 스크린샷 or 영상(UI 변경 시)

문서 변경만 있어 해당 없음.

🛠️ 작업내용

1. 백엔드 레포 레퍼런스 (CLAUDE.md)

• 상세 레퍼런스 섹션(iOS 26 프레임워크 표 아래)에 "백엔드(서버)" 표 추가
  • 대상: Cygnus 서버 레포 — https://github.com/UMC-PRODUCT/cygnus-server/tree/main
  • 참고 시점: API 엔드포인트·요청/응답 스펙 확인, 서버 구현/배포 상태 점검, iOS DTO와 실제 응답이 어긋날 때 원인 추적
• 조회 수단 명시 — gh CLI(gh api repos/UMC-PRODUCT/cygnus-server/contents/..., gh search code --repo ...) 또는 WebFetch
• 읽기 전용 원칙 — 서버 레포에 커밋·PR·이슈 생성 금지(메인테이너가 명시적으로 지시한 경우 제외)
• 스펙 추측 금지 — 필드명·타입·nullable 여부는 서버 컨트롤러/DTO 실제 코드로 확인한 뒤 iOS Response DTO에 반영(절대 규칙 💄 [Design] 디자인 시스템 기반 토큰 및 스타일 구현 #2·#3과 연계)

2. PR 제목 컨벤션 명문화 (CLAUDE.md · docs/claude/git-workflow.md)

• 기존 문서에는 "PR 제목 끝에 (#이슈번호)"만 있고 제목 형식 자체가 정의돼 있지 않아 이슈 제목 형식(📄 Docs: …)과 혼동되던 문제를 정정
• docs/claude/git-workflow.md에 "PR 제목 형식" 섹션 신설
  • 형식: {이모지} [Type] {작업 내용} (#이슈번호) — 분류는 반드시 [대괄호]
  • ✅/❌ 예시로 안티패턴 명시: 📄 Docs: …(이슈 형식 오용) · 📄 [Docs]: …(대괄호 뒤 콜론) · [Feature](→ [Feat]) · 이슈번호 누락
  • 이슈 제목 vs PR 제목 형식 대조 블록 추가 (이슈 = Type: , PR = [Type] … (#번호))
  • PR [Type] ↔ 이모지 ↔ 브랜치 ↔ 이슈 제목 접두사 ↔ 라벨 통합 매핑표 추가 (레포 실제 PR 100건 사용 빈도 기준: Docs=📄, Chore=🔧, Feat=✨ 등)
• CLAUDE.md 절대 규칙 #10에 PR 제목 형식·안티패턴을 한 줄로 요약하고 상세 문서를 링크

📋 추후 진행 상황

• API 연동 작업 시 실제로 서버 레포를 참조해 보고, 자주 쓰는 경로(컨트롤러/DTO 디렉터리)가 굳어지면 docs/claude/network-router.md에도 링크 보강
• 서버 스웨거/스펙 문서가 별도로 공개되면 같은 표에 행 추가
• 커밋 메시지 형식도 문서(type: 내용)와 실제 이력(✨ [Feat] …)이 어긋나 있어, 팀 합의 후 별도 이슈로 정리 필요

📌 리뷰 포인트

• CLAUDE.md:117-125 - 추가된 "백엔드(서버)" 표와 하위 규칙 3줄. 읽기 전용 원칙과 스펙 추측 금지 문구가 팀 운영 방식과 맞는지 확인 부탁드립니다.
• docs/claude/git-workflow.md:46-71 - PR 제목 형식 섹션의 매핑표. 특히 Chore 이모지를 🔧로 확정(레포 사용 빈도 🔧 7 / 🛠️ 3 / 🍀 2)한 부분과, 이슈 템플릿 접두사가 🍀 ETC: 인 점의 불일치를 그대로 표에 남겨둔 게 괜찮은지 봐주세요.
• 서버 레포 링크가 main 브랜치 기준인데, 참조 기준 브랜치를 develop 등으로 바꿔야 하는지 확인 필요합니다.

✅ Checklist

PR이 다음 요구 사항을 충족하는지 확인해주세요!!!

• 커밋 메시지 컨벤션에 맞게 작성했습니다
  • 해당 링크 : 깃 모지 컨벤션
• 유지-보수를 위해 주석처리를 잘 작성하였는가?
  • 해당 링크 : Xcode 주석 정리