검증

에이전트가 작업을 끝냈다고 말하는 것만으로 결과를 확인할 수는 없다. 검증은 린트, 테스트, 빌드처럼 다시 실행할 수 있는 기준을 작업의 완료 조건으로 두는 일이다.

완료 기준을 먼저 알려주기

프로젝트에서 쓸 명령과 통과 조건을 작업 지시에 적는다. 에이전트가 명령을 모르면 확인을 생략하거나, 실행하지 않은 검사를 통과했다고 오해할 수 있다.

완료 조건
1. 관련 단위 테스트가 통과한다.
2. pnpm lint가 통과한다.
3. pnpm build가 종료 코드 0으로 끝난다.
4. 실행한 명령과 결과를 마지막에 보고한다.

저장소의 지침 파일에도 자주 쓰는 명령, 필요한 환경 준비, 완료 기준을 적어 두면 매 요청마다 반복할 설명을 줄일 수 있다. 검증 명령이 실패하면 원인을 요약하고 수정한 뒤 같은 명령을 다시 실행한다.

린트와 빌드

린터는 형식, 오류가 나기 쉬운 패턴, 프로젝트 규칙 위반을 빠르게 찾는다. ESLint를 쓰는 JavaScript 프로젝트라면 예를 들어 다음 명령을 검증 루프에 둔다.

pnpm eslint src

프로젝트에 실제로 등록된 스크립트 이름을 확인해 사용한다. 포맷과 타입 검사도 프로젝트에 명령이 준비되어 있으면 함께 실행할 수 있다.

빌드는 코드가 배포 가능한 형태로 묶이는지 확인한다. 테스트가 통과해도 타입 검사나 빌드 단계에서만 드러나는 문제가 있으므로 별도 완료 조건으로 둔다.

pnpm test
pnpm lint
pnpm build

검증 순서는 빠른 검사부터 시작하면 수정 주기를 짧게 유지할 수 있다. 관련 단위 테스트, 린트·포맷·타입 검사, 필요한 통합 테스트, 빌드, 마지막 변경 검토 순으로 실행한다. 실패 메시지와 종료 코드를 기록해 실제로 실행한 결과를 구분한다.

TDD로 회귀를 막기

테스트 주도 개발(TDD)은 먼저 실패하는 테스트를 만들고, 그 테스트를 통과시키는 변경을 한 뒤 구조를 정리하는 순환이다.

실패를 재현하는 테스트 작성
→ 테스트가 실패하는지 확인
→ 최소한의 수정
→ 테스트 통과 확인
→ 필요하면 구조 정리
→ 전체 관련 테스트 재실행

예를 들어 빈 문자열이 허용되지 않아야 하는 버그라면 입력과 기대 결과를 테스트로 고정한다. 테스트가 수정 전에는 실패하고 수정 후에는 통과해야 회귀 조건을 잡았다고 볼 수 있다.

it("빈 이름은 저장하지 않는다", () => {
  expect(validateName("")).toEqual({ ok: false });
});

이미 실패를 재현하는 테스트가 있다면 새 테스트 대신 그 테스트를 사용해도 된다. 어떤 사례를 고쳤는지 분명하도록 기존 테스트의 입력과 기대값을 확인한다.

BDD로 동작을 표현하기

행동 주도 개발(BDD)은 사용자나 시스템이 관찰할 수 있는 동작을 예시로 표현한다. 기능을 요청할 때 상황, 행동, 기대 결과를 함께 적으면 구현과 검증이 같은 조건을 바라본다.

시나리오: 로그인하지 않은 사용자의 보호 페이지 접근
주어진 상황: 사용자가 로그인하지 않았다
행동: /account를 연다
기대 결과: 로그인 화면으로 이동한다

BDD 형식은 사람이 읽는 인수 조건에도 쓸 수 있고, 프로젝트에 도구가 있으면 자동화 시나리오로 연결할 수 있다. 도구 없이도 이 예시를 테스트 사례와 수동 확인 목록으로 바꿀 수 있다.

버그를 다음 작업에 반영하기

버그를 발견하면 먼저 같은 조건에서 다시 나타나는지 확인한다. 재현 테스트를 추가하고, 수정한 뒤 테스트를 통과시키면 이후 변경에서 같은 오류를 빠르게 잡을 수 있다.

오류 발견
→ 최소 재현
→ 실패 테스트 작성 또는 갱신
→ 수정
→ 테스트·린트·빌드 실행
→ 결과를 기록

사람이 반복해서 찾아낸 문제가 자동 검사로 표현될 수 있다면 테스트, 프로젝트 규칙, 재사용 가능한 절차에 반영한다. 그러면 다음 작업에서 같은 실수를 검사로 발견할 수 있다.

에이전트가 검증을 끝냈다고 보고할 때는 실행한 명령과 결과를 요구한다. 테스트 파일을 추가했다는 사실은 테스트가 실제로 통과했다는 증거가 아니다. 중요한 변경은 최종 diff도 읽고 요구한 동작이 구현되었는지 확인한다.

보충: 런타임에서 검증 루프를 유지하는 방법

Claude Code의 작업 안내는 에이전트가 실행할 테스트·빌드·린터를 제공하고, 완료 보고에 출력과 명령 결과 같은 근거를 포함하도록 권한다. 같은 지시에서 반복하거나 완료 조건, Stop 훅, 별도 검증 에이전트로 통과 여부를 확인할 수 있다.

Codex 모범 사례는 테스트 작성·갱신, 관련 테스트 실행, 린트·포맷·타입 확인, 최종 동작 점검과 diff 검토 흐름을 설명한다. 저장소 지침에 명령과 완료 조건을 적으면 에이전트가 스스로 확인할 수 있다. 미커밋 변경은 로컬 /review로 검토하고 CI 품질 게이트에는 Codex GitHub Action을 구성할 수 있다. 기준일: 2026-09-30.