AI를 활용한 코드 생성

파일 조작을 익혔으니 이제 코드를 만들게 할 차례입니다. 이 글은 "무엇을 주면 원하는 결과가 나오는지"를 다룹니다. 원구연 강사의 8주 교재 5주차가 이 주제 하나에 통째로 할애된 이유는, 환경이 갖춰진 뒤 문제가 가장 많이 터지는 곳이 결국 지시 방식이기 때문입니다. 다음 글은 「디버깅 지원 기능」입니다.

핵심 요약

• 좋은 지시는 범위, 목적, 제약, 검증 기준 네 요소를 갖춥니다.
• 기존 코드의 패턴을 기준으로 삼게 하면 프로젝트와 어긋나지 않습니다.
• 테스트를 먼저 쓰게 하면 Claude Code가 스스로 검증 루프를 닫습니다.
• 큰 기능은 5~6단계로 쪼개고 단계마다 QA와 커밋을 합니다.

좋은 지시의 네 요소

교재 5주차의 정의는 한 줄입니다. 좋은 요청은 범위, 목적, 제약조건, 검증기준입니다. 공식 모범 사례도 "지시사항이 정확할수록 필요한 수정이 적습니다"라고 말합니다.

네 요소가 모두 들어간 황금 문장은 통째로 외워 두면 됩니다.

기존 기능은 절대 삭제하지 말고, 현재 오류의 원인을 먼저 분석한 뒤
최소 수정으로 해결해 주세요.
수정 후 변경된 파일, 수정 이유, 테스트 방법을 정리해 주세요.

기존 코드를 기준으로 삼기

새 기능을 만들 때 프로젝트에 이미 있는 비슷한 코드를 가리키면 결과가 프로젝트 스타일에 맞게 나옵니다. 공식 모범 사례의 방식은 "기존 위젯이 어떻게 구현되는지 먼저 보고, 그 패턴을 따라 새 위젯을 만들라"입니다. 우리 식으로 쓰면 이렇습니다.

@src/reports/weekly.py 가 보고서를 만드는 방식을 먼저 파악해 줘.
같은 패턴으로 월간 보고서 monthly.py를 만들어 줘.
프로젝트에서 이미 쓰는 라이브러리 외에는 새로 추가하지 마.

제약이 없으면 AI는 필요한 것보다 큰 도구를 가져옵니다.

테스트를 먼저 시키기

공식 문서의 표현을 빌리면 "Claude는 작업이 완료된 것처럼 보일 때 멈춥니다." 실행할 수 있는 확인 방법이 없으면 사람이 검증 루프가 됩니다. 테스트 케이스를 지시문에 넣으면 Claude Code가 작업하고, 테스트를 돌리고, 결과를 읽고, 통과할 때까지 반복합니다.

사업자번호 검증 함수 validate_biz_no를 만들어 줘.
테스트 케이스: "123-45-67890"은 True, "12345"는 False, 빈 문자열은 False.
먼저 실패하는 테스트를 작성하고, 구현한 뒤 테스트를 실행해서 결과를 보여 줘.

우리 교육이 "정지 규칙은 증거"라고 말하는 것이 이것입니다. 테스트 출력이 증거이고, 그것이 나와야 끝입니다.

단계를 나누기

교재 5주차의 예를 그대로 옮깁니다. "고객 상담 관리 시스템 만들어 줘"는 잘못된 요청입니다. 좋은 요청은 이렇게 쪼갭니다.

1. 고객 목록 화면 만들기
2. 고객 상세 화면 만들기
3. 상담 기록 입력 폼 만들기
4. 상담 기록 DB 저장하기
5. 담당자별 조회 만들기
6. 주간 요약 보고서 뽑기

각 단계가 끝날 때마다 정상 동작을 확인하고 커밋한 뒤 다음 단계로 갑니다. 쪼개기 자체도 시킬 수 있습니다. "이 기능을 작은 단계로 나눠서 계획을 먼저 보여 줘. 1단계부터 하나씩, 각 단계 끝나면 QA 항목 알려 줘." Shift+Tab으로 plan 모드에 들어가 이 지시를 주면 편집 없이 계획만 받을 수 있습니다.

생성된 코드를 검토하는 눈

코드를 다 읽을 필요는 없습니다. 교재 5주차의 QA 항목을 검토 기준으로 씁니다.

• 코드 관점: 기존 기능이 덮어써지지 않았나, 불필요한 중복이 없나, 콘솔 에러가 없나, .env나 키 같은 민감정보가 코드에 박히지 않았나.
• 서비스 관점: 버튼이 실제로 동작하나, 조회·저장·수정·삭제가 되나, 화면 문구와 데이터가 맞나.

검토를 시키는 문장도 정해져 있습니다. "방금 작업에 대한 QA 체크리스트를 만들어서 하나씩 검증하고, 결과를 통과/실패로 보고해 줘." 원구연 강사는 여기에 다른 AI의 교차 검수를 더해 맹점을 보완합니다.

안 될 때 쓰는 문장

결과가 틀렸을 때 "다시 해 줘"는 도움이 안 됩니다. 무엇이 어떻게 틀렸는지, 그리고 "고쳐짐"이 무엇인지 적습니다.

결과가 틀렸어. 기대: 8월 매출 합계 1,240,000원. 실제: 0원.
@data/sales.csv 의 날짜 열 형식을 확인하고, 원인을 먼저 설명한 뒤 최소 수정으로 고쳐 줘.

같은 문제를 두 번 고쳐도 안 되면 컨텍스트가 실패한 접근으로 어지러워진 상태입니다. 공식 모범 사례대로 /clear 후 배운 내용을 넣은 더 구체적인 지시로 새로 시작합니다.

연습 문제

1. 최근에 AI에게 했던 요청 하나를 골라 네 요소(범위, 목적, 제약, 검증)로 다시 써 보세요.
2. 작은 함수 하나를 테스트 케이스 세 개와 함께 지시하고, 테스트 출력을 캡처하세요.
3. 만들고 싶은 기능 하나를 5~6단계로 쪼개 plan 모드에서 계획만 받아 보세요.

다음 레슨

만든 코드는 언젠가 깨집니다. 다음 글 「디버깅 지원 기능」에서 "고쳐 줘"보다 강력한 지시와 원인 추적 흐름을 배웁니다.

정리

• 범위·목적·제약·검증이 빠진 요청은 AI를 추측하게 만듭니다.
• 기존 코드를 기준으로, 테스트를 먼저, 단계를 나눠서 시킵니다.
• 검토는 QA 체크리스트로, 실패는 기대값과 실제값을 적어 알립니다.

자주 묻는 질문