화면 모드
검증
에이전트가 작업을 끝냈다고 말하는 것만으로 결과를 확인할 수는 없다. 검증은 린트, 테스트, 빌드처럼 다시 실행할 수 있는 기준을 작업의 완료 조건으로 두는 일이다.
실습 저장소: 검증 루프(main). 빈 이름을 거절하는 테스트와 빌드 산출물 검사를 Node.js 24와 pnpm 10으로 실행한다. 이 실습 폴더에는 lint 스크립트가 없으며 pnpm test·pnpm build·pnpm verify로 검증한다. 실습 README의 실패 → 수정 → 재검증 순서로 TDD 예제를 따라갈 수 있다. 코드는 MIT 라이선스로 제공한다.
완료 기준을 먼저 알려주기
프로젝트에서 쓸 명령과 통과 조건을 작업 지시에 적는다. 에이전트가 명령을 모르면 확인을 생략하거나, 실행하지 않은 검사를 통과했다고 오해할 수 있다.
text
완료 조건
1. 관련 단위 테스트가 통과한다.
2. pnpm lint가 통과한다.
3. pnpm build가 종료 코드 0으로 끝난다.
4. 실행한 명령과 결과를 마지막에 보고한다.저장소의 지침 파일에도 자주 쓰는 명령, 필요한 환경 준비, 완료 기준을 적어 두면 매 요청마다 반복할 설명을 줄일 수 있다. 검증 명령이 실패하면 원인을 요약하고 수정한 뒤 같은 명령을 다시 실행한다.
린트와 빌드
린터는 형식, 오류가 나기 쉬운 패턴, 프로젝트 규칙 위반을 빠르게 찾는다. ESLint를 쓰는 JavaScript 프로젝트라면 예를 들어 다음 명령을 검증 루프에 둔다.
bash
pnpm eslint src프로젝트에 실제로 등록된 스크립트 이름을 확인해 사용한다. 포맷과 타입 검사도 프로젝트에 명령이 준비되어 있으면 함께 실행할 수 있다.
빌드는 코드가 배포 가능한 형태로 묶이는지 확인한다. 테스트가 통과해도 타입 검사나 빌드 단계에서만 드러나는 문제가 있으므로 별도 완료 조건으로 둔다.
bash
pnpm test
pnpm lint
pnpm build검증 순서는 빠른 검사부터 시작하면 수정 주기를 짧게 유지할 수 있다. 관련 단위 테스트, 린트·포맷·타입 검사, 필요한 통합 테스트, 빌드, 마지막 변경 검토 순으로 실행한다. 실패 메시지와 종료 코드를 기록해 실제로 실행한 결과를 구분한다.
테스트 종류와 범위
검증 명령을 하나만 정해 두면 무엇이 확인되지 않았는지 알기 어렵다. 테스트는 범위나 목적에 따라 종류가 갈리고, 종류마다 필요한 준비와 걸리는 시간이 다르다. 이 구분은 뒤의 TDD와 BDD와 다르다. TDD는 테스트를 작성하는 순환이고 BDD는 동작을 시나리오로 적어 합의하는 방식이므로, 둘 다 앞에서 다룬 여러 종류의 테스트를 함께 쓴다.
단위 테스트·통합 테스트·E2E 테스트의 구분은 Azure Well-Architected Framework의 테스트 피라미드가 근거다. 이 문서에는 그 셋에 더해 스모크 테스트와 슬라이스 테스트를 함께 둔다.
| 종류 | 검사 범위 | 작은 주문 예시 | 언제 쓰는가 |
|---|---|---|---|
| 단위 테스트 | 함수나 클래스 하나 | 할인율 계산이 경계값에서 맞는다 | 로직을 고칠 때마다 |
| 슬라이스 테스트 | 선택한 계층이나 기능 일부 | 컨트롤러가 요청을 응답으로 바꾼다 | 웹 계층이나 저장소 계층만 좁혀 볼 때 |
| 통합 테스트 | 여러 구성요소가 서로 맞물리는지 | 주문이 DB에 저장되고 다시 조회된다 | 모듈 경계나 배선을 바꿨을 때 |
| 스모크 테스트 | 기본 동작이 되는지 | 방금 띄운 서비스가 주문을 받는다 | 배포 직후. CI에서는 배포한 환경에 대해 매 변경마다 |
| E2E 테스트 | 사용자 흐름 전체 | 로그인부터 결제까지 끝낸다 | 중요한 흐름이 바뀔 때 |
범위가 넓어질수록 준비가 늘어난다. 데이터베이스나 다른 서비스를 함께 띄워야 하고, 브라우저를 열고 화면을 따라가야 하며, 실패했을 때 원인이 낯선 곳까지 멀어진다. 실제 걸리는 시간과 준비 비용은 프로젝트에 따라 크게 다르므로, 순서가 아니라 무엇을 확인하는지를 기준으로 고른다.
단위 테스트
가장 좁은 범위다. 함수나 클래스 하나를 다른 코드와 분리해 입력과 결과를 확인한다. 바깥에 의존하지 않아 준비가 거의 필요 없어서 반복해서 돌리기 좋다.
mock을 넣는다고 단위 테스트가 되는 것은 아니다. 시간·파일·네트워크처럼 바깥에 있는 부분만 대체하고, 실제로 계산하는 함수는 그대로 둔다. mock이 필요 없는 함수도 많다.
슬라이스 테스트
애플리케이션의 일부만 잘라 내서 검사하는 슬라이스다. 무엇을 남기고 무엇을 뺄지 선택하므로, 좁은 통합 테스트일 수도 있다. Spring Boot는 @WebMvcTest와 @DataJpaTest 같은 애노테이션으로 이 방식을 지원한다. @WebMvcTest는 웹 계층 빈만 스캔하고 @DataJpaTest는 엔티티와 Spring Data 저장소, JPA 인프라를 구성한다. 빠진 부분에서 생긴 문제는 잡지 못하므로 좁게 볼 때 쓴다.
통합 테스트
여러 구성요소가 실제 배선된 상태에서 서로 맞물리는지 확인한다. 데이터베이스에 실제로 저장하고 다시 읽어 값이 남는지 보는 경우가 대표적이다. 필요한 구성요소는 실제로 두되, 비용이 큰 바깥 서비스는 대역으로 대신하기도 한다. 이 단계에서만 드러나는 경우가 많아 중요하다.
스모크 테스트
범위가 넓다는 뜻이 아니라 목적이 기본 동작 확인이라는 점이 중요하다. 그래서 범위 단계가 아니라 목적에 붙은 이름인 스모크 테스트다. 배포된 서비스가 뜬 채로 기본 흐름 한 번을 통과하는지만 본다.
Azure Well-Architected Framework는 인프라가 잘 준비됐어도 애플리케이션이 그 자원을 실제로 쓰지 못하면 문제가 된다고 지적하면서, 상태 확인 엔드포인트에 대한 스모크 테스트가 그 빈틈을 잡아 준다고 설명한다. 같은 문서는 빠른 스모크 테스트를 매 커밋마다 돌리도록 권한다. 목적이 기본 동작 확인이므로 가볍고 빠르게 유지할 수 있다.
E2E 테스트
E2E는 end-to-end의 약자로, 여러 경계를 연결한 사용자 흐름 전체를 끝까지 통과하는 검사다. 브라우저를 조작하는 테스트만을 뜻하지 않는다. API 수준의 흐름을 E2E라고 부르기도 하지만, 기준은 사용자 관점의 전체 흐름이다. 그 서비스를 사용하는 사람의 인터페이스가 화면이든 API든, 한 흐름이 처음부터 끝까지 이어지는지를 본다. 실패 원인을 찾기 어려운 만큼 로그인·결제처럼 중요한 흐름에 둔다.
관찰할 대상을 고를 때도 기준이 필요하다. Playwright의 테스트 원칙은 자동화 테스트가 최종 사용자가 보는 결과를 확인해야 하고, 함수 이름이나 CSS 클래스 같은 구현 세부에 기대지 말라고 안내한다.
무엇을 언제 돌리나
변경한 범위에서 관련되는 검사를 먼저 돌리고, 그다음 프로젝트의 CI가 요구하는 검사를 통과시킨다.
- 반복해서 코드를 고칠 때: 단위 테스트
- 웹 계층이나 저장소 계층만 바꿨을 때: 슬라이스 테스트
- 모듈 경계나 배선을 바꿨을 때: 통합 테스트
- 배포 직후, 또는 CI에서 배포한 환경을 확인할 때: 스모크 테스트
- 중요한 흐름이 바뀌었을 때: E2E
Azure Well-Architected Framework는 커버리지와 파이프라인 효율 사이에 상충 관계가 있으며, 컴파일과 검증을 하는 초기 빌드에 가능한 검사를 전부 넣으면 릴리스 주기가 느려지고 중요한 테스트가 우회될 수 있다고 지적한다. 모든 종류를 항상 돌릴 필요는 없다.
느린 단계에서 처음 실패했다면, 그 원인이 빠른 단계에서 잡혔어야 하는 문제인지 확인한다. 순수 계산 오류라면 단위 테스트를 보강하고, 배선 오류라면 통합 테스트를 그대로 둔다. 전체 검사를 늘리기보다 원인이 있는 층의 테스트를 보강한다.
TDD로 회귀를 막기
테스트 주도 개발(TDD)은 먼저 실패하는 테스트를 만들고, 그 테스트를 통과시키는 변경을 한 뒤 구조를 정리하는 순환이다.
text
실패를 재현하는 테스트 작성
→ 테스트가 실패하는지 확인
→ 최소한의 수정
→ 테스트 통과 확인
→ 필요하면 구조 정리
→ 전체 관련 테스트 재실행예를 들어 빈 문자열이 허용되지 않아야 하는 버그라면 입력과 기대 결과를 테스트로 고정한다. 테스트가 수정 전에는 실패하고 수정 후에는 통과해야 회귀 조건을 잡았다고 볼 수 있다.
ts
it("빈 이름은 저장하지 않는다", () => {
expect(validateName("")).toEqual({ ok: false });
});이미 실패를 재현하는 테스트가 있다면 새 테스트 대신 그 테스트를 사용해도 된다. 어떤 사례를 고쳤는지 분명하도록 기존 테스트의 입력과 기대값을 확인한다.
BDD로 동작을 표현하기
행동 주도 개발(BDD)은 사용자나 시스템이 관찰할 수 있는 동작을 예시로 표현한다. 기능을 요청할 때 상황, 행동, 기대 결과를 함께 적으면 구현과 검증이 같은 조건을 바라본다.
text
시나리오: 로그인하지 않은 사용자의 보호 페이지 접근
주어진 상황: 사용자가 로그인하지 않았다
행동: /account를 연다
기대 결과: 로그인 화면으로 이동한다BDD 형식은 사람이 읽는 인수 조건에도 쓸 수 있고, 프로젝트에 도구가 있으면 자동화 시나리오로 연결할 수 있다. 도구 없이도 이 예시를 테스트 사례와 수동 확인 목록으로 바꿀 수 있다.
버그를 다음 작업에 반영하기
버그를 발견하면 먼저 같은 조건에서 다시 나타나는지 확인한다. 재현 테스트를 추가하고, 수정한 뒤 테스트를 통과시키면 이후 변경에서 같은 오류를 빠르게 잡을 수 있다.
text
오류 발견
→ 최소 재현
→ 실패 테스트 작성 또는 갱신
→ 수정
→ 테스트·린트·빌드 실행
→ 결과를 기록사람이 반복해서 찾아낸 문제가 자동 검사로 표현될 수 있다면 테스트, 프로젝트 규칙, 재사용 가능한 절차에 반영한다. 그러면 다음 작업에서 같은 실수를 검사로 발견할 수 있다.
에이전트가 검증을 끝냈다고 보고할 때는 실행한 명령과 결과를 요구한다. 테스트 파일을 추가했다는 사실은 테스트가 실제로 통과했다는 증거가 아니다. 중요한 변경은 최종 diff도 읽고 요구한 동작이 구현되었는지 확인한다.
보충: 런타임에서 검증 루프를 유지하는 방법
Claude Code의 작업 안내는 에이전트가 실행할 테스트·빌드·린터를 제공하고, 완료 보고에 출력과 명령 결과 같은 근거를 포함하도록 권한다. 같은 지시에서 반복하거나 완료 조건, Stop 훅, 별도 검증 에이전트로 통과 여부를 확인할 수 있다.
Codex 모범 사례는 테스트 작성·갱신, 관련 테스트 실행, 린트·포맷·타입 확인, 최종 동작 점검과 diff 검토 흐름을 설명한다. 저장소 지침에 명령과 완료 조건을 적으면 에이전트가 스스로 확인할 수 있다. 미커밋 변경은 로컬 /review로 검토하고 CI 품질 게이트에는 Codex GitHub Action을 구성할 수 있다. 기준일: 2026-09-30.