AI에게 코드를 잘 시키려면 역할이나 말투보다 목표, 현재 상태, 성공 조건, 제약 조건, 검증 순서를 분명히 적는 것이 먼저입니다. 이 다섯 항목으로 코딩 요청을 만들고 실제 화면에서 결과를 확인했습니다.
좋은 코딩 프롬프트의 다섯 부분
첫 번째는 목표입니다. “앱을 개선해 줘”가 아니라 “할 일 앱에 전체·미완료·완료 필터를 추가해 줘”처럼 사용자가 보고 확인할 변화를 적습니다. 목표가 여러 개라면 한 번에 모두 요청하지 말고 우선순위를 정해 작은 작업으로 나눕니다. 서로 다른 기능을 한 요청에 넣을수록 AI가 무엇을 보존해야 하는지 놓치기 쉽습니다.
두 번째는 현재 상태입니다. 이미 작동하는 기능, 관련 파일, 사용하는 프레임워크, 관찰한 오류를 알려 줍니다. 이번 실습에서는 “항목 추가, 완료 체크, 로컬 저장은 작동한다”고 적었습니다. 현재 되는 일을 명시하면 새 기능을 넣는 과정에서 기존 동작을 지켜야 한다는 기준이 생깁니다.
세 번째는 성공 조건입니다. 결과를 감상으로 평가하지 않고 값으로 확인할 수 있게 적습니다. “필터가 잘 작동한다”보다 “전체 버튼은 모든 항목, 미완료 버튼은 완료되지 않은 항목, 완료 버튼은 완료된 항목만 보여 주며 표시 개수가 실제 배열과 일치한다”가 낫습니다. 입력, 행동, 기대 결과가 연결돼야 테스트로 바꿀 수 있습니다.
네 번째는 제약 조건입니다. 바꾸지 말아야 할 데이터 구조, 기존 화면, 브라우저 지원 범위, 보안 요구를 적습니다. 이번 입력에는 “기존 저장 데이터와 모바일 한 열 레이아웃을 유지한다”를 넣었습니다. 제약이 없으면 AI가 동작하는 기능을 만들기 위해 저장 키나 구조를 통째로 바꿔 기존 사용자 데이터를 읽지 못하게 할 수 있습니다.
다섯 번째는 검증 순서입니다. 변경 전 동작 확인, 목표 범위 수정, 성공 조건 실행, 실패 조건과 오류 보고 순서로 요청합니다. 코드를 만들었다는 응답만으로 끝내지 않고 실제 실행 결과를 요구해야 합니다. 검사할 수 없는 환경이라면 실행했다고 단정하지 말고 필요한 확인 명령과 예상 결과를 구분해 제시하게 합니다.
공식 가이드에서 확인한 프롬프트 원칙
GitHub의 Copilot 프롬프트 엔지니어링 문서는 큰 목표에서 시작한 뒤 구체화하고, 예시를 제공하고, 복잡한 작업을 작은 작업으로 나누며, 모호한 표현을 피하고, 관련 코드를 지정하고, 반복해서 개선하라고 안내합니다. 현재 파일과 대화 기록도 입력 맥락에 포함될 수 있으므로 관련 없는 맥락을 줄이는 기준도 설명합니다.
GitHub Copilot 사용 모범 사례는 요구사항과 입력·출력 예시를 구체적으로 제공하고, 제안된 코드를 반드시 검증해야 한다고 강조합니다. 이 글의 다섯 부분은 특정 문장을 외우는 공식이 아니라, 이 원칙을 실제 코딩 작업에 적용하기 위한 체크리스트입니다.
예시는 정답을 복사시키기 위한 것이 아니라 경계를 분명하게 만드는 데 유용합니다. 날짜 형식을 다루는 함수라면 유효한 입력과 잘못된 입력을 각각 한두 개 제시할 수 있습니다. 화면 필터라면 항목 세 개 중 완료 한 개라는 작은 데이터와 버튼별 기대 개수를 적을 수 있습니다. 예시가 너무 많거나 서로 충돌하면 오히려 핵심 요구를 흐릴 수 있습니다.
관련 코드 지정도 파일 전체를 무조건 보내는 것과 다릅니다. 수정할 컴포넌트, 상태가 보관되는 함수, 현재 실패하는 테스트, 호출 관계를 알려 주고 민감정보는 제외합니다. API 키, 사용자 데이터, 운영 로그의 개인 정보가 프롬프트나 캡처에 들어가지 않도록 먼저 가려야 합니다.
직접 실행한 프롬프트 설계 테스트
테스트 날짜: 2026년 9월 10일. 환경: Windows 11, Chrome 기반 브라우저, localhost 정적 웹 페이지. 목표 입력: “할 일 앱에 완료 필터 추가”. 현재 상태: “항목 추가, 완료 체크, 로컬 저장은 작동함”. 성공 조건: “전체·미완료·완료 버튼별 목록 수가 실제 데이터와 일치함”. 제약 조건: “기존 저장 데이터와 모바일 한 열 레이아웃 유지”.
실습 도구는 외부 AI 서비스를 호출하지 않습니다. 네 입력값을 다섯 부분의 텍스트 명세로 조합하고 각 부분이 존재하는지 화면에서 순서대로 확인하는 로컬 페이지입니다. 계정, 이메일, API 키, 실제 서비스 코드나 비공개 대화는 사용하지 않았습니다.
시작 화면에서 목표, 현재 상태, 성공 조건, 제약 조건 입력란과 “프롬프트 만들기” 버튼이 각각 한 개씩 있는지 확인했습니다. 오른쪽 결과 영역은 대기 상태였고, 목표부터 검증 순서까지 다섯 단계가 아직 완료되지 않은 상태로 표시됐습니다.
네 입력란에 위의 값을 채운 뒤 버튼을 눌렀습니다. 결과 영역에는 [목표], [현재 상태], [성공 조건], [제약 조건], [검증 순서] 제목이 모두 포함된 227자의 프롬프트가 나타났습니다. 구성 단계 다섯 개가 차례로 진행되고 마지막에 배지가 “5 / 5 완료”로 바뀌었습니다.
영상은 같은 브라우저 세션에서 버튼 클릭 전후를 약 0.22초 간격으로 기록해 연결했습니다. 마지막 상태에서 완료 항목 수 5개, 배지 “5 / 5 완료”, 안내 문구 “검증 가능한 코딩 프롬프트를 만들었습니다”를 확인했습니다. 이 결과는 프롬프트 구조가 생성됐다는 검증이며, 해당 요청으로 만든 실제 필터 기능의 품질을 대신 증명하지는 않습니다.
실전에 바로 쓰는 작성 순서
먼저 현재 문제를 한 문장으로 적습니다. 기능 추가라면 사용자가 하는 행동과 바뀌는 화면을 포함합니다. 버그 수정이라면 재현 순서, 기대 결과, 실제 결과를 포함합니다. “가끔 안 된다”라는 문장만으로는 어떤 상태를 다시 만들어야 하는지 알기 어렵습니다.
다음으로 관련 파일과 현재 되는 기능을 적습니다. 예를 들어 “데이터는 app.js의 habits 배열에 있고 추가·체크·로컬 저장은 통과한다. 필터 영역만 새로 추가한다”처럼 범위를 좁힙니다. 프로젝트 전체를 변경 대상으로 열어 두지 않으면 불필요한 재작성 위험을 줄일 수 있습니다.
그다음 성공 조건을 체크리스트로 바꿉니다. 전체 항목 3개, 완료 1개인 테스트 데이터에서 전체=3, 미완료=2, 완료=1이 표시돼야 한다고 적습니다. 새로고침 뒤 선택 필터를 유지할지 초기화할지도 정합니다. 키보드로 버튼을 이동하고 선택할 수 있는지, 모바일에서 버튼이 잘리지 않는지도 필요한 경우 포함합니다.
마지막으로 AI가 해야 할 보고 형식을 정합니다. 수정한 파일, 핵심 변경, 실행한 검사, 관찰한 결과, 남은 한계를 짧게 제시하게 합니다. 실행 환경에 접근하지 못했다면 실제로 통과했다고 쓰지 말고 사용자가 실행할 명령과 예상 결과를 분리하도록 요구합니다.
한 번에 다 시키지 않고 두 단계로 나누기
첫 요청에서는 테스트를 먼저 추가하도록 할 수 있습니다. 전체·미완료·완료 버튼별 기대 개수를 검사하는 테스트가 현재 실패하는지 확인합니다. 이 실패가 기능이 없기 때문에 발생하는지 살핀 뒤 최소 변경으로 통과시킵니다. 화면 스타일 변경은 기능 검사 뒤 별도 요청으로 나누는 편이 좋습니다.
두 번째 요청에서는 레이아웃과 접근성을 보완합니다. 필터 버튼의 선택 상태가 텍스트나 aria-pressed로 드러나는지, 작은 화면에서 줄바꿈되는지, 색상만으로 선택을 표현하지 않는지 확인합니다. 기능과 스타일을 함께 크게 바꾸면 문제가 생겼을 때 원인을 찾기 어렵습니다.
대화 기록이 길어졌다면 새 작업에 필요한 결정과 파일만 정리해 새 대화에서 시작할 수 있습니다. 이전의 실패한 시도와 무관한 요구가 계속 남아 있으면 모델이 현재 목표보다 오래된 맥락을 따라갈 수 있습니다. 다만 중요한 제약과 이미 통과한 테스트를 빼면 같은 문제를 다시 만들 수 있으므로 핵심 상태는 남겨야 합니다.
잘 안 되는 프롬프트와 고치는 방법
“최고의 앱을 만들어 줘”: 최고라는 기준이 없습니다. 대상 사용자, 핵심 행동, 성공 조건을 적습니다. 예를 들어 “초보 사용자가 항목을 추가하고 필터 버튼 세 개로 목록을 구분하며, 테스트 데이터의 개수가 일치해야 한다”로 바꿉니다.
“오류를 모두 고쳐 줘”: 오류 범위가 너무 큽니다. 재현 순서 하나와 오류 메시지 하나를 먼저 제공합니다. 현재 통과하는 테스트를 적고, 실패한 테스트 하나를 추가한 뒤 최소 범위로 수정하게 합니다.
“전체 코드를 새로 작성해 줘”: 기존 데이터와 동작이 사라질 수 있습니다. 보존할 파일, 공개 API, 저장 키, 화면 구조를 제약 조건으로 적습니다. 정말 재작성해야 한다면 이전 데이터 변환과 되돌리기 계획을 함께 요구합니다.
“테스트도 알아서 해 줘”: 무엇을 확인해야 하는지 모호합니다. 입력값, 실행 동작, 기대 출력, 실패 조건, 검사 환경을 적습니다. 외부 계정이나 결제가 필요한 테스트는 자동 실행 범위에서 제외하고 사람 승인을 두는 편이 안전합니다.
긴 원문을 그대로 붙이는 방식: 관련 없는 정보와 민감정보가 섞일 수 있습니다. 오류 주변 코드, 필요한 설정, 재현에 필요한 최소 로그만 제공합니다. 비밀값은 자리표시자로 바꾸고, 운영 데이터 대신 재현용 예시 데이터를 사용합니다.
검증 결과를 읽는 방법
AI가 “완료했습니다”라고 답해도 수정된 파일과 실제 검사 결과를 확인합니다. 테스트 명령이 종료 코드 0이었는지, 실패 개수가 0인지, 원래 재현 단계가 더 이상 실패하지 않는지 살펴봅니다. 코드 비교만으로 화면 동작이 맞다고 단정할 수 없고, 화면이 보인다는 사실만으로 데이터 저장이 맞다고 단정할 수도 없습니다.
변경 범위가 요청보다 넓으면 이유를 확인합니다. 관련 없는 파일이 수정됐다면 되돌리기 전에 사용자 변경과 AI 변경을 구분해야 합니다. 데이터 삭제, 배포, 결제, 메시지 발송처럼 외부 상태를 바꾸는 명령은 대상과 영향을 다시 확인합니다.
실패 결과도 유용합니다. 어떤 입력에서 어느 단계가 실패했고 실제 출력이 무엇이었는지 남기면 다음 프롬프트가 더 짧고 구체적이 됩니다. 같은 명령을 이유 없이 반복하기보다 환경, 권한, 네트워크, 데이터 조건 중 무엇이 달랐는지 확인합니다.
한계와 주의사항
이 글의 실습 도구는 입력된 문장을 정해진 형식으로 조합합니다. 프롬프트가 5개 부분을 포함했다는 사실만 확인하며, 특정 모델이 항상 원하는 코드를 만든다고 보장하지 않습니다. 모델 버전, 프로젝트 구조, 제공된 코드, 대화 기록, 도구 권한에 따라 결과는 달라질 수 있습니다.
공식 가이드는 GitHub Copilot을 중심으로 설명하지만 목표 구체화, 작업 분할, 예시, 관련 맥락, 반복 검증 원칙은 다른 코딩 도구를 사용할 때도 참고할 수 있습니다. 다만 각 제품의 입력 데이터 처리, 저장 기간, 조직 정책, 요금, 지원 기능은 별도 공식 문서를 확인해야 합니다.
화면 두 장과 3.1초 영상은 로컬 프롬프트 구성 도구의 작동 증거입니다. 생성된 요청으로 실제 할 일 앱 코드를 수정하거나 필터 테스트를 실행한 증거는 아닙니다. 실제 프로젝트에 적용할 때는 변경 전후의 코드와 테스트 결과를 별도로 남겨야 합니다.
결론: 요청보다 판정 기준을 먼저 쓴다
코딩 프롬프트를 잘 쓰는 가장 실용적인 방법은 멋진 표현을 찾는 것이 아니라 결과를 판정할 기준을 먼저 만드는 것입니다. 목표, 현재 상태, 성공 조건, 제약 조건, 검증 순서가 있으면 AI에게 무엇을 바꾸고 무엇을 지켜야 하는지 전달하기 쉬워집니다.
작은 프로젝트에서 이 방식을 연습하려면 프롬프트로 타이머 웹앱을 만든 실전 글의 저장·시작·정지 조건을 다시 작성해 볼 수 있습니다. 기능 하나마다 성공 조건을 한두 개로 제한하고 실제 브라우저 결과를 확인하는 습관이 긴 프롬프트보다 중요합니다.