sweep.yaml 규칙과 저장소 가이드라인을 구성하여 자동화된 Pull Request를 기존 코딩 표준에 맞추는 방법

소프트웨어 엔지니어링 팀이 일상적인 버그 수정, 소규모 기능 구현, 코드 리팩토링 작업을 자동화하기 위해 Sweep AI를 도입할 때 가장 핵심적인 과제는 생성된 Pull Request(PR)가 팀의 기존 코딩 표준과 아키텍처 규칙을 엄격히 준수하도록 보장하는 것입니다. 명확한 제약 조건이 없으면 대규모 언어 모델(LLM)은 코드 스타일 불일치를 초래하거나, 단위 테스트를 누락하거나, 사용이 중단된 레거시 유틸리티를 호출하거나, 심지어 중요한 CI/CD 파이프라인 및 보안 구성 파일을 무단 수정할 위험이 있습니다.

이러한 문제를 방지하기 위해 개발팀은 저장소 루트의 sweep.yaml 구성 파일을 핵심 제어판으로 삼고, 저장소 규칙 문서(SWEEP.md), 디렉터리 보호 정책, GitHub Actions 기반의 폐쇄 루프 피드백을 결합하여 견고한 AI 코드 거버넌스 체계를 구축합니다.

1. sweep.yaml의 구조: 핵심 제어 매니페스트

sweep.yaml 파일은 저장소의 루트 디렉터리에 위치하며 Sweep AI 에이전트의 동작을 규정하는 선언적 설정 매니페스트 역할을 합니다. 이 파일에 선언된 매개변수들은 AI가 코드베이스를 탐색하고, 코드 수정을 계획하며, PR을 제출하는 모든 과정에 직접적인 영향을 미칩니다.

주요 구성 매개변수는 다음과 같습니다:

2. sweep.yaml에서 실효성 있는 규칙(rules) 정의하기

rules 필드는 팀 내부의 엔지니어링 표준을 AI 모델이 실행할 수 있는 프롬프트 제약 조건으로 변환하는 공간입니다. "깔끔한 코드를 작성하라"와 같은 모호한 문장은 효과가 없으며, 규칙은 구체적이고 명령형이어야 하며 자동화된 도구로 검증 가능해야 합니다.

권장되는 핵심 규칙 범주

1. 테스트 및 커버리지 필수화

   • 새로운 비즈니스 로직이나 함수 작성 시 반드시 동일 디렉터리 또는 테스트 디렉터리에 단위 테스트를 추가하도록 강제합니다.
   • 예시: "All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."

2. 정적 타입 분석 및 최신 문법 준수

   • 함수의 매개변수와 반환값에 명확한 타입 힌트를 요구하고 현대적인 내장 타입을 우선 사용하도록 지정합니다.
   • 예시: "Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."

3. 로깅 표준화 및 디버깅 코드 정리

   • 표준 로깅 라이브러리를 지정하고 프로덕션 코드에 원시 print 문이 남지 않도록 차단합니다.
   • 예시: "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."

4. 모듈성 유지 및 잔여 부채 해소

   • 단일 함수의 복잡도를 제한하고 리팩토링 과정에서 남겨진 미완성 작업 표식을 반드시 해결하도록 명시합니다.
   • 예시: "Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."

3. 프로덕션 환경을 위한 sweep.yaml 청사진

다음은 FastAPI와 PostgreSQL 기반의 백엔드 서비스에 적용 가능한 프로덕션 수준의 sweep.yaml 구성 예시입니다:

# sweep.yaml - Sweep AI 저장소 자동화 구성 파일

# PR의 기준이 되는 타깃 브랜치
branch: main

# 프로젝트 아키텍처 개요, 실행 환경 요구사항 및 엔트리포인트
description: >
  This is a Python 3.10 microservice built on FastAPI with PostgreSQL.
  The primary API routes are registered in app/api/v1/.
  Use SQLAlchemy 2.0 async sessions for database access.
  Strictly adhere to PEP 8 standards and asynchronous I/O paradigms.

# 초기 검토를 위해 PR을 드래프트 상태로 생성할지 여부
draft: false

# CI/CD 폐쇄 루프: GitHub Actions 실패 로그를 읽어 스스로 코드 수정
gha_enabled: true

# 보호 조치: 워크플로, 데이터베이스 마이그레이션, 보안 비밀번호 파일 수정 차단
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# 코드 계획 및 생성 시 강제 적용되는 세부 코딩 규칙 목록
rules:
  - "All new endpoints and service logic must include corresponding unit and integration tests using pytest."
  - "Annotate all function parameters and return values with strict type hints."
  - "Use structured logging via loguru; use logger.exception inside catch blocks. Never use print() statements."
  - "Use list, dict, and tuple built-ins for type annotations instead of importing from typing."
  - "Resolve any remaining TODO items created during refactoring before finalizing the PR."
  - "Follow existing repository import conventions: group external libraries first, then internal module imports."
  - "Do not modify database migrations or schema files without explicit issue instructions."

4. SWEEP.md 및 저장소 가이드라인과의 협업 확장

기계적 플래그를 관리하는 sweep.yaml 외에도 많은 엔지니어링 팀은 프로젝트 루트에 SWEEP.md 파일을 함께 배치하여 규칙을 확장합니다.

SWEEP.md의 역할과 중요성

SWEEP.md는 CLAUDE.md 또는 .cursorrules와 유사하게 지속적인 프로젝트 컨텍스트를 제공합니다. GitHub 기반의 자율 PR 생성뿐 아니라 JetBrains 플러그인과 같은 IDE 환경에서도 일관된 개발 규칙을 제공합니다.

