01. 비전과 범위
1. 문제 정의
AI Agent(Claude Code, Cursor, Copilot Workspace 등)로 생성된 "바이브코딩" 프로젝트는 동작은 하지만 품질이 천차만별이다. 사람 리뷰어가 일일이 들여다보지 않으면 다음과 같은 문제가 누적된다.
AI 산출물에서 반복 관찰되는 안티패턴
| 안티패턴 | 설명 | 왜 AI에서 자주 발생하는가 |
|---|---|---|
| BIG CLOC 파일 | 하나의 파일이 수천 라인 | AI는 컨텍스트 안에서 "한 파일에 다 넣는" 응답을 선호. 파일 분리는 멀티스텝 작업이라 생략됨 |
| 거대 함수 | 한 함수가 수백 라인, 깊은 중첩 | 요구사항을 한 번에 구현하면서 추출 리팩토링을 하지 않음 |
| 순환 참조 | 모듈/패키지 간 import cycle | 전체 의존 그래프를 보지 못하고 지역적으로 import를 추가 |
| 중복 코드 | 거의 동일한 블록이 여러 파일에 산재 | 기존 코드를 찾기보다 새로 생성하는 것이 빠름. GitClear(2024)는 AI 도입 후 copy/paste 코드 비율이 유의하게 증가했다고 보고 |
| God Object | 모든 책임이 한 클래스/구조체에 집중 | SOLID(특히 SRP) 위반. 점진적 기능 추가가 한 곳에 누적 |
| 보안 무시 | 하드코딩된 시크릿, 인젝션 취약 패턴 | Pearce et al.(2022)은 Copilot 생성 코드의 약 40%가 보안 취약 시나리오에서 취약점을 포함함을 보임 |
| 자원 관리 부재 | close/free/defer 누락, 무한정 고루틴 생성 | 행복 경로(happy path)만 생성하는 경향 |
| 죽은 코드 / 잠재 위험 | 사용되지 않는 함수, 빈 catch, TODO 방치 | 이전 시도의 잔재가 정리되지 않음 |
2. 목표
- 진단: 위 안티패턴들을 정량 메트릭으로 측정하여 프로젝트 건강 점수를 산출한다. 기본 점수는 jam-lite, 선택적 통합 점수는 jam-full이다.
- 근거 제시: 모든 감점은
파일:라인단위로 정확히 지목되어야 한다. "점수가 왜 이런가"에 대해 CSV로 전수 근거를 제공한다. - 연구 기반: 메트릭 정의와 임계값은 가능한 한 학술 연구·산업 표준(McCabe, Halstead, Chidamber-Kemerer, Maintainability Index, SQALE, SonarSource Cognitive Complexity 등)에 근거한다. → 02-metrics-catalog.md
- CI 게이트로 사용 가능: exit code와 임계값 설정으로 "이 점수 미만이면 머지 금지" 같은 자동화에 쓸 수 있다.
3. 비목표 (Non-goals)
- jam-lite는 빌드/실행 기반 분석 안 함: 타입체커 풀가동, 테스트 실행, 동적 분석, 커버리지 측정은 범위 밖. jam-full에서
test-cli와security-cli를 호출해 테스트/커버리지/보안/SCA를 합산한다. - 자동 수정(autofix) 안 함: 진단 도구이지 리팩토링 도구가 아니다.
- jam-lite는 완전한 보안 스캐너 대체 안 함: SAST 전문 도구(Semgrep, CodeQL) 수준의 정밀 taint 분석은 하지 않는다. AI가 자주 만드는 명백한 패턴 위주의 휴리스틱 검출. jam-full은
security-cli결과를 별도 컴포넌트로 합성한다. - 스타일 린트 안 함: 포매팅, 네이밍 컨벤션 등은 기존 린터의 영역.
4. 핵심 제약 조건
| 제약 | 함의 |
|---|---|
| 오프라인, 빌드 불가 | 컴파일러 풀 타입 해석 불가 → AST 수준 분석 + 휴리스틱 심볼 해석. import 해석은 파일 경로/모듈 메타파일 기반 |
| Go 구현, 단일 실행파일 | CGo 의존 없이 크로스 컴파일. Go AST + 내부 경량 프론트엔드 + 일부 임베드 tree-sitter WASM(wazero) → 04-architecture.md |
| Win/Linux/Mac | 경로 처리(filepath), 줄바꿈(CRLF), 인코딩(BOM) 모두 대응 |
| AST/Language Server 사용 OK | Go AST는 기본 사용. LSP 서버 실행은 외부 프로세스 의존이라 기본 비활성(선택적 확장) |
| 정확한 파일:라인 지목 | 모든 finding은 위치 정보 필수. 파일 단위 메트릭도 대표 라인(예: 함수 시작)을 기록 |
5. 사용자 시나리오
시나리오 A — 바이브코딩 결과 검수
$ jam scan ./my-vibe-project
JAM Lite Score: 62/100 (Grade C)
Architecture : 55 (순환 참조 3건, God file 2건)
Complexity : 70 (CCN>15 함수 12개)
Duplication : 48 (중복률 18.2%)
Security : 60 (하드코딩 시크릿 1건, SQL 문자열 결합 4건)
Hygiene : 77
→ jam-report.md, jam-detail.csv 생성됨프로덕션 게이트가 필요하면 full 세트를 사용한다.
$ jam full ./my-vibe-project --out reports/jam
JAM Full Score: 78/100 (Grade C)
jam-lite 62/100
test 84/100
security 92/100
→ jam-full-report.md, jam-full.json 생성됨시나리오 B — CI 게이트
$ jam scan . --fail-under 70
# exit code 1 → 파이프라인 실패시나리오 C — 시계열 추적
주기적으로 스캔하여 점수 변화를 추적(CSV를 누적 비교). jam diff로 이전 jam-detail.csv 대비 새 finding/해결 finding을 확인하고 CI 게이트에 연결.
6. 성공 기준
- 의도적으로 망가뜨린 픽스처 프로젝트에서 모든 안티패턴 카테고리를 검출한다.
- 잘 관리되는 유명 오픈소스(예: 표준적인 Go/TS 프로젝트)는 B 이상을 받는다 — 오탐으로 점수가 무너지지 않아야 한다.
- 10만 LOC 프로젝트를 일반 노트북에서 30초 내 스캔한다.
- 모든 감점 항목이 CSV에서 파일:라인으로 추적 가능하다.