BACKEND

AI 기반 자동 코드 생성 — 백엔드 작업 지시·테스트·검증

junetapa 2026. 10. 30 업데이트 12 min read

AI 기반 자동 코드 생성을 백엔드 작업에 쓰는 순서를 정리한다. 어떤 일을 맡기고, 어떻게 지시하고, 무엇으로 검증할지가 핵심이다. 특정 모델의 순위나 점수는 판이 바뀔 때마다 달라지므로 이 글에서는 다루지 않고, 도구와 무관하게 오래 쓰는 작업 방식(규칙 파일, 테스트를 명세로 쓰기, 정지 조건, 측정 데이터와 함께 맡기는 최적화)을 공식 문서 기준으로 정리했다.

무엇이 바뀌었나 — 자동완성에서 저장소 에이전트로

AI 코드 생성 도구는 크게 두 층으로 나뉜다. IDE 안에서 다음 줄이나 함수 하나를 제안하는 인라인 자동완성, 그리고 작업을 받아 저장소를 탐색하고 여러 파일을 고치고 명령을 실행해 결과를 확인하는 저장소 단위 에이전트다. Claude Code, Codex, Cursor의 에이전트 모드, GitHub Copilot의 에이전트 기능이 후자에 속한다.

백엔드 작업은 후자의 비중이 크다. API 엔드포인트 추가, 스키마 마이그레이션, 서비스 간 의존성 정리처럼 변경 하나가 여러 파일에 걸치기 때문이다. 그만큼 위험도 커진다. 에이전트는 빠르게 많은 줄을 바꾸고, 사람의 리뷰 속도는 그대로다. 그래서 이 글의 초점은 «더 많이 만들기»가 아니라 «검증할 수 있게 만들기»다. 도구별 기능·요금 비교는 AI 코딩 도구 비교 2026 — Claude Code·Codex·Cursor에 따로 정리했다.

bash
# 저장소에서 에이전트에게 작업을 맡기는 예
claude "auth 미들웨어에 로그인 시도 횟수 제한을 추가하고,
        tests/auth 아래에 통합 테스트를 작성한 뒤
        npm test 가 통과하면 바뀐 파일 목록만 보고해"

맡길 일과 남길 일

AI에 맡기기 좋은 일사람이 정하거나 확인할 일
정해진 패턴의 반복 코드(DTO, 검증 스키마, 라우트 연결)도메인 규칙과 경계(무엇이 한 트랜잭션인가)
기존 테스트를 통과하는 범위의 리팩터링공개 API·DB 스키마의 호환성 판단
테스트 초안(경계값·오류 경로 나열)테스트가 실제 요구를 담았는지
로그·스택 트레이스 읽고 원인 후보 좁히기운영 데이터 수정, 배포 결정
마이그레이션 파일·문서 초안보안 관련 변경(인증·권한·암호화)의 최종 승인

왼쪽 일은 «틀렸을 때 테스트나 리뷰로 바로 드러나는» 일이고, 오른쪽 일은 «틀려도 한참 뒤에 드러나는» 일이다. 이 구분이 맡길 범위를 정하는 가장 실용적인 기준이다.

도구 층을 작업에 맞춰 고른다

모든 일을 저장소 에이전트에게 맡길 필요는 없다. 함수 하나를 채우거나 반복 패턴을 이어 쓰는 일은 인라인 자동완성이 빠르고, 사람이 흐름을 계속 쥐고 있어 리뷰 부담도 작다. 여러 파일을 함께 바꾸고 테스트를 돌려 가며 고쳐야 하는 일, 예를 들어 새 엔드포인트를 라우트·서비스·저장소·테스트까지 한 번에 추가하는 일은 에이전트가 맞다. 원인을 모르는 버그는 먼저 에이전트에게 «고치지 말고 원인 후보와 확인 방법만 보고»하게 한 뒤, 사람이 원인을 고르고 나서 수정을 맡기는 두 단계가 안전하다. 처음부터 «고쳐 줘»라고 하면 증상만 가리는 변경이 나오기 쉽다.

세션을 길게 끌지 않는 것도 요령이다. 한 세션에 여러 작업을 이어 붙이면 앞 작업의 맥락이 뒤 작업 판단에 섞인다. 작업 하나가 끝나면 결과를 커밋하고, 다음 작업은 새 세션에서 규칙 파일과 지시문만으로 시작한다.

