Spec Review vs Code Review 2026 — requirements.md부터 써야 덜 깨지는 팀의 조건

Posted on by

코드는 빨리 나오는데 팀은 왜 더 자주 깨질까.

diff는 늘었는데, 왜 오히려 리뷰는 더 느려질까.

AI가 코드를 잘 써줄수록, 왜 사람은 더 헷갈릴까.

requirements.md 하나만 먼저 써도 정말 덜 깨질까.

Spec Review는 코드 리뷰를 없애는 얘기일까, 아니면 리뷰의 위치를 한 칸 올리는 얘기일까.

이런 질문이 한 번이라도 들었다면, 지금 이 글이 딱 맞다.

한 줄 결론: requirements.md는 코드를 예쁘게 쓰는 문서가 아니라, 팀이 같은 문제를 같은 방식으로 이해하게 만드는 계약서다.

AI 시대엔 코드보다 합의가 먼저 무너진다.

그래서 requirements.md부터 쓰는 팀이 생각보다 덜 깨진다.

왜 이 얘기가 2026년에 더 아프냐

예전엔 사람이 코드를 천천히 썼다.

그래서 리뷰어는 코드만 봐도 대충 의도를 읽을 수 있었다.

지금은 다르다.

AI가 초안을 금방 뽑아주니까, 구현은 빨라졌는데 문제정의가 뒤로 밀린다.

그 순간부터 팀은 이상한 방향으로 달린다.

코드 자체는 맞는데, 원래 만들기로 한 건 다른 경우가 많아진다.

이건 기능이 커서 생기는 문제가 아니다.

작은 변경도 합의가 없으면 충분히 깨진다.

Google의 코드리뷰 가이드는 팀 전체의 흐름과 속도를 중요하게 보고, 큰 변경은 더 잘게 쪼개라고 말한다. Google Engineering Practices – Code Review와 Small CLs를 보면, 리뷰는 빨라야 하고 변화는 작을수록 낫다.

GitHub도 PR 리뷰에서 파일 단위로 보고, 변경 목적은 이슈나 토론 맥락을 같이 보라고 안내한다. GitHub pull request review docs는 결국 같은 얘기를 한다. 먼저 맥락, 그다음 diff다.

즉 2026년의 핵심은 이거다.

코드리뷰만 잘한다고 팀이 안 깨지는 게 아니다.

리뷰 전에 문서와 합의 구조가 있어야 한다.

Spec Review와 Code Review는 뭐가 다르냐

둘은 비슷해 보이는데 보는 대상이 완전히 다르다.

Spec Review는 무슨 문제를 풀 건지를 검토한다.

Code Review는 그걸 어떻게 구현했는지를 검토한다.

Spec Review가 없으면, code review는 종종 구현 디테일만 만지다가 끝난다.

Code Review가 없으면, spec이 좋아도 구현이 새는 걸 못 잡는다.

둘 중 하나만 고르는 문제가 아니다.

순서의 문제다.

항목 Spec Review Code Review
리뷰 시점 구현 전 구현 후
핵심 질문 이걸 왜 만들지, 범위는 어디까지지 이 구현이 맞나, 안전한가
주 대상 requirements.md, spec, acceptance criteria diff, 테스트, 구현 상세
잘 잡는 문제 범위 오해, 비목표 침범, 누락된 예외 버그, 성능, 스타일, 테스트 누락
잘 놓치는 문제 구현의 미세한 결함 문제정의 자체의 오류
팀이 얻는 것 합의, 범위 잠금, 기대치 정렬 correctness, maintainability, regression 방지
AI와의 궁합 아주 좋음. 초안을 빨리 만들고 사람은 방향을 본다 여전히 필요함. 다만 diff만 보면 과부하가 온다

여기서 중요한 건 한 가지다.

Spec Review는 코드리뷰를 대체하는 게 아니다.

코드리뷰가 보기 전에, 문제정의가 맞는지 먼저 보는 거다.

