6.2 소크라틱 프롬프팅과 적대적 리뷰 실습 가이드

이번 실습에서는 뉴스레터 구독 기능을 곧바로 만들지 않습니다. 먼저 질문으로 요구사항을 정리하고 설계를 승인합니다. 그다음 테스트가 포함된 계획을 세워 구현을 맡기고, 마지막에는 Codex로 공개 전에 남은 위험을 찾습니다.

💡 사전 요구사항: 6.1 스타터 웹사이트 세팅 가이드를 먼저 완료해 주세요. 이 가이드는 magma-content-site 프로젝트에서 시작합니다.

이번 실습에서 익힐 흐름

전체 순서는 다음과 같습니다.

1. Hermes 기본 개발 스킬을 확인합니다.
2. Superpowers와 Codex 플러그인을 설치합니다.
3. 새 세션이 프로젝트를 먼저 읽게 합니다.
4. 질문을 주고받으며 요구사항과 설계를 정합니다.
5. 테스트부터 시작하는 상세 계획을 만듭니다.
6. 만드는 역할과 검토하는 역할을 나눠 구현합니다.
7. 브라우저와 테스트 결과로 기능을 확인합니다.
8. Codex로 공개 전에 남은 위험을 찾고 사용자가 최종 판단합니다.

1단계. Hermes 기본 개발 스킬 확인하기

Hermes에는 개발 과정에서 하나씩 사용할 수 있는 기본 스킬이 있습니다. 이번 실습에서는 다음 다섯 가지를 확인합니다.

• plan: 구현 전에 작업 순서를 정합니다.
• systematic-debugging: 추측하지 않고 오류 메시지와 재현 조건부터 확인합니다.
• test-driven-development: 구현 전에 실패해야 하는 테스트부터 작성합니다.
• requesting-code-review: 바뀐 코드와 테스트 결과를 다른 검토자에게 확인받습니다.
• simplify-code: 동작은 그대로 두고 불필요한 중복과 복잡함을 줄입니다.

1-1. 계획만 요청하기

아직 코드를 바꾸지 않고 구현 순서만 보고 싶을 때 사용합니다.

/plan 뉴스레터 구독 폼 작업의 구현 순서만 세워 줘. 아직 파일은 수정하지 마.

프로젝트 파일을 읽은 뒤 파일별 작업 순서가 나오면 성공입니다. plan은 기능 코드를 수정하지 않아도 .hermes/plans 아래에 계획 문서를 만들 수 있습니다.

1-2. 오류 조사 순서 확인하기

/systematic-debugging 구독 폼을 제출하면 오류가 난다고 가정하고, 재현과 증거 수집부터 조사 순서를 보여줘.

브라우저와 서버의 오류 메시지, 같은 오류가 나타나는 조건, 요청이 처리되는 순서부터 확인하면 정상입니다.

1-3. 실패 테스트부터 작성하는 순서 확인하기

/test-driven-development 이메일 검증 함수를 만든다고 가정하고 실패 테스트부터 어떤 순서로 작성할지 보여 줘.

정상 이메일뿐 아니라 빈값과 잘못된 형식, 앞뒤 공백, 영문 대소문자 처리까지 테스트 항목으로 나오면 됩니다.

1-4. 코드 검토 순서 확인하기

/requesting-code-review 아직 변경 파일은 없으니 검증을 실행하지 말고, 커밋 전에 확인하는 단계만 요약해 줘.

변경 범위와 요구사항을 먼저 비교하는 순서가 나오면 됩니다. 이어서 보안과 기존 기능을 확인하고 테스트, 코드 검사, 빌드를 실행합니다.

1-5. 코드를 안전하게 정리하는 기준 확인하기

/simplify-code 동작은 유지하면서 폼 처리 코드의 중복을 줄일 때 확인할 기준을 보여 줘.

브라우저 검증과 서버 검증을 무조건 합치지 않고, 테스트로 현재 동작을 지킨 뒤 안전한 부분만 정리하는 설명이 나오면 됩니다.

⚠️ Unknown command가 나오는 경우 스킬이 삭제된 것이 아니라 해당 프로필의 보관함으로 이동했을 수 있습니다. 강의와 같이 Sam 프로필을 사용한다면 아래 순서로 확인해 보세요.

sam curator list-archived
sam curator restore systematic-debugging
sam curator restore test-driven-development
sam curator restore requesting-code-review
sam curator restore simplify-code

