[한글자막] Claude Code, 완료했다고 끝이 아니다

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 결론

Claude Code의 완료 선언을 실제 완료로 만들려면, 검증 기준을 먼저 승인하고 독립 리뷰·수정·복구까지 이어지는 루프를 설계해야 한다.

📌 핵심 요점

1. 생성 속도가 빨라질수록 리뷰 부담도 커진다. 영상은 Anthropic의 일일 검토 대상 변경이 4개월 만에 약 2,500건에서 30,000건 이상으로 늘었다고 설명한다. 검토를 생략하면 사용자에게 전달된 오류를 뒤늦게 고치는 비용이 커진다.
2. 완료 기준은 구현 전에 정한다. 기능 요구사항에서 실행 가능한 eval.md를 만들고, 디자인이 있으면 목업도 준비한다. 사람이 평가 기준과 목업을 승인한 뒤 구현하며, 훅으로 평가 통과 전 완료 처리를 막는다.
3. 구현자와 검토자의 역할을 분리한다. 빌더는 구현하고, 검증자는 평가 항목의 통과 여부를 확인하며, 리뷰어는 평가가 놓친 문제를 찾는다. 각 에이전트에 별도 문맥을 주어 구현 당시의 판단을 그대로 추종하는 일을 줄인다.
4. 위험도와 반복 한도를 함께 관리한다. 고객의 금전 손실·접근 차단·타인 데이터 노출로 이어질 수 있는 변경에는 더 엄격한 평가를 적용한다. 반복 리뷰에는 변경분 중심 검사, 중복 지적 방지, 접근 재검토와 중단 조건이 필요하다.
5. 통과 이후에도 발견과 복구가 필요하다. 신규 사용자 관점의 사용성 검사와 직접 사용으로 남은 문제를 찾고, Git의 기능별 브랜치와 정상 동작 버전을 활용해 원인 추적과 되돌리기를 준비한다. 반복 오류와 오탐에서 얻은 규칙은 사람의 승인 후 리뷰 지침에 반영한다.

🧩 배경과 문제 정의

에이전트가 긴 시간 자율적으로 기능을 구현할 수 있게 되면서, 사람이 구현 과정을 지켜보지 않은 변경이 빠르게 쌓인다. 영상은 Anthropic의 검토 대상 변경량 증가를 사례로 들어, 생성 능력의 향상이 검토 부담과 오류 누락 가능성도 키운다고 설명한다.

이에 따라 리뷰의 질문을 ‘누가 코드를 읽었는가’에서 ‘무엇이 잘못될 수 있고 어떻게 발견할 것인가’로 바꾼다. 구현 중의 기본 검사에 더해, 사전 승인된 평가 기준, 독립 리뷰, 위험도별 검토 강도, 반복 제한, 배포 후 발견과 복구를 연결하는 것이 영상의 중심 제안이다. Claude Code 팀의 운영 사례와 이를 응용해 만든 시연용 스킬의 설정은 구분해서 이해해야 한다.

🕒 시간순 섹션별 상세정리

1. 생성 속도 증가가 만드는 리뷰 병목

• 에이전트가 여러 기능을 수시간 동안 자율 구현하면 사람이 과정을 보지 않은 변경이 쌓인다. 영상은 Anthropic의 일일 검토 대상 변경이 4개월 만에 약 2,500건에서 30,000건 이상으로 증가했다고 보여준다. [00:49]
• 검사를 서두르면 누락된 버그가 실제 사용자에게 전달되고, 이후 변경 확인과 수정에 더 많은 시간이 든다. 리뷰의 질문도 코드 열람 여부에서 실패 가능성과 발견 방법으로 옮겨야 한다. [01:38]
• Claude가 구현 도중 기본 검사를 수행하도록 하되, 다양한 사용 방식에서도 앱이 견디는지 확인하는 심층 검증을 별도로 둔다. [02:20]

2. 구현 전에 평가 기준과 목업 승인하기

• 완료했다는 말 대신 테스트 결과나 디자인과 비교한 스크린샷을 요구한다. 각 평가는 작업 완료 여부를 판단하는 고정된 검사이며, 잘못된 작업을 탈락시킬 만큼 엄격해야 한다. [02:53]
• 시연에서는 specs 아래 기능별 요구사항을 eval.md로 전환하는 스킬을 만든다. 디자인이 있으면 먼저 웹 목업을 만들고, 평가와 목업을 사람이 검토하기 전에는 구현하지 않도록 하며 평가 통과 전 완료를 막는 훅도 요청한다. [03:56]
• 스킬과 템플릿으로 요구사항·평가·목업을 준비하고 상태를 검토 단계로 바꾼다. 사람은 에이전트가 내린 결정, 다른 화면 상태와 모바일 디자인까지 살핀 뒤 수정하거나 구현을 승인한다. [04:54]

