더 나은 프롬프트 없이 AI 코딩 에이전트(AI Coding Agents)를 위한 코드베이스를 만드는 방법

에이전트가 유효한 코드를 작성했습니다. 하지만 여전히 핵심을 놓쳤습니다.

잘못된 패키지 매니저(Package manager). 파이프라인에서 절대 사용하지 않는 플래그로 실행되는 테스트. 모델이 세 폴더 떨어진 곳에서 유사한 파일을 발견했다는 이유로 비즈니스 로직(Business logic)이 라우트 핸들러(Route handler)에 배치되었습니다. 더 많은 컨텍스트(Context)를 붙여넣고, 프롬프트(Prompt)를 다듬고, 다시 실행했습니다. 다음 작업에서도 똑같은 실패가 발생했습니다.

이것은 모델의 문제가 아닙니다. 리포지토리(Repo)의 문제입니다.

2026년 초에 쏟아진 일련의 게시물들(Medeiros, Fabisevich, Marmelab, Sourcegraph, Vstorm 등)은 동일한 아이디어로 수렴했습니다: 에이전트의 생산성은 아키텍처(Architectural)에 달려 있다. 도구도 중요합니다. 하지만 구조와 피드백 루프(Feedback loops)가 더 중요합니다.

이 포스트는 실질적인 정수만을 담았습니다. 특정 도구를 숭배하지 않습니다. Copilot, Claude Code, Cursor, Codex 또는 다음 달에 당신이 무엇을 사용하든, 매 세션마다 프로젝트를 다시 설명할 필요 없이 결과물을 내놓을 수 있도록 리포지토리에 무엇을 추가해야 하는지에 대해 다룹니다.

프롬프트가 작동하지 않는 이유

인간은 암묵적 지식(Tribal knowledge)을 흡수합니다. 절반만 문서화된 설정 스크립트, "인증(Auth)에 대해서는 Priya에게 물어봐" 같은 것들 말이죠. 에이전트는 Priya에게 물어보지 않습니다. 그들은 트리(Tree)에 있는 내용과 grep할 수 있는 내용을 바탕으로 패턴 매칭(Pattern-match)을 수행합니다.

Hélio Medeiros는 리포지토리를 하나의 인터페이스(Interface)로 정의합니다. InfoWorld의 "Coding for agents"는 한 걸음 더 나아갑니다: 컨텍스트(Context)는 인프라(Infrastructure)입니다. 작업자가 에이전트일 때, 테스트 명령, 경계(Boundaries), 그리고 "건드리지 마시오" 경로 등은 작업이 실행되는 방식의 일부가 됩니다.

리트머스 시험지 (모델을 탓하기 전에 이것을 사용해 보세요):

1. 채팅 기록을 삭제합니다.
2. 동일한 브랜치(Branch)에서 새로운 에이전트 세션을 엽니다.
3. 하나의 실제 작업을 부여합니다: "결제 API에 필드를 추가해줘" 또는 "모듈 X의 실패하는 테스트를 수정해줘."
4. 아키텍처 에세이를 붙여넣지 마세요.

만약 에이전트가 커밋된 파일(Committed files)만 사용하여 작업을 완료할 수 없다면, 당신이 여전히 부담을 짊어지고 있는 것입니다. 에이전트는 타이핑을 하고 있을 뿐입니다.

그 테스트는 10분이 소요됩니다. 하지만 그 테스트는 당신이 다음에 어디에 투자해야 할지를 정확히 알려줍니다.

레포지토리가 지침을 포함하고 있을 때 얻는 것들

에이전트(Agents)를 위해 사후에 구조를 조정(retrofit)한 팀들은 다음과 같은 동일한 성과를 보고하고 있습니다:

• 잘못된 명령(설치, 테스트, 린트(lint), 마이그레이션)의 감소.
• 생성된 파일, 락파일(lockfiles) 또는 비밀값(secrets)에 대한 수정 횟수 감소.
• 팀이 실제로 코드를 계층화하는 방식과 일치하는 더 작은 디프(diffs).
• 매 스레드마다 "우리는 pnpm을 사용합니다" 또는 "마이그레이션은 생성됩니다"라고 다시 타이핑하는 시간 감소.

Vstorm의 가이드와 AGENTS.md에 관한 커뮤니티 글에 따르면, 첫 버전을 설정하는 데 걸리는 시간은 대략 15분 정도입니다. 그 보상은 당신이 직접 수행할 필요가 없어진 첫 번째 주간의 리뷰 루프(review loops)에서 나타납니다.

당신은 로봇을 위해 구축하는 것이 아닙니다. 숙련된 시니어 엔지니어가 첫날에 필요로 할 내용을 기록하는 것입니다. 에이전트는 온보딩(onboarding)에 참여할 수 없기 때문에 이 문제를 강제할 뿐입니다.

1단계: 레포지토리 루트에 AGENTS.md 추가하기

1년 전에는 모든 도구가 자신만의 규칙 파일을 원했습니다. .cursorrules, CLAUDE.md, .github/copilot-instructions.md, 도구별 Gemini 설정 등 말이죠. 동일한 관례가 네 번씩 복사되었고, 몇 주 안에 서로 어긋나기 시작했습니다.

