검증 가능한 /goal 조건 작성하기

상황을 떠올려 보세요. 이미 만들어진 브라우저 게임에서 한 판을 진행해 달라고 에이전트에게 요청합니다. 몇 수를 두고 현재 상황을 설명하더니 멈춥니다. 게임은 아직 진행 중입니다. "계속해"라고 입력하면 다시 말을 움직이고 또 메시지를 기다립니다. 어느 순간 가장 반복적인 일을 하고 있는 사람이 바로 여러분이라는 걸 깨닫게 됩니다.

Goal은 완료 조건이 있는 목표로, /goal 명령으로 에이전트에게 설정합니다. 예를 들어 "페이지에 게임이 끝났다고 표시될 때까지 양쪽을 번갈아 플레이하세요"라고 할 수 있습니다. 작업의 한 차례가 끝날 때마다 별도의 모델이 대화를 확인해 목표를 달성했는지 판단합니다. 아직 달성하지 못했다면 여러분이 "계속해"라고 말하지 않아도 작업이 이어집니다. 결과가 나올 때까지 기다릴 수 있지만, 장애물이나 오류가 작업을 먼저 멈추게 할 수도 있습니다.

먼저 게임에 쓸 완성된 조건부터 살펴본 다음, 검색과 폼, 모바일 페이지의 목표를 작성해 보겠습니다. 각각 명확한 결과와 확인 방법이 있습니다. 에이전트에게 조건 작성을 맡기는 법과 실제 완료를 결과 없는 중단과 구별하는 방법도 알아봅니다.

/goal이 작업을 이어 가는 방식

게임 예시에서는 서로 다른 두 가지 메커니즘이 함께 작동하므로 혼동하기 쉽습니다. 하나는 브라우저에서 클릭하고 수를 입력하며 페이지에 표시된 내용을 읽는 등 실제 동작을 수행합니다. 다른 하나는 아무것도 클릭하지 않고 대화 전체를 읽은 뒤 작업을 계속할지 판단합니다.

첫 번째는 MCP를 통해 미리 연결한 브라우저 도구 Playwright입니다. 두 번째는 /goal 명령으로 시작됩니다. Playwright는 말을 움직이고, /goal은 멈출 시점을 판단합니다. 겉으로는 같은 일이 일어나는 것처럼 보여도 두 기능은 서로 다릅니다.

중요한 점은 마우스를 클릭할 때마다 평가하는 것이 아니라, 에이전트가 작업을 한 차례 마친 뒤, 대략 응답 전체가 끝난 시점에 평가한다는 것입니다. 한 차례의 작업 중에도 말 하나를 움직이고, 결과를 읽고, 그에 반응하는 등 여러 동작을 연달아 수행할 수 있습니다. /goal은 평가할 내용이 생긴 다음에야 개입합니다.

게임 실행 준비하기

조건을 설정하기 전에 예시가 제대로 작동해야 합니다. 페이지가 정해진 주소에서 열리고, 게임에 필요한 도구(여기서는 Playwright)가 이미 연결되어 있으며, 게임이 끝났는지 보여 주는 표시가 페이지에 있어야 합니다.

이 예시에서는 데이터 속성을 사용합니다. 진행 중인 게임에는 data-game-over="false", 끝난 게임에는 data-game-over="true"가 붙습니다. 이 약속은 게임 페이지를 만든 사람이 정한 것이며, 에이전트가 새로 만들어 내는 게 아니라 읽기만 합니다.

확인하는 방법은 간단합니다. 에이전트에게 페이지를 열고 속성값을 읽어 달라고 요청하세요. 막 시작한 게임에서는 false를 받습니다. 정상적인 결과이며, 시작 시점에 기대하는 값입니다.

페이지에 속성이 아예 없다면 아직 목표를 설정할 때가 아닙니다. 조건은 실제로 읽을 수 있는 정보만 근거로 삼을 수 있습니다. 그러니 먼저 표시 자체를 복구해야지, 진행 도중에 대체 표시를 만들어 내면 안 됩니다. 예시를 설정한 다음에는 게임 중간에 기준을 바꾸거나, 시연을 빨리 끝내려고 별도의 타이머를 붙이지 마세요. 조건은 시작부터 끝까지 동일하게 유지됩니다.