3. 독립 리뷰어와 프로젝트별 리뷰 규칙

• 구현한 에이전트는 자신의 판단에 동의하기 쉬우므로 별도 리뷰어가 필요하다. 영상은 팀의 리뷰 에이전트와 Claude Code의 가벼운 코드 리뷰 명령을 소개하고, effort 수준에 따라 검사 깊이를 조절한다고 보여준다. [05:41]
• 프로젝트 규칙을 review.md에 적되, 이 파일이 기본적으로 읽히지는 않는다고 보여준다. 새 세션에서도 함께 읽도록 Claude.md에서 해당 규칙 파일을 연결하는 방식을 제안한다. [06:10]
• 리뷰 규칙에는 실제 실패의 정의, 문제의 심각도, 무시할 항목, 보고 형식과 검사 방법을 담는다. 이후 코드 리뷰가 같은 기준에서 시작하도록 구성한다. [06:34]

4. 구현·검증·리뷰를 반복하고 학습한 규칙 남기기

• 리뷰 루프에서는 메인 에이전트가 오케스트레이터를 맡고, 별도 문맥의 빌더·검증자·리뷰어를 실행한다. 검증자는 평가별 통과 여부를 확인하고, 리뷰어는 review.md를 바탕으로 평가가 놓친 문제를 찾는다. [07:30]
• state.md에 반복 회차와 남은 실패를 기록하고, 훅으로 조기 완료를 막는다. 판단하기 어려운 결정은 사람에게 보고하며, 기본 종료 조건은 모든 평가 통과와 새로운 리뷰 문제의 부재다. [08:07]
• 이후 발견된 버그나 반복 오탐은 리뷰 규칙을 개선하는 재료가 된다. 루프는 반복 문제를 연결해 한 줄 규칙을 제안하고, 사람이 승인할 때만 추가한다. [08:55]

5. 고객 피해를 기준으로 검토 강도 정하기

• 정밀 리뷰에는 시간과 사용량이 든다. 영상은 변경을 분류하는 에이전트를 소개하며, 핵심 질문을 ‘이 기능이 고장 나면 고객에게 어떤 일이 생기는가’로 제시한다. [09:18]
• 외형상의 문제는 낮은 위험, 손실 없이 기능이 멈추는 경우는 중간 위험으로 보여준다. 금전 손실·접근 차단·타인 데이터 노출은 높은 위험으로 보고, 구현 전 분류 결과를 평가 작성에 전달해 더 엄격한 기준을 적용한다. [09:53]

6. 반복 리뷰의 비용과 중단 조건 관리하기

• 팀 사례에서는 수정과 리뷰가 50회 넘게 반복됐고, 나중에 보니 지적 사항 약 59%가 첫 회차부터 있던 문제였다고 보여준다. 이런 반복은 사용량 한도를 소모한다. [10:30]
• 팀이 도입한 규칙은 세 차례 후 접근 재검토, 첫 회차 이후 수정된 부분만 검사하고 기존 지적을 반복하지 않기, 문제 유형을 알려 같은 유형을 여러 위치에서 함께 고치기다. 영상은 이후 첫 리뷰 통과가 늘었다고 전해진다. [11:12]
• 시연용 루프는 매회 구현·브라우저 평가·코드 리뷰를 수행하므로 최대 다섯 회로 설정한다. 같은 문제가 두 차례 수정 후에도 남으면 그보다 일찍 멈추도록 한다. [11:30]

7. 신규 사용자 관점의 발견과 Git 기반 복구

• 모든 평가를 통과해도 오류는 남을 수 있다. 팀은 제품을 직접 사용해 문제를 찾고 대부분의 배포를 수분 내 되돌릴 수 있다고 설명하며, 사용자에게도 고객처럼 새 기능을 써보라고 권한다. [11:57]
• 구현을 보지 않은 에이전트가 처음 온 사용자처럼 앱을 탐색하게 한다. 시연에서는 임시 데이터베이스를 제공하고 훅으로 터미널을 통한 소스 열람까지 막아, 사용 중 막히는 지점과 개선안을 보고하게 한다. [13:02]
• Git으로 기능별 브랜치와 정상 동작 버전을 남기고, 버그 수정 스킬이 문제를 재현해 원인 가설을 확인하도록 한다. 저장된 버전에서 원인 변경을 추적하고 이전 버전으로 되돌릴 수 있게 준비한다. [13:57]

