From 4dd3f320eaafb4796c0757656d755c34c95360a6 Mon Sep 17 00:00:00 2001 From: manNomi Date: Tue, 28 Jul 2026 09:19:00 +0900 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20=EC=8A=A4=ED=82=AC=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EB=A5=BC=20.claude/skills=EB=A1=9C=20?= =?UTF-8?q?=EC=8A=B9=EA=B2=A9=ED=95=98=EA=B3=A0=20university-web=20?= =?UTF-8?q?=EB=A6=AC=EB=9D=BC=EC=9D=B4=ED=8A=B8=20=EC=A3=BC=EC=9D=98?= =?UTF-8?q?=EC=82=AC=ED=95=AD=20=EC=8A=A4=ED=82=AC=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/skills/*.md를 실행 가능한 .claude/skills/*/SKILL.md 형식(frontmatter 포함)으로 이관 - apps/university-web가 별도 배포되는 Multi-Zone SSG 앱이며 현재 레이아웃 리라이트가 진행 중임을 명시하는 university-web-rewrite-caution 스킬 신설 - CLAUDE.md에 누락되어 있던 프로젝트 개요 추가 (기존엔 커밋 규칙만 존재) - AGENTS.md/llms.txt에서 새 스킬 경로와 university-web 주의사항을 참조하도록 갱신 --- .../skills/biome-unification-ci/SKILL.md | 19 +++++- .../skills/bruno-codegen-react-query/SKILL.md | 25 +++---- .../skills/commit-push-pr/SKILL.md | 9 ++- .../skills/rebase-issues-405-409/SKILL.md | 7 +- .../skills/univ-extends-bruno-sync/SKILL.md | 7 +- .../university-web-rewrite-caution/SKILL.md | 67 +++++++++++++++++++ AGENTS.md | 16 ++++- CLAUDE.md | 10 ++- llms.txt | 1 + 9 files changed, 135 insertions(+), 26 deletions(-) rename docs/skills/biome-unification-ci-skill.md => .claude/skills/biome-unification-ci/SKILL.md (71%) rename docs/skills/ai-bruno-codegen-react-query-skill.md => .claude/skills/bruno-codegen-react-query/SKILL.md (72%) rename docs/skills/commit-push-pr-subagent.md => .claude/skills/commit-push-pr/SKILL.md (78%) rename docs/skills/rebase-fix-issues-405-409.md => .claude/skills/rebase-issues-405-409/SKILL.md (83%) rename docs/skills/univ-extends-bruno-sync-skill.md => .claude/skills/univ-extends-bruno-sync/SKILL.md (83%) create mode 100644 .claude/skills/university-web-rewrite-caution/SKILL.md diff --git a/docs/skills/biome-unification-ci-skill.md b/.claude/skills/biome-unification-ci/SKILL.md similarity index 71% rename from docs/skills/biome-unification-ci-skill.md rename to .claude/skills/biome-unification-ci/SKILL.md index f5142109..3509dd08 100644 --- a/docs/skills/biome-unification-ci-skill.md +++ b/.claude/skills/biome-unification-ci/SKILL.md @@ -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,9 @@ 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 ci:check` +5. `pnpm build` ## 실패 대응 diff --git a/docs/skills/ai-bruno-codegen-react-query-skill.md b/.claude/skills/bruno-codegen-react-query/SKILL.md similarity index 72% rename from docs/skills/ai-bruno-codegen-react-query-skill.md rename to .claude/skills/bruno-codegen-react-query/SKILL.md index ef8262cc..2c753f63 100644 --- a/docs/skills/ai-bruno-codegen-react-query-skill.md +++ b/.claude/skills/bruno-codegen-react-query/SKILL.md @@ -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 형식 확인 +- 타입 불일치 지속 시: 임시 수동 패치 금지, 생성기 로직 우선 수정 diff --git a/docs/skills/commit-push-pr-subagent.md b/.claude/skills/commit-push-pr/SKILL.md similarity index 78% rename from docs/skills/commit-push-pr-subagent.md rename to .claude/skills/commit-push-pr/SKILL.md index 4ef92ff9..0af3d5da 100644 --- a/docs/skills/commit-push-pr-subagent.md +++ b/.claude/skills/commit-push-pr/SKILL.md @@ -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,7 +20,7 @@ 1. 작업 브랜치 확인: `git branch --show-current` 2. 변경사항 확인: `git status --short --branch`, `git diff --stat` -3. 커밋 스타일 준수: 저장소 규칙(`: `) 사용 +3. 커밋 스타일 준수: 저장소 규칙(이모지 + `: `, `CLAUDE.md` 참고) 4. 커밋 메시지와 PR 제목/본문은 한국어로 작성 ## Execution Steps diff --git a/docs/skills/rebase-fix-issues-405-409.md b/.claude/skills/rebase-issues-405-409/SKILL.md similarity index 83% rename from docs/skills/rebase-fix-issues-405-409.md rename to .claude/skills/rebase-issues-405-409/SKILL.md index d498f729..04fcb858 100644 --- a/docs/skills/rebase-fix-issues-405-409.md +++ b/.claude/skills/rebase-issues-405-409/SKILL.md @@ -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` 리베이스 플레이북 ## 목적 diff --git a/docs/skills/univ-extends-bruno-sync-skill.md b/.claude/skills/univ-extends-bruno-sync/SKILL.md similarity index 83% rename from docs/skills/univ-extends-bruno-sync-skill.md rename to .claude/skills/univ-extends-bruno-sync/SKILL.md index a84e28e2..013c3d2a 100644 --- a/docs/skills/univ-extends-bruno-sync-skill.md +++ b/.claude/skills/univ-extends-bruno-sync/SKILL.md @@ -1,4 +1,9 @@ -# Skill: feat/univ-extends 리베이스 + Bruno 명세 동기화 +--- +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 명세 동기화 ## 목적 diff --git a/.claude/skills/university-web-rewrite-caution/SKILL.md b/.claude/skills/university-web-rewrite-caution/SKILL.md new file mode 100644 index 00000000..981aa506 --- /dev/null +++ b/.claude/skills/university-web-rewrite-caution/SKILL.md @@ -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 기준 +- `[[bruno-codegen-react-query]]` — university-web도 같은 Bruno codegen을 공유하므로 API 변경 시 함께 참고 diff --git a/AGENTS.md b/AGENTS.md index 2ec944c9..951853a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,8 +19,10 @@ - `apps/web`: user-facing web app (App Router based). - `apps/admin`: admin web app. +- `apps/university-web`: university catalog app, deployed as a separate Next.js Multi-Zone project (SSG). **Currently mid-rewrite** — read the `university-web-rewrite-caution` skill before touching it. - `packages`: shared package workspace. - `docs`: project docs and workflow references. +- `.claude/skills`: task-specific skills (Bruno codegen, Biome CI unification, commit/push/PR flow, university-web caution, branch-specific rebase playbooks). ## Working Rules @@ -46,8 +48,16 @@ ## Architecture References - High-level architecture: `ARCHITECTURE.md`. -- Web app auth/details: `apps/web/AUTHENTICATION.md`. -- Web component guidance: `apps/web/COMPONENTS.md`. +- Web app auth/details: `apps/web/AUTHENTICATION.md` (kept in sync verbatim with `apps/university-web/AUTHENTICATION.md` — edit both). +- Web component guidance: `apps/web/COMPONENTS.md` (kept in sync verbatim with `apps/university-web/COMPONENTS.md` — edit both). +- University multi-zone routing/deploy: `docs/university-multizone-deployment.md`. - Team workflow: `docs/development-workflow.md` and `CLAUDE.md`. - LLM repository context: `llms.txt`. -- Bruno + codegen + React Query skill doc: `docs/skills/ai-bruno-codegen-react-query-skill.md`. + +## Skills + +- `.claude/skills/bruno-codegen-react-query` — Bruno sync, codegen, React Query wiring. +- `.claude/skills/biome-unification-ci` — keep Biome lint/typecheck commands identical across apps, Husky, and CI. +- `.claude/skills/commit-push-pr` — one-shot commit + push + PR creation, Korean-language output. +- `.claude/skills/university-web-rewrite-caution` — **read before any `apps/university-web` change**; the app is a separately deployed SSG Multi-Zone app under active layout rewrite, with route-ownership and duplicated-doc pitfalls. +- `.claude/skills/rebase-issues-405-409`, `.claude/skills/univ-extends-bruno-sync` — branch-specific rebase playbooks, relevant only while those branches are active. diff --git a/CLAUDE.md b/CLAUDE.md index 7206666b..07690d9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,12 @@ -# 커밋 룰 +# solid-connect-web + +## 프로젝트 개요 + +- Solid Connection 교환학생 플랫폼의 pnpm + turbo 모노레포. +- 앱: `apps/web`(사용자 메인, Next.js App Router), `apps/admin`(관리자), `apps/university-web`(대학 정보 카탈로그, 별도 배포되는 Multi-Zone SSG 앱). +- 공유 패키지: `packages/api-schema`(Bruno 기반 생성 API 클라이언트), `packages/bruno-api-typescript`(codegen), `packages/ui`(공통 컴포넌트), `packages/ai-inspector`(운영 중 UI 수정 요청 → PR 자동화). +- `apps/university-web`은 **현재 데스크톱 레이아웃 리라이트가 진행 중**이다. 이 앱을 건드리기 전에 반드시 `[[university-web-rewrite-caution]]` 스킬(`.claude/skills/university-web-rewrite-caution/SKILL.md`)을 먼저 확인한다. +- 더 자세한 아키텍처/컨텍스트는 `AGENTS.md`, `llms.txt`, `ARCHITECTURE.md`를 참고한다. ## 커밋 메시지 작성 규칙 diff --git a/llms.txt b/llms.txt index 594dc361..8fb9f544 100644 --- a/llms.txt +++ b/llms.txt @@ -10,6 +10,7 @@ This repository uses Bruno as the single source of truth for API schema and gene - Main apps: - `apps/web` (Next.js) - `apps/admin` + - `apps/university-web` (Next.js, separately deployed Multi-Zone SSG app for university catalog pages — **currently mid-rewrite**, see the `university-web-rewrite-caution` skill and `docs/university-multizone-deployment.md` before editing) - Shared API schema package: - `packages/api-schema` - Code generator: From 89822786371ce7db9062119a56b711b98ceab5ef Mon Sep 17 00:00:00 2001 From: manNomi Date: Tue, 28 Jul 2026 09:26:00 +0900 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20=EC=A0=80=EC=9E=A5=EC=86=8C?= =?UTF-8?q?=20=EA=B3=B5=ED=86=B5=20=EA=B7=9C=EC=B9=99=EC=9D=84=20AGENTS.md?= =?UTF-8?q?=20=EB=8B=A8=EC=9D=BC=20=EC=86=8C=EC=8A=A4=EB=A1=9C=20=ED=86=B5?= =?UTF-8?q?=ED=95=A9=ED=95=98=EA=B3=A0=20CLAUDE.md=EB=8A=94=20=EC=96=87?= =?UTF-8?q?=EA=B2=8C=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로젝트 개요/커밋 컨벤션/스킬 목록을 AGENTS.md 하나로 모아 Codex가 그대로 읽고 Claude Code는 @AGENTS.md import로 동일 내용을 가져오도록 변경 (중복/드리프트 제거) - CLAUDE.md에 잘못 섞여 있던 메모리 시스템 전용 [[name]] 링크 문법 제거, 일반 파일 경로 참조로 교체 - AGENTS.md Skills 표에 각 스킬의 frontmatter가 Claude Code 전용 메타데이터이며 다른 에이전트는 본문만 읽으면 된다는 안내 추가 --- .../university-web-rewrite-caution/SKILL.md | 2 +- AGENTS.md | 70 ++++++++++++++++--- CLAUDE.md | 65 ++--------------- 3 files changed, 67 insertions(+), 70 deletions(-) diff --git a/.claude/skills/university-web-rewrite-caution/SKILL.md b/.claude/skills/university-web-rewrite-caution/SKILL.md index 981aa506..47c07cdb 100644 --- a/.claude/skills/university-web-rewrite-caution/SKILL.md +++ b/.claude/skills/university-web-rewrite-caution/SKILL.md @@ -64,4 +64,4 @@ pnpm --filter @solid-connect/web run build # UNIVERSITY_WEB_DOMAIN 필요 - `docs/university-multizone-deployment.md` — 라우트 소유권, Vercel 프로젝트 분리, 배포 절차 - `docs/screenshots/university-skyscanner-layout-poc/` — 진행 중인 리라이트의 최신 시각 QA 기준 -- `[[bruno-codegen-react-query]]` — university-web도 같은 Bruno codegen을 공유하므로 API 변경 시 함께 참고 +- `.claude/skills/bruno-codegen-react-query/SKILL.md` — university-web도 같은 Bruno codegen을 공유하므로 API 변경 시 함께 참고 diff --git a/AGENTS.md b/AGENTS.md index 951853a8..b8a18112 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,11 @@ # AGENTS Knowledge Base +이 문서는 Codex, Claude Code 등 이 저장소에서 작업하는 모든 코딩 에이전트가 공통으로 읽는 단일 소스입니다. +저장소 규칙/개요를 바꿀 때는 이 파일만 수정하세요 (`CLAUDE.md`는 이 파일을 그대로 불러오는 얇은 파일이라 별도로 복제하지 않습니다). + ## Mandatory Rule -- PR 제목과 본문은 반드시 한국어로 작성한다. +- 커밋 메시지와 PR 제목/본문은 반드시 한국어로 작성한다. ## Project Overview @@ -35,10 +38,53 @@ - Branch from `main` for new work. - Always start every new task from a fresh branch created from `main`, and name the branch to match the task scope (for example: `fix/university-fallback-image-contrast`). -- Keep commit messages aligned with repository conventions. +- Keep commit messages aligned with the Commit Message Convention below. - Write commit messages and PR title/body in Korean by default. - Run `pnpm typecheck` (and relevant app checks) before push. +## Commit Message Convention + +1. **깃 이모지 사용**: 커밋 타입을 나타내는 이모지를 맨 앞에 사용한다. +2. **원자적 커밋**: 하나의 커밋은 하나의 논리적 변경사항만 포함한다. +3. **간결하게 한 줄로**: 커밋 메시지는 한 줄로 간결하게 작성한다. + +| 이모지 | 코드 | 설명 | +| ------ | ----------------------------- | ------------------------ | +| ✨ | `:sparkles:` | 새로운 기능 추가 | +| 🐛 | `:bug:` | 버그 수정 | +| 🔧 | `:wrench:` | 설정 파일 수정 | +| 📝 | `:memo:` | 문서 추가/수정 | +| 💄 | `:lipstick:` | UI/스타일 파일 추가/수정 | +| ♻️ | `:recycle:` | 코드 리팩토링 | +| 🔥 | `:fire:` | 코드/파일 삭제 | +| 🚀 | `:rocket:` | 배포/성능 개선 | +| ✅ | `:white_check_mark:` | 테스트 추가/수정 | +| 🔒 | `:lock:` | 보안 이슈 수정 | +| ⬆️ | `:arrow_up:` | 의존성 업그레이드 | +| ⬇️ | `:arrow_down:` | 의존성 다운그레이드 | +| 🎨 | `:art:` | 코드 구조/포맷 개선 | +| 🚧 | `:construction:` | 작업 진행 중 | +| 💚 | `:green_heart:` | CI 빌드 수정 | +| 📦 | `:package:` | 패키지 또는 빌드 관련 | +| 🔀 | `:twisted_rightwards_arrows:` | 브랜치 병합 | + +```bash +# 좋은 예 +git commit -m "✨ 사용자 인증 기능 추가" +git commit -m "🐛 로그인 버튼 클릭 오류 수정" +git commit -m "🔥 불필요한 레거시 파일 삭제" +git commit -m "📝 README 설치 가이드 추가" +git commit -m "♻️ API 호출 로직 리팩토링" + +# 나쁜 예 (여러 변경사항을 한 커밋에) +git commit -m "기능 추가 및 버그 수정 및 문서 업데이트" + +# 나쁜 예 (설명이 너무 김) +git commit -m "사용자 인증 기능을 추가했습니다. 이 기능은 JWT를 사용하며..." +``` + +하나의 커밋은 다음 중 하나만 포함해야 한다: 기능 추가 1건, 버그 수정 1건, 리팩토링 1건, 관련된 설정 변경 1건. 여러 작업을 했다면 각각 별도의 커밋으로 분리한다. + ## UI Guardrails (University Fallback) - For university background image fallback UI, keep existing text color unchanged in surrounding UI. @@ -51,13 +97,21 @@ - Web app auth/details: `apps/web/AUTHENTICATION.md` (kept in sync verbatim with `apps/university-web/AUTHENTICATION.md` — edit both). - Web component guidance: `apps/web/COMPONENTS.md` (kept in sync verbatim with `apps/university-web/COMPONENTS.md` — edit both). - University multi-zone routing/deploy: `docs/university-multizone-deployment.md`. -- Team workflow: `docs/development-workflow.md` and `CLAUDE.md`. +- Team workflow: `docs/development-workflow.md`. - LLM repository context: `llms.txt`. ## Skills -- `.claude/skills/bruno-codegen-react-query` — Bruno sync, codegen, React Query wiring. -- `.claude/skills/biome-unification-ci` — keep Biome lint/typecheck commands identical across apps, Husky, and CI. -- `.claude/skills/commit-push-pr` — one-shot commit + push + PR creation, Korean-language output. -- `.claude/skills/university-web-rewrite-caution` — **read before any `apps/university-web` change**; the app is a separately deployed SSG Multi-Zone app under active layout rewrite, with route-ownership and duplicated-doc pitfalls. -- `.claude/skills/rebase-issues-405-409`, `.claude/skills/univ-extends-bruno-sync` — branch-specific rebase playbooks, relevant only while those branches are active. +Task-specific runbooks live under `.claude/skills//SKILL.md`. They are plain Markdown and work with any coding agent — open the file directly by path when its topic matches your task: + +- Claude Code auto-discovers and can invoke these via its Skill tool (the YAML frontmatter at the top of each file is Claude Code's discovery metadata; ignore it if your tool doesn't use it and just read the Markdown body below it). +- Codex and other agents have no auto-discovery for this folder — read the relevant `SKILL.md` path directly (listed below) when the task matches, the same way you would read any other doc referenced from this file. + +| Skill path | Use when | +|---|---| +| `.claude/skills/bruno-codegen-react-query/SKILL.md` | Syncing Bruno API specs, regenerating the shared TypeScript client, or wiring React Query on top of it. | +| `.claude/skills/biome-unification-ci/SKILL.md` | Adding/checking lint, typecheck, or CI scripts so web/admin/university-web/Husky/CI stay identical. | +| `.claude/skills/commit-push-pr/SKILL.md` | Doing commit + push + PR creation in one pass, Korean-language output. | +| `.claude/skills/university-web-rewrite-caution/SKILL.md` | **Any change touching `apps/university-web`.** It's a separately deployed SSG Multi-Zone app under an active layout rewrite, with route-ownership and duplicated-doc pitfalls — read this first. | +| `.claude/skills/rebase-issues-405-409/SKILL.md` | Rebasing the `fix/issues-405-409` branch specifically. | +| `.claude/skills/univ-extends-bruno-sync/SKILL.md` | Rebasing the `feat/univ-extends` branch and re-syncing Bruno specs. | diff --git a/CLAUDE.md b/CLAUDE.md index 07690d9e..bdc49838 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,65 +1,8 @@ # solid-connect-web -## 프로젝트 개요 +@AGENTS.md -- Solid Connection 교환학생 플랫폼의 pnpm + turbo 모노레포. -- 앱: `apps/web`(사용자 메인, Next.js App Router), `apps/admin`(관리자), `apps/university-web`(대학 정보 카탈로그, 별도 배포되는 Multi-Zone SSG 앱). -- 공유 패키지: `packages/api-schema`(Bruno 기반 생성 API 클라이언트), `packages/bruno-api-typescript`(codegen), `packages/ui`(공통 컴포넌트), `packages/ai-inspector`(운영 중 UI 수정 요청 → PR 자동화). -- `apps/university-web`은 **현재 데스크톱 레이아웃 리라이트가 진행 중**이다. 이 앱을 건드리기 전에 반드시 `[[university-web-rewrite-caution]]` 스킬(`.claude/skills/university-web-rewrite-caution/SKILL.md`)을 먼저 확인한다. -- 더 자세한 아키텍처/컨텍스트는 `AGENTS.md`, `llms.txt`, `ARCHITECTURE.md`를 참고한다. +## Claude Code 전용 참고사항 -## 커밋 메시지 작성 규칙 - -1. **깃 이모지 사용**: 커밋 타입을 나타내는 이모지를 맨 앞에 사용 -2. **원자적 커밋**: 하나의 커밋은 하나의 논리적 변경사항만 포함 -3. **간결하게 한 줄로**: 커밋 메시지는 한 줄로 간결하게 작성 - -## 깃 이모지 가이드 - -| 이모지 | 코드 | 설명 | -| ------ | ----------------------------- | ------------------------ | -| ✨ | `:sparkles:` | 새로운 기능 추가 | -| 🐛 | `:bug:` | 버그 수정 | -| 🔧 | `:wrench:` | 설정 파일 수정 | -| 📝 | `:memo:` | 문서 추가/수정 | -| 💄 | `:lipstick:` | UI/스타일 파일 추가/수정 | -| ♻️ | `:recycle:` | 코드 리팩토링 | -| 🔥 | `:fire:` | 코드/파일 삭제 | -| 🚀 | `:rocket:` | 배포/성능 개선 | -| ✅ | `:white_check_mark:` | 테스트 추가/수정 | -| 🔒 | `:lock:` | 보안 이슈 수정 | -| ⬆️ | `:arrow_up:` | 의존성 업그레이드 | -| ⬇️ | `:arrow_down:` | 의존성 다운그레이드 | -| 🎨 | `:art:` | 코드 구조/포맷 개선 | -| 🚧 | `:construction:` | 작업 진행 중 | -| 💚 | `:green_heart:` | CI 빌드 수정 | -| 📦 | `:package:` | 패키지 또는 빌드 관련 | -| 🔀 | `:twisted_rightwards_arrows:` | 브랜치 병합 | - -## 커밋 메시지 예시 - -```bash -# 좋은 예 -git commit -m "✨ 사용자 인증 기능 추가" -git commit -m "🐛 로그인 버튼 클릭 오류 수정" -git commit -m "🔥 불필요한 레거시 파일 삭제" -git commit -m "📝 README 설치 가이드 추가" -git commit -m "♻️ API 호출 로직 리팩토링" - -# 나쁜 예 (여러 변경사항을 한 커밋에) -git commit -m "기능 추가 및 버그 수정 및 문서 업데이트" - -# 나쁜 예 (설명이 너무 김) -git commit -m "사용자 인증 기능을 추가했습니다. 이 기능은 JWT를 사용하며..." -``` - -## 원자적 커밋 가이드 - -하나의 커밋은 다음 중 하나만 포함해야 합니다: - -- 하나의 기능 추가 -- 하나의 버그 수정 -- 하나의 리팩토링 작업 -- 관련된 설정 변경 - -여러 작업을 했다면 각각 별도의 커밋으로 분리합니다. +- 이 저장소는 Codex 등 다른 코딩 에이전트와 공유됩니다. 프로젝트 개요, 커밋 규칙, 스킬 목록 등 공통 규칙은 위에서 불러온 `AGENTS.md`에 단일 소스로 유지하세요. 내용을 바꿀 때는 `AGENTS.md`를 수정하고, 여기 `CLAUDE.md`에는 복제하지 않습니다. +- Claude Code는 `.claude/skills/*/SKILL.md`를 Skill 도구로 자동 탐지·호출할 수 있습니다. Codex 등 자동 탐지 기능이 없는 에이전트는 `AGENTS.md`의 "Skills" 표에 있는 경로를 직접 열어 참고합니다. From d6cc73da9d9eb000ee4b393dd76b9f4fbe01ff86 Mon Sep 17 00:00:00 2001 From: manNomi Date: Tue, 28 Jul 2026 10:23:55 +0900 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20=EC=BD=94=EB=93=9C=EB=9E=98?= =?UTF-8?q?=EB=B9=97=20=EB=A6=AC=EB=B7=B0=20=EB=B0=98=EC=98=81:=20?= =?UTF-8?q?=EC=8A=A4=ED=82=AC=20=EB=AC=B8=EC=84=9C=20=EC=A0=95=ED=99=95?= =?UTF-8?q?=EC=84=B1=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - univ-extends-bruno-sync: sync-bruno.mjs 실제 우선순위대로 BRUNO_COLLECTION_DIR이 BRUNO_SOURCE_MODE보다 우선한다는 점을 반영하고, 존재하지 않는 develop 브랜치를 임의로 만들지 않고 origin/develop 존재 여부를 먼저 확인하도록 리베이스 절차 수정 - rebase-issues-405-409: 완료 검증에서 하드코딩된 커밋 개수(0 7) 기대값을 제거하고 조상 관계 + clean 상태 기준으로 검증하도록 수정 - biome-unification-ci: 검증 체크리스트에 누락되어 있던 루트 pnpm typecheck 추가 - commit-push-pr: 실행 예시 커밋 메시지에 저장소 규칙(이모지 접두사) 반영, CLAUDE.md 대신 AGENTS.md를 참조하도록 수정 --- .claude/skills/biome-unification-ci/SKILL.md | 5 +++-- .claude/skills/commit-push-pr/SKILL.md | 4 ++-- .claude/skills/rebase-issues-405-409/SKILL.md | 4 +++- .claude/skills/univ-extends-bruno-sync/SKILL.md | 10 +++++++--- 4 files changed, 15 insertions(+), 8 deletions(-) diff --git a/.claude/skills/biome-unification-ci/SKILL.md b/.claude/skills/biome-unification-ci/SKILL.md index 3509dd08..728a84ef 100644 --- a/.claude/skills/biome-unification-ci/SKILL.md +++ b/.claude/skills/biome-unification-ci/SKILL.md @@ -62,8 +62,9 @@ description: Standardize Biome-based lint/typecheck commands across web, admin, 1. `pnpm --filter @solid-connect/web run ci:check` 2. `pnpm --filter @solid-connect/admin run ci:check` 3. `pnpm --filter @solid-connect/university-web run ci:check` -4. `pnpm ci:check` -5. `pnpm build` +4. `pnpm typecheck` (루트 Turbo 전체 타입 체크) +5. `pnpm ci:check` +6. `pnpm build` ## 실패 대응 diff --git a/.claude/skills/commit-push-pr/SKILL.md b/.claude/skills/commit-push-pr/SKILL.md index 0af3d5da..95f42132 100644 --- a/.claude/skills/commit-push-pr/SKILL.md +++ b/.claude/skills/commit-push-pr/SKILL.md @@ -20,14 +20,14 @@ description: One-shot commit, push, and PR creation subagent flow with Korean co 1. 작업 브랜치 확인: `git branch --show-current` 2. 변경사항 확인: `git status --short --branch`, `git diff --stat` -3. 커밋 스타일 준수: 저장소 규칙(이모지 + `: `, `CLAUDE.md` 참고) +3. 커밋 스타일 준수: 저장소 규칙(이모지 + `: `, `AGENTS.md`의 Commit Message Convention 참고) 4. 커밋 메시지와 PR 제목/본문은 한국어로 작성 ## Execution Steps ```bash git add -git commit -m "docs: 커밋/푸시/PR 서브에이전트 스킬 문서 추가" +git commit -m "📝 docs: 커밋/푸시/PR 서브에이전트 스킬 문서 추가" git push -u origin gh pr create --base --head --title "" --body "$(cat <<'EOF' ## 요약 diff --git a/.claude/skills/rebase-issues-405-409/SKILL.md b/.claude/skills/rebase-issues-405-409/SKILL.md index 04fcb858..ae657607 100644 --- a/.claude/skills/rebase-issues-405-409/SKILL.md +++ b/.claude/skills/rebase-issues-405-409/SKILL.md @@ -45,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 diff --git a/.claude/skills/univ-extends-bruno-sync/SKILL.md b/.claude/skills/univ-extends-bruno-sync/SKILL.md index 013c3d2a..004c3851 100644 --- a/.claude/skills/univ-extends-bruno-sync/SKILL.md +++ b/.claude/skills/univ-extends-bruno-sync/SKILL.md @@ -15,9 +15,12 @@ description: Rebase the feat/univ-extends branch and keep the generated Bruno Ty 1. 기준 브랜치 fetch - `git fetch --all --prune` 2. 기준 브랜치 확인 - - `develop`이 없으면 로컬 `develop`을 최신 `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. 리베이스 실행 - - `git rebase develop` + - `origin/develop`이 있는 경우: `git rebase develop` + - 없는 경우: `git rebase origin/main` 4. 충돌 처리 원칙 - 자동 생성 API 충돌은 의미 없는 대량 충돌이면 해당 커밋 `git rebase --skip` - 기능 코드 충돌은 수동 병합 후 `git add` + `git rebase --continue` @@ -47,5 +50,6 @@ description: Rebase the feat/univ-extends branch and keep the generated Bruno Ty ## 실패 대응 -- `BRUNO_SOURCE_MODE=remote`에서 `BRUNO_REPO_URL` 미설정이면 즉시 실패한다. +- `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` 경로가 없으면 즉시 실패한다.