신규 프로젝트를 빠르게 이해하기 위한 프로젝트 분석 프롬프트
개발을 하다 보면 어느 순간 새로운 프로젝트를 맡게 되는 일이 꼭 생긴다.
특히 기존 서비스에 투입되거나 다른 팀에서 운영하던 시스템을 인수받는 경우라면 더 그렇다. 저장소를 처음 열어보는 순간 대부분 같은 생각을 한다.
"이 프로젝트… 어디서부터 봐야 하지?"
나 역시 실무에서 여러 번 이런 상황을 겪었다. 처음에는 가장 정석적인 방법으로 접근했다.
Controller부터 시작해서 Service, Repository를 하나씩 따라가며 구조를 이해하려고 했다. 하지만 실무 프로젝트는 생각보다 훨씬 크고 복잡하다. Spring Boot 기반 프로젝트 하나만 해도 수백 개의 클래스가 존재하고, 여기에 인증, 캐시, 메시징, 외부 API 연동 같은 요소까지 섞여 있으면 전체 흐름을 파악하는 데 상당한 시간이 필요하다.
특히 Redis, JWT 인증, Spring Security 같은 인프라 요소가 포함된 프로젝트라면 단순히 코드 몇 개를 읽는 것만으로 전체 구조를 이해하기가 쉽지 않다. 실제로 예전에 Spring Boot 기반 서비스에서 JWT 인증과 Redis 캐시가 함께 사용된 구조를 분석해야 했던 적이 있었는데, 단순히 코드만 따라가다가 구조를 파악하는 데만 몇 시간이 걸렸던 경험이 있다.
그때 느꼈던 생각은 하나였다.
"프로젝트를 좀 더 빠르게 이해할 수 있는 방법이 없을까?"
그래서 여러 가지 방법을 시도해봤고, 결국 정리하게 된 것이 바로 프로젝트 분석 프롬프트였다.
이 글에서는 내가 실제로 사용하는 프로젝트 분석 프롬프트를 공유하기 전에, 왜 이런 프롬프트가 필요했는지 그리고 사용했을 때 어떤 장점과 단점이 있는지를 먼저 이야기해보려고 한다.
문제 상황
실무에서 새로운 프로젝트를 분석해야 하는 상황은 생각보다 자주 발생한다.
대표적으로 다음과 같은 경우가 있다.
- 기존 서비스 유지보수 담당자로 투입되는 경우
- 다른 팀이 개발한 프로젝트를 인수받는 경우
- 신규 기능을 추가하기 전에 전체 구조를 이해해야 하는 경우
- 오픈소스 프로젝트 구조를 분석해야 하는 경우
이런 상황에서 가장 어려운 점은 프로젝트의 전체 구조를 빠르게 파악하는 것이다.
예를 들어 Spring Boot 프로젝트를 분석한다고 가정해보자. 보통 다음과 같은 요소들이 함께 등장한다.
- Controller
- Service
- Repository
- Entity
- DTO
- Config
- Filter
- Interceptor
- Security 설정
- JWT 인증
- Redis 캐시
이 요소들이 서로 어떻게 연결되어 있는지를 이해해야 실제로 개발을 진행할 수 있다.
특히 JWT 인증이 포함된 경우에는 Security Filter 체인을 이해해야 하고, Redis 캐시가 포함된 경우에는 어떤 데이터가 캐시에 저장되는지까지 파악해야 한다. 문제는 이런 요소들이 보통 여러 파일에 분산되어 있다는 것이다.
예를 들어 JWT 인증 로직은 다음과 같은 위치에 흩어져 있을 수 있다.
- SecurityConfig
- JwtAuthenticationFilter
- AuthenticationProvider
- TokenProvider
여기에 Redis 캐시까지 추가되면 캐시 설정, 캐시 전략, TTL 설정 등을 함께 확인해야 한다. 이런 구조를 처음부터 코드만 읽어서 이해하려고 하면 생각보다 시간이 많이 소모된다.
나도 예전에 Redis 기반 캐시와 JWT 인증이 동시에 적용된 Spring Boot 프로젝트를 분석해야 했는데, 인증 흐름과 캐시 흐름을 동시에 이해하려다 보니 어디서부터 봐야 할지 헷갈렸던 경험이 있다.
그래서 "프로젝트를 체계적으로 분석할 수 있는 질문 목록"을 만들어 보기로 했다.
내가 시도한 방법
처음에는 프로젝트를 분석하기 위해 여러 가지 방법을 시도했다.
1. 패키지 구조 먼저 보기
가장 기본적인 방법이다. 보통 다음과 같은 패키지 구조를 먼저 확인한다.
controller
service
repository
config
domain
이렇게 보면 대략적인 아키텍처는 파악할 수 있다. 하지만 실제 비즈니스 흐름이나 인증 구조, 캐시 전략 같은 부분까지 이해하기에는 부족하다.
특히 JWT 인증 로직이나 Redis 캐시 로직은 config나 filter 내부에 숨어 있는 경우가 많아서 패키지 구조만으로는 찾기 어렵다.
2. API 흐름 따라가기
두 번째로 시도했던 방법은 API 기준으로 코드를 따라가는 방식이었다.
예를 들어 Controller에 있는 API를 기준으로 Service와 Repository까지 따라가는 방식이다.
Controller → Service → Repository
이 방식은 실제 요청 흐름을 이해하는 데 도움이 된다. 하지만 프로젝트 규모가 커질수록 모든 API를 확인하기가 어렵다.
또한 JWT 인증 같은 보안 로직은 API 흐름과 별개로 Filter 단계에서 처리되는 경우가 많기 때문에 이 방식만으로는 전체 구조를 이해하기 어렵다.
3. 프로젝트 분석 프롬프트 만들기
그래서 마지막으로 시도했던 방법이 바로 프로젝트 분석 프롬프트를 만드는 것이었다.
단순히 "이 프로젝트 설명해줘"라고 묻는 것이 아니라, 프로젝트 구조를 분석하기 위한 질문들을 미리 정리해두는 방식이다.
예를 들어 다음과 같은 질문들을 포함한다.
- 전체 아키텍처 구조
- 주요 패키지 역할
- 핵심 도메인
- 인증 방식 (JWT 인증 여부)
- 캐시 사용 여부 (Redis 등)
- 주요 API 흐름
- 외부 시스템 연동 여부
- 핵심 비즈니스 로직
이렇게 질문을 구조화해두면 프로젝트 분석 결과도 훨씬 체계적으로 정리된다.
특히 Spring Boot 프로젝트에서 JWT 인증 구조나 Redis 캐시 사용 여부를 빠르게 파악하는 데 도움이 된다.
프롬프트를 사용했을 때 장점
실제로 이 방식으로 프로젝트를 분석해보면서 몇 가지 장점을 느꼈다.
1. 프로젝트 이해 속도가 빨라진다
예전에는 프로젝트 구조를 파악하는 데 반나절 이상 걸리는 경우도 있었다. 하지만 분석 프롬프트를 사용하면 전체 구조를 훨씬 빠르게 파악할 수 있다.
특히 JWT 인증 흐름이나 Redis 캐시 사용 여부 같은 부분을 빠르게 확인할 수 있다는 점이 좋았다.
2. 놓치기 쉬운 구조를 발견할 수 있다
프로젝트를 분석하다 보면 의외로 놓치는 부분이 많다. 예를 들어 다음과 같은 것들이다.
- JWT 인증 Filter 위치
- Security 설정 구조
- Redis 캐시 적용 범위
- 외부 시스템 연동 방식
분석 프롬프트를 사용하면 이런 부분들을 체크리스트처럼 확인할 수 있다.
3. 프로젝트 문서화를 쉽게 할 수 있다
분석 결과를 그대로 팀 위키나 내부 문서로 정리할 수도 있다. 신규 팀원이 프로젝트에 합류했을 때도 도움이 된다.
프롬프트 사용의 단점
물론 단점도 존재한다.
1. AI 분석이 항상 정확하지는 않다
AI가 코드를 분석하는 과정에서 일부 구조를 잘못 이해할 수도 있다. 특히 복잡한 도메인 로직이나 커스텀 프레임워크가 사용된 경우에는 분석 결과를 그대로 신뢰하기 어렵다.
그래서 분석 결과는 참고 자료로 활용하고, 중요한 로직은 반드시 직접 코드를 확인하는 것이 좋다.
2. 결국 코드를 읽는 과정은 필요하다
프로젝트 분석 프롬프트는 어디까지나 초기 구조를 파악하는 도구일 뿐이다. 실제 개발을 진행하려면 결국 코드를 직접 읽어야 한다.
정리 및 느낀 점
실무에서 새로운 프로젝트를 분석하는 일은 생각보다 많은 시간을 잡아먹는다. 특히 Spring Boot 기반 프로젝트에서 JWT 인증, Redis 캐시, Security 설정까지 섞여 있다면 구조 파악이 쉽지 않다.
그래서 나는 프로젝트를 처음 접할 때 프로젝트 분석 프롬프트를 먼저 사용해서 전체 구조를 빠르게 파악하는 방식을 사용하고 있다.
물론 이 방법이 완벽한 해결책은 아니다. AI 분석이 틀릴 수도 있고, 결국 코드를 직접 읽어야 하는 순간도 온다. 하지만 최소한 프로젝트의 큰 그림을 빠르게 이해하는 데는 꽤 도움이 된다.
다음 글에서는 내가 실제로 사용하는 신규 프로젝트 분석 프롬프트를 그대로 공유해보려고 한다. 새로운 프로젝트를 자주 분석해야 하는 개발자라면 한 번쯤 유용하게 사용할 수 있을 것이다.
'AI > 프롬프트' 카테고리의 다른 글
| 신규 프로젝트 분석 프롬프트 (0) | 2026.03.16 |
|---|