AI 시대 코드 리뷰 → Spec Review로 올리면 팀에 생기는 변화: 체크리스트 5가지

Posted on by

Quick Answer

AI가 코드를 더 빨리 쓰는 시대에는, 사람 리뷰어가 계속 diff만 보고 있으면 금방 지친다. 그래서 리뷰의 무게중심을 코드가 예쁘냐에서 무슨 문제를 풀기로 했고 acceptance criteria를 충족했냐로 올리는 Spec Review가 필요하다. 쉽게 말하면, 사람은 점점 코드 문장교정보다 문제정의, 범위, 비목표, 검증 기준을 보는 쪽으로 올라가야 한다.

이 글이 필요한 사람

  • AI 코딩 도구를 팀에 붙였더니 PR 수는 늘었는데 리뷰 피로가 더 커진 팀
  • Copilot coding agent, Claude Code, Codex 같은 도구를 쓰는데 사람 리뷰어가 어디를 봐야 할지 헷갈리는 팀
  • “코드 리뷰는 하는데 왜 자꾸 범위가 틀어지지?”를 겪는 리드
  • acceptance criteria, spec, plan, tasks를 실제 운영 루프로 묶고 싶은 사람

지금 결론

  1. AI가 코드를 더 많이 만들수록, 사람 리뷰어가 코드보다 계약을 봐야 효율이 산다.
  2. Spec Review는 코드 리뷰를 없애는 게 아니라, 코드 리뷰 전에 문제정의 리뷰를 하나 더 올리는 것에 가깝다.
  3. 실제 운영에서는 requirements -> design -> tasks -> implementation -> review 순서를 만들면 PR이 덜 시끄럽고, 리뷰 코멘트도 덜 감정적이 된다.

코드를 나중에 보고 스펙을 나중에 떠올리는 팀보다, 스펙을 먼저 고정하고 코드를 나중에 확인하는 팀이 AI 시대엔 훨씬 덜 피곤하다.

예전엔 코드 리뷰에서 제일 중요한 질문이 “이 구현 괜찮나?”였다. 근데 AI 코딩 도구를 붙이고 나면 질문이 살짝 바뀐다. 이제는 “이 코드가 맞냐?”보다 먼저 “우리가 원래 뭘 만들기로 했더라?”가 더 자주 터진다.

그게 왜 문제냐면, AI는 코드를 안 쓰는 게 아니라 너무 잘 써서 문제이기 때문이다. 코드가 빨리 나오니까 사람은 오히려 더 많은 diff를 읽게 되고, 그 와중에 중요한 버그는 문법이 아니라 범위 오해, acceptance criteria 누락, 비목표 침범에서 터진다.

그래서 요즘은 코드 리뷰를 완전히 버리자는 얘기가 아니라, 사람의 시선을 한 단계 위로 올려서 Spec Review를 같이 해야 한다는 쪽이 더 현실적이다.

왜 갑자기 Spec Review 얘기가 나오냐

이건 유행어 장난이 아니다. 도구 회사들도 이미 비슷한 방향으로 가고 있다.

Kiro 공식 Specs 문서는 아예 스펙을

  • requirements.md
  • design.md
  • tasks.md

세 파일 구조로 나누고, requirements.md 안에 user stories와 acceptance criteria를 먼저 잡는 흐름을 기본으로 둔다. 즉 “바로 구현”이 아니라 “먼저 정리, 그 다음 구현”이 제품 흐름에 들어가 있다는 뜻이다.

GitHub 블로그의 agentic primitives와 context engineering 글도 비슷하다. 여기서는 .spec.md를 구현용 블루프린트로 보고, .prompt.md 워크플로 안에 human validation gate를 넣는 구조를 보여준다. 한마디로 “에이전트가 일하게 하되, 사람은 중요한 체크포인트에서 승인하라”는 말이다.

