README Clew 2: AdaL로 만들고, Jev가 분류하고, 코드가 판정하고, Haiku가 설명합니다

AI 요약

README Clew 2는 README의 설명이 저장소 코드와 맞는지 검사하는 웹 페이지와 Chrome 확장 프로그램입니다. 공개 JavaScript·TypeScript 저장소를 입력하면 README를 줄 단위로 읽고, 각 검사 결과에 README 문장과 코드 근거, 판정 주체를 함께 표시합니다. 결과는 ‘모순됨’, ‘누락’, ‘검증 불가’, ‘확인됨’ 네 가지로 나눕니다.

분류와 판정을 분리합니다

README의 제목, 배지, 빈 줄처럼 모델이 필요 없는 항목은 코드가 바로 분류합니다. 나머지 문장은 결정 모델 Jev가 의존성, 명령, 환경 변수, 파일·URL, 그 밖의 항목 중 하나로 분류합니다. Jev의 확신도가 0.8 이상일 때만 다섯 가지 결정론적 검증기로 넘깁니다. 검증기는 package.json, 파일 트리, 소스 코드를 살펴보고 결과를 정합니다. 확신도가 기준에 못 미치거나 코드 검사로 판별할 수 없는 문장은 ‘검증 불가’로 남깁니다.

Claude Haiku는 마지막에 검사 결과의 개수와 이름만 받아 짧은 요약을 씁니다. README 문장 자체는 보지 않습니다. 작성자는 README에 심어 둔 지시문이 요약 모델의 답을 바꾸지 못하도록 이 경계를 뒀습니다. 이 설계에서 모델은 사실 여부를 판정하지 않습니다. Jev는 문장의 종류만 정하고, 코드 검증기가 참·거짓을 가립니다.

오탐을 줄인 방식과 평가 결과

작성자는 틀린 문장을 놓치는 일보다 맞는 문장을 ‘모순됨’으로 잘못 표시하는 일이 신뢰를 더 크게 해친다고 봅니다. 그래서 확신이 낮은 문장을 ‘검증 불가’로 보내 검사 범위가 줄어드는 쪽을 택했습니다. 문장 유형을 잘못 붙여도, 산문에만 등장하는 패키지 이름은 ‘모순됨’으로 판정할 수 없게 하는 규칙도 코드에 넣었습니다.

설정을 고정한 뒤 보류한 README 문장 32개를 두 차례 검사했습니다. 두 실행 모두 확신도 기준을 통과한 오분류는 0건이었고, 전체 흐름에서 발생한 잘못된 ‘모순됨’ 판정도 0건이었습니다. 실제 문서와 코드가 어긋난 사례는 두 실행 모두 3건 중 3건을 찾았습니다. 다만 32개는 작은 표본이므로 측정된 오류율로 보기는 어렵다고 글은 선을 긋습니다. 한 번 전체를 검사하는 비용은 약 1센트이며, 그중 Jev 호출 비용은 약 0.009달러입니다.

첫 실전 검사에서 드러난 오류

첫 검사는 작성자의 이전 버전 저장소를 대상으로 했습니다. README Clew 2는 세 문장을 ‘모순됨’으로, 네 패키지를 ‘누락’으로 표시했지만 확인 결과 일곱 건 모두 오탐이었습니다. 저장소가 pnpm 모노레포였고, 워크스페이스 탐색기가 일부 폴더를 놓쳤습니다. 또 pnpm의 --filter 옵션을 스크립트 이름으로 읽었습니다. 수정 뒤 해결하지 못하는 항목은 ‘모순됨’ 대신 ‘검증 불가’로 처리했고, 해당 저장소를 회귀 테스트에 추가했습니다. 다시 검사하자 잘못된 모순 판정은 3건에서 0건으로 줄었고, 누락으로 표시했던 패키지 네 개는 실제 누락으로 확인됐습니다.

