diff --git a/.agents/skills/dt-fe-code-review/SKILL.md b/.agents/skills/dt-fe-code-review/SKILL.md new file mode 100644 index 00000000..990ae282 --- /dev/null +++ b/.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)를 읽고 적용함. +요청된 범위를 먼저 확인하고, 발견 사항과 실제 검증 결과를 보고함. diff --git a/.agents/skills/dt-fe-pull-request/SKILL.md b/.agents/skills/dt-fe-pull-request/SKILL.md new file mode 100644 index 00000000..733aa065 --- /dev/null +++ b/.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을 생성함. diff --git a/.claude/skills/dt-fe-code-review/SKILL.md b/.claude/skills/dt-fe-code-review/SKILL.md new file mode 100644 index 00000000..990ae282 --- /dev/null +++ b/.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)를 읽고 적용함. +요청된 범위를 먼저 확인하고, 발견 사항과 실제 검증 결과를 보고함. diff --git a/.claude/skills/dt-fe-pull-request/SKILL.md b/.claude/skills/dt-fe-pull-request/SKILL.md new file mode 100644 index 00000000..1fe703f3 --- /dev/null +++ b/.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을 생성함. diff --git a/.gitignore b/.gitignore index 9e2f6755..89585812 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,7 @@ yarn-error.log* *storybook.log +# 로컬 리뷰 보고서와 PR 초안 +/review-report-????-??-??.md +/PR.md + diff --git a/AGENTS.md b/AGENTS.md index d2b4f714..8556724b 100644 --- a/AGENTS.md +++ b/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를 실행하고 실제 결과를 보고함. 실행하지 못한 검증은 통과로 적지 않음. 기존 사용자 변경과 작업 트리를 보존함. 범위 밖 파일을 되돌리거나 커밋에 포함하지 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.md b/README.md index 7cf63407..5cf69d95 100644 --- a/README.md +++ b/README.md @@ -48,5 +48,5 @@ ## 📖 문서 -- [아키텍처 소개](/docs/README.md) -- [헌법](/docs/CONSTITUTION.md) +- [아키텍처 소개](docs/README.md) +- [헌법](docs/CONSTITUTION.md) diff --git a/docs/README.md b/docs/README.md index cc7978e3..8e3edad2 100644 --- a/docs/README.md +++ b/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 구조분해, 버튼 이름, 테스트 함수 이름 등에서 diff --git a/docs/conventions/docs.md b/docs/conventions/docs.md index 07e55847..6cfa115a 100644 --- a/docs/conventions/docs.md +++ b/docs/conventions/docs.md @@ -3,7 +3,7 @@ ## 적용 범위 이 문서는 `docs/**/*.md`, 루트 `AGENTS.md`·`README.md`, `.github`의 이슈·PR -Markdown 템플릿에 적용함. +Markdown 템플릿과 `.agents/skills/*/SKILL.md`에 적용함. ## 형식과 분량 @@ -11,6 +11,9 @@ Markdown 템플릿에 적용함. - 빈 줄, 표, 코드 블록, front matter를 포함한 물리적 줄 수를 셈. - 모든 적용 문서는 500줄을 넘기지 않음. `docs/README.md` 이외의 문서는 300줄 이하를 권장함. +- `docs/workflows/`의 스킬 워크플로 문서와 `.agents/skills/*/SKILL.md`는 + 200줄 이하를 권장하고 300줄을 넘기지 않음. 200줄을 넘으면 중복을 먼저 + 제거하고 책임이 다른 경우에만 분할함. - 300줄을 넘으면 중복을 먼저 제거하고, 서로 다른 독자 과제나 책임이 섞여 있을 때만 분할함. 분량을 채우려고 내용을 추가하지 않음. - 문장형 어미 대신 `~함`, `~했음`, `~임` 등 명사형 어미로 종결함. 코드, 명령어, diff --git a/docs/workflows/dt-fe-code-review.md b/docs/workflows/dt-fe-code-review.md new file mode 100644 index 00000000..abb37606 --- /dev/null +++ b/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, 요약, 분류별 발견 사항, 실행한 검증과 미실행 검증, 잔여 위험을 기록함. +발견 사항이 없으면 그 사실과 검토 범위·한계를 명시함. 사용자에게도 주요 결과와 +보고서 경로를 전달함. + +같은 날 파일이 있으면 먼저 내용을 읽음. 이전 자동 보고서임을 확인할 수 있는 +구간만 갱신함. 사용자 작성 내용이 있으면 보존하고 새 자동 보고서 구간을 +추가하거나 갱신함. 자동 구간은 ``와 +``로 표시함. 구분이 불가능하면 덮어쓰지 않고 +사용자에게 충돌을 알림. + +보고서는 로컬 산출물임. 커밋·push 대상에서 제외하고, 리뷰 범위에도 포함하지 +않음. PR을 준비할 때는 [PR 생성 워크플로](dt-fe-pull-request.md)의 중단 조건에 +따라 결과를 처리함. diff --git a/docs/workflows/dt-fe-pull-request.md b/docs/workflows/dt-fe-pull-request.md new file mode 100644 index 00000000..790f7d62 --- /dev/null +++ b/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 --title "[{label}] {title}" --body-file PR.md`로 +PR을 생성함. +명령이 중단되거나 실패하면 원격 브랜치·기존 PR 상태를 확인하고 중복 생성하지 +않음. 생성된 PR 링크와 검증·리뷰 결과를 보고함.