Heyosseus/sloppy: AI 에이전트가 작성한 PHP 코드를 정리합니다.

AI 에이전트가 PHP를 작성하면, Sloppy가 이를 깔끔하게 정리해 줍니다.

이는 사람들이 후회하는 코드—신(god) 메서드, 삼켜진 예외(swallowed exceptions), N+1 쿼리—를 Claude Code, CI, 그리고 Pest 스위트 내에서 잡아냅니다.

결정론적이며 로컬로 작동합니다: 모델 필요 없음, API 키 필요 없음, 네트워크 연결 필요 없음.

실제 결과물. Claude Code는 편집할 때마다 이를 실행하여 모델에 전달하고, 사용자가 보기 전에 catch 블록을 수정해 줍니다.

composer require --dev heyosseus/sloppy
vendor/bin/sloppy # 프로젝트 스캔 (Laravel의 경우 php artisan sloppy)
vendor/bin/sloppy agents install # Claude Code가 자체 작업을 확인하도록 설정 (--host=gemini, --host=codex)

그게 전부입니다: 설정 파일도, 계정도 필요 없습니다. Sloppy는 composer.json에서 소스 루트를 찾습니다.

어떤 PHP 8.3+ 프로젝트에서도 실행되며, Laravel 12 또는 13을 발견하면 텐(ten)개의 Eloquent 인식 규칙을 추가합니다.

히스토리가 있는 코드베이스를 처음 스캔한다고 해서 수백 개의 문제점을 처리해야 하는 상황에 놓이는 것은 아닙니다. 가장 먼저 수정할 가치가 있는 결함을 나열하고, 나머지는 파일별로 합산하며, 이미 존재하는 것을 기준으로 삼을지 제안합니다.

의존성을 추가하기 전에 사용해 보고 싶으신가요? composer global require heyosseus/sloppy를 실행하거나 phar 파일을 다운로드하세요. Getting started를 참조하세요.

에이전트는 코드를 빠르게 생성하지만, 똑같은 실수를 빠르게 저지릅니다: 실패를 숨기는 catch (Throwable), 200줄짜리 컨트롤러 액션, 루프 내부의 쿼리 같은 것들입니다. 코드 리뷰는 이를 너무 늦게 잡아냅니다. Sloppy는 에이전트가 코드를 가지고 있을 때 잡아냅니다.

규칙이 먼저 들어갑니다.CLAUDE.md (또는 AGENTS.md, .cursorrules, Copilot, Windsurf, Gemini CLI, Laravel Boost)는 이 프로젝트의 규칙을 가져오며, 각 규칙은 에이전트가 따를 수 있는 지침으로 작성됩니다.모든 편집이 확인됩니다. PHP 파일이 변경될 때마다 Claude Code (또는 Gemini CLI, 또는 Codex)는 Sloppy를 실행하고 모델에 그 편집이 도입한 모든 것을 전달하며, 그러면 모델이 이를 수정합니다.더러운 상태로는 완료할 수 없습니다. 에이전트가 작업을 완료하려고 할 때, 임계값 이상으로 새로운 문제점이 발견되면 다시 돌아와서 수정하도록 합니다.

이 기능은 방해되지 않도록 설계되었습니다. 이미 파일이 존재하는 경우 발견 사항을 보고하지 않아 에이전트가 아무도 건드리라고 요청하지 않은 코드를 '수정'하며 돌아다니지 않습니다. 최종 확인(finish check)은 한 번만 차단하므로, 오탐(false positive)이 발생해도 세션 전체가 아닌 라운드 트립(round trip) 하나만 비용이 듭니다. 그리고 Sloppy를 실행할 수 없는 경우(git 없음, 설정 오류 등), 에이전트는 계속 진행됩니다. sloppy agents uninstall은 모든 것을 제거하고 다른 모든 설정을 바이트 단위로 원래 상태로 되돌립니다.

또한, 필요에 따라 스캔해야 하는 에이전트를 위한 MCP 서버도 있습니다. Coding agents를 참조하세요.

26개의 규칙과 사용자의 변경 사항을 기본값(base)과 비교하는 두 가지 확인 기능, 그리고 설명한 아키텍처를 강제하는 다섯 가지 추가 기능이 있습니다. 이들 각각은 특정 패턴에서 작동하도록 테스트되었으며, 일반적인 Laravel 코드에서는 침묵을 유지합니다.