다른 프로필을 사용한다면 첫 단어 sam을 자신의 프로필 이름으로 바꿔 주세요. 복원한 스킬은 새 세션에서 확인하는 것이 가장 안전합니다.

2단계. 원작과 Hermes용 플러그인 확인하기

Superpowers의 원작자는 GitHub에서 obra라는 이름으로 활동하는 Jesse Vincent입니다. 원작은 에이전트가 바로 코드를 만들지 않게 돕는 공개 프로젝트입니다. 질문과 설계 승인을 먼저 거친 뒤 계획, 구현, 검증 순서로 진행하게 합니다.

• 원작 obra/superpowers
• Dante Labs hermes-superpowers
• Dante Labs hermes-codex-plugin

hermes-superpowers는 원작의 작업 흐름을 Hermes에서 사용할 수 있게 다시 만든 버전입니다. Hermes에 같은 역할의 기본 스킬이 있으면 그대로 사용합니다. 그 앞뒤에 질문과 승인, 작업 전달, 마지막 확인 단계를 연결합니다.

hermes-codex-plugin은 Codex에게 코드 검토를 맡기기 위한 플러그인입니다. 이번 실습에서는 기능을 만드는 역할이 아니라 공개 전에 위험을 찾는 두 번째 검토자로 사용합니다.

플러그인 설치하기

Hermes 바깥의 일반 터미널에서 실행합니다.

hermes plugins install dandacompany/hermes-superpowers --enable
hermes plugins install dandacompany/hermes-codex-plugin --enable
hermes plugins list --plain --no-bundled

목록에 superpowers와 codex가 모두 enabled로 보이면 설치가 끝난 것입니다. 플러그인은 새 세션부터 적용되므로 현재 Hermes 세션을 끝내고 다시 시작해 주세요.

💡 Codex 모델 이름을 설치 명령에 따로 넣을 필요는 없습니다. Codex 플러그인은 사용자의 ~/.codex/config.toml 설정을 따릅니다.

3단계. 새 세션이 프로젝트를 먼저 읽게 하기

강의를 듣는 우리는 6.1에서 이 사이트를 만들었다는 사실을 알고 있습니다. 하지만 새로 시작한 Hermes 세션은 그 앞선 과정을 자동으로 알지 못합니다. 따라서 기능을 요청하기 전에 현재 폴더와 주요 파일부터 확인하게 해야 합니다.

프로젝트 폴더에서 Sam 시작하기

cd ~/.hermes/profiles/sam/workspace/magma-content-site
hermes chat -p sam

새 세션에서 플러그인이 정상적으로 적용됐는지 확인합니다.

/superpowers

superpowers loaded와 현재 작업 단계가 보이면 정상입니다.

프로젝트 조사 요청하기

아직 파일을 수정하지 않도록 분명히 적어 주세요.

현재 작업 폴더의 프로젝트를 먼저 조사해 줘. 아직 파일은 수정하지 마.
README와 package.json, 주요 소스 디렉터리, 현재 홈 화면 구성을 확인하고 아래 내용을 짧게 보고해 줘.
1. 이 프로젝트가 무엇을 하는 사이트인지
2. 사용 중인 기술 스택과 실행·검증 명령
3. 뉴스레터 구독 폼을 붙일 수 있는 화면 위치
4. 작업 전에 확인해야 할 불확실한 점

사이트의 목적과 사용 기술, 실행 명령, 폼 위치 후보가 실제 파일과 맞는지 확인합니다. 에이전트가 추천한 폼 위치는 아직 확정된 결정이 아닙니다.

4단계. 질문으로 요구사항과 설계 정하기

실제로 사용할 때는 요청을 길게 작성할 필요가 없습니다. 아래처럼 목적과 사용할 스킬만 알려줘도 Superpowers가 한 번에 하나씩 질문하며 요구사항을 구체화합니다.

이 프로젝트에 뉴스레터 구독 폼을 추가하고 싶어.
superpowers:brainstorming을 사용해서 요구사항과 설계부터 정리해 줘.
아직 구현하지 말고 질문을 한 번에 하나씩 해 줘.

강의와 비슷한 질문 범위와 종료 지점을 재현하고 싶다면 아래 상세 프롬프트를 사용하세요.

좋아. 방금 파악한 이 프로젝트에 뉴스레터 구독 폼을 추가하고 싶어.
superpowers:brainstorming을 사용해 요구사항과 설계를 먼저 정리해 줘.