GitHub 공식 Copilot 문서의 technical debt tutorial도 결은 같다. 큰 리팩터링 작업일수록 먼저 이슈를 구체적으로 쓰고, 그걸 기반으로 coding agent가 draft PR을 만들고, 마지막엔 사람이 리뷰와 승인을 맡는 흐름을 권한다.

즉 시장 전체가 이미 이렇게 말하고 있는 셈이다.

  • AI에게 코드는 맡겨도 된다
  • 하지만 사람은 리뷰 위치를 올려야 한다
  • 그냥 diff만 보지 말고 spec과 validation gate를 같이 보라

Code Review와 Spec Review는 뭐가 다르냐

말로만 들으면 되게 있어 보이는데, 실제 차이는 꽤 소박하다.

기존 코드 리뷰

보통 이런 질문이 중심이다.

  • 이 함수 이름 적절한가
  • 예외처리 빠진 데 없나
  • 테스트 케이스 괜찮나
  • 쿼리 성능 문제 없나

당연히 필요하다. 이건 계속 필요하다. 근데 AI가 코드를 많이 찍는 순간, 이 질문들만으로는 부족해진다.

Spec Review

Spec Review는 질문이 다르다.

  • 우리가 풀기로 한 문제를 정확히 잡았나
  • In Scope / Out of Scope가 분리돼 있나
  • acceptance criteria가 테스트 가능한 문장인가
  • 실패 흐름이 정의돼 있나
  • 구현 전에 빠진 전제가 없는가

즉 코드를 보기 전에 무엇을 맞다고 볼지를 먼저 리뷰하는 거다.

이 차이가 크다. 코드 리뷰는 나온 결과물을 보고 평가하는 느낌이라면, Spec Review는 아예 출발선의 트랙이 맞는지 확인하는 느낌에 더 가깝다.

내가 체감한 진짜 변화: 사람이 보는 위치가 올라간다

이건 이론만 읽고 하는 말이 아니다. 우리 볼트에서도 비슷한 흐름을 이미 쓰고 있다.

prototype-architect.md는 from-sdd 모드에서 acceptance criteria나 Given-When-Then을 태스크별 완료 기준, 테스트 포인트, 실패 흐름에 직접 매핑하라고 적어둔다. 그리고 prototype-reviewer.md는 구현이 설계와 맞는지, 인터페이스가 설계대로인지, 실행 가능성이 있는지 순서대로 보게 만든다.

이 구조를 실제로 돌려보면 체감이 딱 온다.

  • 리뷰가 “이거 왜 이렇게 썼어?”보다 “이건 애초에 스펙에 없는데?”로 이동한다
  • 사람끼리 덜 싸운다
  • 구현 품질보다 범위 오해를 먼저 잡는다
  • 리뷰어가 한 줄 한 줄 스타일 지적하는 시간이 줄어든다

쉽게 말하면, 리뷰어가 문장교정자에서 편집장으로 올라가는 느낌이다. 이게 진짜 중요하다.

표로 보면 더 쉽다

항목 코드 리뷰 중심 팀 Spec Review 포함 팀
리뷰 시작점 PR 열리고 나서 구현 전 requirements/design부터
사람의 주 질문 구현이 괜찮나 구현 대상 자체가 맞나
AI가 늘릴수록 생기는 문제 diff 읽기 과부하 초기 스펙 품질이 병목
PR 코멘트 성격 스타일, 세부 구현, 예외처리 범위, 계약, acceptance criteria
실패 원인 코드 실수 문제정의/범위 오해 + 코드 실수
사람의 역할 세부 리뷰어 승인자, 계약 검증자

Spec Review를 넣는다고 코드 리뷰가 사라지는 건 아니다. 다만 순서가 바뀐다.

  1. 먼저 spec을 보고
  2. 그다음 implementation plan을 보고
  3. 마지막에 code diff를 본다

이 순서가 되면 리뷰가 훨씬 덜 흐트러진다.

체크리스트 5가지: Spec Review로 올리면 팀에 실제로 생기는 변화

여기부터가 핵심이다. 이건 그냥 멋진 개념이 아니라, 팀 운영에 실제로 생기는 변화다.

