hyhmrright/brooks-lint

Portable AI code quality reviews for Codex, Cursor, Copilot and other coding agents: six Agent Skills for architecture, technical debt, tests and remediation.

개요

brooks-lint는 다양한 에이전트 플랫폼(Claude, Gemini, Codex, Cursor 등)에서 AI 기반 코드 리뷰 '스킬'을 실행할 수 있는 도구입니다. 구문이나 스타일을 린트하지 않습니다. 대신 저자가 12권의 고전 소프트웨어 공학 서적(예: 인월신화, 클린 아키텍처, 리팩토링)에서 추출한 6가지 부패 위험 차원을 기준으로 프로덕션 코드와 테스트 스위트를 평가합니다. 각 위험에 대해 구조화된 결과를 생성합니다:

증상 → 원인 → 결과 → 해결책

각 결과는 원본 책에 인용되고 심각도(🔴 치명적, 🟡 경고, 🟢 제안)로 표시되며 전체 건강 점수(0-100)에 기여합니다. 이 도구는 또한 아키텍처 다이어그램(Mermaid), 부채 순위 테이블, 안전한 수정을 자동으로 적용하는 '스윕' 모드를 생성할 수 있습니다.

이 패키지는 Agent-Skills로 배포되며 작은 설치 스크립트를 통해 많은 AI 어시스턴트 플랫폼에 설치할 수 있습니다. 설치 후 6개의 슬래시 명령(/brooks-review, /brooks-audit 등)을 호출하거나 어시스턴트에게 "이 PR을 리뷰해줘"라고 요청할 수 있습니다.

주요 기능

기능	설명	중요성
6가지 부패 위험 차원	인지 과부하, 변경 전파, 지식 중복, 우발적 복잡성, 의존성 혼란, 도메인 모델 왜곡(추가로 6가지 테스트 스위트 위험)	라인 수 지표를 넘어 원칙적이고 책에 근거한 코드 건강 관점 제공
구조화된 결과	각 문제는 증상 → 원인 → 결과 → 해결책으로 보고되며 고전 책에 대한 인용 포함	개발자와 리뷰어에게 피드백을 추적 가능하고 실행 가능하게 만듦
건강 점수(0-100)	구성 가능한 엄격도 프리셋(엄격, 균형, 레거시 친화적)을 사용하여 심각도 수를 집계	PR, 릴리스 또는 전체 저장소에 대한 빠르고 비교 가능한 건강 지표 제공
아키텍처 감사	Mermaid 의존성 그래프 생성, 순환 및 Conway의 법칙 불일치 강조	린터가 놓치는 높은 수준의 설계 드리프트를 식별하는 데 도움
기술 부채 로드맵	결과를 고통 × 확산으로 순위를 매기고 중요 / 예정 / 모니터링 계층으로 그룹화	팀에 점진적 개선을 위한 구체적인 계획 제공
테스트 스위트 감사	테스트 모호성, 취약성, 중복, 목 남용, 커버리지 환상, 아키텍처 불일치 확인	동일한 위험 모델을 테스트 코드베이스로 확장
자동 수정 / 스윕 모드	안전한 단일 파일 수정을 자동으로 적용; 더 큰 변경은 수동 검토를 위해 기록	낮은 위험 문제에 대한 수동 작업 감소
다중 플랫폼 Agent-Skills	단일 스크립트로 Claude, Gemini, Codex, Cursor, OpenCode, Windsurf, IBM Bob 등에 설치 가능	선호하는 AI 어시스턴트에 관계없이 팀이 동일한 리뷰 로직을 사용할 수 있음
제로 구성 기본값	즉시 사용 가능; 선택적 `.brooks-lint.yaml`로 사용자 정의 엄격도, 비활성화된 위험, 무시 패턴 설정	채택 장벽이 낮음

작동 방식(높은 수준 흐름)

설치 – 제공된 install.sh 스크립트를 대상 플랫폼 이름(예: bash scripts/install.sh codex)으로 실행합니다. 스크립트는 스킬 파일을 플랫폼의 스킬 디렉토리에 복사합니다.
호출 – 채팅/IDE에서 슬래시 명령(/brooks-review)을 실행하거나 어시스턴트에게 PR을 리뷰하도록 요청합니다.
모델 호출 – 스킬은 관련 코드(차이, 전체 파일 또는 의존성 그래프)를 6가지 위험 질문과 인용 스타일을 인코딩한 프롬프트와 함께 기본 LLM(Claude, Gemini 등)에 보냅니다.
파싱 – LLM은 Markdown 보고서를 반환합니다. brooks-lint의 파서는 각 결과를 추출하고 표준 위험 코드에 매핑하며 심각도 수를 계산합니다.
점수 및 출력 – 도구는 수를 건강 점수로 집계하고 선택적으로 Mermaid 그래프를 렌더링하며 구조화된 보고서를 사용자에게 반환합니다.
선택적 스윕 – /brooks-sweep 모드에서 도구는 자동화해도 안전한 '해결책' 단계를 적용하려고 시도한 다음 '수정 로그'와 업데이트된 점수를 보고합니다.