표준 SWEEP.md는 대개 다음 네 가지 섹션으로 구성됩니다:

• 빌드 및 검증 명령어: 의존성 설치, 빌드, 린트, 테스트 실행 명령 명시 (npm run lint, pytest tests/unit/ -v).
• 코드 스타일 선호도: 파일 명명 규칙(kebab-case 등), 폴더 구조 원칙, 선호 유틸리티 라이브러리.
• 아키텍처 및 데이터 흐름: 모듈 간 종속성 방향, 상태 관리 패턴, API 인터페이스 규격.
• 코드 리뷰 체크리스트: PR 제목 형식, 연관 Issue 지정 규칙, CHANGELOG 업데이트 기준.

팀은 Sweep 설정 창의 Rules 탭에서 Generate SWEEP.md 버튼을 클릭하여 기존 저장소 규칙을 바탕으로 기초 파일을 자동 생성할 수 있습니다.

5. CI/CD 폐쇄 루프: GitHub Actions를 통한 자동 자가 치유

프롬프트 규칙이 아무리 정교하더라도 LLM은 복잡한 프로젝트에서 괄호 누락, 전역 타입 추론 실패, 미사용 import 문 생성 등 사소한 오류를 범할 수 있습니다. Sweep이 기존 엔지니어링 표준을 완벽히 충족하는 가장 강력한 메커니즘은 GitHub Actions와의 폐쇄 루프 연동(gha_enabled: true)입니다.

+--------------------+         +--------------------+         +--------------------+
| GitHub Issue /     | ------> | Sweep AI 코드 계획  | ------> | 대상 브랜치로       |
| 작업 생성          |         | 및 변경점 작성     |         | Pull Request 오픈  |
+--------------------+         +--------------------+         +--------------------+
                                                                        |
                                                                        v
                                                              +--------------------+
                                                              | GitHub Actions     |
                                                              | 실행 (린터, 타입    |
                                                              | 체크, 단위 테스트) |
                                                              +--------------------+
                                                                        |
                                    +-----------------------------------+
                                    |
                     [CI 성공]      |               [CI 실패]
                         v          |                   v
            +--------------------+  |         +--------------------+
            | 엔지니어의         |  |         | Sweep이 실패 로그와|
            | Code Review 단계   |  |         | 에러 메시지 자동 수집|
            +--------------------+  |         +--------------------+
                                    |                   |
                                    |                   v
                                    |         +--------------------+
                                    +---------| 수정 패치 커밋을   |
                                              | PR 브랜치에 푸시   |
                                              +--------------------+

폐쇄 루프 동작 메커니즘:

1. PR 자동 생성: Sweep이 이슈 지침과 sweep.yaml 규칙을 준수하여 코드를 작성하고 PR을 제출합니다.
2. CI 파이프라인 가동: GitHub Actions가 ESLint, Ruff, Trunk와 같은 린터, tsc 및 pyright 같은 타입 체커, 테스트 러너를 실행합니다.
3. 오류 로그 수집: CI 단계가 실패하면 Sweep이 실패 로그와 콜스택을 즉시 수집합니다.
4. 자가 치유 커밋 발행: 오류가 발생한 파일명, 라인 번호, 구체적 원인(미정의 변수, 타입 불일치 등)을 파악한 뒤 타깃 diff 패치를 생성하여 해당 PR 브랜치에 직접 커밋을 추가 푸시합니다.
5. 엔지니어 검토 부담 완화: 모든 정적 검사와 테스트가 통과된 녹색(Green) 상태에서만 동료 엔지니어가 리뷰에 참여하므로, 서식이나 단순 구문 오류로 낭비되는 시간을 대폭 줄일 수 있습니다.

6. 팀을 위한 실전 권장 사항 및 안전 수칙

안정적인 자동화를 정착시키기 위해 엔지니어링 팀은 다음 원칙을 준수하는 것이 좋습니다:

1. 민감한 디렉터리 완벽 차단: .github/, 인프라 배포 스크립트, DB 마이그레이션 파일, 인증서 및 시크릿 디렉터리를 반드시 blocked_dirs에 등록하십시오.
2. 작업 스코프 최소화: 이슈당 수정 파일은 3~5개, 총 수정 코드 라인은 300줄 이내로 유지하십시오. 태스크 범위가 작을수록 AI의 완성도와 자가 치유율이 급상승합니다.
3. 이슈 작성 시 명확한 경로와 지침 제공: 수정 대상 파일, 기대 동작, 참고할 기존 코드 패턴을 명확히 제시하십시오 (예: "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. PR 코멘트를 통한 대화형 수정: 생성된 PR에서 수정이 필요한 경우, 코드 라인에 sweep: 접두어로 코멘트를 남기면 AI가 직접 코드를 업데이트하므로 로컬 체크아웃이 불필요합니다.
5. 도입 초기 Draft 모드 운영: 대규모 레거시 코드베이스에 Sweep을 처음 적용할 때는 sweep.yaml에 draft: true를 설정하여 사람이 먼저 변경점을 확인한 후 정규 CI 파이프라인을 실행하는 것이 안전합니다.

참고 자료

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• Sweep Config Documentation
• Sweep Advanced Features Guide
• Sweep Official Repository sweep.yaml
• CodeCrafters Frontend sweep.yaml Configuration
• Sweep Client Configuration Parser
• AI-powered junior dev meets Trunk, a super-linter