아직 구현하거나 파일을 수정하거나 구현 계획을 작성하지 마.
이번 대화는 텍스트로만 진행하고, 아래 여섯 결정 범위를 순서대로 다뤄 줘.
1. 기능의 목적과 화면 위치
2. 수집할 정보와 개인정보 범위
3. 입력 정리, 형식 확인, 중복 처리
4. 제출 중, 성공, 실패 상태의 사용자 경험
5. 저장 방식, 데이터 보존, 동시 요청의 한계
6. 테스트 성공 조건과 공개 승인 조건

진행 규칙:
- 한 메시지에는 질문을 하나만 해 줘.
- 가능하면 추천안을 첫 번째로 둔 2~3개 선택지와 추천 이유 한 줄을 제시해 줘. 직접 답하는 선택도 허용해 줘.
- 프로젝트 조사나 앞선 답변에서 이미 확정된 내용은 다시 묻지 마.
- 치명적인 불확실성만 후속 질문으로 묻고, 추가 질문은 최대 2개로 제한해 줘.
- 대화 중에는 결정 사항과 미결 사항을 채팅 안에서 누적해 줘. 승인 전에는 문서 파일을 만들지 마.
- 질문이 끝나면 구현 접근안 2~3개와 장단점, 추천안을 제시해 줘.
- 마지막에는 구성 요소, 데이터가 이동하는 순서, 오류 처리, 테스트, 공개 보류 조건이 포함된 짧은 설계를 제시하고 내 승인을 기다려 줘.

답변할 때 확인할 여섯 가지

강의에서는 다음과 같이 결정했습니다.

1. 콘텐츠 업데이트를 받는 폼을 브랜드 소개와 최신 글 사이에 둡니다.
2. 이름 없이 이메일만 받습니다.
3. 이메일의 공백을 없애고 영문을 소문자로 바꾼 뒤 브라우저와 서버에서 형식을 확인합니다.
4. 처음 등록한 주소와 이미 등록된 주소에 같은 성공 메시지를 보여줍니다.
5. 제출 중에는 버튼을 잠그고, 실패하면 입력값을 유지합니다.
6. 로컬 파일 저장은 개발 환경에서만 사용하고 실제 서비스 공개는 보류합니다.

⚠️ 강의의 선택을 그대로 따라야 하는 것은 아닙니다. 자신의 프로젝트라면 개인정보 범위와 저장 방법, 공개 조건을 직접 판단해 주세요.

설계가 보이기 전에는 승인하지 않기

질문이 끝났더라도 구현 방법의 비교와 최종 설계가 화면에 나오지 않았다면 승인하지 마세요. 다음처럼 보완을 요청할 수 있습니다.

아직 구현 접근안 2~3개와 장단점, 추천안, 최종 설계 본문이 화면에 제시되지 않았어.
먼저 보여주고 다시 승인을 요청해 줘.

승인 질문만 계속 반복되면 같은 문장을 계속 입력하지 마세요. 현재 승인 창을 취소하고 /superpowers로 상태를 확인한 뒤 새 세션을 시작하는 편이 안전합니다. 새 세션에는 이미 결정한 내용을 전달하고 접근안 비교와 설계 정리부터 다시 요청하면 됩니다.

설계 문서에 요구사항과 데이터가 이동하는 순서가 들어갔는지 확인하세요. 오류 처리와 테스트, 공개 보류 조건까지 확인한 뒤 명시적으로 승인합니다.

5단계. 테스트가 포함된 상세 계획 만들기

설계를 승인한 다음에는 긴 파일명을 다시 적지 않아도 됩니다. 같은 세션에서 방금 승인한 설계를 가리켜 요청해 보세요.

방금 승인한 설계를 기준으로 superpowers:writing-plans를 사용해서 테스트 우선 상세 구현 계획을 작성해 줘.

계획에는 다음 내용이 있어야 합니다.

• 어떤 파일을 새로 만들거나 수정하는지
• 먼저 실패해야 하는 테스트가 무엇인지
• 테스트를 통과시키기 위한 최소 구현이 무엇인지
• 각 작업을 확인할 명령이 무엇인지
• 실제 서비스 공개 전에 해결할 조건이 무엇인지

강의에서는 테스트 도구 준비부터 마지막 빌드까지 8개 작업으로 나뉜 계획이 만들어졌습니다. 현재 프로젝트에 테스트 도구가 없다면 첫 작업에 Vitest 같은 도구 설치가 포함될 수 있습니다.

6단계. 만드는 역할과 검토하는 역할을 나누기

