solid-connection · manNomi · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · coderabbitai
@@ -1,4 +1,9 @@
-# Skill: Biome 단일 품질체크 표준화 (Web/Admin/CI)
+---
+name: biome-unification-ci
+description: Standardize Biome-based lint/typecheck commands across web, admin, university-web, Husky hooks, and CI so local and GitHub Actions runs stay identical. Use when adding a new package's quality scripts, debugging a CI-vs-local lint mismatch, or asked to unify quality checks.
+---
+
+# Biome 단일 품질체크 표준화 (Web/Admin/University-Web/CI)
 
 ## 목적
 
@@ -21,6 +26,13 @@
 - 타입 체크: `pnpm --filter @solid-connect/admin run typecheck`
 - CI 체크: `pnpm --filter @solid-connect/admin run ci:check`
 
+### University Web
+
+- 자동 수정: `pnpm --filter @solid-connect/university-web run lint`
+- 체크 전용: `pnpm --filter @solid-connect/university-web run lint:check`
+- 타입 체크: `pnpm --filter @solid-connect/university-web run typecheck:ci`
+- CI 체크: `pnpm --filter @solid-connect/university-web run ci:check`
+
 ### Root (Turbo)
 
 - 전체 CI 체크: `pnpm ci:check`
@@ -49,8 +61,10 @@
 
 1. `pnpm --filter @solid-connect/web run ci:check`
 2. `pnpm --filter @solid-connect/admin run ci:check`
-3. `pnpm ci:check`
-4. `pnpm build`
+3. `pnpm --filter @solid-connect/university-web run ci:check`
+4. `pnpm typecheck` (루트 Turbo 전체 타입 체크)
+5. `pnpm ci:check`
+6. `pnpm build`
 
 ## 실패 대응
 

@@ -1,4 +1,9 @@
-# Skill: Bruno API 동기화 + Codegen + React Query 연계
+---
+name: bruno-codegen-react-query
+description: Sync Bruno API specs, regenerate the shared TypeScript API client, and wire React Query on top. Use when the user asks to "브루노 다시 동기화해줘", "codegen 돌려서 타입 최신화해줘", "생성 코드 기준으로 react-query 붙여줘", or reports a response type mismatch between server and generated types.
+---
+
+# Bruno API 동기화 + Codegen + React Query 연계
 
 ## 목적
 
@@ -11,17 +16,10 @@
 - 응답 타입 불일치 점검
 - 앱별 React Query 래퍼/훅 연결
 
-## 실행 트리거 예시
-
-- "브루노 다시 동기화해줘"
-- "codegen 돌려서 타입 최신화해줘"
-- "생성 코드 기준으로 react-query 붙여줘"
-- "응답 타입이 서버랑 다른데 원인 확인해줘"
-
 ## 핵심 원칙
 
 1. Bruno를 단일 소스로 본다.
-2. 생성 파일을 직접 수정하지 않는다.
+2. 생성 파일(`packages/api-schema/src/apis/*`)을 직접 수정하지 않는다.
 3. 잘못된 생성 결과는 생성기(`packages/bruno-api-typescript`)를 수정한다.
 4. `onSuccess`, invalidation, toast, navigation 등은 앱 레이어에서 처리한다.
 
@@ -66,9 +64,6 @@
 
 ## 실패 대응
 
-- remote sync 실패 시:
-  - `BRUNO_REPO_URL`, `BRUNO_REPO_REF`, `BRUNO_COLLECTION_PATH` 점검
-- 생성 실패 시:
-  - 파싱 불가 `.bru`와 docs JSON 형식 확인
-- 타입 불일치 지속 시:
-  - 임시 수동 패치 금지, 생성기 로직 우선 수정
+- remote sync 실패 시: `BRUNO_REPO_URL`, `BRUNO_REPO_REF`, `BRUNO_COLLECTION_PATH` 점검
+- 생성 실패 시: 파싱 불가 `.bru`와 docs JSON 형식 확인
+- 타입 불일치 지속 시: 임시 수동 패치 금지, 생성기 로직 우선 수정
@@ -1,4 +1,9 @@
-# Skill: Commit + Push + PR Subagent
+---
+name: commit-push-pr
+description: One-shot commit, push, and PR creation subagent flow with Korean commit/PR language enforced. Use when the user asks to commit and push and open a PR in a single request (e.g. "커밋하고 푸시해서 PR까지 만들어줘").
+---
+
+# Commit + Push + PR Subagent
 
 ## Goal
 