🧾 결론

• 완료 여부는 에이전트의 선언보다 테스트 결과, 디자인 비교, 독립 리뷰 같은 확인 가능한 근거로 판단해야 한다.
• 평가 기준은 구현 전에 검토하고, 구현 후에는 평가 항목 밖의 문제까지 별도 리뷰로 확인해야 한다.
• 리뷰 루프의 품질은 반복 횟수보다 위험에 맞는 검사 강도, 중복 제거, 명확한 중단 조건에 달려 있다.
• 모든 평가를 통과해도 오류는 남을 수 있으므로, 실제 사용 관찰과 빠른 복구 수단까지 개발 과정에 포함해야 한다.

📈 투자·시사 포인트

• 생산성 평가 기준의 이동: 생성한 코드나 기능의 양과 함께 검증에 드는 시간, 재작업, 배포 후 복구 부담을 살펴야 한다.
• 검증 체계의 중요성: 요구사항·평가 파일·리뷰 규칙·완료 방지 훅을 연결하는 운영 방식이 에이전트 활용 성과를 좌우한다.
• 사용량 비용의 관리: 모든 변경에 같은 수준의 정밀 검토를 적용하기보다 고객 피해 가능성에 따라 검토 자원을 배분필요가 있다.
• 복구 능력의 가치: 영상에서 빠른 되돌리기는 팀이 코드 검토 부담을 줄일 수 있는 조건으로 제시된다. 생성 속도와 함께 오류 발견 및 복구 능력을 평가해야 한다.

⚠️ 불확실하거나 확인이 필요한 부분

• 일일 변경량 약 2,500건→30,000건 이상, 50회 넘는 반복, 지적 사항 약 59%의 재등장은 영상이 전하는 사례다. 제공된 자막만으로는 원자료, 집계 기준, 적용 범위를 확인할 수 없다.
• 리뷰 에이전트의 Team·Enterprise 제공 여부, 코드 리뷰 명령의 기능과 effort 설정은 영상 설명 시점의 정보다. 현재 이용 환경에서의 제공 여부는 별도로 확인해야 한다.
• 영상의 평가 작성·리뷰 루프·신규 사용자 검사·버그 수정 스킬은 시연에서 구성한 방식이다. 실제 프롬프트, 훅 코드, 파일 내용이 제공되지 않아 동일한 동작을 그대로 재현할 수 있는지는 알 수 없다.
• 자막 기반 정리: 타임스탬프가 있는 자막을 기준으로 정리했으며, 고유명사·수치·인용은 원문 확인 필요 시 별도 검증한다.
• 영상 속 주장: 발표자의 해석·전망·비교는 확인된 외부 사실이 아니라 영상 속 주장으로 분리해 읽는다.
• 검증 필요: 수치, 기업 실적, 정책·시장 전망은 발행 전 최신 자료로 별도 검증이 필요하다.

✅ 액션 아이템

• 기능별 요구사항을 정리하고, 잘못된 구현이 실제로 실패하도록 실행 가능한 평가 항목을 작성한다.
• 디자인이 있는 기능은 목업과 모바일·다른 화면 상태를 준비하고, eval.md와 함께 사람이 검토한 뒤 구현을 시작한다.
• 평가 통과 전 완료 처리를 막는 훅을 구성하고, 실패 상태에서 완료 선언이 차단되는지 확인한다.
• 구현·평가 검증·코드 리뷰 역할을 분리하고, 리뷰 규칙에 실제 실패의 정의, 심각도, 제외 항목, 보고 형식과 검사 방법을 적는다.

❓ 열린 질문

• 우리 기능에서 고객의 금전 손실, 접근 차단, 데이터 노출로 이어지는 실패는 무엇이며 어떤 평가로 잡을 수 있을까?
• 현재 평가 목록이 놓치는 문제를 독립 리뷰어와 신규 사용자 검사가 얼마나 보완할 수 있을까?
• 어떤 상태에서 자동 수정을 계속하고, 언제 접근을 바꾸거나 사람의 판단을 요청해야 할까?