AI 코딩 도구에 컨텍스트 잘 주는 법: 규칙 파일을 운영 문서로 쓰기

규칙 파일은 설명서가 아니라 작업 계약서다

AI 코딩 도구에 긴 README를 통째로 먹이는 방식은 초반에는 편하지만, 프로젝트가 커질수록 답변이 흔들리기 쉽습니다. 중요한 것은 “우리 프로젝트는 무엇인가”보다 “이 저장소에서 코드를 바꿀 때 어떤 결정을 반복해야 하는가”입니다.

CLAUDE.md, AGENTS.md, rules 파일은 제품 소개서가 아니라 작업 계약서에 가깝게 써야 합니다. AI가 매번 지켜야 할 기준을 짧고 명확하게 적고, 바뀌기 쉬운 계획이나 임시 메모는 빼는 편이 보통 더 안정적입니다.

좋은 규칙 파일은 다음 질문에 답합니다.

• 어디를 먼저 읽어야 하는가
• 어떤 패턴을 따라야 하는가
• 무엇을 하면 안 되는가
• 변경 후 무엇으로 검증해야 하는가
• 애매할 때 어떤 선택을 선호하는가

먼저 적을 것: 반복되는 의사결정

규칙 파일의 핵심은 코드 스타일보다 의사결정 기준입니다. 예를 들어 “TypeScript 사용”보다 “API 응답 타입은 route 내부에서 새로 만들지 말고 lib/types의 공유 타입을 우선 확인한다”가 더 유용합니다.

1인 개발자는 머릿속 컨벤션이 많습니다. 문제는 AI가 그 맥락을 모른다는 점입니다. 그래서 반복해서 말하게 되는 지시를 규칙 파일로 올려두면 좋습니다.

특히 “기존 패턴 우선”은 강하게 적어둘 만합니다. AI는 새 헬퍼나 새 구조를 쉽게 만들기 때문에, 작은 프로젝트에서는 오히려 복잡도가 빨리 늘어납니다.

빼야 할 것: 오래된 목표와 긴 배경 설명

규칙 파일이 길수록 좋은 것은 아닙니다. 토큰을 많이 쓰면 실제 작업 지시가 뒤로 밀리고, 서로 충돌하는 문장이 생길 가능성도 커집니다.

다음 내용은 별도 문서로 빼는 편이 낫습니다.

• 지난 의사결정의 긴 역사
• 언젠가 만들 기능 목록
• 마케팅 문구 초안
• 이미 코드로 확인 가능한 라이브러리 목록
• 한 번만 필요한 마이그레이션 지시

예를 들어 “앞으로 결제 기능을 붙일 수도 있음”은 AI에게 당장 필요하지 않을 수 있습니다. 반대로 “결제 관련 코드는 아직 없으므로 임의로 결제 플로우를 만들지 말 것”은 작업 안전장치가 됩니다. 같은 정보라도 행동 기준으로 바꾸면 가치가 생깁니다.

추천 구조: 짧은 섹션 6개

처음부터 거창한 문서를 만들 필요는 없습니다. 아래 정도면 대부분의 1인 프로젝트에서 출발점으로 충분합니다.

# Project Rules

## 읽기 순서
- 작업 전 관련 route, component, server action을 먼저 확인

## 코드 스타일
- 기존 컴포넌트와 헬퍼를 우선 재사용
- 새 의존성은 필요성이 명확할 때만 추가

## 데이터/API 규칙
- 입력 검증은 서버 경계에서 처리
- 에러 응답 형식은 기존 API와 맞춤

## UI 규칙
- 새 디자인 시스템을 만들지 않음
- 기존 spacing, 색상 토큰, 버튼 컴포넌트 사용

## 금지
- 사용자 변경사항 되돌리기 금지
- 관련 없는 리팩터링 금지

## 검증
- 변경 범위에 맞는 lint, typecheck, 테스트 실행

핵심은 “짧지만 판단 가능한 문장”입니다. “좋은 코드 작성”처럼 해석 범위가 넓은 말보다 “관련 없는 리팩터링 금지”처럼 행동이 선명한 문장이 낫습니다.

작업 프롬프트와 규칙 파일을 분리하라

규칙 파일은 항상 적용되는 기준이고, 프롬프트는 이번 작업의 목표입니다. 둘을 섞으면 문서가 금방 지저분해집니다.

작업을 시킬 때는 이렇게 나누면 좋습니다.

• 규칙 파일: 프로젝트에서 늘 지켜야 할 원칙
• 이슈/프롬프트: 이번에 바꿀 기능, 제약, 완료 조건
• 코드 주석: 특정 구현을 이해하는 데 필요한 근거
• README: 사람에게 필요한 설치·운영 안내

예를 들어 “회원가입 버튼 색을 바꿔줘”는 규칙 파일에 들어갈 내용이 아닙니다. 하지만 “색상은 theme.ts 토큰을 통해서만 추가한다”는 규칙 파일에 둘 만합니다.

유지보수 루틴: 실패한 답변을 규칙으로 바꾸기

가장 실용적인 관리법은 AI가 실수했을 때마다 규칙 파일을 조금씩 고치는 것입니다. 단, 실수를 전부 기록하면 문서가 비대해집니다. 반복될 가능성이 있는 실수만 남기세요.

체크 기준은 간단합니다.

• 같은 지시를 두 번 이상 반복했는가
• 코드 리뷰에서 자주 지적하는 패턴인가
• 새 파일을 만들기 전에 반드시 알아야 하는가
• 어기면 복구 비용이 큰가

이 기준을 통과하지 못하면 프롬프트에만 적고 넘기는 편이 낫습니다. 규칙 파일은 기억 저장소가 아니라, 다음 작업의 품질을 높이는 최소 운영 문서입니다.

마무리: AI에게 맡길수록 문서는 짧고 날카로워야 한다

AI 코딩 도구를 잘 쓰는 핵심은 더 많은 배경을 주는 것이 아니라, 매번 흔들리는 결정을 줄이는 것입니다. 프로젝트 규칙 파일에는 철학보다 기준, 배경보다 금지사항, 설명보다 검증 명령을 남기세요.

혼자 만드는 프로젝트일수록 이런 작은 문서가 큰 차이를 만듭니다. 매번 같은 컨벤션을 설명하는 시간을 줄이고, AI가 만든 코드가 기존 코드베이스 안에 자연스럽게 들어올 가능성을 높여줍니다.