AI 에이전트가 코드를 도와주는 수준을 넘어, 구현·테스트·문서·리뷰·CI까지 맡기려면 개발 방식 자체가 바뀝니다. 이제 중요한 건 "코드를 얼마나 잘 짜느냐"보다 "에이전트가 잘 일할 환경을 얼마나 잘 설계하느냐"입니다. 핵심은 간단합니다. 에이전트가 읽을 수 있는 지식은 저장소 안에 넣고, 아키텍처 규칙은 문서가 아니라 도구로 강제하며, 코드베이스의 어질러짐은 자동 정리 루프로 회수하는 것입니다.1
AI 에이전트 개발, 사람의 역할은 무엇이 달라질까
예전엔 개발자가 직접 손으로 코드를 쌓아 올렸다면, 에이전트 우선 개발에서는 사람이 무대를 세팅합니다. 조금 과장하면 개발자는 요리사가 아니라 주방 설계자가 됩니다. 레시피, 동선, 위생 규칙, 검수 기준을 잡아두면 로봇 셰프가 계속 같은 품질로 요리를 내는 방식이죠.
이 관점이 중요한 이유는 문제가 생겼을 때 "누가 이 파일을 망쳤지?"가 아니라 "왜 시스템이 이런 결과를 허용했지?"로 질문이 바뀌기 때문입니다. 결국 생산성의 차이는 모델 성능보다 저장소 구조, 문서 체계, 테스트 루프, 관측 가능성에서 벌어집니다.1
AGENTS.md와 문서 전략, 길게 쓰면 오히려 독이 된다
많은 팀이 AI용 규칙 파일을 길게 써야 한다고 생각합니다. 그런데 최근 분석에서는 사람이 직접 쓴 최소한의 컨텍스트는 약간의 도움을 줄 수 있지만, 불필요하게 많은 지침은 성공률을 떨어뜨리고 비용을 키울 수 있다고 봤습니다. 특히 자동 생성된 컨텍스트 파일은 평균 성공률을 3% 낮추고, 추론 비용은 20% 넘게 늘린 사례도 보고됐습니다.2
그래서 좋은 AGENTS.md는 두꺼운 매뉴얼이 아니라 표지판에 가깝습니다. 프로젝트 목적, 꼭 필요한 실행 명령, 사람에게 물어봐야 하는 경계 정도만 짧게 담는 편이 낫습니다.3 스타일 규칙이나 import 제한처럼 기계가 검사할 수 있는 내용은 문서에 반복해서 적지 말고 린터와 설정 파일로 보내야 합니다. 한마디로, 설명보다 실행 가능한 규칙이 더 강합니다.
아키텍처는 문서가 아니라 린터와 테스트로 지켜야 한다
"이 레이어는 저 레이어를 참조하면 안 됩니다"라는 문장을 README에 써두는 것만으로는 부족합니다. 에이전트는 바쁘고, 문서는 쉽게 낡습니다. 대신 구조 테스트, 맞춤형 린터, CI 체크로 경계를 고정해야 합니다.
실제로 현대 린터는 단순한 스타일 검사기를 넘어, 위험한 패턴과 의존성까지 잡아내는 정적 분석 도구로 발전했습니다.4 TypeScript 계열에선 아키텍처 규칙을 바로 스캔하는 도구도 있고5, Go 생태계에서도 import 제한이나 복잡도 관리 같은 규칙을 세밀하게 강제할 수 있습니다.6 중요한 건 에이전트에게 "이렇게 해줘"라고 부탁하는 게 아니라, "이 규칙을 어기면 통과하지 못한다"는 환경을 만드는 일입니다.
QA 병목 없는 AI 코딩 환경 만드는 법
에이전트가 많은 변경을 빠르게 만들기 시작하면 가장 먼저 막히는 곳은 사람 QA입니다. 그래서 앱을 에이전트가 직접 읽고 조작할 수 있게 만들어야 합니다. 격리된 미리보기 환경, 브라우저 자동화, 스크린샷과 DOM 스냅샷, 로그·메트릭·트레이스 접근이 중요한 이유입니다.1
피드백 속도도 정말 중요합니다. 빠른 타입 체크와 린팅, 즉시 실패하는 검증 루프는 사람뿐 아니라 AI에게도 큰 차이를 만듭니다.7 에이전트는 느린 환경에서 똑똑해지지 않습니다. 그냥 더 많이 헤맬 뿐입니다. 결국 "좋은 AI 코딩"은 좋은 프롬프트보다 빠르고 엄격한 피드백 시스템에서 나옵니다.
시사점
AI 에이전트 시대의 개발은 코딩 자동화가 아니라 개발 시스템 재설계에 가깝습니다. 먼저 에이전트가 볼 수 있는 정보부터 저장소 안으로 끌어오세요. 다음으로 문서로 설득하지 말고 린터, 테스트, CI로 강제하세요. 마지막으로 품질 저하와 기술 부채는 사람이 주말에 한 번 치우는 일이 아니라, 자동 정리 작업이 매일 조금씩 갚도록 만들어야 합니다.
앞으로 경쟁력은 "누가 더 잘 코딩하나"보다 "누가 더 잘 작동하는 에이전트 작업장을 만들었나"에서 갈릴 가능성이 큽니다.
참고
1하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기 | OpenAI
2New Research Reassesses the Value of AGENTS.md Files for AI Coding
3AGENTS.md Specification: A Research-Backed Guide
5Architecture Linter - Visual Studio Marketplace
7Fastest Frontend Tooling for Humans & AI | Christoph Nakazawa
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.