규칙 파일 — 매번 설명하지 않게

에이전트는 세션마다 새 맥락으로 시작한다. 빌드·테스트 명령, 코드 스타일, 건드리면 안 되는 폴더를 매번 설명하지 않으려면 저장소에 규칙 파일을 둔다.

파일읽는 도구문서 설명
AGENTS.md여러 코딩 에이전트가 함께 쓰는 열린 형식«에이전트용 README». 설치 명령·코드 스타일·테스트 방법·PR 규칙. 모노레포에서는 고치는 파일에 가장 가까운 파일이 이김
CLAUDE.mdClaude Code프로젝트·사용자 단위 지시. 저장소의 AGENTS.md를 대신 읽을 수도 있음
AGENTS.md
# orders-api

## 명령
- 설치: npm ci
- 테스트: npm test (변경 뒤 반드시 실행)
- 타입 검사: npm run typecheck

## 규칙
- 라우트는 src/routes, 비즈니스 로직은 src/services 에만 둔다
- DB 접근은 src/repositories 를 거친다 (라우트에서 직접 쿼리 금지)
- 마이그레이션 파일은 새로 만들기만 하고 기존 파일은 고치지 않는다
- .env, secrets/ 는 읽지도 고치지도 않는다

Claude Code 문서는 이런 지시가 «강제 설정이 아니라 맥락»이라고 분명히 적는다. 모델이 지시를 어길 가능성이 남으므로, 꼭 막아야 하는 동작(비밀 파일 읽기, 특정 명령 실행)은 지시문이 아니라 도구 실행 전에 거르는 훅(PreToolUse) 같은 장치로 막으라고 권한다. 지시는 짧고 구체적일수록 잘 지켜진다.

작업 지시 네 칸 — 범위·명세·검증·정지

막연한 «이거 고쳐 줘» 대신 네 칸을 채워 지시하면 결과를 검증하기 쉬워진다.

1

범위 — 작게 쪼갠다

«인증 전체 리팩터링» 대신 «로그인 엔드포인트에 토큰 갱신 추가»처럼 한 단위로 나눈다. 작은 변경일수록 리뷰가 쉽고 되돌리기 안전하다.

2

명세 — 테스트로 준다

기대 동작을 테스트로 먼저 쓰거나, 테스트부터 작성하게 하고 사람이 그 테스트를 먼저 리뷰한다. 통과해야 할 테스트가 있으면 모델이 따라야 할 기준이 분명해진다.

3

검증 — 명령으로 적는다

«잘 동작하게»가 아니라 «npm test와 npm run typecheck가 통과» 같은 실행 가능한 조건을 준다.

4

정지 — 끝낼 조건을 건다

«통과하면 멈추고 바뀐 파일 목록과 요약만 보고»처럼 종료 조건을 건다. 범위 밖 수정과 끝없는 고치기 반복을 막는다.

text
작업: orders 서비스 결제 처리에 멱등 키(Idempotency-Key)를 추가한다.

범위:
  - POST /orders/{id}/pay 경로와 src/services/payment.ts 만 수정
  - Idempotency-Key 헤더로 24시간 안 중복 요청은 첫 응답을 그대로 돌려줌

명세:
  - tests/payment-idempotency.test.ts 를 먼저 작성해 보여 줄 것
    (같은 키 두 번 → 결제 1번 · 다른 키 → 각각 결제 · 키 없음 → 400)

검증:
  - npm test, npm run typecheck 통과
  - 기존 결제 테스트가 깨지지 않을 것

정지:
  - 위 조건을 통과하면 멈추고, 바뀐 파일 목록과 판단이 필요했던 점만 보고

성능 최적화는 측정 데이터와 함께

AI를 백엔드 성능 개선에 쓸 때 가장 큰 차이를 만드는 것은 측정 데이터를 함께 주는가다. «느린 것 같으니 빠르게 해 줘»는 추측을 부르고, 실행 계획과 구간별 시간을 주면 근거 있는 제안이 나온다. N+1 쿼리 제거, 인덱스 추가, 캐시, 비동기 처리 전환이 대표적인 결과물이다.

text
문제: GET /api/users/{id}/orders 응답이 느리다.