1. 리뷰 코멘트가 “취향”에서 “계약”으로 바뀐다

보통 지치는 리뷰는 이런 식이다.

  • 이 변수명 별로네요
  • 이 함수 분리하죠
  • 이거 제가 선호하는 패턴은 아닌데요

물론 다 의미는 있다. 근데 AI가 코드를 빠르게 찍기 시작하면 이런 코멘트가 엄청 늘어난다. 리뷰어도 지치고 작성자도 지친다.

Spec Review를 먼저 하면 코멘트 축이 바뀐다.

  • 로그인 실패 3회 제한이 acceptance criteria에 없는데요
  • 비목표에 “관리자 권한 분리 제외”라고 돼 있는데 여기서 범위가 늘었네요
  • 실패 흐름이 정의되지 않아서 테스트 기준이 없어요

이렇게 되면 리뷰가 덜 취향 싸움이 된다. 훨씬 덜 감정적이고, 더 재현 가능하다.

2. PR이 커져도 검토 포인트가 덜 흔들린다

GitHub Copilot coding agent 같은 흐름은 큰 리팩터링이나 다중 파일 변경에 특히 강하다. 문제는 그다음이다. PR이 30파일, 50파일로 커지면 사람은 읽다가 정신이 풀린다.

이때 Spec Review가 없으면 리뷰어는 그냥 diff 바다에서 수영하다가 체력만 소모한다. 반대로 spec이 있으면 기준점이 생긴다.

  • 이 PR은 원래 무엇을 바꾸는 작업인가
  • 어떤 경로는 의도적으로 안 건드리기로 했나
  • 성공 조건은 뭐였나

리뷰어가 전부 읽지 않아도, 무엇을 반드시 확인해야 하는지를 먼저 안다. 그 차이가 진짜 크다.

3. AI가 똑똑할수록 더 필요한 인간 역할이 생긴다

재밌는 역설인데, AI가 좋아질수록 사람이 할 일이 사라지는 게 아니라 위치가 바뀐다.

사람이 계속 해야 하는 건 이런 쪽이다.

  • 문제정의
  • 품질 기준 고정
  • 비목표 선언
  • 리스크 승인
  • 트레이드오프 결정

이건 모델이 코드를 잘 짠다고 자동 해결되지 않는다. 오히려 AI가 알아서 많이 해주면, 사람이 이런 걸 더 분명하게 정해야 전체가 덜 흔들린다.

그래서 나는 요즘 리뷰어의 역할을 이렇게 본다.

  • 예전: “잘 짰는지 보는 사람”
  • 지금: “무엇을 잘 짠 걸로 볼지 정하는 사람”

이게 Spec Review가 필요한 이유다.

4. 테스트가 덜 장식품이 된다

acceptance criteria가 없는 팀에서 테스트는 가끔 “있으면 좋은 것”이 된다. 근데 acceptance criteria가 있으면 테스트는 갑자기 의미가 또렷해진다.

왜냐면 이렇게 연결되기 때문이다.

  • 요구사항
  • acceptance criteria
  • tasks
  • tests

Kiro 문서가 specs를 requirements -> design -> tasks로 자르는 이유도 여기 있다. 구현 태스크가 그냥 TODO 목록이 아니라, 무슨 조건을 만족해야 끝인지와 연결돼야 하기 때문이다.

우리 로컬 prototype architect 규칙도 같은 방향이다. acceptance criteria를 완료 기준, 테스트 포인트, 실패 흐름에 직접 연결하라고 박아둔 이유가 바로 그거다.

테스트가 “혹시나 돌리는 것”이 아니라 스펙 계약을 증명하는 문서가 되기 시작한다.

5. 팀장이 덜 피곤해진다

이게 은근 제일 중요하다.

리드나 팀장이 제일 피곤한 순간은

  • 다들 열심히 했는데
  • 뭔가 많이 만들었는데
  • 마지막에 “근데 우리가 원래 원한 건 이게 아니었는데?”가 나오는 순간

