AI 코딩 프롬프트, 과제를 맡기기 전 5줄 체크리스트

AI에게 코딩 과제를 맡길 때 가장 자주 생기는 문제는 모델 성능보다 요청문이 흐린 데서 시작된다. “로그인 고쳐줘”라고 쓰면 AI는 무엇을 고쳐야 하는지 추측한다. 어느 화면에서 실패하는지, 건드리면 안 되는 파일이 있는지, 끝난 뒤 어떤 명령으로 확인해야 하는지 빠져 있기 때문이다. 그래서 첫 문장은 길게 쓰는 것보다 5줄로 고정하는 편이 낫다.

developers.openai.com의 Codex 문서는 Codex가 터미널에서 대화형으로 실행되고, 이미지 입력, 로컬 코드 리뷰, 웹 검색, MCP, 승인 모드 같은 작업 방식을 제공한다고 설명한다. help.openai.com의 GitHub 연결 도움말도 저장소를 읽고 검색하고 인용하는 용도와 코드를 생성하거나 수정해 올리는 Codex 작업을 구분한다. 같은 help.openai.com의 Canvas 도움말은 글쓰기와 코딩 프로젝트를 고치고 리뷰하는 화면을 설명한다. 도구가 많아질수록 요청문에는 “무엇을 바꿀지”보다 “어디까지 바꾸고 어떻게 확인할지”가 먼저 들어가야 한다.

먼저 결과물이 아니라 작업 경계를 써야 한다

초보자가 가장 많이 놓치는 줄은 목표가 아니라 경계다. AI는 “고쳐줘”라는 말을 받으면 관련 있어 보이는 파일을 넓게 열어 본다. 작은 수정이면 편하지만, 학습 과제나 실서비스 코드에서는 오히려 불안해진다. 요청문 첫 줄에는 결과물을 쓰고, 둘째 줄에는 지금 상태를 쓴다. 셋째 줄에는 건드리면 안 되는 것을 쓴다. 넷째 줄에는 확인 명령을 쓴다. 다섯째 줄에는 보고 형식을 쓴다.

다음 코딩 과제를 처리해 주세요.

목표: {무엇을 바꿀지 한 문장}
맥락: {현재 증상, 관련 화면, 관련 파일, 이미 시도한 것}
제약: {건드리면 안 되는 파일, 유지해야 할 스타일, 새 의존성 금지 여부}
검증: {실행할 테스트, 빌드, lint, 수동 확인 방법}
보고: 바뀐 파일, 핵심 변경, 검증 결과, 남은 위험을 짧게 정리해 주세요.

예를 들어 “회원가입 버튼이 안 눌림”보다 아래처럼 쓰면 AI가 추측할 자리가 줄어든다.

다음 코딩 과제를 처리해 주세요.

목표: 회원가입 화면에서 제출 버튼이 눌리지 않는 문제를 고쳐 주세요.
맥락: app/signup/page.tsx에서 이메일과 비밀번호를 입력해도 버튼이 disabled 상태로 남습니다.
제약: UI 문구와 색상은 바꾸지 말고, 새 패키지는 추가하지 마세요.
검증: npm run lint와 npm run test를 실행하고 실패하면 원인을 설명해 주세요.
보고: 바뀐 파일, 수정 이유, 실행한 명령, 남은 확인 항목을 정리해 주세요.

이 형식의 핵심은 AI가 코드를 쓰기 전에 작업 범위를 읽게 만드는 데 있다. 좋은 프롬프트는 친절한 설명문이 아니라 작은 작업 지시서에 가깝다.

맥락 줄에는 증상보다 재현 조건을 넣어야 한다

맥락을 “버그가 납니다”로 쓰면 AI는 오류를 재현하지 못한 채 코드를 훑는다. 맥락 줄에는 사용자가 실제로 한 행동과 기대 결과, 실제 결과가 들어가야 한다. 가능하면 오류 메시지와 관련 파일도 붙인다.

맥락 줄을 아래 기준으로 다시 써 주세요.

사용자 행동: {어떤 화면에서 무엇을 눌렀는지}
기대 결과: {정상이라면 보여야 할 상태}
실제 결과: {지금 보이는 오류, 빈 화면, 콘솔 메시지}
관련 파일: {알고 있는 파일 경로}
이미 시도한 것: {재시작, 캐시 삭제, 테스트 실행 등}

이 줄이 좋아지면 AI가 바꾸는 파일 수도 줄어든다. “아마 이 파일일 것”이라는 추측 대신 “이 증상을 만들 가능성이 높은 흐름”을 먼저 따라가기 때문이다.

제약 줄은 AI를 느리게 만드는 말이 아니라 사고를 줄이는 말이다

