Vercel이 TypeScript 코드베이스의 구조적 컨벤션을 강제하는 CLI 린터 konsistent를 오픈소스로 공개했다. TypeScript 타입 검사나 ESLint로는 다룰 수 없는 파일/폴더 구조 규칙을 빠르고 결정론적으로 검사하며, AI 에이전트와 인간 개발자 모두가 일관된 코드 구조를 유지하도록 돕는다.
핵심 포인트- 패턴 X와 일치하는 파일들이 특정 함수를 export하는지, 폴더에 필요한 파일이 모두 있는지 등 구조적 컨벤션을 기계적으로 검사한다.
- konsistent.json에 규칙을 선언적으로 정의하며, 340개 파일을 212ms에 검사할 정도로 빠르다.
- Vercel의 AI SDK와 Chat SDK에서 실제로 harness 패키지 구조 강제에 사용 중이다.
- AI 에이전트가 코드 생성 시 구조 컨벤션을 준수하는지 자동 검증하는 단계로 활용 가능하다.
- npx로 즉시 설치 가능하며, 에이전트 스킬로 konsistent.json 초기 설정 생성을 위임할 수 있다.
상세 정리- 문제: TypeScript 타입 체커와 ESLint는 코드 문법/타입을 검사하지만 "이 패턴의 파일들이 특정 export를 반드시 가져야 한다"는 구조적 컨벤션은 검사하지 못한다.
- 해결: konsistent.json에 글로브 패턴 기반 규칙 선언 — 파일 패턴 매칭 후 export/import 존재 여부, 타입 구현 여부, 관련 파일 존재 여부를 검사한다.
- 규칙 유형 1: 패턴 X와 일치하는 모든 파일이 함수 Y와 Z를 export하는지 확인.
- 규칙 유형 2: 특정 파일이 있는 폴더에 파일 Y도 반드시 있어야 한다는 의존성 규칙.
- 규칙 유형 3: 패턴 X와 일치하는 파일에서 export된 클래스가 타입 Y를 구현하는지 확인.
- CLI 출력: 오류 발생 시 파일명, 규칙 ID, 누락된 export/import/파일을 상세 출력하여 정확히 무엇이 빠졌는지 즉시 파악 가능.
- 실사용: Vercel AI SDK에서 harness 패키지가 HarnessV1 타입 구현 여부, bridge 파일의 필수 심볼 export 여부 등을 konsistent로 강제 관리 중.
- 에이전트 활용: AI 에이전트는 컨텍스트 일관성이 깨지면 잘못된 구조의 코드를 생성하는데, konsistent가 이를 기계적으로 검증해 일관성을 보장한다.
왜 읽나AI 에이전트와 협업하거나 대규모 TypeScript 코드베이스에서 구조적 컨벤션을 자동으로 강제하고 싶은 개발자에게 실용적인 린터 도구 레퍼런스.
Stack Overflow Blog·
