[DOCS] PR 생성 및 리뷰 스킬 추가

.agents/skills/dt-fe-code-review/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: dt-fe-code-review
+description: Debate Timer FE의 PR·브랜치·diff를 검토하고 분류별 근거와 검증 결과를 로컬 보고서에 기록할 때 사용함.
+---
+
+# 코드 리뷰
+
+[코드 리뷰 워크플로](../../../docs/workflows/dt-fe-code-review.md)를 읽고 적용함.
+요청된 범위를 먼저 확인하고, 발견 사항과 실제 검증 결과를 보고함.

.agents/skills/dt-fe-pull-request/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: dt-fe-pull-request
+description: Debate Timer FE의 일반 작업 브랜치에서 develop으로 보내는 PR을 검토·검증·준비·생성할 때 사용함.
+---
+
+# 일반 PR 생성
+
+[PR 생성 워크플로](../../../docs/workflows/dt-fe-pull-request.md)를 읽고 적용함.
+PR 준비 전에 **`dt-fe-code-review` 스킬을 먼저 호출**하고 보고서를 확인함.
+승인 경계를 지키며 일반 작업 PR을 생성함.

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

@@ -0,0 +1,9 @@
+---
+name: dt-fe-code-review
+description: Debate Timer FE의 PR·브랜치·diff를 검토하고 분류별 근거와 검증 결과를 로컬 보고서에 기록할 때 사용함.
+---
+
+# 코드 리뷰
+
+[코드 리뷰 워크플로](../../../docs/workflows/dt-fe-code-review.md)를 읽고 적용함.
+요청된 범위를 먼저 확인하고, 발견 사항과 실제 검증 결과를 보고함.

.claude/skills/dt-fe-pull-request/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: dt-fe-pull-request
+description: Debate Timer FE의 일반 작업 브랜치에서 develop으로 보내는 PR을 검토·검증·준비·생성할 때 사용함.
+---
+
+# 일반 PR 생성
+
+[PR 생성 워크플로](../../docs/workflows/dt-fe-pull-request.md)를 읽고 적용함.
+PR 준비 전에 **`dt-fe-code-review` 스킬을 먼저 호출**하고 보고서를 확인함.
+승인 경계를 지키며 일반 작업 PR을 생성함.

.gitignore

@@ -25,3 +25,7 @@ yarn-error.log*
 
 *storybook.log
 
+# 로컬 리뷰 보고서와 PR 초안
+/review-report-????-??-??.md
+/PR.md
+

AGENTS.md

@@ -21,15 +21,23 @@
 문서끼리 충돌하면 우선순위로 임의 선택하지 않고 문서 오류로 보고함. 실행 권한
 경계는 다른 문서에서 생략해도 계속 적용함.
 
+### 에이전트 작업 안내
+
+에이전트는 작업 내용을 대략 식별한 직후, [문서 지도](docs/README.md)의 작업별
+읽기 경로를 기준으로 즉시 읽어야 할 `docs/architecture/` 또는
+`docs/conventions/` 내 상세 문서를 사용자에게 명시적으로 답변함. 문서의 실제
+파일 경로와 선택 이유를 제시하고, 해당 문서를 읽은 뒤 작업을 진행함.
+
 ## 작업 절차
 
 1. 변경 목적과 영향을 받는 화면·데이터·소켓·테스트 경계를 확인함.
-2. 관련 상세 문서와 현재 코드를 대조함. 기존 코드의 불일치를 새 규칙의 예외로
+2. 작업 관련 읽어야 할 상세 문서를 식별하고, 읽을 예정인 문서 목록을 사용자에게 안내.
+3. 작업 관련 문서와 현재 코드를 대조함. 기존 코드의 불일치를 새 규칙의 예외로
    확대하지 않음.
-3. 기능 구현은 [TDD 절차](docs/conventions/testing-and-storybook.md)에 따라 실패
+4. 기능 구현은 [TDD 절차](docs/conventions/testing-and-storybook.md)에 따라 실패
    확인 → 최소 구현 → 리팩터링 순으로 진행함.
