# 검증

린트, 단위 테스트, 빌드 파이프라인을 통한 자동화된 작업 결과 검증 방법을 다룹니다.

원본 URL: https://abc.noco.kr/harness-advanced/verification

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

## 완료 기준을 먼저 알려주기

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

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

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

## 린트와 빌드

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

```bash
pnpm eslint src
```

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

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

```bash
pnpm test
pnpm lint
pnpm build
```

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

## TDD로 회귀를 막기

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

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

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

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

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

## BDD로 동작을 표현하기

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

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

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

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

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

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

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

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

::: details 보충: 런타임에서 검증 루프를 유지하는 방법
[Claude Code의 작업 안내](https://code.claude.com/docs/en/best-practices)는 에이전트가 실행할 테스트·빌드·린터를 제공하고, 완료 보고에 출력과 명령 결과 같은 근거를 포함하도록 권한다. 같은 지시에서 반복하거나 완료 조건, Stop 훅, 별도 검증 에이전트로 통과 여부를 확인할 수 있다.

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