📌 문서 개요

• 문서 목적: 프로젝트의 코드 품질 관리(Linting) 및 포맷팅(Formatting) 도구 표준화 정의
• 작성 배경: Next.js 15 및 ESLint 9 환경에서 기존 Rush Stack 설정의 호환성 문제 해결 및 최신 표준 도입 필요성 대두
• 문서 타입: 기획서 / 기술 문서 / 회고 / 설계 / 테스트 / 회의록 / 기타

🧩 핵심 요약

기존 Rush Stack 설정이 최신 ESLint 9(Flat Config) 환경에서 발생하는 구조적 오류(순환 참조 등)를 해결하고, Next.js 15와의 호환성을 확보하기 위해 Native Flat Config 기반의 typescript-eslint v8을 도입한다. Rush Stack 수준의 엄격한 Type-Safety를 유지하면서도, 설정의 복잡도를 낮추고 유지보수성을 높이는 것을 목표로 한다.

📚 상세 내용

<aside>

1. 제목 (Title)

Rush Stack 기반 린트 설정을 Native ESLint 9 (Flat Config)로 마이그레이션

2. 상태 (Status)

Accepted

3. 배경 (Context)

이 결정을 하게 된 상황, 문제, 요구사항

• 기술적 부채: 현재 프로젝트는 Next.js 15와 ESLint 9을 사용 중이나, 기존에 도입하려던 @rushstack/eslint-config는 구형 설정 방식(Legacy Config)에 최적화되어 있음.
• 호환성 문제: ESLint 9에서 Rush Stack 패치를 사용하기 위해 FlatCompat 등을 시도했으나, Circular structure 오류 및 플러그인 로드 실패 등 불안정한 모습을 보임.
• 요구사항: 팀은 엄격한 타입 체크와 일관된 코드 스타일을 원하지만, 설정 파일이 복잡해지거나 외부 라이브러리에 과도하게 의존하는 것은 피하고 싶음.

4. 결정 (Decision)

최종적으로 어떤 선택을 했는지

프로젝트의 린팅 시스템을 ESLint 9 Native Flat Config (eslint.config.mjs) 방식으로 전면 전환하고, 다음 구성을 확정한다.

1. Core Config: typescript-eslint v8의 strictTypeChecked 및 stylisticTypeChecked 프리셋을 사용하여 Rush Stack 수준의 엄격함 유지.
2. Plugin: eslint-plugin-next, react, react-hooks를 직접 구성하여 Next.js 최적화 규칙 적용.
3. Custom Rules: no-floating-promises(비동기 처리 강제), explicit-module-boundary-types(함수 반환 타입 명시) 등 핵심 품질 규칙 커스텀 적용.

5. 근거 (Rationale)

왜 이 선택이 최선인지, 어떤 장단점이 있었는지

이 선택이 최선인 이유는 다음과 같음:

• 표준 준수 및 호환성: ESLint 9부터 Flat Config가 표준이 됨. Rush Stack의 패치 방식은 더 이상 권장되지 않으며, Native 방식이 Next.js 15 생태계와 충돌 없이 가장 잘 동작함.
• 성능 향상: Flat Config는 파일 시스템 탐색 비용이 줄어들어 린트 실행 속도가 더 빠름.
• Type-Safety 유지: Rush Stack을 버린다고 해서 코드 품질이 떨어지는 것이 아님. typescript-eslint의 strictTypeChecked 옵션은 Rush Stack이 제공하던 '타입 기반 린팅' 기능을 완벽하게 대체 및 상회함.
• 명확한 설정 가시성: 숨겨진 패치 파일 없이 eslint.config.mjs 파일 하나에서 모든 규칙을 제어할 수 있어, 팀원 누구나 설정을 이해하고 수정하기 쉬움.

6. 대안(Alternatives)

고려했지만 선택하지 않은 다른 옵션들, 그걸 선택하지 않은 이유

• 대안 1: Rush Stack 유지 (Legacy Mode 강제)
  • 내용: ESLINT_USE_FLAT_CONFIG=false 환경 변수를 사용하여 구형 모드로 작동.
  • 기각 사유: Next.js 15는 Flat Config를 기본으로 권장함. 장기적으로 지원이 중단될 Legacy 모드에 의존하는 것은 기술 부채를 남기는 행위임.
• 대안 2: 기본 eslint-config-next만 사용
  • 내용: Next.js 설치 시 제공되는 기본 설정만 사용.
  • 기각 사유: 기본 설정은 타입 체크가 느슨함. any 타입 남용이나 Promise 처리 누락 같은 잠재적 버그를 잡지 못해 팀의 품질 기준을 충족하지 못함.

7. 결과(Consequences)

이 결정이 가져올 영향, 장기적 고려사항

긍정적 영향:

• 더 이상 Circular structure 에러나 패치 오류에 시달리지 않음.
• Prettier와 ESLint가 완벽하게 통합되어 저장 시 자동 수정(Auto-fix)이 매끄럽게 동작함.
• tsconfig.json 기반의 강력한 타입 검사가 이루어져 런타임 에러를 사전에 방지함.

주의해야 할 점:

• Type-Aware Linting을 사용하므로 린트 실행 시 컴파일 시간이 소요되어 단순 문법 검사보다는 약간 느릴 수 있음.
• VS Code 설정에서 ESLint 플러그인이 최신 버전인지 확인이 필요함. </aside>