[UE5] ProjectFT#7 AI 협업 환경 구축

AI 협업 환경을 구축한 이유

프로젝트 규모가 커질수록 AI에게 매번 프로젝트 구조와 규칙을 다시 설명해야 하는 문제가 발생했다.

특히 새로운 기능을 구현하거나 기존 코드를 수정할 때마다

• 프로젝트 구조
• 클래스 역할
• 코딩 규칙
• 설계 방향

을 반복해서 전달해야 했고, 이 과정에서 컨텍스트가 부족하거나 잘못 이해되는 경우가 있었다.

이를 해결하기 위해 AI가 프로젝트를 빠르게 이해할 수 있는 문서 구조를 설계하였다.

---

AGENTS.md 작성

AGENTS.md는 AI가 프로젝트에서 따라야 하는 개발 규칙을 정리한 문서이다.

주요 내용

• 프로젝트 코딩 컨벤션
• 클래스 네이밍 규칙
• 폴더 구조
• 아키텍처 원칙
• 구현 시 지켜야 할 규칙

예를 들어

- UI는 ViewModel을 통해 접근한다.
- Actor는 UI를 직접 제어하지 않는다.
- 게임 데이터는 DataTable에서 관리한다.

와 같은 프로젝트의 공통 규칙을 기록하였다.

이를 통해 AI가 새로운 기능을 구현하더라도 기존 설계 방향을 유지할 수 있도록 하였다.

---

PROJECT_CONTEXT.md 구성

PROJECT_CONTEXT.md는 프로젝트 전체 구조를 설명하는 문서이다.

주요 내용

• 프로젝트 개요
• 시스템 구조
• 주요 클래스 역할
• 기능 간 관계
• 현재 구현 상태

예를 들어

Player
    │
    ▼
Terminal
    │
    ▼
UI
    │
    ▼
ViewModel
    │
    ▼
Subsystem

처럼 전체 아키텍처를 한눈에 이해할 수 있도록 정리하였다.

---

AI_CONTEXT.md 작성

AI_CONTEXT.md는 현재 작업 중인 기능과 최근 변경 사항을 기록하는 문서이다.

프로젝트 전체를 설명하기보다는

• 현재 작업 목표
• 최근 리팩터링 내용
• 앞으로 구현할 기능
• 주의해야 할 사항

등을 정리하였다.

이를 통해 AI가 현재 작업의 맥락을 빠르게 이해하고 이어서 작업할 수 있도록 구성하였다.

---

프로젝트 문서 구조 설계

각 문서의 역할을 명확하게 분리하였다.

AGENTS.md
    │
    ├─ 개발 규칙
    ├─ 코딩 컨벤션
    └─ 설계 원칙

PROJECT_CONTEXT.md
    │
    ├─ 프로젝트 구조
    ├─ 시스템 설명
    └─ 클래스 관계

AI_CONTEXT.md
    │
    ├─ 현재 작업
    ├─ 진행 상황
    └─ 최근 변경 사항

문서를 목적별로 분리하면서 필요한 정보만 빠르게 전달할 수 있는 구조를 만들었다.

---

컨텍스트 압축 전략

AI와 협업하면서 가장 중요하게 느낀 점은 모든 정보를 전달하는 것이 아니라, 필요한 정보를 효율적으로 전달하는 것이었다.

프로젝트 전체를 한 번에 설명하기보다

• 항상 필요한 정보 → AGENTS.md
• 프로젝트 구조 → PROJECT_CONTEXT.md
• 현재 작업 내용 → AI_CONTEXT.md

로 구분하여 필요한 문서만 참조하도록 구성하였다.

이렇게 컨텍스트를 분리하면

• 토큰 사용량을 줄일 수 있고
• AI가 불필요한 정보를 읽지 않으며
• 현재 작업에 집중할 수 있다는 장점이 있었다.

---

느낀 점

AI는 프로젝트를 스스로 기억하는 것이 아니라 전달된 컨텍스트를 기반으로 작업한다는 점을 다시 한번 느꼈다.

좋은 결과를 얻기 위해서는 질문을 잘하는 것뿐만 아니라, 프로젝트 정보를 체계적으로 정리해 전달하는 환경을 만드는 것도 중요했다.

이번 AI 협업 환경 구축을 통해 반복 설명을 줄이고, 프로젝트의 설계 방향을 유지하면서 AI와 더욱 효율적으로 협업할 수 있는 기반을 마련할 수 있었다.