파일이 다섯 개인 레포는 사실 아무것도 없는 것과 같다
CLAUDE.md, GEMINI.md, .cursorrules—익숙한 파일들이다. 문제는 이 파일들이 전부 '비슷한 말'을 하고 있다는 것이다. pnpm test 먼저 돌려라, src/generated/ 건드리지 마라, 컴포넌트는 테스트 파일과 같은 폴더에 두어라. 내용은 거의 같은데 파일은 세 개다. 그리고 어느 날 하나를 업데이트하면 나머지 둘은 조용히 낡아간다.
오늘 팀원이 Cursor로 작업하다가 에이전트가 지난 스프린트의 DB 마이그레이션 패턴을 그대로 따르는 것을 발견했다면, 그건 에이전트 문제가 아니다. .cursorrules를 업데이트하지 않은 사람의 문제다.
AGENTS.md: 에이전트를 위한 README
dev.to에 소개된 AGENTS.md 스펙은 이 문제를 정면으로 해결한다. OpenAI Codex, Google Jules, Cursor, Amp, Factory 등 주요 에이전트 생태계가 공동으로 설계에 참여한 오픈 포맷으로, 사실상 '에이전트를 위한 README'다. 지금 이미 Aider, goose, Zed, Warp, VS Code Copilot, Devin까지 지원 목록에 올라 있다.
핵심 아이디어는 단순하다. 빌드 커맨드, 테스트 실행 방법, 아키텍처 컨벤션처럼 에이전트가 알아야 하는 것들은 AGENTS.md 하나에 모은다. 인간을 위한 온보딩 스토리, 프로젝트 히스토리, 처음 개발 환경 설정하는 법—이건 README에 남긴다. 에이전트는 당신의 origin story가 필요 없다.
Claude Code는 아직 CLAUDE.md를 기본으로 읽지만(AGENTS.md 지원은 진행 중), 이미 실용적인 브릿지 패턴이 있다. AGENTS.md를 단일 진실의 원천으로 두고, CLAUDE.md는 그걸 참조한 뒤 Claude 전용 설정(Extended Thinking 사용 기준, MCP 도구 우선순위 등)만 추가하는 방식이다. 컨벤션이 바뀌면 고쳐야 할 파일은 하나다.
컨텍스트 파일은 '설계'다, 메모가 아니다
AGENTS.md를 잘 쓰려면 무엇을 넣고 무엇을 빼야 하는지 판단하는 감각이 필요하다. 스펙이 권장하는 내용은 명확하다: 빌드·테스트 커맨드, 컴포넌트 배치 규칙, 건드리면 안 되는 파일 경로, 아키텍처 상의 책임 경계(인증 로직은 middleware.ts에만, DB 접근은 lib/db.ts를 통해서만). 반대로 넣지 말아야 할 것도 있다. 특정 스프린트나 날짜를 언급하는 내용, 테스트 실행 결과 샘플—이런 건 금방 낡아서 에이전트를 혼란스럽게 만든다.
좋은 AGENTS.md는 '지금 이 코드베이스의 상태'를 담는다. 작성 당시 당신이 하고 있던 작업을 담는 게 아니라.
매일 쓰는 Claude 프롬프트, 패턴이 전부다
컨텍스트 파일을 잘 세팅했다면, 다음은 일상 대화의 품질이다. dev.to에 공유된 한 개발자의 6개월 실전 프롬프트 모음은 단순한 팁 모음이 아니다. 거기엔 구조가 있다: 역할 → 구체적 컨텍스트 → 정확한 산출물 → 원하지 않는 것의 명시.
이 구조를 따르지 않으면 아무리 Claude가 좋아도 Stack Overflow 검색과 다를 게 없다. 몇 가지 패턴만 짚어보자.
버그를 찾을 때 단순히 '고쳐줘'가 아니라 '왜 틀렸는지 내가 놓친 멘탈 모델을 알려줘'라고 하면 출력이 달라진다. 코드 리뷰를 요청할 때 예상 트래픽과 스케일을 함께 주고 '악의적인 사용자라면 이 코드로 무엇을 할 수 있는가'를 명시적으로 물으면 보안 관점이 활성화된다. 레거시 코드 분석에는 '유능한 개발자인데 이 코드베이스를 모르는 사람이라고 가정해줘'라는 한 줄이 설명의 밀도를 완전히 바꾼다.
그리고 가장 레버리지가 높은 습관 하나: 세션 시작 시 스택, 프로젝트 목표, 선호 스타일을 15초 안에 붙여넣는 컨텍스트 템플릿. Claude는 이전 대화를 기억하지 못한다. 매 세션마다 제로에서 시작하게 두면, 뛰어난 모델도 평범한 조수가 된다.
에이전트가 DB를 직접 프로비저닝하는 시대
세팅 레이어는 파일과 프롬프트에서 끝나지 않는다. 이번 주 dev.to의 DevSignal 뉴스레터가 포착한 흐름이 그 다음을 보여준다: Neon의 MCP 통합이 Codex와 Cursor 양쪽에 동시 출시됐다.
이게 의미하는 건 단순하다. 에이전트가 마이그레이션 SQL을 '써주는' 것에서 끝나지 않고, 이제 Neon API를 직접 호출해서 DB 브랜치를 만들고 마이그레이션을 실행하고 결과를 확인하는 전체 루프를 IDE 안에서 닫는다. Prisma Compute는 한 발 더 나아가 앱 호스팅과 DB 인프라를 같은 플랫폼에 묶어서, 에이전트가 배포-테스트-수정-재배포 사이클을 플랫폼 이탈 없이 돌린다.
개발자의 역할이 바뀐다. 코드를 타이핑하던 손이 이제 인프라 워크플로우를 설계하는 손이 된다.
설정의 품질이 에이전트의 품질을 결정한다
세 가지 흐름—AGENTS.md 표준화, 구조화된 프롬프트 패턴, MCP 기반 인프라 통합—은 결국 같은 방향을 가리킨다. AI 코딩 도구의 생산성은 모델의 능력치가 아니라 당신이 구성한 컨텍스트 레이어의 품질에서 온다.
단일 AGENTS.md로 다섯 개의 낡은 파일을 대체하는 것, 매 세션에 15초짜리 컨텍스트 템플릿을 붙여넣는 것, MCP로 에이전트의 실행 반경을 인프라까지 확장하는 것—이 모든 것이 '설정'이다. 도구를 잘 쓰는 것과 도구를 제대로 세팅하는 것은 완전히 다른 기술이다. 그리고 지금 이 시점에서, 후자를 먼저 투자하는 사람이 훨씬 앞서 나간다.