소프트웨어 개발 환경에서 반복적이고 자잘한 버그 수정 작업은 시니어 엔지니어의 집중력과 시간을 지속적으로 분산시키는 주요 원인입니다. Null 예외 처리, 라이브러리 지원 중단 대응, 정규표현식 수정, 누락된 단위 테스트 보강과 같은 작업은 위험도는 낮지만 백로그에 수주 동안 방치되기 쉽습니다.
Sweep은 이러한 병목 현상을 해결하기 위해 자율형 AI 주니어 개발자(AI Junior Developer)로 설계되었습니다. GitHub App 형태로 리포지토리에 연결된 Sweep은 신규 이슈를 모니터링하고, 벡터 임베딩과 AST(추상 구문 트리) 코드 분석을 통해 코드베이스 문맥을 파악한 뒤, 여러 파일에 걸친 수정 코드를 작성하여 체계적인 Pull Request(PR)를 생성합니다. 나아가 GitHub Actions의 CI 테스트 실패 로그를 스스로 분석하여 수정 커밋을 추가하고, 개발자의 인라인 코드 리뷰 의견에도 실시간으로 반응합니다.
본 가이드에서는 엔지니어링 팀이 Sweep을 도입하여 프로덕션 환경에 최적화된 sweep.yaml을 구성하고, 정밀한 이슈 프롬프트를 작성하며, CI 자율 복구 루프와 안전 보호 장치를 구축하는 방법을 정리합니다.
1. Sweep 이슈-PR 변환의 핵심 워크플로
설정 파일을 구성하기 전에 Sweep이 이슈를 처리하는 전체 수명주기를 파악해야 합니다.
- 트리거 이벤트 발생: 개발자가
Sweep:접두사를 붙여 GitHub 이슈를 생성하거나(예:Sweep: Fix KeyError when user metadata payload is missing), 기존 이슈에sweep라벨을 추가하거나, 댓글로@sweepai를 호출합니다. - 코드베이스 문맥 검색: Sweep의 웹훅 진입 함수(
on_ticket)가 실행되어 코드 벡터 검색과 AST 청킹을 기반으로 이슈와 관련된 소스 파일, 함수 정의 및 테스트 코드를 색인합니다. - 작업 계획 수립: Sweep은 이슈 본문에 댓글을 남겨 수정할 파일 목록과 구체적인 구현 방안을 포함한 작업 계획을 제시합니다.
- 코드 생성 및 브랜치 분기: 독립된 브랜치(예:
sweep/fix-...)를 생성하고 프로젝트 코딩 규칙에 맞춰 코드를 수정한 뒤 원격으로 푸시합니다. - Pull Request 오픈: 수정된 이슈 번호(
Fixes #<id>), 작업 요약, 세부 체크리스트를 포함한 PR을 등록합니다. - 양방향 피드백 루프:
- CI 자체 치유: GitHub Actions 연동(
gha_enabled: true)이 활성화되어 있으면, 단위 테스트 실패 시 에러 로그를 읽고 자동 수정 커밋을 추가합니다. - 사람 개발자 코드 리뷰: 리뷰어가 PR Diff에 인라인 코멘트를 남기면, Sweep이 이를 반영하여 추가 커밋을 생성합니다.
- CI 자체 치유: GitHub Actions 연동(
2. GitHub 설치 및 필수 권한 구성
조직 또는 개별 리포지토리에 Sweep을 연동하는 절차는 다음과 같습니다.
- GitHub App 설치: Sweep GitHub App 설치 페이지로 이동하여 적용할 리포지토리 또는 조직 전체를 선택합니다.
- 필수 권한 설정:
- Repository Contents(읽기 및 쓰기): 코드베이스 탐색 및 수정 브랜치 생성을 위해 필수적입니다.
- Issues(읽기 및 쓰기): 이슈 본문 확인, 라벨 지정, 진행 상황 댓글 작성을 위해 필요합니다.
- Pull Requests(읽기 및 쓰기): PR 생성, 변경점(Diff) 검토, 리뷰 피드백 대응을 위해 필요합니다.
- Actions / Checks(읽기): 빌드 및 테스트 실패 시 CI 로그를 수집하기 위해 필요합니다.
- Draft 모드 활용: 초기 도입 단계에서는 PR을 초안 상태(
draft: true)로 생성하도록 설정하여 팀 알림 채널의 피로도를 낮추고, 1차 검토 후 정식 리뷰로 전환하는 것을 권장합니다.
3. sweep.yaml을 활용한 프로젝트 규칙 제약
Sweep의 핵심 동작은 리포지토리 루트에 위치한 sweep.yaml(또는 .sweep/config.yaml) 파일에 의해 제어됩니다. 체계적인 설정을 통해 잘못된 패키지 임포트(할루시네이션)를 방지하고 팀 고유의 코드 스타일을 강제할 수 있습니다.
프로덕션 환경 sweep.yaml 설정 예시
# sweep.yaml - 자동화 이슈 해결을 위한 설정 파일
# Sweep이 브랜치를 파생하고 PR을 생성할 대상 기본 브랜치
branch: 'main'
# PR을 Draft 상태로 열지 여부 (초기 도입 시 true 권장, 안정화 후 false)
draft: false
# GitHub Actions의 테스트 실패 로그를 읽고 자체 수정 커밋을 생성할지 여부
gha_enabled: true
# 프로젝트 아키텍처 개요 (모델의 코드베이스 이해도 향상)
description: >
Python 3.10과 FastAPI로 구축된 백엔드 REST API 리포지토리입니다.
데이터베이스 작업은 SQLAlchemy 2.0 및 PostgreSQL을 사용합니다.
비즈니스 로직은 services/, 데이터 모델은 models/, API 엔드포인트는 api/v1/에 있습니다.
모든 파이썬 임포트는 절대 경로를 사용해야 합니다 (예: `from services.auth import verify_token`).
# Sweep이 절대 접근하거나 수정해서는 안 되는 차단 디렉터리
blocked_dirs:
- "deploy/"
- "terraform/"
- ".github/workflows/"
- "migrations/"
- "*.env*"
- "security/"
# PR 생성 전 Sweep 격리 샌드박스에서 수행할 검증 명령어
sandbox:
install:
- "poetry install --no-root"
check:
- "poetry run ruff check {file_path}"
- "poetry run pytest tests/unit"
# 에이전트 프롬프트에 주입되는 강제 코딩 가이드라인
rules:
- "모든 버그 수정은 tests/ 디렉터리에 상응하는 pytest 단위 테스트를 반드시 추가하거나 갱신해야 합니다."
- "와일드카드 임포트(`from module import *`)는 엄격히 금지합니다."
- "모든 API 요청 및 응답 검증에는 Pydantic v2 스키마를 사용합니다."
- "로깅에는 loguru를 사용하며 예외 처리 블록 내부에서는 logger.exception()으로 트레이스백을 남깁니다."
- "명시적인 요청이 없는 한 데이터베이스 스키마를 변경하거나 alembic 마이그레이션을 생성하지 않습니다."
- "모든 신규 및 변경 함수 시그니처에는 완전한 타입 힌트(Type Annotations)를 작성합니다."
핵심 필드 설명
branch: PR 타깃 브랜치입니다.develop브랜치 기반으로 작업하는 팀은 해당 브랜치명으로 지정합니다.blocked_dirs: 절대적인 안전 보호 장치입니다. 인프라 코드, CI 스크립트, 비밀 키 설정 파일, DB 마이그레이션 파일 등을 명시하여 AI의 임의 수정을 차단합니다.gha_enabled:true로 설정하면 GitHub Actions 워크플로 결과를 모니터링하여 테스트 실패 시 에러 로그를 기반으로 자율 디버깅을 수행합니다.rules: 팀의 개발 표준을 자연어로 전달하는 규칙 목록입니다. AI가 코드를 작성할 때 컨텍스트로 적용되어 일관된 코딩 스타일을 유지합니다.sandbox: 격리된 실행 환경에서 의존성 설치(install)와 정적 분석 및 테스트(check)를 사전 실행하여 검증된 코드만 PR로 생성하도록 보장합니다.
4. 정밀한 PR을 이끌어내는 이슈 작성 가이드
Sweep이 생성하는 PR의 품질은 GitHub 이슈에 제공된 정보의 밀도와 정확도에 정비례합니다. 인간 개발자는 모호한 부분을 사내 메신저로 확인할 수 있지만, AI는 오직 이슈 본문과 코드베이스에만 의존합니다.
추천 버그 리포트 템플릿
제목: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile
### 버그 설명
`PUT /api/v1/profile`을 통해 프로필을 업데이트할 때, 요청 본문 `metadata`에 빈 딕셔너리 `{}`를 전달하면 기본값 초기화 대신 ValidationError가 발생합니다.
### 재현 단계
1. `/api/v1/profile`로 `{"metadata": {}}` 바디를 포함하여 PUT 요청을 전송합니다.
2. API가 HTTP 400 응답과 함께 `Value error, metadata must contain required fields` 메시지를 반환하는 것을 확인합니다.
### 기대 동작
빈 `metadata` 딕셔너리가 전달된 경우에도 정상 수용되어야 하며, 기본값(`{"theme": "light", "notifications": true}`)으로 채워진 후 데이터베이스에 정상 저장되어야 합니다.
### 관련 소스 코드 및 파일
- `api/v1/profile.py`: `update_profile` 라우트 핸들러.
- `schemas/profile.py`: `UserProfileUpdate` Pydantic 모델.
- `services/profile_service.py`: `save_profile_metadata` 헬퍼 함수.
### 수용 기준
- `schemas/profile.py`의 유효성 검증을 수정하여 빈 딕셔너리 허용 및 기본값 적용.
- `tests/unit/test_profile_api.py`에 빈 페이로드 케이스를 검증하는 단위 테스트 추가.
- `tests/unit/` 내의 기존 테스트가 모두 정상 통과할 것.
이슈 제목 접두사 및 실행 모드 제어
Sweep의 이슈 파서(strip_sweep)는 제목 접두사에 따라 세부 실행 전략을 전환합니다.
Sweep: <제목>: 표준 자동화 작업 모드.Sweep(sandbox): <제목>: 샌드박스 검증을 필수로 실행한 후 PR 생성.Sweep(fast): <제목>: 단순 텍스트나 간단한 수정을 위해 고속 추론 모드 적용.Sweep(slow): <제목>: 복잡한 다중 의존성 문제를 위해 심층 탐색 모드 적용.Sweep(lint): <제목>: 코드 포맷팅 및 정적 린트 규칙 검사를 엄격히 적용.Sweep(subissues): <제목>: 큰 규모의 작업을 하위 이슈들로 자동 분할.
5. 코드 리뷰 및 반복 개선 절차
PR이 생성된 이후의 협업은 GitHub의 익숙한 UI 내에서 자연스럽게 이루어집니다.
[GitHub 이슈] ──> Sweep 실행 ──> PR 생성 ──> CI (GitHub Actions)
│
┌─────────────────────────────┴────┐
▼ ▼
CI 실패 (gha_enabled) CI 성공
│ │
▼ ▼
Sweep 자동 수정 커밋 사람 개발자 Code Review
│ │
└─────────► PR 실시간 갱신 ◄────────┘
│
(Diff 코멘트 입력:
"@sweepai 공통 유틸의
날짜 변환 함수를 사용해주세요")
인라인 리뷰 피드백
개발자가 로컬 머신에서 해당 브랜치를 체크아웃할 필요가 없습니다. GitHub PR Diff 화면에서 변경할 코드 라인을 지정하고 다음과 같이 코멘트를 남기면 됩니다.
@sweepai 여기에 새로운 포매터를 구현하지 말고, 기존 DateUtils.formatIso() 함수를 재사용해주세요.
Sweep은 웹훅을 통해 코멘트를 감지하고 문맥을 파악한 뒤 해당 브랜치에 수정 커밋을 즉시 푸시합니다.
이슈 재정의 및 PR 재생성
초기 이슈 내용에 착오가 있었거나 요구사항 방향이 달라졌을 경우, PR을 닫고 다시 작성할 필요 없이 원래의 GitHub 이슈 제목이나 본문을 수정하기만 하면 됩니다. Sweep이 변경 사항을 감지하여 기존 브랜치를 정리하고 새로운 PR을 다시 구성합니다.
6. 프로덕션 안전 수칙 및 엔지니어링 한계
AI 에이전트를 실무 개발 파이프라인에 통합할 때는 다음 원칙을 반드시 준수해야 합니다.
- 자동 머지(Auto-merge) 절대 금지: Sweep이 생성한 PR에는 자동 병합을 설정하지 마십시오. 브랜치 보호 규칙을 적용하여 최소 1명 이상의 시니어 엔지니어 승인과 CI 통과를 머지 필수 조건으로 둡니다.
- 핵심 영역 격리:
blocked_dirs를 활용해 클라우드 인프라 정의 파일(terraform/,k8s/), CI/CD 파이프라인(.github/), DB 마이그레이션 스크립트 및 환경 변수 파일을 완전히 격리합니다. - 명확한 작업 범위 한정: Sweep은 단일 버그 해결, 단위 테스트 추가, 국소 리팩토링에 가장 적합합니다. 아키텍처 재설계나 명세가 불분명한 대규모 기능 개발에는 적합하지 않습니다.
- 철저한 테스트 커버리지: Sweep의 자율 복구 능력은 테스트 에러 메시지의 정확도에 전적으로 의존합니다. 단위 및 통합 테스트 커버리지가 탄탄할수록 AI가 안전하고 완성도 높은 코드를 작성합니다.
참고 자료
- GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
- GitHub - sweepai/sweep: sweep.yaml configuration file
- GitHub - sweepai/sweep: sweepai/config/client.py
- GitHub - sweepai/sweep: sweepai/handlers/on_ticket.py
- GitHub - sweepai/sweep: sweepai/utils/str_utils.py
- sweepai · PyPI
- Launch YC: Sweep: JetBrains AI Coding Assistant | Y Combinator