google/eng-practices —
구글이 20년간 쌓아 올린 "코드리뷰 헌법"

2025년 11월 아카이브되었지만 오늘도 트렌딩 11위에 올라 있는 레포. 코드가 한 줄도 없다. 그 대신 "코드리뷰를 어떻게 해야 하는가"에 대한 구글 사내 가이드 — 리뷰어 가이드 7편, 작성자 가이드 4편 — 이 마크다운으로 정리되어 있다. ⭐ 20.5k · CC-BY 3.0 · 모든 언어·모든 회사에 적용 가능한 "코드리뷰의 표준."

1프로젝트 한줄 요약

코드는 없다. 사상(philosophy)이 있다.

구글 사내에서 모든 신입 엔지니어가 입문서로 읽는 "코드리뷰 가이드라인"을 외부에 공개한 것. 리뷰어가 무엇을 봐야 하는지, CL(Change List, 풀리퀘) 작성자는 어떻게 행동해야 하는지, 의견 충돌은 어떻게 풀어야 하는지를 "규칙이 아니라 원칙"으로 풀어 썼다.

2왜 지금도 주목받는가

2019년 공개 → 2025년 11월 아카이브 → 그래도 매일 트렌딩에 오르는 이유.

이 레포는 사실 업데이트가 멈춘 지 오래된 문서다. 2025년 11월 21일자로 read-only 아카이브 처리됐다. 그런데도 매일 누군가가 별을 누른다. 이유는 세 가지다.

① "왜 우리 팀 리뷰는 항상 싸움이 되는가"의 답이 여기 있다

리뷰가 길어지면 본질이 아니라 감정싸움이 된다. 이 문서는 "리뷰어 vs 작성자"가 아니라 "코드 헬스(code health) vs 시간"이라는 더 추상적인 축으로 갈등 구조를 재정의한다. 사람을 비판하는 게 아니라 "장기적으로 코드가 더 건강해지는가"를 보자는 것. 이 관점 하나만 팀에 깔려도 리뷰 문화가 180도 바뀐다.

② 모든 언어/모든 도구에서 통한다

"Go 코드는 이렇게 리뷰하라", "React PR은 이런 체크리스트로" 같은 도구 의존적 문서가 아니다. 리뷰 자체의 메타 원칙을 다루기 때문에, GitHub·GitLab·Phabricator·Gerrit 어느 환경에서도 그대로 적용 가능하다. CC-BY 3.0 라이선스라 회사 위키에 그대로 복사·번역해도 된다.

③ AI 코딩 시대에 오히려 더 중요해졌다

2026년 현재 Claude Code, Cursor, Copilot이 PR을 자동 생성한다. 그러면 리뷰어의 역할이 더 무거워진다 — AI가 생성한 1000줄짜리 PR을 그냥 LGTM할 수는 없으니까. 이 문서가 말하는 "작은 CL 원칙", "every line 원칙", "Why를 묻는 코드리뷰"가 AI 시대의 안전벨트 역할을 하게 됐다. 트렌드 카테고리에 #AI agent가 없는데도 11위에 오른 건 그 때문이다.

경쟁/유사 자료와의 비교

3"기술 스택" — 사실은 문서 구조 그 자체

코드가 없으니 기술 스택도 없다. 대신 "문서가 어떻게 짜여 있는가"가 곧 이 레포의 설계다.

이 레포는 review/ 폴더 하나에 모든 콘텐츠가 들어 있다. Jekyll 기반 GitHub Pages로 빌드되어 google.github.io/eng-practices에 호스팅된다. 빌드 설정은 _config.yml 한 파일이 전부.

4"아키텍처" — 코드리뷰 의사결정의 흐름도

코드 아키텍처 대신, 이 문서가 가르치는 리뷰 의사결정 트리를 그려본다.

핵심 설계 패턴 1: "단일 헌법 조항"

이 문서 전체에서 가장 중요한 한 문장:

핵심 설계 패턴 2: "팀 속도 > 개인 속도"

리뷰가 늦어지면 개인은 다른 일을 할 수 있어서 효율적으로 보인다. 그러나 팀 관점에서는 손해다. 그래서 이 문서는 "리뷰 응답 시간은 영업일 1일 이내"라는 강한 룰을 박는다. 단, 본인이 "집중 작업 중"이라면 끊기지 말 것. 끊김 비용이 더 크기 때문.

핵심 설계 패턴 3: "작은 CL의 우월성"

이 문서가 거의 신앙처럼 반복하는 주장: "CL은 작을수록 좋다." 이유는 8가지로 정리된다.

• ① 더 빨리 리뷰된다 (5분 짬을 내기 쉽다)
• ② 더 꼼꼼히 리뷰된다 (큰 PR에선 중요한 코멘트가 묻힌다)
• ③ 버그 가능성이 낮다
• ④ 리젝트돼도 손실이 작다
• ⑤ 머지가 쉽다 (충돌 적음)
• ⑥ 디자인을 다듬기 쉽다
• ⑦ 다음 작업이 블록되지 않는다
• ⑧ 롤백이 단순하다

가이드라인은 약 "100줄이 적당, 1000줄은 너무 큼". 다만 줄 수보다 "한 가지 일만 하는가(one self-contained change)"가 더 중요한 판단 기준이다.

5디렉토리 구조 해부

"이 폴더 구조 자체가 가르침이다."

핵심은 두 폴더로 나뉜다는 것이다. 리뷰어와 작성자는 같은 사건을 다른 관점에서 본다. 그래서 같은 사건(=CL 충돌)에 대해 양쪽 문서가 서로 다른 조언을 한다. 그러나 결론은 항상 같은 "헌법 1조"로 수렴한다 — standard.md의 "코드 헬스 개선" 원칙.