준비된 목표 실행하기

이제 실제 명령을 살펴보겠습니다. 이 예시의 조건은 다음처럼 작성할 수 있습니다.

/goal 페이지 인터페이스를 통해 양쪽을 번갈아 플레이하세요.
매 수를 둔 뒤 data-game-over를 읽고 페이지에 보이는 내용을 보여 주세요.
data-game-over가 true가 되면 게임이 끝난 것으로 봅니다.
게임을 40수 진행한 뒤에도 끝나지 않으면 멈추고
막힌 지점을 설명하세요. 게임 코드는 변경하지 마세요.

문구를 부분별로 나눠 보겠습니다. 이 구성은 여러분의 과제에도 활용할 수 있습니다.

• "페이지 인터페이스를 통해 플레이하세요"는 에이전트가 실제로 수행하고 대화에서 보여 줄 수 있는 측정 가능한 동작입니다.
• "data-game-over가 true가 되면 게임이 끝난 것으로 봅니다"는 여기서 실제 결과로 인정되는 유일한 조건입니다. 평가기가 대화에서 바로 이것을 찾습니다.
• "매 수를 둔 뒤 읽고 보여 주세요"는 평가기가 확인할 수 있게 해 주는 근거입니다. 이 문구가 없으면 평가기는 확인할 대상이 없습니다.
• "게임을 40수 진행한 뒤에도 끝나지 않으면 멈추고 설명하세요"는 true가 되지 않을 때를 위한 별도의 지시입니다. 성공 조건의 일부가 아니라, 성공하지 못했을 때 작업을 끝내는 방법입니다. 목표의 범위를 제한할 뿐 결과를 대신하지는 않습니다. 또한 프로그램이 강제하는 타이머가 아니라 텍스트에 적힌 지시이므로, 이것 역시 대화를 바탕으로 평가합니다.
• "게임 코드는 변경하지 마세요"는 에이전트가 결과를 얻는 동안 일어나서는 안 되는 일을 정합니다.

실제 결과는 미리 알 수 없습니다. 구체적인 승자나 게임 길이, 게임이 끝날지 여부까지 약속할 수는 없습니다. 다만 에이전트가 무엇을 보여 줘야 하는지는 분명합니다. 읽어 온 게임 상태와 작업을 계속하거나 멈추는 이유입니다.

조건의 구성 요소

"과제가 끝나는 시점은..."이라는 문장으로 시작하세요. 뒤에 "모든 것이 더 좋아졌을 때"라고 이어지면 에이전트가 여러분의 의도를 추측해야 합니다. 판단이 아니라 눈으로 확인할 수 있는 동작으로 바꾸세요. 예를 들어 "검색어를 지우면 모든 카드가 다시 표시된다"처럼요. 수정된 검색처럼 하나의 결과를 설명한다면 확인 항목이 여러 개여도 괜찮습니다.

• 결과를 명시하세요. "검색 수정"은 방향만 제시하지만, "이름으로 카드를 찾고 검색어를 지우면 전체 목록을 표시한다"는 완료 기준을 정합니다.
• 확인 방법을 적으세요. 무엇을 열고, 무엇을 입력하며, 어떤 응답이 예상되는지 쓰세요. 평가기가 읽을 수 있도록 실제 결과를 대화에 보여 달라고 요청하세요.
• 변경 범위를 제한하세요. 스타일만 바꿔야 한다면 그렇게 말하세요. 이미 완성된 게임을 확인하는 경우 원하는 결과를 만들려고 게임 코드를 바꾸지 못하도록 하세요.
• 성공하지 못했을 때의 중단 조건도 정하세요. 예를 들어 세 번 수정하고 다시 확인한 뒤에도 남은 문제가 있다면 에이전트가 이를 설명하도록 합니다. 이는 작업 범위의 한계이지, 완료를 선언하는 또 하나의 방법이 아닙니다.

