教學

產生稽核報告和合規文件

使用 IBM Bob 分析 Galaxium Travels 程式碼庫並產生涵蓋程式碼品質、相依性健康狀況、技術債務和合規態勢的結構化稽核報告。學習如何從 AI 輔助分析中組裝面向利害關係人的文件。

軟體稽核產生工程團隊、安全審查員和合規利害關係人在交付、收購或認證系統之前所依賴的文件證據。

在本教學中,你使用 Bob 系統地分析 Galaxium Travels 程式碼庫並產生五個結構化工件:

  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

本教學使用儲存庫的 main 分支,而不是 bob-learning-path-branch。本教學引用的 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 推斷出的專案結構、技術堆疊和關鍵模式。此內容直接提高了後續提示中 分析的品質。

產生程式碼品質摘要

程式碼品質摘要為工程師和審查員提供了整個程式碼庫問題的結構化檢視:反模式、缺少的保護措施、測試 覆蓋率差距以及在專案生命週期中累積的不一致性。與 linter 報告不同,Bob 產生的品質摘要使用 人類可讀的解釋和嚴重性內容綜合跨語言和層的發現。

Galaxium Travels 程式碼庫跨越三個不同的技術堆疊:Python(後端)、TypeScript(前端)和 Java (hold 服務)。建構你的提示以獨立分析每個服務,然後產生統一的發現表。使用 context mentions 為 Bob 提供精確的檔案範圍,而不是讓 Bob 猜測哪些檔案相關。

開始新任務

點選 + 按鈕開始新任務。重新開始可使此提示的內容限制在你在此處提到的檔案,而不是 攜帶 Bob 在 /init 期間讀取的所有內容。

產生程式碼品質摘要

在 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 以確認每個清單的表和跨領域發現部分在繼續之前存在。

評估技術債務

技術債務評估評估隨時間累積成本的結構、架構和營運決策。建構你的提示以將債務分為架構、安全、 營運準備和程式碼品質,並對每個項目的嚴重性和補救工作進行評級,以便領導層可以確定優先順序。

以下提示在 context mentions 中包含 AGENTS.md,以便為 Bob 提供有關推斷的架構和營運模式的 見解,這可以為架構和營運債務的評估提供資訊。你在初始化專案內容部分 執行的 /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 以確認所有六個部分在繼續之前存在。

編譯利害關係人稽核報告

完成四個單獨的分析後,要求 Bob 將它們組裝成一個面向高階主管的稽核報告。利害關係人報告與按主題 分析不同:它以發現摘要開頭,優先考慮最可操作的項目,並提供非技術讀者可以採取行動的建議補救 順序。

提示使用 context mentions 載入 Bob 在前面部分寫入磁碟的四個報告。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 以確認執行摘要、記分卡和五個部分存在。你現在 在 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. 刪除包含五個產生報告的 docs/audit/ 目錄。
  2. 如果你不想保留 Bob 產生的專案內容,請刪除 /init 命令建立的 AGENTS.md 檔案和 .bob/ 資料夾。
  3. 刪除你在設定你的工作區中複製的 galaxium-travels 目錄。

後續步驟

在本教學中,你使用 IBM Bob 來:

  • 使用 /init 初始化專案內容,以便 Bob 的分析反映專案的結構和技術堆疊
  • 產生四個重點稽核工件:程式碼品質摘要、相依性稽核、技術債務評估和合規文件。每個都由來源檔案 中的證據支援
  • 將四個分析編譯成一個利害關係人稽核報告,其中包含生產準備記分卡和建議的補救順序
  • 使用 Agent 模式和 context mentions 將每個報告持久化到磁碟,保持分析自包含且權杖高效

繼續使用以下資源:

這個主題如何?