측정 데이터(첨부):
  - 추적(trace) 결과: 요청 시간 대부분이 DB 구간
  - EXPLAIN (ANALYZE, BUFFERS) 결과: orders 순차 스캔
  - 주문마다 product 를 따로 조회 (N+1)

요청:
  1) orders(user_id, created_at DESC) 인덱스 마이그레이션 (CONCURRENTLY)
  2) product 를 한 번의 조인 또는 IN 조회로 묶기
  3) 같은 벤치마크 스크립트로 바꾸기 전/후 p95 를 측정해 표로 보고
  4) 응답 JSON 모양이 바뀌지 않았음을 기존 테스트로 확인

마지막 두 줄이 중요하다. 개선 폭은 AI의 예상치가 아니라 같은 조건에서 다시 잰 값으로 확인하고, 응답 모양이 그대로인지 기존 테스트로 지킨다. 실행 계획 읽는 법과 인덱스를 안전하게 적용하는 조건은 AI 기반 데이터베이스 쿼리 최적화에 정리했다.

검증 단계 — 생성 속도보다 리뷰 속도

검증의 출발점은 «무엇이 바뀌었는지 사람이 한눈에 볼 수 있는가»다. 에이전트에게 변경을 작게 나눠 커밋하게 하고, 커밋 메시지에 왜 그렇게 바꿨는지를 한 줄씩 남기게 하면 리뷰어가 diff를 따라가기 쉽다. 한 PR에 구현·리팩터링·서식 정리가 섞이면 검토 시간이 크게 늘어나므로, 기능 변경과 정리 변경은 PR을 나눈다. 리뷰어는 구현보다 테스트 변경을 먼저 읽고, 그다음 공개 인터페이스(라우트·스키마·설정)가 바뀐 곳을 확인한 뒤, 마지막에 내부 구현을 본다. 이 순서면 «테스트를 고쳐 통과시킨» 변경과 «호환을 깨는» 변경을 먼저 잡을 수 있다.

테스트와 리뷰, 정적 분석 등 에이아이 생성 코드의 품질 관리 방법을 정리한 도해
생성 속도가 빨라진 만큼 «걸러 내는 장치»가 더 필요해진다.

AI가 만든 변경은 사람이 쓴 변경과 같은 관문을 지나되, 몇 가지를 더 본다.

관문무엇을AI 변경에서 특히 볼 것
1. 자동 검사타입 검사·린트·테스트·의존성 취약점 점검테스트를 «통과하도록» 고쳐 버린 흔적(단언 삭제, skip)
2. diff 읽기범위 밖 파일이 바뀌었는지지시하지 않은 설정·의존성 추가
3. 보안 관점입력 검증, 권한 확인, 비밀 값로그에 토큰·개인정보를 찍는 코드
4. 운영 관점마이그레이션 잠금, 타임아웃, 재시도운영 데이터 크기에서의 실행 시간
5. 기록무엇을 맡겼고 무엇을 고쳤는지 PR 설명사람이 판단한 지점 명시

AI 변경에서 자주 보이는 실수

  • 테스트 약화 — 실패하는 단언을 지우거나 기대값을 실제 결과에 맞춰 고쳐 «통과»시킨다. 테스트 파일의 diff는 구현 diff보다 먼저 읽는다.
  • 있지 않은 API 호출 — 라이브러리에 없는 함수나 옛 판의 옵션을 쓴다. 타입 검사와 실제 실행으로 걸러지지만, 동적 언어에서는 테스트가 그 경로를 지나야 드러난다.
  • 예외 삼키기 — 오류를 잡아 로그만 남기고 성공처럼 돌려준다. 결제·저장 경로에서는 실패를 호출한 쪽에 그대로 알리는지 확인한다.
  • 조용한 의존성 추가 — 작은 기능을 위해 새 패키지를 들인다. 잠금 파일 변경이 있으면 이유를 PR 설명에 적게 한다.
  • 범위 밖 정리 — 지시하지 않은 이름 바꾸기·서식 정리가 섞여 리뷰할 diff가 커진다. 지시문에 «범위 밖 파일은 고치지 않는다»를 넣는다.