polka 저장소에서도 예제 폴더의 별도 package 파일 때문에 패키지 14개를 누락으로 표시했습니다. 작성자는 이 사례도 같은 유형의 수정과 테스트로 다뤘습니다. 이후 검토에서는 20개 파일 읽기 제한 너머에서 사용되는 환경 변수와, 커밋되지 않는 dist/ 같은 빌드 출력물을 가리키는 README 경로가 추가 오탐 원인으로 확인됐습니다. 두 경우 역시 ‘검증 불가’로 돌렸습니다.

구현 범위와 개발 과정

검사는 JavaScript와 TypeScript만 지원합니다. 모노레포는 단순한 워크스페이스 패턴 최대 30개까지 다루며, 범위를 넘으면 ‘누락’ 대신 ‘검증 불가’로 처리합니다. 검사마다 소스 파일은 최대 20개까지 읽고, 50KB보다 큰 README는 잘라냅니다. 대부분의 README 문장은 코드로 확인하기 어려운 설명문이라, 자체 README 검사에서도 285줄 가운데 107줄이 ‘검증 불가’였습니다. 계정이나 데이터베이스는 없으며 검사 결과는 저장하지 않습니다. JSON 내보내기에는 저장소와 커밋 정보, README와 보고서의 지문을 담습니다.

이 프로젝트는 AdaL의 해커톤을 위해 5일 동안 만들었습니다. 작성자는 직접 코드를 쓰기보다 방향을 정하고 결과를 검증했습니다. AdaL은 코드와 테스트 작성, Jev 평가, 배포, 브라우저 QA를 맡았고, Claude Opus 5.5는 설계 문서와 구조 검토를 담당했습니다. 파일마다 200줄 제한을 두고 테스트에서 강제했으며, 최종 제출 시 테스트는 474개였습니다. 다만 매 테스트마다 일부러 실패를 확인하는 방식은 에이전트 실행 비용을 키웠습니다. 작성자는 API 키 사용료로 약 3시간 반 동안 36달러를 썼고, 이후 새 세션을 블록마다 시작하는 ‘lean mode’를 적용했습니다. 에이전트 비용은 최종 40.35달러였습니다.

dev.to 반응

• @dev_in_the_fog — AI 워크플로를 깊이 있게 살펴볼 수 있어 흥미롭습니다. 더 많은 에이전트 시스템이 실제 서비스에 들어가면 출력의 근거를 확보하고 지연 시간 예산을 평가하는 일이 중요해지겠습니다.
  • @earlgreyhot1701d — 감사합니다. 근거를 확보하는 게 설계의 전부였습니다. Jev는 문장이 어떤 종류인지 분류하고, 실제 저장소를 검사하는 코드가 참인지 판정합니다. 요약 모델도 검사 결과만 보고 README 자체는 보지 않으므로 README에 관한 내용을 지어낼 수 없습니다. 본인 작업에서는 출력을 어떤 방식으로 근거에 연결하는지 궁금합니다.
