낯선 코드베이스 파악하기
IBM Bob을 사용해 낯선 애플리케이션의 목적, 프로젝트 구조, 아키텍처, 기술 스택, 주요 컴포넌트, 테스트 커버리지, 배포 모델을 빠르게 파악하세요. 오래된 문서나 팀원의 도움 없이도 가능합니다.
낯선 코드베이스에서 생산성을 높이려면 보통 코드를 읽고, 문서를 찾고, 팀원에게 컨텍스트를 물어보는 데 몇 시간이 걸립니다. 이 튜토리얼에서는 Ask 모드로 Bob을 사용해 Galaxium Travels 코드베이스를 체계적으로 분석하고 애플리케이션의 전체적인 그림을 파악합니다. 구체적으로는 목적과 아키텍처, 기술 스택, 주요 컴포넌트, 유닛 및 통합 테스트 커버리지, 배포 모델을 살펴봅니다. 이후 Agent 모드로 전환해 Bob이 발견한 모든 내용을 팀 전체가 활용할 수 있는 영구적인 Markdown 참조 문서로 저장합니다.
Galaxium Travels는 React 프론트엔드, Python FastAPI 백엔드, Java Spring Boot 인벤토리 서비스를 갖춘 의도적으로 복잡한 실세계 스타일의 애플리케이션입니다. 덕분에 이 워크플로에 최적인 예시입니다.
Bob의 출력은 코드베이스의 현재 상태에 따라 달라집니다. 이 튜토리얼의 예시는 정확한 실행 결과가 아닌 대표적인 출발점으로 참고하세요. 자신의 프롬프트를 조정하고 결과를 개선하는 데 활용하세요.
학습할 주요 기능
- Ask 모드: Bob이 파일을 수정하지 않고 코드를 탐색하고 분석합니다.
- Agent 모드: Bob이 자율적으로 파일을 작성해 생성된 산출물을 프로젝트에 저장합니다.
- 컨텍스트 멘션:
@로 특정 파일과 폴더를 참조해 Bob에게 정확한 분석 범위를 지정합니다. /init: 질문을 시작하기 전에 Bob이 코드베이스 관례를 이해할 수 있도록 프로젝트 컨텍스트를 초기화합니다.
사전 요구사항
이 튜토리얼을 완료하려면 다음이 필요합니다.
- Bob IDE 설치됨.
- Git 로컬에 설치됨.
- Bob 기본 사용법 숙지. Bob이 처음이라면 먼저 빠른 시작 튜토리얼을 완료하세요.
작업 공간 설정
Galaxium Travels 리포지터리 복제
터미널에서 예시 리포지터리를 복제합니다.
git clone https://github.com/IBM/galaxium-travels.git예시 프로젝트 열기
Bob IDE에서 방금 복제한 galaxium-travels 폴더를 엽니다. Bob이
"Do you trust the authors of the files in the folder?"라고 물으면
Yes, I trust the authors를 클릭하세요.
Bob 채팅 인터페이스 열기
채팅 인터페이스가 아직 열려 있지 않다면 내비게이션 바의 Bob 아이콘을 클릭하거나 단축키 Option + Command + B(Mac) 또는 Ctrl + Alt + B(Windows)를 사용하세요.
프로젝트 컨텍스트 초기화
Bob은 시작 시 기본적으로 Agent 모드로 실행됩니다. 모드를 전환하기 전에 /init
명령을 실행해 Bob이 프로젝트를 읽고 이후 상호작용에서 사용할 AGENTS.md 컨텍스트
파일을 생성하게 합니다.
/init자동 승인이 비활성화되어 있으면 Bob이 파일 읽기 및 AGENTS.md 파일 쓰기 권한을
요청합니다. 각 요청을 승인하세요. Bob은 루트 레벨의 AGENTS.md와 모드별 설정이 담긴
.bob/ 폴더를 생성합니다.
생성된 AGENTS.md를 검토해 Bob이 리포지터리의 멀티서비스 구조를 올바르게
파악했는지 확인하세요.
Ask 모드로 전환
채팅 입력 필드 아래의 모드 선택기에서 Ask를 선택하거나 /ask를 입력해 모드를
전환합니다. Ask 모드는 엄격히 읽기 전용입니다. Bob은 파일을 분석하지만 생성하거나
수정할 수 없으므로 이 튜토리얼의 모든 탐색 작업에 적합한 모드입니다.
애플리케이션 목적과 프로젝트 구조 파악
가장 넓은 질문부터 시작합니다. 이 애플리케이션은 무엇을 하며, 코드베이스는 어떻게
구성되어 있나요? Bob은 프로젝트 구조와 README.md, package.json,
requirements.txt, 빌드 파일, 기타 설정 파일 같은 주요 파일을 읽습니다.
각 디렉터리를 직접 추적하지 않아도 Bob이 간결한 요약을 합성합니다.
Ask 모드에서 다음 프롬프트를 입력합니다.
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.Bob은 파일 트리와 주요 진입점을 읽은 뒤 다음을 포함한 출력을 생성합니다.
- 애플리케이션 목적
- 최상위 디렉터리의 역할
- 각 최상위 디렉터리 내용 요약
- 고수준 아키텍처 다이어그램
기술 스택 분석
고수준 구조가 명확해지면 실제 사용 기술을 심층적으로 파악합니다. 이 프롬프트는 빌드 도구를 이해하거나, 의존성 선택을 평가하거나, 업그레이드 범위를 가늠할 때 유용합니다.
Ask 모드에서 다음 프롬프트를 입력합니다.
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.Bob은 각 서비스의 의존성 및 설정 파일을 검토하고 다음을 포함한 출력을 생성합니다.
- 각 서비스의 상세 기술 스택 분석
- 엔드투엔드 테스트 프레임워크 식별
- CI/CD 스택과 배포 스크립트의 추가 도구
- 모든 서비스와 레이어의 기술 스택을 시각적으로 요약한 "Stack at a Glance" 다이어그램
주요 컴포넌트 매핑
기술 스택을 알면 코드베이스가 무엇을 사용하는지 알 수 있고, 주요 컴포넌트를 알면 어떻게 동작하는지 알 수 있습니다. 이 프롬프트는 서비스 경계를 넘나드는 변경을 하기 전에 세 서비스 전체의 컴포넌트 경계와 데이터 흐름을 추적하도록 Bob에게 요청합니다.
Ask 모드에서 가장 관련성 높은 파일을 가리키는 컨텍스트 멘션과 함께 다음 프롬프트를 입력합니다.
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.Bob은 상호작용 체인을 추적하고 다음을 포함한 출력을 생성합니다.
- 프론트엔드, 백엔드 API, 데이터베이스 레이어, Java 홀드 서비스의 상세 역할
- 컴포넌트 상호작용이 주석으로 표시된 두 가지 예약 라이프사이클 흐름 다이어그램
- 변경 전에 알아야 할 5가지 서비스 간 계약 요약
- 컴포넌트 상호작용 맵
유닛 테스트 커버리지 평가
기능을 추가하거나 리팩터링하기 전에 기존 테스트 스위트가 무엇을 다루고 있으며 어디에 빈틈이 있는지 파악해야 합니다. 이 프롬프트는 테스트를 실행하지 않고도 테스트 파일을 읽어 커버리지 평가를 생성하도록 Bob에게 요청합니다.
Ask 모드에서 다음 프롬프트를 입력합니다.
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.Bob은 테스트 파일을 읽고 다음을 포함한 상세 테스트 스위트 분석을 생성합니다.
- 각 서비스별 테스트 프레임워크, 테스트 대상 클래스, 클래스당 테스트 수, 클래스별 검증 항목
- 심각한 테스트 빈틈
- 핵심 비즈니스 로직의 누락된 테스트 커버리지
통합 및 엔드투엔드 테스트 커버리지 평가
유닛 테스트는 개별 컴포넌트가 독립적으로 동작하는지 확인하고, 통합 및 엔드투엔드 테스트는 서비스가 함께 올바르게 동작하는지 확인합니다. 예약 확인 흐름이 세 서비스 모두를 거치는 Galaxium Travels에서는 이것이 특히 중요합니다.
Ask 모드에서 다음 프롬프트를 입력합니다.
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.Bob은 엔드투엔드 테스트 스위트를 읽고 다음을 포함한 상세 커버리지 분석을 생성합니다.
- 스위트를 실행하기 위한 테스트 인프라 및 요구사항
- 스모크 테스트
- 주요 인프라 결정 사항
- 커버된 서비스 간 흐름과 커버되지 않은 흐름
- 경계 수준에서의 테스트 어설션
배포 모델 검토
애플리케이션이 배포되는 방법(대상 플랫폼, 컨테이너화 전략, 인프라 자동화)을 이해하는 것은 컨트리뷰터로 합류하거나 로컬 환경 이외의 곳에서 애플리케이션을 실행하기 전에 필수입니다.
Ask 모드에서 다음 프롬프트를 입력합니다.
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.Bob은 배포 산출물을 읽고 배포 모델 분석을 생성합니다. 분석에는 다음이 포함됩니다.
- 지원되는 배포 대상
- 각 서비스의 컨테이너화 전략
- 인프라 프로비저닝 세부 정보
- CI/CD 워크플로
- 주요 배포 제약 사항과 빈틈
분석 결과를 리포지터리에 저장
Ask 모드에서 생성한 분석은 채팅 세션에만 존재합니다. Agent 모드로 전환해 향후 컨트리뷰터가 이 작업의 혜택을 받을 수 있도록 영구적인 온보딩 참조 문서를 리포지터리에 작성하도록 Bob에게 요청합니다.
Agent 모드로 전환
모드 선택기에서 Agent를 선택하거나 채팅 입력 필드에 /agent를 입력합니다.
온보딩 참조 문서 생성
Bob이 발견한 모든 내용을 단일 Markdown 파일로 정리하도록 요청합니다. Bob은 전체 대화 컨텍스트를 보유하고 있으므로 모든 파일을 다시 읽지 않고도 발견 내용을 합성합니다.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.Bob이 파일을 작성합니다. 자동 승인이 비활성화되어 있으면 Bob이
docs/ONBOARDING.md 쓰기 권한을 요청할 때 Approve를 클릭하세요.
출력 확인
에디터에서 docs/ONBOARDING.md를 열어 문서에 예상하는 모든 내용이 포함되어
있는지 확인합니다. Bob에게 미리보기를 요청할 수도 있습니다.
Show me a preview of docs/ONBOARDING.mdBob이 채팅 인터페이스에 Markdown을 렌더링합니다. 커밋하기 전에 내용의 정확성과 완성도를 검토하세요.
파일 커밋
선호하는 Git 워크플로를 사용해 docs/ONBOARDING.md를 리포지터리에 커밋합니다.
이제 모든 컨트리뷰터와 Bob 자체가 향후 세션에서 이 문서를 활용할 수 있습니다.
문제 해결
Bob의 분석이 피상적이거나 서비스가 누락됨
기본적으로 Bob은 프로젝트 구조와 일부 주요 파일을 읽습니다. 출력에 서비스가 누락되거나 예상보다 덜 상세하다면 명시적인 컨텍스트 멘션을 추가해 Bob의 초점을 좁힙니다.
예를 들어 Java 홀드 서비스가 기술 스택 분석에 반영되지 않은 경우 프롬프트에
@booking_system_inventory_hold_service/pom.xml을 추가합니다.
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.Bob이 테스트 파일을 찾지 못함
Bob이 테스트 파일을 찾을 수 없다고 보고하면 컨텍스트 멘션을 사용해 테스트 디렉터리를 직접 가리킵니다.
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.Bob의 배포 분석에 대상이 누락됨
AWS, IBM Cloud, 로컬 배포 산출물은 여러 최상위 디렉터리에 분산되어 있습니다. Bob의 배포 요약이 불완전하다면 특정 디렉터리를 지정합니다.
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init이 비어 있거나 잘못된 AGENTS.md를 생성함
작업 공간 루트에서 /init 명령은 README.md, package.json, requirements.txt,
pom.xml, Makefile 같은 앵커 파일을 읽어 프로젝트 컨텍스트를 구성합니다.
이러한 파일이 루트에 없거나 작업 공간 루트가 하위 디렉터리로 설정되어 있으면
Bob은 프로젝트의 일부만 보게 되어 빈약하거나 잘못된 AGENTS.md를 생성합니다.
생성된 AGENTS.md가 멀티서비스 구조를 반영하지 않으면 다음을 확인하세요.
- 작업 공간 루트:
booking_system_backend/같은 하위 디렉터리가 아닌galaxium-travels/가 작업 공간 루트로 열려 있는지 확인합니다. 세 서비스 디렉터리 모두가 최상위 레벨에 표시되어야 합니다. - 앵커 파일 누락: 루트에
README.md나 다른 매니페스트가 없으면/init이 읽을 내용이 부족합니다. 간략한 프로젝트 설명을 담은 루트 레벨README.md를 추가한 뒤/init을 다시 실행하세요.
루트를 수정한 후 /init을 다시 실행해 AGENTS.md 파일을 재생성합니다.