# 환웅굴 · AI 검증 실전 가이드

AI가 코드를 쓴 뒤 사람이 화면을 열어 확인하고 오류를 전달하던 일을, 반복 가능한 실행·관측·수정 과정으로 바꾸는 방법입니다.

Lauren Tan의 [발표 영상](https://www.youtube.com/watch?v=KwOX7vJyoOk)을 바탕으로 환웅굴의 공유 자료로 재구성했습니다. 그녀의 원본 사내 코드나 원본 스킬을 배포하는 자료는 아닙니다. 아래 양식·요청문·문의 폼 예시는 실제 프로젝트에 적용하기 위해 새로 작성했습니다.

## 먼저 이것만 따라 하세요

**처음에는 스킬 설치 없이 이 MD 파일 하나로 시작하세요.** 프로젝트 파일을 읽고 앱을 실행·조작할 수 있는 AI 작업 환경에서 사용합니다. 일반 채팅에 파일만 올리면 설명은 받을 수 있지만, 앱을 직접 검사한 결과까지 얻을 수 있는 것은 아닙니다.

### 1. 준비하기

- AI 작업 환경에서 검사할 프로젝트 폴더를 엽니다. 화면만 검사하려면 접속할 테스트 주소를 준비합니다.
- 이 MD를 첨부하거나, AI가 읽을 수 있는 프로젝트 폴더에 저장합니다.
- 로그인이 필요하면 테스트 계정으로 접속할 수 있게 합니다. 수정까지 맡기려면 소스 코드에도 접근할 수 있어야 합니다.

실행 명령이나 브라우저 제어 도구 이름을 몰라도 괜찮습니다. 아래 요청문이 기존 설정부터 확인하도록 안내합니다. 실제 연결이 없으면 AI가 필요한 설정을 알려줘야 합니다.

### 2. 빈칸 세 개를 채워서 보내기

아래 전체를 복사하세요. 처음에는 기능 하나만 고릅니다.

```text
첨부한 환웅굴 AI 검증 가이드를 읽고 다음 기능을 직접 확인해줘.

프로젝트 폴더 또는 테스트 주소: [여기에 입력]
확인할 기능 하나: [예: 문의 폼 제출]
정상 기준: [예: 잘못된 이메일은 접수되지 않고, 정상 테스트 이메일은 한 번만 접수된다]

먼저 기존 실행 방법과 앱 조작 도구가 있는지 확인해줘.
준비돼 있으면 직접 앱을 열어 기능을 실행해줘.
없는 주소·명령·실행 결과를 추측하지 말고, 꼭 필요한 정보만 물어봐.

문제가 확인되고 소스 코드에 접근할 수 있으면 원인을 찾아 수정해줘.
고친 뒤 같은 입력으로 다시 확인하고, 정상 입력도 함께 확인해줘.
수정할 코드에 접근할 수 없으면 관측한 문제와 수정할 위치를 정리해줘.
테스트 환경에서 진행하고 실제 고객 전송·결제·배포는 하지 마.

마지막에는 아래 네 가지를 보여줘.
1. 무엇을 어떤 입력으로 직접 실행했는지
2. 수정 전·후 결과 또는 현재 확인된 결과
3. 실제 화면과 필요한 로그·저장 결과의 증거 파일
4. 확인하지 못한 부분과 다음에 필요한 행동

이번 실행의 결과는 verification/검증결과.md에,
증거는 verification/evidence/에 저장해줘.
파일을 저장할 수 없으면 그 사실을 밝히고 채팅에 결과를 써줘.
```

**고치지 않고 확인만 받고 싶다면** 요청문의 “문제가 확인되고…”부터 “수정할 위치를 정리해줘.”까지를 `코드는 수정하지 말고, 확인 결과와 증거만 남겨줘.`로 바꾸세요.

### 3. 결과에서 이것만 확인하기

| AI가 준 결과 | 내가 확인할 것 |
| --- | --- |
| “통과했습니다” | 어떤 입력으로 확인했는지, 증거 파일이 실제로 열리는지 |
| “수정했습니다” | 고치기 전과 후에 같은 동작을 해봤는지, 정상 입력도 되는지 |
| “실행할 수 없습니다” | 필요한 주소·테스트 계정·도구 연결 중 무엇이 없는지 |

`verification/검증결과.md`를 열고 증거 링크를 확인하세요. 저장·접수 기능은 성공 화면만으로 충분하지 않습니다. 실제 저장된 값이나 접수 건수까지 확인했는지 봅니다.

**결과 형식 예시 — 실제 실행 기록이 아닙니다**

> 일부 확인: 잘못된 이메일을 넣었을 때 화면에 오류가 나타났습니다. 요청 기록과 접수 데이터에는 접근하지 못해 실제 미접수 여부는 확인하지 못했습니다. 다음 확인에는 테스트 접수 목록 접근이 필요합니다.

증거 없이 “정상입니다”라고만 답했다면 이렇게 이어서 요청하세요.

> 실제로 실행한 입력과 결과를 보여줘. 화면이나 저장 결과를 확인하지 못했다면 통과라고 하지 말고 미확인으로 표시해줘.

### 반복해서 쓸 때만 스킬 추가하기

처음 한 번은 위 요청문으로 충분합니다. 자주 사용하게 되면 함께 제공한 `hwanwoong-verify` 폴더 전체를 사용하는 AI 도구의 스킬 설치 방식에 맞춰 추가하세요. 설치 전에는 `$hwanwoong-verify` 호출만으로 작동한다고 가정하지 마세요.

설치를 지원하지 않는 환경에서는 아래처럼 파일을 직접 읽게 할 수 있습니다.

> 이 자료의 hwanwoong-verify/SKILL.md를 읽고 필요한 양식을 사용해서, 방금 확인한 기능을 같은 기준으로 다시 검증해줘.

**여기까지만 읽고 시작해도 됩니다.** 아래는 검증 절차를 이해하거나 내 프로젝트에 맞게 확장할 때 읽는 상세 가이드입니다. 이 자료는 문서와 연결 파일을 점검한 상태이며, 독자의 앱에서 실행 성공을 보장하거나 여러 모델의 성능 평가를 완료한 자료는 아닙니다.

---

## 먼저 구분할 세 가지

| 구성 | 하는 일 | 예 |
| --- | --- | --- |
| 제어 도구 | 앱을 실행하고 조작하며 증거를 수집 | 화면 클릭, 로그, 스크린샷, 성능 기록 |
| 스킬 | 어떤 순서와 기준으로 도구를 사용할지 안내 | 관련 코드 확인 → 재현 → 수정 → 같은 조건에서 재검증 |
| 자동 검사 | 반드시 지켜야 하는 규칙을 코드로 검사 | 금지된 의존 관계, 타입 검사, 특정 오류의 회귀 테스트 |

스킬 문서만 저장한다고 앱을 조작하는 기능이 생기지는 않습니다. 사용할 브라우저·앱 제어 도구와 실행 환경을 연결해야 합니다. 실제 동작이 맞는지와 코드 구조가 적절한지도 별도로 판단합니다.

## 1. 핵심 기능 하나와 성공 조건부터 정하기

처음부터 서비스 전체를 맡기지 않습니다. 재현할 수 있는 동작 하나를 고릅니다.

**적용 예시: 문의 폼의 이메일 검증**

- 목표: 잘못된 이메일로 제출하면 화면에 오류가 나타나고 전송되지 않는다.
- 정상 경로: 올바른 테스트 이메일을 넣으면 테스트 환경에서 한 번만 접수된다.
- 확인 대상: 화면 안내, 요청 발생 여부, 접수 건수.
- 작업 환경: 로컬 또는 별도 테스트 환경. 실제 고객에게 메시지를 보내지 않는 테스트 경로.
- 완료 조건: 수정 전 실패를 확인하고, 수정 후 동일한 경로가 통과하며 정상 제출도 유지된다.

실패를 재현하지 못했으면 “재현 안 됨”이라고 기록합니다. 버그가 없거나 해결됐다는 결론으로 바꾸지 않습니다. 이전 버전에 접근할 수 없다면 현재 버전만 확인했다고 명시합니다.

## 2. AI에게 앱을 조작할 도구 연결하기

그녀의 `control-glass`는 Playwright와 CDP를 이용해 실행 중인 앱을 다루는 도구였습니다. CDP는 브라우저를 프로그램으로 제어하는 통로입니다. 이 특정 도구의 사내 경로와 명령을 다른 프로젝트에 그대로 복사하지 않습니다.

내 프로젝트에서는 이미 있는 자동화 도구를 우선 사용합니다. 부족한 기능이 있을 때만 작은 제어 스크립트를 덧붙입니다.

| 필요한 능력 | 실제 확인할 것 |
| --- | --- |
| 실행 | 프로젝트의 실행 명령, 준비 완료 신호, 접속 대상 |
| 조작 | 이동, 클릭, 입력, 키보드 조작 |
| 관측 | 화면·접근성 트리·콘솔·필요한 요청 또는 앱 로그 |
| 증거 | 스크린샷, 테스트 결과, 필요할 때 성능 기록 |
| 재실행 | 같은 초기 데이터와 조건으로 다시 시작할 방법 |

웹 앱은 사용 가능한 브라우저 자동화 기능, Electron 앱은 프로젝트가 제공하는 제어 경로, iOS 앱은 준비된 시뮬레이터 도구를 선택합니다. 실제로 사용 가능한 API와 명령을 확인한 후 연결합니다. 도구가 없으면 결과를 추측하지 말고 필요한 연결을 기록합니다.

도구의 입력·출력·준비 상태·실패 처리는 [제어 도구 명세 양식](hwanwoong-verify/assets/control-contract.md)으로 정리할 수 있습니다.

## 3. 제품 지도 작성하기

AI는 코드를 읽어도 사용자가 말하는 “왼쪽 사이드바”가 어느 화면인지 모를 수 있습니다. 기능별로 다음 정보를 연결합니다.

1. 사용자가 부르는 기능 이름.
2. 해당 화면까지 가는 순서.
3. 로그인·데이터 등 필요한 초기 상태.
4. 버튼의 접근 가능한 이름, 관측한 선택자, 실제 단축키.
5. 동작 후 기대하는 화면 또는 상태.
6. 관련 코드와 확인한 버전.

“제출 버튼”이라고만 쓰지 말고 어느 페이지의 어떤 버튼인지 적습니다. 선택자를 추측해 넣지 않습니다. 제품이 바뀌면 바뀐 기능의 항목부터 다시 확인합니다.

[제품 지도 양식](hwanwoong-verify/assets/feature-map.md)을 프로젝트 문서로 복사해 사용하세요.

## 4. 한 번의 검증을 끝까지 닫기

`기대 결과 정의 → 문제 재현 → 증거 수집 → 원인 조사 → 수정 → 동일 조건 재검증`

실행 전 성공 조건을 적어두면 AI가 자기 결과에 맞춰 기준을 바꾸는 일을 줄일 수 있습니다.

- **재현:** 문제의 경로를 직접 실행합니다.
- **관측:** 오류 메시지와 로그, 화면, 필요한 성능 기록을 남깁니다.
- **조사:** 증거와 관련 코드의 연결을 확인합니다.
- **수정:** 요청 범위에서 원인을 해결합니다.
- **재검증:** 동일한 입력과 조건으로 다시 실행하고 가까운 정상 경로도 확인합니다.
- **보고:** 확인한 사실, 해석, 미확인 영역을 분리합니다.

화면이 예쁘게 보이는 것만으로 저장 성공을 증명하지 않습니다. 성공 토스트 외에 저장된 값·요청 결과 등 그 기능에 맞는 증거를 확인합니다. 모든 작업에 모든 종류의 로그가 필요한 것은 아닙니다.

## 5. AI의 실패를 스킬에 반영하기

그녀는 자신 있게 답하지만 관련 코드를 보지 않는 행동을 발견하고 조사 절차를 개선했습니다. 실패를 발견할 때마다 긴 금지 목록을 쌓기보다, 해당 실패에 필요한 지침을 좁게 고칩니다.

| 관측한 실패 | 다음 지침에 반영할 내용 |
| --- | --- |
| 읽지도 않은 코드를 원인으로 단정 | 관측한 증거와 확인한 코드 위치를 근거로 가설 제시 |
| 비슷한 이름의 다른 버튼 클릭 | 제품 지도에서 진입 경로·화면 상태·선택자를 함께 확인 |
| 테스트 도구 오류를 제품 버그로 오해 | 환경 오류와 앱 동작 실패를 따로 기록 |
| 실행하지 않고 “수정 완료”라고 답함 | 재검증 기록이 없으면 실행 검증 미완료로 보고 |
| 최신 버전이 통과하니 과거 제보도 틀렸다고 결론 | 이전 버전과 현재 버전의 재현 결과를 분리 |

지침을 고친 다음에는 그 실패를 일으켰던 사례를 다시 실행합니다.

## 6. 스킬도 평가하기

그녀는 스킬 변경 후 여러 모델에서 결과를 평가하고, 다른 모델을 평가자로 사용해 판단을 교차 확인했습니다.

처음에는 작은 사례 묶음으로 시작해도 됩니다.

- 정상 경로.
- 알려진 오류 또는 경계 입력.
- 모호한 사용자 제보.
- 실행 환경이 부족한 상황.
- 이전 버전과 현재 버전의 결과가 다른 상황.

평가 기준은 “말을 잘했는가”보다 실제로 올바른 기능을 찾아 조작했는지, 올바른 상태를 판정했는지, 증거를 남겼는지입니다. 모델별 비교는 가능한 환경과 예산 안에서 진행합니다. 같은 실행 조건을 기록하고, 한 번의 통과를 전체 신뢰성으로 일반화하지 않습니다.

평가용으로 쓰지 않은 별도 사례도 남겨 지침이 익숙한 문제에만 맞춰지는 것을 확인합니다. 이는 이 공유 자료에서 보완한 실무 적용 방법입니다.

[평가 방법](hwanwoong-verify/references/evaluation.md)과 [평가 사례 양식](hwanwoong-verify/assets/eval-cases.md)을 함께 제공합니다.

## 7. 반드시 지킬 규칙은 자동 검사로 옮기기

반복해서 사람의 댓글로 지적하는 규칙 중 기계가 판별할 수 있는 것은 자동 검사 후보입니다.

예를 들어 그녀는 화면 처리와 백그라운드 코드 사이에서 금지된 의존 관계를 검사했습니다. 자신의 프로젝트에서 허용되는 방향과 예외를 먼저 정의해야 합니다. 모든 프로젝트에 동일한 폴더 경계나 특정 API 금지를 적용하지 않습니다.

- 규칙을 어긴 작은 사례에서 검사가 실패하는지 확인.
- 정상 사례에서는 통과하는지 확인.
- 해당 규칙에 맞는 기존 타입 검사·린트·의존 관계 검사·회귀 테스트를 활용.
- 동작 검증과 구조 검사의 결과를 따로 보고.

CI는 코드 변경에 맞춰 검사를 자동으로 실행하는 체계입니다. CI 통과가 모든 사용자 동작과 설계 품질을 증명하는 것은 아닙니다.

## 8. 신뢰를 쌓은 뒤 확장하기

처음에는 직접 관찰할 수 있는 로컬 환경에서 시작합니다. 반복 실행이 안정적이고 실패를 구분해 보고할 수 있을 때 더 많은 작업이나 클라우드 실행으로 넓힙니다.

그녀의 Benny 사례에서는 이전 코드에서 버그를 재현하고 최신 코드에는 이미 수정돼 있다는 결과까지 알려줬습니다. 이처럼 “수정할 필요가 없는 상태”도 정확히 구분하는 것이 유용한 자동화입니다.

600개가 넘는 PR은 그녀가 설명한 구조 개편 작업량입니다. 모든 팀이 채워야 하는 목표 수치가 아닙니다. 자동 확장은 사람 수보다 재현성, 증거의 품질, 실패 처리, 시간·비용에 근거해 판단합니다. 이 자료나 스킬은 자동 배포·자동 병합을 지시하지 않습니다.

## 바로 쓰는 요청문

이 MD 파일을 프로젝트를 다룰 수 있는 AI 도구에 전달한 뒤, 대괄호 부분을 내 프로젝트에 맞게 바꾸세요.

> 이 가이드에 따라 [프로젝트]의 [핵심 기능 하나]를 검증할 수 있게 만들어줘. 기존 실행·테스트 도구부터 확인하고, 필요한 조작 기능만 보완해줘. 기능의 화면 경로와 조작법을 제품 지도로 남기고, [관측된 문제]를 재현해줘. 성공 조건을 먼저 적고, 수정이 필요한 경우 같은 조건에서 수정 전후를 비교해줘. 스크린샷·로그·테스트 결과 중 필요한 증거를 남기고, 실행하지 못한 부분은 따로 보고해줘.

이미 스킬을 설치했다면:

> $hwanwoong-verify 이 프로젝트의 문의 폼을 검증해줘. 잘못된 이메일은 전송되지 않아야 하고, 정상 테스트 입력은 한 번만 접수되어야 해. 로컬 테스트 경로에서 실행하고 결과와 증거를 남겨줘.

## 포함 파일과 사용법

- 이 MD: 사람이 읽거나 AI에 전달하는 실전 가이드.
- `hwanwoong-verify/SKILL.md`: AI가 반복해서 적용하는 검증 지침.
- `hwanwoong-verify/assets/`: 제품 지도·제어 명세·보고서·평가 사례 양식.
- `hwanwoong-verify/references/evaluation.md`: 스킬 평가 방법.

지원 도구의 스킬 디렉터리에 `hwanwoong-verify` 폴더 전체를 넣어 사용합니다. 지원하지 않는 도구에서는 SKILL.md와 필요한 양식을 프로젝트 자료로 전달할 수 있습니다. 템플릿은 실행 결과가 아니므로 실제 관측으로 채워야 합니다.

## 영상 근거

| 내용 | 구간 |
| --- | --- |
| 실행·성능 기록을 통한 검증 | [06:05](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=365s) |
| control-glass와 제어 도구 | [09:22](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=562s) |
| 제품 지도와 유지 | [10:17](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=617s) |
| 실패 관찰과 스킬 개선 | [14:25](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=865s) |
| 평가와 모델 교차 확인 | [17:47](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=1067s) |
| 로컬 검증과 Benny 사례 | [23:57](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=1437s) |
| 구조 개편 투자 | [34:01](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=2041s) |
| 의존 관계와 자동 검사 | [41:27](https://www.youtube.com/watch?v=KwOX7vJyoOk&t=2487s) |

환웅굴 팔로우하고 계속 사업에 도움되는 정보 받아가세요.