팀 AI 개발 워크플로Team AI Development Workflow
📅
들어가기 전에 🔗
팀원마다 AI를 쓰는 방식이 다르면 PR에 남는 정보도 달라집니다.
어떤 PR은 변경 이유와 테스트 결과가 명확하지만, 다른 PR은 “AI로 구현했고 동작합니다”라는 설명만 있습니다.
코드는 빨리 만들어졌는데 검토자는 다시 요구사항을 찾고 검증 명령을 확인해야 합니다.
이 시리즈에서는 필요한 맥락을 전달하고, 모델을 선택하고, 결과를 검증하는 방법을 각각 다뤘습니다.
마지막 편에서는 이 기법들을
다음 사람이 판단할 근거가 이어지는 개발 흐름
으로 묶어 보겠습니다.
예시는 기존 서비스에 검색어와 상태 필터를 추가하는 작업입니다.
소개하는 문서와 결과는 적용 방법을 설명하는 예시이며, 특정 프로젝트에서 실행한 결과나 생산성 측정치는 아닙니다.작업의 시작 🔗
구현을 맡기기 전에 완료했음을 어떻게 확인할지 정합니다.
“검색을 개선해 줘” 대신 사용자의 행동과 결과를 적습니다.
이번 작업의 완료 조건은 검색어와 상태 필터가 URL에 반영되고, 새로고침과 뒤로 가기 뒤에도 화면이 그 값을 복원하는 것입니다.
빈 결과와 오류 표시도 포함하고, 정렬 규칙 변경과 DB 구조 변경은 제외합니다.
작업 책임자는 이 조건과 변경 경계를 확정합니다.
AI는 기존 코드의 제약과 필요한 선택지를 찾아 설명할 수 있지만, 서로 다른 제품 동작을 임의로 확정하지 않도록 요청에 기준을 넣습니다.
기존 요구사항으로 판단할 수 있는 구현 선택은 그 범위 안에서 진행합니다.
task_id: search-filter
goal: 검색어와 상태 필터를 URL과 동기화
acceptance:
- 검색 시 q와 status가 URL에 반영됨
- 새로고침 뒤 URL과 화면 필터가 일치함
- 뒤로 가기 뒤 이전 필터가 복원됨
- 빈 결과와 API 오류를 구분해 표시함
scope:
include:
- 검색 폼과 상태 처리
- 기존 검색 API의 필터 처리
- 관련 테스트
exclude:
- 정렬 규칙 변경
- DB 구조 변경
contract: docs/contracts/search-filter.md
verification:
- 저장소에 정의된 타입 검사
- 필터 파싱과 API 계약 테스트
- 실제 브라우저의 새로고침과 뒤로 가기이 파일은 도구가 자동으로 실행하는 설정이 아닙니다.
작업 요청에서 경로를 알려 주고, 실제 저장소의 명령과 문서에 맞춰 작성합니다.
짧은 수정에는 필요한 항목만 사용합니다.
👨💻
팀의 첫 적용 대상은 반복되면서 결과를 확인하기 쉬운 작업으로 고르시기 바랍니다.
완료 기준이 불명확한 큰 프로젝트를 통째로 맡기기보다, 기존 패턴이 있는 기능 하나로 요청·검증·리뷰 흐름을 먼저 맞춥니다.
단계별 근거 🔗
작업을 요청, 계약, 구현, 검증, 리뷰의 순서로 연결합니다.
각 단계가 끝나면 다음 단계가 사용할 수 있는 근거가 있어야 합니다.
측정은 전체 과정을 대상으로 하고, 결과는 다음 작업의 개선에 사용합니다.
요청, 계약, 구현, 검증, 리뷰를 연결하고 완료율과 재작업, 시간과 비용으로 개선하는 팀 AI 개발 사이클
| 단계 | 해야 할 판단 | 다음 단계에 남길 것 |
|---|---|---|
| 요청 | 목표와 완료 조건이 분명한가? | 작업 명세와 제외 범위 |
| 계약 | 화면과 API가 같은 동작을 기대하는가? | 파라미터·응답·오류 처리 기준 |
| 구현 | 필요한 정보와 변경 경로가 무엇인가? | 코드·변경 이유·남은 판단 |
| 검증 | 최종 코드가 완료 조건을 만족하는가? | 실행 명령·결과·미검증 범위 |
| 리뷰 | 의도와 회귀 위험을 검토했는가? | 리뷰 결과와 후속 조치 |
Claude Code 공식 문서도 탐색·계획·구현을 구분하고, 테스트나 기대 결과처럼 확인 가능한 기준을 제공하도록 권장합니다.
Claude Code 모범 사례↗
작은 작업은 탐색과 구현을 짧게 이어갈 수 있습니다.
모든 단계에 긴 보고서나 별도 회의를 만들기보다, 필요한 판단과 근거가 빠지지 않도록 사용합니다.
맥락과 계약 🔗
AI가 처음 읽을 정보는 공통 지침, 관련 진입점, 이번 작업 명세로 제한해 시작합니다.
검색 화면의 진입 파일, 기존 API 라우트, 테스트 명령 위치를 알려 주면 저장소 전체를 다시 탐색하는 일을 줄일 수 있습니다.
추가 의존성은 실제로 필요할 때 읽도록 안내합니다.
2편의
AGENTS.md·CLAUDE.md에는 저장소에서 반복 적용할 규칙을 둡니다.
4편의 작업 요청에는 이번 기능의 목표와 경계를, 10편의 인계 문서에는 진행 중 상태를 둡니다.
수명이 다른 정보를 한 파일에 계속 쌓지 않습니다.검색 계약 🔗
화면과 API가 공유할 기준을 먼저 정합니다.
예를 들어 상태 필터의 허용 값, 빈 검색어 처리, 응답 필드, 오류 상태를 문서로 남깁니다.
프론트엔드가 보내는 파라미터와 서버가 읽는 파라미터를 실제 코드에서 확인합니다.
입력: q는 검색어, status는 all 또는 active 또는 archived
빈 q: 검색어 제한 없이 상태 필터만 적용
status 누락: all로 처리
성공: HTTP 200, items 배열과 nextCursor 반환
잘못된 status: HTTP 400, INVALID_QUERY 오류 반환
빈 결과: HTTP 200, items는 빈 배열
URL 복원: 누락된 status도 화면에서는 all로 표시이 계약은 설명용으로 선택한 동작입니다.
기존 서비스에 다른 기준이 있다면 그 기준을 따르거나 변경 합의를 먼저 반영합니다.
타입 선언뿐 아니라 실제 요청과 응답도 같은 계약을 지키는지 확인합니다.
모델과 구현 🔗
기존 패턴을 따르는 필터 구현은 6편의 기본 경로에서 시작할 수 있습니다.
재현되지 않는 상태 오류나 여러 계층의 원인 분석이 필요해지면 정보 부족과 환경 문제부터 확인한 뒤 모델·추론 강도를 조정합니다.
모든 테스트 실패를 모델 성능 문제로 취급하지 않습니다.
5편의 Skill은 반복하는 절차와 기준에, MCP는 필요한 외부 상태 조회에 사용합니다.
9편의 캐싱은 반복 입력이 실제로 있을 때 측정하며 적용합니다.
이번 기능에 필요하지 않은 도구나 문서를 비용 최적화라는 이유로 추가할 필요는 없습니다.
병렬화 판단 🔗
검색 계약과 담당 파일이 안정적이라면 화면과 API 구현을 병렬로 진행할 수 있습니다.
계약이 아직 바뀌는 중이라면 먼저 확정하고 나눕니다.
병렬화할 경우 11편처럼 작업 공간과 수정 책임을 분리하고, 통합 뒤에 전체 연결을 확인합니다.
작은 기능이라면 하나의 세션으로 순서대로 구현하는 편이 인계와 통합 비용을 줄일 수도 있습니다.
검증과 재작업 🔗
7편의 검증 루프를 이번 완료 조건에 연결합니다.
필터 파싱은 단위 테스트로, API 입력·응답은 계약 테스트로, 뒤로 가기와 새로고침은 브라우저 동작으로 확인합니다.
검사의 이름보다 어떤 완료 조건을 확인했는지가 중요합니다.
| 완료 조건 | 확인 방법 예시 |
|---|---|
| q·status 반영 | 요청 파라미터와 URL 확인 |
| 누락된 status의 기본값 | 파싱 단위 테스트와 API 테스트 |
| 빈 결과와 오류 구분 | 화면 상태 테스트와 실제 응답 확인 |
| 뒤로 가기·새로고침 복원 | 브라우저 E2E 또는 기록된 수동 재현 |
OpenAI의 반복 수정 예제도 검토·수정·검증을 연결하고, 남은 실패를 다음 수정의 입력으로 전달하는 흐름을 설명합니다.
OpenAI 반복 수정 루프↗
실패하면 관찰과 가설을 구분해 다음 행동을 고릅니다.
URL은 바뀌는데 입력창만 남아 있다면 그 재현 결과를 고정하고 상태 갱신 경로를 확인합니다.
테스트 서버가 시작되지 않았다면 실행 환경부터 점검합니다.
요구사항이 서로 충돌하면 작업 책임자가 결정할 내용을 정리합니다.
🖐️
검증을 통과시키려고 완료 조건을 약하게 바꾸거나 예외 검사를 제거하지 마십시오.
요구사항이 바뀌었다면 변경 이유와 새 기준을 먼저 기록하고, 그 기준으로 다시 검증해야 합니다.
중단과 인계 🔗
같은 실패에 새로운 근거 없이 수정만 반복되면 원인 분석으로 돌아갑니다.
현재 경로와 커밋, 미커밋 변경, 통과·실패·미실행 검사, 다음 행동을 남깁니다.
다음 세션은 기록과 실제 코드를 대조한 뒤 계속합니다.
모델을 바꾸거나 세션을 새로 열 때도 작업 번호를 유지하면 재시도 비용을 한 작업으로 집계할 수 있습니다.
리뷰와 완료 🔗
리뷰 담당자는 AI의 설명뿐 아니라 실제 변경과 검증 근거를 확인합니다.
작업 책임자는 목표와 범위를, 구현 담당은 변경과 실행 결과를, 리뷰 담당은 의도와 누락을 판단합니다.
구현 담당이 AI를 사용하더라도 팀이 정한 완료 책임은 명확히 둡니다.
작업 책임자, 구현 담당, 리뷰 담당이 맡는 판단과 남겨야 할 근거를 비교한 역할 표
작은 팀에서는 한 사람이 여러 역할을 맡을 수 있습니다.
이 경우에도 구현 때의 설명을 그대로 승인하기보다 완료 조건과 변경 파일을 기준으로 다시 검토합니다.
어떤 모델을 사용했는지는 운영 기록으로 남기되, PR에는 검토에 필요한 변경 이유와 근거를 중심으로 씁니다.
문제: 검색 필터가 URL에 남지 않아 공유·새로고침 시 조건이 사라짐
변경: q·status 직렬화와 URL 변경에 따른 화면 상태 복원
범위: 검색 폼, API 필터 처리, 관련 테스트
검증: 타입 검사, 파싱·계약 테스트, 브라우저 복원 시나리오
미검증: 실행 환경이 없는 브라우저는 별도로 표시
제외: 정렬 규칙과 DB 구조는 변경하지 않음
작업 기록: docs/tasks/search-filter.yaml위 내용은 보고 형식의 예시입니다.
실제 PR에는 실행한 명령과 결과, 적용한 코드 상태를 확인할 수 있는 링크나 로그를 붙입니다.
리뷰 수정 뒤에는 영향받는 검사를 다시 실행합니다.
개발 완료, 머지, 배포는 팀의 정의에 따라 구분합니다.
이번 예시처럼 검증과 리뷰 통과를 작업 완료로 정했다면 배포 완료라고 보고하지 않습니다.
배포까지 범위에 포함했다면 기존 배포 절차와 배포 후 확인 근거를 기록합니다.
기록과 개선 🔗
반복 작업을 개선하려면 결과뿐 아니라 어디서 시간이 들었는지도 남깁니다.
8편의 완료율·사람 재작업·전체 시간·총사용량을 작업 번호에 연결합니다.
API를 쓴 경우 실제 요금 기준을, 구독 도구를 쓴 경우 확인 가능한 사용량과 한도를 기록합니다.
OpenAI의 반복 업무 자동화 사례도 작업 맥락을 정리하고 실행 결과를 기록하며, 이전 실행에서 배운 것을 다음 작업에 활용하는 방식을 소개합니다.
OpenAI의 반복 업무 워크플로 사례↗
리뷰에서 API 필드 오해가 반복됐다면 계약 문서를 개선합니다.
같은 위치를 찾는 탐색이 반복됐다면 진입점 안내를 보완합니다.
검증 대기가 길다면 실제 병목을 확인하고 관련 검사를 먼저 실행하도록 바꿉니다.
모델·지침·검증 방식을 한꺼번에 바꾸기보다 변수 하나를 조정해 같은 조건에서 비교합니다.
👨💻
매주 반복되는 문제 하나를 선택해 공통 규칙이나 작업 템플릿을 바꿔 보시기 바랍니다.
개별 작업의 모든 실패 로그를 공통 지침에 넣기보다, 다음 작업에서도 필요한 짧은 규칙과 근거 위치를 남깁니다.
시리즈 적용 순서 🔗
12편의 기법을 처음부터 모두 도입할 필요는 없습니다.
팀의 반복 문제에 맞춰 필요한 부분부터 적용하고, 측정한 결과를 바탕으로 확장합니다.
| 팀에서 반복되는 문제 | 먼저 적용할 내용 | 관련 편 |
|---|---|---|
| AI가 관련 파일을 찾느라 오래 걸림 | 최소 지침과 저장소 진입점 | 1~3편 |
| 결과가 요청과 다르게 나옴 | 작업 범위·완료 조건·계약 | 4편 |
| 문서와 도구가 과도하게 로드됨 | Skill·MCP의 조건부 로딩 | 5편 |
| 작업별 비용과 대기 시간이 불균형 | 모델·추론 강도 선택 | 6편 |
| 테스트 통과 뒤에도 재작업 발생 | 재현·검증·완료 근거 | 7편 |
| 개선 효과를 판단하기 어려움 | 작업 단위 지표와 비교 | 8편 |
| 같은 입력을 반복 처리함 | 캐시 읽기·쓰기와 총비용 확인 | 9편 |
| 세션을 바꾸면 맥락이 끊김 | 코드 상태와 인계 기록 | 10편 |
| 병렬 결과를 합칠 때 문제 발생 | 담당 경계·격리·통합 검증 | 11편 |
바로 시작하려면 작업 명세 하나, 저장소의 실제 검증 명령, 완료 보고 형식부터 맞춥니다.
이 세 가지가 운영되면 모델 라우팅이나 병렬화도 같은 완료 기준 안에서 비교할 수 있습니다.
결론 🔗
팀의 AI 개발 워크플로는 목표와 변경 경계를 정하고, 필요한 정보를 전달하고, 코드와 실행 근거를 검토하는 흐름입니다.
작업별 기록과 지표가 연결돼야 빠르게 생성한 코드가 실제로 완료한 기능으로 이어졌는지 알 수 있습니다.
12편에 걸쳐 다룬 기법의 공통 기준은
다음 판단에 필요한 정보를 남기고, 실제 결과로 확인하는 것
입니다.
반복되는 작은 작업부터 이 흐름을 적용하고, 완료율과 사람의 재작업이 어떻게 바뀌는지 확인하며 팀에 맞게 다듬어 보시기 바랍니다.