**AGENTS.md**는 살아남은 관례입니다. 여러 에이전트가 읽을 수 있는 루트의 마크다운(Markdown) 파일 하나입니다. 일반 텍스트이며, JSON 스키마(JSON schema)를 사용하지 않습니다. Copilot, Codex, Claude Code, Cursor 및 기타 도구 전반에서 작동합니다 (DEV의 이 크로스 플랫폼 테스트를 참조하세요).

원한다면 도구별 추가 사항을 유지해도 됩니다 (예: Claude 전용 워크플로우를 위한 CLAUDE.md). 하지만 AGENTS.md는 독립적으로 존재해야 합니다. 에이전트가 파일 하나만 읽더라도, 이곳에서 어떻게 작업해야 하는지 여전히 알아야 합니다.

여기에 담아야 할 내용 (가장 영향력이 큰 것부터)

이 스켈레톤(skeleton)을 복사하여 빈칸을 채우세요:

# AGENTS.md

## Project overview
...

가장 큰 피해를 방지하는 섹션들:

섹션	방지하는 문제
Commands	pip vs uv, npm vs pnpm, 잘못된 테스트 러너 (test runner)
...

README 전체를 붙여넣지 마세요. OpenAI의 harness engineering notes (2026년에 널리 요약됨)에 따르면, 하나의 거대한 에이전트 매뉴얼은 금방 구식이 됩니다. AGENTS.md를 백과사전이 아닌 지도(map)로 사용하세요.

2단계: 에이전트에게 더 넓은 지도가 필요한 경우 llms.txt 추가하기

Joe Fabisevich의 Recap 2.0 글은 전체 저장소(repo)를 컨텍스트(context)에 쏟아붓지 않고도 에이전트가 올바른 문서로 향할 수 있게 안내하는 작은 llms.txt를 설명합니다.

규칙이 아닌 포인터(pointers) 용도로 사용하세요:

# llms.txt
/docs/architecture.md
/docs/api.md
...

운영 규칙은 AGENTS.md에 넣으세요. "다음에 어디를 봐야 하는지"는 llms.txt 또는 웹 프로젝트의 경우 public/llms.txt에 넣으세요.

3단계: 명령어를 위한 단일 골든 패스(golden path) 구축 (및 CI와 일치시키기)

Medeiros는 Make로 감싸진 안정적인 엔트리포인트(entrypoints)를 권장합니다:

make bootstrap
make test
make lint
...

구현 방식은 npm scripts, pnpm, mise 또는 Taskfile가 될 수 있습니다. 에이전트는 래퍼(wrapper)가 무엇인지 상관하지 않습니다. 에이전트가 중요하게 여기는 것은 클린 클론(clean clone) 상태에서 항상 작동하는 하나의 문자열이며, CI에서도 동일한 문자열이 실행된다는 점입니다.

나쁜 상태: 로컬은 npm test, CI는 pnpm test --filter=api. 에이전트는 터미널에서 방금 실행된 것에 맞춰 최적화합니다. 결과적으로 로컬에서는 통과(green)하지만 파이프라인에서는 실패(red)하는 머지를 하게 됩니다.

좋은 상태:

