Agents.md로 AI 코딩 도구에게 팀 컨벤션 알려주기

2026. 5. 28. 10:37ㆍ카테고리 없음

반응형

AI 코딩 도구를 쓰다 보면 처음에는 꽤 놀랍습니다. 요구사항을 말하면 컴포넌트도 만들고, 테스트도 작성하고, 리팩터링 방향도 제안합니다. 그런데 실무 프로젝트에 조금만 깊게 들어가면 곧 이런 문제가 생깁니다.

  • 우리 팀의 폴더 구조를 자꾸 무시한다.
  • 테스트 실행 방법을 매번 다시 알려줘야 한다.
  • 사용하지 않는 라이브러리나 패턴을 제안한다.
  • 작은 수정인데도 너무 넓은 범위를 바꾼다.
  • PR에서 리뷰어가 싫어하는 스타일을 반복한다.

이 문제는 AI 성능만의 문제가 아닙니다. AI에게 프로젝트의 기준과 맥락을 전달하는 방식이 아직 정리되지 않았기 때문에 생기는 문제에 가깝습니다. 최근 글에서 다룬 Spec-Driven Development가 “무엇을 만들지”를 명확히 하는 접근이라면, Agents.md는 “이 프로젝트에서는 어떻게 일해야 하는지”를 AI에게 알려주는 프로젝트 설명서라고 볼 수 있습니다.

Agents.md가 필요한 이유

개발자는 프로젝트에 들어오면 README, package.json, 폴더 구조, 기존 코드, PR 기록을 보면서 암묵적인 규칙을 익힙니다. 하지만 AI 코딩 도구는 매번 제한된 컨텍스트 안에서 작업합니다. 저장소 전체를 읽을 수 있다고 해도 어떤 정보가 중요한지 스스로 완벽히 판단하지는 못합니다.

그래서 AI에게는 짧고 명확한 작업 가이드가 필요합니다.

Agents.md에는 보통 다음과 같은 내용을 담습니다.

  • 프로젝트의 목적과 기술 스택
  • 자주 사용하는 명령어
  • 폴더별 역할
  • 코드 스타일과 네이밍 규칙
  • 테스트 작성 기준
  • 수정하면 안 되는 영역
  • PR 전에 확인해야 할 체크리스트

중요한 점은 문서를 길게 쓰는 것이 아닙니다. AI가 작업 전에 빠르게 읽고 바로 적용할 수 있어야 합니다.

기본 구조 예시

프론트엔드 프로젝트라면 아래 정도의 구조로 시작할 수 있습니다.

# Project Guide for AI Agents

## Tech Stack
- React 19
- TypeScript
- Vite
- TanStack Query
- CSS Modules

## Commands
- install: `pnpm install`
- dev: `pnpm dev`
- test: `pnpm test`
- lint: `pnpm lint`
- typecheck: `pnpm typecheck`

## Folder Rules
- `src/components`: 재사용 가능한 UI 컴포넌트
- `src/features`: 도메인 단위 기능
- `src/hooks`: 공통 훅
- `src/api`: API 클라이언트와 타입

## Coding Rules
- 모든 새 컴포넌트는 TypeScript로 작성한다.
- props 타입은 `ComponentNameProps` 형식으로 둔다.
- API 호출은 컴포넌트에서 직접 하지 않고 hooks 또는 query 레이어를 사용한다.
- any 사용은 피하고, 필요한 경우 이유를 주석으로 남긴다.

## Before Finishing
- lint, typecheck, test를 실행한다.
- 변경 범위 밖의 파일은 수정하지 않는다.
- 스냅샷 변경이 필요한 경우 이유를 설명한다.

이 정도만 있어도 AI의 작업 품질이 달라집니다. 특히 “명령어”와 “수정하면 안 되는 범위”는 반복 작업에서 큰 차이를 만듭니다.

팀 컨벤션은 구체적으로 적기

AI에게 “깔끔하게 작성해줘”라고 하면 사람마다 다른 결과가 나옵니다. 대신 팀에서 실제로 리뷰하는 기준을 문장으로 적는 것이 좋습니다.

