AI가 유용한 코드를 작성하게 만드는 데 어려움을 겪었습니다 — 마침내 효과를 본 방법

지난달, 저는 새로운 마이크로서비스 (microservice)를 위해 수십 개의 API 엔드포인트 (endpoints)를 구축해야 했습니다. CRUD 작업, SQLAlchemy 모델, Pydantic 스키마 (schemas)와 같은 패턴은 알고 있었지만, 그 모든 상용구 (boilerplate) 코드를 직접 타이핑하는 것은 영혼을 갉아먹는 기분이었습니다.

저는 AI가 몇 시간을 아껴주길 바라며 도움을 요청했습니다. 그 결과는 잘못된 출력, 환각 (hallucinations), 그리고 좌절의 롤러코스터였습니다. 하지만 일주일간의 실패 끝에, 실제로 신뢰할 수 있고 바로 복사해서 붙여넣을 수 있는 코드를 생성하는 프롬프팅 (prompting) 접근 방식을 찾아냈습니다.

이것은 단순히 "이 도구를 사용하세요"라는 이야기가 아닙니다. 여러분이 응용할 수 있는 실제 사례와 함께, 마침내 저에게 효과가 있었던 기술에 관한 이야기입니다.

문제점: AI가 계속 쓰레기 같은 코드를 작성함

저는 당연한 것부터 시작했습니다: "사용자 생성을 위한 Flask 라우트 (route)를 작성해줘." AI는 다음과 같은 것을 내뱉었습니다:

@app.route('/users', methods=['POST'])
def create_user():
    data = request.json
...

하드코딩된 응답! 입력값조차 사용하지 않았습니다. 다시 시도했습니다: "검증 (validation) 기능이 포함된 적절한 엔드포인트를 작성해줘." AI는 Flask와 FastAPI 문법이 뒤섞인 것을 주었습니다. 정말 미칠 노릇이었습니다.

문제는 저라는 것을 깨달았습니다. 저는 AI에게 제 마음을 읽으라고 요구하고 있었습니다. AI는 저의 데이터베이스 스키마 (database schema), 에러 처리 (error handling) 패턴, 심지어 제가 어떤 ORM을 사용하는지조차 알지 못했습니다.

효과가 없었던 방법들

상황을 더 악화시켰던 몇 가지 시도들을 해보았습니다:

• 모호한 프롬프트 (Vague prompts): "사용자 CRUD를 생성해줘" → 임포트 (imports)도 없는 일반적이고 엉망인 결과물 도출
• 컨텍스트 (context) 없는 원샷 (One-shot): 예시 없음 → 모델이 무작정 추측함
• 이전 메시지를 기억할 것이라는 가정: 상태가 없는 (stateless) API 호출에서는 모든 프롬프트가 새로운 시작임
• 한 번에 너무 많은 것을 요구함: 모듈 전체를 작성하라는 단일 프롬프트 → 출력이 끊기거나 일관성이 없는 경우가 많음

돌파구: 생성 전 구조화하기

저는 AI를 시니어 개발자처럼 대하는 것을 멈추고, 매우 상세한 지침이 필요한 성실한 인턴처럼 대하기 시작했습니다. 핵심은 다음을 제공하는 것이었습니다:

1. 명시적인 입출력 형식 (Explicit input/output format) – “JSON 형식의 모델 정의가 주어지면, Flask 블루프린트 (Flask blueprint) 파일을 생성하라.”
2. 퓨샷 예시 (Few-shot examples) – 생성을 요청하기 전에 두세 개의 완전한 입출력 쌍을 보여줍니다.
3. 역할을 설정하는 시스템 메시지 (A system message setting the role) – “당신은 Python 백엔드 개발자입니다. 당신은 Flask의 베스트 프랙티스 (best practices)를 따르며, 깔끔하고 타입 어노테이션 (type-annotated)이 적용된 코드를 작성합니다.”

다음은 저에게 실제로 효과가 있었던 접근 방식입니다.

퓨샷 프롬프트 템플릿 (The Few-Shot Prompt Template)

저는 Python으로 프롬프트 생성기를 만들었습니다. 이 생성기는 스키마 (schema) 설명을 입력받아 예시가 포함된 프롬프트를 생성합니다:

import requests

def generate_endpoint_code(schema_json: dict) -> str:
...

결과 (The Result)

