TL;DR

  • Perch는 의사결정 모델을 활용해 코드의 의미적 결함을 검사하며, 변경되지 않은 코드의 결과를 캐시하고 첫 5달러를 무료로 제공함.
  • perch scan은 파일별 문제와 심각도·신뢰도·결함 유형을 표시하며, perch issues와 perch issues <id>로 문제를 확인할 수 있음.
  • perch check <id>는 수정했다고 판단한 문제를 다시 검사하며, 그 결과를 기록하지 않음.
  • perch.yaml에 사용자 지정 규칙을 추가할 수 있고, Claude Code·Codex·Pi·Cursor용 에이전트 지침도 설치할 수 있음.
  • Perch Cloud는 기본적으로 질문에 적합한 모델을 선택하며, System One 형식을 지원하는 다른 엔드포인트·키·모델도 지정할 수 있음.

시작하기

  • npm install -g @lakeday/perch로 설치하고 perch login으로 Perch Cloud에 로그인한 다음 perch scan으로 검사함.
  • 첫 5달러는 무료이며, 의사결정 결과가 캐시되므로 코드가 바뀌지 않은 상태에서 다시 실행하면 무료임.
  • Perch Cloud는 별도의 워크플로 파일을 작성하지 않아도 지속적 통합(CI)에서 풀 리퀘스트를 검사함.
  • 검사 결과에는 파일별 문제 식별자(ID), 줄 번호, 심각도, 유형, 신뢰도, 문제 유형, 메서드가 표시됨. 예시 결과에는 wrong_order, inverted_condition, off_by_one, unhandled_null 결함이 포함됨.
  • 예시 실행 결과는 5개 파일에서 문제 20건이 발견됐으며, 모두 실패 처리됨을 표시함.
  • perch issues는 심각도가 높은 문제부터 표시하고, perch issues <id>는 지정한 문제 하나를 보여줌.
  • perch check <id>는 수정했다고 판단한 뒤 해당 문제를 다시 확인하며, 확인 결과를 기록하지 않음.

에이전트 스킬

  • perch setup claude-code는 .claude/skills/perch/SKILL.md에 지침을 설치함.
  • perch setup codex는 .codex/skills/perch/SKILL.md에 지침을 설치함.
  • perch setup pi는 .pi/skills/perch/SKILL.md에 지침을 설치함.
  • perch setup cursor는 .cursor/rules/perch.mdc에 지침을 설치함.

의미 기반 린팅

  • perch.yaml에 규칙을 추가해 Perch의 린팅을 확장할 수 있음.
  • 규칙은 이름, 적용 대상 경로 패턴(where), 검사 단위(each), 충족해야 할 조건(ensure)으로 구성됨. 예시 규칙은 src/**/*.ts의 각 메서드에서 비밀번호와 액세스 토큰을 로그에 남기지 않도록 요구함.

모델

  • 기본 설정에서 Perch Cloud는 질문에 답하기 적합한 모델로 질문을 전달함.
  • 특정 의사결정 모델을 사용하려면 엔드포인트, API 키, 모델 ID를 지정함. 예시 설정은 PERCH_BASE_URL=https://api.typesafe.ai/v1/systemone, PERCH_API_KEY, PERCH_MODEL_ID=jev-latest임.
  • 제공된 모델과 엔드포인트는 다음과 같음.
  • Jev: https://api.typesafe.ai/v1/systemone, 모델 ID jev-latest
  • Liquid AI d1: https://api.liquid.ai/decisions/v1/systemone, 모델 ID d1:free
  • DiffusionGemma Jev on Beam: https://app.beam.cloud/v1/models/jev/diffusiongemma/invoke, 모델 ID jev/diffusiongemma
  • SemiF on Beam: https://app.beam.cloud/v1/models/jev/semif/invoke, 모델 ID jev/semif
  • System One 형식을 지원하는 엔드포인트라면 모두 사용할 수 있음. 모델마다 요청 한 번에 처리하는 질문 수가 다르며, 모델이 해당 수를 명시하지 않으면 PERCH_MAX_QUESTIONS를 설정함.
  • 모델 비교 정보는 벤치마크에서 확인할 수 있음.

문서

  • 시작하기: 설치, 로그인, 첫 검사
  • 문제 읽기: 문제 목록, 필터, 중요하지 않은 문제 닫기
  • 의미 기반 린팅: where, each, sees, min, gate 및 전체 문법
  • 변경 사항 확인: 진행 중인 작업에 perch check 사용
  • CI에서 Perch 사용: 빌드에서 실패 조건으로 설정할 수 있는 항목과 설정할 수 없는 항목
  • 명령어 참조: 모든 명령어와 플래그, 종료 코드의 의미
  • 검사 내부 동작: 그래프 탐색, 질문, 확률을 순위로 변환하는 과정

Perch 파일

  • .perch/에는 생성된 검사 결과와 캐시 파일이 저장되며, 아래의 커밋 대상 파일과 함께 사용됨. --out <directory>로 다른 결과 저장 위치를 지정할 수 있음.
  • .perch/rules/에는 .yaml 및 .yml 파일로 나눈 사용자 지정 규칙이 저장되며, 이 파일은 커밋 대상임.
  • .perch/closed.jsonl에는 무시 처리한 발견 항목과 사유가 저장되며, 이 파일은 커밋 대상임.
  • perch.yaml에는 사용자 지정 규칙이 저장되며, perch rules add, edit, remove 명령으로 갱신됨.
  • .claude/, .codex/, .pi/, .cursor/에는 perch setup <assistant>로 선택한 어시스턴트에 설치한 지침이 저장됨.

개발

  • npm run check는 린트, 타입 검사, 테스트를 실행함.
  • npm run build는 src/cli.js를 dist/cli.mjs로 묶음.
  • 체크아웃한 소스에서 Perch를 설치하려면 npm install && npm run build && npm link를 실행함.