AI튜터랩 로고AI튜터랩
블로그 목록
바이브코딩

상위 1%는 프롬프트보다 AGENTS.md를 먼저 쓴다

•읽는 시간 4분•조회 17

바이브코딩을 시작하면 처음 며칠은 놀랍습니다. 한 문장만 입력해도 화면이 생기고, 버튼이 움직이고, 배포까지 됩니다. 그런데 프로젝트가 커지는 순간 문제가 생깁니다. 어제는 잘 지켰던 폴더 구조를 오늘은 무시하고, 같은 기능을 다른 방식으로 다시 만들며, 수정 하나가 엉뚱한 화면을 망가뜨립니다.

이때 많은 사람이 더 긴 프롬프트를 씁니다. 하지만 상위 1%의 바이브코딩은 프롬프트를 길게 쓰는 기술이 아니라 AI가 매번 같은 기준으로 일하게 만드는 시스템에 가깝습니다. 그 출발점이 AGENTS.md입니다.

왜 채팅 프롬프트만으로는 부족할까

채팅 프롬프트는 일회성 지시입니다. 반면 프로젝트에는 계속 유지되어야 하는 규칙이 있습니다.

  • 어떤 패키지 매니저를 쓰는가
  • 컴포넌트는 어디에 두는가
  • 수정 후 어떤 테스트를 실행하는가
  • 기존 디자인 시스템에서 무엇을 재사용하는가
  • 절대로 건드리면 안 되는 파일은 무엇인가

이 규칙이 대화에만 있으면 새 세션이 시작될 때마다 다시 설명해야 합니다. AGENTS.md는 이런 저장소 수준의 작업 지침을 코드와 함께 보관합니다. OpenAI의 Codex 가이드도 AGENTS.md를 활용해 에이전트가 작업 전 프로젝트 지침을 읽도록 안내합니다.

좋은 바이브코딩은 AI에게 자유를 많이 주는 것이 아니라, 자유롭게 움직여도 되는 경계를 선명하게 만드는 일입니다.

최소 AGENTS.md 구조

처음부터 거대한 규칙집을 만들 필요는 없습니다. 아래 다섯 항목이면 충분합니다.

markdown
# 프로젝트 목표
소상공인이 3분 안에 예약 페이지를 만드는 서비스

# 기술 스택
- Next.js App Router
- TypeScript strict mode
- Tailwind CSS

# 작업 규칙
- 새 컴포넌트보다 기존 컴포넌트 재사용 우선
- 데이터 변경 전 관련 타입과 호출부 확인
- 요청 범위 밖의 리팩터링 금지

# 검증
- npm run lint
- npm run test
- 주요 화면 모바일 390px 확인

# 완료 보고
- 변경 파일
- 검증 결과
- 남은 위험

핵심은 명령을 많이 넣는 것이 아니라 결과를 판단할 기준을 넣는 것입니다. “예쁘게 만들어줘”보다 “모바일 390px에서 주요 버튼이 첫 화면에 보여야 한다”가 훨씬 강합니다.

상위 1%의 4단계 작업 루프

다이어그램을 그리는 중입니다.

1. 결과를 먼저 정의한다

“로그인 페이지 만들어줘” 대신 “이메일 로그인, 오류 메시지, 모바일 대응, 성공 시 대시보드 이동까지 완료해줘”라고 씁니다. 기술보다 사용자가 보게 될 완료 상태를 먼저 적습니다.

2. 바로 코딩시키지 않는다

수정할 파일, 재사용할 요소, 위험한 변경을 먼저 요약하게 합니다. 계획이 틀렸다면 코드가 생기기 전에 고칠 수 있습니다.

3. 한 번에 하나의 검증 단위만 맡긴다

인증, 결제, 관리자 화면을 한 프롬프트에 넣지 마세요. “구현하고 확인할 수 있는 한 덩어리”로 쪼개야 실패 원인을 찾기 쉽습니다.

4. 완료의 증거를 요구한다

테스트 명령, 브라우저 확인 항목, 남은 예외를 보고하게 하세요. “완료했습니다”가 아니라 무엇으로 완료를 확인했는지가 중요합니다.

자주 하는 실수

첫째, AGENTS.md에 취향을 너무 많이 적는 것입니다. 규칙이 길수록 중요한 지침이 묻힐 수 있습니다. 실제로 반복해서 틀리는 것만 추가하세요.

둘째, 테스트 규칙 없이 구현 규칙만 적는 것입니다. AI는 빠르게 만들 수 있지만, 검증 기준이 없으면 빠르게 틀릴 수도 있습니다.

셋째, 프로젝트가 바뀌었는데 규칙은 그대로 두는 것입니다. 사용하지 않는 명령과 오래된 폴더 구조는 오히려 혼란을 만듭니다.

핵심 정리

  • 바이브코딩의 품질 차이는 프롬프트 재주보다 지속되는 프로젝트 문맥에서 벌어집니다.
  • AGENTS.md에는 기술 스택, 작업 경계, 검증 명령, 완료 보고 형식을 넣습니다.
  • 요구사항 → 계획 → 작은 구현 → 검증 → 기록의 루프를 반복합니다.
  • 규칙은 짧고 측정 가능하게 유지합니다.

실습: 내 프로젝트의 첫 AGENTS.md 만들기

  1. 현재 프로젝트에서 AI가 반복해서 틀리는 행동 3개를 적습니다.
  2. 각 행동을 “해야 한다/하지 않는다” 형태의 규칙으로 바꿉니다.
  3. 프로젝트에서 실행 가능한 검증 명령 2개를 추가합니다.
  4. 작은 수정 하나를 요청하고, AI가 규칙을 지키는지 확인합니다.
  5. 도움이 되지 않은 규칙은 지우고 필요한 규칙만 남깁니다.

참고 자료