튜토리얼

감사 보고서 및 규정 준수 문서 생성

IBM Bob을 사용하여 Galaxium Travels 코드베이스를 분석하고 코드 품질, 종속성 상태, 기술 부채 및 규정 준수 태세를 다루는 구조화된 감사 보고서를 생성합니다. AI 지원 분석에서 이해관계자용 문서를 조립하는 방법을 배웁니다.

소프트웨어 감사는 엔지니어링 팀, 보안 검토자 및 규정 준수 이해관계자가 시스템을 출시, 인수 또는 인증하기 전에 의존하는 문서 증거를 생성합니다.

이 튜토리얼에서는 Bob을 사용하여 Galaxium Travels 코드베이스를 체계적으로 분석하고 5개의 구조화된 아티팩트를 생성합니다:

  1. 코드 품질 요약: 코드베이스 전체의 유지보수성, 복잡성 및 스타일 문제를 강조합니다.
  2. 종속성 감사: 오래되었거나 취약하거나 사용되지 않는 타사 패키지에 플래그를 지정합니다.
  3. 기술 부채 평가: 단축키, 해결 방법 및 리팩토링이 필요한 영역을 카탈로그화합니다.
  4. 규정 준수 문서: 관련 규제 또는 조직 표준에 대한 조사 결과를 기록합니다.
  5. 모든 조사 결과를 결합한 통합 이해관계자 감사 보고서: 위의 내용을 하나의 공유 가능한 문서로 통합합니다.

수정 제안 없이 상세하고 증거에 기반한 조사 결과를 도출하도록 프롬프트를 구조화합니다.

이 튜토리얼이 끝나면 이해관계자와 공유하고 수정 계획의 기준선으로 사용할 수 있는 감사 문서 세트가 완성됩니다.

이 튜토리얼에서 Bob의 출력은 코드베이스의 현재 상태에 따라 예제와 다를 수 있습니다. 생성된 보고서를 시작점으로 사용하고 이해관계자에게 배포하기 전에 조사 결과를 개선하세요.

배우게 될 주요 기능

  • Context mentions: @ 기호를 사용하여 프롬프트에서 특정 파일과 폴더를 참조합니다. Context mentions를 통해 Bob은 정확하고 증거에 기반한 조사 결과를 위해 분석할 파일을 정확히 알 수 있습니다.
  • Agent 모드: Bob이 자율적으로 파일을 작성하여 생성된 아티팩트를 프로젝트에 유지하도록 합니다.
  • 구조화된 출력을 위한 프롬프트 엔지니어링: 원하는 출력 형식을 포함하도록 프롬프트를 구조화하여 서술적 산문이 아닌 이해관계자용 문서를 얻습니다.

전제 조건

작업 공간 설정

Galaxium Travels 리포지토리 복제

터미널에서 다음 명령을 실행하여 Galaxium Travels 예제 리포지토리를 복제합니다:

git clone https://github.com/IBM/galaxium-travels

이 튜토리얼은 bob-learning-path-branch가 아닌 리포지토리의 main 브랜치를 사용합니다. 이 튜토리얼이 참조하는 Java hold 서비스 및 기타 구성 요소는 main에만 있습니다.

IBM Bob 실행

컴퓨터에서 IBM Bob IDE를 실행합니다.

예제 프로젝트 열기

Bob IDE에서 복제한 galaxium-travels 폴더를 엽니다. Bob이 "이 폴더의 파일 작성자를 신뢰하십니까?"라고 묻는 경우 예, 작성자를 신뢰합니다를 클릭합니다.

루트 디렉토리의 README.md 파일을 검토하여 애플리케이션 아키텍처의 개요를 파악합니다. Galaxium Travels는 Python FastAPI 백엔드, React/TypeScript 프론트엔드 및 Java Spring Boot 인벤토리 hold 서비스를 갖춘 풀스택 우주 여행 예약 시스템입니다.

Bob 채팅 인터페이스 열기