이러한 변화 이후, AI는 다음과 같은 코드를 생성하기 시작했습니다:

• 실제로 request.json을 사용함
• 올바른 모듈 (modules)을 임포트 (import)함
• 일관된 에러 핸들링 (error handling)을 갖춤
• 저의 명명 규칙 (naming conventions)을 사용함 (예시에서 이를 보여주었기 때문)

그 결과, 저는 출력물을 몇 가지 세부 사항만 수정하여 프로젝트에 바로 복사하여 사용할 수 있었습니다.

교훈 및 트레이드오프 (Lessons Learned & Trade-offs)

이 접근 방식은 마법이 아닙니다. 누군가 저에게 미리 말해줬으면 좋았을 점들은 다음과 같습니다:

• 여전히 모든 것을 검토해야 합니다. AI는 임포트 (imports)를 환각 (hallucinates)하거나 존재하지 않는 메서드 (methods)를 사용합니다. from sqlalchemy import Column, Integer, String은 괜찮았지만, 한 번은 확장 기능 설정 없이는 존재하지 않는 from flask_sqlalchemy import db를 지어낸 적이 있습니다.
• 퓨샷 (Few-shot)은 반복적인 패턴에 가장 효과적입니다. 여러 조건이 포함된 복잡한 비즈니스 로직 (business logic)의 경우, AI는 종종 실수를 합니다. 그런 부분은 여전히 제가 직접 작성합니다.
• 온도 (Temperature) 설정이 중요합니다. 온도를 0.0으로 설정하면 매우 예측 가능한 코드가 나오지만 때로는 딱딱한 코드가 생성됩니다. 저는 0.2로 결정했습니다.
• 컨텍스트 길이 (Context length)는 한계가 있습니다. 제가 제공한 예시들이 토큰 (tokens)을 차지하여, 실제 생성에 사용할 수 있는 공간이 줄어들었습니다. 큰 스키마 (schemas)의 경우 예시를 짧게 줄여야 했습니다.
• 공짜가 아닙니다. API 호출에는 비용이 듭니다. 간단한 스크립트에는 괜찮지만, 수백 개의 엔드포인트 (endpoints)를 생성해야 한다면 템플릿 엔진 (template engine)을 선호하게 될 수도 있습니다.

이 방식을 사용하지 말아야 할 때 (When NOT to Use This)

• 패턴이 사소하여 10초 안에 직접 타이핑할 수 있는 경우.
• 보안이 중요한 경우 – AI는 인증 체크 (authentication checks)를 누락할 수 있습니다.
• 모델이 학습하지 못한 매우 특정한 코드 스타일 (code style)을 준수해야 하는 경우.

다음에 제가 다르게 할 일 (What I'd Do Differently Next Time)

1. 로컬 모델 (local model)에 투자하기. 개인정보 보호와 비용 문제로, 현재는 제 컴퓨터에서 양자화 버전 (quantized version)의 Llama 3를 사용해보고 있습니다. 품질이 근접합니다.
2. 스키마 컴파일러 (schema compiler) 사용하기. AI로 코드를 생성하는 대신, Pydantic 모델을 위해 datamodel-code-generator와 같은 도구를 사용하고, AI는 연결 작업 (wiring; 라우트, 에러 핸들링)에만 사용할 것입니다.
3. 프롬프트 라이브러리 (prompt library) 구축하기. 처음부터 다시 시작하지 않도록 다양한 작업(모델, 라우트, 테스트)에 사용할 수 있는 재사용 가능한 프롬프트 조각들을 보관합니다.

마치며 (Final Thoughts)

AI 코드 생성은 반복적인 상용구 (boilerplate) 작업으로 인한 번아웃으로부터 당신을 구해줄 수 있지만, 만능 해결책 (silver bullet)은 아닙니다. 핵심은 모델에게 너무 모호하지도, 너무 경직되지도 않은 적절한 수준의 구조를 제공하는 것입니다. 퓨샷 프롬프팅 (few-shot prompting)을 활용하세요. 그리고 언제나, 항상 결과물을 검토하십시오.

저는 아직 이 여정의 초입에 있습니다. 여러분은 워크플로우 (workflow)에서 AI가 생성한 코드를 어떻게 다루시나요? 프롬프트에 의존하시나요, 아니면 이를 중심으로 커스텀 도구를 구축하셨나요? 여러분에게 무엇이 효과적인지 꼭 듣고 싶습니다.