실행 전에 에이전트가 필요한 페이지와 파일, 도구에 접근할 수 있는지 확인하세요. 조건에 적은 주소와 요소 이름은 실제 프로젝트와 일치해야 합니다. 시도 횟수를 텍스트로 제한하면 작업을 관리하는 데 도움이 되지만, 시간이나 비용을 기술적으로 강제하는 제한은 아닙니다.

되돌아가는 화살표에 주목하세요. 결과에 아직 도달하지 못했다면 에이전트는 다음 작업 차례를 받아 문제를 수정하고 다시 확인할 수 있습니다. 하지만 이 순환을 벗어났다고 해서 언제나 성공한 것은 아닙니다. 장애물이나 미리 정한 한계에 도달했다면 이를 따로 밝혀야 합니다. 그림은 조건의 작동 방식을 보여 주며, 에이전트와 평가기는 대화를 보고 시도 횟수의 한계를 확인합니다.

직접 활용할 세 가지 예시

아래는 이미 존재하는 페이지에 사용할 수 있는 예시 조건입니다. 실행 전에 주소와 데이터, 기대 동작을 여러분의 환경에 맞게 바꾸세요. 완료한 작업의 보고서가 아니라 조건 예시입니다.

카탈로그 검색 수정하기

로컬 카탈로그에 "Atlas"와 "Orion" 카드가 있지만 검색어를 지운 뒤에도 목록이 비어 있다고 해 보겠습니다. "검색을 제대로 만들어 줘"라는 요청으로는 원하는 동작을 알 수 없습니다. 다음 세 가지 경우를 구체적으로 지정하는 편이 낫습니다.

/goal http://localhost:3000/catalog의 검색을 수정하세요.
"atlas"를 검색하면 "Atlas" 카드가 나오고,
"zzzz-no-match"를 검색하면 "결과가 없습니다"가 표시되며,
입력란을 지우면 기존 카드가 모두 돌아오면 완료입니다.
Playwright로 세 가지 경우를 확인하고 대화에 검색어,
기대 결과, 실제로 표시된 카드 또는 메시지를 보여 주세요.
마지막 수정 후 세 가지 확인을 모두 다시 수행하세요.
검색 로직만 변경하고 카탈로그 데이터와 스타일은 그대로 두세요.
세 번 수정하고 확인한 뒤에도 문제가 남으면 멈추고
아직 작동하지 않는 경우를 나열하세요.

여기서 "모두"라는 말이 중요합니다. 카드 하나를 찾았다고 검색이 고쳐진 것은 아닙니다. 카탈로그 데이터는 그대로여야 하므로 카드 이름을 바꿔서 원하는 결과를 만들 수도 없습니다. 마지막 수정 뒤 다시 확인하는 것도 중요합니다. 입력란을 지우는 동작을 고치다가 검색 자체를 망가뜨렸을 수 있으니까요.

수정 없이 폼 확인하기

목표의 결과가 관찰 내용 목록일 수도 있습니다. 이미 완성된 회원가입 폼을 확인하되 수정 사항은 따로 논의하고 싶다고 해 보겠습니다. 이 경우 오류가 발견되더라도 모든 경우를 확인하면 목표가 끝납니다.

/goal http://localhost:3000/signup의 폼을 Playwright로 확인하세요.
프로젝트 파일은 변경하지 마세요.
각각 빈 폼에서 시작해 다음 두 가지 경우를 확인하세요.
1. 입력란을 채우지 않고 "가입하기"를 클릭합니다.
필수 입력 안내가 표시되고 가입은 진행되지 않아야 합니다.
2. 이메일 입력란에 "alex"를 넣고 나머지 필수 입력란은
유효한 테스트 값으로 채운 뒤 버튼을 클릭합니다.
이메일 형식 오류가 표시되고 가입은 진행되지 않아야 합니다.
두 경우 모두 입력한 값, 기대한 결과, 페이지에 표시된 내용,
차이가 있는지를 대화에 보고하면 완료입니다.
유효한 이메일로 폼을 제출하거나 계정을 만들지 마세요.
페이지나 요소를 열 수 없다면 확인을 멈추고
확인하지 못한 경우와 이유를 적으세요.