채팅 인터페이스가 아직 열려 있지 않은 경우 탐색 모음에서 Bob 아이콘을 클릭하거나 단축키 Option + Command + B(Mac) 또는 Ctrl + Alt + B(Windows)를 사용합니다.

프로젝트 컨텍스트 초기화

Bob은 시작 시 기본적으로 Agent 모드를 사용합니다. 모드를 변경한 경우 초기화 명령을 실행하기 전에 Agent 모드로 전환하세요. Bob은 프로젝트 컨텍스트를 설정하기 위해 파일을 작성해야 합니다. 이 튜토리얼은 작업별로 권한을 제한하는 대신 Agent 모드의 기본 기능을 사용하므로 Bob은 추가 구성 없이 파일을 읽고 쓸 수 있습니다.

채팅 인터페이스 입력 필드에 /init 명령을 입력합니다.

/init

자동 승인이 비활성화된 경우 Bob은 파일을 읽고 변경 사항을 작성하기 전에 권한을 요청합니다. 이러한 프롬프트가 나타나면 승인하세요. 이는 /init 명령과 Bob이 튜토리얼 후반부에 작성하는 각 보고서에 적용됩니다.

Bob은 프로젝트의 관련 파일을 읽고 루트 디렉토리에 메인 AGENTS.md 파일과 모드별 AGENTS.md 파일을 포함하는 .bob/ 폴더를 생성합니다. 계속하기 전에 AGENTS.md.bob/ 폴더가 프로젝트 루트에 나타나는지 확인하세요. 생성된 파일을 검토하여 Bob이 프로젝트 구조, 기술 스택 및 주요 패턴에 대해 추론한 내용을 이해하세요. 이 컨텍스트는 후속 프롬프트에서 분석 품질을 직접 향상시킵니다.

코드 품질 요약 생성

코드 품질 요약은 엔지니어와 검토자에게 코드베이스 전체의 문제에 대한 구조화된 보기를 제공합니다: 안티 패턴, 누락된 보호 장치, 테스트 커버리지 격차 및 프로젝트 수명 동안 축적되는 불일치. 린터 보고서와 달리 Bob이 생성한 품질 요약은 사람이 읽을 수 있는 설명과 심각도 컨텍스트를 사용하여 언어와 레이어 전체의 조사 결과를 종합합니다.

Galaxium Travels 코드베이스는 Python(백엔드), TypeScript(프론트엔드) 및 Java(hold 서비스)의 세 가지 고유한 스택에 걸쳐 있습니다. 각 서비스를 독립적으로 분석한 다음 통합된 조사 결과 테이블을 생성하도록 프롬프트를 구조화합니다. Bob이 어떤 파일이 관련되어 있는지 추측하도록 하는 대신 Bob에게 정확한 파일 범위를 제공하기 위해 context mentions를 사용합니다.

새 작업 시작

+ 버튼을 클릭하여 새 작업을 시작합니다. 새로 시작하면 이 프롬프트의 컨텍스트가 여기서 언급하는 파일로 제한되며 /init 중에 Bob이 읽은 모든 것을 가져오지 않습니다.

코드 품질 요약 생성

Agent 모드에서 채팅 입력 필드에 다음 프롬프트를 입력합니다:

Analyze the code quality of the Galaxium Travels application across all three
services.

For the Python backend, examine @booking_system_backend/server.py,
@booking_system_backend/models.py, @booking_system_backend/services, and
@booking_system_backend/tests.

For the TypeScript frontend, examine @booking_system_frontend/src.

For the Java hold service, examine
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.

Produce a structured Markdown file named `docs/audit/code-quality-summary.md`.
The content should include the following sections:
1. An overview table listing each component, language, files analyzed, and
   issue count by severity (Critical, High, Medium, Low).
2. Per-component findings, each with: severity label, issue title, file and
   approximate line reference, description, and impact.

Focus on: missing input validation, inconsistent error handling, authentication
and credential storage patterns, test coverage gaps, type safety, and logging
practices. Do not suggest fixes — only report findings with evidence from the
source files.

