재현 절차 쓰기

"가끔 안 돼요"로는 아무도 못 고쳐요. 어떤 순서로 하면 그 문제가 반드시 나는지를 번호 붙여 적는 것이 재현 절차예요. 이 몇 줄이 고치는 시간을 반으로 줄여요.

쉽게 말하면

가게 냉장고가 가끔 안 시원할 때 수리 기사를 부르는 일과 똑같아요. "가끔 안 시원해요"라고만 하면, 기사님이 왔을 때 냉장고가 멀쩡하면 그냥 돌아가요. 그런데 "문을 열어 둔 채 3분이 지나면 뒤에서 딱딱 소리가 나고, 그날 밤엔 꼭 안 시원해요"라고 하면 이야기가 달라져요. 기사님이 그 자리에서 문을 열고 3분을 기다려 보면 되니까요. 문제를 그 자리에서 다시 일으키는 순서, 이게 재현 절차예요.

서비스 고치기도 순서가 같아요. AI든 개발자든, 문제를 자기 눈앞에서 한 번 일으켜 봐야 고칠 수 있어요. 눈앞에서 안 나는 문제는 어디를 고쳐야 하는지 알 수 없고, 고쳤다 해도 진짜 고쳐졌는지 확인할 방법이 없어요.

증상만 말하기

"결제가 가끔 안 돼요. 고쳐 주세요"

받은 쪽이 결제를 눌러 보면 멀쩡해요. 어디를 봐야 할지 몰라서 추측으로 고치고, 문제는 그대로 남아요.

순서로 말하기

"1. 장바구니에 2개 담고 2. 하나를 지운 다음 3. 결제를 누르면 금액이 안 맞다며 실패해요"

받은 쪽이 세 번을 그대로 따라 하면 눈앞에서 문제가 나요. 원인이 어디 있는지 바로 좁혀져요.

그러니까 재현 절차는 개발 기술이 아니라 말하는 기술이에요. 코드를 몰라도 쓸 수 있고, 오히려 문제를 직접 겪은 사장님이 세상에서 제일 잘 쓸 수 있는 문서예요.

재현 절차에 들어가는 다섯 칸

형식은 자유지만, 아래 다섯 가지가 들어 있으면 받는 쪽이 헤매지 않아요. 다섯 줄이면 충분해요.

칸	무엇을 적나	예시
어디서	어느 화면, 어느 기기에서 났는지	"예약 화면, 제 아이폰에서요"
시작 상태	하기 전에 어떤 상태였는지	"로그인한 상태로, 장바구니는 비어 있었어요"
순서	누른 것을 순서대로, 번호 붙여서	"1. 날짜 선택 2. 오후 7시 선택 3. 예약 버튼"
실제 결과	그래서 무엇이 나왔는지, 화면의 문구 그대로	"'요청이 실패했습니다'라는 빨간 글씨가 떠요"
기대한 결과	원래는 무엇이 나와야 했는지	"예약 완료 화면이 나와야 해요"

마지막 칸을 빼먹기 쉬워요

"기대한 결과"는 뻔해 보여서 다들 빼먹는데, 사실 제일 중요해요. 무엇이 정상인지 적혀 있어야 버그인지 원래 없는 기능인지 갈리고, 고친 뒤에 "됐다"를 판정할 기준이 생겨요.

여기에 하나를 더 얹을 수 있으면 금상첨화예요. 화면 캡처나 화면 녹화요. 에러 문구를 요약하지 말고 사진으로 그대로 보여 주면, 받은 쪽이 에러 읽는 법대로 원인 단서를 바로 뽑아요.

"가끔만" 나는 문제를 잡는 법

진짜 골치 아픈 건 매번 나는 문제가 아니라 가끔 나는 문제예요. 그런데 "가끔"은 대부분 진짜 무작위가 아니에요. 어떤 조건이 겹칠 때만 나는데, 그 조건을 아직 못 찾았을 뿐이에요.

그래서 가끔 나는 문제를 만나면, 고쳐 달라고 하기 전에 문제가 난 순간의 주변 조건을 메모해 두세요. 두세 번 쌓이면 공통점이 보여요. 그 공통점이 재현 절차의 재료예요.

살펴볼 조건	이렇게 물어보세요
기기와 브라우저	제 폰에서만 나나요, 컴퓨터에서도 나나요? 아이폰과 갤럭시가 다른가요?
로그인 상태	로그인했을 때만 나나요, 안 했을 때도 나나요?
순서	꼭 무언가를 한 직후에만 나나요? 지우고 나서, 뒤로 갔다 와서, 새로고침하고 나서요
넣은 값	특정 값일 때만 나나요? 이름이 아주 길 때, 수량이 0일 때, 특수문자가 들어갈 때요
처음 한 번	처음 열었을 때만 나고 두 번째부터는 멀쩡한가요? 그 반대인가요?
시간대	특정 시간이나 요일에만 나나요? 자정 넘어서, 사람이 몰리는 저녁에요

한 사장님의 사례

“쿠폰이 가끔 적용이 안 된다는 문의가 일주일에 두세 번 왔어요. 저는 눌러 보면 늘 됐고요.”

문의가 올 때마다 손님에게 "어떤 순서로 하셨어요?"를 물어 메모했더니 공통점이 나왔어요. 전부 쿠폰을 먼저 적용하고 나서 장바구니 수량을 바꾼 손님이었어요. 그 순서를 그대로 적어 넘기자 한 번에 고쳐졌어요. 무작위로 보이던 문제가 사실은 순서 문제였던 거예요.

그래도 못 잡겠으면

