코딩 요청은 기술 이름보다 완료된 화면을 먼저 설명해야 한다

AI에게 “회원가입 페이지 만들어줘”라고 부탁하면 입력칸과 버튼이 있는 화면을 빠르게 만들 수 있습니다. 하지만 이메일 확인이 필요한지, 휴대전화에서 어떻게 보여야 하는지, 가입에 실패하면 무슨 말을 보여줄지는 알 수 없습니다. 결과가 엇나간 이유가 AI 성능보다 빠진 조건일 때가 많습니다.

코딩 요청은 식당 주문과 비슷합니다. “맛있는 음식 주세요”보다 알레르기, 인원, 원하는 메뉴와 양을 말해야 결과를 확인할 수 있습니다. 어려운 기술 이름을 아는 척하기보다 누가 어떤 행동을 하고 무엇을 보면 완료인지 설명하는 편이 낫습니다.

목표는 사용자 행동 한 문장으로 쓴다

기능 이름은 사람마다 범위가 다릅니다. “검색 기능” 대신 “방문자가 상품 이름을 입력하면 현재 판매 중인 상품만 이름순으로 보고, 결과가 없으면 다른 검색어를 안내받는다”처럼 적습니다. 사용자, 입력, 결과가 한 문장에 들어가면 AI가 질문할 지점도 분명해집니다.

아직 정하지 못한 조건은 숨기지 않습니다. 로그인한 사람만 쓰는지 모르겠다면 “로그인 필요 여부는 아직 결정하지 않았으니 코드를 바꾸기 전에 선택지를 설명해줘”라고 씁니다. AI가 임의로 계정 체계를 만드는 것보다 필요한 결정을 먼저 돌려받는 편이 안전합니다.

현재 상태는 보이는 사실로 전달한다

오류를 고칠 때는 원하는 결과만큼 현재 상황이 중요합니다. 어느 주소에서, 어떤 값을 넣고, 어떤 버튼을 눌렀으며, 화면이나 터미널에 어떤 문장이 나왔는지 순서대로 적습니다. 가능하면 관련 파일과 오류 전문을 함께 줍니다.

Cursor 문서에서는 목표 같은 의도 정보와 파일·오류·화면 같은 현재 상태 정보가 함께 있어야 더 알맞은 결과를 만들 수 있다고 설명합니다. 단, 오류 로그에 이메일과 토큰, 고객 자료가 있다면 가리고 공유합니다.

재현 위치: /signup
입력: 이메일은 정상, 비밀번호는 7글자
행동: 가입 버튼 클릭
현재 결과: 버튼이 계속 로딩 중이고 안내 없음
기대 결과: 8글자 이상 필요하다는 안내 후 버튼 다시 활성화
오류 문장: Password must be at least 8 characters

“안 돼요”보다 이 여섯 줄이 원인을 좁히는 데 훨씬 도움이 됩니다.

바꿀 것과 바꾸지 않을 것을 함께 적는다

AI가 문제를 해결하면서 디자인이나 다른 기능까지 손대지 않게 범위를 정합니다. 관련 페이지와 테스트만 바꾸라고 하거나, 데이터베이스와 결제 설정은 건드리지 말라고 씁니다. 범위를 모르면 먼저 읽기만 하고 수정 계획을 보여달라고 합니다.

다음 네 칸을 요청 끝에 붙여봅니다.

• 바꿀 대상은 가입 버튼의 입력 검사와 오류 안내입니다.
• 기존 이메일 전송 방식과 화면 색상은 유지합니다.
• 새 라이브러리를 설치하지 않습니다.
• 파일을 수정하기 전에 바뀔 파일과 이유를 알려줍니다.

이 조건은 AI를 방해하는 장벽이 아니라 예상하지 않은 변경을 알아보기 위한 기준입니다. 작업 도중 범위를 넓혀야 한다면 이유와 새 위험을 확인한 뒤 별도 단계로 나눕니다.

예시 입력과 결과를 한 쌍 넣는다

“올바르게 검사해줘”는 올바름의 기준이 보이지 않습니다. 짧은 예시 두세 개를 주면 기대 결과가 선명해집니다. GitHub의 공식 안내도 입력과 출력 예시, 테스트를 프롬프트에 활용하고 모호한 표현을 피하도록 권합니다.

회원가입 비밀번호라면 이렇게 적을 수 있습니다.

입력 "abc1234" → 실패, 8글자 이상 안내
입력 "abc12345" → 통과
입력 빈 값 → 실패, 비밀번호 입력 안내

실제 고객 비밀번호를 예시로 쓰지 않습니다. 날짜와 금액, 이름도 가짜 값으로 바꿉니다. 예시가 업무의 모든 경우를 대표하지 않으므로 경계값과 빈 값도 하나씩 넣습니다.

완료 조건은 눈으로 확인할 수 있어야 한다