Bob은 세 가지 서비스를 분석하고, 아직 존재하지 않는 경우 docs/audit/ 디렉토리를 생성하고, Markdown 파일을 생성하고, 채팅 인터페이스에 요약을 출력합니다. 보고서에는 지정한 섹션과 구조가 포함되며, 증거로 특정 파일과 코드 줄을 참조하는 조사 결과가 포함됩니다.

보고서 확인

계속하기 전에 Bob 파일 탐색기에서 docs/audit/code-quality-summary.md를 열어 개요 테이블과 구성 요소별 조사 결과가 포함된 파일이 생성되었는지 확인합니다.

종속성 감사 실행

종속성 감사는 프로젝트가 의존하는 라이브러리가 알려진 양호한 버전에 고정되어 있는지, 고정 전략이 다국어 스택 전체에서 일관성이 있는지, 종속성 구성 관행이 제어되지 않은 업그레이드 위험을 초래하는지 확인합니다. 이것은 CVE 스캔과 다릅니다: 알려진 취약점뿐만 아니라 버전 관리 규율을 평가하고 있습니다.

Galaxium Travels 프로젝트에는 세 가지 종속성 매니페스트가 있습니다: booking_system_backend/requirements.txt(Python), booking_system_frontend/package.json(Node.js) 및 booking_system_inventory_hold_service/pom.xml(Java/Maven). 세 가지 모두를 context mentions에 포함합니다.

새 작업 시작

+ 버튼을 클릭하여 새 작업을 시작합니다.

종속성 감사 생성

Agent 모드에서 채팅 입력 필드에 다음 프롬프트를 입력합니다:

Audit the dependency manifests for all three services in the Galaxium Travels
repository.

Analyze @booking_system_backend/requirements.txt,
@booking_system_frontend/package.json, and
@booking_system_inventory_hold_service/pom.xml.

Produce a structured Markdown file named `docs/audit/dependency-audit.md`.
The content should include these sections:
1. Per-manifest findings table: package name, declared version or range,
   pinning status (exact, caret/tilde range, or unpinned), and a brief
   finding note.
2. Cross-cutting findings: consistency issues, missing tooling (lock files,
   audit CI steps, vulnerability scanners), and version drift risks.
3. Findings that require immediate attention before a production deployment,
   listed with rationale.

Report findings only. Do not generate upgrade commands or patch suggestions.

Bob은 매니페스트를 분석하고 보고서를 작성합니다. 고정 상태 테이블과 교차 조사 결과 섹션이 포함됩니다.

보고서 확인

계속하기 전에 docs/audit/dependency-audit.md를 열어 매니페스트별 테이블과 교차 조사 결과 섹션이 있는지 확인합니다.

기술 부채 평가

기술 부채 평가는 시간이 지남에 따라 비용이 축적되는 구조적, 아키텍처적 및 운영상의 결정을 평가합니다. 부채를 아키텍처, 보안, 운영 준비 및 코드 품질로 분리하고 각 항목의 심각도와 수정 노력을 평가하여 리더십이 우선순위를 지정할 수 있도록 프롬프트를 구조화합니다.

다음 프롬프트에는 추론된 아키텍처 및 운영 패턴에 대한 통찰력을 Bob에게 제공하기 위해 context mentions에 AGENTS.md가 포함되어 있으며, 이는 아키텍처 및 운영 부채 평가에 정보를 제공할 수 있습니다. 프로젝트 컨텍스트 초기화 섹션에서 실행한 /init 명령이 AGENTS.md 파일을 생성했습니다.

새 작업 시작

+ 버튼을 클릭하여 새 작업을 시작합니다.

기술 부채 평가 생성

Agent 모드에서 채팅 입력 필드에 다음 프롬프트를 입력합니다:

Conduct a technical debt assessment of the Galaxium Travels application.
Analyze the full codebase across all three services:
@booking_system_backend, @booking_system_frontend, and
@booking_system_inventory_hold_service.