"폼을 확인한다"와 "폼이 작동하도록 만든다"는 서로 다른 과제입니다. 여기서는 에이전트가 두 경우를 실제로 확인하고 결과를 보여 줬다면 폼에 오류가 있어도 보고를 마칠 수 있습니다. 하지만 페이지에 접근할 수 없다면 완료할 수 없습니다. 추측은 관찰을 대신하지 못합니다.

모바일 화면에 맞게 페이지 조정하기

"모바일에서 보기 좋게 만들어 줘"라고 하면 에이전트의 판단에 맡기는 부분이 너무 많습니다. 페이지와 창 크기, 계속 사용할 수 있어야 하는 요소를 구체적으로 정하세요.

/goal http://localhost:3000 페이지의 스타일을
창 크기 390x844와 1440x900에 맞게 수정하세요.
두 크기 모두 가로 스크롤이 없고,
제목과 "시작" 버튼이 완전히 보이며 겹치지 않고,
"시작"을 누르면 게임 섹션이 계속 열리면 완료입니다.
마지막 수정 후 Playwright로 두 크기를 모두 확인하세요.
스크린샷과 클릭 결과, 페이지 루트 요소의 측정값인
scrollWidth와 clientWidth를 보여 주세요.
scrollWidth는 clientWidth보다 크면 안 됩니다.
CSS만 변경하세요. 스크롤을 없애려고 콘텐츠를 숨기거나
잘라내지 마세요. 텍스트와 게임 동작은 그대로 유지하세요.
세 번 수정하고 확인한 뒤에도 조건을 충족하지 못하면
멈추고 남은 차이를 보여 주세요.

여기서 크기는 브라우저 창의 너비와 높이를 픽셀로 나타냅니다. scrollWidth는 가장자리 밖에 있는 부분까지 포함한 콘텐츠 너비이고, clientWidth는 사용할 수 있는 너비입니다. 두 값을 비교하면 넘침을 찾는 데 도움이 되지만, 그것만으로 텍스트가 잘리지 않았거나 버튼을 사용할 수 있음을 증명하지는 못합니다. 그래서 조건에 스크린샷과 클릭 확인도 포함했습니다. 두 가지 크기를 확인했다고 모든 기기에서 편리하다는 뜻은 아닙니다. 두 크기는 이 과제의 범위를 정할 뿐입니다.

에이전트에게 goal 초안 요청하기

조건을 처음부터 직접 작성할 필요는 없습니다. Claude Code Best Practice에는 커뮤니티의 팁 두 가지가 소개되어 있습니다. 프로젝트 맥락을 바탕으로 에이전트에게 목표를 제안해 달라고 하거나, 대화와 파일을 읽은 뒤 조건 문구를 작성하도록 맡기는 방법입니다. 아래는 작은 과제에 적용한 예입니다.

오래 걸릴 작업으로 무엇을 맡겨야 할지 아직 모르겠다면 /goal 없이 일반 메시지부터 보내세요.

현재 대화와 과제에 관련된 프로젝트 파일을 읽어 주세요.
검증 가능한 결과로 이어질 만한 유용한 목표 세 가지를 제안하세요.
각 목표의 결과와 확인 방법, 변경 범위, 실행 전에 더 필요한
정보를 적어 주세요. 우리가 합의한 내용을 기준으로 하세요.
아직 목표를 실행하거나 파일을 변경하지 마세요.
의도가 분명하지 않다면 질문하세요.

목표 하나를 선택하세요. 오래 작업하는 것 자체가 장점은 아닙니다. 몇 시간 동안 막연하게 "개선"하는 것보다 검색을 제대로 고치는 편이 유용합니다. 과제가 이미 명확하다면 첫 요청은 건너뛰고 조건 초안을 바로 요청해도 됩니다.

선택한 과제에 대해 대화와 프로젝트 파일, 문서를 바탕으로
/goal 문구를 작성하세요. 아직 아무 작업도 하지 마세요.
관찰 가능한 결과와 확인 방법, 대화에서 보여 줄 내용을 적으세요.
변경 범위와 성공하지 못했을 때의 중단 조건도 추가하세요.
주소나 명령, 완료 기준을 지어내지 마세요.
프로젝트에서 찾거나 저에게 확인하세요.
완성된 문구 하나를 제시하고 불분명한 점은 따로 나열하세요.