@@ -15,14 +20,14 @@
 
 1. 작업 브랜치 확인: `git branch --show-current`
 2. 변경사항 확인: `git status --short --branch`, `git diff --stat`
-3. 커밋 스타일 준수: 저장소 규칙(`<type>: <subject>`) 사용
+3. 커밋 스타일 준수: 저장소 규칙(이모지 + `<type>: <subject>`, `AGENTS.md`의 Commit Message Convention 참고)
 4. 커밋 메시지와 PR 제목/본문은 한국어로 작성
 
 ## Execution Steps
 
 ```bash
 git add <files>
-git commit -m "docs: 커밋/푸시/PR 서브에이전트 스킬 문서 추가"
+git commit -m "📝 docs: 커밋/푸시/PR 서브에이전트 스킬 문서 추가"
 git push -u origin <branch>
 gh pr create --base <base> --head <branch> --title "<title>" --body "$(cat <<'EOF'
 ## 요약

@@ -1,4 +1,9 @@
-# Skill: `fix/issues-405-409` 리베이스 플레이북
+---
+name: rebase-issues-405-409
+description: Rebase playbook for the fix/issues-405-409 branch onto origin/main, including known conflict resolution rules for UniverSityCard and pnpm-lock.yaml. Use only when working on the fix/issues-405-409 branch.
+---
+
+# `fix/issues-405-409` 리베이스 플레이북
 
 ## 목적
 
@@ -40,11 +45,13 @@ git rebase --continue
 
 ```bash
 git status --short --branch
+git merge-base --is-ancestor origin/main HEAD && echo "origin/main is ancestor: OK"
 git rev-list --left-right --count origin/main...HEAD
 git log --oneline --max-count=12
 ```
 
-- 기대값: `origin/main...HEAD` 결과가 `0 7` (기준 브랜치 대비 feature 커밋 7개만 남음)
+- 워킹 트리가 clean하고, `origin/main`이 현재 브랜치의 조상(ancestor)인지로 리베이스 성공 여부를 판단한다.
+- `git rev-list --left-right --count origin/main...HEAD`의 좌측 값(뒤처진 커밋 수)은 반드시 `0`이어야 한다. 우측 값(feature 커밋 수)은 `origin/main`이 전진했거나 브랜치에 커밋이 추가/제거됐으면 달라질 수 있으므로 고정값(예: `7`)으로 기대하지 말고 `git log`로 실제 커밋 목록을 참고값으로만 확인한다.
 - 원격 feature 브랜치와 히스토리가 달라지므로 push 시 `--force-with-lease`를 사용한다.
 
 ```bash