Also review @docker-compose.yml and @AGENTS.md for infrastructure and
operational context.

Produce a structured Markdown file named `docs/audit/technical-debt-assessment.md`.
The content should include these sections: Architecture Debt, Security Debt, Operational Readiness Debt, and Code Quality Debt.

For each debt item include:
- A severity label: [CRITICAL], [HIGH], [MEDIUM], or [LOW]
- An effort-to-resolve label: [DAYS], [WEEKS], or [MONTHS]
- A title
- The affected files or components
- A description of the debt and why it matters
- The consequence of leaving it unaddressed

Conclude with a summary table: category, count by severity, and total items.
Report findings only. Do not generate implementation plans or code.

Bob은 코드베이스를 분석하고 보고서를 작성하며, 각 부채 항목에 심각도 및 노력 추정치를 레이블로 지정합니다.

보고서 확인

계속하기 전에 docs/audit/technical-debt-assessment.md를 열어 네 가지 부채 범주와 요약 테이블이 있는지 확인합니다.

규정 준수 문서 생성

규정 준수 문서는 규제 기관, 감사자 및 엔터프라이즈 보안 팀이 프로덕션 시스템에서 찾을 것으로 예상하는 제어에 대해 코드베이스의 현재 상태를 매핑합니다. 엔지니어가 아닌 이해관계자의 경우 이 문서는 다음 질문에 답합니다: "이 시스템은 민감한 데이터로 무엇을 하는가, 액세스는 어떻게 제어되는가, 격차는 어디에 있는가?"

데이터 분류, 인증 및 액세스 제어, 데이터 보호, 감사 추적 범위 및 라이선스 준수를 다루도록 프롬프트를 구조화합니다.

새 작업 시작

+ 버튼을 클릭하여 새 작업을 시작합니다.

규정 준수 문서 생성

Agent 모드에서 채팅 입력 필드에 다음 프롬프트를 입력합니다:

Generate compliance documentation for the Galaxium Travels application,
suitable for sharing with security reviewers and compliance stakeholders.

Analyze the following files and directories:
@booking_system_backend/models.py,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/requirements.txt,
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain,
@booking_system_inventory_hold_service/pom.xml,
@booking_system_frontend/src,
@booking_system_frontend/package.json,
@LICENSE.

Produce a structured Markdown file named `docs/audit/compliance-documentation.md`. The content should include these sections:
1. Data Classification — table of data elements, classification tier, storage
   location, and retention policy.
2. Authentication and Access Control — table of controls, implementation status
   (Implemented / Partial / Not Implemented), and a source reference or gap note.
3. Data Protection — table of controls, implementation status, and notes.
4. Audit Trail Coverage — what is logged, what is not, and where audit records
   are stored.
5. License Compliance — table of key dependencies (Python, Node, and Java) with
   their license and a compliance note.
6. Regulatory Applicability — brief assessment of GDPR, SOC 2, and PCI DSS
   applicability given the data the system handles.

Use neutral, factual language. Do not recommend remediations.

Bob은 소스 파일을 분석하고 보고서를 작성하며, 각 제어를 코드 참조와 함께 구현 상태에 매핑합니다.

보고서 확인

계속하기 전에 docs/audit/compliance-documentation.md를 열어 6개 섹션이 모두 있는지 확인합니다.

이해관계자 감사 보고서 컴파일

네 가지 개별 분석이 완료되면 Bob에게 이를 하나의 경영진 대상 감사 보고서로 조립하도록 요청합니다. 이해관계자 보고서는 주제별 분석과 다릅니다: 조사 결과 요약으로 시작하고, 가장 실행 가능한 항목의 우선순위를 지정하며, 비기술 독자가 조치할 수 있는 권장 수정 순서를 제공합니다.

프롬프트는 이전 섹션에서 Bob이 디스크에 작성한 네 가지 보고서를 로드하기 위해 context mentions를 사용합니다. Bob은 소스 코드를 다시 분석하는 대신 이러한 파일을 읽고 단일 문서로 합성하므로 출력은 이미 검토한 조사 결과를 반영합니다.

