코드베이스를 에이전트가 읽는 시대
소프트웨어 개발 방식이 근본적으로 바뀌고 있다. 코드는 더 이상 사람만을 위해 작성되는 것이 아니다. Cursor, GitHub Copilot Agent Mode, Claude Code와 같은 자동화 CLI 도구들이 코드베이스를 직접 탐색하고, 디버깅하며, 기능을 확장하는 시대가 열렸다. 이 흐름 속에서 4년 차 이상의 Java 백엔드 개발자라면 단순히 "작동하는 코드"를 넘어, 에이전트가 이해할 수 있는 구조를 설계하는 역량이 점점 중요해지고 있다.
이제 코드베이스의 가독성과 맥락 전달력은 팀원 온보딩 수준을 넘어, 자동화 도구의 작업 품질을 좌우하는 핵심 요소가 된다. 구조화된 프로젝트 설명과 명확한 컨벤션이 없다면 에이전트는 잘못된 방향으로 코드를 수정하거나 엉뚱한 의존성을 추가할 수 있다.
AGENTS.md가 필요한 이유
AGENTS.md는 프로젝트 루트에 위치하는 에이전트 전용 가이드 문서다. README가 사람을 위한 진입점이라면, AGENTS.md는 자동화 도구가 코드베이스의 구조, 규칙, 실행 방법을 파악하도록 돕는 명세서다. 다음과 같은 정보를 담는 것이 효과적이다.
- 프로젝트 개요: 어떤 도메인을 다루는 서비스인지, 모듈 구성은 어떻게 되는지
- 빌드 및 실행 명령어: 에이전트가 로컬에서 직접 빌드하고 테스트를 수행할 수 있도록 명확한 커맨드 제공
- 코딩 컨벤션: 패키지 구조, 네이밍 규칙, 레이어 분리 원칙
- 금지 사항: 수정하면 안 되는 파일, 직접 변경을 피해야 하는 설정 등
## Build & Test
./mvnw quarkus:dev # 개발 서버 실행 (Dev Services 자동 구성)
./mvnw test # 전체 테스트 수행
## Conventions
- REST 리소스 클래스는 `*Resource.java`로 명명
- 비즈니스 로직은 `*Service.java`에만 위치
- DB 접근은 반드시 `*Repository.java` 경유
Quarkus가 에이전트 친화적인 이유
Quarkus는 이러한 에이전트 친화적 환경 구축에 유리한 출발점을 제공한다. 초고속 개발 루프(Live Coding)는 에이전트가 코드를 수정한 직후 결과를 즉시 확인할 수 있게 해주며, 내장된 Dev Services는 데이터베이스나 메시지 브로커 같은 인프라를 별도 설정 없이 자동으로 구성해준다.
# Quarkus Dev Services - 에이전트 실행 시 별도 인프라 설정 불필요
./mvnw quarkus:dev
# PostgreSQL, Kafka 등 자동 컨테이너 기동
지속적 테스트(Continuous Testing) 기능은 에이전트가 파일을 변경할 때마다 테스트를 자동으로 재실행하므로, 코드 품질 피드백 루프가 즉각적으로 동작한다. 에이전트 입장에서 보면 수정 후 결과를 빠르게 확인할 수 있는 환경이 갖춰져 있다는 뜻이다. 이는 에이전트의 반복 작업 효율을 크게 높여준다.
정리
AGENTS.md는 자동화 에이전트가 코드베이스를 올바르게 이해하고 작업하도록 돕는 에이전트 전용 가이드 문서다.- 빌드 명령, 코딩 컨벤션, 금지 사항을 명시해두면 에이전트의 코드 수정 품질이 크게 향상된다.
- Quarkus의 Dev Services와 지속적 테스트는 에이전트 친화적 개발 환경의 강력한 기반이 된다.