“잘 작동한다”, “깔끔하다”, “안전하다”는 완료 여부를 판단하기 어렵습니다. 버튼이 다시 활성화되는지, 오류 문구가 입력칸 가까이에 보이는지, 휴대전화 폭에서 잘리지 않는지처럼 확인 가능한 문장으로 바꿉니다.

기능 하나에는 다섯 가지 정도면 충분합니다.

1. 정상 입력에서 기존 성공 흐름이 유지된다.
2. 빈 값과 잘못된 값에서 전송되지 않는다.
3. 사용자가 다음 행동을 알 수 있는 한국어 안내가 보인다.
4. 빠르게 두 번 눌러도 요청이 중복되지 않는다.
5. 모바일 화면과 키보드만으로 사용할 수 있다.
6. 관련 테스트와 빌드가 실제로 통과한다.

AI에게 이 조건을 기준으로 테스트를 제안하게 할 수 있지만, 통과했다는 문장만 받지 말고 실행한 명령과 결과, 직접 확인하지 못한 항목을 구분해 달라고 합니다.

큰 기능은 읽기와 변경으로 나눈다

처음부터 “결제까지 되는 쇼핑몰을 만들어줘”라고 하면 화면, 상품, 주문, 결제, 환불, 보안이 한꺼번에 섞입니다. 먼저 기존 프로젝트와 필요한 결정을 읽기만 하게 하고, 다음에 가장 작은 화면을 만들며, 그 뒤 입력 검사와 데이터 저장을 연결합니다.

작업을 나눌 때는 각 단계가 혼자 확인 가능해야 합니다.

• 1단계는 현재 구조와 위험을 설명하고 수정하지 않습니다.
• 2단계는 정적인 화면과 모바일 배치만 만듭니다.
• 3단계는 가짜 데이터로 입력 검사를 붙입니다.
• 4단계는 테스트 계정의 저장 기능을 연결합니다.
• 5단계는 오류와 중복 요청을 시험합니다.
• 6단계는 실제 공개 주소에서 다시 확인합니다.

한 단계가 실패하면 다음으로 넘어가지 않습니다. 이 방식은 답변 횟수를 줄이기 위한 것이 아니라 문제 위치를 찾기 위한 것입니다.

오류 수정 요청은 원인 추정과 검증을 분리한다

AI가 오류 원인을 한 가지로 단정하면 그럴듯해 보여도 틀릴 수 있습니다. 가능한 원인을 두세 가지로 정리하고, 가장 안전한 읽기 전용 확인부터 하도록 요청합니다. 확인 결과와 맞는 원인만 수정하고 한 번에 한 가지를 바꿉니다.

다음 문장을 그대로 활용할 수 있습니다.

이 오류의 가능한 원인을 최대 3개로 좁혀줘.
파일을 바꾸기 전에 각 원인을 확인할 읽기 전용 방법을 알려줘.
확인된 원인만 최소 범위로 고치고 같은 재현 순서로 다시 시험해줘.
추측과 실제 확인 결과를 구분해서 보고해줘.

삭제와 초기화, 강제 덮어쓰기 명령은 내용을 이해하고 정확한 대상을 확인하기 전에는 실행하지 않습니다.

결과를 받을 때 물어볼 다섯 문장

코드가 만들어지면 처음 요청과 완료 조건을 다시 꺼냅니다. 화면이 예뻐 보이는 것과 약속한 동작이 맞는 것을 나눠 확인합니다.

• 바뀐 파일과 각 이유를 알려줘.
• 완료 조건별로 어떻게 확인했는지 보여줘.
• 실행하지 못한 테스트와 이유를 알려줘.
• 개인정보와 비밀값, 결제, 삭제에 영향이 있는지 알려줘.
• 실제 공개 환경에서 내가 직접 확인할 순서를 알려줘.

AI의 답도 틀릴 수 있으므로 변경 비교, 테스트 출력, 브라우저 화면을 직접 확인합니다. 요청을 잘 쓰는 목적은 한 번에 완벽한 코드를 받는 것이 아니라 기대한 결과와 실제 결과의 차이를 빠르게 찾는 데 있습니다.

메모장으로 첫 요청을 완성해 보기

고치고 싶은 작은 화면 하나를 정합니다. 메모장에 사용자 행동 한 문장, 현재 상태, 바꿀 것, 바꾸지 않을 것, 예시 입력 두 개, 완료 조건 다섯 개를 적습니다. 비밀정보를 지운 뒤 AI에게 먼저 이해한 내용을 요약하고 빠진 결정을 질문해 달라고 합니다.

계획이 내 의도와 맞을 때만 한 단계의 수정을 허용합니다. 결과를 받은 뒤 같은 완료 조건으로 직접 확인하고 차이가 있으면 “더 좋게”가 아니라 실패한 조건 하나를 정확히 알려줍니다. 이 습관이 생기면 기술 이름을 많이 몰라도 AI와 함께 작은 기능을 안전하게 완성할 수 있습니다.