Article
AI Driven Development 적용 방법 2: 팀 규칙과 컨텍스트 설계
목차
AI Driven Development를 팀에 적용하려면 개인의 프롬프트 실력보다 저장소 안의 공통 규칙과 컨텍스트 관리가 더 중요합니다. 이 글은 3부작 중 2탄으로, AI가 팀의 아키텍처·코딩 스타일·테스트 기준을 반복해서 따르게 만드는 방법을 다룹니다. 글을 읽고 나면 저장소 규칙 파일, 작업별 컨텍스트 묶음, PR 리뷰 기준을 설계해 팀 단위로 AI 활용 방식을 맞출 수 있습니다.
이 글은 2026년 7월 1일 기준의 GitHub Copilot 문서와 OpenAI Codex 문서를 참고했습니다. 도구별 세부 기능은 바뀔 수 있으므로, 특정 UI보다 팀에서 오래 유지할 수 있는 규칙 설계에 초점을 맞춥니다.
1탄에서 이어지는 문제
1탄에서는 AI Driven Development의 기본 루프를 정의 → 분해 → 생성 → 검증으로 정리했습니다. 개인 작업에서는 이 루프만으로도 꽤 많은 시행착오를 줄일 수 있습니다. 하지만 팀으로 확장하면 다른 문제가 생깁니다.
같은 요구사항을 두고도 개발자마다 AI에게 주는 설명이 다르면 결과가 달라집니다. 어떤 사람은 테스트를 먼저 만들고, 어떤 사람은 컨트롤러부터 만들고, 어떤 사람은 기존 아키텍처를 무시한 새 헬퍼 클래스를 추가할 수 있습니다. 그러면 AI를 썼는데도 팀의 코드 일관성은 오히려 약해질 수 있습니다.
따라서 2탄의 핵심 질문은 이것입니다. AI가 매번 새 팀원처럼 행동하지 않게 하려면, 어떤 규칙과 컨텍스트를 저장소 안에 두어야 할까?
팀 적용의 핵심은 프롬프트가 아니라 기준이다
프롬프트는 실행 시점의 요청입니다. 기준은 반복해서 지켜야 하는 약속입니다. 팀에서 AI를 안정적으로 쓰려면 매번 긴 프롬프트를 잘 쓰는 사람에게 의존하기보다, 저장소 안에 기준을 남겨야 합니다.
기준이 없으면 AI는 일반적인 모범 사례를 따르려고 합니다. 하지만 실무 코드베이스는 일반적인 모범 사례만으로 설명되지 않습니다. 이미 선택한 아키텍처, 예외 처리 방식, 테스트 계층, 패키지 구조, 배포 제약, 보안 규칙이 있기 때문입니다.
예를 들어 어떤 팀은 헥사고날 아키텍처를 사용해 외부 API 호출을 포트 뒤에 둡니다. 다른 팀은 단순한 레이어드 아키텍처를 쓰고, 서비스에서 직접 클라이언트를 호출할 수 있습니다. 둘 중 하나가 항상 옳은 것이 아니라, 해당 저장소의 일관성이 중요합니다. AI에게 이 차이를 알려 주지 않으면 그럴듯하지만 팀과 맞지 않는 코드를 만들 수 있습니다.
저장소 규칙 파일에 담아야 할 내용
저장소 규칙 파일은 AI와 사람 리뷰어가 함께 보는 짧은 개발 계약입니다. 이름은 팀 도구에 맞게 정하면 됩니다. 예를 들어 AGENTS.md, .github/copilot-instructions.md, CONTRIBUTING.md, docs/development-rules.md처럼 둘 수 있습니다.
중요한 것은 파일 이름보다 내용입니다. 규칙 파일에는 원칙만 길게 쓰기보다, AI가 코드 생성 시 바로 적용할 수 있는 구체적인 경계를 담아야 합니다.
| 영역 | 규칙에 담을 질문 | 예시 |
|---|---|---|
| 아키텍처 | 새 코드가 들어갈 경계는 어디인가? | 외부 시스템 호출은 adapter에서만 수행한다 |
| 코딩 스타일 | 기존 코드와 맞춰야 할 표현은 무엇인가? | Java record는 DTO에만 사용한다 |
| 테스트 | 어떤 테스트를 먼저 작성해야 하는가? | 도메인 정책은 단위 테스트로 검증한다 |
| 오류 처리 | 예외와 응답 코드는 어떻게 매핑하는가? | 비즈니스 충돌은 409로 반환한다 |
| 보안 | 절대 프롬프트에 넣으면 안 되는 것은 무엇인가? | 토큰, 고객 원문 데이터, 운영 비밀값 |
| 변경 범위 | 하지 말아야 할 자동 개선은 무엇인가? | 요청과 무관한 리팩터링 금지 |
이 표의 해석이 중요합니다. “좋은 코드를 작성한다”는 규칙은 너무 넓습니다. AI가 무엇을 바꿔야 하고 무엇을 건드리면 안 되는지 판단하기 어렵습니다. 반대로 “외부 API 호출은 ExternalApiPort를 통해 application 계층에서 의존하고, 구현은 adapter에 둔다”는 규칙은 코드 생성에 직접 영향을 줍니다.
규칙 파일 예시
아래 예시는 Spring Boot 백엔드 저장소를 가정한 규칙 파일입니다. 실제 팀에서는 더 짧게 시작해도 됩니다. 처음부터 완벽한 문서를 만들기보다, AI가 자주 틀리는 지점을 발견할 때마다 규칙을 보강하는 방식이 좋습니다.
# AI 개발 규칙
## 기본 원칙
- 요청한 작업과 직접 관련된 파일만 수정한다.
- 기존 public API, URL, 이벤트 이름은 명시 요청 없이는 바꾸지 않는다.
- 새 추상화는 중복이 실제로 생긴 뒤에만 추가한다.
- 보안 토큰, 고객 개인정보, 운영 비밀값을 예제로도 작성하지 않는다.
## 아키텍처
- application 계층은 도메인 정책과 유스케이스를 담당한다.
- 외부 API, DB, 메시징 구현은 adapter 계층에 둔다.
- application 계층은 adapter 구현 클래스를 직접 의존하지 않는다.
- 도메인 객체는 프레임워크 annotation에 의존하지 않는다.
## 테스트
- 도메인 정책은 단위 테스트로 먼저 검증한다.
- API 응답 코드는 통합 테스트에서 확인한다.
- AI가 만든 테스트는 요구사항 언어로 이름을 작성한다.
- 단순 getter/setter만 확인하는 테스트는 추가하지 않는다.
## 리뷰 기준
- 변경 범위가 작업 설명보다 넓으면 이유를 설명한다.
- 예외 흐름, 권한, 중복 요청, 롤백 가능성을 우선 검토한다.
- 스타일 취향보다 동작 오류와 회귀 위험을 우선한다.
이 문서는 AI만을 위한 문서가 아닙니다. 새 팀원이 온보딩할 때도 읽을 수 있어야 합니다. 사람이 이해하기 어려운 규칙은 AI에게도 일관되게 적용되기 어렵습니다. 규칙은 짧고 명령형으로 쓰되, 실제 코드 경계가 드러나야 합니다.
컨텍스트는 전체 저장소가 아니라 작업 묶음이다
AI에게 “저장소 전체를 보고 알아서 해 줘”라고 맡기고 싶을 때가 있습니다. 하지만 컨텍스트가 많아질수록 중요한 신호와 관련 없는 정보가 섞입니다. 컨텍스트 설계의 목표는 모든 파일을 넣는 것이 아니라, 이번 작업의 판단에 필요한 자료를 묶어 주는 것입니다.
작업별 컨텍스트는 다음 네 가지로 나눌 수 있습니다.
| 컨텍스트 종류 | 포함할 자료 | 제외할 자료 |
|---|---|---|
| 정책 컨텍스트 | 요구사항, 수용 기준, 예외 조건 | 아직 합의되지 않은 추측 |
| 코드 컨텍스트 | 유사 구현, 도메인 모델, 테스트 예시 | 오래된 패턴, 관련 없는 유틸 |
| 운영 컨텍스트 | 배포 순서, 장애 이력, 지표 기준 | 민감 로그 원문, 비밀값 |
| 리뷰 컨텍스트 | 변경 diff, 체크리스트, 실패 조건 | 전체 저장소 덤프 |
컨텍스트는 양보다 밀도가 중요합니다. 주문 취소 API를 만들 때 결제, 배송, 주문 상태 전이를 보여 주는 파일은 중요합니다. 반면 같은 프로젝트의 회원 가입 화면 코드는 프레임워크 사용 예시로 보일 수는 있지만, 도메인 판단에는 방해가 될 수 있습니다.
작업별 컨텍스트 템플릿
팀에서 반복적으로 AI에게 작업을 맡긴다면 다음 템플릿을 사용할 수 있습니다. 이 템플릿은 이슈 본문, PR 설명, AI 작업 요청에 거의 그대로 재사용할 수 있습니다.
## 작업 목표
- 무엇을 해결하려는가?
## 변경 범위
- 수정할 계층:
- 수정할 파일 후보:
- 건드리지 않을 영역:
## 도메인 규칙
- 성공 조건:
- 실패 조건:
- 권한 조건:
- 중복 요청 처리:
## 참고 컨텍스트
- 유사 구현:
- 테스트 예시:
- 에러 응답 규칙:
- 관련 문서:
## AI에게 요청할 일
- 먼저 할 일:
- 하지 말아야 할 일:
- 출력 형식:
## 검증
- 실행할 테스트:
- 리뷰에서 볼 위험:
- 배포 전 확인:
이 템플릿의 장점은 프롬프트와 작업 문서가 분리되지 않는다는 점입니다. 개발자가 AI에게 준 맥락을 리뷰어도 볼 수 있습니다. 리뷰어는 “AI가 왜 이런 코드를 만들었는지”가 아니라 “우리가 준 기준을 지켰는지”를 확인하면 됩니다.
실전 예제: Spring Boot 작업 컨텍스트 만들기
예를 들어 주문 상태 변경 API를 추가한다고 가정해 보겠습니다. AI에게 바로 컨트롤러를 만들라고 요청하면 기존 도메인 규칙을 놓칠 수 있습니다. 먼저 작업 컨텍스트를 다음처럼 정리합니다.
작업 목표:
- 결제 완료 주문을 배송 준비 상태로 변경하는 API를 추가한다.
변경 범위:
- OrderApplicationService에 유스케이스를 추가한다.
- OrderStatusController에 PATCH API를 추가한다.
- OrderStatusChanged 이벤트 발행을 추가한다.
- 기존 결제 승인 로직은 수정하지 않는다.
도메인 규칙:
- PAID 상태에서만 PREPARING으로 변경할 수 있다.
- CANCELLED, SHIPPED 상태에서는 409를 반환한다.
- 요청자는 주문 관리 권한을 가져야 한다.
- 같은 요청이 재시도되어도 이벤트는 중복 발행되지 않아야 한다.
참고 컨텍스트:
- OrderApplicationService.java
- OrderStatusController.java
- OrderStatusChanged.java
- OrderApplicationServiceTest.java
- ApiExceptionHandler.java
AI에게 요청할 일:
- 먼저 도메인 상태 전이 테스트 초안을 작성한다.
- 운영 코드는 테스트 검토 후 최소 변경으로 작성한다.
- 패키지 구조와 예외 매핑은 기존 파일을 따른다.
이 컨텍스트는 구현보다 먼저 작성됩니다. AI가 테스트 초안을 만들면 개발자는 정책 해석이 맞는지 확인합니다. 그런 다음 구현을 요청합니다. 이렇게 하면 AI가 만든 코드가 실패하더라도 어느 기준을 잘못 이해했는지 빨리 알 수 있습니다.
아래 Java 예시는 “컨텍스트를 코드 경계로 옮기는 방식”을 보여 줍니다. 상태 전이 규칙을 컨트롤러에 흩뿌리지 않고 도메인 메서드에 모으면, AI도 테스트도 같은 경계를 바라보기 쉬워집니다.
public final class Order {
private final long id;
private final OrderStatus status;
public Order(long id, OrderStatus status) {
this.id = id;
this.status = status;
}
public Order prepareShipping() {
if (status != OrderStatus.PAID) {
throw new InvalidOrderStatusException(
"Only paid orders can be prepared for shipping."
);
}
return new Order(id, OrderStatus.PREPARING);
}
}
실무에서는 메시지 발행, 권한 확인, 멱등성 처리가 더 필요합니다. 하지만 도메인 상태 전이를 한곳에 모아 두면 컨텍스트를 줄이기 쉬워집니다. AI에게도 “주문 상태 규칙은 Order의 메서드와 테스트를 기준으로 판단하라”고 말할 수 있습니다.
도구별 지침과 저장소 규칙을 분리하기
팀에서 여러 AI 도구를 쓰면 도구별 설정 파일이 늘어납니다. GitHub Copilot은 저장소 지침과 프롬프트 파일을 사용할 수 있고, Codex는 저장소의 AGENTS.md 같은 지침을 읽어 작업 방식에 반영할 수 있습니다. 세부 기능은 도구마다 다르지만, 공통 규칙과 도구별 사용법은 분리하는 편이 좋습니다.
| 문서 | 목적 | 자주 바뀌는가 |
|---|---|---|
CONTRIBUTING.md | 사람을 위한 기여 절차 | 낮음 |
docs/architecture.md | 아키텍처 결정과 경계 | 낮음 |
AGENTS.md | AI 작업 시 지켜야 할 행동 규칙 | 중간 |
.github/copilot-instructions.md | Copilot에 제공할 저장소 지침 | 중간 |
| PR 템플릿 | 리뷰어와 작성자의 확인 항목 | 중간 |
| 작업별 프롬프트 파일 | 반복 작업 요청 형식 | 높음 |
공통 규칙은 특정 도구에 갇히지 않게 둡니다. 예를 들어 “외부 API 호출은 adapter에서만 수행한다”는 Copilot에도, Codex에도, 사람 리뷰어에게도 같은 규칙입니다. 반면 “응답 형식은 findings-first로 작성한다”처럼 도구 상호작용에 가까운 내용은 AI 지침 파일에 둘 수 있습니다.
이 분리가 없으면 도구를 바꿀 때 팀 규칙까지 같이 흔들립니다. 팀이 지키는 개발 기준은 오래 살아야 하고, 도구별 instructions는 그 기준을 각 도구에 전달하는 어댑터처럼 생각하면 됩니다.
PR 리뷰 기준까지 AI 친화적으로 만들기
AI를 도입하면 PR 리뷰도 바뀝니다. 리뷰어는 생성된 코드의 스타일보다 변경이 주어진 컨텍스트를 지켰는지 확인해야 합니다. 그러려면 PR 템플릿도 AI 시대에 맞게 조금 조정할 필요가 있습니다.
## 작업 요약
-
## AI 사용 여부
- [ ] AI로 초안 작성
- [ ] AI로 테스트 후보 작성
- [ ] AI로 diff 리뷰
- [ ] 사용하지 않음
## 제공한 컨텍스트
- 작업 목표:
- 참고 파일:
- 지킨 규칙:
## 검증
- [ ] 단위 테스트 실행
- [ ] 통합 테스트 실행
- [ ] 수동 확인
- [ ] 실행하지 못한 검증과 이유:
## 리뷰어가 중점적으로 볼 부분
- 권한:
- 예외 흐름:
- 중복 요청:
- 배포/롤백:
이 템플릿은 AI 사용 여부를 감시하기 위한 문서가 아닙니다. 리뷰어가 검토해야 할 맥락을 줄이기 위한 문서입니다. 어떤 컨텍스트를 줬고 어떤 검증을 했는지 남기면, 리뷰는 “AI가 썼냐”보다 “품질 기준을 통과했냐”에 집중할 수 있습니다.
보안과 개인정보 경계 정하기
컨텍스트 설계에서 가장 조심해야 할 부분은 민감 정보입니다. AI에게 좋은 컨텍스트를 주겠다는 이유로 운영 로그 원문, 고객 개인정보, 토큰, 내부 인증 정보를 넣으면 안 됩니다. 개발 속도보다 데이터 보호가 먼저입니다.
팀 규칙에는 다음 내용을 명확히 적어야 합니다.
- 운영 비밀값과 API 키는 프롬프트에 포함하지 않는다.
- 고객 식별 정보는 마스킹하거나 재현 가능한 더미 데이터로 바꾼다.
- 장애 로그는 필요한 필드만 추출하고 원문 전체를 붙이지 않는다.
- 권한 변경, 결제, 삭제 작업은 AI 제안만으로 실행하지 않는다.
- AI가 생성한 코드에도 기존 보안 리뷰 기준을 동일하게 적용한다.
특히 프롬프트에는 코드보다 더 넓은 정보가 들어갈 때가 많습니다. 버그를 설명하다 보면 고객 사례, 내부 운영 절차, 장애 시간표가 함께 섞일 수 있습니다. 팀은 “무엇을 넣으면 좋은가”뿐 아니라 “무엇을 절대 넣지 않는가”를 같이 정해야 합니다.
규칙은 짧게 시작하고 실패에서 보강한다
처음부터 완벽한 AI 개발 규칙을 만들려고 하면 문서가 길어지고 아무도 읽지 않습니다. 좋은 출발점은 한 페이지입니다. 팀이 자주 겪는 문제 5개만 먼저 적고, 실제 PR에서 반복되는 실수를 기준으로 보강합니다.
예를 들어 다음과 같은 문제가 반복된다면 규칙을 추가할 수 있습니다.
- AI가 요청과 무관한 리팩터링을 한다.
- 테스트가 구현 세부사항만 검증한다.
- 예외를 모두 500으로 반환한다.
- 외부 API 클라이언트를 application 계층에서 직접 생성한다.
- 마이그레이션 롤백을 고려하지 않는다.
규칙 추가는 회고처럼 다루면 좋습니다. “누가 실수했는가”보다 “다음에 AI와 사람이 같은 실수를 덜 하려면 어떤 문장을 저장소에 남길 것인가”를 묻습니다. 이렇게 쌓인 규칙은 팀의 개발 지식이 됩니다.
자주 하는 실수와 주의사항
규칙 파일을 너무 추상적으로 쓴다
“좋은 테스트를 작성한다”, “클린 코드를 지향한다”는 말은 방향은 맞지만 실행 기준이 약합니다. AI에게는 구체적인 금지와 선호가 필요합니다. “도메인 정책은 단위 테스트로 먼저 작성하고, 단순 getter/setter 테스트는 추가하지 않는다”처럼 행동으로 바꿀 수 있어야 합니다.
모든 컨텍스트를 한 번에 제공한다
전체 저장소를 넣으면 AI가 더 잘할 것 같지만 실제로는 관련 없는 패턴까지 따라 할 수 있습니다. 작업에 필요한 파일과 규칙을 골라야 합니다. 컨텍스트 선택은 개발자의 중요한 역할입니다.
도구별 instructions에 팀 지식을 흩어 놓는다
Copilot 설정에는 있고 Codex 지침에는 없는 규칙이 생기면 도구마다 다른 결과가 나옵니다. 공통 개발 기준은 한곳에 두고, 도구별 파일은 그 기준을 전달하는 얇은 계층으로 유지하는 편이 안전합니다.
AI 사용 사실만 기록하고 기준은 기록하지 않는다
“AI 사용함”이라는 표시만으로는 리뷰에 도움이 되지 않습니다. 어떤 작업 목표와 참고 파일, 어떤 제약을 줬는지가 더 중요합니다. 리뷰어는 AI 사용 여부보다 제공된 기준과 결과의 일치 여부를 확인해야 합니다.
보안 경계를 프롬프트 예절로만 다룬다
민감 정보를 넣지 말자는 말만으로는 부족합니다. 로그 마스킹, 더미 데이터 생성, 비밀값 스캔, 권한 있는 도구 실행 제한 같은 시스템 장치가 함께 필요합니다. 특히 운영 데이터가 들어간 이슈와 장애 분석에서는 더 보수적으로 접근해야 합니다.
팀에 적용하는 순서
AI 규칙과 컨텍스트 설계를 팀에 적용할 때는 작은 순서로 시작하는 편이 좋습니다.
- 최근 PR 5개를 보고 AI가 자주 틀릴 만한 팀 규칙을 뽑는다.
- 한 페이지짜리 저장소 규칙 파일을 만든다.
- 반복 작업 1개를 골라 작업별 컨텍스트 템플릿을 적용한다.
- PR 템플릿에 제공한 컨텍스트와 검증 명령을 남긴다.
- 리뷰에서 반복되는 누락을 규칙 파일에 반영한다.
- 한 달 뒤 규칙 중 실제로 쓰이지 않는 문장을 삭제한다.
규칙은 많을수록 좋은 것이 아닙니다. 읽히고 적용되는 규칙만 가치가 있습니다. AI가 자주 어기는 규칙은 더 구체적으로 바꾸고, 사람이 읽지 않는 규칙은 줄여야 합니다.
3탄으로 이어지는 질문
2탄까지 적용하면 팀은 AI에게 더 일관된 컨텍스트를 줄 수 있습니다. 하지만 여기서 끝나면 “느낌상 좋아졌다”에 머물 수 있습니다. 실제로 개발 속도가 빨라졌는지, 리뷰 품질이 좋아졌는지, 결함이 줄었는지 확인해야 합니다.
3탄에서는 AI Driven Development를 도입한 뒤 품질과 운영 안정성을 어떻게 측정할지 다룰 예정입니다. 단순히 생성 코드량이나 작업 시간을 보는 것이 아니라, 재작업률, 리뷰 지연, 테스트 실패, 장애와 배포 안정성을 함께 보는 방법을 정리하겠습니다.
결론 및 도움말
AI Driven Development를 팀에 적용하는 핵심은 더 긴 프롬프트를 잘 쓰는 사람이 되는 것이 아닙니다. 저장소 안에 팀의 아키텍처, 테스트, 보안, 리뷰 기준을 남기고, 작업마다 필요한 컨텍스트를 작게 묶어 제공하는 것입니다.
AI가 좋은 팀원처럼 일하려면 팀의 기준을 배워야 합니다. 그 기준은 말로 흩어져 있으면 반복되지 않습니다. 규칙 파일, 컨텍스트 템플릿, PR 리뷰 기준으로 남길 때 AI와 사람 모두 같은 방향으로 움직일 수 있습니다.