초안을 보내기 전에 의미를 확인하세요. 결과가 여러분의 의도와 맞나요? 적힌 페이지가 실제로 있나요? 에이전트가 데이터 변경이나 기능 추가까지 허용한 것은 아닌가요? 마지막에 불분명한 점이 남아 있다면 먼저 해결하세요. 내용을 확정한 뒤 실행해야 합니다. /goal 명령은 입력 즉시 작업을 시작합니다.

상태 확인 및 작업 중단하기

목표가 활성화된 동안 진행 상태를 확인할 수 있습니다. 인수 없이 /goal을 입력하면 조건, 지금까지 지난 시간과 작업 차례 수, 평가기가 반환한 마지막 사유가 표시됩니다.

목표를 일찍 중단할 수도 있습니다. /goal clear 명령을 사용하면 게임이 끝나지 않았더라도 조건이 해제됩니다.

여기서 확인된 결과는 하나뿐입니다. 조건이 충족되어 평가기의 답변에 그 사실이 나타난 경우입니다. /goal clear 명령으로 목표를 해제하는 것도 분명한 결말이지만, 이것은 멈추겠다는 여러분의 결정이지 작업이 끝났다는 증거가 아닙니다. 목표가 자동으로 멈추는 다른 경우는 결과를 확인해 주지 않습니다.

평가 모델이 받는 정보

/goal 평가기는 페이지 자체가 아니라 대화를 봅니다. 에이전트가 작성한 내용과 브라우저에서 관찰한 결과를 대화에 복사한 내용입니다. 평가기에는 자체 도구가 없습니다. 페이지를 다시 열거나 직접 명령을 실행하지 않고, 이미 쌓인 텍스트만 읽습니다.

여기서 간단한 결론을 얻을 수 있습니다. 에이전트가 "게임이 끝났습니다"라고 말하는 것만으로는 평가기나 여러분에게 아무것도 입증되지 않습니다. 실제로 페이지에서 읽은 결과가 근거가 됩니다. 바로 data-game-over 값입니다. 첫 번째는 주장이고 두 번째는 관찰입니다. 비슷하게 들릴 수 있어도 서로 다릅니다.

이 신호가 알려 주는 범위도 알아야 합니다. data-game-over는 특정 애플리케이션의 상태, 즉 페이지 작성자가 구현해 둔 내용을 알려 줍니다. 전체 게임이 체스 규칙에 따라 단 한 번의 실수 없이 진행되었는지는 말해 주지 않습니다. 마찬가지로 스크롤이 없다고 버튼이 작동한다는 뜻은 아닙니다. 원하는 결과에 맞는 신호를 고르고, 그 신호가 말해 주는 것 이상으로 해석하지 마세요.

작업 방식에 생기는 변화

여러분의 과제에도 같은 짧은 절차를 적용할 수 있습니다.

• 명확한 결과와 실제로 사용할 수 있는 확인 방법;
• 변경 범위와 중단 기준을 담아 /goal 명령으로 설정한 조건;
• 언제든 확인할 수 있는 상태: 인수 없는 /goal;
• 관찰과 확인 결과로 뒷받침되는 결론;
• 작업이 막히거나 조건이 적절하지 않으면 /goal clear 명령으로 직접 해제한 목표.

작업을 자동으로 계속하는 것과 다음에 무엇을 할지 결정하는 것은 별개입니다. 한 세션 안에서 첫 번째는 /goal에 맡길 수 있습니다. 실제로 어떤 결과가 나왔는지 확인하고, 끝나지 않은 목표를 해제하고, 다음 과제를 정하는 일은 여전히 여러분의 몫입니다.

평가기의 정확한 동작과 상태 형식은 Claude Code 버전에 따라 조금씩 다를 수 있습니다. 페이지에 직접 접근하는 대신 대화를 바탕으로 평가한다는 원칙은 동일합니다.