결과를 검토할 수 있도록 AI 어시스턴트에게 작업을 어떻게 써야 하나요?
변경은 하나만 요청하고, 어디에 넣을지와 바뀌면 안 되는 것을 말하고, 통과나 실패가 나오는 확인을 주고, 한 일을 보고하게 하세요.
변경은 하나만, 몇 분 안에 직접 해 볼 수 있을 만큼 작게 요청하세요. 그 변경이 어디에 들어가는지, 무엇이 그대로 남아야 하는지, 잘 되는지 어떻게 확인하는지, 그리고 무엇을 돌려받고 싶은지를 말하세요. 이렇게 쓴 작업은 여러분이 판단할 수 있는 형태로 돌아옵니다. 바뀐 파일의 짧은 목록, 통과했거나 실패한 확인, 그리고 직접 플레이해서 확인할 수 있는 게임입니다. 모호한 작업은 "다 된 것처럼 보이는" 큰 변경으로 돌아오고, 그러면 확인은 전부 여러분의 몫이 됩니다.
검토할 수 있는 작업에는 무엇이 필요한가요?
다섯 부분입니다. 대부분의 작업에는 다섯 가지가 모두 필요하고, 각각 한두 문장이면 됩니다.
| 부분 | 무엇을 쓰나 | 검토에 왜 도움이 되나 |
|---|---|---|
| 1. 변경 | 게임이 다르게 해야 할 한 가지 | 그 일이 일어났는지 알 수 있다 |
| 2. 위치 | 그 변경이 속한 파일, 화면, 함수 | 변경이 한곳에 머문다 |
| 3. 바뀌면 안 되는 것 | 조작, 저장, 다른 화면, 라이브러리 | 목록 밖의 변화가 바로 눈에 띈다 |
| 4. 확인 | 테스트, 명령, 또는 플레이할 단계 | 인상이 아니라 통과나 실패를 준다 |
| 5. 보고 | 바뀐 파일, 실행한 확인, 테스트하지 않은 것 | 작업을 다시 하는 대신 증거를 읽는다 |
새로운 조언은 아닙니다. GitHub의 Copilot용 프롬프트 작성 가이드는 단계로 나눈 단순하고 구체적인 요청과, 기대하는 결과의 예 한두 개를 요구합니다. Claude Code 모범 사례는 어시스턴트가 직접 실행할 수 있는 확인을 맨 앞에 둡니다. 그것이 없으면 "다 된 것처럼 보인다"가 어시스턴트가 가진 유일한 신호이기 때문입니다. 2026년 10월 25일에 두 페이지 모두 그렇게 적혀 있었습니다. 아래에서는 이를 작은 게임에 적용합니다.
작업 하나는 얼마나 작아야 하나요?
변경을 한 문장으로 설명하고 몇 분 안에 해 볼 수 있을 만큼 작아야 합니다. "일시 정지 화면을 추가해 줘"는 작업 하나입니다. "일시 정지 화면, 설정 메뉴, 소리를 추가해 줘"는 세 개이고, 무언가 고장 나면 그중 어느 것 때문인지 알 수 없습니다.
설명이 길어지는 작업이라면 먼저 계획을 요청하고 코드는 나중으로 미루세요. Claude Code 페이지가 바로 그렇게 제안합니다. 어시스턴트가 코드를 읽고 어떤 파일이 바뀔지 제안하게 한 뒤, 계획을 직접 읽고, 그다음에야 코드를 쓰게 하는 것입니다. 프로젝트의 절반을 건드리는 계획은 작업을 나누어야 한다는 신호입니다.
이는 첫 게임을 작게 유지하는 것과 같은 규칙입니다. 모든 기능은 다른 모든 기능과 함께 동작해야 하므로, 기능 세 개를 한꺼번에 더하는 작업은 확인을 몇 배로 늘립니다.
모호한 작업과 검토할 수 있는 작업을 나란히 놓으면 어떻게 다른가요?
작은 슈팅 게임에 대한 같은 요청을 두 번 써 봤습니다.
| 모호함 | 검토 가능 |
|---|---|
| "게임을 더 어렵게 해 줘." | "웨이브 코드에서 새 웨이브마다 이전 웨이브보다 10% 빠르게 하되, 처음 속도의 두 배까지만. 플레이어 속도, 생명, 조작은 바꾸지 마." |
| "점수 버그 고쳐 줘." | "다시 시작하면 점수가 0이 아니라 예전 점수에서 시작해. 다시 시작할 때 게임을 초기화하는 곳을 찾아서 점수도 초기화하게 하고, 두 번 다시 시작한 뒤 0을 기대하는 테스트를 추가해 줘." |
| "모바일 조작을 추가해 줘." | "터치 화면에서는 왼쪽, 오른쪽, 발사 버튼을 보여 주고, 키보드와 같은 키 이벤트를 보내게 해 줘. 키보드로 하는 플레이는 바뀌면 안 돼. 아직 터치 조작이 없는 화면이 어디인지 알려 줘." |
오른쪽 열이 더 길지만, 모든 줄을 확인할 수 있습니다. 세 번째는 우리가 KittenGalaxy에 터치 조작을 추가했을 때 한 방식과 비슷합니다. 버튼이 키보드가 보낼 키 이벤트를 보내므로 게임 자체는 바꿀 필요가 없었습니다.
어시스턴트에게 작업을 확인하는 방법을 어떻게 알려 주나요?
"예" 또는 "아니요"로 답이 나오는 것을 주세요.
- 테스트: 어시스턴트가 실행할 수 있고 경우가 적혀 있는 것. "다시 시작하면 점수가 0이 된다."
- 명령: 결과를 읽을 수 있는 것. 빌드가 끝나고, 페이지가 콘솔 오류 없이 열린다.
- 직접 플레이할 단계: 변경 전에 적어 둔 것. "시작, 생명을 모두 잃기, 다시 시작 누르기, 점수가 0으로 표시됨."
어시스턴트에게 통과했다고 말하라고 하지 말고, 확인을 실행해서 출력을 보여 달라고 하세요. 붙여 넣은 테스트 결과나 오류 없는 콘솔 기록은 몇 초면 읽지만, "모두 잘 됩니다"라는 문장은 아무것도 증명하지 않습니다.
사람만 판단할 수 있는 것도 있습니다. 점프의 손맛이 괜찮은지, 레벨이 공정한지 같은 것입니다. 이런 것은 무엇을 볼지 적어 두고 직접 플레이하세요. 어시스턴트의 보고가 그것을 대신하게 두지 마세요.
다 끝나면 어시스턴트는 무엇을 알려 줘야 하나요?
같은 작업 안에서 다음 순서로 짧은 보고를 요청하세요.
- 어떤 파일이 바뀌었는지, 파일마다 한 줄로 이유와 함께;
- 어떤 확인을 실행했고 결과가 무엇이었는지;
- 무엇을 테스트하지 않았는지, 그리고 그 이유;
- 요청하지 않았는데 바꾼 것.
가장 중요한 것은 마지막 항목입니다. 요청을 넘어선 변경이 늘 틀린 것은 아니지만, 언제나 검토할 계획이 없던 것입니다. 파일 목록을 작업의 3부와 비교해 보세요. 바뀌지 말았어야 할 파일이 가장 먼저 살펴볼 곳입니다.
매번 작업에 쓰는 대신 프로젝트 파일에 둘 것은 무엇인가요?
그렇지 않으면 되풀이하게 될 모든 것입니다. 게임과 테스트를 실행하는 방법, 건드리면 안 되는 폴더, 코드의 규칙 같은 것이죠. 대부분의 어시스턴트는 세션을 시작할 때 이런 파일을 읽습니다(Claude Code에서는 CLAUDE.md라고 부릅니다). 짧게 유지하세요. Claude Code 페이지는 긴 파일에서는 중요한 규칙이 묻힌다고 경고합니다.
어떤 규칙이 거기 있을 자격이 있는 것은, 잊어버리면 게임이 망가질 때입니다. 우리가 KittenGalaxy를 위해 적어 두는 노트에는, 키나 화면이나 게임 상태를 추가할 때 그 터치 조작도 같은 변경에서 함께 추가한다고, 그렇지 않으면 휴대폰 플레이어가 그곳에 닿을 수 없다고 적혀 있습니다. 그러면 작업에는 새로운 것만 쓰면 됩니다.
결과가 틀렸을 때는 어떻게 하나요?
되돌린 다음, 더 나은 작업으로 다시 요청하세요.
작업마다 그 전에 작동하는 버전을 버전 관리의 커밋으로 저장해 두면, 잘못된 변경을 한 번에 되돌릴 수 있습니다. 확인이 실패하면 수정을 한두 번 요청할 수 있습니다. 두 번 고쳐도 실패하면, Claude Code 페이지는 계속 고치게 하기보다 더 나은 첫 요청으로 새 세션을 시작하라고 권합니다. 실패한 시도가 대화에 남아 있기 때문입니다. 변경을 되돌리고, 알게 된 것을 작업에 더해서 다시 보내세요.
자주 묻는 질문
이런 작업을 쓰려면 프로그래머여야 하나요? 아니요. 1, 3, 5부는 게임이 무엇을 하는지에 관한 것이라 쉬운 말로 쓰면 됩니다. 2부는 변경을 요청하기 전에 어시스턴트에게 그 변경이 어디에 들어가야 하는지 먼저 물어보세요.
긴 작업이 짧은 작업보다 나은가요? 그 자체로는 아닙니다. 많은 변경을 요구하는 긴 작업은 하나만 요구하는 짧은 작업보다 검토하기 어렵습니다. 길이는 확인이나 제한을 더할 때 도움이 됩니다.
작은 게임에서도 테스트를 요청해야 하나요? 점수, 생명, 타이머, 저장처럼 정확히 말할 수 있는 규칙이라면 그렇습니다. 이후 변경할 때마다 적은 비용으로 다시 실행할 수 있습니다. 손맛과 재미는 여전히 플레이해 봐야 합니다.
어시스턴트가 질문을 하면요? 코드를 쓰기 시작하기 전에 작업 안에서 답하세요. 일찍 나온 질문은 잘못된 변경보다 비용이 적습니다.
게임을 사람들에게 보여 줄 때는 언제인가요? 낯선 사람이 링크로 시작해서 여러분의 도움 없이 끝까지 플레이할 수 있을 때입니다. 그때 HeapPlay에 제출할 수 있고, 인증된 개발자는 새 버전마다 무엇이 바뀌었는지 기록할 수 있습니다.
ai-assistants workflow testing
게임을 만들고 계신가요? HeapPlay에 제출하고 개발자가 받는 것을 확인해 보세요.