Devin 세션 플레이북 작성 가이드: PR 첫 승인률을 극대화하는 구조화된 프롬프트 전략
Devin 세션 플레이북이란?
Devin은 Cognition AI가 개발한 자율형 AI 소프트웨어 엔지니어입니다. 세션 플레이북(Session Playbook)은 Devin에게 작업을 위임할 때 사용하는 구조화된 지침 문서로, 명확한 태스크 프롬프트, 수락 기준, 스냅샷 리뷰 워크플로우, 반복 피드백 루프를 포함합니다. 잘 작성된 플레이북은 PR 첫 승인률(First-Attempt Approval Rate)을 극적으로 향상시킵니다.
1단계: 환경 설정 및 Devin 세션 시작
- Devin 대시보드에 로그인하고 워크스페이스를 설정합니다.- GitHub 리포지토리를 연결합니다.- 새 세션을 생성하고 플레이북을 적용합니다.
# Devin CLI 설치 및 세션 시작 npm install -g @cognition-ai/devin-cli
인증 설정
devin auth login —token YOUR_API_KEY
리포지토리 연결 확인
devin repo connect —url https://github.com/your-org/your-repo
새 세션 시작 (플레이북 적용)
devin session start —playbook ./playbooks/feature-task.md
2단계: 구조화된 태스크 프롬프트 작성
효과적인 태스크 프롬프트는 컨텍스트, 목표, 제약 조건을 명확히 분리합니다. 아래는 권장 플레이북 템플릿입니다.
# playbooks/feature-task.md
Context
- 프로젝트: e-commerce 백엔드 API
- 기술 스택: Python 3.12, FastAPI, PostgreSQL, SQLAlchemy
- 브랜치 전략: feature/* → develop → main
Task
사용자 주문 내역 조회 API 엔드포인트를 구현하세요.
- GET /api/v1/orders?user_id={id}&status={status}
- 페이지네이션 지원 (limit, offset)
- 응답 형식: JSON (orders 배열 + total_count)
Constraints
- 기존 OrderModel 스키마를 수정하지 마세요
- 새로운 의존성 추가 금지
- 테스트 커버리지 80% 이상 유지
File Scope
- 수정 대상: src/api/routes/orders.py, src/services/order_service.py
- 테스트: tests/api/test_orders.py
참고 파일: src/api/routes/products.py (유사 패턴)
3단계: 수락 기준(Acceptance Criteria) 정의
수락 기준은 Devin이 작업 완료를 판단하는 체크리스트입니다. SMART 원칙(구체적, 측정 가능, 달성 가능, 관련성, 시한)을 적용하세요.
## Acceptance Criteria
기능 요구사항
- GET /api/v1/orders 엔드포인트가 200 상태 코드를 반환한다
- user_id 필터링이 정상 동작한다
- status 필터링이 pending, completed, cancelled을 지원한다
- limit/offset 파라미터로 페이지네이션이 동작한다
- 잘못된 파라미터에 대해 422 에러를 반환한다
비기능 요구사항
- 응답 시간 200ms 이하 (1000건 기준)
- SQL 쿼리 N+1 문제 없음
- Pydantic 스키마로 응답 직렬화
코드 품질
- pytest 테스트 최소 5개 작성
- mypy 타입 체크 통과
- ruff 린트 에러 없음
기존 테스트 전체 통과
4단계: 스냅샷 리뷰 워크플로우
스냅샷 리뷰는 Devin의 작업 진행 상황을 중간 점검하는 프로세스입니다. 전체 작업이 완료되기 전에 방향 수정이 가능하므로 재작업을 최소화합니다.
# 세션 중간 스냅샷 요청
devin session snapshot --session-id SESSION_ID
스냅샷 diff 확인
devin session diff —session-id SESSION_ID —snapshot latest
특정 파일의 변경사항만 확인
devin session diff —session-id SESSION_ID —file src/api/routes/orders.py
플레이북에 스냅샷 체크포인트를 명시하면 Devin이 자동으로 중간 보고를 합니다.
## Checkpoints
- 라우트 스켈레톤 완성 후 → 스냅샷 제출 (구조 확인)
- 서비스 로직 구현 후 → 스냅샷 제출 (쿼리 최적화 확인)
- 테스트 작성 완료 후 → 스냅샷 제출 (커버리지 확인)
린트/타입체크 통과 후 → 최종 PR 제출
5단계: 반복 피드백 루프 구성
Devin 세션 내에서 피드백을 전달하면 실시간으로 코드를 수정합니다. 효과적인 피드백은 구체적이고 실행 가능해야 합니다.
# 세션 내 피드백 전달
devin session message --session-id SESSION_ID \
--message "order_service.py의 get_orders 함수에서 \
joinedload 대신 selectinload를 사용해주세요. \
1:N 관계에서 selectinload가 더 효율적입니다."
특정 파일에 대한 피드백
devin session feedback —session-id SESSION_ID
—file src/api/routes/orders.py
—line 45
—comment “status 파라미터에 Enum validation을 추가해주세요”
| 피드백 유형 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 버그 수정 | ”이거 틀렸어요" | "line 32: offset이 음수일 때 ValueError가 발생합니다. ge=0 validator를 추가하세요” |
| 스타일 변경 | ”코드 스타일 고쳐주세요" | "함수명을 get_user_orders로 변경하고, 독스트링에 Returns 섹션을 추가하세요” |
| 구조 변경 | ”리팩토링 필요" | "필터 로직을 OrderFilter 클래스로 분리하세요. products.py의 ProductFilter 패턴을 참조하세요” |
Pro Tips: 파워 유저를 위한 고급 전략
- Knowledge Base 연동: 플레이북에
## References섹션을 추가하여 팀 코딩 컨벤션 문서, ADR(Architecture Decision Records)을 링크하면 Devin이 컨텍스트를 더 잘 이해합니다.- 플레이북 템플릿 재사용: 반복적인 작업 유형(버그 수정, API 추가, 리팩토링)별로 템플릿을 만들고 변수화하세요.- CI 연동 자동 검증: PR 생성 시 자동으로 린트, 테스트, 타입 체크가 실행되도록 설정하면 수락 기준 검증이 자동화됩니다.- 작업 범위 제한: 하나의 세션에 하나의 논리적 작업만 할당하세요. 범위가 넓을수록 첫 승인률이 급격히 떨어집니다.- Negative Constraints 활용: “하지 말아야 할 것”을 명시하면 불필요한 변경을 방지할 수 있습니다.## Anti-Patterns (하지 말 것) - 기존 API 엔드포인트의 시그니처를 변경하지 마세요
- 새로운 ORM 모델을 생성하지 마세요
- print() 디버깅 코드를 남기지 마세요
requirements.txt를 수정하지 마세요
Troubleshooting: 자주 발생하는 문제
문제: Devin이 잘못된 파일을 수정함
**원인:** File Scope가 명시되지 않아 Devin이 관련 파일을 스스로 판단함.
**해결:** 플레이북에 ## File Scope 섹션을 추가하고 수정 대상 파일을 명확히 지정하세요.
문제: PR이 기존 테스트를 깨뜨림
원인: 수락 기준에 기존 테스트 통과 조건이 누락됨.
해결: - [ ] 기존 테스트 전체 통과 (pytest —tb=short)를 수락 기준에 항상 포함하세요.
문제: Devin이 불필요한 리팩토링을 수행함
원인: 작업 범위가 모호하여 Devin이 “개선”을 시도함.
해결: Constraints에 요청된 변경사항만 구현하세요. 추가적인 리팩토링이나 최적화를 수행하지 마세요를 추가하세요.
PR 첫 승인률 체크리스트
- 컨텍스트(프로젝트, 스택, 브랜치 전략)가 명시되어 있는가- 태스크가 단일 책임 원칙을 따르는가- 수락 기준이 5개 이상 구체적으로 정의되어 있는가- 파일 범위가 제한되어 있는가- Anti-Pattern이 명시되어 있는가- 스냅샷 체크포인트가 2개 이상 설정되어 있는가- 참고 파일(유사 패턴)이 지정되어 있는가
자주 묻는 질문 (FAQ)
Q1: 플레이북 없이 Devin을 사용하면 어떤 차이가 있나요?
플레이북 없이 자연어 프롬프트만 사용하면 Devin이 작업 범위, 코딩 스타일, 테스트 요구사항을 스스로 판단합니다. 이는 팀의 기대와 불일치할 확률이 높아 PR 리뷰 라운드가 평균 23회 증가하는 경향이 있습니다. 구조화된 플레이북을 사용하면 첫 승인률을 4060%에서 80% 이상으로 끌어올릴 수 있습니다.
Q2: 스냅샷 체크포인트는 몇 개가 적절한가요?
작업 규모에 따라 다르지만, 일반적으로 2~4개가 적절합니다. 너무 많으면 워크플로우가 느려지고, 너무 적으면 방향 수정이 어렵습니다. 핵심 로직 구현 후 1회, 테스트 작성 후 1회를 최소 기준으로 설정하세요.
Q3: 여러 세션에서 동일한 플레이북을 재사용할 수 있나요?
네, 플레이북을 마크다운 파일로 리포지토리의 playbooks/ 디렉토리에 저장하고 템플릿 변수를 활용하면 재사용이 가능합니다. 예를 들어 {{ENDPOINT_PATH}}, {{MODEL_NAME}} 같은 변수를 정의하고 세션 시작 시 값을 주입하는 방식으로 운영하면 효율적입니다.