Development4 min read

모호한 개발 이슈를 AI에 맡기기 전: 작업 범위 분해와 완료 조건 명세 예시

2026년 10월 12일4 min read

AI에게 맡기기 전 작업을 작은 검증 가능한 단위로 나누고, 수정 범위와 완료 조건(수용기준)을 명확히 적은 템플릿과 구체적 예시를 제공합니다. 템플릿은 입력물, 출력물, 검증방법, 비범위(Out-of-scope), 보안·프라이버시 제약을 포함합니다.

#AI#acceptance-criteria#명세#작업분해
모호한 개발 이슈를 AI에 맡기기 전: 작업 범위 분해와 완료 조건 명세 예시

결론부터 말하면: AI에 맡기기 전 각 작업을 ‘수정 범위(scope)’와 ‘완료 조건(acceptance criteria)’으로 짧고 검증 가능하게 명세하면 실패 확률을 크게 줄일 수 있습니다. 아래 템플릿과 예시를 그대로 사용해 보세요.

언제·왜 이 방식이 필요한가

모호한 이슈를 그대로 AI에게 넘기면 결과도 모호합니다. 명확한 범위와 완료 조건은 다음을 보장합니다.

  • AI가 반환해야 할 산출물의 형식과 내용이 명확해집니다.
  • 자동화된 검증(CI 테스트, 단위/통합 테스트, 엔드투엔드 시나리오)을 통해 결과를 기계적으로 판정할 수 있습니다.
  • 프라이버시·보안 제약을 미리 고지하면 민감한 데이터 노출을 줄일 수 있습니다.

어떻게 나누고 명세를 작성할까 — 핵심 원칙

명세를 작성할 때 지켜야 할 최소 원칙들:

  • 작업 단위는 ‘검증 가능한 하나의 가설’이 되도록 작게 쪼갭니다(예: 버그 수정, 단일 API의 응답 포맷 변경, 단위 테스트 추가 등).
  • 입력(현재 코드 위치, 관련 파일, 재현방법)과 출력(변경 파일, 커밋 메시지 형식, 패치 포맷)을 명시합니다.
  • 명확한 완료 조건(테스트 통과, 특정 API 응답 예시와 일치, 성능 수치 달성)을 적습니다.
  • 비범위(Out-of-scope)와 안전성 제약(데이터 마스킹, 외부 전송 금지)을 포함합니다.
  • 검증 방법(로컬 명령, CI 파이프라인, 샘플 요청)과 예상 소요 시간을 기재합니다.

작업 명세 템플릿 (복사해서 사용하세요)

{
  "title": "한 줄 요약(영문/한글)",
  "context": "문제가 발생하는 서비스/모듈과 관련 파일 경로 및 재현 방법(최소한)",
  "scope": {
    "in": ["정확히 무엇을 변경할지(파일/함수/엔드포인트)"],
    "out": ["변경하지 않을 것(아키텍처, DB 스키마 등)"]
  },
  "deliverables": [
    "수정된 파일 리스트(패치/PR),",
    "테스트 코드(단위/통합),",
    "간단한 변경 설명(커밋 메시지/PR 설명)"] ,
  "acceptance_criteria": [
    "자동화 테스트 명령과 기대 결과(예: ./gradlew test 단위테스트 42개 통과),",
    "수동 검사 예시(예: POST /api/users/profile → status 200, body.avatarUrl는 100x100 썸네일 URL)",
    "성능 기준(있다면 구체 수치)"
  ],
  "verification_steps": [
    "로컬 명령어/CI 빌드 명령/예상 출력 스니펫"
  ],
  "constraints": {
    "timebox": "예: 4h/1일/3일",
    "privacy": "민감 데이터 사용 금지, mock 데이터 사용 등",
    "tools": "요구되는 빌드 도구/버전(선택 사항)"
  },
  "estimated_effort": "예: 2h",
  "notes": "추가 참조 자료나 주의 사항"
}

구체적 예시: 프로필 이미지 썸네일 생성 버그

문제: 사용자가 업로드한 프로필 사진에서 썸네일이 생성되지 않음. 재현 방법과 원하는 결과를 명확히 적은 예시입니다.

