plan-route

name	plan-route
description	src/app 하위 특정 라우트(page.tsx가 있는 디렉토리) 하나에 국한된 작업을 요청받았을 때, 구현을 시작하기 전에 반드시 이 스킬을 먼저 실행한다. 그 라우트 폴더의 _docs/plan.md를 확인/생성하고, 작업 항목을 todo 체크리스트로 기록한 뒤 진행 상황을 갱신한다. 공통 컴포넌트(src/components), 전역 hooks/store/utils, 여러 라우트에 걸치는 작업에는 사용하지 않는다.

plan-route

라우트별 작업 계획을 해당 라우트 폴더 하위 _docs/plan.md에 todo 체크리스트로 기록하고, 작업 진행에 따라 갱신한다.

대상 판단

page.tsx가 있는 디렉토리를 라우트 폴더로 본다. 라우트 폴더는 route group에 따라 위치가 다르다:

• src/app/(home)/ — 그룹 폴더 자체가 라우트 (하위에 별도 라우트명 폴더 없음)
• src/app/(admin)/{routeName}/, src/app/(route)/{routeName}/ — 그룹 하위 라우트명 폴더

요청이 그 라우트 폴더 하위(page.tsx, _components/_hooks/_types/_utils)만 다루면 대상으로 본다. 다음 경우엔 이 스킬을 사용하지 않는다:

• 여러 라우트에 걸친 요청 — 각 라우트가 별개 작업이면 이 스킬 대상이 아니다 (라우트마다 따로 요청받았을 때만 각각의 plan.md를 개별 적용)
• src/components, src/hooks, src/store, src/utils 등 전역 공통 코드를 다루는 작업
• 라우트 하나로 좁혀지지 않는 범위가 애매한 요청 — 이 경우 사용자에게 대상 라우트를 먼저 확인한다

절차

1. 시작 전: {라우트 폴더}/_docs/plan.md를 읽는다.

   • 파일이 없으면 새로 만든다: # {routeName} 작업 계획 제목 아래, 이번 요청의 작업 항목을 - [ ] ... 체크리스트로 정리해 작성한다.
   • 파일이 이미 있으면(제목만 있는 빈 파일 포함) 기존 내용을 그대로 두고, 이번 요청에 해당하는 새 작업 항목을 이어서 추가한다. 기존 완료(- [x]) 항목은 수정하지 않는다.
   • 작업 항목은 실제로 변경할 코드 단위로 구체적으로 쪼갠다 (예: "AlertCategory 필터 UI 추가", "알림 읽음 처리 API 연동"). "작업하기"처럼 뭉뚱그리지 않는다.

2. 작업 진행 중: 항목을 하나 마칠 때마다 즉시 해당 줄을 - [x]로 갱신한다. 여러 항목을 몰아서 한 번에 갱신하지 않는다.

3. 응답을 마치기 전: plan.md의 상태가 실제 완료 여부와 일치하는지 다시 확인하고 저장한다. 이번 요청 범위에서 착수하지 못한 항목은 - [ ]로 남겨 다음 세션이 이어갈 수 있게 한다.

번역(i18n) 체크리스트

이 라우트에 새로운 정적 텍스트가 추가되면(신규 페이지 생성이든 기존 페이지 수정 중 텍스트 추가든 동일하게), 절차 1번에서 plan.md 체크리스트를 작성할 때 아래 항목도 함께 넣는다. (admin) 라우트 그룹처럼 i18n 대상에서 제외된 라우트(eslint.config.mjs의 ignore 목록 참고)는 생략한다.

• 네임스페이스 이름 정하기 (컴포넌트/페이지명 PascalCase, src/messages/ko.json 기준 — 구현 전에 먼저 정해서 하드코딩 없이 바로 t()로 작성)
• 하드코딩 대신 t()/useTranslations(클라이언트), getTranslations(서버)로 구현
• src/messages/ko.json, en.json에 키를 동시에 추가 (한쪽만 채우고 나중으로 미루지 않기)
• npm run lint:i18n-literal, npm run check:i18n-keys 로컬 실행해 통과 확인

check:i18n-keys는 CI(jest.yml)에서도 자동으로 실행되어 ko/en 키 불일치 시 PR을 막지만(차단형), lint:i18n-literal은 기존 하드코딩 잔여분 때문에 CI에서는 참고용(비차단)으로만 연결되어 있다. 새로 작성한 코드에 하드코딩이 남아 있는지는 로컬에서 직접 확인해야 한다.

로케일마다 표현 방식이 달라 ko/en 키가 의도적으로 비대칭인 경우(예: 복수형 처리 차이)는 scripts/check-i18n-keys.js의 ALLOWED_MISMATCHES 목록에 추가하면 된다.

주의

• plan.md는 문서일 뿐이다. 코드 변경 없이 plan.md만 갱신하고 끝내지 않는다.
• _docs도 다른 private 폴더(_components 등)와 동일하게 취급한다 — 라우트 밖에서 import하지 않는다.
• 이 스킬은 문서화 절차만 다룬다. 빌드/테스트 실행 여부는 루트 CLAUDE.md의 검증 커맨드 규칙을 따로 따른다.
• git add/commit 대상에 plan.md를 포함할지는 일반 커밋 규칙(이번 응답에서 Claude가 건드린 파일만 add)을 그대로 따른다.