예를 들어 다음처럼 작성할 수 있습니다.

  • 상태가 3개 이상이면 boolean 여러 개보다 union type을 우선한다.
  • 컴포넌트 내부에서 날짜 포맷을 직접 만들지 말고 formatDate 유틸을 사용한다.
  • 서버 응답 타입은 src/api/types에 둔다.
  • 화면에 직접 노출되는 문자열은 추후 i18n을 고려해 상수로 분리한다.
  • loading, error, empty 상태를 모두 고려한다.

이런 규칙은 사람에게는 사소해 보여도 AI에게는 매우 중요한 힌트가 됩니다. AI는 “우리 팀이 당연하게 여기는 것”을 모릅니다. 당연한 것을 적어두는 것이 오히려 핵심입니다.

Spec-Driven Development와 함께 쓰기

Agents.md는 프로젝트 공통 규칙이고, 스펙 문서는 특정 작업의 요구사항입니다. 둘을 함께 쓰면 AI에게 전달되는 정보가 훨씬 선명해집니다.

예를 들어 “알림 설정 화면을 만들어줘”라고만 지시하는 대신 다음처럼 작업을 나눌 수 있습니다.

  1. Agents.md를 읽고 프로젝트 규칙을 확인한다.
  2. 알림 설정 화면의 요구사항을 별도 스펙으로 작성한다.
  3. 스펙에 사용자 시나리오, 예외 상황, API 계약, 테스트 기준을 포함한다.
  4. 구현 전 AI에게 누락된 요구사항을 질문하게 한다.
  5. 구현 후 Agents.md의 체크리스트 기준으로 검증한다.

이 방식은 Vibe Coding의 빠른 장점은 유지하면서도, 결과물이 프로젝트 규칙에서 벗어나는 문제를 줄여줍니다.

너무 많은 규칙은 오히려 방해가 된다

주의할 점도 있습니다. Agents.md를 팀 위키처럼 너무 길게 만들면 AI가 핵심을 놓칠 수 있습니다. 처음부터 완벽한 문서를 만들기보다, 자주 반복되는 실수부터 짧게 적는 편이 좋습니다.

추천하는 운영 방식은 다음과 같습니다.

  • 처음에는 50~100줄 정도로 시작한다.
  • AI가 반복해서 틀리는 내용을 발견하면 한 줄 추가한다.
  • 오래된 명령어나 사용하지 않는 패턴은 바로 제거한다.
  • 프로젝트 루트에 두고 README에서 링크한다.
  • 큰 저장소라면 하위 폴더별 Agents.md를 추가한다.

문서는 살아 있어야 합니다. 한 번 만들고 방치하면 오히려 잘못된 지시가 됩니다.

실무 체크리스트

AI 코딩 도구를 팀에서 사용하고 있다면 아래 항목부터 확인해보면 좋습니다.

  • 프로젝트 루트에 AI용 작업 가이드가 있는가?
  • 설치, 실행, 테스트, 린트 명령어가 최신인가?
  • 폴더 구조와 책임이 설명되어 있는가?
  • 팀에서 금지하는 패턴이 명확히 적혀 있는가?
  • PR 전 확인해야 할 기준이 있는가?
  • AI가 반복해서 실수한 내용이 문서에 반영되는가?
  • 문서가 너무 길어져 핵심이 흐려지지는 않았는가?

마무리

AI 코딩 도구를 잘 쓰는 핵심은 더 멋진 프롬프트를 외우는 것이 아니라, 프로젝트의 맥락을 AI가 이해할 수 있는 형태로 정리하는 것입니다. Agents.md는 그 출발점이 될 수 있습니다.

처음부터 완벽할 필요는 없습니다. 오늘 당장 프로젝트에서 자주 쓰는 명령어, 폴더 구조, 리뷰 기준만 정리해도 충분합니다. 그리고 AI가 실수할 때마다 문서를 조금씩 업데이트해 보세요. 팀의 암묵지가 문서화될수록 AI는 단순한 코드 생성기를 넘어 프로젝트에 맞춰 일하는 동료에 가까워집니다.

반응형
저작자표시 (새창열림)

티스토리툴바