계획 승인 화면에서는 서브에이전트 기반 구현 진행을 선택합니다. 선택 화면이 없다면 다음처럼 자연어로 요청할 수 있습니다.

이 계획으로 진행해 줘.
superpowers:subagent-driven-development를 사용해서 작업마다 만드는 역할과 검토하는 역할을 분리해 줘.
각 작업은 테스트를 먼저 작성하고, 완료할 때마다 테스트 결과와 커밋을 남겨 줘.
마지막에는 superpowers:verification-before-completion으로 전체 검증 결과를 보여 줘.

기존 작업 폴더에 관계없는 변경이 있다면 별도 작업 폴더를 사용할지 질문할 수 있습니다. 기존 변경을 보존하려면 권장 선택지인 별도 작업 폴더를 선택하세요.

진행 상태 확인하기

/agents

/agents는 실행 중인 작업과 위임 상태를 확인합니다. 주 에이전트가 idle이어도 따로 맡긴 작업이 running이면 구현은 진행 중입니다.

⚠️ /bg는 상태 확인 명령이 아닙니다. 새로운 백그라운드 작업을 보내는 명령이므로 진행 상황은 /agents 또는 /tasks로 확인하세요.

강의에서는 작업별 검토가 실제로 두 가지 문제를 찾았습니다.

• 파일 저장에 실패하면 .tmp 임시 파일이 남을 수 있었습니다.
• 구독 요청의 값이 비어 있거나 요청 내용이 잘못된 경우를 확인하는 테스트가 빠져 있었습니다.

각 문제는 실패 테스트를 추가한 뒤 코드를 고치고 다시 테스트하는 순서로 해결했습니다.

7단계. 개발 서버와 실제 화면 확인하기

테스트 통과만 보고 끝내지 않고 브라우저에서도 확인합니다.

현재 구현을 개발 서버로 띄워줘. 브라우저에서 확인할 수 있는 접속 주소도 알려줘.

다음 순서로 확인하세요.

1. 브랜드 소개와 최신 글 사이에 폼이 보이는지 확인합니다.
2. 잘못된 이메일이 형식 오류로 막히는지 확인합니다.
3. 정상 이메일을 제출하면 감사 메시지가 나오는지 확인합니다.
4. 같은 이메일을 다시 제출해도 같은 성공 메시지가 나오는지 확인합니다.
5. 저장 파일에 공백 제거와 소문자 변환을 마친 이메일이 한 건만 있는지 확인합니다.

강의의 최종 결과는 테스트 파일 5개, 테스트 36개 통과였습니다. 코드 검사와 타입 오류 검사, 실제 배포용 빌드도 성공했습니다.

💡 이번 범위에는 구독 확인 메일을 보내는 기능이 없습니다. 이메일 주소를 저장하는 기능과 실제 메일을 발송하는 기능을 구분해 주세요.

8단계. Codex로 공개 전에 남은 위험 찾기

테스트가 모두 통과해도 실제 서비스에 바로 공개해도 된다는 뜻은 아닙니다. 테스트에서 다루지 않은 저장 방식과 개인정보, 여러 사용자의 동시 요청도 확인해야 합니다.

비교 기준 커밋 정하기

적대적 리뷰는 어느 시점부터 바뀐 코드를 볼지 기준이 필요합니다. 강의에서는 구현 전에 승인한 설계 커밋 4e165f8을 기준으로 사용했습니다.

자신의 프로젝트에서는 구현을 시작하기 직전 커밋 ID로 바꿔 주세요. 현재 구현이 이미 main에 들어갔다면 --base main을 사용하지 마세요. 변경 내용이 잡히지 않을 수 있습니다.

/codex-adversarial-review --base 기준_커밋_ID 뉴스레터 구독 기능을 배포하면 안 되는 이유를 찾아 줘. 이메일 검증, 중복 가입, 개인정보, 저장 지속성, 동시 제출, 오류 복구와 롤백을 집중적으로 검토해 줘.

강의와 같은 저장소 상태를 재현하는 경우에는 다음 명령을 사용했습니다.

/codex-adversarial-review --base 4e165f8 뉴스레터 구독 기능을 배포하면 안 되는 이유를 찾아 줘. 이메일 검증, 중복 가입, 개인정보, 저장 지속성, 동시 제출, 오류 복구와 롤백을 집중적으로 검토해 줘.

강의에서 실제로 발견한 문제