6핵심 챕터 미리보기 — 사실상 이 책의 요약

14개 문서 중 가장 자주 인용되는 5개 챕터를 한 페이지로 압축.

6-1. standard.md — "코드 헬스가 헌법이다"

중요한 부속 원칙:

• 기술적 사실과 데이터 > 개인 취향
• 스타일은 스타일 가이드가 최종 결정자 (스타일 가이드에 없으면 작성자 의견 존중)
• 소프트웨어 설계는 "취향" 문제가 아니다 — 원칙으로 판단
• 충돌 시 → 합의 시도 → 미팅 → escalation. "CL이 합의 안 됐다고 며칠씩 방치하지 말 것."

6-2. looking-for.md — 리뷰어 체크리스트 8개 영역

그리고 가장 강한 한 줄: "Every line. 사람이 작성한 모든 라인을 본다." 자동 생성 코드, 데이터 파일이 아니라면 한 줄도 건너뛰지 말 것. 이해 안 되면 작성자에게 물어볼 것 — 당신이 이해 못한 코드는 미래의 개발자도 이해 못한다.

6-3. speed.md — "리뷰는 빨라야 한다, 단 본인은 끊기지 말 것"

6-4. comments.md — 리뷰 코멘트는 "사람"이 아니라 "코드"를 향한다

코멘트는 심각도 라벨을 붙일 것:

• Nit: — 사소함. 기술적으로 맞지만 큰 영향 없음
• Optional: / Consider: — 좋은 아이디어일 수 있지만 강제는 아님
• FYI: — 이번 CL에 안 해도 됨. 참고용

이 라벨이 없으면 작성자는 모든 코멘트를 필수로 받아들여 좌절한다. 한 줄 라벨이 갈등의 90%를 줄인다.

6-5. cl-descriptions.md — CL 설명은 "What + Why"가 의무다

"Fix bug", "Fix build", "Phase 1" — 모두 나쁜 CL 설명의 실제 예시다.

구조: ① 첫 줄 = 명령문으로 압축 (Delete X. / Add Y. / Replace Z.) → ② 본문 = 왜(why), 어떤 trade-off, 어떤 한계를 함께 설명. 미래의 누군가가 git log를 grep할 때 발견할 수 있도록.

7학습 포인트 — 이 문서에서 무엇을 배울 수 있나

기술이 아니라 "관점"이 학습 대상이다.

학습 포인트 ①: 리뷰의 목적을 다시 정의하기

"버그 잡기"가 아니다. "장기적 코드 헬스 유지"다. 이 관점이 깔리면 다음과 같은 변화가 생긴다:

• "이 PR에 버그가 없는가?"가 아니라 "1년 뒤 신입이 이 코드를 읽고 수정할 수 있는가?"
• "내가 이 코드를 짰다면 이렇게 하지 않았을 텐데"가 아니라 "이게 시스템을 후퇴시키는가?"
• "완벽해질 때까지 안 머지" 대신 "지금 머지하고 follow-up CL로 개선"

학습 포인트 ②: 갈등을 escalation 체인으로 풀기

리뷰어와 작성자가 충돌하면? 이 문서가 제시하는 순서:

1. 코멘트로 합의 시도
2. 안 되면 화상 미팅 / 페이스 투 페이스 (단, 결과는 CL 코멘트에 기록)
3. 그래도 안 되면 더 넓은 팀 토론 → 테크리드 → 코드 오너 → 엔지니어링 매니저 순으로 escalation
4. 핵심: "CL을 며칠씩 방치하지 말 것"

학습 포인트 ③: "Nit:" 한 단어의 위력

실무에서 가장 즉시 적용 가능한 팁. PR 코멘트 앞에 Nit:를 붙이는 습관 하나만 들여도 팀 분위기가 바뀐다. 작성자는 "이건 안 고쳐도 됨"을 알 수 있고, 리뷰어는 "내가 이건 그냥 취향임을 인정함"을 표시할 수 있다.

학습 포인트 ④: PR을 작게 쪼개는 4가지 전략

학습 포인트 ⑤: 댓글이 아니라 코드를 고친다

리뷰어가 "이거 이해 안 됨"이라고 하면 작성자의 첫 반응은 무엇이어야 할까? 설명 댓글이 아니다. 코드를 더 명확하게 고친다. 안 되면 코드 주석을 단다. 그것도 안 되면 그제서야 PR 댓글로 설명한다. 이유는 단순하다 — PR 댓글은 1년 뒤 코드를 읽는 사람에게는 안 보이기 때문.

8하드웨어/시스템 요구사항

"이 레포에는 코드가 없다. 그래서 요구사항도 없다."

로컬에서 실행할 게 없다. 문서를 읽기만 하면 된다. 굳이 빌드해보고 싶다면 Jekyll만 설치하면 GitHub Pages와 동일한 사이트를 로컬에서 띄울 수 있다.

9직접 해볼 수 있는 실습 과제

"읽기"가 아니라 "내 팀에 적용"이 진짜 학습이다.

10관련 기술 심화 학습 로드맵 (4주)

이 레포는 "출발선"이다. 4주 동안 코드리뷰의 전체 우주를 돌아본다.

11핵심 키워드 사전

이 레포에 반복 등장하는 용어 한 자리 정리.

12참고 링크

• github.com/google/eng-practices — 원본 레포 (2025-11-21 아카이브)
• google.github.io/eng-practices — 공식 호스팅 페이지 (읽기 좋음)
• google.github.io/styleguide — 함께 봐야 할 구글 스타일 가이드 (언어별)
• abseil.io/resources/swe-book — 《Software Engineering at Google》 무료 공개판, Ch.9가 코드리뷰
• Chromium의 "Respectful Code Reviews" — 이 레포가 인용하는 자매 문서
• CC-BY 3.0 라이선스 본문