AI가 건드린 코드, 신뢰 등급으로 막는 오픈소스 도구 ‘tears’

AI 코딩을 막는 게 아니라, 위험한 코드 경로를 막는 도구

• tears는 저장소 안의 모든 파일을 같은 기준으로 리뷰하지 말자는 문제의식에서 출발함

  • 대시보드, 스크립트, 프로토타입은 빠르게 바꿔도 되지만 인증, 결제, 핵심 비즈니스 로직은 훨씬 조심해야 한다는 얘기
  • 문제는 이 코드들이 같은 저장소에 살다 보면, 검토 안 된 모듈이 민감한 코드로 슬쩍 import될 수 있다는 점임

• 해결 방식은 파일마다 @tear 헤더로 신뢰 등급을 붙이는 것

  • @tear: 0은 보안 중요 코드나 도메인 오너가 깊게 리뷰한 코드
  • @tear: 1은 사람이 줄 단위로 리뷰한 코드
  • @tear: 2는 데이터 유출, 네트워크 호출, 뻔한 보안 문제 정도를 훑어본 코드
  • @tear: 3은 이른바 바이브 코딩(vibe coding)으로 만든 코드

• import 규칙은 꽤 직관적임. 같은 등급이거나 더 신뢰 높은 코드만 가져올 수 있음
  • 0 등급 파일은 0만 import 가능
  • 1 등급 파일은 0, 1을 import 가능
  • 2 등급 파일은 0, 1, 2를 import 가능
  • 3 등급 파일은 사실상 전부 import 가능

AI가 파일을 건드리면 등급이 내려감

• tears에서 제일 재밌는 장치는 “diff에 남는 신뢰 등급 변경”임

  • AI 에이전트가 파일을 수정하면 훅이 해당 파일의 헤더를 자동으로 낮은 신뢰 등급으로 바꿈
  • 사람이 리뷰한 뒤 등급을 다시 올릴 수 있음
  • 만약 diff에서 그 변경을 보고 되돌렸다면, 적어도 그 코드를 봤다는 뜻이 됨

• 지원하는 에이전트 훅은 Claude Code, Codex, OpenCode 쪽으로 준비돼 있음

  • Claude Code는 Edit, Write, MultiEdit 이후 stdin JSON payload에서 수정 파일 경로를 읽음
  • Codex는 현재 apply_patch 편집만 처리하고, PostToolUse payload에서 파일 경로를 뽑아 공통 훅 로직에 넘김
  • OpenCode 플러그인은 edit, write, apply_patch 호출을 감지해 uv run python -m tears.hook FILE을 실행함

• 단, 아직 한계도 분명함

  • Codex 훅은 repo-local 방식이고 패키지 설치형이 아님
  • Codex는 사용자가 시작 시 훅 활성화에 동의해야 동작함
  • OpenCode 플러그인도 아직 repo-local 방식임

도입 방식은 부드러운 시험 모드부터 가능

• 바로 전체 저장소를 엄격하게 막는 구조는 아님. soft trial mode가 있음

  • default_tear = 1을 쓰면 기존에 헤더가 없는 파일을 일단 리뷰된 코드처럼 취급함
  • 이후 준비가 되면 default_tear를 3으로 바꾸거나 제거해서 더 엄격한 모드로 갈 수 있음
  • --missing-only 옵션은 기존에 의도적으로 붙인 등급은 건드리지 않고, 헤더 없는 파일만 태깅함

• 설정은 .tears.toml에서 읽고, 꽤 많은 조절 포인트가 있음

  • max_tear는 최고 등급 숫자이며 기본값은 3
  • missing_header는 헤더 없는 파일을 경고로 볼지 에러로 볼지 정함
  • languages는 스캔할 언어 목록이고 기본값은 python
  • directory_requirements로 민감한 경로가 특정 신뢰 등급 이하로 내려가지 못하게 할 수 있음
  • artificial_tears로 특정 파일에 별도 import 예산을 줄 수도 있음

• 현재 스캐너는 Python이 기본이고, 다른 언어는 설정으로 켜는 방식임

  • 지원 목록에는 C, C++, C#, Dart, Go, Java, JavaScript, Kotlin, PHP, Ruby, Rust, TypeScript가 있음
  • 다만 import resolution은 로컬 기준의 보수적 분석이고, 패키지 alias나 빌드 메타데이터는 아직 모델링하지 않음
  • tears PATH에서 PATH는 하위 필터가 아니라 설정과 스캔의 루트로 취급됨

sequenceDiagram
    participant 에이전트 as AI 에이전트
    participant 파일 as 소스 파일
    participant 훅 as tears 훅
    participant 리뷰어 as 사람 리뷰어
    participant 씨아이 as CI
    에이전트->>파일: 코드 수정
    훅->>파일: @tear 등급 자동 하향
    리뷰어->>파일: diff 확인 후 등급 복원
    씨아이->>파일: import 신뢰 규칙 검사
    씨아이-->>리뷰어: 위반 시 병합 차단

기술 맥락

• tears가 고른 핵심 선택은 코드 신뢰도를 외부 시스템이 아니라 파일 헤더에 넣는 방식이에요. 별도 대시보드나 스프레드시트는 시간이 지나면 실제 코드와 어긋나기 쉬운데, 헤더는 diff와 함께 움직이니까 리뷰 과정에서 자연스럽게 보이거든요.

• import 방향을 신뢰 등급으로 제한하는 것도 중요한 선택이에요. 보안상 위험한 건 낮은 품질의 코드 자체보다, 그 코드가 인증이나 결제 같은 핵심 경로로 흘러 들어오는 상황이기 때문이에요. 그래서 @tear: 0 코드는 같은 0 등급만 import하게 막는 구조가 나와요.

• AI 에이전트 훅은 “누가 코드를 썼는가”보다 “사람이 다시 읽었는가”를 남기려는 장치예요. 에이전트가 건드리면 등급을 낮추고, 사람이 diff에서 그 변경을 되돌리면 검토했다는 흔적이 남아요. 리뷰 여부를 말로 주장하는 대신 변경 내역으로 확인하게 만드는 셈이에요.

• 아직 구현은 현실적인 제약이 있어요. Python이 기본 스캔 대상이고, 다른 언어는 켤 수 있지만 import 해석은 로컬 기준의 보수적 방식이에요. 패키지 alias나 빌드 시스템까지 정확히 따라가는 단계는 아니라서, 대규모 다언어 저장소에서는 trial mode로 먼저 돌려보는 게 맞아요.