일반적인 사용 사례

시나리오	명령	얻는 것
풀 리퀘스트 리뷰	`/brooks-review`	변경된 파일에 대한 부패 위험 결과 목록, 각각 책 인용 및 수정 조언, PR에 대한 건강 점수 포함.
아키텍처 건전성 검사	`/brooks-audit`	Mermaid 의존성 그래프, 순환 의존성 경고, 모듈 결합 및 의존성 방향과 관련된 위험 결과.
기술 부채 분류	`/brooks-debt`	순위가 매겨진 부채 항목, 고통 × 확산 점수, 로드맵(중요 / 예정 / 모니터링).
테스트 스위트 건강	`/brooks-test`	테스트 코드에 특정한 결과(모호성, 취약성, 목 남용 등) 및 테스트 리팩토링 제안.
빠른 건강 스냅샷	`/brooks-health`	모든 차원에 걸친 복합 건강 점수 – 릴리스 전이나 온보딩에 유용.
자동 정리	`/brooks-sweep`	안전한 수정을 자동 적용하고 수정 로그를 생성하며 건강 점수의 변화를 표시.

설치 빠른 시작

# Codex CLI 플랫폼 예시
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh \
  | bash -s -- codex

스크립트는 스킬 파일을 적절한 ~/.codex/skills(또는 동등한) 폴더에 복사하고 6개의 슬래시 명령을 등록합니다. Claude Code, Gemini CLI 또는 다른 나열된 에이전트의 경우 codex를 플랫폼 이름으로 바꿉니다.

Claude Code용 수동 설치를 선호하는 경우:

mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/

설치 후 어시스턴트에게 "이 PR을 리뷰해줘"라고 요청하거나 슬래시 명령 중 하나를 실행합니다.

구성(선택 사항)

저장소 루트에 .brooks-lint.yaml을 생성하여 동작을 조정합니다:

version: 1
strictness: balanced   # strict | balanced (기본값) | legacy-friendly
disable:
  - T5                 # 커버리지 지표 검사 건너뛰기
severity:
  R1: suggestion       # 인지 과부하 결과 다운그레이드
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

strictness는 건강 점수 계산 방식을 변경합니다.
disable은 특정 위험 범주를 끌 수 있습니다.
severity는 특정 프로젝트에 대한 위험을 다시 라벨링할 수 있습니다.
ignore는 glob 패턴을 사용하여 생성되거나 공급업체 파일을 제외합니다.

제한 사항 및 미해결 문제

제한 사항	세부 사항
LLM 품질에 대한 의존성	결과의 정확성은 기본 모델(Claude, Gemini 등)에 달려 있습니다. 저장소는 결정적 파싱 벤치마크를 제공하지만 결과의 의미적 정확성은 여전히 모델에 의존합니다.
플랫폼 검증	유지 관리자는 Claude Code 테스트가 더 이상 수행되지 않는다고 언급합니다. Codex 관련 기능만 적극적으로 검증됩니다. 다른 플랫폼에 대한 커뮤니티 테스트가 권장됩니다.
언어에 구애받지 않지만 언어를 인식하지 못함	brooks-lint는 코드를 텍스트로 취급하므로 모든 언어에서 작동하지만 언어별 AST 정보를 활용할 수 없으므로 언어를 인식하는 정적 분석기보다 일부 패턴을 놓칠 수 있습니다.
벤치마크 수치는 예시용	README는 벤치마크 테이블이 "예시용"이며 실제 평가 수치가 다를 수 있다고 명시합니다.
기존 린터를 대체하지 않음	ESLint, Pylint 또는 정적 분석 스위트와 같은 도구를 보완하기 위한 것이지 대체하기 위한 것이 아닙니다.

누가 혜택을 받을 수 있나요?

엔지니어링 관리자는 여러 저장소에 걸친 높은 수준의 건강 지표를 찾고 있습니다.
Dev-ops / CI 파이프라인은 병합 전에 AI 기반 품질 게이트를 원합니다.
개별 개발자는 원본 텍스트를 읽지 않고도 실행 가능하고 책에 근거한 리뷰 코멘트를 원합니다.
여러 AI 어시스턴트를 사용하는 팀 – 동일한 스킬이 Claude, Gemini, Codex, Cursor 등에서 작동하여 일관된 피드백을 제공합니다.

결론

brooks-lint는 고전 소프트웨어 공학 지혜와 현대 LLM 기반 코드 리뷰를 연결합니다. 6가지 명확하게 정의된 부패 위험에 걸쳐 구조화되고 인용이 풍부한 결과를 제공하고 복합 건강 점수를 생성하며 안전한 수정을 자동 적용할 수도 있습니다. 기존 린터를 대체하지는 않지만 많은 AI 지원 리뷰어가 놓치는 아키텍처 및 설계 수준의 통찰력을 추가합니다.

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다. 외부 가정은 추가되지 않았습니다.