코딩 에이전트는 코드를 쓰기보다 코드를 이해해야 한다
사람은 낯선 저장소에 들어가면 먼저 지도를 찾는다. 어디가 앱 코드인지, 어디가 테스트인지, 무엇이 생성 파일인지, 무엇을 건드리면 안 되는지부터 본다. 코딩 에이전트도 똑같다. 문제는 많은 팀이 에이전트에게 코드만 열어 주고 지도는 주지 않는다는 데 있다. 그러고 나서 왜 자꾸 엉뚱한 파일을 고치느냐고 묻는다.
에이전트의 실패는 종종 모델이 약해서가 아니라, 현재 단계에 맞는 컨텍스트가 빠졌기 때문에 생긴다. LangChain도 에이전트 신뢰성의 핵심을 올바른 정보와 도구를 올바른 형식으로 넣는 일로 설명한다.1 코딩 작업에서는 특히 이 차이가 크게 드러난다. 좋은 모델이 있어도 저장소 구조, 실행 규칙, 테스트 피드백이 흐릿하면 결과는 금방 흔들린다.
핵심은 간단하다. 코드를 잘 쓰는 모델보다, 코드를 잘 이해하게 만드는 환경이 더 중요하다.
저장소는 파일 모음이 아니라 작업 현장이다
코딩 에이전트에게 저장소는 단순한 텍스트 더미가 아니다. 일종의 작업 현장이다. 현장에는 배치도가 있고, 안전수칙이 있고, 검사 기준이 있다. 이 셋이 빠지면 에이전트는 눈앞의 파일만 보고 움직인다.
그래서 저장소 구조를 먼저 컨텍스트로 주어야 한다. 예를 들어 웹 서비스 저장소라면 적어도 다음 정도는 빠르게 파악할 수 있어야 한다.
어디가 진입점인가:
apps/web,src/main,server/어디에 도메인 로직이 모여 있는가:
core/,services/,lib/어디가 테스트인가:
tests/,__tests__/,spec/어디가 생성물인가:
generated/,dist/,coverage/어디가 건드리면 위험한 경계인가: 마이그레이션, 인프라, 벤더 코드
이 정보는 거대한 문서 한 편보다 짧은 지도 한 장으로 주는 편이 낫다. 사람도 처음 보는 대형 마트에서 상품 철학 20페이지보다 층별 안내판 하나가 더 반갑다.
단, 저장소 전체 트리를 통째로 넣는 것은 좋은 설계가 아니다. 중요한 디렉터리, 편집 가능 영역, 금지 구역, 자주 연결되는 파일만 요약해야 한다. 그래야 에이전트가 탐색을 덜 헤매고, 필요한 순간에만 더 깊이 읽는다.
규칙 문서는 길수록 좋지 않다
코딩 에이전트 도구들은 저장소 수준의 규칙 파일을 널리 사용한다. Claude Code는 CLAUDE.md를 자동으로 읽고, 루트나 하위 디렉터리 등 여러 위치의 파일을 합쳐 컨텍스트로 끌어올릴 수 있다고 안내한다.2 AGENTS.md는 여러 도구에서 공통으로 쓰는 공개 형식으로, 빌드 명령, 테스트 절차, 스타일 규칙, 금지 사항을 담는 용도로 제안된다.3 모노레포에서는 루트에 공통 규칙을 두고 하위 패키지에 더 가까운 규칙 파일을 두는 방식이 특히 잘 맞는다. AGENTS.md는 가까운 위치의 파일이 더 우선하도록 설계되어 있어, 패키지별 차이를 다루기 좋다.3
여기서 많은 팀이 실수한다. 규칙 문서를 친절함의 이름으로 너무 길게 쓰는 것이다. 최신 연구는 이 습관에 제동을 건다. 저장소 수준의 컨텍스트 파일은 종종 성공률을 떨어뜨리고 추론 비용을 20퍼센트 넘게 올렸으며, 특히 LLM이 자동 생성한 장황한 파일은 도움이 적었다.4 이유는 아이러니하다. 에이전트가 문서를 무시해서가 아니라, 오히려 너무 성실하게 따르기 때문이다. 불필요한 검사, 과한 파일 탐색, 지금 필요 없는 규칙 준수가 늘어나면서 작업이 무거워진다.
좋은 규칙 문서는 많은 것을 설명하는 문서가 아니라, 에이전트가 스스로 추론하기 어려운 것만 적는 문서다. 예를 들면 이런 정보가 값어치가 있다.
일반 상식으로 알 수 없는 실행 명령과 플래그
이 저장소만의 예외적인 스타일 규칙
생성 파일, 레거시 호환 영역처럼 손대면 안 되는 경계
테스트를 통과해도 실패로 봐야 하는 숨은 품질 기준
특정 패키지나 서비스 간의 비표준 의존 관계
반대로 README에 이미 있는 소개 문장, 언어의 기본 관례, 막연한 미사여구는 빼는 편이 낫다.
짧고 강한 규칙 문서는 대체로 이런 느낌이다.
## 자주 쓰는 명령
- 설치: `pnpm install`
- 웹 앱 테스트: `pnpm turbo run test --filter=@acme/web`
- 타입 검사: `pnpm turbo run typecheck --filter=@acme/web`
## 수정 경계
- `src/generated/**`는 수정하지 않는다.
- DB 스키마 변경은 `packages/db` 안에서만 한다.
## 완료 조건
- 바꾼 패키지의 테스트와 타입 검사를 통과한다.
- 사용자 문구를 바꾸면 스냅샷 테스트를 갱신한다.핵심은 설명의 양이 아니라, 오해를 줄이는 밀도다.
설정 파일은 말 없는 교과서다
사람은 package.json, pyproject.toml, tsconfig.json, eslint 설정, pytest.ini, Makefile, Dockerfile, .github/workflows 같은 파일을 보며 저장소의 생활 습관을 읽는다. 코딩 에이전트도 마찬가지다. 이런 파일은 조용하지만 매우 솔직하다. 팀이 실제로 무엇을 빌드하고, 어떤 검사기를 돌리며, 어떤 버전을 전제로 삼는지 숨기지 않는다.
그래서 코딩 환경을 설계할 때는 규칙 문서보다 설정 파일을 우선 진실의 원천으로 취급해야 한다. AGENTS.md가 테스트 명령을 알려 줄 수는 있지만, 실제 CI가 무엇을 돌리는지는 워크플로 파일이 더 정확하다. README가 Python 3.11을 말해도, pyproject.toml이 3.12를 요구하면 에이전트는 후자를 따라야 한다.
실전에서는 다음 순서로 읽게 만드는 편이 좋다.
패키지 매니페스트와 의존성 파일
린트, 포매터, 타입 검사 설정
테스트 러너 설정
CI 워크플로
그다음에야 관련 소스 파일
이 순서가 좋은 이유는 간단하다. 먼저 규칙을 이해한 다음 코드를 읽어야, 에이전트가 보기에는 그럴듯하지만 저장소 기준으로는 틀린 패치를 덜 만든다.
파일 시스템은 코딩 에이전트의 자연어다
최근 코딩 에이전트는 거대한 문맥을 다루는 기본 인터페이스로 파일과 파일 시스템을 많이 사용한다. 긴 대화 이력, 외부 문서, 작업 계획, 중간 산출물을 파일로 남기고 필요할 때 다시 검색하는 방식이 점점 일반화되고 있다.5 이 흐름은 코딩 작업과 잘 맞는다. 저장소 자체가 이미 파일 중심 세계이기 때문이다.
이 점은 아주 실용적인 결론으로 이어진다. 긴 설명을 한 번의 프롬프트에 우겨 넣기보다, 다음 같은 작업 파일을 바깥에 두는 편이 더 낫다.
research.md: 관련 모듈 조사 결과plan.md: 수정 계획과 영향 범위debug.md: 재현 절차와 관찰 내용test-summary.md: 실패 테스트 묶음과 원인 가설
이 파일들은 컨텍스트 윈도우 바깥의 작업 기억이다. 필요할 때 골라 읽을 수 있고, 압축도 쉽고, 사람 검토도 쉽다. 무엇보다 에이전트가 긴 세션 뒤에 기억을 잃어도, 기록은 남는다.
에러 로그는 쓰레기가 아니라 연료다
코딩 에이전트를 써 보면 같은 장면을 자주 본다. 테스트가 실패했고, 터미널에는 수천 줄 로그가 쏟아진다. 사람은 그중 첫 번째 진짜 원인만 골라낸다. 하지만 에이전트에게 로그를 통째로 던지면, 중요한 한 줄이 잡음 속에 묻히기 쉽다.
그래서 에러 로그는 원문과 요약을 분리해야 한다. 원문은 파일로 저장하고, 모델에게는 압축된 진단 카드만 넣는 편이 좋다. 좋은 진단 카드는 보통 다음 정보를 담는다.
어떤 명령이 실패했는가
가장 먼저 터진 원인 에러는 무엇인가
어느 파일, 어느 줄, 어느 테스트 케이스와 연결되는가
재현 가능한가, 간헐적인가
현재 브랜치의 변경분과 어떤 관련이 있는가
운영 관점에서도 로그는 단순 기록이 아니라 재구성 도구여야 한다. 프롬프트, 도구 호출, 상태 스냅샷, 토큰 사용량, 오류 시점이 구조화되어 남아 있으면, 같은 실패를 다시 따라가기 쉬워진다.6 특히 도구 호출은 조용히 실패하는 경우가 많아서 입력 인자, 검증 결과, 출력 요약을 함께 남기는 편이 안전하다.7
한마디로, 로그는 많이 쌓는 것이 아니라 다시 쓸 수 있게 쌓는 것이 중요하다.
테스트 결과는 판정표가 아니라 대화다
테스트를 마지막 관문으로만 생각하면 코딩 에이전트는 자꾸 큰 수정 후에 한꺼번에 무너진다. 더 좋은 방식은 테스트를 작업 중간의 대화 상대로 쓰는 것이다.
예를 들어 버그 수정 루프는 이렇게 설계할 수 있다.
먼저 실패하는 테스트 한두 개로 문제를 고정한다.
관련 파일만 읽고 작은 패치를 만든다.
바뀐 영역에 가까운 테스트를 좁게 돌린다.
통과하면 타입 검사와 린트를 돌린다.
마지막에만 더 넓은 스위트를 확인한다.
이 순서는 비용과 정확도의 균형이 좋다. 모든 수정마다 전체 테스트를 돌리면 안심은 되지만, 속도와 토큰 비용이 크게 늘어난다. 반대로 테스트를 너무 늦게 돌리면 잘못된 방향으로 오래 전진한다. 연구에서 보았듯 규칙 문서는 에이전트가 더 많은 테스트를 돌리게 만들 수 있다.4 문제는 많이 돌리는 것이 아니라, 관련 없는 것까지 무차별로 돌리는 데 있다.
좋은 코딩 에이전트는 테스트를 폭탄 해체처럼 다룬다. 아무 선이나 다 자르지 않고, 먼저 어느 선이 연결되어 있는지 본다.
코딩 에이전트용 컨텍스트 패키지는 이렇게 조립한다
실무에서 가장 효과적인 방법은 작업 시작마다 작은 컨텍스트 패키지를 조립하는 것이다. 한 번에 모든 것을 먹이는 방식이 아니라, 현재 이슈에 필요한 재료만 담아 보내는 도시락이라고 생각하면 쉽다.
도시락 안에는 보통 이런 것들이 들어간다.
작업 목표: 무엇을 고치고 무엇은 건드리지 않는가
저장소 지도: 관련 디렉터리와 핵심 파일
가까운 규칙 문서: 루트 규칙과 하위 디렉터리 규칙
실행 근거: 패키지 설정, 테스트 명령, CI 단서
현재 증상: 에러 로그 요약, 실패 테스트 요약, 재현 절차
최근 변경: 관련 diff나 수정 후보 파일
완료 조건: 어떤 테스트와 어떤 형식 검사를 통과해야 하는가
이렇게 조립하면 에이전트는 처음부터 저장소 전체를 뒤지지 않아도 된다. 반대로 정말 더 넓은 탐색이 필요할 때만 추가 파일을 읽게 만들 수 있다. 이 차이가 성능 차이로 이어진다.
좋은 코딩 에이전트는 똑똑한 타이피스트가 아니다
코딩 에이전트를 단순히 코드를 빠르게 찍어 주는 도구로 보면 자꾸 실망한다. 진짜 강점은 다른 데 있다. 저장소라는 복잡한 환경을 읽고, 규칙을 지키고, 실패 신호를 받아 다시 수정하는 반복을 빠르게 수행하는 데 있다.
그래서 실무에서 먼저 바꿔야 하는 것은 모델 이름이 아니라 작업 환경이다. 저장소 지도를 만들고, 규칙 문서를 줄이고, 설정 파일을 진실의 원천으로 삼고, 로그를 압축하고, 테스트를 피드백 루프로 바꾸면 같은 모델도 훨씬 안정적으로 일한다.
결국 코딩 에이전트 설계는 멋진 한 줄 프롬프트를 찾는 게임이 아니다. 낯선 신입 개발자가 첫날부터 덜 헤매게 만드는 온보딩 설계에 가깝다. 지도, 집안 규칙, 공구함, 검사표를 제대로 쥐여 주면 실력은 그다음부터 비로소 드러난다.
참고
1Context engineering in agents
2Claude Code: Best practices for agentic coding
4Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.