[Docs] 프론트엔드 컨벤션 문서 작성

.claude/manifest.md → .claude/README.md

@@ -1,11 +1,11 @@
-# Claude Manifest
+# Claude README
 
 이 문서는 AI 코딩 에이전트가 `kusitms-admin`에서 작업하기 전에 어떤 지침을 읽어야 하는지 정의합니다.
 
 ## 부트 순서
 
 1. `CLAUDE.md` 또는 `AGENTS.md`에서 프로젝트 개요를 읽습니다.
-2. 이 manifest를 읽습니다.
+2. 이 README를 읽습니다.
 3. 코드 변경 작업에서는 Tier 1 규칙을 로드합니다.
 4. Tier 2 규칙과 admin API/domain reference는 작업에 필요한 경우에만 로드합니다.
 
@@ -18,7 +18,7 @@
 | `.claude/rules/workflow.md` | 기본 inspect-edit-verify 작업 흐름 |
 | `.claude/rules/verification.md` | 검증 명령 선택 기준 |
 
-Tier 1은 코드 변경, 리뷰, 리팩터링처럼 실제 작업이 시작될 때만 로드합니다. 단순 질문이나 설명 요청에서는 `CLAUDE.md`와 이 manifest만으로 답합니다.
+Tier 1은 코드 변경, 리뷰, 리팩터링처럼 실제 작업이 시작될 때만 로드합니다. 단순 질문이나 설명 요청에서는 `CLAUDE.md`와 이 README만으로 답합니다.
 
 ## Tier 2: 필요 시 로드
 

.claude/agents/debugger.md

@@ -8,7 +8,7 @@ tools: Read, Glob, Grep, Bash
 
 당신은 React + TypeScript 관리자 애플리케이션의 디버거입니다.
 
-수정 전에 항상 `CLAUDE.md`, `.claude/manifest.md`, 관련 도메인 문서와 최근 변경 diff를 읽습니다. API 또는 인증 문제면 해당 `.claude/references/api/admin-*.md`도 읽습니다.
+수정 전에 항상 `CLAUDE.md`, `.claude/README.md`, 관련 도메인 문서와 최근 변경 diff를 읽습니다. API 또는 인증 문제면 해당 `.claude/references/api/admin-*.md`도 읽습니다.
 
 절차:
 

.claude/agents/reviewer.md

@@ -8,7 +8,7 @@ tools: Read, Glob, Grep, Bash
 
 당신은 React + TypeScript 관리자 애플리케이션의 코드 리뷰어입니다.
 
-리뷰 전에 `CLAUDE.md`, `.claude/manifest.md`, `.claude/rules/architecture.md`, `.claude/rules/code-style.md`, `.claude/rules/component-guide.md`, `.claude/rules/data-fetching.md`와 변경 관련 도메인 문서를 읽습니다.
+리뷰 전에 `CLAUDE.md`, `.claude/README.md`, `.claude/rules/architecture.md`, `.claude/rules/code-style.md`, `.claude/rules/component-guide.md`, `.claude/rules/data-fetching.md`와 변경 관련 도메인 문서를 읽습니다.
 
 절차:
 

.claude/skills/code-review/SKILL.md

@@ -2,7 +2,7 @@
 name: code-review
 description: 변경된 코드를 프로젝트 규칙 기준으로 읽기 전용 리뷰하고, 실제 위험이 있는 finding만 보고합니다.
 user-invocable: true
-argument-hint: [file-or-ref]
+argument-hint: "[file-or-ref]"
 allowed-tools: Bash, Read, Grep, Glob
 ---
 

.claude/skills/create-pr/SKILL.md

@@ -2,7 +2,7 @@
 name: create-pr
 description: 현재 브랜치 변경 내용을 분석해 프로젝트 PR 템플릿 기준으로 제목과 본문 초안을 작성합니다.
 user-invocable: true
-argument-hint: [--append]
+argument-hint: "[--append]"
 allowed-tools: Bash, Read, Grep, Glob
 ---
 
