무엇이 바뀌었나 — 자동완성에서 저장소 에이전트로
AI 코드 생성 도구는 크게 두 층으로 나뉜다. IDE 안에서 다음 줄이나 함수 하나를 제안하는 인라인 자동완성, 그리고 작업을 받아 저장소를 탐색하고 여러 파일을 고치고 명령을 실행해 결과를 확인하는 저장소 단위 에이전트다. Claude Code, Codex, Cursor의 에이전트 모드, GitHub Copilot의 에이전트 기능이 후자에 속한다.
백엔드 작업은 후자의 비중이 크다. API 엔드포인트 추가, 스키마 마이그레이션, 서비스 간 의존성 정리처럼 변경 하나가 여러 파일에 걸치기 때문이다. 그만큼 위험도 커진다. 에이전트는 빠르게 많은 줄을 바꾸고, 사람의 리뷰 속도는 그대로다. 그래서 이 글의 초점은 «더 많이 만들기»가 아니라 «검증할 수 있게 만들기»다. 도구별 기능·요금 비교는 AI 코딩 도구 비교 2026 — Claude Code·Codex·Cursor에 따로 정리했다.
# 저장소에서 에이전트에게 작업을 맡기는 예
claude "auth 미들웨어에 로그인 시도 횟수 제한을 추가하고,
tests/auth 아래에 통합 테스트를 작성한 뒤
npm test 가 통과하면 바뀐 파일 목록만 보고해"맡길 일과 남길 일
| AI에 맡기기 좋은 일 | 사람이 정하거나 확인할 일 |
|---|---|
| 정해진 패턴의 반복 코드(DTO, 검증 스키마, 라우트 연결) | 도메인 규칙과 경계(무엇이 한 트랜잭션인가) |
| 기존 테스트를 통과하는 범위의 리팩터링 | 공개 API·DB 스키마의 호환성 판단 |
| 테스트 초안(경계값·오류 경로 나열) | 테스트가 실제 요구를 담았는지 |
| 로그·스택 트레이스 읽고 원인 후보 좁히기 | 운영 데이터 수정, 배포 결정 |
| 마이그레이션 파일·문서 초안 | 보안 관련 변경(인증·권한·암호화)의 최종 승인 |
왼쪽 일은 «틀렸을 때 테스트나 리뷰로 바로 드러나는» 일이고, 오른쪽 일은 «틀려도 한참 뒤에 드러나는» 일이다. 이 구분이 맡길 범위를 정하는 가장 실용적인 기준이다.
도구 층을 작업에 맞춰 고른다
모든 일을 저장소 에이전트에게 맡길 필요는 없다. 함수 하나를 채우거나 반복 패턴을 이어 쓰는 일은 인라인 자동완성이 빠르고, 사람이 흐름을 계속 쥐고 있어 리뷰 부담도 작다. 여러 파일을 함께 바꾸고 테스트를 돌려 가며 고쳐야 하는 일, 예를 들어 새 엔드포인트를 라우트·서비스·저장소·테스트까지 한 번에 추가하는 일은 에이전트가 맞다. 원인을 모르는 버그는 먼저 에이전트에게 «고치지 말고 원인 후보와 확인 방법만 보고»하게 한 뒤, 사람이 원인을 고르고 나서 수정을 맡기는 두 단계가 안전하다. 처음부터 «고쳐 줘»라고 하면 증상만 가리는 변경이 나오기 쉽다.
세션을 길게 끌지 않는 것도 요령이다. 한 세션에 여러 작업을 이어 붙이면 앞 작업의 맥락이 뒤 작업 판단에 섞인다. 작업 하나가 끝나면 결과를 커밋하고, 다음 작업은 새 세션에서 규칙 파일과 지시문만으로 시작한다.
규칙 파일 — 매번 설명하지 않게
에이전트는 세션마다 새 맥락으로 시작한다. 빌드·테스트 명령, 코드 스타일, 건드리면 안 되는 폴더를 매번 설명하지 않으려면 저장소에 규칙 파일을 둔다.
| 파일 | 읽는 도구 | 문서 설명 |
|---|---|---|
AGENTS.md | 여러 코딩 에이전트가 함께 쓰는 열린 형식 | «에이전트용 README». 설치 명령·코드 스타일·테스트 방법·PR 규칙. 모노레포에서는 고치는 파일에 가장 가까운 파일이 이김 |
CLAUDE.md | Claude Code | 프로젝트·사용자 단위 지시. 저장소의 AGENTS.md를 대신 읽을 수도 있음 |
# orders-api ## 명령 - 설치: npm ci - 테스트: npm test (변경 뒤 반드시 실행) - 타입 검사: npm run typecheck ## 규칙 - 라우트는 src/routes, 비즈니스 로직은 src/services 에만 둔다 - DB 접근은 src/repositories 를 거친다 (라우트에서 직접 쿼리 금지) - 마이그레이션 파일은 새로 만들기만 하고 기존 파일은 고치지 않는다 - .env, secrets/ 는 읽지도 고치지도 않는다
Claude Code 문서는 이런 지시가 «강제 설정이 아니라 맥락»이라고 분명히 적는다. 모델이 지시를 어길 가능성이 남으므로, 꼭 막아야 하는 동작(비밀 파일 읽기, 특정 명령 실행)은 지시문이 아니라 도구 실행 전에 거르는 훅(PreToolUse) 같은 장치로 막으라고 권한다. 지시는 짧고 구체적일수록 잘 지켜진다.
작업 지시 네 칸 — 범위·명세·검증·정지
막연한 «이거 고쳐 줘» 대신 네 칸을 채워 지시하면 결과를 검증하기 쉬워진다.
범위 — 작게 쪼갠다
«인증 전체 리팩터링» 대신 «로그인 엔드포인트에 토큰 갱신 추가»처럼 한 단위로 나눈다. 작은 변경일수록 리뷰가 쉽고 되돌리기 안전하다.
명세 — 테스트로 준다
기대 동작을 테스트로 먼저 쓰거나, 테스트부터 작성하게 하고 사람이 그 테스트를 먼저 리뷰한다. 통과해야 할 테스트가 있으면 모델이 따라야 할 기준이 분명해진다.
검증 — 명령으로 적는다
«잘 동작하게»가 아니라 «npm test와 npm run typecheck가 통과» 같은 실행 가능한 조건을 준다.
정지 — 끝낼 조건을 건다
«통과하면 멈추고 바뀐 파일 목록과 요약만 보고»처럼 종료 조건을 건다. 범위 밖 수정과 끝없는 고치기 반복을 막는다.
작업: 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 쿼리 제거, 인덱스 추가, 캐시, 비동기 처리 전환이 대표적인 결과물이다.
문제: 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 | 테스트·타입 검사 명령 정비 | 한 줄 명령으로 전체 검증이 돈다 |
| 2 | AGENTS.md(또는 CLAUDE.md) 작성 | 명령·폴더 규칙·금지 경로가 적혀 있다 |
| 3 | 꼭 막을 동작은 훅·권한 설정으로 | 비밀 파일·위험 명령이 지시문에만 의존하지 않는다 |
| 4 | 작은 작업부터 네 칸 지시로 맡기기 | PR마다 범위·검증 결과가 붙는다 |
| 5 | 리뷰 관문에 AI 변경 점검 항목 추가 | 테스트 약화·범위 밖 변경을 걸러 낸다 |
| 6 | 지표 보기 | 리드 타임과 변경 실패율을 함께 본다(속도만 보지 않음) |
자주 묻는 것
AI 코딩 에이전트에게 백엔드 작업을 어디까지 맡겨도 되나요?
반복 코드, 기존 테스트를 통과하는 범위의 리팩터링, 테스트 초안처럼 틀렸을 때 테스트나 리뷰로 바로 드러나는 일부터 맡깁니다. 공개 API·DB 스키마 호환성, 보안 관련 변경, 배포 결정처럼 틀려도 늦게 드러나는 일은 사람이 정합니다.
AGENTS.md와 CLAUDE.md는 무엇이 다른가요?
AGENTS.md는 여러 코딩 에이전트가 함께 읽는 열린 형식의 규칙 파일이고, CLAUDE.md는 Claude Code가 읽는 지시 파일입니다. Claude Code는 저장소의 AGENTS.md를 대신 읽을 수도 있어, 팀이 여러 도구를 쓴다면 AGENTS.md 하나에 명령과 규칙을 모으는 방법이 편합니다.
규칙 파일에 금지라고 적으면 에이전트가 반드시 지키나요?
반드시 지킨다고 볼 수 없습니다. Claude Code 문서는 이런 지시가 강제 설정이 아니라 맥락이라고 설명합니다. 비밀 파일 읽기나 위험한 명령처럼 꼭 막아야 하는 동작은 도구 실행 전에 거르는 훅이나 권한 설정으로 막습니다.
AI가 제안한 성능 개선은 어떻게 확인하나요?
실행 계획과 구간별 시간 같은 측정 데이터를 함께 주고 제안을 받은 뒤, 같은 벤치마크로 바꾸기 전후 값을 다시 재서 비교합니다. 응답 모양이 바뀌지 않았는지는 기존 테스트로 확인합니다.
참고 자료
- Claude Code Docs. How Claude remembers your project — CLAUDE.md·AGENTS.md 읽기, 지시는 맥락이지 강제 설정이 아님, 막을 동작은 PreToolUse 훅(2026-10-30 확인). code.claude.com
- AGENTS.md — 에이전트용 README·담을 내용·모노레포에서 가장 가까운 파일 우선(2026-10-30 확인). agents.md
- PostgreSQL 18 Docs. CREATE INDEX — CONCURRENTLY 조건(2026-10-30 확인). postgresql.org