CcLint

AI 커맨드를 위한 Linter — 모호성을 검출하고 결정론성을 높인다.

왜 CcLint인가?

AI 코딩 에이전트에게 자연어로 지시를 내릴 때, 같은 커맨드를 줘도 매번 다른 결과가 나온다.

f("커밋 메시지 잘 작성해줘") → 실행 1: 영어로 작성
f("커밋 메시지 잘 작성해줘") → 실행 2: 한국어로 작성
f("커밋 메시지 잘 작성해줘") → 실행 3: 본문 없이 제목만

같은 입력에 다른 출력 — 이러면 이 위에 더 큰 시스템을 안정적으로 쌓을 수 없다.

CcLint는 AI 커맨드의 모호성을 검출하고 결정론성(Determinism)을 높인다. ESLint가 JS 코드를, Black이 Python 코드를 정리하듯이.

설치

npm (권장)

npm install -g @seunggabi/cclint

npx (설치 없이 바로 사용)

npx @seunggabi/cclint "커밋 메시지 잘 작성해줘"

curl

curl -fsSL https://raw.githubusercontent.com/seunggabi/cclint/main/install.sh | bash

빠른 시작

# 단일 커맨드 검증
cclint "커밋 메시지 잘 작성해줘"

# 자동 수정 제안
cclint --fix "테스트 코드 작성해줘"

# 현재 디렉토리 .md 파일 전체 lint (CLAUDE.md, AGENTS.md 등)
cclint .

# 특정 파일 lint
cclint CLAUDE.md

# 파일 감시 모드 — 저장 시 자동 re-lint
cclint --watch .

# 인터랙티브 모드 — 문제마다 선택지 제공
cclint --interactive "모든 파일 정리해줘"

# Claude AI 개선안 출력
cclint --suggest-print "커밋 메시지 잘 작성해줘"

# 프로젝트 초기화 (.cclintrc 생성 + pre-commit hook)
cclint init

동작 예시

기본 lint

$ cclint "커밋 메시지 잘 작성해줘"

────────────────────────────────────────────────────────────
CcLint v0.3.0
────────────────────────────────────────────────────────────
입력: "커밋 메시지 잘 작성해줘"

❌  "잘" — 정량 기준 없음  (ambiguous-qualifier)
     → "잘"는 해석이 실행마다 달라질 수 있습니다.
⚠️   language 미지정  (missing-constraint)
⚠️   format 미지정  (missing-constraint)
⚠️   max-length 미지정  (missing-constraint)

Determinism Score: 4/10 🔴 — 매번 다른 결과

--fix 자동 수정

$ cclint --fix "커밋 메시지 잘 작성해줘"

# ... lint 결과 ...

자동 수정 제안 (--fix)
────────────────────────────────────────────────────────────
→ commit:
    language: ko
    format: conventional-commits
    max-length: '72'

수정 후 예상 Score: 10/10

--interactive 선택지 모드

$ cclint --interactive "커밋 메시지 잘 작성해줘"

⚠️ language 미지정
  1) ko (한국어)
  2) en (영어)
  3) Claude에게 제안 받기 (claude -p)
  4) 직접 입력
선택 (1-4): 1

.md 파일 전체 lint

$ cclint .

CcLint v0.3.0
디렉토리: /your/project
대상 파일: 3개 (*.md)

CLAUDE.md
  L3: ❌ ambiguous-qualifier: "깔끔하게" — 정량 기준 없음
  L7: ❌ conflicting-rules: "간결하게" vs "상세하게" — 규칙 충돌
  L12: ⚠️  missing-constraint: format 미지정

✖ 2 error, 1 warning (3개 파일 검사)

Determinism Score

| 점수 | 의미 | 상태 | |------|------|------| | 9-10 | 거의 순수 함수 수준 | 🟢 매번 같은 결과 | | 7-8 | 대부분 예측 가능 | 🟡 minor 차이만 | | 5-6 | 결과가 상당히 달라질 수 있음 | 🟠 | | 3-4 | 매번 다른 결과 | 🔴 | | 1-2 | 랜덤에 가까움 | ⛔ |

Score는 확률 기반 불확실성 전파 모델로 계산됩니다:

P_deterministic = Π(1 - u_i)
Score = 10 × P_deterministic

각 규칙 위반은 독립 사건으로, 위반이 누적될수록 Score가 급격히 하락합니다.

규칙 (Rules)

| Rule ID | 설명 | 기본값 | |---------|------|--------| | ambiguous-qualifier | "잘", "적절히" 등 모호한 수식어 | error | | missing-constraint | 도메인별 필수 제약 조건 누락 | warn | | conflicting-rules | "간결하게" vs "상세하게" 등 충돌 | error | | implicit-assumption | "기존처럼", "알아서" 등 암묵적 전제 | warn | | unbounded-scope | "모든 파일" 등 범위 무제한 | warn | | no-subjective-criterion | "예쁘게", "우아하게" 등 주관적 기준 | warn | | vague-quantifier | "많은", "빠른" 등 모호한 수량 표현 | warn | | no-rollback-plan | 삭제/배포 작업에 롤백 계획 없음 | warn |

설정 (.cclintrc)

프로젝트 루트에 .cclintrc 파일을 만들면 규칙을 커스텀할 수 있습니다.

rules:
  ambiguous-qualifier: error     # error | warn | off
  missing-constraint: warn
  conflicting-rules: error
  implicit-assumption: warn
  unbounded-scope: warn
  no-subjective-criterion: warn
  vague-quantifier: warn
  no-rollback-plan: warn

custom:
  language: ko                   # 이 언어는 missing-constraint에서 제외
  domains:
    deploy:
      required: [environment, strategy, rollback-plan]

우선순위: ./cclintrc > ./.cclintrc > ~/.cclintrc

Claude AI 통합

--suggest-print 플래그로 Claude에게 개선안을 요청하는 명령어를 출력합니다:

$ cclint --suggest-print "테스트 코드 작성해줘"

claude -p '다음 AI 커맨드에서 아래 문제들이 감지되었습니다.
원본 커맨드: "테스트 코드 작성해줘"
감지된 문제:
- framework 미지정 (missing-constraint)
- coverage 미지정 (missing-constraint)
...'

claude CLI가 설치된 경우 --suggest로 직접 실행할 수도 있습니다.

CLI 옵션

cclint [target] [options]

Arguments:
  target          커맨드 문자열, 파일 경로, 또는 디렉토리 (기본: 현재 디렉토리)

Options:
  -f, --fix           자동 수정 제안 생성
  -i, --interactive   문제마다 선택지를 제공하는 인터랙티브 모드
  -s, --suggest       claude -p 로 AI 개선안 실행
  --suggest-print     claude -p 명령어 출력 (실행 안 함)
  -w, --watch         파일 변경 감시 후 자동 re-lint
  --json              JSON 형식으로 출력
  --ext <exts>        lint 대상 확장자 (기본: md)
  -V, --version       버전 출력
  -h, --help          도움말

Commands:
  init [--force]      .cclintrc 생성 + pre-commit hook 설치

왜 중요한가

AI 에이전트가 파이프라인의 한 단계로 쓰이는 시대에, 각 단계의 커맨드가 불순 함수이면 오류가 곱셈으로 전파됩니다:

불확실성 0.7 × 0.7 × 0.7 = 0.343

커맨드의 결정론성을 높이는 것은 AI 기반 소프트웨어 엔지니어링의 신뢰성 기반을 만드는 일입니다.

Contributing

CONTRIBUTING.md를 참고하세요.

git clone https://github.com/seunggabi/cclint.git
cd cclint
npm install
npm run build

License

MIT © seunggabi