-4. 계약·경로가 바뀌면 해당 소유 문서와 문서 지도의 링크·요약을 갱신함.
-5. 영향 범위에 맞는 테스트, lint, 타입 검사, build를 실행하고 실제 결과를
+5. 계약·경로가 바뀌면 해당 소유 문서와 문서 지도의 링크·요약을 갱신함.
+6. 영향 범위에 맞는 테스트, lint, 타입 검사, build를 실행하고 실제 결과를
    보고함. 실행하지 못한 검증은 통과로 적지 않음.
 
 기존 사용자 변경과 작업 트리를 보존함. 범위 밖 파일을 되돌리거나 커밋에 포함하지

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -48,5 +48,5 @@
 
 ## 📖 문서
 
-- [아키텍처 소개](/docs/README.md)
-- [헌법](/docs/CONSTITUTION.md)
+- [아키텍처 소개](docs/README.md)
+- [헌법](docs/CONSTITUTION.md)

docs/README.md

@@ -15,7 +15,9 @@
 계약을 대체하거나 재정의하지 않음. 헌법과 직접 충돌하면 헌법을 우선함. 이 문서의
 요약과 상세 계약이 다르거나 상세 문서끼리 다르면 문서 오류로 보고·수정함.
 [AGENTS.md](../AGENTS.md)는 에이전트의 실행 절차, 루트
-[README.md](../README.md)는 공개 안내를 소유함.
+[README.md](../README.md)는 공개 안내를 소유함. `docs/workflows/`는
+저장소 전용 스킬의 실행 흐름과 중단·검증 절차를 소유함. 스킬 진입점은
+`.agents/skills/`와 `.claude/skills/`에 둠.
 
 ## 2. 현재 기술과 계층 지도
 
@@ -62,7 +64,14 @@ main.tsx → Router → page → 기능 전용 UI·hooks → 공용 UI·hooks
 | [데이터·실시간](conventions/data-and-realtime.md)          | Query·Mutation·API·MSW·Repository·소켓 작성 형식 |
 | [테스트·Storybook](conventions/testing-and-storybook.md)   | TDD, 테스트·모킹·Story 작성 방식                 |
 
-## 5. 작업별 필수 읽기와 갱신
+## 5. 스킬 워크플로
+
+| 문서                                            | 읽을 때                                           |
+| ----------------------------------------------- | ------------------------------------------------- |
+| [코드 리뷰](workflows/dt-fe-code-review.md)     | PR·브랜치·diff를 검토하고 보고서를 작성할 때      |
+| [일반 PR 생성](workflows/dt-fe-pull-request.md) | 작업 브랜치에서 `develop`으로 PR을 준비·생성할 때 |
+
+## 6. 작업별 필수 읽기와 갱신
 
 모든 코드 변경 전에 [헌법](CONSTITUTION.md)과 이 문서를 읽고, 아래에서 해당하는
 상세 문서를 함께 읽음. 여러 행에 해당하면 모두 적용함.
@@ -76,12 +85,14 @@ main.tsx → Router → page → 기능 전용 UI·hooks → 공용 UI·hooks
 | 오류 UI·Sentry                     | 오류와 관측, React·UI, 테스트·Storybook       | 오류와 관측                             |
 | 테스트·Story                       | 테스트·Storybook, 대상 기능의 아키텍처·컨벤션 | 테스트·Storybook 또는 대상 문서         |
 | 문서·템플릿                        | 문서 작성, 이 문서, 관련 상세 문서            | 원칙 변경은 헌법, 계약 변경은 소유 문서 |
+| 코드 리뷰·리뷰 보고서              | 코드 리뷰, 변경 영역의 상세 문서              | 코드 리뷰 또는 해당 상세 문서           |
+| 일반 PR 준비·생성                  | 일반 PR 생성, 코드 리뷰, 문서 작성            | 일반 PR 생성 또는 코드 리뷰             |
 
