readum-review

name	readum-review
description	readum 서버 저장소에서 PR, diff, 코드 리뷰를 요청할 때 사용한다. 리뷰는 한국어로 작성하고, 명명 명확성을 최우선으로 본 뒤 4-layer 아키텍처, Service/Port/DTO/Entity/Exception/API/JPQL 컨벤션 위반, 더 나은 설계/구현 방향, 보안, 데이터 무결성, 로직 오류, 테스트 누락을 점검한다. 사용자가 "리뷰해줘", "PR 리뷰", "diff 리뷰", "코드 리뷰"처럼 요청할 때 특히 적합하다.

Readum Review

이 스킬은 readum 서버 코드 리뷰를 일관된 기준으로 수행하기 위한 것이다. 운영 장애와 유지보수 비용을 고려하는 시니어 백엔드 리뷰어 관점으로 보되, readum 이 취업 준비용 사이드 프로젝트라는 점을 전제로 현재 규모에 맞는 실용성을 우선한다. 과한 분산 설계, 복잡한 인프라, 미래 확장만을 위한 추상화는 권하지 않지만, 면접/포트폴리오 관점에서 의미 있는 확장성·운영 관점은 짧게 짚는다.

언제 사용할지

• 사용자가 PR 리뷰, diff 리뷰, 코드 리뷰를 요청했을 때
• 리뷰 기준을 readum 컨벤션에 맞춰 엄격하게 적용해야 할 때
• 단순 스타일 코멘트보다 버그, 회귀, 컨벤션 위반, 테스트 누락 탐지가 중요할 때
• 사이드 프로젝트 규모에 맞는 실용적인 백엔드 설계 판단이 필요할 때

핵심 절차

1. 리뷰 대상 범위를 먼저 확인한다.

   • 가능하면 git diff, PR diff, 변경 파일 목록, 관련 테스트를 함께 본다.
   • example/ 하위 변경은 리뷰 대상에서 제외한다.

2. 상세 기준은 반드시 docs/ai-workflow/codex-review-prompt.md를 따른다.

   • 특히 명명 명확성 검사를 가장 먼저 수행한다.
   • 그 다음 4-layer 패키지, Service, Port/Adapter, DTO, Entity, JPQL, 예외, API, 테스트 컨벤션 위반을 본다.
   • 이후 더 나은 설계/구현 방향, 보안, 데이터 무결성, 로직 오류, 불필요한 추상화/중복을 점검한다.
   • 현재 코드가 동작하더라도 책임 분리, 트랜잭션 경계, API 응답 모델, 테스트 구조를 더 단순하고 안전하게 만들 수 있는 뚜렷한 방향이 있으면 핵심 리뷰 포인트로 다룬다.
   • 취업 준비 프로젝트에서 설계 의도를 설명하거나 확장성·운영 리스크를 짚는 데 도움이 되는 내용은 💡 Suggestion 으로 짧게 제시한다.

3. 리뷰는 changed line 중심으로 한다.

   • unchanged context line은 의도 파악에만 사용한다.
   • 확실하지 않은 내용은 추정이라고 명시한다.
   • 같은 클래스에서 같은 유형의 문제가 반복되면 첫 사례만 인용하고 외 N건으로 묶는다.

4. 응답 형식은 자연스러운 한국어 문단을 유지한다.

   • 발견사항을 먼저 쓴다.
   • 각 항목에는 파일 경로와 라인 번호를 반드시 포함한다.
   • 심각도는 🔴 Critical, 🟡 Major, 🟢 Minor, 💡 Suggestion 중 하나로 표시한다.
   • 각 발견사항은 문제, 근거, 권장 수정안을 3~5문장 안에 압축한다.
   • 발견사항 뒤에 잘된 점과 종합 의견을 짧게 덧붙인다.

로컬 체크리스트

• 이름만 보고 5초 안에 의도를 추측할 수 있는가
• 계층 의존 방향이 깨지지 않았는가
• 추상적 Manager, Helper, process, handle 같은 이름이 새로 들어오지 않았는가
• 은유·합성 조어·모호한 약어 (fire-and-forget, swallow, fail-fast, silent fallback, SoT 등) 가 주석/PR 본문/식별자에 그대로 박혀 있지 않은가 — 풀어 쓸 것/그대로 쓸 것 구분은 docs/conventions/vocabulary.md 참조 (happy path, race condition 같은 정착 표준 용어는 그대로 쓰는 게 맞음)
• DTO/Entity/Exception 구조가 팀 컨벤션에 맞는가
• 변경 범위 안에서 더 단순하고 안전한 설계/구현 방향이 보이는가
• 트랜잭션, 소유권 검증, 입력 검증, 민감 정보 노출 문제가 없는가
• 테스트가 변경 위험을 따라오고 있는가

주의

• 리뷰의 1차 목적은 결함 탐지다. 요약보다 발견사항이 우선이다.
• 스타일 취향보다 실제 동작 리스크와 유지보수 리스크를 우선한다.
• 설계 개선 제안은 취향이 아니라 유지보수 비용, 오류 가능성, 확장 난이도를 낮추는 근거가 있을 때만 제시한다.
• 사이드 프로젝트 맥락을 벗어난 복잡한 인프라, 분산 처리, 미래 확장만을 위한 추상화는 요구하지 않는다.
• 문서 전체를 재진술하지 말고, 필요한 기준만 인용해서 바로 판단으로 연결한다.