코드베이스 아키텍처 온보딩 문서 생성기

**컨텍스트:** 저는 방금 프로젝트에 합류한 개발자이며, AI 코딩 어시스턴트인 여러분을 사용하여 기존 코드베이스에 대한 깊은 이해를 얻고자 합니다. 제 목표는 가능한 한 빨리 생산성을 발휘하고, 현재 시스템에 대한 확실한 이해를 바탕으로 정보에 입각한 기술적 결정을 내리는 것입니다. **주요 목표:** 이 프로젝트/워크스페이스에서 제공된 소스 코드를 분석하고, 시스템의 아키텍처, 기능, 주요 흐름, 핵심 구성 요소 및 기술 스택을 설명하는 상세하고 명확하며 잘 구조화된 Markdown 문서를 생성합니다. 이 문서는 기술 온보딩 가이드 역할을 해야 합니다. 가능할 때마다 관련 파일, 클래스 및 함수에 대한 직접 링크와 개념을 명확히 하는 데 도움이 되는 코드 예제를 제공하여 탐색성을 개선합니다. --- ## 세부 지침 - 다음 사항을 다루십시오: ### 1. README / 지침 파일 요약 - README.md, LEIAME.md, CONTRIBUTING.md 또는 유사한 문서와 같은 파일을 찾습니다. - 새 개발자에게 가장 관련성이 높은 섹션에 대한 객관적이면서도 상세한 요약을 제공합니다: - 프로젝트 개요 - 시스템을 로컬에서 설정하고 실행하는 방법 - 채택된 표준 및 규칙 - 기여 지침(사용 가능한 경우) --- ### 2. 상세 기술 스택 - 프로젝트에서 사용된 전체 기술 스택을 식별하고 나열합니다: - 프로그래밍 언어 및 감지 가능한 버전(예: package.json, pom.xml, .tool-versions, requirements.txt, build.gradle 등에서). - 주요 프레임워크(백엔드, 프론트엔드 등 - 예: Spring Boot, .NET, React, Angular, Vue, Django, Rails). - 데이터베이스: - 유형(SQL / NoSQL) - 이름(PostgreSQL, MongoDB 등) - 핵심 아키텍처 스타일(예: 모놀리스, 마이크로서비스, 서버리스, MVC, MVVM, 클린 아키텍처). - 클라우드 플랫폼(SDK 또는 구성을 통해 식별 가능한 경우 - AWS, Azure, GCP). - 빌드 도구 및 패키지 관리자(Maven, Gradle, npm, yarn, pip). - 기타 관련 기술(캐싱, 메시지 브로커, 컨테이너화 - Docker, Kubernetes). - 각 항목을 입증하는 구성 파일을 참조하고 링크합니다. --- ### 3. 시스템 개요 및 목적 - 시스템이 무엇을 하는지, 누구를 위한 것인지 명확하게 설명합니다. - 어떤 문제를 해결합니까? - 핵심 기능을 나열합니다. - 가능하면 시스템을 관련 비즈니스 도메인과 연결합니다. - 주요 기능에 대한 높은 수준의 설명을 제공합니다. --- ### 4. 프로젝트 구조 및 읽기 권장 사항 - 진입점: 코드 탐색을 어디서 시작해야 합니까? 주요 진입점을 식별합니다(예: main.go, index.js, Program.cs, app.py, Application.java). 이러한 파일에 대한 직접 링크를 제공합니다. - 일반 구성: 전체 폴더 및 파일 구조를 설명합니다. 중요한 규칙을 강조합니다. 실제 폴더 및 파일 이름 예를 사용합니다. - 구성: 주요 구성 파일이 있습니까? (예: config.yaml, .env, appsettings.json) 중요한 구성은 무엇입니까? 링크를 제공합니다. - 읽기 권장 사항: 프로젝트의 핵심 개념을 빠르게 파악하기 위해 먼저 읽어야 할 파일/모듈의 순서 또는 핵심 파일 세트를 제안합니다. --- ### 5. 핵심 구성 요소 - 가장 중요하거나 중앙적인 모듈, 클래스, 함수 또는 서비스를 식별하고 설명합니다. - 각 구성 요소의 책임을 설명합니다. - 책임과 상호 의존성을 설명합니다. - 각 구성 요소에 대해: - 대표적인 코드 스니펫 포함 - 구현된 위치에 대한 링크 제공 - 가능할 때마다 직접 링크와 코드 예제를 제공합니다. --- ### 6. 실행 및 데이터 흐름 - 가장 일반적이거나 중요한 워크플로우 또는 비즈니스 프로세스를 설명합니다(예: 주문 처리, 사용자 인증). - 데이터가 시스템을 통해 흐르는 방식을 설명합니다: - 데이터가 저장되는 위치 - 데이터가 읽히고, 수정되고, 전파되는 방식 - 가능할 때마다 예제로 설명하고 관련 함수 또는 클래스에 링크합니다. #### 6.1 데이터베이스 스키마 개요(해당하는 경우) - 데이터 집약적인 애플리케이션의 경우: - 주요 엔터티/테이블/컬렉션 식별 - 주요 관계 설명 - 가능한 경우 ORM 모델, 마이그레이션 또는 스키마 파일을 기반으로 함 --- ### 7. 종속성 및 통합 - 종속성: 사용된 주요 외부 라이브러리, 프레임워크 및 SDK를 나열합니다. 각각의 역할을 간략히 설명합니다. 구성되거나 가장 일반적으로 사용되는 위치에 대한 링크를 제공합니다. - 통합: 외부 서비스, 추가 데이터베이스, 타사 API, 메시지 브로커 등과의 통합을 식별하고 설명합니다. 통신은 어떻게 발생합니까? 담당 모듈/클래스를 지적하고 링크를 포함합니다. #### 7.1 API 문서(해당하는 경우) - 프로젝트가 API를 노출하는 경우: - API 문서 도구 또는 표준의 증거가 있습니까(예: Swagger/OpenAPI, Javadoc, 엔드포인트별 docstring)? - 이 문서는 어디에서 찾을 수 있거나 어떻게 생성할 수 있습니까? --- ### 8. 다이어그램 - 시스템 아키텍처와 동작을 시각화하기 위한 높은 수준의 다이어그램을 생성합니다: - 구성 요소 다이어그램(주요 모듈과 상호 작용 강조) - 데이터 흐름 다이어그램(정보가 시스템을 통해 이동하는 방식 표시) - 클래스 다이어그램(해당하는 경우 주요 클래스와 관계 표시) - 단순화된 배포 다이어그램(구성 요소가 실행되는 위치, 감지 가능한 경우) - 단순화된 인프라/배포 다이어그램(인프라 세부 정보가 명백한 경우) - Markdown 파일 내에서 Mermaid 구문을 사용하여 이러한 다이어그램을 생성합니다. - 다이어그램은 높은 수준이어야 합니다. 광범위한 세부 정보는 필요하지 않습니다. --- ### 9. 테스트 - 자동화된 테스트가 있습니까? - 단위 테스트 - 통합 테스트 - 엔드투엔드(E2E) 테스트 - 프로젝트에서 어디에 위치합니까? - 어떤 테스트 프레임워크가 사용됩니까? - 테스트는 일반적으로 어떻게 실행됩니까? - 테스트를 로컬에서 어떻게 실행할 수 있습니까? - 테스트와 관련된 CI/CD 전략이 있습니까? --- ### 10. 오류 처리 및 로깅 - 애플리케이션은 일반적으로 오류를 어떻게 처리합니까? - 표준 패턴이 있습니까(예: 전역 미들웨어, 사용자 정의 예외)? - 어떤 로깅 라이브러리가 사용됩니까? - 표준 로깅 형식이 있습니까? - 모니터링 도구(예: Datadog, Sentry)와의 가시적인 통합이 있습니까? --- ### 11. 보안 고려 사항 - 코드에 명백한 보안 메커니즘이 있습니까? - 인증 - 권한 부여(미들웨어/필터) - 입력 검증 - 특정 보안 라이브러리가 눈에 띄게 사용됩니까(예: Spring Security, Passport.js, JWT 라이브러리)? - 주목할 만한 보안 관행이 있습니까? - 비밀 관리 - 일반적인 공격에 대한 보호 --- ### 12. 기타 관련 관찰(빌드/배포 포함) - 빌드 또는 배포와 관련된 파일이 있습니까? - Dockerfile - docker-compose.yml - 빌드/배포 스크립트 - CI/CD 구성 파일(예: .github/workflows/, .gitlab-ci.yml) - 이러한 파일은 애플리케이션이 어떻게 빌드되고 배포되는지에 대해 무엇을 나타냅니까? - 새 개발자에게 중요하거나 특히 도움이 되는 다른 것이 있습니까? - 주석에 언급된 알려진 기술 부채 - 비정상적인 디자인 패턴 - 중요한 코딩 규칙 - 성능 메모 --- ## 최종 출력 형식 - 완전한 응답을 잘 구성된 Markdown(.md) 문서로 생성합니다. - 명확하고 직접적인 언어를 사용합니다. - 위의 번호가 매겨진 섹션에 따라 제목과 부제목으로 콘텐츠를 구성합니다. - 관련 코드 스니펫(짧고 대표적인)을 포함합니다. - 특정 코드 요소가 언급될 때마다 파일, 함수, 클래스 및 정의에 대한 클릭 가능한 링크를 포함합니다. - 가독성을 위해 위의 번호가 매겨진 섹션을 사용하여 문서를 구성합니다. 가능할 때마다: - 파일, 함수 및 클래스에 대한 클릭 가능한 링크를 포함합니다. - 짧고 대표적인 코드 스니펫을 표시합니다. - 목록에 글머리 기호 또는 표를 사용합니다. --- ### 중요 분석은 프로젝트의 모든 파일을 고려해야 합니다. 이 작업을 완전히 실행하고 시스템에 대한 완전한 이해를 달성하는 데 필요한 모든 파일을 읽고 이해합니다. --- ### 조치 현재 내 환경/워크스페이스에서 사용 가능한 소스 코드를 분석하고 요청된 대로 Markdown 문서를 생성합니다. 출력 파일 이름은 다음 형식을 따라야 합니다: <yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>