공식 문서가 공통으로 말하는 것

이건 그냥 감이 아니라 실제 도구 문서 흐름과도 맞는다.

Atlassian의 Product requirements template은 요구사항을 쓸 때 assumptions, user stories, UX design, scoping, out of scope를 분리해서 적으라고 안내한다.

즉 요구사항 문서는 “만들자”가 아니라, “무엇을 만들고 무엇을 안 만들지”를 적는 자리다.

GitHub rulesets 문서는 브랜치와 태그에 대해 pull request requirement, status checks, force push 차단 같은 규칙을 걸 수 있다고 설명한다. GitHub rulesets docs

이 말은 곧, 팀 운영은 사람의 기억보다 저장소 규칙에 더 많이 기대는 쪽으로 가고 있다는 뜻이다.

Google의 코드리뷰 가이드는 또 다른 방향에서 같은 결론을 준다.

리뷰는 팀 전체 속도를 위해 빨라야 하고, 큰 변경은 잘게 나눌수록 더 잘 보인다. Speed of Code Reviews

정리하면 이렇다.

  • 요구사항은 먼저 잠가라
  • 구현은 작게 나눠라
  • 리뷰는 빠르게 돌려라
  • 책임은 문서와 규칙에 분산시켜라

이 네 개가 같이 돌아가야 덜 깨진다.

requirements.md가 필요한 순간

모든 작업에 requirements.md가 필요한 건 아니다.

오히려 너무 남발하면 문서가 일을 먹어치운다.

하지만 아래 상황이라면 requirements.md가 거의 필수다.

1. 같은 기능 설명이 사람마다 다를 때

PM은 “알림 개선”이라고 하고, 개발자는 “푸시 재시도”라고 하고, QA는 “실패 시나리오 보강”이라고 말하는 상황.

이건 이미 문서가 필요한 상태다.

requirements.md가 없으면 각자 머릿속 화면이 달라진다.

코드는 맞게 나왔는데, 다들 다른 제품을 상상하고 있었던 거다.

2. AI가 초안을 먼저 만들기 시작할 때

AI는 구현을 빨리 뽑는다.

근데 문제정의가 안 박혀 있으면 그 빠름이 그냥 빠른 오해가 된다.

requirements.md가 있으면 AI가 먼저 묻는 질문이 바뀐다.

  • 이 기능의 목적이 뭐지
  • 어디까지가 범위지
  • 성공 조건은 뭐지
  • 제외할 건 뭐지

이 질문이 먼저 나오면, 코드가 덜 헛돌아간다.

3. 여러 사람이 같은 기능을 나눠 맡을 때

브랜치가 늘어나고, PR이 분기되고, 리뷰어가 달라지면 합의 문서는 더 중요해진다.

특히 에이전트가 들어오면 더 그렇다.

사람은 맥락을 기억하지만, 에이전트는 문서를 먹고 움직인다.

즉 requirements.md는 사람용 메모가 아니라, 사람과 에이전트가 같이 읽는 기준선이다.

4. 실패 비용이 클 때

결제, 인증, 데이터 마이그레이션, 운영 자동화, 권한 체계.

이런 건 한 번 삐끗하면 되돌리기 비싸다.

이럴수록 spec이 먼저고, code review는 그다음이다.

5. 테스트가 요구사항을 따라가야 할 때

acceptance criteria가 있으면 테스트가 덜 장식품이 된다.

무작정 “테스트도 좀 넣자”가 아니라, “이 조건이 충족됐는지 확인하자”가 된다.

그때부터 테스트는 감시카메라가 아니라 계약서 검증기가 된다.

오히려 과한 경우

requirements.md가 무조건 좋은 건 아니다.

과하면 그냥 문서 피로만 쌓인다.

1. 오타 수정

설명보다 속도가 중요하다.

이런 건 PR 설명 한 줄이면 충분한 경우가 많다.

