AI 지원 도구를 사용한 멀티 팀 개발에서, PR(Pull Request) 리뷰를 할 때마다 같은 지적을 반복하고 있다는 사실을 깨달았다.

2개 거점 체제로 Laravel에서 React로의 이전을 진행 중인 현장의 이야기다. 전원이 동일한 AI 통합 개발 환경(AWS가 공개한 Kiro)을 사용하고 있음에도 불구하고, 왜인지 팀 간에 코드 품질의 편차가 발생한다. 규칙 정의 파일(steering이나 instructions)에 규약을 적어 두었는데도 말이다.

이 기사에서는 규칙이 "존재하지만 적용되지 않는" 문제의 원인을 특정하고, fileMatch 설정과 구체적인 임계값(threshold)을 통해 당일 즉시 해결한 실천 사례를 공유한다.

• React 18 + TypeScript
• 백엔드: Express (TypeScript)
• AI 지원: Kiro (AWS가 공개한 AI 통합 개발 환경. steering / skill / instructions를 통해 AI에게 읽힐 규칙을 정의할 수 있음)
• 팀 구성: 2개 거점 체제

어느 PR을 리뷰했을 때, 다음과 같은 내용이 한꺼번에 나왔다.

❌ 공통 데이터 취득 훅(hook)을 사용해야 하는 곳에서 상태 관리 스토어(store)를 신규 추가
❌ 레거시 API 래퍼(Legacy API wrapper, 구 API를 집약한 거대 파일)에 메서드 추가 (기능별 분리 없이)
❌ IT 사양서가 독자적인 경로에 배치
...

전부 규칙 정의 파일에 적혀 있는 규약이다. 적혀 있는데도 지켜지지 않고 있다. 솔직히 3번째 정도 지적했을 때, 이것은 시스템의 문제라고 확신했다.

# 이렇게 되어 있었다
---
inclusion: manual
...

manual은 개발자가 채팅에서 명시적으로 #규칙명이라고 지정하지 않으면 AI의 컨텍스트(context)에 들어가지 않는다.

AI는 "현재 컨텍스트에 들어있는 정보"만으로 판단한다. 규칙이 들어있지 않으면, 가장 최근의 코드(= 오래된 패턴)를 참조하여 생성한다. 결과적으로 한쪽 팀의 AI는 다른 쪽 팀이 정비한 규칙의 존재를 모른 채 오래된 패턴을 계속 답습하고 있었다.

리뷰에서 몇 번을 지적해도 다음 PR에서 또 같은 일이 발생하는 이유는 이것이었다.

---
inclusion: fileMatch
fileMatchPattern: 'react/src/**/*.{ts,tsx}'
...

react/src/ 하위의 파일을 건드리는 순간 규칙이 자동으로 읽힌다. 잊어버릴 수가 없다. 이것이 가장 효과가 컸다.

"규모가 커지면 분할을 검토할 것" → AI에게는 통하지 않는다. 다음과 같이 고쳐 썼다:

## Repository 입도(granularity) 가이드라인
| 행 수 | 대응 |
|------|------|
...

수치가 있으면 AI는 판단에 망설임이 없다. 인간도 마찬가지다.

## 금지 사항
- 레거시 API 래퍼에 대한 신규 메서드 추가 → 기능별 API 클래스를 신규 생성할 것
- `.github/workflows/` 하위의 변경 → React 이전 PR에서는 원칙적으로 불가
...

"권장하지 않습니다"가 아니라 "금지"라고 쓴다. AI는 모호함에 약하다. 명확하게 NG라고 쓰면 생성 단계에서 피하게 된다.

## 모범 PR (구조의 참고용)
- PR-A: 화면 이식 — 셀프 리뷰 수렴 · ADR · 인간 대응 사항 리스트
- PR-B: 참조계 API 화면 — API 설계 · discriminated union

AI는 "어디를 참조할지"를 지정해 주면 그 패턴을 답습한다. 지정하지 않으면 최근의 커밋(오래된 패턴)이 참조 대상이 된다.

대책 투입 다음 날 들어온 PR:

✅ 공통 데이터 취득 훅을 사용
✅ API 클래스는 기능별 파일로 독립
✅ IT 사양서는 정해진 디렉토리에 배치
...

같은 개발자가 제출한 PR임에도 품질이 일치했다. 규칙이 자동으로 읽히게 된 것만으로 AI의 생성 결과가 달라진다.

React 이전 코딩 규칙처럼 "그 파일을 건드린다면 반드시 알고 있어야 하는" 것은 fileMatch가 정답이다.

# ❌ 효과 없는 작성법
Repository가 너무 커지지 않도록 주의해 주세요.
# ✅ 효과 있는 작성법
...

AI에 대한 지시도 인간에 대한 지시와 마찬가지로, 구체성이 없으면 행동으로 이어지지 않는다.

• 규칙의 "존재"와 "적용"은 별개다.
  manual과 fileMatch의 차이는, 문서를 작성하느냐 아니면 Slack이나 Wiki를 통해 공지하느냐의 차이만큼 임팩트가 있다.
• AI가 생성하는 코드의 품질은, 컨텍스트 (Context)에 무엇이 들어있는가에 따라 9할이 결정된다.
• 리뷰에서 같은 말을 3번 했다면, 그것은 규칙 설계의 결함이다. 기계가 지키게 해야 한다.

"AI에게 맡기는" 시대의 코드 품질 관리는, 코드 그 자체보다 "AI가 참조하는 규칙"의 설계가 본질이라는 것을 실감했다.

다음으로는 이 규칙 설계 자체를 CI에서 자동으로 체크하는 메커니즘(새로운 파일이 추가되었을 때 기존 규칙과의 정합성을 검증하는 등)을 만들고 싶다.

본 블로그에 게재된 내용은 저 개인의 견해이며, 소속된 조직의 입장이나 전략, 의견을 대표하지 않습니다.