• @traceypears — “Jev가 분류하고, 코드가 판정하고, Haiku가 설명한다”는 접근이 꽤 흥미롭습니다. 데이터 분류, 논리 평가, 자연어 생성의 세 단계를 명확히 나눴습니다. AdaL(Adaptive Labeling?)로 분류 단계의 사람 개입을 줄이면서도 최종 관문은 코드가 맡는 점이 좋습니다. 파이프라인에 관해 질문이 있습니다. Haiku는 코드의 결과와 추론을 바탕으로 설명을 생성하나요, 아니면 원래 맥락인 diff, 파일 트리, 연결된 이슈에도 접근하나요? 결과와 짧은 이유만 전달하면 환각이 나오거나 설명이 일반적일 수 있습니다. 맥락을 너무 압축해 이런 문제를 겪는 프로젝트를 많이 봤습니다. 성능 측면에서는 코드가 Jev의 분류를 거부할 때 AdaL이 자동으로 피드백을 받아 재학습하나요? 아니면 아직 사람이 오탐과 미탐을 검토하나요?
• @roredcol — 분류(Jev), 판정(코드), 설명(Haiku)을 분리한 방식이 흥미롭습니다. 사람 개입이 있는 방식과 비슷하지만 자동화된 파이프라인으로 끌어올렸습니다. Jev가 라벨 A를 붙였는데 코드 로직이 라벨 B에 투표하는 충돌은 어떻게 처리하나요? 대체 전략이나 확신도 기준이 있나요? AdaL을 기반으로 썼다고 했는데, README 검증으로 확장한 건 자연스러운 선택처럼 보입니다. readme-score나 awesome-readme linter 같은 규칙 기반 기준과 비교한 벤치마크가 있나요? CI/CD 설정 없이 사람 손으로 README를 검토하는 저장소의 오탐률은 어느 정도인가요? 모노레포의 README 여러 개나 docs/README.md 같은 비표준 위치를 앞으로 어떻게 처리할지도 궁금합니다.
• @humam_moin — 도구가 처음 틀린 대상이 본인의 저장소였다는 점이 가장 마음에 듭니다. 그게 어떤 도구든 가장 솔직한 테스트입니다. 직접 코드를 쓰지 않고 방향을 정하고, 검증하고, 결정한다는 방식도 몇 년 뒤 우리 대부분이 일하는 모습이라고 생각합니다. 5일 만에 출시한 점도 존경스럽습니다. 공유해 주셔서 감사합니다.
• @alexcodebytes — 아키텍처를 먼저 세운 AI 엔지니어링의 좋은 사례입니다. 문장을 쓸 수 없는 결정 모델 Jev를 제약으로 삼고, 전통적인 LLM 파이프라인의 약점을 해결하는 데 쓴 점은 방어적인 설계의 교과서 같습니다. Jev가 README 문장 분류만 맡고 Claude Haiku는 요약에만 쓰는 2단계 검증은 신뢰도를 높입니다. 실제 사용에서 오래된 저장소를 처음 검사해 틀렸다는 사실을 공개한 점도 좋습니다. 검증 도구에서 잘못된 고발과 잘못된 확인은 모두 위험합니다. 다섯 가지 결정론적 코드 검사를 앞세워 산문을 패키지로 오해하는 문제를 막았습니다. Ariadne의 실타래를 따라 README의 주장을 정적 코드 근거로 연결하는 이름도 설계 철학과 잘 맞습니다. Glasser를 통해 소형 결정 모델을 쓰려면 0부터 1까지의 확신도 기준을 세밀하게 조정해야 합니다. 두 가지 기술 패턴을 제안합니다. 첫째, 경계 사례에는 확신도 기준을 둡니다. 예를 들어 0.72보다 낮으면 다섯 검사기로 넘기지 말고 ‘의미 경계 사례’로 표시한 뒤 Haiku에 2차 검증을 맡길 수 있습니다. 고정된 라벨에 맞지 않는 복잡한 문장을 위한 회로 차단기 역할을 합니다. 둘째, Jev의 라벨에 따라 AST나 패키지 검사 범위를 좁힙니다. 의존성 주장이라면 package.json의 의존성 항목만 살피고, 구조나 설정 주장이면 AST의 진입점을 검증하는 식입니다. AdaL로 코드와 문서의 일치를 지키는 도구를 만드는 일은 오픈소스 생태계에 필요한 작업입니다.
• @sinarezaei — 32개 문장을 따로 평가한 결과는 유용한 시작점입니다. 장기적으로 이 접근의 가치를 입증할 곳은 회귀 테스트라고 생각합니다. 한 가지 경계 사례를 시험해 볼 만합니다. 워크스페이스 패키지에 README 명령이 있지만 다른 워크스페이스의 의존성이나 스크립트가 바뀐 뒤 그 명령이 유효하지 않게 되는 경우입니다. 검증기는 실제 어긋남을 잡되 관련 없는 패키지 변경을 잘못된 모순 판정으로 바꾸지 않아야 합니다. 명령, 의존성, 환경 변수처럼 주장 유형별 정밀도를 따로 추적하고 싶습니다. 전체에서 잘못된 모순 판정이 0건이라는 결과는 고무적이지만, 유형별 결과가 있으면 검증기가 어디서 믿을 만하고 어디서 검사 범위가 부족한지 더 쉽게 알 수 있습니다.

원문: dev.to / 번역·요약: Trawling