18. AX·AI 생산성 지표 설계 (제안)
상태: 설계 문서 (proposal) — metrics v14.2.0 기준. 여기의 지표 ID는 예약이며, 구현 시 11-metrics-versioning.md의 캘리브레이션 우선 원칙(신규 신호는 info·감점 0으로 도입 → 코퍼스/라벨 검증 → 등급 승격)을 따른다.
1. 문제 정의 — "AI 생산성"을 정적 도구가 정직하게 잴 수 있는 부분
AI 코딩 도구의 생산성 논의는 세 층으로 나뉜다.
| 층 | 예 | JAM이 잴 수 있는가 |
|---|---|---|
| 산출 속도 | 시간당 PR/LOC, 수용률 | ✗ — 조직 텔레메트리 영역 (DORA/SPACE) |
| 산출물 품질·수명 | 생성 코드의 결함 밀도, 재작업률, 클론 증가 | ◐ — JAM의 본령. 트리 + git 이력으로 측정 가능 |
| 환경 준비도 (AX) | 에이전트가 안전하게 일할 수 있는 저장소인가 | ✔ — 파일 존재/구조 검사로 오프라인 측정 가능 |
근거가 되는 외부 실증:
- GitClear (2024, 2025), *AI Copilot Code Quality* — AI 보급 후 copy/paste·클론 코드 비율 급증, 2주 내 재수정(churn)되는 코드 비율 상승. "빠른 생성 ≠ 생산성"의 대표 실증.
- Google DORA (2024, *Accelerate State of DevOps*) — AI 도입 확대가 처리량을 올리지만 전달 안정성(change failure)을 낮추는 상관 보고.
- Peng et al. (2023, arXiv:2302.06590) — Copilot 과제 완료 55% 단축(속도 층의 실증, JAM 범위 밖임을 명시하는 근거).
- Forsgren et al. (2021, *The SPACE of Developer Productivity*, ACM Queue) — 생산성은 단일 지표로 환원 불가; 활동량 지표 단독 사용 금지. JAM이 속도 층을 다루지 않는 이론적 근거.
- 기존 JAM 바이브코딩 tell 계열(HYG-08..13)과 v14.2.0 캘리브레이션 신호(CPLX-06 churn, HYG-14)는 이 문서의 기반 인프라다.
2. 축 A — AI 산출물 품질 tell (트리만으로 측정, lite 후보)
| 예약 ID | 이름 | 계산(오프라인) | 근거 | 정밀도 위험 |
|---|---|---|---|---|
| HYG-15 | 잔여 플레이스홀더 (Placeholder Artifact) | your_api_key, TODO: implement, example.com 하드코딩, lorem ipsum, <placeholder>, "as an AI" 등 생성 템플릿 흔적 토큰. 비테스트 파일 대상 | 생성 흔적은 SATD(Potdar 2014)의 AI 변형. SEC-01(비밀)과 상보 | 낮음 — 토큰 리스트 보수 유지 시 |
| HYG-16 | 중복 설명 주석 (Redundant Comment) | 주석 토큰 집합이 바로 다음 문장의 식별자·키워드와 고도 중첩(예: Jaccard ≥ 0.7)하는 "코드를 그대로 읽어주는" 주석 밀도. LLM 산출물의 대표 스타일 | Coleman(1994) 주석 밀도의 질적 보완; GitClear 2025의 주석 인플레이션 관측 | 중간 — 언어별 불용어 처리 필요 |
| HYG-17 | 미해석 내부 import (Broken Internal Import) | 프로젝트 내부 경로로 보이는 import가 실재 파일/모듈로 해석 안 됨 (ARCH 그래프 해석기 재사용). 환각 API의 코드 레벨 관측치 | 환각 참조는 컴파일 언어에선 CI가 잡지만 Python/JS 동적 로딩·경로 alias에선 잔존. CWE-1078 계열 | 중간 — tsconfig paths 미구현(roadmap M2-4)과 충돌, 선행 필요 |
| HYG-18 | 동어반복 테스트 (Tautological Test) | assert True, expect(true).toBe(true), assertEquals(x, x) 등 항상 참인 단언. HYG-13(단언 부재)의 쌍 — "단언은 있으나 무의미" | van Deursen (2001); Martinez et al. (2017, Defects4J 분석)의 trivial test | 낮음 |
| SIZE-05 | 사변적 일반화 (Speculative Generality) | 내부에서 한 번도 호출되지 않는 public/exported 심볼 비율(HYG-02 dead-code의 공개 심볼 버전, 라이브러리 profile 제외) | Fowler (1999, *Refactoring*)의 Speculative Generality 냄새; AI의 과잉 API 생성 경향 | 높음 — 라이브러리/플러그인 오탐. profile=application 한정 필수 |
3. 축 B — AI 시대의 코드 수명·재작업 (git 이력, CPLX-06 배선 재사용, opt-in)
모두 churn.enabled opt-in + info 캘리브레이션으로 도입한다. 이력은 환경 의존적이므로 점수 산입은 장기 검토 대상이다.
| 예약 ID | 이름 | 계산 | 근거 |
|---|---|---|---|
| CHURN-01 | 단명 코드율 (Code Half-Life) | 추가 후 N일(기본 14일) 내 재수정·삭제된 라인 비율 (git log --numstat 시계열). GitClear가 AI 도입 후 상승을 실증한 바로 그 지표 | GitClear 2024/2025; Tornhill (2015) |
| CHURN-02 | AI 귀속 커밋 비율 | Co-Authored-By:.*(Claude|Copilot|ChatGPT|Gemini|...), Generated with trailer가 있는 커밋/라인 비율. 품질 판단이 아니라 분모 제공용 — CHURN-01·DUP를 AI/비-AI 코호트로 나눠 비교 가능하게 함 | SPACE(2021)의 다차원 원칙 — 귀속 없는 생산성 주장 불가 |
| CHURN-03 | 테스트 동반 변경율 | 프로덕션 코드를 바꾼 커밋 중 테스트 파일을 함께 바꾼 비율. AI 대량 생성 커밋에서 급락하는 패턴 | Zaidman et al. (2011, EMSE, test co-evolution) |
| CHURN-04 | 거대 일괄 커밋 | 단일 커밋 추가 라인 상위 outlier(평균+2σ, 절대 하한 병용). "AI 덤프" 패턴의 프로세스 신호 | Nagappan & Ball (2005); 소규모 변경의 결함률 우위는 Purushothaman & Perry (2005, IEEE TSE) |
4. 축 C — AX (Agent Experience): 에이전트 친화 저장소 준비도
에이전트가 안전하게, 검증 가능하게 일할 수 있는 저장소인지의 오프라인 점검. 신규 카테고리 AX (도입 시 가중치 0 → 캘리브레이션 후 승격 결정)로 예약한다.
| 예약 ID | 이름 | 계산(파일 존재·구조) | 근거 |
|---|---|---|---|
| AX-01 | 에이전트 지침 존재·품질 | AGENTS.md/CLAUDE.md/.cursorrules 등 존재 + 최소 품질(빌드·테스트 명령 언급, 길이 하한) | agents.md 산업 관행(OpenAI/Google/Anthropic 공동 채택), Anthropic 에이전트 운용 가이드 |
| AX-02 | 기계 검증 게이트 | CI 워크플로 + lint/formatter 설정 + 테스트 러너 설정의 존재. 에이전트 산출물이 자동 검증되는 안전망 | DORA 2024 — AI 성과는 기존 엔지니어링 기반 위에서만 실현; NIST SSDF PW.7/PW.8 |
| AX-03 | 재현 가능 환경 | lockfile(HYG-14 재사용) + 버전 파일(.tool-versions, go.mod toolchain 등) + 컨테이너/devcontainer 정의 | SLSA/재현 빌드; HYG-14 근거 공유 |
| AX-04 | 검증 루프 속도 프록시 | 테스트 파일 비율(HYG-06 재사용) + 문서화된 단일 명령 빌드·테스트 진입점(Makefile/justfile/package.json scripts) | 에이전트 루프의 병목은 검증 회전율 — SPACE의 flow 차원 |
AX는 "코드 품질"이 아니라 "이 저장소에서 AI 협업이 검증 가능한가"를 재므로, lite 합성 점수와 분리된 별도 리포트 섹션(예: AX readiness: 3/4)으로 시작하는 것이 정직하다.
5. 도입 로드맵 (제안)
- P1 — ✅ 구현됨 (metrics v14.3.0): HYG-15 플레이스홀더, HYG-18 동어반복 테스트 — info 캘리브레이션으로 도입 완료(02-metrics-catalog.md 참조).
- P2 — ✅ 구현됨 (metrics v14.4.0): CHURN-01 단명 코드율, CHURN-02 AI 귀속 커밋 비율 — CPLX-06 배선 재사용, opt-in·info로 도입 완료.
- P3 — ✅ 구현됨 (CLI v0.45.0): AX-01..04 —
jam-report.md의 "AX Readiness: N/4 (점수 미산입)" 섹션과jam-result.json의 additiveax필드로 도입 완료(internal/analyze/ax). metrics spec은 변경 없음(지표가 아닌 리포트 데이터). - P4 — ✅ 구현됨 (metrics v14.5.0): HYG-16(요약 보고), HYG-17(상대 import 한정으로 tsconfig paths 선행 과제 우회), SIZE-05(
profile: applicationopt-in), CHURN-03/04 — 모두 info 캘리브레이션. - 승격 관문: 각 신호는 16종 코퍼스 + 실프로젝트에서 오탐률 측정 후에만 warning 이상·가중치 부여. 근거 인용 없는 등급 승격 금지(AGENTS.md 원칙).
6. 명시적 비목표
- 시간당 산출량·PR 처리량·수용률 등 속도 지표는 다루지 않는다 — 정적 도구가 재면 왜곡 유인(LOC 부풀리기)만 만든다 (SPACE의 활동량 지표 경고).
- 특정 AI 도구 벤더 판별·차단은 목표가 아니다. CHURN-02 귀속은 trailer 표준 관행만 읽는다.
- 코드가 "AI 생성인지" 확률 추정(AI 탐지기)은 하지 않는다 — 오탐 시 해악이 크고 근거 표준이 없다.