@@ -0,0 +1,55 @@
+---
+name: univ-extends-bruno-sync
+description: Rebase the feat/univ-extends branch and keep the generated Bruno TypeScript API client in sync. Use only when working on the feat/univ-extends branch or asked to rebase it against develop/main.
+---
+
+# feat/univ-extends 리베이스 + Bruno 명세 동기화
+
+## 목적
+
+- `feat/univ-extends`를 최신 기준 브랜치에 리베이스한다.
+- Bruno 명세 변경이 생겨도 TypeScript API 코드를 재생성할 수 있는 구조를 유지한다.
+
+## 리베이스 절차
+
+1. 기준 브랜치 fetch
+   - `git fetch --all --prune`
+2. 기준 브랜치 확인
+   - `git ls-remote --heads origin develop`으로 원격 `develop` 존재 여부를 먼저 확인한다.
+   - 존재하면: 로컬 `develop`을 최신 `origin/develop`으로 맞춘 뒤(`git checkout develop && git reset --hard origin/develop`, 로컬에 없으면 `git checkout -b develop origin/develop`) 그 브랜치로 리베이스한다.
+   - 존재하지 않으면(이 저장소는 기본적으로 `develop`이 없다): `origin/main`을 기준으로 직접 리베이스한다. 로컬 `develop`을 만들어서 우회하지 않는다.
+3. 리베이스 실행
+   - `origin/develop`이 있는 경우: `git rebase develop`
+   - 없는 경우: `git rebase origin/main`
-   - `git ls-remote --heads origin develop`으로 원격 `develop` 존재 여부를 먼저 확인한다.
-   - 존재하면: 로컬 `develop`을 최신 `origin/develop`으로 맞춘 뒤(`git checkout develop && git reset --hard origin/develop`, 로컬에 없으면 `git checkout -b develop origin/develop`) 그 브랜치로 리베이스한다.
-   - 존재하지 않으면(이 저장소는 기본적으로 `develop`이 없다): `origin/main`을 기준으로 직접 리베이스한다. 로컬 `develop`을 만들어서 우회하지 않는다.
-3. 리베이스 실행
-   - `origin/develop`이 있는 경우: `git rebase develop`
-   - 없는 경우: `git rebase origin/main`
+   - `git ls-remote --heads origin develop`으로 원격 `develop` 존재 여부를 먼저 확인한다.
+   - 존재하면: 로컬 `develop`을 최신 `origin/develop`으로 맞춘 뒤(`git checkout develop && git reset --hard origin/develop`, 로컬에 없으면 `git checkout -b develop origin/develop`) 동기화가 끝나면 `git checkout feat/univ-extends`로 작업 브랜치로 돌아간다.
+   - 존재하지 않으면(이 저장소는 기본적으로 `develop`이 없다): `origin/main`을 기준으로 직접 리베이스한다. 로컬 `develop`을 만들어서 우회하지 않는다.
+3. 리베이스 실행
+   - `origin/develop`이 있는 경우: `git rebase develop`
+   - 없는 경우: `git rebase origin/main`
-   - `git ls-remote --heads origin develop`으로 원격 `develop` 존재 여부를 먼저 확인한다.
-   - 존재하면: 로컬 `develop`을 최신 `origin/develop`으로 맞춘 뒤(`git checkout develop && git reset --hard origin/develop`, 로컬에 없으면 `git checkout -b develop origin/develop`) 그 브랜치로 리베이스한다.
-   - 존재하지 않으면(이 저장소는 기본적으로 `develop`이 없다): `origin/main`을 기준으로 직접 리베이스한다. 로컬 `develop`을 만들어서 우회하지 않는다.
-3. 리베이스 실행
-   - `origin/develop`이 있는 경우: `git rebase develop`
-   - 없는 경우: `git rebase origin/main`
+   - `git ls-remote --heads origin develop`으로 원격 `develop` 존재 여부를 먼저 확인한다.
+   - 존재하면: 로컬 `develop`을 최신 `origin/develop`으로 맞춘 뒤(`git checkout develop && git reset --hard origin/develop`, 로컬에 없으면 `git checkout -b develop origin/develop`) 동기화가 끝나면 `git checkout feat/univ-extends`로 작업 브랜치로 돌아간다.
+   - 존재하지 않으면(이 저장소는 기본적으로 `develop`이 없다): `origin/main`을 기준으로 직접 리베이스한다. 로컬 `develop`을 만들어서 우회하지 않는다.
+3. 리베이스 실행
+   - `origin/develop`이 있는 경우: `git rebase develop`
+   - 없는 경우: `git rebase origin/main`
+4. 충돌 처리 원칙
+   - 자동 생성 API 충돌은 의미 없는 대량 충돌이면 해당 커밋 `git rebase --skip`
+   - 기능 코드 충돌은 수동 병합 후 `git add` + `git rebase --continue`
+
+## Bruno 동기화 절차
+
+1. 기본 실행
+   - `pnpm run sync:bruno`
+2. 원격 명세 강제 동기화 (기본과 동일 동작 명시)
+   - `pnpm --filter @solid-connect/api-schema run sync:bruno:remote`
+3. 모드 제어
+   - `BRUNO_SOURCE_MODE=local|remote|auto` (기본: `remote`)
+
+## 환경 변수 규칙
+
+- `BRUNO_COLLECTION_DIR`: 로컬 명세 폴더를 직접 지정
+- `BRUNO_REPO_URL`: 원격 Bruno 저장소 URL
+- `BRUNO_REPO_REF`: 원격 브랜치/태그 (기본 `main`)
+- `BRUNO_COLLECTION_PATH`: 저장소 내부 명세 폴더 (기본 `Solid Connection`)
+- 권장 파일: `packages/api-schema/.env`
+
+## 검증 체크리스트
+
+1. `pnpm --filter @solid-connect/api-schema run sync:bruno`
+2. `pnpm typecheck`
+3. `pnpm build`
+
+## 실패 대응
+
+- `BRUNO_COLLECTION_DIR`이 설정되어 있으면 `BRUNO_SOURCE_MODE` 값과 무관하게 그 로컬 경로가 항상 우선 사용된다(`packages/api-schema/scripts/sync-bruno.mjs`의 `resolveCollectionDir()` 참고). 이 경우 `BRUNO_REPO_URL`은 필요 없다.
+- `BRUNO_COLLECTION_DIR`이 없고, `BRUNO_SOURCE_MODE=remote`이거나(`auto` 모드에서 로컬 기본 경로도 없어) 원격 경로를 resolve해야 하는 상황에서 `BRUNO_REPO_URL`이 없으면 즉시 실패한다.
+- 원격 clone 성공 후 `BRUNO_COLLECTION_PATH` 경로가 없으면 즉시 실패한다.
@@ -0,0 +1,67 @@
+---
+name: university-web-rewrite-caution
+description: Safety checklist before touching apps/university-web — it is a separately deployed Next.js Multi-Zone SSG app that is CURRENTLY MID-REWRITE (desktop "skyscanner-style" layout redesign) with parallel work happening in git worktrees. Use whenever a task touches apps/university-web, the /university/* routes, packages/ui shared layout primitives, or anything under docs/screenshots/*-poc.
+---
+
+# University Web: 리라이트 중 주의사항
+
+## 왜 이 스킬이 필요한가
+
+`apps/university-web`은 단순한 하위 라우트가 아니라 **별도로 배포되는 독립 Next.js 앱**이고, 지금 **데스크톱 레이아웃 전면 리라이트("skyscanner-layout" 스타일)가 진행 중**이다. 다른 앱(`apps/web`, `apps/admin`)과 같은 감각으로 수정하면 다음이 쉽게 깨진다:
+
+- 이미 진행 중인 리라이트 작업과 충돌하는 중복/역행 수정
+- SSG 빌드 실패(빈 카탈로그로 조용히 넘어가지 않고 빌드 자체가 실패하도록 설계됨)
+- `apps/web` ↔ `apps/university-web` 간 라우트 소유권 경계 위반
+- `apps/web`과 `apps/university-web`에 **동일 내용으로 중복 보관된** `AUTHENTICATION.md`/`COMPONENTS.md` 드리프트
+
+## 작업 전 체크리스트 (순서대로)
+
+1. **진행 중인 리라이트와 충돌하는지 먼저 확인한다.**
+   ```bash
+   git worktree list
+   git branch -a --list "*skyscanner*" "*university*"
+   ```
+   university 관련 worktree/브랜치가 이미 떠 있다면(예: `feat/skyscanner-layout-poc`, `fix/university-*`), 같은 화면을 건드리기 전에 해당 브랜치의 최신 diff를 확인해 중복 작업을 피한다.
+
+2. **`docs/screenshots/`에 이미 있는 POC 자료를 확인한다.**
+   - `docs/screenshots/skyscanner-layout-poc/`, `docs/screenshots/university-skyscanner-layout-poc/`에 데스크톱(1440x1000)/모바일(390x844) contact sheet가 있다.
+   - 이미 리뷰된 레이아웃 결정(예: 대학 목록 가상화, 모바일 하단 네비 유지, 데스크톱 nav 숨김)을 임의로 되돌리지 않는다.
+
+3. **라우트 소유권을 `docs/university-multizone-deployment.md` 기준으로 지킨다.**
+   - `/university`, `/university/search`, `/university/:homeUniversity`, `/university/:homeUniversity/:id`, `/university-static/*` → `apps/university-web` 소유 (SSG)
+   - `/university/score/*`, `/university/application/*` → `apps/web` 소유 (인증/수정 플로우, 여기는 그대로 둔다)
+   - `/university/list/:homeUniversity`는 legacy URL이며 child route를 새로 만들지 않는다. redirect만 유지.
+   - 카탈로그 성격의 새 university 라우트를 실수로 `apps/web`에 추가하지 않는다.
+
+4. **공유 문서 동기화: `AUTHENTICATION.md` / `COMPONENTS.md`**
+   - `apps/web/AUTHENTICATION.md` ≡ `apps/university-web/AUTHENTICATION.md`
+   - `apps/web/COMPONENTS.md` ≡ `apps/university-web/COMPONENTS.md`
+   - 둘은 현재 완전히 동일한 내용이다. 한쪽만 고치면 drift가 생기므로, 컨벤션을 바꿀 때는 **두 파일을 함께 수정**한다(diff로 확인: `diff apps/web/COMPONENTS.md apps/university-web/COMPONENTS.md`).
+
+5. **레이아웃 공통화는 `packages/ui`로.**
+   - 리라이트 과정에서 공통 레이아웃 프리미티브가 `packages/ui`로 추출되고 있다 (예: `packages/ui/src/mobile-hero-detail-shell.tsx`).
+   - university 전용 화면이라도 web/admin과 겹치는 레이아웃 패턴이면 `apps/university-web` 내부에 새로 만들지 말고 `packages/ui`에 있는지 먼저 확인하고, 없으면 그쪽에 추가하는 것을 우선 고려한다.
+
+6. **SSG 데이터 페칭은 실패를 삼키지 않는다.**
+   - university-web의 카탈로그 SSG는 "데이터 fetch 실패 시 빈 카탈로그로 조용히 빌드 성공" 대신 **빌드 자체가 실패**하도록 되어 있다. 이 특성을 유지한다 (에러를 try/catch로 삼켜 빈 배열 fallback을 만들지 않는다).
+   - 데이터 갱신은 수동 DB 갱신 후 university zone 재배포로 처리한다(`/university/revalidate` 참고).
+
+7. **환경변수 의존성 확인.**
+   - `apps/web`은 빌드 시 `UNIVERSITY_WEB_DOMAIN`이 없으면 실패하도록 되어 있다(`/university` rewrite 대상이 없으면 catalog가 404가 되기 때문). 이 가드를 우회/삭제하지 않는다.
+
+## 검증
+
+```bash
+pnpm --filter @solid-connect/university-web run lint:check
+pnpm --filter @solid-connect/university-web run typecheck:ci
+pnpm --filter @solid-connect/university-web run build
+pnpm --filter @solid-connect/web run build   # UNIVERSITY_WEB_DOMAIN 필요
+```
+
+레이아웃을 변경했다면, 기존 POC와 같은 방식으로 데스크톱 1440x1000 / 모바일 390x844 스크린샷을 `docs/screenshots/<작업명>/`에 남기고 PR에 첨부하는 것을 권장한다 (기존 사례: `docs/screenshots/university-skyscanner-layout-poc/README.md`).
+
+## 참고 문서
+
+- `docs/university-multizone-deployment.md` — 라우트 소유권, Vercel 프로젝트 분리, 배포 절차
+- `docs/screenshots/university-skyscanner-layout-poc/` — 진행 중인 리라이트의 최신 시각 QA 기준
+- `.claude/skills/bruno-codegen-react-query/SKILL.md` — university-web도 같은 Bruno codegen을 공유하므로 API 변경 시 함께 참고