새 작업 시작

+ 버튼을 클릭하여 새 작업을 시작합니다.

이해관계자 감사 보고서 생성

Agent 모드에서 채팅 입력 필드에 다음 프롬프트를 입력합니다:

Using @docs/audit/code-quality-summary.md, @docs/audit/dependency-audit.md,
@docs/audit/technical-debt-assessment.md,
and @docs/audit/compliance-documentation.md, compile a consolidated
stakeholder audit report for the Galaxium Travels application.

The audience is engineering leadership and security reviewers who need to
assess the system's production readiness and compliance posture without
reading four separate documents.

Structure the report as follows:
1. Executive Summary: 2-3 paragraphs covering overall state, most critical
   risks, and the highest-priority remediation categories.
2. Production Readiness Scorecard: a table scoring the system against six
   dimensions (Authentication, Data Protection, Observability, Dependency
   Health, Test Coverage, Operational Readiness) with a RAG status
   (Red / Amber / Green) and a one-line rationale for each.
3. Critical and High Findings: a consolidated table of all Critical and High
   severity findings from all four analyses, with category, finding title,
   affected component, and effort to resolve.
4. Recommended Remediation Sequence: an ordered list of the top 5 items to
   address first, with a brief rationale for the ordering.
5. Positive Findings: a brief section acknowledging controls and practices
   that are already well-implemented.

Do not repeat all findings in full. Reference the detailed documents for
complete findings. Save the report as `docs/audit/stakeholder-audit-report.md`.

Bob은 저장된 네 가지 보고서를 읽고 조사 결과를 합성하여 docs/audit/stakeholder-audit-report.md를 생성합니다. Bob은 소스 코드를 다시 분석하는 대신 이미 검토한 보고서에서 작업하므로 통합 보고서는 상세한 조사 결과와 일관성을 유지합니다.

보고서 확인

docs/audit/stakeholder-audit-report.md를 열어 경영진 요약, 스코어카드 및 5개 섹션이 있는지 확인합니다. 이제 이해관계자와 공유하고 수정 계획의 기준선으로 사용할 수 있는 docs/audit/의 완전한 감사 문서 세트가 있습니다.

문제 해결

Bob의 분석이 서비스 또는 파일을 생략함

Bob의 출력에 다루어질 것으로 예상한 구성 요소에 대한 조사 결과가 누락된 경우, 가장 가능성 있는 원인은 프롬프트가 context mention에 파일 또는 디렉토리를 포함하지 않았거나 컨텍스트 창이 너무 가득 차서 Bob이 참조된 모든 콘텐츠를 한 번에 읽을 수 없었기 때문입니다.

context mentions 확인

프롬프트의 @ 멘션이 올바른 경로로 확인되는지 확인합니다. Bob 채팅 인터페이스에서 Bob은 context mention이 확인되었는지 여부를 나타낼 수 있습니다. Bob이 멘션을 인식하지 못하면 경로의 철자가 틀렸거나 디렉토리가 로컬 클론에 존재하지 않을 수 있습니다.

많은 파일이 있는 디렉토리의 경우 Bob은 하위 집합만 읽을 수 있습니다. 범위를 가장 관련성 있는 하위 디렉토리로 좁히거나 전체 폴더를 참조하는 대신 특정 파일을 열거합니다.

분석을 집중된 프롬프트로 분할

세 가지 서비스를 모두 다루는 단일 프롬프트 대신 서비스당 하나씩 세 개의 개별 프롬프트를 실행한 다음 Bob에게 조사 결과를 병합하도록 요청합니다. 예를 들어, Python 및 TypeScript 패스를 완료한 후 세 번째 집중 프롬프트는 다음과 같습니다:

The code quality analysis we ran earlier covered the Python backend and
TypeScript frontend. Run the same analysis for the Java hold service only,
using @booking_system_inventory_hold_service/src. Use the same output format
and severity labels as the earlier reports.