"scripts": {
  "test": "vitest run",
  "lint": "eslint ."
...

...그리고 워크플로우(workflow) 파일이 다른 주문(incantation)이 아닌 pnpm test와 pnpm lint를 호출하는 상태입니다.

검증이 느리거나 불안정(flaky)해지면, 에이전트는 단순한 디프(diff) 머신이 되고 당신은 테스트 러너가 됩니다. 순수 도메인 코드(pure domain code)에 대한 빠른 단위 테스트(unit tests)는 프론티어 모델(frontier model)로 교체하는 것보다 피드백 루프를 더 효과적으로 단축시킵니다.

4단계: 변경 사항이 허용되는 범위를 축소하기

모든 사이드 프로젝트에 육각형 아키텍처 (hexagonal architecture)가 필요한 것은 아닙니다. 하지만 **명확한 경계 (obvious boundaries)**는 반드시 필요합니다.

Medeiros와 동료들은 포트 및 어댑터 (ports-and-adapters) 스타일의 레이아웃을 권장하는데, 이는 위반 사항을 가시화해주기 때문입니다. 예를 들어, 도메인 코드 (domain code)가 데이터베이스 드라이버 (database driver)를 임포트할 수 없도록 설정하면, 에이전트 (agent)가 지름길을 택했을 때 빌드가 실패하게 됩니다.

어떤 스택에서도 적용 가능한 전이 가능한 패턴 (Transferable pattern)은 다음과 같습니다:

• 비즈니스 규칙 (business rules)을 한 곳에 모으기 (domain, core/, lib/domain/ 등).
• 프레임워크 결합 코드 (framework glue)를 얇게 유지하기 (핸들러 (handlers), UI 라우트 (routes), CLI).
• 의존성 (dependencies)을 가장자리에서 연결하기 (main, app/, composition root).

기능 중심 폴더 구조 (feature-folder)를 사용하는 Next.js 앱의 경우, 이는 다음과 같은 의미일 수 있습니다: 라우트는 app/에, 제품 로직은 features/*/에 위치시키고, 공유 MDX 경로는 AGENTS.md에 문서화하여 "블로그 포스트 추가"라는 요청이 같은 날 data/blog/와 features/blog/data/posts/를 동시에 생성하는 일을 방지하는 것입니다.

에이전트가 자주 혼동하는 폴더(src/billing/, packages/api/ 등)에는 한 단락짜리 README를 추가하세요. 에이전트는 디렉터리 목록을 나열할 때 폴더 내의 README를 자주 읽습니다.

5단계: 에이전트의 실수를 리포지토리 티켓으로 취급하기

Marmelab의 에이전트 경험 포스트는 내용이 깁니다. 여기서 가져올 만한 가치가 있는 습관은 간단합니다:

에이전트가 어리석은 행동을 할 때마다, 리포지토리 (repository) 차원에서 이를 방지할 수 없었는지 자문해 보세요.

에이전트의 실수	리포지토리 수정 사항
잘못된 테스트 명령	AGENTS.md의 Commands 섹션에 추가
...

도구 (Tooling)와 MCP 서버는 이 순서에서 가장 마지막입니다. 대부분의 팀은 플러그인 (plugins)이 부족해서가 아니라, 컨텍스트 (context)가 부족해서 여전히 실패하고 있습니다.

80% 문제 (그리고 당신의 규모에서 해야 할 일)

Sourcegraph의 에이전틱 코딩 가이드 (agentic coding guide)는 팀들이 인지하고 있는 한 가지 패턴을 언급합니다. 바로 에이전트가 눈에 보이는 80%를 완료한다는 점입니다. 에이전트가 건드린 파일 내에서는 테스트가 통과합니다. 하지만 며칠 뒤, 미들웨어 (middleware), DTO, 감사 로그 (audit logs), 또는 형제 서비스 (sibling service)가 여전히 이전의 계약 (contract)을 기대하고 있기 때문에 CI가 다른 곳에서 실패하게 됩니다.

이것은 에이전트의 어리석음이 아니라, 불완전한 컨텍스트 (incomplete context)의 문제입니다.

단일 앱의 경우, 영향 범위 (blast radius)가 더 작습니다. 하지만 작업을 완료했다고 호출하기 전에 여전히 다음 과정을 실행하십시오: 에이전트가 이름을 변경하거나 내보낸 (exported) 모든 심볼(symbol)에 대해 grep을 실행하십시오. 에이전트가 건드리지 않은 파일들도 열어보십시오. 만약 무언가가 이전 형태 (old shape)에 의존하고 있다면, 그 작업은 완료된 것이 아닙니다.

대규모 또는 멀티 레포 (multi-repo) 코드베이스의 경우, 머지 (merge) 전에 결정론적인 교차 레포 검색 (deterministic cross-repo search)과 명시적인 스코핑 (explicit scoping)이 필요합니다. 해결책은 규모가 커지지만, 진단 방법은 동일합니다.

30분 개조 체크리스트

에이전트를 가장 많이 사용하는 레포지토리에서 다음을 수행하십시오:

1. 위의 골격을 사용하여 AGENTS.md를 작성합니다 (15분).
2. 로컬 테스트/린트 (test/lint)를 CI와 일치시킵니다 (하나의 스크립트 이름으로 양쪽 모두 적용).
3. 에이전트가 계속 잘못 찾아가는 폴더에 README를 추가합니다 (필요한 곳에만, 각각 5분씩).
4. 새로운 세션과 하나의 실제 작업으로 리트머스 시험 (litmus test)을 실행합니다.
5. 작업이 끝난 후, 에이전트에게 채팅으로 알려주어야 했던 내용이 있다면 AGENTS.md에 한 줄을 추가합니다.

이 패턴을 배우는 중이라면 작은 프로젝트부터 시작하십시오. Fabisevich의 조언은 범위가 제한된 무언가에서 연습한 다음, 그 습관을 대규모 코드베이스로 이식하라는 것입니다.

에이전트 친화적인 레포지토리에 대해 읽는 것만으로는 파일이 git에 올라가기 전까지 아무런 효과가 없습니다. 리트머스 시험이 곧 점수판입니다.

추가 읽을거리

이 포스트의 주요 출처:

추가 읽을거리

이 포스트의 주요 출처:

• Agent 친화적인 코드베이스를 위한 시간 (Hélio Medeiros) 및 블로그 동반자
• Agent 친화적인 코드베이스를 위한 작은 단계들 (Joe Fabisevich)
• AGENTS.md: AI 에이전트 친화적 코드베이스 가이드 (Vstorm OSS)
• 에이전트 경험: 모범 사례 (Marmelab)
• 에이전트를 위한 코딩 (InfoWorld)
• 2026년 에이전트적 코딩: 대규모 코드에 대한 실용 가이드 (Sourcegraph)
• What is AGENTS.md? (Cobus Greyling)
• 세 가지 플랫폼에 걸친 AGENTS.md 테스트 (DEV Community)