이다.

Spec Review를 넣으면 이 확률이 꽤 줄어든다. 왜냐면 구현 전에 최소한 한 번은

  • 범위
  • 비목표
  • 승인 기준
  • 리스크

를 말로 고정하고 들어가기 때문이다.

솔직히 이건 기능 하나 더 붙이는 것보다 운영비 절감 효과가 크다. 팀장이 덜 지치면 팀도 덜 피곤하다. 리더십도 결국 배터리 싸움이거든.

그럼 실제로 어떻게 굴리면 되냐

거창하게 프로세스 혁명까지 갈 필요는 없다. 처음엔 아래 정도면 충분하다.

최소 Spec Review 루프

  1. 이슈나 노트에 문제정의를 쓴다
  2. In Scope / Out of Scope를 나눈다
  3. acceptance criteria를 3~7개 적는다
  4. 구현 전 사람이 한 번 읽고 승인한다
  5. AI에게 구현을 맡긴다
  6. PR 리뷰에서는 spec 대비 어긋난 부분을 먼저 본다

이 6단계만 들어가도 리뷰 피로가 꽤 달라진다.

acceptance criteria를 쓸 때 좋은 문장

  • 사용자는 저장 후 새로고침해도 상태를 유지할 수 있어야 한다
  • 에러 발생 시 사용자에게 재시도 방법이 보여야 한다
  • 관리자 권한 없는 사용자는 설정 변경 API에 접근할 수 없어야 한다
  • 기존 CSV 업로드 기능은 이번 작업에서 변경되지 않아야 한다

좋은 acceptance criteria의 핵심은 하나다. 테스트 가능한 문장이어야 한다.

반대로 안 좋은 건 이런 거다.

  • UX가 좋아야 한다
  • 보안이 강화돼야 한다
  • 더 안정적이어야 한다

이건 말은 멋있는데 리뷰에 전혀 도움이 안 된다. 너무 추상적이다.

Spec Review를 도입할 때 많이 하는 실수 TOP 5

1. 문서만 늘리고 승인 지점은 안 만드는 실수

스펙 문서가 있어도, 사람이 구현 전에 한 번 승인하지 않으면 반쪽이다. 문서는 있는데 validation gate가 없으면 결국 다시 PR에서 싸운다.

2. acceptance criteria를 너무 추상적으로 쓰는 실수

“좋아야 한다”, “개선돼야 한다”, “편해야 한다”는 리뷰 기준이 아니다. 테스트 가능한 문장으로 내려와야 한다.

3. 코드 리뷰를 없애려는 실수

Spec Review는 코드 리뷰 대체재가 아니다. 코드 리뷰는 그대로 필요하다.

  • 보안
  • 에러 처리
  • 의존성 정합성
  • 실행 가능성

이런 건 여전히 봐야 한다. 다만 사람의 첫 질문이 달라지는 거다.

4. 비목표를 안 적는 실수

AI는 열심히 해주려고 하다가 종종 범위를 넓힌다. 그래서 무엇을 하지 않을지를 적는 게 진짜 중요하다.

비목표가 없으면 PR이 조용히 커진다. 나중에 보면 “이걸 왜 여기서 바꿨지?”가 튀어나온다.

5. spec 작성자를 따로, 리뷰어를 따로, 구현자를 따로 두면서 연결 문장을 안 맞추는 실수

문서가 많아질수록 연결 문장이 중요하다.

  • 이 요구사항은 어느 태스크로 갔는가
  • 이 태스크는 어느 테스트로 검증되는가
  • 이 PR은 어느 acceptance criteria를 닫는가

이 연결선이 안 보이면, 문서만 늘고 실무는 더 복잡해진다.

내 추천 운영 방식

지금 바로 팀에 붙이려면 이 조합이 제일 현실적이다.

작은 팀

  • issue 또는 markdown spec 하나
  • acceptance criteria 3~5개
  • 구현 전 10분 Spec Review
  • 구현 후 10분 Code Review