제약을 넣으면 AI가 덜 창의적으로 보일 수 있다. 하지만 코딩 작업에서는 그 편이 더 안전하다. 수업 과제라면 배운 문법 안에서 풀어야 하고, 팀 프로젝트라면 기존 스타일을 유지해야 한다. 새 패키지를 마음대로 넣으면 과제 채점이나 배포 환경에서 실패할 수 있다.

상황	제약 줄 예시
학습 과제	아직 React Hook만 배웠으니 상태 관리 라이브러리는 쓰지 마세요.
기존 프로젝트	기존 컴포넌트 구조와 CSS 클래스 이름을 유지해 주세요.
작은 버그 수정	관련 없는 리팩터링은 하지 말고 실패 원인에 필요한 줄만 바꿔 주세요.
배포 전 수정	새 의존성 추가, DB 스키마 변경, 환경 변수 변경은 하지 마세요.

제약은 AI를 막는 장치가 아니라 검토 시간을 줄이는 장치다. 특히 처음 맡기는 코딩 과제라면 “새 패키지 금지”, “관련 없는 파일 수정 금지”, “테스트 실패 시 멈추고 보고” 세 문장을 자주 쓴다.

검증 줄을 빼면 작업이 끝났는지 알 수 없다

AI가 “수정했습니다”라고 말해도 실제로 실행되지 않은 경우가 있다. 그래서 요청문에는 검증 명령을 넣어야 한다. 테스트가 없는 작은 과제라도 최소한 실행 방법이나 확인 화면을 써 두는 편이 낫다.

수정 후 아래 순서로 확인해 주세요.

1. npm run lint
2. npm run test
3. npm run build
4. 실패한 명령이 있으면 실패 로그의 핵심 줄과 다음 수정 방향을 알려 주세요.
5. 모든 명령을 실행하지 못했다면 실행하지 못한 이유를 분리해서 적어 주세요.

검증 줄에는 “성공하면 좋겠다”가 아니라 실제 명령을 넣는다. 과제 저장소라면 npm test, pytest, go test ./..., pnpm build처럼 프로젝트에 맞는 명령을 적는다. 모르면 “package.json을 확인해서 가장 가까운 검증 명령을 찾고 실행해 주세요”라고 쓴다.

결과가 이상하면 전체 프롬프트를 다시 쓰지 말고 증상만 고친다

첫 결과가 마음에 들지 않을 때 전체 요청을 새로 쓰면 대화가 길어진다. 증상별로 짧은 수정문을 붙이는 편이 빠르다.

결과 증상	다시 붙여 넣을 수정문
파일을 너무 많이 바꿈	이번 작업과 직접 관련 없는 변경을 되돌리지 말고 목록으로 분리해 주세요. 필요한 최소 파일만 남기는 패치를 다시 제안해 주세요.
설명은 좋은데 코드가 안 바뀜	설명보다 실제 수정이 필요합니다. 관련 파일을 수정하고 실행한 검증 명령을 보고해 주세요.
테스트를 안 돌림	완료라고 말하기 전에 가능한 검증 명령을 실행해 주세요. 실행할 수 없으면 이유와 대신 확인한 내용을 나눠 적어 주세요.
새 패키지를 추가함	새 의존성 없이 같은 문제를 해결하는 방식으로 다시 수정해 주세요. 추가한 패키지가 있다면 왜 필요한지 먼저 설명해 주세요.
코드 스타일이 달라짐	기존 파일의 네이밍, 함수 구조, 포맷을 따르도록 수정해 주세요. 스타일 변경은 기능 수정과 분리해 주세요.

이 수정문은 AI를 꾸짖는 문장이 아니라 작업 기준을 다시 좁히는 문장이다. 코딩사관학교 학습자라면 특히 “내가 배운 범위 안에서 설명해 주세요”를 자주 붙이는 것이 좋다.

오늘 바로 쓰려면 5줄 템플릿 하나만 저장한다

처음부터 완벽한 프롬프트 모음을 만들 필요는 없다. 아래 템플릿 하나를 저장해 두고 {} 안만 바꾸면 된다.

다음 코딩 과제를 처리해 주세요.

목표: {}
맥락: {}
제약: {}
검증: {}
보고: 바뀐 파일, 핵심 변경, 실행한 검증, 남은 위험을 짧게 정리해 주세요.

AI 코딩 도구는 막연한 부탁을 알아서 과제 명세로 바꿔 주기도 하지만, 그 과정에서 잘못된 전제를 세울 수 있다. 사용자가 먼저 목표, 맥락, 제약, 검증을 고정하면 AI는 더 작은 범위에서 움직인다. 오늘 맡길 과제가 있다면 코드부터 붙여 넣기보다 이 5줄을 먼저 채우는 편이 빠르다.

코딩 과제를 AI에게 맡기기 전 5줄로 써야 할 것