각 집중 분석이 완료되면 Bob에게 병합하도록 요청합니다:

Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.

보고서에 프롬프트 간 상충되는 조사 결과가 포함됨

다중 프롬프트 세션을 실행할 때 이후 프롬프트가 이전 프롬프트와 모순되는 것처럼 보이는 조사 결과를 생성할 수 있습니다. 이는 Bob이 다른 파일 읽기에서 다른 추론을 도출하거나 이전 조사 결과가 부정확한 경우 발생할 수 있습니다.

상충되는 주장 식별

새 프롬프트에서 두 조사 결과를 모두 인용하고 특정 파일 참조로 불일치를 해결하도록 Bob에게 요청합니다. 예를 들어:

In the code quality summary you stated that error handling in server.py is
inconsistent. In the technical debt assessment you described the same issue
as absent error handling. Review @booking_system_backend/server.py and clarify
which description is more accurate, with a specific line reference.

영향을 받는 보고서 업데이트

Bob이 권위 있는 조사 결과를 생성한 후 저장된 보고서 파일의 특정 섹션을 업데이트하도록 Bob에게 요청합니다. 예를 들어 기술 부채 평가가 더 정확한 경우 코드 품질 요약을 업데이트하도록 Bob에게 요청합니다:

Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.

Bob이 분석에 요청하지 않은 권장 사항을 추가함

프롬프트가 명시적 제약 없이 Bob에게 "분석" 또는 "평가"를 요청하면 Bob은 조사 결과와 함께 수정 제안을 포함하는 경우가 많습니다. 규정 준수 또는 감사 보고서의 경우 요청하지 않은 권장 사항이 문제가 될 수 있습니다: 잘못될 수 있고, 대상 환경에 대한 가정을 반영할 수 있으며, 조사 결과만 있는 문서를 기대하는 이해관계자를 혼란스럽게 할 수 있습니다.

이것이 중요한 분석 프롬프트에 "Report findings only. Do not generate implementation plans, code, or remediation suggestions." 지침을 추가합니다. Bob이 이미 혼합 콘텐츠가 있는 보고서를 생성한 경우 Bob에게 권장 사항을 제거하도록 요청합니다. 예를 들어 코드 품질 요약에 권장 사항이 포함된 경우 다음 프롬프트를 입력합니다:

Remove all remediation suggestions, implementation guidance, and code examples
from docs/audit/code-quality-summary.md. Keep all finding descriptions,
severity labels, file references, and impact statements exactly as written.

정리

이 튜토리얼에서 생성된 아티팩트를 제거하려면:

  1. 생성된 5개의 보고서가 포함된 docs/audit/ 디렉토리를 삭제합니다.
  2. Bob이 생성한 프로젝트 컨텍스트를 유지하지 않으려면 /init 명령이 생성한 AGENTS.md 파일과 .bob/ 폴더를 삭제합니다.
  3. 작업 공간 설정에서 복제한 galaxium-travels 디렉토리를 삭제합니다.

다음 단계

이 튜토리얼에서는 IBM Bob을 사용하여 다음을 수행했습니다:

  • /init으로 프로젝트 컨텍스트를 초기화하여 Bob의 분석이 프로젝트의 구조와 기술 스택을 반영하도록 했습니다
  • 네 가지 집중 감사 아티팩트, 코드 품질 요약, 종속성 감사, 기술 부채 평가 및 규정 준수 문서를 생성했습니다. 각각은 소스 파일의 증거로 뒷받침됩니다
  • 네 가지 분석을 프로덕션 준비 스코어카드와 권장 수정 순서가 포함된 단일 이해관계자 감사 보고서로 컴파일했습니다
  • Agent 모드와 context mentions를 사용하여 각 보고서를 디스크에 유지하여 분석을 자체 포함적이고 토큰 효율적으로 유지했습니다

다음 리소스를 계속 진행하세요:

이 주제는 어떤가요?