하나의 파일로 모든 것을 통제하는 방법: AI 코드 어시스턴트의 규칙 파일 전략

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

• 개발자 및 DevOps 엔지니어
• AI 코드 어시스턴트(Cursor, Windsurf, VS Code) 사용자
• 규칙 기반 코드 자동화를 도입하고자 하는 팀 리더/기술 담당자
• 난이도: 중간 (AI 툴 사용 경험, TypeScript/Playwright 기초 지식 필요)

핵심 요약

• 🤖 규칙 파일의 핵심 가치: AI 어시스턴트가 프로젝트별 코드 스타일, 아키텍처 패턴, 테스트 전략을 일관되게 준수하도록 강제
• 🚀 개발자 온보딩 가속화: 새로운 팀원/AI 어시스턴트가 1일 내 프로젝트 컨벤션을 완벽히 이해
• 🧩 컨텍스트 기반 정확성: Playwright, Zod, TypeScript Strict Mode 등 프로젝트 기술 스택을 AI 어시스턴트에게 명시적으로 전달
• ✅ 프롬프트 편향 최소화: "JSDoc 추가"나 "사용자 직관적 로케이터 사용" 같은 반복적 지시를 규칙 파일에 포함하여 개발자 시간 절약

섹션별 세부 요약

1. AI 코드 어시스턴트의 문제점

• 불일치된 결과: AI 어시스턴트가 프로젝트 스탠다드를 무시한 코드 생성 → 테스트/프론트엔드/백엔드 협업 장애
• 시간 낭비: 개발자가 AI를 위한 반복적 프롬프트 작성 → 프로젝트별 커스터마이징 필요성 증대

2. 규칙 파일의 구조적 이점

• 테스트 자동화 프레임워크 예시:

- fixture/api/schemas.ts: Zod 스키마로 API 요청/응답 검증

- pages//*.ts: Page Object Model (POM)** 기반의 로케이터 정의 (ex: this.page.getByRole('textbox', { name: 'Article Title' }))

- .prettierrc: Prettier 설정으로 코드 포맷 일관성 유지

• 코드 생성 규칙:

- TypeScript Strict Mode 사용 → any 타입 최소화

- ESNext 기능 (옵셔널 체이닝, nullish coalescing) 활용

- JSDoc 주석 필수 (ex: @param, @returns, @throws)

3. 규칙 파일의 구현 방법

• 파일 구조:

```bash

root/

├── env/ # 환경 변수 (.env.dev, .env.example)

├── fixture/ # Playwright 테스트 퍼시픽스 (api, pom)

├── pages/ # Page Object Model 클래스 (adminPanel, clientSite)

├── tests/ # E2E, API, UI 테스트 스크립트

└── TEST-PLAN.md # 테스트 전략 문서

```

• 규칙 예시:

- POM 클래스 생성 규칙:

```typescript

constructor(private page: Page) {}

get articleTitleInput() {

return this.page.getByRole('textbox', { name: 'Article Title' });

}

```

- 메서드 설계:

```typescript

async publishArticle(articleData: ArticleData): Promise {

await this.articleTitleInput.fill(articleData.title);

await this.articleBodyInput.fill(articleData.body);

await this.publishButton.click();

await expect(this.page.getByText('Published successfully')).toBeVisible();

}

```

결론

• 규칙 파일 생성 전략:

1. 프로젝트별 기술 스택, 아키텍처, 테스트 전략을 명시한 단일 markdown 파일 작성
2. AI 어시스턴트가 접근 가능한 경로에 파일 배치 (ex: rules.md)
3. 정기 업데이트 및 팀 내 공유 강화 → 코드 품질과 협업 효율성 극대화

• 실무 적용 팁:

- playwright.config.ts에 reporters: ['html'] 설정으로 테스트 결과 시각화

- Zod 스키마를 사용해 API 요청/응답의 타입 안전성 보장

- data-testid 속성으로 로케이터의 안정성 확보 (ex: this.page.locator('[data-testid="error-message"]'))