OpenCode로 리팩토링·버그픽스 워크플로우 만들기: 실전 템플릿 5종
OpenCode를 실무에 붙일 때 바로 써먹을 수 있는 리팩토링/버그픽스 워크플로우 템플릿 5가지를 정리했습니다. 안전장치, 체크리스트, 예시 프롬프트까지 포함.
목차
- 0. 시작 전 원칙(안전장치)
- 1. 템플릿 #1: 소규모 리팩토링(가독성/구조 개선)
- 2. 템플릿 #2: 성능 개선(병목 추정 → 검증)
- 3. 템플릿 #3: 버그 재현 → 원인 후보 → 최소 수정
- 4. 템플릿 #4: 테스트 추가/보강(회귀 방지)
- 5. 템플릿 #5: 코드리뷰 보조(리스크/엣지케이스 체크)
- 자주 하는 실수
- FAQ
- 정리
0. 시작 전 원칙(안전장치)
OpenCode 같은 코딩 에이전트 도구를 “실전”에 붙일수록 중요한 건 속도보다 안전한 반복입니다. 아래 4가지는 최소 안전장치로 추천합니다.
- 브랜치 분리: 작업은 항상 별도 브랜치에서
- 변경 범위 제한: 한 번에 한 모듈/한 기능만
- 검증 루틴 고정: 테스트/린트/빌드 중 최소 1개는 매번
- 리뷰 습관: 적용 전 diff를 사람이 확인
1. 템플릿 #1: 소규모 리팩토링(가독성/구조 개선)
언제 쓰나
- 함수/클래스가 너무 커져서 읽기 힘들 때
- 중복 코드가 늘어나고 있을 때
체크리스트
- 공개 API/동작 변경 금지
- 함수 분리 후 이름/책임 명확화
- 테스트 1회 이상 통과
예시 프롬프트(복붙용)
목표: 가독성 개선(동작 동일 유지)
제약: public API 변경 금지, 파일 범위는 ./src/foo/* 로 제한
작업: 중복 로직을 헬퍼 함수로 분리하고, 함수/변수명을 의도 중심으로 바꿔줘
검증: 기존 테스트 통과 + lint 통과2. 템플릿 #2: 성능 개선(병목 추정 → 검증)
언제 쓰나
- 특정 API/페이지가 느려졌을 때
- 대량 처리 작업에서 시간이 튈 때
체크리스트
- “추정”이 아니라 측정(로그/프로파일/벤치) 기반
- 변경 전/후 지표 비교(시간, 메모리, 호출 횟수)
예시 프롬프트
목표: 실행시간 20% 단축
입력: 느린 구간의 로그/벤치 결과를 기반으로 병목 후보를 3개 제시하고,
가장 가능성 높은 1개에 대해 최소 수정으로 개선안을 적용해줘.
검증: 개선 전/후 벤치 로그를 출력(또는 측정 코드 추가)3. 템플릿 #3: 버그 재현 → 원인 후보 → 최소 수정
언제 쓰나
- 에러 로그가 있고 재현이 가능한 버그
체크리스트
- 재현 단계(1~5)를 텍스트로 고정
- 원인 후보 3개 → 가장 가능성 높은 것부터 검증
- 해결 후 회귀 테스트(최소 1개) 추가
예시 프롬프트
버그: (증상 한 줄)
재현: 1) ... 2) ... 3) ...
기대: ...
실제: ...
로그: (에러 로그 붙이기)
요청: 원인 후보 3개를 제시하고, 가장 가능성 높은 원인에 대해 최소 변경으로 수정해줘.
추가: 같은 버그가 다시 생기지 않게 테스트 1개를 추가해줘.4. 템플릿 #4: 테스트 추가/보강(회귀 방지)
언제 쓰나
- 리팩토링/버그수정 이후 불안할 때
- 핵심 로직인데 테스트가 없을 때
체크리스트
- “가장 위험한 입력 3개”부터
- 실제 버그 재현 케이스를 테스트로 고정
예시 프롬프트
대상: ./src/foo/bar.ts 의 함수 baz()
요청: 엣지케이스 3개를 포함한 테스트를 추가해줘.
조건: 테스트는 독립적으로 실행 가능해야 하고, 네트워크/외부 I/O는 목킹해줘.5. 템플릿 #5: 코드리뷰 보조(리스크/엣지케이스 체크)
언제 쓰나
- PR 리뷰 시간이 부족할 때
- 내가 놓칠 수 있는 리스크를 빨리 훑고 싶을 때
체크리스트
- 보안/권한/입력 검증 포인트
- 에러 처리/타임아웃/재시도
- 성능(불필요한 반복/쿼리)
예시 프롬프트
요청: 아래 diff(또는 변경 파일 목록)를 리뷰해줘.
관점: (1) 버그 가능성 (2) 보안/입력검증 (3) 성능 (4) 테스트 누락
출력: 우선순위 높은 이슈 TOP 5 + 근거 + 수정 제안자주 하는 실수
- 요청이 모호함: 목표/제약/검증을 안 주고 “리팩토링해줘”만 던지기
- 검증 생략: 테스트 없이 적용
- 한 번에 너무 크게: 여러 모듈을 한 번에 손대기
FAQ
Q1. 템플릿은 어떻게 관리하는 게 좋아요?
A. “프로젝트 공통” 템플릿과 “레포 전용” 템플릿을 분리해 두면 유지보수가 편합니다. (예: prompts/common/, prompts/project-a/)
Q2. 에이전트가 코드를 망치면 어떻게 하나요?
A. 브랜치/커밋 단위로 되돌릴 수 있게만 해두면 리스크가 크게 줄어듭니다. 초반엔 자동 커밋을 끄고 사람이 커밋하세요.
Q3. 어떤 템플릿부터 쓰면 효과가 크나요?
A. 대부분은 버그 재현 → 최소 수정 템플릿이 체감이 큽니다. 그리고 테스트 1개 추가까지 묶으면 품질이 확 올라갑니다.
정리
OpenCode를 잘 쓰는 핵심은 “좋은 템플릿”을 만들어 반복하는 것입니다. 위 5가지 워크플로우를 그대로 복붙해서 시작한 뒤, 본인 레포/팀 규칙에 맞게 제약과 검증을 조금씩 강화해보세요.