-표의 문서 이름은 3·4절의 링크를 가리킴. 정확히 일치하는 행이 없으면 변경 대상과
+표의 문서 이름은 3~5절의 링크를 가리킴. 정확히 일치하는 행이 없으면 변경 대상과
 소비자를 기준으로 관련 문서를 선택함. 경로·기술·작업 분류가 바뀌면 이 문서의
 지도와 읽기 표를 갱신함.
 
-## 6. 현재 코드와 목표 규칙
+## 7. 현재 코드와 목표 규칙
 
 상세 문서의 확정 규칙은 새 코드와 실질적으로 수정한 코드에 적용함. 일부 기존
 코드는 함수 선언, 상수 이름, Props 구조분해, 버튼 이름, 테스트 함수 이름 등에서

docs/conventions/docs.md

@@ -3,14 +3,17 @@
 ## 적용 범위
 
 이 문서는 `docs/**/*.md`, 루트 `AGENTS.md`·`README.md`, `.github`의 이슈·PR
-Markdown 템플릿에 적용함.
+Markdown 템플릿과 `.agents/skills/*/SKILL.md`에 적용함.
 
 ## 형식과 분량
 
 - 문서는 Markdown으로 작성함.
 - 빈 줄, 표, 코드 블록, front matter를 포함한 물리적 줄 수를 셈.
 - 모든 적용 문서는 500줄을 넘기지 않음. `docs/README.md` 이외의 문서는 300줄
   이하를 권장함.
+- `docs/workflows/`의 스킬 워크플로 문서와 `.agents/skills/*/SKILL.md`는
+  200줄 이하를 권장하고 300줄을 넘기지 않음. 200줄을 넘으면 중복을 먼저
+  제거하고 책임이 다른 경우에만 분할함.
 - 300줄을 넘으면 중복을 먼저 제거하고, 서로 다른 독자 과제나 책임이 섞여 있을
   때만 분할함. 분량을 채우려고 내용을 추가하지 않음.
 - 문장형 어미 대신 `~함`, `~했음`, `~임` 등 명사형 어미로 종결함. 코드, 명령어,

docs/workflows/dt-fe-code-review.md

@@ -0,0 +1,49 @@
+# 코드 리뷰 워크플로
+
+## 호출과 범위
+
+`dt-fe-code-review` 스킬을 호출하면 이 절차를 적용함. 리뷰 대상 PR, 브랜치 또는
+diff가 명시되면 해당 대상을 기준으로 검토함. 대상이 없으면 현재 브랜치의
+`develop` 대비 커밋 변경과 현재 작업 트리의 staged·unstaged·새 파일을 함께
+검토함. 기준 브랜치와 실제 변경 범위를 먼저 기록하고 중복된 변경은 한 번만 검토함.
+
+스킬 호출은 아래 로컬 보고서 작성까지 포함함. 사용자가 명시적으로 읽기 전용
+검토를 요청하면 파일을 변경하지 않고 결과를 답변에 제공함. 대상이 불명확하거나
+기준 브랜치를 확인할 수 없으면 범위를
+추측하지 않고 사용자에게 확인함. `develop → main` 배포 PR은 이 일반 작업
+워크플로의 대상이 아님.
+
+## 검토
+
+1. [헌법](../CONSTITUTION.md), [문서 지도](../README.md), 변경 영역의 상세 계약과
+   실제 코드를 대조함. 리뷰 중 코드·Git index·외부 상태를 변경하지 않음.
+2. PR이면 base·head와 실제 diff를 확인함. 브랜치이면 `develop`과의 분기점 및
+   커밋 diff를 확인함. 작업 트리의 staged·unstaged diff와 새 파일도 별도로 확인함.
+3. 기능·회귀·데이터 경계·접근성·테스트 누락 및 확정 컨벤션 위반을 검토함.
+   기존 코드의 불일치를 새 규칙의 예외로 해석하지 않음.
+4. 필요한 검증은 실행 가능 범위에서 수행하고 명령, 결과, 실행하지 못한 이유를
+   구분함. 재현되지 않은 문제는 확정된 발견 사항으로 단정하지 않음.
+5. 발견 사항은 영향과 우선순위에 따라 `상`·`중`·`하`·`컨벤션 위반`으로
+   분류함. 각 항목에 파일·위치, 관찰 근거, 재현 조건 또는 확인 방법, 영향과
+   권장 조치를 적음. 계약 위반은 영향도와 별개로 `컨벤션 위반`에 둠.
+
+`상`은 기능·데이터·보안·핵심 사용자 흐름을 깨뜨리는 문제, `중`은 제한된 경로의
+동작 오류나 유의미한 회귀 위험, `하`는 영향이 작은 결함이나 개선 사항으로
+분류함. 확실하지 않은 사항은 근거와 미확인 조건을 표시함.
+
+## 보고서
+
+한국 시간 날짜로 루트 `review-report-yyyy-mm-dd.md`에 대상, 기준 커밋 또는
+diff, 요약, 분류별 발견 사항, 실행한 검증과 미실행 검증, 잔여 위험을 기록함.
+발견 사항이 없으면 그 사실과 검토 범위·한계를 명시함. 사용자에게도 주요 결과와
+보고서 경로를 전달함.
+
+같은 날 파일이 있으면 먼저 내용을 읽음. 이전 자동 보고서임을 확인할 수 있는
+구간만 갱신함. 사용자 작성 내용이 있으면 보존하고 새 자동 보고서 구간을
+추가하거나 갱신함. 자동 구간은 `<!-- dt-fe-code-review:start -->`와
+`<!-- dt-fe-code-review:end -->`로 표시함. 구분이 불가능하면 덮어쓰지 않고
+사용자에게 충돌을 알림.
+
+보고서는 로컬 산출물임. 커밋·push 대상에서 제외하고, 리뷰 범위에도 포함하지
+않음. PR을 준비할 때는 [PR 생성 워크플로](dt-fe-pull-request.md)의 중단 조건에
+따라 결과를 처리함.

