(#9) 프런트엔드 검증 계약과 엔트리포인트를 정리

- typecheck script와 verification contract 문서 추가
- AGENTS.md 추가 및 README overview-only 정리
- CI baseline을 lint/typecheck/build 순서로 맞춤

Author: alexization

.github/workflows/ci.yml

@@ -10,7 +10,7 @@
 #   - develop, main 브랜치 push 시: 코드 품질 검사
 #
 # 파이프라인 흐름:
-#   Checkout → Setup Node.js → Install → Lint → Build
+#   Checkout → Setup Node.js → Install → Lint → Typecheck → Build
 #
 # =============================================================================
 
@@ -65,12 +65,38 @@ jobs:
         run: npm run lint
 
   # =========================================
-  # Job 2: 빌드 검사
+  # Job 2: 타입 검사
+  # =========================================
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    needs: lint  # lint 성공 후 실행
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # TypeScript 타입 검사
+      # - noEmit 기준으로 타입 계약만 확인
+      - name: Run typecheck
+        run: npm run typecheck
+
+  # =========================================
+  # Job 3: 빌드 검사
   # =========================================
   build:
     name: Build
     runs-on: ubuntu-latest
-    needs: lint  # lint 성공 후 실행
+    needs: typecheck  # lint + typecheck 성공 후 실행
 
     steps:
       - name: Checkout code
@@ -86,7 +112,7 @@ jobs:
         run: npm ci
 
       # Next.js 빌드
-      # - 빌드 성공 = TypeScript 타입 오류 없음 + 코드 문법 정상
+      # - 빌드 성공 = production bundle + route tree + required public env contract 정상
       # - 환경변수: 빌드 시점에 필요 (NEXT_PUBLIC_* 변수는 빌드 시 인라인됨)
       - name: Build Next.js
         run: npm run build

AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md
+
+`git-ranker-client`는 Git Ranker의 Next.js 16 프런트엔드다. workflow repo는 orchestration만 소유하고, 프런트엔드 구현 판단의 canonical source는 이 저장소 안에 둔다.
+
+## Start Order
+
+1. [README.md](README.md)에서 프로젝트 overview만 확인한다.
+2. [docs/verification-contract.md](docs/verification-contract.md), [package.json](package.json), [.env.example](.env.example)에서 verification command와 required public env를 확인한다.
+3. [.github/workflows/ci.yml](.github/workflows/ci.yml), [.github/workflows/deploy.yml](.github/workflows/deploy.yml)에서 retained CI/deploy gate를 확인한다.
+4. [next.config.ts](next.config.ts), [tsconfig.json](tsconfig.json), [eslint.config.mjs](eslint.config.mjs), [Dockerfile](Dockerfile), [docker-compose.yml](docker-compose.yml)에서 build/runtime config surface를 확인한다.
+5. [src/app](src/app), [src/features](src/features), [src/shared](src/shared), [src/proxy.ts](src/proxy.ts)에서 route, feature, shared runtime ownership을 따라간다.
+
+## Source Of Truth
+
+- [README.md](README.md): 프로젝트 overview-only surface
+- [docs/verification-contract.md](docs/verification-contract.md): lint/typecheck/build contract와 결과 해석 기준
+- [package.json](package.json): npm command surface
+- [.env.example](.env.example): required public env baseline
+- [.github/workflows/ci.yml](.github/workflows/ci.yml), [.github/workflows/deploy.yml](.github/workflows/deploy.yml): retained CI/deploy gate
+- [next.config.ts](next.config.ts), [tsconfig.json](tsconfig.json), [eslint.config.mjs](eslint.config.mjs): build/static analysis config
+- [src/app](src/app), [src/features](src/features), [src/shared](src/shared), [src/proxy.ts](src/proxy.ts): app behavior canonical source
+
+## Operational Rules
+
+- repo-local docs, config, code가 workflow 문서보다 우선한다.
+- root `README.md`는 overview만 맡고, concrete bootstrap과 execution guidance는 `AGENTS.md`와 named entry docs가 소유한다.
+- verification baseline은 `npm run lint`, `npm run typecheck`, `npm run build`다.
+- `.github/workflows/ci.yml`는 같은 baseline order를 그대로 실행해야 한다.
+- `npm run build`와 runtime bootstrap은 absolute URL로 설정된 `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_API_URL`를 요구한다.
+- local Next.js 명령은 `.env.local`, Docker Compose는 `.env`를 사용하며 시작값은 `.env.example`에서 가져온다.
+- repo-local `.codex/skills/`는 현재 없으므로 fallback first source는 `AGENTS.md`와 nearest docs/config/code surface다.
+- verification contract나 deploy gate가 바뀌면 `docs/verification-contract.md`, `package.json`, workflow, `AGENTS.md`를 함께 갱신한다.

README.md

@@ -1,64 +1,5 @@
 # git-ranker-client
 
-`git-ranker-client`는 Git Ranker의 Next.js 16 프런트엔드다. 랭킹 조회, 사용자 상세, 로그인 진입, SEO 메타데이터와 배지 링크를 제공한다.
+`git-ranker-client`는 Git Ranker의 Next.js 16 프런트엔드다. 랭킹 조회, 사용자 상세, 로그인 진입, SEO 메타데이터, 배지 링크 생성을 담당한다.
 
-## Requirements
-
-- Node.js 20+
-- npm
-- `NEXT_PUBLIC_BASE_URL`
-- `NEXT_PUBLIC_API_URL`
-
-`NEXT_PUBLIC_BASE_URL`와 `NEXT_PUBLIC_API_URL`는 build와 runtime 모두에서 필수다. 값이 없으면 `npm run build`와 런타임 초기화가 즉시 실패한다.
-
-## Environment
-
-로컬 Next.js 실행은 `.env.local`, Docker Compose 실행은 `.env`를 사용하면 된다. 시작점으로는 [.env.example](.env.example)을 복사한다.
-
-로컬 개발 예시:
-
-```env
-NEXT_PUBLIC_BASE_URL=http://localhost:3000
-NEXT_PUBLIC_API_URL=http://localhost:8080
-```
-
-프로덕션 예시:
-
-```env
-NEXT_PUBLIC_BASE_URL=https://www.git-ranker.com
-NEXT_PUBLIC_API_URL=https://www.git-ranker.com
-```
-
-선택 env:
-
-- `NEXT_PUBLIC_ANALYTICS_ENDPOINT`
-- `NEXT_PUBLIC_SENTRY_DSN`
-- `SENTRY_DSN`
-
-선택 env가 없어도 핵심 기능은 동작한다. 없으면 analytics/web vitals 전송이나 Sentry 수집만 비활성화된다.
-
-## Commands
-
-```bash
-npm install
-npm run dev
-npm run lint
-npx tsc --noEmit
-npm run build
-```
-
-## Docker Compose
-
-```bash
-cp .env.example .env
-docker compose up --build
-```
-
-`docker-compose.yml`과 `Dockerfile`은 `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_API_URL`가 비어 있으면 즉시 실패한다.
-
-## Build And Runtime Notes
-
-- `JetBrains Mono`는 공식 JetBrains Mono release v2.304에서 가져온 로컬 자산을 사용한다.
-- 폰트 라이선스는 [src/fonts/JetBrainsMono-OFL.txt](src/fonts/JetBrainsMono-OFL.txt)에 보관한다.
-- locale routing과 보안 헤더는 [src/proxy.ts](src/proxy.ts)에서 처리한다.
-- public URL 정책은 [src/shared/lib/public-env.ts](src/shared/lib/public-env.ts)에서 단일 기준으로 관리한다.
+repo-local entrypoint는 [AGENTS.md](AGENTS.md), verification contract는 [docs/verification-contract.md](docs/verification-contract.md)에 둔다.

docs/verification-contract.md

@@ -0,0 +1,45 @@
+# Frontend Verification Contract
+
+`git-ranker-client`의 verification contract는 repo-local command surface가 소유한다. workflow repo는 상위 `frontend-change` semantics만 가리키고, concrete command와 environment precondition은 이 문서와 repo config가 canonical source다.
+
+## Required Environment
+
+- Node.js `20+`
+- `npm`
+- dependency install 완료 상태 (`npm install` 또는 `npm ci`)
+- absolute URL로 설정된 `NEXT_PUBLIC_BASE_URL`
+- absolute URL로 설정된 `NEXT_PUBLIC_API_URL`
+
+local Next.js 명령은 `.env.local`, Docker Compose는 `.env`를 읽는다. 시작점은 [.env.example](../.env.example)이며, `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_API_URL`가 비어 있거나 absolute URL이 아니면 build/runtime verification은 실패해야 한다.
+
+## Commands
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+```
+
+- `npm run lint`
+  - `eslint.config.mjs` 기준으로 Next.js / TypeScript lint surface를 검사한다.
+- `npm run typecheck`
+  - `tsconfig.json` 기준으로 `tsc --noEmit`를 실행한다.
+  - `strict: true`, `noEmit: true`, path alias resolution이 깨지면 실패해야 한다.
+- `npm run build`
+  - `next build`를 실행한다.
+  - production bundle, route tree, required public env contract를 함께 검증한다.
+
+## Result Interpretation
+
+- lint 실패:
+  - ESLint rule 위반이나 React/Next static analysis regression이 생긴 상태다.
+- typecheck 실패:
+  - TypeScript contract, import path, generated type surface 중 하나가 깨진 상태다.
+- build 실패:
+  - Next.js production build, required public env, 또는 build-time code path 중 하나가 깨진 상태다.
+
+## Current Notes
+
+- `.github/workflows/ci.yml`는 `npm run lint`, `npm run typecheck`, `npm run build`를 같은 baseline order로 실행한다.
+- CI build 단계는 placeholder absolute URL env를 주입해 required public env contract를 함께 검증한다.
+- current repo-local baseline 기준 추가 GC follow-up risk는 없다.

package.json

@@ -6,7 +6,8 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint"
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@radix-ui/react-alert-dialog": "^1.1.15",