프로젝트 4: 코드 리뷰 Skill 만들기
코드 리뷰 Skill은 팀의 취향을 적는 문서가 아닙니다. 팀이 실제로 무엇을 위험으로 보고, 무엇을 품질이라고 부르며, 어디서 자주 회귀가 나는지를 에이전트가 재현 가능하게 검사하도록 만드는 실행 패키지입니다. 특히 AI가 작성한 코드가 늘어날수록, 코드 리뷰는 "좋아 보인다"는 인상 비평이 아니라, 근거와 절차를 가진 검증 시스템이 되어야 합니다.1
이번 장에서는 프로젝트 컨벤션, 보안·성능·유지보수성 기준, 테스트 정책, 리뷰 코멘트 톤, PR 요약 형식까지 한 번에 담는 코드 리뷰 Skill을 실제로 설계해 보겠습니다. 목표는 단순합니다. 팀의 암묵적 품질 기준을 문서로 꺼내고, 그것을 에이전트가 매번 같은 순서로 적용하게 만드는 것입니다.
코드 리뷰 Skill이 특히 중요한 이유
문서 작성 Skill은 결과물의 스타일을 드러내고, 리서치 Skill은 조사 절차를 드러냅니다. 코드 리뷰 Skill은 그보다 더 직접적입니다. 이 Skill을 열어 보면 팀이 무엇을 두려워하는지 바로 보입니다. 인증 누락을 가장 크게 보는지, 성능보다 유지보수성을 우선하는지, 테스트가 없으면 무조건 막는지, 아니면 작은 위험은 빠르게 통과시키는지까지 다 드러납니다.
좋은 코드 리뷰 Skill은 코드에 대한 의견을 늘어놓지 않습니다. 먼저 변경의 의도를 파악하고, 테스트를 보고, 그다음 구현을 읽고, 마지막에 승인 판단을 내립니다. 이런 순서가 중요한 이유는 리뷰가 감상문이 아니라 검증 절차이기 때문입니다.2
또 하나 기억할 점이 있습니다. 코드 리뷰 Skill의 기본 모드는 가능하면 읽기 전용이어야 합니다. 리뷰 단계에서 자동 수정까지 섞어 버리면, 피드백과 변경이 한 덩어리가 되어 검증 책임이 흐려집니다. 리뷰는 문제를 찾고 근거를 제시하는 일이고, 수정은 별도 Skill이나 별도 단계로 분리하는 편이 안전합니다.3
이번 프로젝트의 목표와 범위
이번에 만들 Skill은 다음 일을 하도록 설계합니다.
프로젝트 컨벤션을 기준으로 PR이나 커밋 diff를 읽는다.
보안, 성능, 유지보수성, 테스트 누락, 회귀 위험을 우선순위에 따라 점검한다.
모든 코멘트를 심각도와 근거와 수정 제안이 있는 형태로 출력한다.
마지막에 PR 요약과 승인 전 확인 항목을 만든다.
반대로 이 Skill은 하지 않는 일도 분명해야 합니다. 예를 들어 포매터가 할 일을 리뷰 코멘트로 반복하지 않고, 자동 수정도 기본 모드에서는 하지 않습니다. Skill의 설명은 "무엇을 하는가"만큼 "무엇을 하지 않는가"까지 써야 제대로 활성화되고, 다른 Skill과 충돌도 줄어듭니다.4
1단계: 프로젝트 컨벤션과 리뷰 우선순위를 수집한다
코드 리뷰 Skill의 품질은 화려한 문장보다 입력 자료의 정확도에서 갈립니다. 먼저 팀의 기준을 수집해야 합니다. 실무에서는 대개 다음 네 곳에서 규칙이 나옵니다.
CLAUDE.md,rules/, 아키텍처 문서 같은 사람이 쓴 운영 규칙ESLint, Prettier, TypeScript 설정, 테스트 설정 같은 도구 규칙
이미 머지된 좋은 PR과 시니어 리뷰 코멘트 같은 실제 사례
장애 회고, 보안 이슈, 성능 병목 기록 같은 실패 이력
여기서 중요한 것은 모든 규칙을 다 넣는 것이 아닙니다. 머지 판단에 영향을 주는 규칙부터 골라야 합니다. 예를 들어 "세미콜론을 쓴다"보다 "공개 API 변경 시 회귀 테스트가 필요하다"가 훨씬 중요합니다. 프로젝트 전역 문맥은 CLAUDE.md 같은 파일에 두고, 코드 리뷰 Skill은 그 위에 "리뷰할 때 무엇을 어떤 순서로 볼지"를 얹는 방식이 가장 관리하기 쉽습니다.5
저는 이 단계에서 규칙을 세 층으로 나누는 방식을 추천합니다.
머지를 막는 규칙: 인증·인가 누락, 데이터 손상 가능성, 중요한 테스트 부재
가능하면 수정해야 하는 규칙: 성능 저하, 중복 증가, 구조 악화
참고 또는 제안 규칙: 이름 개선, 작은 단순화, 코멘트 보강
이 구분이 없으면 에이전트는 모든 문제를 같은 무게로 말합니다. 그러면 작성자는 "이게 진짜 막히는 문제인가, 그냥 취향인가?"를 구분하지 못하고, 리뷰는 금방 피로해집니다.
2단계: Skill 폴더 구조를 설계한다
코드 리뷰 Skill은 처음부터 모든 언어와 프레임워크 규칙을 SKILL.md에 밀어 넣으면 금방 무거워집니다. 핵심 워크플로만 본문에 두고, 언어별·프레임워크별 기준은 references/로 분리하는 편이 좋습니다. 이런 점진적 로딩 구조가 있어야 평소에는 가볍고, 필요할 때만 깊어질 수 있습니다.4
예를 들면 이런 구조가 실용적입니다.
project-code-review/
├── SKILL.md
├── references/
│ ├── project-conventions.md
│ ├── security-checklist.md
│ ├── performance-checklist.md
│ ├── test-policy.md
│ └── react-typescript-review.md
├── assets/
│ ├── review-comment-template.md
│ └── pr-summary-template.md
└── scripts/
├── collect_diff_context.sh
└── map_test_impact.py여기서 핵심은 역할 분리입니다. SKILL.md는 관제탑입니다. 언제 이 Skill을 쓸지, 어떤 순서로 검토할지, 어떤 형식으로 출력할지를 적습니다. 긴 기준표와 언어별 룰은 references/에 둡니다. 스크립트는 diff 수집, 변경 파일 통계, 테스트 영향 추정처럼 기계적으로 돌릴 수 있는 작업만 맡깁니다. 핵심 판단 로직을 스크립트 안에 숨기면 나중에 Skill을 읽어도 왜 그런 결론이 나왔는지 이해하기 어려워집니다.43
3단계: SKILL.md에 리뷰의 계약을 쓴다
코드 리뷰 Skill에서 가장 중요한 한 줄은 사실 본문이 아니라 description입니다. 이 한 줄이 "리뷰해 줘", "이 PR 봐 줘", "머지 전에 체크해 줘" 같은 요청을 이 Skill로 연결해 주는 라우팅 신호가 되기 때문입니다.4
다음은 실전에 바로 쓸 수 있는 축약형 예시입니다.
---
name: project-code-review
description: Use when reviewing a pull request, commit, diff, or AI-generated code before merge. Applies this repository's conventions, security rules, performance heuristics, and test requirements. Produces severity-labeled findings, regression risks, a PR summary, and an approval recommendation. Do not use for formatting-only fixes or automatic code modification.
---
You are a read-only code reviewer for this repository.
Do not edit files in review mode.
## Mission
Review changes before merge using project conventions and five review axes:
correctness, maintainability, architecture fit, security, and performance.
## Required context
1. The intent of the change: PR description, issue, or task summary.
2. The diff or changed files.
3. Project conventions from CLAUDE.md, rules/, linters, and tests.
4. Evidence of verification already run by the author.
If the diff or intended behavior is missing, stop and ask for it.
## Review order
1. Understand the purpose of the change.
2. Read tests first.
3. Review implementation file by file.
4. Classify findings by severity.
5. Produce a PR summary, risks, test gaps, and approval recommendation.
## Severity labels
- Blocking: must be fixed before merge.
- Important: should be fixed before merge unless the team explicitly accepts the risk.
- Suggestion: useful improvement, not merge-blocking.
- FYI: information only.
## Comment format
For each finding include:
- Severity
- File and line
- Observation
- Why it matters
- Suggested change
## Approval rule
Approve when the change clearly improves overall code health and does not introduce unacceptable risk.
Do not block a change only because you would have written it differently.
## Final output
1. PR summary
2. Findings by severity
3. Test and regression gaps
4. Approval recommendation
5. Pre-merge checklist이 예시에서 중요한 포인트는 세 가지입니다. 첫째, 이 Skill은 읽기 전용 리뷰라는 점을 초반에 못 박습니다. 둘째, 테스트를 먼저 보게 합니다. 셋째, 승인 기준을 "내 취향"이 아니라 "코드베이스 전체 건강"으로 둡니다. 이런 기준이 있어야 리뷰가 까다롭되 고집스럽지 않게 됩니다.2
4단계: 보안·성능·유지보수성 체크리스트를 만든다
리뷰는 결국 무엇을 볼지 정하는 일입니다. 저는 코드 리뷰 Skill의 핵심 축을 다섯 가지로 두는 구성이 가장 안정적이라고 봅니다. 정확성, 유지보수성, 아키텍처 적합성, 보안, 성능입니다.2 이번 장의 요구사항에 맞춰 특히 보안, 성능, 유지보수성 축을 조금 더 구체화해 보겠습니다.
보안 체크리스트
보안은 "보안 팀이 나중에 보겠지"라고 미루기 쉬운 영역이지만, 리뷰 Skill에서는 가장 먼저 질문해야 하는 축입니다. 최소한 다음 항목은 포함해야 합니다.
사용자 입력 검증과 정제 여부
인증과 인가 확인 누락 여부
비밀값, 토큰, 키, 내부 URL의 하드코딩 여부
SQL 문자열 결합, 출력 인코딩 누락, 외부 데이터 신뢰 같은 경계 문제
외부 API나 로그, 설정 파일 등 비신뢰 데이터를 그대로 로직에 쓰는지 여부
여기서 요령은 "취약점 이름 백과사전"을 길게 나열하지 않는 것입니다. 팀이 실제로 자주 밟는 지뢰를 우선순위로 적어야 합니다. 예를 들어 SaaS 백엔드 팀이라면 권한 체크와 감사 로그 누락이 중요할 수 있고, 프론트엔드 팀이라면 사용자 입력 렌더링과 토큰 노출이 더 중요할 수 있습니다.
성능 체크리스트
성능 리뷰는 최적화 집착이 아니라 병목 예방이어야 합니다. 그래서 미세한 취향보다 명백한 비용 구조를 먼저 봅니다.
N+1 쿼리나 반복 네트워크 호출
페이지네이션 없는 대량 조회
UI의 불필요한 재렌더링
핫패스에서 큰 객체 생성이나 중복 계산
동기 I/O, 과도한 직렬 처리, 캐시 누락
성능 코멘트는 반드시 "느릴 수 있다"에서 끝나면 안 됩니다. 어떤 경로에서 비용이 커지는지, 대략 어떤 조건에서 문제가 터지는지, 측정이 필요한지까지 적어야 합니다. 그래야 작성자가 바로 행동할 수 있습니다.
유지보수성 체크리스트
유지보수성은 가장 흔하지만 가장 애매하게 다뤄지는 축입니다. 그래서 체크리스트를 명시적으로 적는 편이 좋습니다.
이름이 역할을 설명하는가
제어 흐름이 지나치게 꼬여 있지 않은가
중복이 늘어나고 있지는 않은가
추상화가 실제 필요 이상으로 앞서가고 있지는 않은가
죽은 코드, 호환성 찌꺼기, 임시 코드가 남아 있지는 않은가
이 축에서는 "더 예쁘게"보다 "다음 사람이 덜 힘들게"를 기준으로 말해야 합니다. 예를 들어 "이 함수가 마음에 안 든다"보다 "이 분기 구조는 다음 버그 수정 때 경로를 놓치기 쉽다"가 좋은 리뷰입니다.
5단계: 테스트 누락과 회귀 위험을 찾는 절차를 넣는다
좋은 코드 리뷰 Skill은 구현보다 먼저 테스트를 읽습니다. 테스트는 작성자의 의도를 가장 압축해서 보여 주기 때문입니다.2 버그 수정이라면 회귀 테스트가 있는지, 새 기능이라면 핵심 시나리오와 경계값이 있는지, 리팩터링이라면 기존 동작 보존을 확인하는 검증이 있는지를 먼저 봐야 합니다.
테스트 절차는 다음처럼 고정해 두면 좋습니다.
변경 목적을 한 문장으로 요약한다.
그 목적이 테스트 이름이나 시나리오에 반영되어 있는지 본다.
happy path뿐 아니라 실패 경로와 경계값이 있는지 확인한다.
버그 수정이면 같은 버그를 다시 잡아낼 회귀 테스트가 있는지 확인한다.
테스트가 없거나 약하면, 어느 동작이 검증되지 않았는지 구체적으로 적는다.
이때 변경 파일만 보고 끝내면 위험합니다. 코드 리뷰 Skill은 가능하면 "이 변경이 건드린 동작에 대응하는 테스트가 무엇인지"까지 연결해 주어야 합니다. 이를 위해 map_test_impact.py 같은 작은 스크립트를 둘 수 있습니다. 변경된 파일 목록을 받아 관련 테스트 파일 후보를 뽑아 주는 정도면 충분합니다. 이렇게 기계적으로 계산 가능한 부분만 스크립트에 맡기면 판단과 자동화의 경계가 깔끔해집니다.3
또 하나 유용한 규칙이 있습니다. 리뷰에서 빠진 파일도 반드시 보고하게 하는 것입니다. 바이너리 파일, 생성 파일, 너무 큰 diff, 외부 서브모듈처럼 제대로 검토하지 못한 대상은 "없었던 것처럼" 넘어가면 안 됩니다. 검토에서 빠졌다면 빠졌다고 적어야 리뷰의 완전성을 알 수 있습니다.3
6단계: 리뷰 코멘트의 톤과 형식을 설계한다
코드 리뷰 Skill이 의외로 많이 실패하는 지점이 바로 말투입니다. 맞는 말을 했는데도 팀이 싫어하는 리뷰가 있습니다. 반대로 날카로운 지적이어도 잘 읽히는 리뷰가 있습니다. 차이는 대개 형식과 톤에서 납니다.
제가 권하는 형식은 아주 단순합니다. 심각도 → 근거 → 영향 → 수정 제안입니다. 여기에 파일과 라인을 붙이면 됩니다. 긴 문장으로 훈계하지 말고, 바로 행동 가능한 단위로 잘라 줘야 합니다.
예를 들면 이런 식입니다.
[Blocking] src/auth/session.ts:84
권한 체크 없이 관리자용 업데이트 경로가 열려 있습니다.
현재 구현이면 로그인만 된 사용자가 다른 조직의 데이터를 수정할 가능성이 있습니다.
조직 소유권 검증을 먼저 수행하고, 이 경로를 검증하는 회귀 테스트를 추가해 주세요.[Important] src/dashboard/useItems.ts:52
리스트 렌더마다 필터 계산이 다시 실행되고 있습니다.
아이템 수가 늘어나면 스크롤 지연으로 이어질 수 있습니다.
입력이 바뀔 때만 계산되도록 메모이제이션하거나 서버 측 필터링으로 옮기는 방안을 검토해 주세요.[Suggestion] src/utils/format.ts:19
`formatDisplayValue`가 날짜, 통화, 퍼센트 포맷을 모두 처리하고 있어 역할이 넓어졌습니다.
지금은 동작하지만 다음 요구사항이 추가되면 조건 분기가 빠르게 커질 수 있습니다.
포맷터를 용도별 함수로 분리하면 테스트도 더 명확해질 것 같습니다.여기서 중요한 것은 명령조를 줄이고, 근거 중심으로 말하는 것입니다. 훌륭한 리뷰 Skill은 "이렇게 고쳐라"라고 소리치기보다 "현재 구조에서는 이런 위험이 보이고, 이런 수정이 현실적이다"라고 말합니다. 심각도 분류를 두고, 질문과 제안을 섞는 협업형 톤을 쓰면 리뷰 잡음이 훨씬 줄어듭니다.6
그리고 한 가지 더. 확신이 낮은 지적은 억지로 단정하지 않는 편이 낫습니다. 고신뢰 이슈만 강하게 말하고, 애매한 부분은 확인 질문이나 FYI로 낮추면 리뷰 품질이 안정됩니다. 자동 리뷰가 시끄러워지는 가장 흔한 이유는 사소하거나 불확실한 지적을 너무 자신 있게 말하기 때문입니다.7
7단계: PR 요약과 승인 전 확인 항목을 출력하게 만든다
리뷰 코멘트만 잔뜩 있으면 작성자는 숲을 잃고 나무만 봅니다. 그래서 코드 리뷰 Skill의 마지막 출력은 반드시 PR 요약이어야 합니다. 이 요약은 팀장, 리뷰어, 작성자가 모두 빠르게 상황을 이해할 수 있게 만드는 압축본입니다.
추천하는 형식은 다음과 같습니다.
## PR 요약
- 무엇이 바뀌었는가
- 왜 바뀌었는가
- 가장 위험한 변경 지점은 어디인가
## 주요 발견 사항
### Blocking
- ...
### Important
- ...
### Suggestion
- ...
## 테스트 및 회귀 위험
- 존재하는 테스트
- 빠진 테스트
- 수동 확인이 필요한 항목
## 승인 판단
- Approve | Changes Requested | Needs Clarification
- 한 문장 근거
## 머지 전 확인 항목
- 필요한 테스트 실행 여부
- 마이그레이션/환경 변수/플래그 확인 여부
- UI 변경 시 스크린샷 또는 동작 검증 여부
- 보안 민감 경로 재확인 여부여기서 "승인 판단"은 사실상 팀의 철학이 드러나는 자리입니다. 저는 다음 규칙을 Skill에 넣는 것을 추천합니다. 코드가 완벽해서 승인하는 것이 아니라, 현재 코드베이스를 더 건강하게 만들고 위험이 통제 가능하면 승인한다. 반대로, 내 취향과 다르다는 이유로 막지는 않습니다.2
이 한 줄이 있으면 리뷰 Skill이 지나치게 교조적으로 흐르는 것을 막을 수 있습니다.
완성된 Skill 패키지를 어떻게 운영할 것인가
이제 Skill은 만들어졌지만, 진짜 중요한 것은 운영입니다. 처음부터 전 언어, 전 프레임워크, 전 규칙을 넣으려고 하면 실패합니다. 먼저 현재 팀이 가장 자주 리뷰하는 경로 하나를 잡으세요. 예를 들어 React + TypeScript 프론트엔드 PR 리뷰, 혹은 Node API PR 리뷰처럼 좁게 시작하는 편이 좋습니다. 그다음 실제 PR 10개 정도에 돌려 보면서, 다음 질문을 기준으로 조정합니다.
막아야 할 문제를 실제로 잘 잡는가
사소한 지적이 너무 많지 않은가
팀 컨벤션을 제대로 반영하는가
테스트 누락을 얼마나 구체적으로 설명하는가
작성자가 바로 수정할 수 있을 정도로 제안이 실용적인가
리포지토리가 커지면 한 개의 거대한 리뷰 Skill보다, 상위 project-code-review Skill 하나와 보안·프레임워크 참고 자료 몇 개를 조합하는 편이 낫습니다. 더 커지면 보안 전용, 성능 전용, 테스트 전용 하위 리뷰어로 분리하는 방법도 있습니다. 다만 출발점은 언제나 하나의 명확한 워크플로여야 합니다. "하나의 Skill, 하나의 리뷰 절차" 원칙을 지키면 라우팅도 유지보수도 쉬워집니다.4
이 장의 최종 정리
코드 리뷰 Skill은 팀의 품질 기준을 가장 노골적으로 드러내는 Skill입니다. 그래서 잘 만들면 신입도 시니어와 비슷한 기준으로 리뷰할 수 있고, AI가 작성한 코드도 같은 잣대로 검증할 수 있습니다. 반대로 대충 만들면 "리뷰해 줘"라는 말에 매번 다른 잣대를 들이미는 또 하나의 프롬프트에 불과해집니다.
이번 장에서 만든 구조를 한 문장으로 요약하면 이렇습니다. 절차는 고정하고, 판단의 근거는 프로젝트 문맥에 묶고, 출력은 바로 행동할 수 있게 만든다.
이제 다음 장에서는 한 단계 더 나아가, 이런 Skill이 실제 외부 도구와 연결될 때 어떤 승인 단계와 대체 경로, 운영 로그 구조가 필요한지 살펴보겠습니다.
참고
2code-review-and-quality SKILL.md
4Skill Design Guide Agent Layer
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.