docs/workflows/dt-fe-pull-request.md

@@ -0,0 +1,77 @@
+# 일반 PR 생성 워크플로
+
+## 범위와 시작
+
+`dt-fe-pull-request` 스킬을 호출하면 이 절차를 적용함. 일반 작업 브랜치에서
+`develop`으로 보내는 PR만 다룸. `develop → main` 배포 PR은 개발자가 GitHub에서
+직접 진행함. Git 변경·commit·push·PR 생성 권한은 [AGENTS.md](../../AGENTS.md)의
+경계를 따름.
+
+1. 현재 브랜치, HEAD, upstream, `develop` 및 원격 상태, staged·unstaged·새 파일,
+   기존 PR, 명시적 제외 파일을 확인함. 실제 브랜치나 이슈가 사용자 설명과 다르면
+   차이를 알리고 대상을 확인함. 이슈 번호가 없으면 추측하지 않고 질문함.
+2. `develop`에서 시작한다면 `git fetch origin develop`로 원격 최신 커밋을
+   가져온 뒤 현재 HEAD가 `origin/develop`의 조상인지 확인함. fast-forward가
+   가능할 때만 `git merge --ff-only origin/develop`로 `develop`을 갱신하고
+   [AGENTS.md](../../AGENTS.md)의 이슈 브랜치 규칙으로 분기함. 미커밋 변경은
+   보존함. 갱신이 변경과 충돌하거나 fast-forward가
+   불가능하면 중단하고 상태를 사용자에게 알림. 변경을 폐기하거나 강제 갱신하지
+   않음.
+3. 이미 작업 브랜치라면 실제 이슈와 대상 브랜치를 확인하고 현재 변경을 유지함.
+   상태 변경 명령이 중단되면 프로세스, 파일·Git 상태, HEAD와 lock을 확인한 뒤
+   재시도 여부를 결정함.
+
+## 선행 리뷰와 중단 조건
+
+PR 작성 전에 **`dt-fe-code-review` 스킬을 먼저 호출**하고
+[코드 리뷰 워크플로](dt-fe-code-review.md)에 따라 현재 PR 범위의 리뷰 보고서를
+확인함. 보고서의 `상` 또는 `컨벤션 위반`이 하나라도 있으면 PR 진행을 중단함.
+보완 계획과 변경 파일·검증 범위를 제시하고 수정 승인을 요청함. 승인 후 수정,
+영향 범위 검증, 같은 범위의 재리뷰를 수행함. 차단 항목이 사라진 보고서를
+확인한 뒤 진행함. `중`·`하`만 있으면 미해결 항목의 근거·영향을 PR 본문에
+공개하고 진행함.
+
+## 검증과 커밋
+
+`npx vitest run`, `npm run lint`, `npm run build`를 실행하고 각 종료 상태와
+핵심 결과를 기록함. 실패한 검증이 있으면 PR을 중단하고 원인과 보완 방법을
+제시함. 실행 불가 항목은 이유, 수동 실행 명령과 확인할 동작을 제시하고
+사용자 결정을 기다림. CI에서 빠진 중요한 검증도 PR 리뷰 요구사항에 수동
+실행 명령과 확인 동작을 적음.
+
+미커밋 변경을 커밋해야 하면 포함·제외 파일과 커밋 단위를 사용자에게 보여주고
+승인을 받은 뒤 커밋함. `review-report-yyyy-mm-dd.md`와 `PR.md`는 로컬 산출물로
+유지하고 커밋·push에서 제외함. 커밋 전 실제 브랜치와 staging을 다시 확인함.
+커밋 후에는 PR에 들어갈 `develop...HEAD` 변경 범위를 다시 확인함.
+
+## PR 본문과 생성
+
+PR 제목은 `[{label}] {title}` 형식으로 작성함. `{label}`은 현재 브랜치 이름의
+첫 `/` 앞 접두어에서 우선 파싱함. 접두어가 아래 GitHub 레이블 목록에 없거나
+접두어가 없으면, 해당 목록에서 PR 변경의
+주된 목적에 맞는 레이블을 선택함. 레이블 이름의 대소문자는 목록과 일치시킴.
+`{title}`은 PR에 포함된 전체 변경을 종합해 에이전트가 결정함. 예를 들어 문서 변경을 포함한
+`docs/#514-add-new-skills` 브랜치는 `[docs] PR 생성 및 리뷰 스킬 추가`로 작성함.
+
+2026-10-01에 [저장소 레이블](https://github.com/debate-timer/debate-timer-fe/labels)을
+조회한 목록임.
+
+- `feat`: 기능 개발, `fix`: 버그 수정, `hotfix`: 긴급 수정임.
+- `design`: UI 변경, `docs`: 문서 작업, `test`: 테스트 코드 작업임.
+- `refactor`: 기능 변경 없는 코드 변경, `style`: 코드 컨벤션 변경임.
+- `config`: 외부 라이브러리 추가·설정, `chore`: 파일 이동·이름 변경·삭제임.
+- `deploy`: `develop → main` 배포이며 이 일반 PR 스킬의 대상에서 제외함.
+
+루트 [PR 템플릿](../../.github/PULL_REQUEST_TEMPLATE.md)의 `연관 이슈`,
+`작업 내용`, 선택적 `스크린샷`, `리뷰 요구사항` 형식으로 루트 `PR.md`를 작성함.
+변경 배경, 사용 예시·정책·처리 흐름, 실제 검증 결과, 미실행 검증, 리뷰 관점과
+미해결 `중`·`하` 발견 사항을 관련 항목에 적음. 이슈 연결 문구는 확인된 번호만
+사용함.
+
+push 직전에 실제 브랜치, upstream, 커밋과 diff, push 대상·범위, staging 및
+제외 파일을 사용자에게 보여주고 **별도 승인**을 받음. 승인 전에는 push와 PR
+생성을 진행하지 않음. 승인 후 확인한 범위만 push하고
+`gh pr create --base develop --head <branch> --title "[{label}] {title}" --body-file PR.md`로
+PR을 생성함.
+명령이 중단되거나 실패하면 원격 브랜치·기존 PR 상태를 확인하고 중복 생성하지
+않음. 생성된 PR 링크와 검증·리뷰 결과를 보고함.