konsistent 공부 정리 | 구조 규칙을 에이전트도 읽는 명세로

Vercel changelog를 보다가 konsistent라는 CLI 린터가 오픈소스로 공개됐다는 발표를 발견했다. TypeScript 프로젝트에서 구조적 컨벤션을 강제하는 도구라는데, “에이전트와 사람 모두에게 일관된 컨텍스트를 제공하기 위해”라는 설명이 함께 달려 있었다.

처음엔 “ESLint랑 뭐가 다른 건데?”라는 생각이 먼저 들어서, 공식 문서를 좀 더 꼼꼼히 읽어봤다.

1️⃣ 이게 뭐냐?

ESLint는 파일 내부의 코드 패턴을 검사한다. 변수 이름, 미사용 import, 타입 문제 같은 것들. TypeScript도 타입 수준에서 구조를 잡아주긴 하지만, 두 도구 다 “폴더나 파일 간의 관계”까지는 다루기 어렵다.

예를 들어 “src/routes 아래에 있는 파일들은 반드시 handler를 export해야 한다”거나, “특정 폴더에 config.ts가 있으면 index.ts도 있어야 한다”는 식의 규칙이다. ESLint는 각 파일을 독립적으로 보기 때문에, 폴더 구조 전체를 아우르는 규칙을 강제하는 건 본래 설계 범위 밖에 가깝다.

konsistent는 이 틈새를 다룬다. 프로젝트 루트에 konsistent.json을 두고 규칙을 선언하면, CLI가 코드베이스 전체를 스캔해서 위반 항목을 찾아준다. 결정론적이고 빠르며, TypeScript나 ESLint가 다루지 못하는 구조 패턴에 특화돼 있다는 게 핵심 설명이었다.

지원하는 검증 유형은 이런 식이다: 특정 패턴의 파일이 지정한 함수나 타입을 export하는지, 어떤 폴더에 파일 A가 있으면 B도 있어야 하는지, 특정 클래스가 인터페이스를 구현하는지. Vercel 자체의 AI SDK와 Chat SDK에서 이미 실운용 중이라고 한다.

2️⃣ 내가 든 생각

처음엔 그냥 린터 하나 더 생긴 것처럼 읽혔는데, “에이전트와 사람 모두를 위해”라는 구절을 다시 보면서 생각이 조금 달라졌다.

코딩 에이전트가 코드를 짤 때 뭘 어려워하냐 하면, 그 프로젝트만의 암묵적인 구조 규칙을 파악하는 게 쉽지 않다는 게 하나인 것 같다. “이 폴더 아래 파일들은 이런 패턴을 따라요”라는 걸 일일이 프롬프트로 알려줘야 하는 상황이 생기는데, konsistent.json이 있으면 에이전트가 그 파일을 읽고 컨텍스트를 얻을 수 있다는 얘기가 된다.

👉🏻 흥미로웠던 건, 이게 결국 코드 컨벤션이 사람만 읽는 가이드에서 에이전트도 참조하는 명세로 기능하게 된다는 방향이었다.

💡 여기서 드는 질문? 선언적 구조 규칙이 있으면, 에이전트가 새 파일을 만들 때 그 규칙을 스스로 따를 수 있을까? 지금은 사후 검증(린팅) 수준인 걸까, 아니면 더 능동적인 방향으로도 쓸 수 있을까.

디자이너 관점에서 보면, 디자인 시스템에서 컴포넌트 사용 규칙을 문서로 정리해두는 것이랑 발상이 비슷하기도 했다. Notion 페이지에 적어두는 것과, 도구가 직접 강제할 수 있는 형태로 선언하는 것의 차이. 후자는 “문서가 오래되면 코드랑 달라지는 문제”를 어느 정도 원천 차단하는 것에 가깝다고 느꼈다.

⭐️ 마지막으로

이런 류의 도구를 볼 때 자꾸 같은 질문을 하게 되는 것 같다 — 이게 코드를 위한 건가, 아니면 코드를 읽는 에이전트를 위한 건가. 아마 둘 다라는 게 답이겠지만, 그 우선순위가 슬금슬금 바뀌고 있다는 게 지금은 더 흥미롭다.

---

참고 원문: Enforce consistent code for agents and humans with konsistent