기존 코드...또는 본문이 있어야 할 곳에 "구현되지 않음" 표시 | 오류 처리 | SL107예외 무시(Swallowed Exception) | 가독성 (Readability) | SL108중복 조건 (Redundant Condition) ·SL109서술형 주석 (Narrative Comment) ·SL110방어적 프로그래밍 노이즈 (Defensive Programming Noise) | Laravel | SL201컨트롤러 내 비즈니스 로직 (Business Logic In Controller) ·SL202인라인 유효성 검사 (Inline Validation) ·SL208직접 외부 API 호출 (Direct External API Call) ·SL209너무 많은 일을 하는 모델 (Model Doing Too Much) | 성능 (Performance) | SL203가능한 N+1 ·SL204루프 내부 쿼리 (Query Inside Loop) ·SL205쿼리가 아닌 컬렉션 사용 (Collection Instead Of Query) ·SL210의심스러운Model::all()| 의존성 (Dependencies) | SL206과도한 컨트롤러 의존성 (Excessive Controller Dependencies) ·SL207과도한 서비스 의존성 (Excessive Service Dependencies) | 아키텍처 (권고 사항) (Architecture (advisory)) | SL301추상화 인플레이션 (Abstraction Inflation) ·SL302빈 래퍼 클래스 (Empty Wrapper Class) ·SL303단일 사용 추상화 (Single-Use Abstraction) | 당신의 아키텍처 (선택 사항) (Your architecture (opt-in)) | SL304레이어 위반 (Layer Violation) ·SL305금지된 기능, 컨트롤러의 쿼리 또는 도메인에서의env()·SL306경계 위반, 한 모듈이 다른 모듈의 내부 구조에 접근하는 것 ·SL307잘못 배치된 클래스, 아키텍처 내에 자리가 없는 새로운 클래스 ·SL308역할 모양 (Role Shape), 두 번째 public 메서드를 가진 액션 | 억제 (Suppression) | SL501설명되지 않은 억제 (Unexplained Suppression) ·SL502기준선 증가, PHPStan 또는 Psalm의 새로운 기준선 항목 ·SL503약화된 테스트, 건너뛰거나, 단언문이 제거되었거나, 통과시키기 위해assertTrue(true)`가 주어진 테스트

모든 발견 사항은 어디에 있는지, 무엇이 측정되었는지, 분석기가 얼마나 확신하는지, 이 패턴이 왜 비용을 발생시키는지, 그리고 대신 무엇을 해야 하는지를 알려줍니다. 규칙(Rules)을 보거나 자신만의 규칙을 작성할 수 있습니다.

원하는 곳 어디에서든 동일한 분석기를 사용할 수 있습니다.

중요한 것부터 시작하세요. 중간 크기의 애플리케이션에 대한 첫 번째 스캔만 해도 수백 가지의 문제점이 발견되는데, 아무도 수백 가지를 읽지 않습니다. 그래서 sloppy는
먼저 결함(예외 무시, 루프 내부 쿼리, 미완성 본문)을 나열하고,
가장 위험한 것부터 보여줍니다. 파일별로 긴 메서드와 서술형 주석의 개수를 합산하여, 자주 변경되는 파일을 상단에 배치합니다. 그런 다음 목록을 읽지 않고도 줄여주는 명령어를 알려줍니다: sloppy fix

기계적인 발견 사항에 대해, sloppy baseline

이미 존재하는 부채에 대해서도 적용할 수 있습니다. --all

모든 것을 나열합니다.

변경 사항 검토. sloppy diff main

당신의 브랜치가 추가한 내용만 보고하고, 상속받은 내용은 절대 보고하지 않습니다. --merge-base를 추가하여

브랜치가 분기된 지점과 비교할 수 있습니다. 이는 sloppy ci가 하는 방식입니다. sloppy review main

동일한 발견 사항을 위험도별로 순위를 매겨, 어떤 파일을 먼저 읽어야 하고 어디서 멈춰야 할지 알게 해줍니다.

히스토리가 있는 코드베이스에 적용. sloppy baseline

오늘의 부채를 수용하여, 오직 새로운 발견 사항만 빌드를 실패하게 합니다. 항목들은 라인 번호가 아닌 클래스와 멤버를 기준으로 키워지므로, 베이스라인은 일반적인 편집에도 살아남습니다.

CI에서 게이트 설정. sloppy ci

실행되는 파이프라인을 읽습니다: GitHub 풀 리퀘스트의 diff에 주석을 달고 GitLab의 코드 품질 위젯을 채웁니다. GitHub Action은 세 줄입니다:

- uses: heyosseus/sloppy-action@v1
with:
diff-branch: main

이미 PHPStan을 사용하고 있나요? 이미 실행 중인 검사 내에서 동일한 발견 사항을 얻으세요:

composer require --dev heyosseus/phpstan-sloppy

각 항목은 고유 식별자(sloppy.SL107)를 가진 PHPStan 오류이므로,
@phpstan-ignore,
ignoreErrors
그리고 PHPStan 베이스라인에서 작동합니다. sloppy ci가 실패할 내용을 정확히 보고합니다. heyosseus/phpstan-sloppy를 확인하세요.

새로운 부채로 테스트 실패시키기. 패키지와 함께 Pest 플러그인이 제공됩니다:

it('has no new slop on this branch', function (): void {
expectCleanSloppyDiff('main');
});

기계가 고칠 수 있는 것을 수정하기. sloppy fix

기계적인 발견 사항을 Rector에게 전달하며, 해당 발견 사항이 있는 파일로 범위를 제한하고, 코드를 단순히 재진술하는 주석을 삭제한 다음, Pint으로 포맷합니다. 어떤 발견 사항은 여전히 사람이 필요하며, 왜 어떤 도구도 건드려서는 안 되는지 알려줍니다.

작업 중 점수 유지하기. sloppy watch

점수를 화면에 표시하고 무엇을 먼저 읽어야 할지 보여주며, 저장할 때마다 다시 그립니다. 코드를 작성하는 에이전트 옆에 두고 사용하도록 만들어졌습니다.

이미 보는 곳에서 확인하기. GitHub 코드 스캐닝과 IDE를 위해 SARIF를 사용하고, --format=github

인라인 주석 및 PR 댓글용 Markdown도 지원합니다.
Filament 위젯, NativePHP 메뉴바 레이블, 그리고 게시된 스키마를 가진 JSON 출력 기능도 있습니다.

Everyday 워크플로우와 CI 및 코드 스캐닝을 확인해 보세요.

이것은 AI 감지기가 아닙니다. 소스 코드만으로는 누가 또는 무엇이 작성했는지 신뢰성 있게 알 수 없으며, Sloppy는 결코 그렇게 하려 하지 않습니다. 이는 코드를 작성한 주체가 누구든 상관없이 유지보수 비용으로 변하는 패턴을 감지합니다. 밤 3시에 사람이 작성했든 에이전트가 작성했든, Throwable를 삼키는 200줄짜리 컨트롤러 액션은 문제입니다.

| 시작하기 | 설치 옵션, 모든 명령어, 첫 스캔 및 장시간 스캔 처리 방법, 기존 코드베이스에 적용하는 방법 |
| 코딩 에이전트 | Claude Code, Gemini CLI 및 Codex 훅, 모든 에이전트를 위한 규칙 세트, Laravel Boost, MCP 서버 |
| 규칙 | 모든 규칙을 상세히 설명하고 오탐(false positives)을 줄이는 방법 |
| ... |
아직 남은 작업: 인라인 풀 리퀘스트 리뷰 코멘트, sloppy explain

하나의 발견 사항에 대한 더 긴 작성 글, HTML 보고서, 그리고 단축 에이전트가 취하는 구성 키(configuration keys)나 존재하지 않는 라우트 같은 경로에 대한 추가 규칙들. AI 지원 기능은 모두 선택적이며 별도로 제공됩니다: 분석기(analyser)는 항상 API 키, 네트워크, 모델 없이 작동합니다.

오탐을 발견했나요? 그것은 우회할 임계값이 아니라 보고할 버그입니다. 이슈를 여세요. Sloppy 자체에 대해 작업하려면 CONTRIBUTING.md를 참조하세요. composer test

Rector, Pint, PHPStan을 레벨 8, 100% 타입 커버리지와 함께 실행하고 테스트 스위트를 실행합니다.

보안 문제: SECURITY.md를 참조하세요.

MIT. LICENSE.md를 참조하세요.