중간 팀

  • requirements.md, design.md, tasks.md 분리
  • 구현 전 reviewer 1명 승인
  • 구현 중 AI/agent 활용
  • PR 리뷰는 spec 대비 이탈 + 보안/실행 가능성 위주

멀티에이전트/자동화 팀

  • spec을 source of truth로 삼기
  • plan/tasks를 자동 생성하되 human gate 유지
  • reviewer는 diff보다 계약 위반 탐지에 집중
  • rollout 전에 비목표/실패 흐름 점검

이 정도면 충분하다. 중요한 건 도구 이름이 아니라, 사람 리뷰어의 시선 위치를 올리는 것이다.

언제는 그냥 코드 리뷰로 끝내도 된다

Spec Review가 만능은 아니다. 괜히 모든 작업에 문서를 붙이면 팀이 갑자기 개발팀이 아니라 결재팀이 된다.

아래 같은 경우는 그냥 코드 리뷰 중심으로 가도 된다.

  • CSS 한두 줄 수정
  • 로그 문구 변경
  • 단순 버그픽스인데 범위와 영향이 아주 명확한 경우
  • 이미 acceptance criteria가 제품 요구사항에 충분히 박혀 있는 반복 작업

반대로 아래는 Spec Review를 붙일 가치가 크다.

  • 여러 파일이 같이 바뀌는 기능
  • PM/디자이너/엔지니어 해석이 갈릴 수 있는 요구사항
  • 실패 흐름이 중요한 작업
  • “이건 이번 v1에서 안 한다”를 명확히 박아야 하는 작업

즉 기준은 간단하다. 구현 난이도보다 해석 난이도가 높으면 Spec Review가 필요하다.

FAQ

Q1. Spec Review는 PM이 하는 거 아닌가요?

반만 맞다. 문제정의는 PM도 깊게 들어오지만, 기술적 비목표, 실패 흐름, 인터페이스 계약, 테스트 가능성은 엔지니어 리뷰가 꼭 필요하다. 그래서 Spec Review는 제품과 엔지니어링이 같이 보는 지점에 가깝다.

Q2. AI가 코드를 잘 짜면 코드 리뷰는 줄여도 되나요?

줄일 수는 있어도 없앨 수는 없다. Spec Review가 먼저라고 해서 보안, 에러 처리, 실행 가능성 검토가 사라지진 않는다. 다만 사람이 무슨 구현을 했나보다 무슨 계약을 만족했나를 먼저 보게 되는 거다.

Q3. acceptance criteria는 몇 개가 적당한가요?

처음엔 3~7개가 좋다. 너무 적으면 기준이 흐리고, 너무 많으면 문서가 아니라 벌칙표가 된다.

Q4. Spec Review를 도입하면 속도가 느려지지 않나요?

초반엔 약간 느려질 수 있다. 근데 PR에서 범위 싸움, 재작업, 뒤늦은 요구사항 추가가 줄면 전체 리드타임은 오히려 줄어드는 경우가 많다. 느리게 출발해서 덜 헤매는 쪽이다.

Q5. 한 줄로 요약하면 이 글의 결론은 뭔가요?

AI 시대 사람 리뷰어의 일은 코드를 많이 읽는 것이 아니라, 무엇을 맞는 구현으로 볼지 먼저 고정하는 것에 더 가까워진다. 그게 바로 Spec Review다.

다음에 읽을 글

출처

결국 AI 시대 리뷰의 핵심은 “사람이 덜 읽어도 된다”가 아니다. 오히려 사람은 더 중요한 걸 읽어야 한다. 코드 줄 수가 아니라 계약, 범위, 비목표, acceptance criteria. 한마디로 이제 리뷰어는 diff 경찰보다 문제정의 편집장에 더 가까워진다. 이걸 받아들이면 팀이 덜 지치고, 안 받아들이면 PR 탭만 점점 두꺼워진다. 진짜로.