{
  "title": "Fix: profile image thumbnail generation failure",
  "context": "서비스: user-service, 모듈 경로: services/user-image, 재현: POST /api/users/123/avatar with multipart/form-data image → expected thumbnail at /thumbnails/123.png but missing",
  "scope": {
    "in": ["services/user-image/thumbnailer.js", "services/user-image/tests/thumbnail.test.js"],
    "out": ["DB 마이그레이션, 인증 로직 변경, 인프라(스토리지) 재구성)"]
  },
  "deliverables": [
    "수정된 thumbnailer.js (최대 50줄 변경),",
    "단위 테스트 추가: thumbnail.test.js (성공/실패 케이스 포함),",
    "설명: PR 본문에 재현 방법과 테스트 명령 포함"
  ],
  "acceptance_criteria": [
    "로컬 단위테스트: npm test -- tests/thumbnail.test.js → 3 passed, 0 failed", 
    "수동 API 체크: curl -F 'file=@avatar.jpg' http://localhost:3000/api/users/123/avatar → 응답 status 200, JSON {\"thumbnailUrl\": \"/thumbnails/123.png\"}",
    "썸네일 파일이 ./storage/thumbnails/123.png로 생성되어야 함(이미지 크기 100x100 확인)"
  ],
  "verification_steps": [
    "로컬: npm ci && npm test -- tests/thumbnail.test.js (출력: 3 passed)",
    "로컬 서버 실행 후 curl 요청으로 응답 확인(예시 응답 본문 포함)"
  ],
  "constraints": {
    "timebox": "4h",
    "privacy": "실제 사용자 이미지를 업로드하지 말고 tests/fixtures/avatar.jpg 사용",
    "tools": "Node.js, sharp(이미지 라이브러리) 설치 필요"
  },
  "estimated_effort": "3h",
  "notes": "파일 저장소는 로컬 fs를 사용, S3 연동은 Out-of-scope"
}

AI에게 전달하는 방법(프롬프트 예시)

위 JSON을 그대로 프롬프트에 포함시키고, 출력 형식(예: git patch, PR 본문, 변경된 파일 내용)을 지정합니다. 예시 프롬프트:

System: You are an assistant that edits code in a git repository. Follow the specification strictly and do not access external networks.
User: Here is the task spec (JSON). Return only: 1) a short PR description, 2) a git patch (unified diff) for changed files, 3) unit test command to run and expected output. Do not include any extra text.

이렇게 명시하면 AI가 산출물 형식을 맞추기 쉬워집니다.

검증과 실행 흐름

AI가 산출물을 제출하면 다음 순서로 검증합니다.

  1. 정적 확인: PR 본문과 수정 범위가 명세와 일치하는지 확인.
  2. 로컬 빌드 및 테스트: 명세에 적힌 명령을 실행해 통과 여부 확인. 예: npm test, mvn -Dtest=... test 등.
  3. 수동 시나리오: API 요청/응답을 검증해 수용기준을 만족하는지 확인.
  4. 리뷰: 변경 의도와 사이드 이펙트(로그, 에러 처리 등)를 코드 리뷰로 확인.
  5. 배포 전 안전조치: 중요 변경인 경우 canary/feature-flag 적용 및 모니터링 설정.

예상 테스트 출력(예시):

> npm test -- tests/thumbnail.test.js

 PASS  tests/thumbnail.test.js
  thumbnail generation
    ✓ creates 100x100 thumbnail (45ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.234s

제한사항과 흔한 실수

  • 너무 넓은 요청: "성능 개선"처럼 목표만 주면 AI가 범위를 확장하여 예상 밖의 변경을 만듭니다. 구체적 수치(예: P95 응답시간 200ms 이하)를 제시하세요.
  • 검증 불충분: 테스트나 검증 스크립트를 요구하지 않으면 결과를 자동 판정하기 어렵습니다.
  • 민감 데이터 포함: 실제 프로덕션 데이터를 포함해 전달하지 마세요. 가능한 경우 mock/fixture로 대체합니다.
  • 되돌리기 계획 부재: 변경 실패 시 롤백 방법(예: revert PR, feature flag off)을 명시하지 않으면 위험이 큽니다.
  • 과도한 분해: 너무 자잘한 태스크(한 줄 주석 수정 등)는 오버헤드를 늘립니다. 목적 대비 적정 크기를 유지하세요.

실무 팁: 처음에는 작은 흠집(1~3시간) 단위로 AI에게 맡겨 검증 루프를 빠르게 돌려보세요. 성공 사례가 쌓이면 더 큰 작업으로 확장할 수 있습니다.

실용적 테이크어웨이: 작업 범위를 “무엇을 변경할지(in) / 무엇을 변경하지 않을지(out)”와 검증 가능한 완료 조건으로 명확히 적어 AI에 넘기면 결과의 신뢰성과 검증 속도가 크게 향상됩니다.