조건을 아무리 찾아도 안 잡히는 문제도 있어요. 그럴 때는 서비스에 오류 기록 모으기를 붙여 달라고 하세요. 문제가 나는 순간의 조건을 사람 대신 기계가 적어 두는 장치라서, 가끔 나는 문제의 마지막 그물이에요.

AI에게 이렇게 말하세요

재현 절차는 개발자에게만 쓰는 게 아니에요. AI에게 고쳐 달라고 할 때 그대로 붙여 넣으면 효과가 제일 커요. AI는 화면을 직접 못 누르는 대신, 순서가 적혀 있으면 그 길을 따라 코드를 읽어요.

이렇게 말하면	무엇이 좋아지나
"1. 장바구니에 2개 담고 2. 하나를 지우고 3. 결제를 누르면 금액 오류가 나요. 원래는 남은 1개 가격으로 결제돼야 해요"	AI가 그 순서에 해당하는 코드만 좁혀서 봐요. 엉뚱한 곳을 고칠 확률이 확 줄어요
"에러 문구는 이거예요" 하고 화면의 빨간 글씨를 그대로 붙여넣기	문구 안에 원인 위치가 들어 있는 경우가 많아요. 요약하면 그 단서가 사라져요
"고친 다음, 위 1번부터 3번을 다시 했을 때 정상인지 확인해 주세요"	고침이 끝이 아니라 재현 절차로 검증까지 하게 돼요. "고쳤다는데 그대로"가 줄어요
"제 폰에서만 나고 컴퓨터에서는 안 나요"	기기 차이가 원인 후보로 바로 올라가요. 못 찾던 문제의 절반이 이런 조건 한 줄에서 풀려요

고치기 전에 하나만 더

고치는 작업을 시키기 전에, 재현 절차대로 했을 때 지금도 문제가 나는지 한 번 다시 해보세요. 이미 사라진 문제를 고쳐 달라고 하면 멀쩡한 코드를 건드리게 돼요. 문제를 다시 일으켜 보는 것 자체가 개발자 도구(F12) 없이도 할 수 있는 첫 번째 점검이에요.

자주 묻는 것

Q. 저는 코드를 모르는데 재현 절차를 쓸 수 있나요?: 코드를 몰라야 오히려 잘 써요. 재현 절차에는 코드가 한 줄도 안 들어가요. 어느 화면에서, 무엇을, 어떤 순서로 눌렀는지만 적으면 돼요. 그건 문제를 직접 겪은 사람이 제일 정확히 알아요.
Q. 손님이 "안 돼요"라고만 하면 어떻게 하나요?: 다섯 칸을 질문으로 바꿔서 물어보세요. "어느 화면에서요?", "무엇을 누르셨어요?", "화면에 뭐라고 떴어요?" 세 개만 물어도 재현 절차의 반이 나와요. 이 질문 목록을 답장 틀로 만들어 두면 문의 대응이 훨씬 빨라져요.
Q. 재현이 한 번도 안 되면 버그가 아닌 건가요?: 아니에요. 재현이 안 된다는 건 조건을 아직 못 찾았다는 뜻이지, 문제가 없다는 뜻이 아니에요. 조건 메모를 계속 쌓고, 오류 기록 장치를 붙이는 쪽으로 방향을 바꾸면 돼요. 다만 한 번 나고 다시는 안 나는 문제라면, 고치는 값보다 지켜보는 값이 쌀 때도 있어요.
Q. 화면 녹화는 어떻게 하나요?: 폰이면 아이폰과 갤럭시 둘 다 기본 화면 녹화 기능이 있어요. 컴퓨터면 윈도우는 Win+G, 맥은 Shift+Cmd+5로 녹화할 수 있어요. 문제가 나는 순간을 한 번만 담아도, 글 열 줄보다 정확하게 전달돼요.
Q. 재현 절차를 적어 뒀는데 또 쓸 일이 있나요?: 네, 두 번 더 써요. 고친 직후에 그 절차대로 다시 해서 "정말 고쳐졌나"를 확인할 때, 그리고 나중에 다른 걸 고친 뒤 "이 문제가 다시 살아나지 않았나"를 점검할 때요. 잘 쓴 재현 절차는 그대로 테스트 목록의 한 줄이 돼요.

확인해 보세요

손님이 "예약이 가끔 안 돼요"라고 했어요. 가장 먼저 할 일은?

하나 더

재현 절차 다섯 칸 중 "기대한 결과"를 적는 이유는?

직접 해보기

재현 절차를 붙여서 고쳐 달라고 해보세요

지금 만들고 있는 것에서 이상한 곳이 하나라도 있으면, 다섯 칸(어디서·시작 상태·순서·실제 결과·기대한 결과)을 채워서 스튜디오 채팅에 그대로 붙여 보세요. 증상 한 줄로 말했을 때와 고쳐지는 속도가 얼마나 다른지 직접 비교해 보는 게 이 문서의 핵심 체험이에요.

스튜디오 열기

이것만 기억하세요

·고치는 사람은 문제를 자기 눈앞에서 한 번 일으켜 봐야 고칠 수 있어요
·다섯 칸이면 돼요. 어디서, 시작 상태, 순서, 실제 결과, 기대한 결과
·"가끔"은 무작위가 아니라 조건을 못 찾은 것이에요. 날 때마다 주변 조건을 메모하세요
·에러 문구는 요약하지 말고 화면 그대로, 가능하면 캡처나 녹화로 전달하세요
·고친 뒤에는 같은 절차를 다시 해서 정말 고쳐졌는지 확인하세요