이 단계에서 하는 것: QA 엔지니어 서브에이전트에게 PRD 완료 기준을 테스트 케이스 문서(
docs/테스트케이스.md)로 옮기고 실행해 결과를 기록하는 일을 맡긴다. 보안 엔지니어 서브에이전트에게는 점검표(docs/보안점검.md)를 쓰고 그대로 점검해 결과를 기록하게 한다. 발견한 문제는 개발 담당 서브에이전트가 수정하고, QA·보안 담당자가 다시 확인한다. 다음 단계로 넘길 것: 세 상황의 테스트를 통과하고 보안 점검에서 발견한 문제를 해결한 앱.
화면·API·AI·인증이 연결되어 정상적으로 보이더라도 경계 상황과 잘못된 요청에서는 오류가 날 수 있다. 이번에는 QA와 보안 점검을 담당할 서브에이전트를 설정한다. QA는 정상·경계·실패 상황을 테스트하고, 보안 담당자는 비밀값과 접근 권한을 확인한다. 두 역할은 구현 코드를 직접 수정하지 않고 문제를 보고한다. 개발 담당자가 수정하면 같은 검사를 다시 실행한다.
.env.local에 Supabase 접속 정보와 Gemini API 키가 서버 전용 환경변수로 들어가 있다.QA 엔지니어 서브에이전트는 테스트 케이스 문서를 쓰고, 그대로 테스트를 만들어 실행하고 결과를 기록한다. 테스트를 통과시키기 위해 구현 코드를 임의로 수정하지 않도록 책임을 정한다. 무엇을 테스트할지는 사람이 불러 주지 않는다 — PRD의 완료 기준이 요구마다 정상·경계·실패로 적혀 있고, 화면기획서가 빈 상태·로딩·에러를, API 명세가 401·400·403과 실패 응답을 정해 두었다. QA는 그 문서들을 읽고 테스트 케이스를 뽑아 docs/테스트케이스.md에 남긴다. 다른 역할의 PRD·화면기획서·ERD·명세처럼 이것이 QA의 산출물이고, 사람은 그 문서를 읽고 판정한다. 아래 프롬프트를 그대로 붙여 넣는다.
① 정의 — 서브에이전트 생성
'QA 엔지니어' 서브에이전트를 만들어줘. docs/PRD.md의 완료 기준, docs/화면기획서.md의 화면 상태, docs/API명세.md의 오류 응답을 근거로 테스트 케이스 문서(docs/테스트케이스.md)를 쓰고, 그 문서대로 테스트를 만들어 실행하고 결과를 문서에 기록한다. 테스트를 통과시키려고 구현 코드를 수정하지 않는다. 발견한 문제의 수정은 개발자 역할에게 맡긴다.서브에이전트를 만든 뒤에는 Claude Code를 한 번 다시 띄운다(/exit 뒤 claude). 새 서브에이전트는 다음 세션부터 보인다.
② 실행 — 테스트 케이스 문서 쓰기
QA 엔지니어 서브에이전트로, docs/테스트케이스.md에 작성해줘. 결제는 빼고 작성해줘. 문서 작성만 하고 끝내.이렇게 나오면 성공: docs/테스트케이스.md가 생기고, PRD의 완료 기준 번호(AC)마다 케이스가 있다. 케이스에는 입력과 기대 결과가 적혀 있고, 정상·경계·실패가 다 들어 있다. 결제 관련 기준은 빠져 있다. 무엇을 적을지는 정의에서 준 근거 문서 셋(PRD 완료 기준·화면 상태·API 오류 응답)으로 QA가 정한다 — 테스트는 아직 실행하지 않았다.
[사람 검토] 문서를 열어 읽는다. 테스트 케이스는 QA의 산출물이다. PRD처럼 사람이 읽고 판정한다. PRD를 옆에 띄우고 완료 기준이 빠진 곳이 없는지, 기대 결과가 PRD 문장과 같은지 두세 개를 대조한다. 빠진 기준이 있으면 번호를 짚어 "AC 몇 번이 빠졌다, 더해줘"라고 한다. 이 문서가 뒤에서 기능을 추가할 때 다시 돌리는 회귀 테스트의 목록이 된다.
③ 실행 — 테스트 만들어 실행하고 결과 기록
QA 엔지니어 서브에이전트로, docs/테스트케이스.md대로 테스트를 만들어 실행하고, 결과를 케이스마다 통과·실패로 문서에 기록해줘.실패 사례 중 하나 이상은 실제로 잘못된 요청을 보내 서버가 거부하는지 확인해.이렇게 나오면 성공: docs/테스트케이스.md의 케이스마다 통과·실패가 기록된다. 그중 하나 이상은 실제 요청을 보내 서버가 거부한 기록이다. 실패가 있으면 어느 요구(R)의 어느 기준인지 바로 읽힌다 — 그것을 단계 3에서 개발자에게 넘긴다.
[사람 검증] AI의 통과 보고를 받은 뒤 테스트를 직접 실행한다. 결과와 실패 항목을 확인한다. 1. "서버 실행해서 url 알려줘"로 앱을 켜 둔다. (거래 등록·조회를 실제로 부르는 통합 테스트가 이 서버를 호출하기 때문. 안 켜면 그 테스트가 "연결 거부"로 빨갛게 실패한다.) 2. 터미널을 열어
npx vitest run(또는 AI가 만든npm test)을 친다. 3. 맨 아래에Test Files N passed / Tests N passed처럼 전부 통과(초록) 가 뜨면 됐다. 빨간 게 있으면 그 출력을 그대로 AI에게 주고 "이 실패를 고쳐줘"라고 한다(단계 3).
기능 테스트와 별도로 비밀값 노출과 접근 권한을 확인한다. 무엇을 점검할지는 사람이 불러 주지 않는다 — CLAUDE.md가 비밀값·클라이언트 DB 접근·서버 판정 규칙을, 아키텍처가 접근 제어 전략을, ERD가 RLS를, API 명세가 401·403을 들고 있다. 보안 엔지니어는 그 넷을 읽고 점검표를 docs/보안점검.md에 쓴 뒤, 그 표대로 점검해 결과를 같은 문서에 기록한다. QA의 테스트케이스처럼 이것이 보안의 산출물이고, 사람은 그 문서를 읽고 판정한다. 아래 프롬프트를 그대로 붙여 넣는다.
① 정의 — 서브에이전트 생성
'보안 엔지니어' 서브에이전트 만들어줘. CLAUDE.md의 규칙, docs/아키텍처.md의 접근 제어 전략, docs/ERD.md의 RLS, docs/API명세.md의 인증·권한 오류를 근거로 보안 점검표(docs/보안점검.md)를 쓰고, 그 표대로 코드를 점검해 결과를 문서에 기록한다. 코드는 고치지 않는다(수정은 개발자 역할 몫).서브에이전트를 만든 뒤에는 Claude Code를 한 번 다시 띄운다(/exit 뒤 claude). 새 서브에이전트는 다음 세션부터 보인다.
② 실행 — 점검표 쓰기
보안 엔지니어 서브에이전트로, docs/보안점검.md에 점검표를 작성해줘. 문서 작성만 하고 끝내.이렇게 나오면 성공: docs/보안점검.md가 생기고, 항목마다 무엇을 어떤 근거(CLAUDE.md 규칙 몇 번, 아키텍처 절, ERD 정책, 명세 오류 코드)로 보는지 적혀 있다. 비밀값 노출, 클라이언트의 DB 직접 접근, 다른 사용자 데이터 차단(RLS), 미인증·권한 없음 응답은 반드시 들어 있다 — 넷 중 하나라도 없으면 근거 문서 이름을 짚어 "CLAUDE.md 규칙 3이 빠졌다, 더해줘"처럼 요청한다. 아직 점검은 하지 않았다.
[사람 검토] 점검표를 읽는다. CLAUDE.md의 규칙 다섯 줄과 나란히 놓고, 규칙마다 점검 항목이 있는지 본다. 이 표가 13장에서 기능을 추가할 때마다 다시 돌리는 점검 목록이 된다.
③ 실행 — 점검하고 결과 기록
보안 엔지니어 서브에이전트로, docs/보안점검.md대로 점검하고 항목마다 통과·실패와 위치·원인을 문서에 기록해줘. 수정은 개발자 역할에게 맡길게.이렇게 나오면 성공: docs/보안점검.md의 항목마다 통과·실패가 기록된다. 실패에는 파일 위치와 원인이 적혀 있다. 문제가 없으면 전부 통과로 남고, 문제가 있으면 단계 3에서 개발자에게 넘긴다.
[사람 검증] 비밀값 관련 설정도 직접 확인한다. 1.
.gitignore파일을 열어.env.local이 들어 있는지 확인한다(저장소에 키가 올라가면 사고). 2. AI에게 "클라이언트 번들(.next/static)에서GEMINI·TOSS_SECRET·SUPABASE_DB_URL문자열을 grep해서 0건인지 보여줘"라고 시켜 결과를 눈으로 본다. (배포 후에는 공개 URL에서 브라우저 개발자도구(F12) → Sources에서 같은 문자열로 검색해도 안 나와야 한다.)
QA나 보안 점검에서 문제가 나오면 개발 담당 서브에이전트에게 해당 부분의 수정을 맡긴다. 수정 뒤에는 QA·보안 담당자가 같은 테스트와 점검을 다시 실행한다.
방금 QA 엔지니어와 보안 엔지니어가 보고한 문제를 담당 개발자 서브에이전트(백엔드/프론트엔드)에게 수정하도록 맡겨줘.수정한 뒤 QA 엔지니어에게 docs/테스트케이스.md를 다시 실행해 결과를 갱신하도록, 보안 엔지니어에게 docs/보안점검.md를 다시 점검해 결과를 갱신하도록 요청해줘.이렇게 나오면 성공: 개발자 역할이 지적된 부분만 고치고, 다시 돌린 테스트 3종이 통과하며 보안 점검에서 걸리는 문제가 사라진다. 문제가 처음부터 없었다면 이 단계는 건너뛴다.
docs/테스트케이스.md로 옮겨 쓰고 그대로 실행해 결과를 기록했고, 잘못된 요청을 서버가 거부하는지 확인했다.docs/보안점검.md에 쓰고 그대로 점검해 결과를 기록했다.테스트를 통과하고 보안 점검에서 발견한 문제를 해결했다면 배포를 준비한다. 다음 단계에서는 인프라 엔지니어 서브에이전트에게 배포 작업을 맡긴다.