@@ -26,7 +26,7 @@ PR 제목과 본문 초안을 만듭니다. 사용자가 명시하지 않으면
 ## Output Shape
 
 ```markdown
-## #️⃣연관된 이슈
+## #️⃣ 연관된 이슈
 
 - Close #<이슈번호> 또는 #<이슈번호>
 

.claude/skills/create-pr/templates/ai-automation-pr.md

@@ -17,7 +17,7 @@ AI 활용/자동화 변경이 포함된 PR은 아래 관점을 본문에 반영
 
 ## 📝작업 내용
 
-- AI 작업 흐름 정리: `CLAUDE.md`와 `AGENTS.md`를 진입점으로 두고, `.claude/manifest.md`에서 작업 종류별 rules/reference 로딩 기준을 관리하도록 구성
+- AI 작업 흐름 정리: `CLAUDE.md`와 `AGENTS.md`를 진입점으로 두고, `.claude/README.md`에서 작업 종류별 rules/reference 로딩 기준을 관리하도록 구성
 - AI 실행 표면 추가: Claude skill 원본과 Codex proxy skill을 분리해 `/create-pr`, `/scaffold-api`, `/figma-to-component` 같은 반복 작업을 프로젝트 규칙에 맞게 실행하도록 구성
 - 자동 검증 흐름 구성: CI에서 타입/포맷/생성물/lint/test/build 결과를 확인하고, PR 댓글로 reviewer가 확인할 상태를 요약하도록 구성
 - 검증: `pnpm format:check`, `pnpm type-check`, `pnpm lint` 통과

.claude/skills/refactor/SKILL.md

@@ -2,7 +2,7 @@
 name: refactor
 description: 현재 코드에서 동작을 바꾸지 않는 리팩터링 후보를 찾고, 승인된 범위만 수정합니다.
 user-invocable: true
-argument-hint: [file-or-scope]
+argument-hint: "[file-or-scope]"
 allowed-tools: Bash, Read, Grep, Glob, Edit, Write
 ---
 

.claude/skills/scaffold-api/SKILL.md

@@ -14,7 +14,7 @@ Swagger는 admin 기능에 필요한 endpoint만 확인하고, 일반 사용자/
 ## 읽을 문서
 
 1. `CLAUDE.md`
-2. `.claude/manifest.md`
+2. `.claude/README.md`
 3. `.claude/rules/data-fetching.md`
 4. `.claude/rules/code-quality.md`
 5. `.claude/references/api/admin.md`

.coderabbit.yaml

@@ -70,7 +70,7 @@ knowledge_base:
     filePatterns:
       - 'AGENTS.md'
       - 'CLAUDE.md'
-      - '.claude/manifest.md'
+      - '.claude/README.md'
       - '.claude/rules/*.md'
       - '.claude/references/**/*.md'
       - 'docs/**/*.md'

AGENTS.md

@@ -1,16 +1,16 @@
 ## kusitms-admin Codex Instructions
 
-이 파일은 Codex용 최소 라우터입니다. 프로젝트의 메인 지침은 `CLAUDE.md`이고, 상세 로딩 기준은 `.claude/manifest.md`가 관리합니다.
+이 파일은 Codex용 최소 라우터입니다. 프로젝트의 메인 지침은 `CLAUDE.md`이고, 상세 로딩 기준은 `.claude/README.md`가 관리합니다.
 
 ### Required Reading
 
 - `CLAUDE.md`
-- `.claude/manifest.md`
+- `.claude/README.md`
 
 ### Codex Rules
 
 - 사용자가 다르게 요청하지 않으면 한국어로 사고하고 응답합니다.
-- 코드 변경 전에는 `.claude/manifest.md`의 Tier 1/Tier 2 로딩 기준을 따릅니다.
+- 코드 변경 전에는 `.claude/README.md`의 Tier 1/Tier 2 로딩 기준을 따릅니다.
 - `/create-pr`, `/scaffold-api` 같은 skill 요청은 `.codex/skills/{skill}/SKILL.md`를 진입점으로 사용하고, 해당 proxy가 가리키는 `.claude/skills/{skill}/SKILL.md`를 원본 지침으로 따릅니다.
 - 기존 사용자 변경을 보존하고 관련 없는 작업을 되돌리지 않습니다.
 - `pnpm`만 사용하고 `npm`/`yarn`은 사용하지 않습니다.

CLAUDE.md

@@ -1,4 +1,4 @@
-@.claude/manifest.md
+@.claude/README.md
 
 # kusitms-admin
 
@@ -48,6 +48,6 @@ KUSITMS 관리자 패널입니다. React 19 + Vite 8 기반 SPA이며, KUSITMS S
 
 ### Boot Loader
 
-@.claude/manifest.md
+@.claude/README.md
 
-상세 rule, reference, skill 로딩 기준은 `.claude/manifest.md`에서 관리합니다.
+상세 rule, reference, skill 로딩 기준은 `.claude/README.md`에서 관리합니다.

README.md

@@ -52,7 +52,7 @@ src/
 └── types.ts      # 공통 타입
 ```
 