CI에서 이 관문을 자동으로 돌리는 구성은 자동화된 테스트·배포 파이프라인에 정리했다. 프런트엔드 쪽 검증 순서(접근성·Core Web Vitals)는 AI 기반 코드 생성 프론트엔드 활용법에서 같은 틀로 다뤘다.

정리 — 팀에 들이는 순서

팀에 에이아이 도구를 도입할 때의 단계와 주의점을 정리한 도해
도구를 나눠 주는 것과 팀이 쓰게 되는 것은 다른 일이다.

도구는 빠르게 바뀌지만 «작게 쪼개고, 테스트로 지키고, 사람이 최종 검증한다»는 원칙은 그대로다. 팀에 들일 때는 아래 순서가 위험이 적다.

순서할 일확인
1테스트·타입 검사 명령 정비한 줄 명령으로 전체 검증이 돈다
2AGENTS.md(또는 CLAUDE.md) 작성명령·폴더 규칙·금지 경로가 적혀 있다
3꼭 막을 동작은 훅·권한 설정으로비밀 파일·위험 명령이 지시문에만 의존하지 않는다
4작은 작업부터 네 칸 지시로 맡기기PR마다 범위·검증 결과가 붙는다
5리뷰 관문에 AI 변경 점검 항목 추가테스트 약화·범위 밖 변경을 걸러 낸다
6지표 보기리드 타임과 변경 실패율을 함께 본다(속도만 보지 않음)
AI 기반 자동 코드 생성 대표 그림 — 왼쪽에 제목 글자가 있고, 오른쪽에 작업 카드가 코드 블록으로 바뀌어 체크 표시가 있는 검사 관문을 지나는 장면
AI 기반 자동 코드 생성 — 백엔드 작업 지시·테스트·검증.

자주 묻는 것

AI 코딩 에이전트에게 백엔드 작업을 어디까지 맡겨도 되나요?

반복 코드, 기존 테스트를 통과하는 범위의 리팩터링, 테스트 초안처럼 틀렸을 때 테스트나 리뷰로 바로 드러나는 일부터 맡깁니다. 공개 API·DB 스키마 호환성, 보안 관련 변경, 배포 결정처럼 틀려도 늦게 드러나는 일은 사람이 정합니다.

AGENTS.md와 CLAUDE.md는 무엇이 다른가요?

AGENTS.md는 여러 코딩 에이전트가 함께 읽는 열린 형식의 규칙 파일이고, CLAUDE.md는 Claude Code가 읽는 지시 파일입니다. Claude Code는 저장소의 AGENTS.md를 대신 읽을 수도 있어, 팀이 여러 도구를 쓴다면 AGENTS.md 하나에 명령과 규칙을 모으는 방법이 편합니다.

규칙 파일에 금지라고 적으면 에이전트가 반드시 지키나요?

반드시 지킨다고 볼 수 없습니다. Claude Code 문서는 이런 지시가 강제 설정이 아니라 맥락이라고 설명합니다. 비밀 파일 읽기나 위험한 명령처럼 꼭 막아야 하는 동작은 도구 실행 전에 거르는 훅이나 권한 설정으로 막습니다.

AI가 제안한 성능 개선은 어떻게 확인하나요?

실행 계획과 구간별 시간 같은 측정 데이터를 함께 주고 제안을 받은 뒤, 같은 벤치마크로 바꾸기 전후 값을 다시 재서 비교합니다. 응답 모양이 바뀌지 않았는지는 기존 테스트로 확인합니다.

참고 자료

  1. Claude Code Docs. How Claude remembers your project — CLAUDE.md·AGENTS.md 읽기, 지시는 맥락이지 강제 설정이 아님, 막을 동작은 PreToolUse 훅(2026-10-30 확인). code.claude.com
  2. AGENTS.md — 에이전트용 README·담을 내용·모노레포에서 가장 가까운 파일 우선(2026-10-30 확인). agents.md
  3. PostgreSQL 18 Docs. CREATE INDEX — CONCURRENTLY 조건(2026-10-30 확인). postgresql.org
AI 코딩 Claude Code Cursor GitHub Copilot 에이전트 코딩 코드 최적화 백엔드
junetapa(박준철)
개발자가 아니라 쓰는 사람. IT 현장 27년의 기준으로 AI 도구를 고르고 기록한다.
Twitter Facebook URL 복사