2. 아주 작은 버그 픽스

예를 들어 null 체크 하나 추가하는 정도.

이걸 requirements.md로 풀어쓰면, 문제보다 문서가 더 커진다.

3. 운영 긴급 대응

장애 복구는 일단 복구가 먼저다.

그 다음에 정리 문서를 쓰는 편이 낫다.

4. 한 번 쓰고 끝나는 실험 코드

PoC나 버려도 되는 실험은 requirements.md보다 최소한의 기록이 더 낫다.

요약하면 이렇다.

requirements.md는 모든 일의 시작점이 아니라, 합의 비용이 커질 때 쓰는 안전장치다.

실무에서 자주 깨지는 패턴

패턴 1. 요구사항 없이 코드 리뷰부터 시작한다

이 경우 리뷰는 자꾸 스타일 싸움으로 흐른다.

문제정의가 없으니, 리뷰어는 구현 디테일을 붙잡고 늘어질 수밖에 없다.

결과는 뻔하다.

누구는 함수명이 거슬리고, 누구는 예외처리가 부족하고, 누구는 본질을 놓친다.

패턴 2. requirements.md가 너무 추상적이다

사용자가 편해진다

성능을 개선한다

안정성을 높인다

이런 말만 있으면 AI도 사람도 못 움직인다.

문서가 있어도 실행 가능한 계약이 없으면 소용이 없다.

패턴 3. requirements.md가 코드처럼 길어진다

이건 반대 방향 사고다.

요구사항 문서에 구현 디테일을 너무 많이 넣으면, 문서는 설명서가 아니라 소설이 된다.

그럼 아무도 안 읽는다.

좋은 requirements.md는 길이가 아니라 경계가 선명해야 한다.

패턴 4. acceptance criteria가 빠진다

이 패턴이 특히 위험하다.

요구사항은 있는데 끝 조건이 없다.

그러면 AI는 “대충 맞는 것 같은 코드”를 잘 만들고, 팀은 “이게 끝인가?”를 계속 묻게 된다.

패턴 5. spec과 PR이 따로 논다

문서는 A라고 했는데 구현은 B로 간다.

리뷰어는 나중에 그걸 발견하고, 작성자는 “근데 이건 필요하다고 생각해서”라고 말한다.

이때부터 피곤함이 시작된다.

내가 보는 실제 워크플로

이건 공식 문서가 아니라 현장 관찰이다.

AI 팀이 덜 깨지려면 보통 이렇게 간다.

  1. requirements.md에 문제, 목표, 비목표, 성공 기준을 적는다.
  2. 사람이 먼저 scope를 읽고 “이건 맞다/아니다”를 확정한다.
  3. AI가 design.md나 task 리스트를 바탕으로 초안을 만든다.
  4. 구현 PR이 올라오면 code review는 diff만 보지 않고 requirements와 같이 본다.
  5. 테스트와 status checks가 requirements의 acceptance criteria를 따라간다.

이 흐름의 장점은 단순하다.

사람은 계약을 보고, AI는 구현을 만든다.

역할이 안 섞여서 덜 싸운다.

GitHub 문서도 PR을 볼 때 관련 이슈, 토론, milestone 같은 맥락을 같이 보라고 한다. 결국 리뷰는 코드만 보는 행위가 아니라, 맥락을 확인하는 행위다.

Spec Review가 특히 잘 먹히는 팀

AI 코딩 에이전트를 이미 쓰는 팀

AI가 코드를 빨리 만들수록 합의가 먼저다.

기능 변경이 자주 일어나는 팀

사양이 자주 바뀌는 팀은 문서가 없으면 금방 전염된다.

리뷰어가 바쁜 팀

리뷰어가 30분짜리 대형 PR을 계속 보면 지친다.

Google이 말하는 작은 변경, 빠른 응답이 왜 중요한지 여기서 체감된다.

제품과 개발 경계가 자주 섞이는 팀