-상세 구조와 생성 워크플로우 규칙은 `.claude/manifest.md`에서 연결된 rules 문서를 기준으로 합니다.
+상세 구조와 생성 워크플로우 규칙은 `.claude/README.md`에서 연결된 rules 문서를 기준으로 합니다.
 
 ## 개발 가이드
 

docs/CONVENTION.md

@@ -0,0 +1,228 @@
+# Frontend Convention
+
+프론트엔드 개발 과정에서 Git 사용 방식, PR 규칙, 코드 작성 기준을 일관되게 맞추기 위한 공용 협업 규칙입니다.
+프로젝트마다 다른 구조·라이브러리 규칙은 각 레포의 문서(예: [development.md](./development.md))에서 관리합니다.
+
+---
+
+## 1. Git Convention
+
+### 1-1. Branch 전략
+
+GitHub Flow를 사용합니다.
+
+| 브랜치      | 용도                        | 규칙                                   |
+| ----------- | --------------------------- | -------------------------------------- |
+| `main`      | 최종 배포 브랜치            | 직접 커밋 금지, PR을 통해서만 병합     |
+| 작업 브랜치 | 기능·버그·문서 등 모든 작업 | `main`에서 분기, 작업 후 `main`으로 PR |
+
+### 1-2. Branch 네이밍
+
+```text
+{type}/{작업내용}-{이슈번호}
+```
+
+- `type`은 커밋 type과 동일하게 사용합니다.
+- 서비스 중 긴급 수정은 예외적으로 브랜치 type `hotfix`를 사용합니다(`hotfix/payment-error-30`). 커밋 type에는 `hotfix`가 없으므로 커밋은 `fix:`로 작성합니다.
+- 작업 내용은 영어 소문자와 `-`로 작성합니다.
+
+| 작업 유형 | 예시                       |
+| --------- | -------------------------- |
+| 기능 개발 | `feat/login-ui-12`         |
+| 버그 수정 | `fix/login-error-21`       |
+| 문서 작업 | `docs/convention-3`        |
+| 리팩토링  | `refactor/auth-cleanup-18` |
+
+### 1-3. Commit 메시지
+
+Udacity Git Commit Message Style Guide를 기반으로 합니다.
+
+```text
+<type>: <subject>
+```
+
+| 타입       | 의미                            |
+| ---------- | ------------------------------- |
+| `feat`     | 기능 추가                       |
+| `fix`      | 버그 수정                       |
+| `docs`     | 문서, 주석 수정                 |
+| `style`    | 포맷팅 등 동작에 영향 없는 변경 |
+| `refactor` | 동작 변경 없는 코드 구조 개선   |
+| `test`     | 테스트 추가·수정                |
+| `chore`    | 설정, 빌드, 패키지 등 기타 작업 |
+
+작성 규칙:
+
+- `:` 앞은 붙이고 뒤는 한 칸 띄웁니다.
+- subject는 한국어로 짧게(50자 이내 권장), 마침표 없이 작성합니다.
+- 무엇을 했는지보다 왜 변경했는지가 드러나게 씁니다.
+- 하나의 커밋에는 하나의 작업 단위만 담습니다. 목적이 섞이면 분리합니다.
+- 필요하면 본문에 짧은 불릿으로 변경 내용을 적고, 푸터에 이슈를 참조합니다(`Closes #12`).
+
+```text
+feat: 로그인 UI 구현
+fix: 캘린더 스크롤 오류 수정
+docs: 프론트엔드 컨벤션 문서 추가
+refactor: 인증 관련 로직 분리
+```
+
+### 1-4. Pull Request
+
+- 작업 브랜치에서 `main`으로 PR을 생성합니다.
+- PR 제목은 PR 생성(opened/reopened) 시 브랜치명 기준으로 자동 정리됩니다. 브랜치가 `{type}/{작업내용}-{이슈번호}` 형식이면 `[Type] 이슈 제목`으로 바뀌고 type에 맞는 라벨이 붙습니다. 그래서 제목은 직접 맞추지 않아도 되고, 커밋 메시지 형식은 커밋에만 적용합니다.
+- 본문에는 연관 이슈, 주요 변경사항, 작업 내용, 리뷰 요구사항을 적고, UI 변경이 있으면 스크린샷을 첨부합니다.
+- 검증하지 못한 항목은 리뷰 요구사항에 명시합니다.
+- 리뷰어를 지정하고, 최소 1명의 승인과 CI 통과 후 병합합니다.
+- 충돌은 PR 작성자가 해결합니다.
+- 병합 전 불필요한 `console.log`, 주석 처리된 코드, 테스트용 코드를 제거합니다.
+
+### 1-5. Issue
+
+모든 작업은 Issue를 먼저 생성한 뒤 진행하고, 작업 브랜치는 Issue 번호 기준으로 만듭니다.
+
+```text
+[type] 작업 내용
+예: [feat] 로그인 화면 구현
+```
+
+---
+
+## 2. Coding Convention
+
+### 2-1. 네이밍
+
+| 대상               | 표기법            | 예시                          |
+| ------------------ | ----------------- | ----------------------------- |
+| 변수·함수·파라미터 | camelCase         | `userName`, `getUserInfo`     |
+| 클래스·생성자      | PascalCase        | `AccessToken`                 |
+| 컴포넌트           | PascalCase        | `UserProfile`                 |
+| 타입·인터페이스    | PascalCase        | `UserResponse`, `ButtonProps` |
+| 상수               | UPPER_SNAKE_CASE  | `MAX_RETRY_COUNT`             |
+| 훅                 | `use` + camelCase | `useAuth`                     |
+
+- 한글 발음을 영어로 표기하지 않고 의미에 맞는 영어 단어를 씁니다. (`moohyungJasan` ❌ → `intangibleAssets` ✅) 고유명사·브랜드명은 예외입니다.
+- 의미가 불분명한 이름(`a`, `data`, `temp`)을 피합니다. 짧은 반복문 인덱스(`i`)는 예외입니다.
+- boolean은 `is`, `has`, `can` 등으로 시작해 상태가 드러나게 합니다.
+- 이벤트 핸들러는 `handle` + 동작(`handleSubmit`), props로 넘기는 콜백은 `on` + 동작(`onSubmit`)으로 짓습니다.
+
+### 2-2. 파일·폴더 네이밍
+
+| 대상               | 규칙                         | 예시                                             |
+| ------------------ | ---------------------------- | ------------------------------------------------ |
+| 컴포넌트 파일·폴더 | PascalCase                   | `LoginForm.tsx`                                  |
+| 훅 파일            | camelCase                    | `useAuth.ts`                                     |
+| 유틸·API·상수 파일 | camelCase                    | `formatDate.ts`, `members.ts`, `apiConstants.ts` |
+| 테스트 파일        | 대상 파일 옆에 `.test.ts(x)` | `LoginForm.test.tsx`                             |
+
+프로젝트 안에서는 **하나의 방식을 선택해 일관되게** 사용합니다. (kebab-case를 쓰기로 했다면 컴포넌트를 제외한 모든 파일에 통일)
+
+### 2-3. 포맷·린트
+
+- 포맷은 Prettier, 정적 검사는 ESLint로 통일하고 사람이 스타일을 따로 맞추지 않습니다.
+- commit 시점에 자동 실행(lint-staged 등)되게 설정해 포맷이 어긋난 코드가 올라가지 않게 합니다.
+
+### 2-4. TypeScript
+
+- 명시적 `any`를 사용하지 않습니다. 형태를 모르면 `unknown`을 쓰고 좁혀서 사용합니다.
+- API 응답과 폼 데이터에는 명시적인 도메인 타입을 둡니다.
+- 타입은 재사용되기 전까지 사용하는 기능 근처에 둡니다.
+- 쓰지 않는 필드까지 과하게 모델링하지 않습니다.
+
+### 2-5. React
+
+- 함수 컴포넌트만 사용합니다.
+- 컴포넌트는 화면 표현에 집중하고, 상태·이벤트 로직은 훅, 서버 요청은 API 모듈, 순수 계산은 유틸로 분리합니다.
+- 재사용되거나 복잡도가 의미 있게 커진 뒤에 컴포넌트를 분리합니다.
+- 공통 컴포넌트는 `className`, `ref` 등 외부에서 스타일·동작을 조정할 수 있는 props를 열어 둡니다.
+- 시각 상태는 boolean props를 늘리지 않고 variant로 통합합니다.
+- 반복 UI는 JSX에 하드코딩하지 않고 데이터 배열로 렌더링합니다.
+- 서버에서 가져온 데이터를 전역 상태에 복제하지 않고 서버 상태 라이브러리(TanStack Query 등)를 사용합니다.
+- 서버 데이터를 `useState + useEffect`로 직접 fetch하지 않습니다.
+
+### 2-6. 스타일링
+
+- 스타일은 일관된 방식(Tailwind `className` 등)으로 작성하고 inline style은 피합니다.
+- 색상·간격·폰트는 디자인 토큰을 사용하고 임의 값을 하드코딩하지 않습니다.
+
+### 2-7. 접근성
+
+- 클릭 가능한 요소는 `div` 대신 `button`/`a` 같은 의미 있는 요소를 씁니다.
+- input에는 보이는 label 또는 접근 가능한 label을 둡니다.
+- 상태를 색상에만 의존해 표현하지 않습니다.
+- dialog, drawer 등은 focus 관리를 처리하는 검증된 primitive를 사용합니다.
+
+### 2-8. 비동기·상태 처리
+
+- 데이터 기반 화면은 loading, empty, error 상태를 항상 처리합니다.
+- 생성·수정·삭제 같은 변경 요청 후에는 관련 서버 상태를 갱신(invalidate)합니다.
+- API endpoint, request/response 형태는 명세(Swagger 등)로 확인하고 추측해서 작성하지 않습니다.
+
+### 2-9. 주석
+
+주석은 "무엇을 하는지"보다 **왜 그렇게 작성했는지**를 적습니다. 코드를 그대로 풀어쓴 주석은 쓰지 않습니다.
+
+```ts
+// 서버가 빈 문자열을 유효한 값으로 처리하므로 null 대신 빈 문자열을 보낸다
+const description = inputValue ?? ''
+```
+
+### 2-10. 로그
+
+- 개발 중 사용한 `console.log`는 커밋 전 제거합니다.
+- 에러 확인이 필요하면 `console.error`를 사용합니다.
+
+### 2-11. 코드 작성 원칙
+
+- 하나의 함수는 하나의 역할만 담당합니다.
+- 중복 코드는 함수·훅·유틸로 분리합니다. 단, 한 번만 쓰는 코드를 위한 추상화는 만들지 않습니다.
+- 중첩은 early return으로 줄입니다.
+- 요청하지 않은 기능, 설정 가능성, 확장성을 미리 넣지 않습니다.
+- 변경은 필요한 파일과 줄에만 합니다. 관련 없는 리팩터링은 같은 PR에 섞지 않습니다.
+- 이번 변경으로 쓰지 않게 된 import, 변수, 함수는 정리합니다.
+
+---
+
+## 3. Test Convention
+
+- 단위·컴포넌트 테스트는 대상 파일 옆에 두고, E2E는 별도 폴더에 둡니다.
+- 회귀 가능성이 있는 동작을 테스트합니다. form은 검증과 submit, 상태 변경은 화면 전환을 확인합니다.
+- snapshot만 있는 테스트, 구현 세부사항을 복제하는 테스트, 단위 테스트로 충분한 변경에 대한 광범위한 E2E는 피합니다.
+
+---
+
+## 4. Dependency Convention
+
+- 프로젝트에서 정한 패키지 매니저 하나만 사용합니다.
+- 의존성을 추가하기 전에 표준 라이브러리, 브라우저 기본 기능, 이미 설치된 패키지로 해결되는지 확인하고 팀과 공유합니다.
+- 생성 파일(barrel index, 아이콘 등)은 직접 수정하지 않고 원본이나 스크립트를 고친 뒤 재생성합니다.
+
+---
+
+## 5. Code Review Checklist
+
+- 브랜치명, 커밋 메시지, PR 제목이 컨벤션을 따르는가
+- 작업 내용이 Issue와 일치하는가
+- 네이밍이 직관적인가
+- 중복 코드가 없는가
+- 불필요한 주석, 로그, `any`, 미사용 코드가 없는가
+- 함수·컴포넌트의 책임이 분리되어 있는가
+- loading / empty / error 등 예외 상황을 처리했는가
+- 접근성(label, 의미 있는 요소, focus)을 지켰는가
+- 검증(테스트, lint, build)을 변경 범위에 맞게 실행했는가
+- UI 변경 시 스크린샷이 첨부되었는가
+
+---
+
+## 6. 작업 진행 순서
+
+```text
+Issue 생성
+→ 작업 브랜치 생성
+→ 기능 개발
+→ 커밋
+→ main으로 PR 생성
+→ 코드 리뷰
+→ 병합
+```
+
+컨벤션과 맞지 않는 상황이 생기면 팀원과 논의한 뒤 이 문서를 업데이트합니다.