1. 공개 환경에서는 폼이 숨겨지고 구독 요청도 거절돼 실제 사용자가 기능을 쓸 수 없습니다.
2. 두 사람이 거의 동시에 제출하면 한 사람의 이메일이 사라질 수 있습니다.
3. 로컬 파일은 다시 배포한 뒤 데이터가 남는다는 보장이 없습니다.
4. 이메일 주인이 직접 가입했는지 확인하는 절차와 반복 요청 제한이 없습니다.
5. 개인정보 처리방침 페이지와 구독 취소, 데이터 삭제 절차가 없습니다.

리뷰가 끝났는지는 다음 명령으로 확인합니다.

/codex-status

Codex 리뷰는 문제와 해결 방향을 알려주지만 소스 파일을 직접 수정하지 않습니다. 리뷰 결과를 읽고 수정할지, 위험을 받아들일지, 공개를 미룰지는 사용자가 결정합니다.

전체 입력 순서 한 장

아래 블록은 이번 실습의 핵심 입력만 순서대로 모은 것입니다. 플러그인 설치 뒤에는 반드시 새 Hermes 세션을 시작하세요.

/superpowers

현재 작업 폴더의 프로젝트를 먼저 조사해 줘. 아직 파일은 수정하지 마.
README와 package.json, 주요 소스 디렉터리, 현재 홈 화면 구성을 확인하고 사이트 목적, 실행 명령, 뉴스레터 폼 위치 후보, 불확실한 점을 보고해 줘.

이 프로젝트에 뉴스레터 구독 폼을 추가하고 싶어.
superpowers:brainstorming을 사용해서 요구사항과 설계부터 정리해 줘.
아직 구현하지 말고 질문을 한 번에 하나씩 해 줘.

방금 승인한 설계를 기준으로 superpowers:writing-plans를 사용해서 테스트 우선 상세 구현 계획을 작성해 줘.

이 계획으로 진행해 줘.
superpowers:subagent-driven-development를 사용해서 작업마다 만드는 역할과 검토하는 역할을 분리해 줘.
각 작업은 테스트를 먼저 작성하고, 마지막에는 전체 검증 결과를 보여 줘.

/agents

현재 구현을 개발 서버로 띄워줘. 브라우저에서 확인할 수 있는 접속 주소도 알려줘.

/codex-adversarial-review --base 기준_커밋_ID 뉴스레터 구독 기능을 배포하면 안 되는 이유를 찾아 줘. 이메일 검증, 중복 가입, 개인정보, 저장 지속성, 동시 제출, 오류 복구와 롤백을 집중적으로 검토해 줘.

/codex-status

자주 만나는 문제

/systematic-debugging이 Unknown command로 나옵니다

sam curator list-archived로 보관된 스킬을 확인하고 필요한 스킬을 복원하세요. 복원 뒤에는 새 세션을 시작합니다.

플러그인을 설치했는데 /superpowers가 나오지 않습니다

설치한 플러그인은 이미 열려 있던 세션에 바로 나타나지 않을 수 있습니다. 현재 세션을 끝내고 hermes chat -p sam으로 새 세션을 시작하세요.

승인 질문만 반복됩니다

설계 본문이 나오지 않았다면 승인하지 마세요. 현재 승인 창을 취소하고 새 세션에서 이미 결정한 내용을 전달해 설계 정리부터 다시 시작합니다.

/agents에서 주 에이전트가 idle입니다

주 에이전트가 대기 중이라는 뜻입니다. 별도 구현 작업이 running으로 표시되면 작업은 계속 진행 중입니다.

서브에이전트가 시간 초과나 오류로 끝났습니다

결과가 모두 사라졌다고 단정하지 마세요. Git 변경 파일과 최근 커밋, 테스트 결과를 다시 확인한 뒤 이어서 진행하면 됩니다.

Codex 리뷰에서 변경 내용이 보이지 않습니다

현재 구현이 이미 main에 들어갔다면 --base main으로는 차이가 나오지 않습니다. 구현 직전의 설계 승인 커밋이나 기능 시작 커밋을 기준으로 사용하세요.

마무리

이번 실습의 핵심은 긴 프롬프트를 외우는 것이 아닙니다. 짧게 시작해도 질문을 통해 필요한 결정을 하나씩 정할 수 있습니다.

중요한 것은 구현 전에 설계를 확인하고, 만드는 역할과 검토하는 역할을 나누는 것입니다. 마지막에는 테스트 결과만 보지 않고 실제 서비스에서 생길 위험까지 확인해야 합니다.

진행하시다가 막히는 부분이 생기면 언제든 인프런 Q&A에 질문 남겨주세요.