"AI에게 코드리뷰를 시킬 때, 50년치 소프트웨어 공학 고전을 옆에 펴놓고 그 기준대로만 평가하게 만드는 채점 기준표"입니다. ESLint처럼 문법을 잡는 게 아니라, 아키텍처 부패 · 지식 중복 · 도메인 왜곡처럼 몇 달 뒤에 팀을 느리게 만드는 구조적 문제를 잡습니다.
일반 AI에게 "이 코드 리뷰해줘"라고 하면, 똑똑한 선생님이 기분 따라 채점하는 것과 같습니다. 어떤 날은 SQL 인젝션을 잡고, 어떤 날은 네이밍만 지적합니다. brooks-lint는 이 선생님에게 "6개 평가 항목, 항목별 근거 교과서, 감점 기준, 답안 양식"이 적힌 채점 기준표를 쥐여줍니다.
결과: 같은 코드를 넣으면 언제나 같은 구조의 진단서가 나옵니다. 레포의 자체 벤치마크에서 구조화된 진단 통과율 94% vs 맨몸 Claude 16%라는 차이가 이 기준표 하나에서 나옵니다.
AI 리뷰의 문제는 능력이 아니라 재현성입니다. 같은 코드라도 물어볼 때마다 다른 걸 지적하니, CI에 넣거나 팀 표준으로 삼기 어렵습니다. brooks-lint는 모든 발견(finding)을 Symptom → Source → Consequence → Remedy 4단 구조로 강제하고, Source 칸에는 반드시 책 제목과 원칙명을 적게 합니다. "왠지 별로예요"가 아니라 "Fowler의 《Refactoring》이 말하는 Shotgun Surgery입니다. 방치하면 X가 깨지고, Y로 고치세요"가 나옵니다.
리뷰 코멘트에 사람이 반발하는 이유는 "네 의견이잖아"이기 때문입니다. 진단마다 Brooks, Fowler, Evans, Ousterhout의 책과 장(chapter)이 인용되면 논쟁의 성격이 바뀝니다. 신참 개발자에게는 리뷰 자체가 고전 읽기 가이드가 됩니다.
같은 skills/ 디렉토리를 Claude Code 플러그인(.claude-plugin/), OpenAI Codex CLI(.codex-plugin/), Gemini CLI(gemini-extension.json)가 공유합니다. 에이전트 스킬이 특정 벤더 종속이 아니라 이식 가능한 지식 패키지임을 보여주는 사례입니다.
| brooks-lint | ESLint/Pylint | Copilot Review | 맨몸 Claude | |
|---|---|---|---|---|
| 문법·스타일 잡기 | — | 잘함 | 잘함 | 가끔 |
| 구조화된 진단 체인 | 항상 | 없음 | 없음 | 없음 |
| 고전 서적 근거 인용 | 항상 | 없음 | 없음 | 없음 |
| 아키텍처 수준 통찰 | 핵심 기능 | 없음 | 가끔 | 가끔 |
| 도메인 모델 분석 | R6 전담 | 없음 | 없음 | 가끔 |
| 언어 무관 | 모든 언어 | 언어별 설치 | 모든 언어 | 모든 언어 |
README가 명확히 선을 긋습니다. 문법은 ESLint에게, 보안 스캔은 전용 도구에게 맡기고, brooks-lint는 린터가 절대 못 잡는 것 — 아키텍처 표류, 지식 사일로, 도메인 왜곡 — 만 노립니다. 도구의 경계를 스스로 정의하는 것 자체가 좋은 설계 교본입니다.
일반적인 웹 서비스의 3계층(프론트/백/인프라) 대신, 이 레포는 지식 계층 / 통합 계층 / 검증 계층으로 나눠 보는 게 정확합니다.
| 계층 | 구성 요소 | 기술 | 역할 |
|---|---|---|---|
| 지식 (본체) | skills/ 6개 스킬 + _shared/ 6개 공유 문서 | Markdown | 진단 규칙·리포트 템플릿·책 인용 매트릭스. 제품 가치의 90% |
| 통합 | .claude-plugin/, .codex-plugin/, gemini-extension.json | JSON 매니페스트 | 3개 AI CLI 런타임에 동일 스킬 등록 |
| 통합 | hooks/session-start | Bash | 세션 시작 시 경량 안내문 주입 + 숏폼 커맨드 자동 설치 |
| 통합 | commands/brooks-*.md | Markdown(4줄) | /brooks-review 등 슬래시 커맨드 → 스킬 위임 |
| 검증 | evals/evals.json + scripts/run-evals*.mjs | Node.js + @anthropic-ai/sdk | 49개 벤치마크 케이스로 프롬프트 회귀 테스트 |
| 검증 | .github/actions/brooks-lint/ | GitHub Action | CI에서 PR 자동 리뷰 |
| 설정 | .brooks-lint.yaml | YAML | 리스크 비활성/심각도 오버라이드/커스텀 리스크 |
레스토랑에 비유하면 — 요리(코드 분석)는 전부 셰프(LLM)가 합니다. 이 레포가 파는 것은 레시피북(skills/), 셰프를 세 주방에 파견하는 계약서(매니페스트 3종), 그리고 요리 품질을 매주 검사하는 시식단(evals)입니다. 주방 설비는 한 점도 팔지 않습니다.
NEVER suggest fixes before completing risk diagnosis.
EVERY finding must follow: Symptom → Source → Consequence → Remedy.모든 스킬 문서의 최상단에 놓인 두 줄입니다. "결과(Consequence)와 처방(Remedy)이 없는 발견은 발견이 아니라 소음"이라고 못 박습니다. LLM의 출력 품질을 코드가 아니라 헌법 조문 같은 절대 규칙으로 통제하는 방식 — 프롬프트 엔지니어링의 정석입니다.
훅이 세션 시작 때 주입하는 건 150단어 미만의 목차뿐입니다. 수천 줄짜리 진단 규칙 전체는 사용자가 실제로 리뷰를 요청한 순간에만 Skill tool로 로드됩니다. 토큰 비용과 능력 사이의 트레이드오프를 구조로 해결한 모범 사례입니다.
| 모드 | 커맨드 | 하는 일 |
|---|---|---|
| PR Review | /brooks-review | diff 단위 리뷰. 파일 미지정 시 git diff --cached → diff → main...HEAD 순 자동 폴백 |
| Architecture Audit | /brooks-audit | 모듈 의존 그래프(Mermaid, 심각도별 색상) + 순환 의존 + Conway's Law 점검 |
| Tech Debt | /brooks-debt | Pain×Spread 점수로 부채 우선순위 + 상환 로드맵 |
| Test Quality | /brooks-test | T1~T6으로 테스트 스위트 건강 진단 |
| Health Dashboard | /brooks-health | 4개 차원 가중평균(아키텍처 0.30이 최대 가중치) 종합 점수 |
| Full Sweep | /brooks-sweep | 진단 + 자동 수정. Safe/Extended-Safe/Residual 3단 수정 등급, 테스트 실패 시 자동 revert |
v1.3.0에서 단일 거대 SKILL.md를 6개 스킬로 쪼개고 공통 규칙은 _shared/로 빼냈습니다. 마크다운 세계에서의 모듈 분리 리팩터링인 셈인데, 자기 도구가 설파하는 원칙(R3 지식 중복 제거)을 자기 구조에 적용한 점이 재미있습니다.
| 코드 | 이름 | 진단 질문 | 대표 근거 서적 |
|---|---|---|---|
| R1 🧠 | Cognitive Overload | 이해하는 데 얼마나 머리가 아픈가? (20줄+ 함수, 중첩 3+, 매직넘버) | Code Complete, A Philosophy of Software Design |
| R2 🔗 | Change Propagation | 하나 고치면 몇 군데가 같이 깨지나? (Shotgun Surgery, Hyrum's Law) | Refactoring, The Pragmatic Programmer |
| R3 📋 | Knowledge Duplication | 같은 결정이 여러 곳에 적혀 있나? (복붙, user/account/member 혼용) | The Pragmatic Programmer(DRY), DDD |
| R4 🌀 | Accidental Complexity | 문제보다 코드가 더 복잡한가? (Speculative Generality, 2차 시스템 효과) | Mythical Man-Month, Refactoring |
| R5 🏗️ | Dependency Disorder | 의존성이 한 방향으로 흐르나? (순환 의존, 도메인→인프라 직결) | Clean Architecture, SE at Google |
| R6 🗺️ | Domain Model Distortion | 코드가 비즈니스를 정직하게 표현하나? (Anemic Domain Model) | Domain-Driven Design |
각 리스크 정의에는 잡지 말아야 할 것 목록이 따라붙습니다. 예: "CRUD 위주 워크플로는 트랜잭션 스크립트가 정당할 수 있다"(R6), "선형이고 이름이 좋은 긴 함수는 괜찮을 수 있다"(McConnell). 심지어 source-coverage.md는 책마다 "과잉 인용하지 말 것" 항목을 둬서 겉멋 인용(shallow citation)을 시스템적으로 차단합니다. AI 린터의 고질병인 "다 문제라고 우기기"에 대한 해답입니다.
점수 = 100 − (Critical × 15) − (Warning × 5) − (Suggestion × 1) # 하한 0
부채 우선순위 = Pain(1~3) × Spread(1~3) # 7~9 Critical / 4~6 Scheduled / 1~3 Monitored실행할 때마다 .brooks-lint-history.json에 기록을 쌓아 Trend: 85 → 82 (−3)처럼 추세를 보여줍니다. 일회성 리뷰 도구가 아니라 코드베이스 건강검진 기록부를 지향합니다.
commands/의 파일들이 전부 4줄이라는 게 중요합니다. 커맨드는 라우팅만 하고 지식은 전부 skills/에 있습니다 — 웹 개발의 "얇은 컨트롤러, 두꺼운 서비스" 패턴이 마크다운 세계에 그대로 재현된 모습입니다.
트리거 경계 설계가 특히 배울 만합니다. 각 스킬의 description에는 발동 조건뿐 아니라 발동하지 말아야 할 조건이 명시됩니다. 예: brooks-debt는 "health"라는 단어 때문에 서버 헬스체크·K8s probe 질문에 오발동하는 것을 description 차원에서 차단합니다. 직접 스킬을 만들 때 그대로 흉내 낼 가치가 있는 디테일입니다.
프롬프트를 고치면 무엇이 좋아지고 무엇이 망가졌는지 알 수 없다는 게 프롬프트 엔지니어링의 근본 문제입니다. 이 레포는 49개 케이스(다국어 트리거, negative 케이스 포함)를 JSON으로 박아두고 npm run evals로 회귀 검증합니다. 코드의 단위 테스트 문화를 프롬프트에 이식한 살아있는 예제입니다.
매니페스트 3개(JSON)만 추가해 Claude Code·Codex·Gemini를 동시 지원합니다. 스킬 본체는 건드리지 않습니다. 어댑터 패턴의 마크다운 버전이며, 직접 만든 스킬을 배포할 때 바로 참고할 수 있는 구조입니다.
AI에게 코드를 고치게 할 때의 위험 관리법을 보여줍니다: Safe(단일 파일+완전 로컬, export 심볼 변경 금지) → Extended-Safe(테스트 존재+공개 API 불변+5파일 이하) → Residual(자동수정 포기, 리포트만). 수정 후 테스트가 깨지면 역순 revert, 3회 실패한 finding은 은퇴 처리, commit/push는 절대 안 함. 에이전트에게 쓰기 권한을 줄 때의 가드레일 설계 견본입니다.
R1~R6 정의 문서는 사실상 고전 12권의 핵심을 코드 진단 관점으로 요약한 초압축 노트입니다. 책을 읽기 전 decay-risks.md를 먼저 읽으면 어떤 책이 어떤 문제를 다루는지 지도가 생깁니다.
| 항목 | 요구사항 |
|---|---|
| 필수 | Claude Code, Codex CLI, Gemini CLI(≥0.30.0) 중 하나 |
| 하드웨어 | 없음 — 연산은 전부 LLM API가 수행. 로컬은 마크다운 몇 백 KB |
| 개발 참여 시 | Node.js (evals 실행), Anthropic API 키 (evals:live) |
| 설치 | /plugin marketplace add hyhmrright/brooks-lint → /plugin install brooks-lint@brooks-lint-marketplace |
Claude Code에서 플러그인을 설치하고, 최근에 작업한 프로젝트에 /brooks-review를 실행해 보세요. Health Score와 finding의 4단 구조(Symptom→Source→Consequence→Remedy)가 실제로 어떻게 나오는지, 인용된 책이 무엇인지 확인합니다.
README 예제처럼 SQL 인젝션 + 4가지 책임이 뒤섞인 함수를 직접 작성해 리뷰시켜 보세요. 그 다음 brooks-lint 없이 맨몸 Claude에게 같은 코드를 주고, 출력의 구조·일관성 차이를 직접 비교합니다(미니 벤치마크 재현).
커버리지 지표를 안 쓰는 팀이라면 disable: [T5], 생성 파일은 ignore: ["**/*.generated.*"], 그리고 custom_risks:로 우리 팀 전용 리스크(C1: 하드코딩된 시크릿 등)를 하나 정의해 보세요. 설정이 리포트의 Config 라인에 반영되는지 확인합니다.
모듈이 10개 이상인 프로젝트에 아키텍처 감사를 돌려 Mermaid 의존 그래프를 받아보세요. 빨간 노드(Critical)가 왜 빨간지 R5(Dependency Disorder) 정의와 대조하고, 제안된 Remedy 중 하나를 실제로 적용한 뒤 재실행해 Trend가 개선되는지 봅니다.
brooks-lint의 골격(Iron Law → 진단 차원 정의 → 리포트 템플릿 → evals)을 그대로 빌려, 다른 도메인의 스킬을 만들어 보세요. 예: 글쓰기 책 3권 기반 문서 리뷰 스킬, 또는 SRE 책 기반 운영 점검 스킬. evals.json에 negative 케이스 3개를 포함시키는 것까지가 과제입니다.
| 주차 | 주제 | 할 일 |
|---|---|---|
| 1주차 | 도구 체득 | 6개 모드 전부 실행해 보기. 리포트의 책 인용을 모아 "내 코드가 가장 자주 위반하는 책" 순위 만들기 |
| 2주차 | 원전 입문 | 가장 많이 인용된 책 1권 읽기 시작 (대부분 《Refactoring》 또는 《A Philosophy of Software Design》이 걸림). decay-risks.md를 독서 가이드로 활용 |
| 3주차 | 스킬 엔지니어링 | Anthropic 공식 Agent Skills 문서 + 이 레포의 _shared/ 구조 분석. 트리거 경계·Progressive Disclosure·커맨드 위임 패턴 정리 |
| 4주차 | 제작과 검증 | 과제 5 수행. evals 작성 → 프롬프트 수정 → 회귀 확인 사이클을 한 바퀴 돌려보기 |
| 용어 | 뜻 |
|---|---|
| Iron Law | "진단 완료 전 수정 제안 금지, 모든 발견은 4단 구조" — brooks-lint 출력 형식의 절대 규칙 |
| Shotgun Surgery | 하나의 변경이 여러 파일에 잔수정을 흩뿌리는 코드 스멜 (Fowler). R2의 대표 증상 |
| Hyrum's Law | "관찰 가능한 모든 동작은 누군가 의존하게 된다" — 암묵적 계약의 법칙 (SE at Google) |
| Anemic Domain Model | 도메인 객체가 getter/setter뿐이고 로직은 전부 서비스층에 있는 안티패턴. R6의 대표 증상 |
| Second-System Effect | 첫 시스템 성공 후 두 번째에 기능을 과적해 망치는 경향 (Brooks). R4 증상 |
| Conway's Law | 시스템 구조는 조직의 의사소통 구조를 닮는다. /brooks-audit가 팀-모듈 정렬을 점검 |
| Seam (이음새) | 코드 수정 없이 동작을 갈아끼울 수 있는 지점 (Feathers). 테스트 가능성의 핵심, T6에서 평가 |
| Coverage Illusion | "커버리지는 실행을 재지 검증을 재지 않는다" — 90% 커버리지로도 핵심 실패를 다 놓칠 수 있음 (T5) |
| Progressive Disclosure | 필요한 시점에 필요한 만큼만 컨텍스트를 로드하는 스킬 설계 원칙 |
| Pain × Spread | 기술 부채 우선순위 = 현재 고통(1~3) × 파급 범위(1~3). 7점 이상은 다음 스프린트 처리 |
| negative eval | "이럴 땐 발동하면 안 된다"를 검증하는 테스트 케이스. 오트리거 방지용 |
| 도그푸딩 | 자기 도구를 자기 개발에 쓰는 것. 이 레포는 PR 리뷰에 brooks-lint 자신을 사용 |
| 링크 | 설명 |
|---|---|
| GitHub 저장소 | 소스 전체. skills/_shared/가 핵심 읽을거리 |
| 출력 갤러리 | Python/TS/Go/Java 실제 리뷰 결과 모음 |
| TrendShift 페이지 | 트렌딩 추이 |
| Claude Code Skills 공식 문서 | 스킬/플러그인 제작 표준 |
| Refactoring (Fowler) | 가장 많이 인용되는 원전 |
| A Philosophy of Software Design | R1(인지 과부하)의 이론적 토대 |