요구사항, UX, 예외처리, rollout이 한 번에 섞이면 구두 합의가 자주 깨진다.

문서를 먼저 잠그면 뒤늦은 말싸움이 줄어든다.

여러 저장소나 여러 에이전트가 얽힌 팀

작업 단위가 분산될수록 requirements.md의 가치가 커진다.

한 파일이 기준점이 되기 때문이다.

code review만으로 버티면 생기는 착시

코드 리뷰만 해도 되지 않냐는 말이 꼭 나온다.

물론 된다.

하지만 어느 순간 리뷰가 이런 식으로 변한다.

  • 방향이 맞는지 뒤늦게 발견
  • 범위가 살짝씩 커짐
  • 테스트는 뒤늦게 붙음
  • PR 코멘트가 취향 논쟁이 됨
  • 리뷰어마다 판단이 달라짐

이건 리뷰를 못해서가 아니다.

리뷰가 너무 뒤에 있기 때문이다.

그래서 Spec Review가 필요하다.

사람이 늦게 고치는 문제를, 앞에서 싸게 고치자는 거다.

requirements.md에 꼭 들어가면 좋은 것

Atlassian 템플릿 흐름을 실무형으로 바꾸면 대충 이 정도다.

  • 문제 정의
  • 목표
  • 비목표
  • 사용자 시나리오
  • 기술 제약
  • 성공 기준
  • out of scope
  • 열려 있는 질문
  • rollout 조건
  • 검증 방법

이 중에서 최소한 목표, 비목표, 성공 기준은 빠지면 안 된다.

이 셋이 없으면 문서가 방향 표지판이 아니라 그냥 안내문이 된다.

리뷰 기준을 어떻게 나눌까

실무에선 이 순서가 제일 덜 싸운다.

1. requirements.md 리뷰

여기서는 “이걸 만들 이유가 있나”를 본다.

2. design 리뷰

여기서는 “이 접근이 제약과 리스크를 견디나”를 본다.

3. code review

여기서는 “구현이 spec과 design에 맞나”를 본다.

이 순서를 뒤집으면 힘들어진다.

코드가 먼저 나오면, 사람은 자꾸 이미 나온 걸 정당화하게 된다.

그게 제일 위험하다.

FAQ

Q1. requirements.md가 PRD랑 같은 거야?

거의 같은 역할이다.

다만 requirements.md는 저장소 안에서 더 실행 가능하게 굴기 좋고, PRD보다 더 가볍게 유지할 수 있다.

Q2. Spec Review가 있으면 code review는 줄여도 돼?

아니다.

줄이는 게 아니라 역할을 바꾸는 거다.

spec은 방향을 잡고, code review는 구현 품질을 잡는다.

Q3. 누가 requirements.md를 써야 해?

정답은 하나가 아니다.

PM이 초안을 쓰고, 개발 리드가 경계와 제약을 더하고, AI가 초안을 정리하는 방식이 실전적이다.

중요한 건 소유자가 아니라 합의가 잠기는지다.

Q4. requirements.md를 짧게 써도 되나?

그럼.

짧아도 된다.

대신 짧더라도 목표, 비목표, 성공 기준은 남겨야 한다.

Q5. 문서가 늘어나면 느려지지 않나?

초반엔 조금 느려질 수 있다.

근데 AI 시대엔 뒤늦게 고치는 비용이 더 크다.

처음에 10분 더 쓰고, 나중에 2시간 덜 싸우는 쪽이 훨씬 낫다.

관련 글

마무리

requirements.md부터 쓰는 팀은 문서를 좋아해서가 아니다.

문서가 없을 때 더 크게 깨지는 걸 알아서다.

AI가 코드를 빨리 쓸수록, 팀은 더 늦기 전에 합의를 잠가야 한다.

그러니까 순서는 이거다.

문제부터 적고.

범위를 잠그고.

비목표를 박고.

그다음 구현하자.

그 순서가 제일 덜 아프다.