일주일 간 에이전트 없이 고정된 코드 유형(readfirst 패턴)만으로 68개 오픈소스 저장소를 스캔해 136건의 실제 문제 지점을 찾고, 21개 프로젝트에 제보했습니다.
그 중 MIT로 공개한 부분은 코드 지도 쪽이며 파일 별 맥락 관리, 이미 존재하는 함수나 기능을 알려줘 중복을 막는 기능 등을 포함합니다.
readfirst: 파일을 바꾸기 전에 읽고 확인해야 할 것을 컨텍스트로 제공하는 도구코딩 에이전트는 import는 따라갈 수 있지만, 개발자, 개발 팀만 아는 프로젝트의 로컬한 지식은 알지 못합니다.
"여기는 금액 단위가 센트다", "이 테이블은 모바일 앱이 읽으니 기존 컬럼을 유지해야 한다", "수정한 뒤 결제 e2e를 돌려라" 같은 맥락이 없기 때문입니다.
이 지식을 코드와 함께 파일 하나(.readfirst/map.json)에 모아두고, 에이전트가 코드를 수정하거나 새 코드를 작업하는 순간마다 파일 단위로 꺼내 주면 어떨까요?
파일을 수정하기 전과 후에 readfirst를 실행하면, 모델 호출이나 서버 없이 로컬에서 알아서
• 해당 파일의 규칙, 위험 요소, 체크 항목, 테스트, 호출자(callers)를 보여주고
• git 히스토리에서 지난 12개월 동안 가장 자주 깨졌던 파일을 찾아내고
• 버려진 QuerySet/문자열 결과나 아무도 await하지 않는 expect(...).resolves 같은 고정된 버그 모양을 스캔하고
• 작업이 끝나기 전에 연결된 체크가 통과했는지, 함께 바꿔야 할 파일이 누락되지 않았는지 검증하고
• 새 함수를 만들기 전에 이미 같은 일을 하는 코드가 있는지 찾아주고 (readfirst find)
• 적어 둔 규칙·위험이 그 뒤 코드가 얼마나 바뀌어 낡았을 수 있는지 git 기록으로 짚어 줍니다 (readfirst audit)
• 앱 코드 버그 100건 (21건은 낮은 심각도의 시크릿 !== 비교)
• 체크가 실패해도 통과해 버리는 테스트 36건 (expect(promise).resolves...에 await나 return이 빠져 Jest에서 단언문이 돌기 전에 테스트가 끝나는 방식)
• 실제 업스트림에 반영돼 픽스된 버그들:
◦ Saleor: 가격, 상세사항이 변경된 물품만 재계산하는 옵션(only_dirty_products)에서 filter() 결과가 버려져 변동사항이 생길때마다 모든 할인 가격을 다시 계산하던 버그 수정 (https://github.com/saleor/saleor/pull/19984) — 제보 이후 Saleor 팀이 미할당 QuerySet을 막는 Semgrep 린트 규칙을 추가했습니다
◦ Wagtail: 슈퍼유저가 자기가 작업하던 페이지를 검토 요청으로 제출할 때 exclude() 결과가 버려져 본인이 제출한 페이지의 검토 이메일을 본인이 받던 버그 수정 (https://github.com/wagtail/wagtail/pull/14790)
◦ n8n: RabbitMQ 노드가 큐 바인딩 전에 채널을 반환하고 바인딩 실패가 처리되지 않은 거부(unhandled rejection)로 빠져나가던 문제를 이슈 제보 후 n8n 팀이 수정 (https://github.com/n8n-io/n8n/pull/43033)
◦ django-allauth: 프로바이더 콜백에서 비 ASCII 값에 대해 깔끔한 실패 대신 500 에러를 반환하던 문제를 제보 당일 수정 (https://codeberg.org/allauth/django-allauth/commit/f1e06cc050eb)
◦ WYGIWYH: OAuth 클라이언트 등록 토큰을 문자열로 비교해서, 비 ASCII 토큰이 들어오면 거절 대신 500 에러가 나던 문제를 회귀 테스트와 함께 PR로 보내 병합 (https://github.com/eitchtee/WYGIWYH/pull/649) — 메인테이너가 "테스트 덕분에 예전 비교가 잘못된 토큰을 500으로 만든다는 걸 쉽게 확인했다"고 남겼습니다
◦ Mealie: 가구(household)별 데이터를 나누는 안전장치에서 filter() 결과가 버려져, 안전장치가 실제로는 적용되지 않던 문제를 이슈로 제보 (https://github.com/mealie-recipes/mealie/issues/8964) — 이후 제보와 별개로 진행된 메인테이너의 범위 수정(https://github.com/mealie-recipes/mealie/pull/8965)에서 해당 코드가 바뀌어 지금 main에서는 사라졌습니다
• 현재 메인테이너 검토 대기 중인 제보 및 PR: Tandoor 필터 누락(https://github.com/TandoorRecipes/recipes/pull/4917), Cal.diy의 실패한 PayPal 캡처 처리 및 await 누락 웹훅(https://github.com/calcom/cal.diy/pull/30526, https://github.com/calcom/cal.diy/pull/30527), Sentry의 커밋 전 태스크 큐잉(https://github.com/getsentry/sentry/pull/130383), vas3k.club의 비 ASCII 시크릿 500 에러(https://github.com/vas3k/vas3k.club/pull/1533, 메인테이너 승인 완료)
그래서 이 CLI와 훅, MCP 서버, GitHub Action을 오픈소스로 공개합니다.
의도대로 사용했을 때 도움될 경우는 다음과 같습니다.
• 저장소에서 계속 깨졌던 부분을 정리해 테스트를 보강하고 싶은 경우
• await가 빠져서 실제로는 아무것도 검사하지 않는 테스트가 있는지 걱정되는 경우
• Claude Code, Cursor, Codex, Gemini CLI, Copilot, OpenCode 같은 코딩 에이전트(그 밖에는 MCP로)와 PR에 파일별 규칙·위험·체크를 연결하고 싶은 경우
맛보기: 설치나 설정 없이 내 저장소 폴더에서 바로
npx readfirst audit지난 1년 git 기록에서 자주 고장 났던 파일을 보여줍니다.
제대로 쓰려면 이 순서를 추천합니다.
1단계. 저장소 맨 위 폴더에서 한 번 실행
npx readfirst init --agent --ci폴더 구조로 첫 지도(.readfirst/map.json)를 만들고, package.json 스크립트에서 돌릴 검사를 찾아 넣습니다. CLAUDE.md나 AGENTS.md에 "파일을 고치기 전에 readfirst를 읽어라"는 한 줄을 넣고, PR에 댓글을 다는 GitHub Action도 추가합니다. (Codex나 Claude Code라면 훅으로 더 확실하게 할 수 있습니다. 그 파일의 노트를 읽기 전에는 수정을 한 번 막고, 맵의 검사가 통과하기 전에는 작업을 끝내지 못하게 합니다.)
2단계. 맵 채우기 (둘 중 하나)
• 로컬 경로: npx readfirst prompt 가 주는 프롬프트를 에이전트에게 보내면, 에이전트가 규칙·위험·검사를 채웁니다.
• 호스팅 경로: GitHub에 readfirst-app(https://github.com/apps/readfirst-app/installations/new)을 설치하고 아무 이슈에 /readfirst fill 이라고 댓글을 달면, 5~20분 뒤 맵이 PR로 옵니다. 계정당 한 번 무료(파일 200개 이하 저장소).
3단계. 확인하고 커밋
npx readfirst check맵에 빠진 파일이나 틀린 곳이 없는지 보고, 통과하면 .readfirst/map.json을 커밋합니다.
그다음부터는 에이전트가 1단계에서 넣은 한 줄을 보고 알아서 확인합니다. 사람이 직접 쓸 때는 두 개만 기억하면 됩니다.(다시 한번 말씀 드리면 agents.md, claude.md를 무시하고 작업하는 경우가 종종 있으니, Claude Code라면 npx readfirst hook --install --verify 로 훅을 걸어 두면 건너뛰는 상황을 확실히 막을 수 있습니다)
npx readfirst read <파일> # 고치기 전에: 이 파일의 규칙, 위험, 돌릴 검사 npx readfirst verify # 끝내기 전에: 필요한 검사가 다 통과했는지완전히 로컬 dev tool이고 코드를 외부로 보내지 않는 MIT 라이선스 오픈소스입니다.
(호스팅 버전인 GitHub App https://readfirst-cloud.vercel.app/ 에서는 계정당 1회 무료로 첫 맵을 작성해 줍니다.)
GitHub: https://github.com/jeonghun917/readfirst
가이드: https://github.com/jeonghun917/readfirst/blob/main/docs/guide.md