監査レポートとコンプライアンスドキュメントの生成
IBM Bobを使用してGalaxium Travelsのコードベースを分析し、コード品質、依存関係の健全性、技術的負債、コンプライアンス態勢をカバーする構造化された監査レポートを作成します。AI支援分析からステークホルダー向けのドキュメントを組み立てる方法を学びます。
ソフトウェア監査は、エンジニアリングチーム、セキュリティレビュアー、コンプライアンスステークホルダーが システムを出荷、取得、または認証する前に依拠する文書的証拠を生成します。
このチュートリアルでは、Bobを使用してGalaxium Travelsのコードベースを体系的に分析し、 5つの構造化されたアーティファクトを生成します:
- コード品質サマリー: コードベース全体の保守性、複雑性、スタイルの問題を強調表示します。
- 依存関係監査: 古い、脆弱な、または未使用のサードパーティパッケージにフラグを立てます。
- 技術的負債評価: ショートカット、回避策、リファクタリングが必要な領域をカタログ化します。
- コンプライアンスドキュメント: 関連する規制または組織の基準に対する調査結果を記録します。
- すべての調査結果を組み合わせた統合ステークホルダー監査レポート: 上記を1つの共有可能なドキュメントに統合します。
修復提案なしで、詳細で証拠に裏付けられた調査結果を引き出すようにプロンプトを構造化します。
このチュートリアルの終わりには、ステークホルダーと共有し、修復計画のベースラインとして使用できる 監査ドキュメントのセットが完成します。
このチュートリアルでは、コードベースの現在の状態によって、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サービス)の3つの異なるスタックにまたがっています。各サービスを個別に分析し、統一された調査結果 テーブルを作成するようにプロンプトを構造化します。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は3つのサービスを分析し、まだ存在しない場合はdocs/audit/ディレクトリを作成し、Markdownファイルを
作成し、チャットインターフェースにサマリーを出力します。レポートには、指定したセクションと構造が含まれ、
証拠として特定のファイルとコード行を参照する調査結果が含まれます。
レポートの確認
続行する前に、Bobファイルエクスプローラーでdocs/audit/code-quality-summary.mdを開いて、概要テーブルと
コンポーネントごとの調査結果を含むファイルが作成されたことを確認します。
依存関係監査の実行
依存関係監査は、プロジェクトが依存するライブラリが既知の良好なバージョンに固定されているかどうか、 固定戦略がポリグロットスタック全体で一貫しているかどうか、依存関係構成の実践が制御されていない アップグレードリスクをもたらすかどうかを確立します。これはCVEスキャンとは異なります:既知の脆弱性 だけでなく、バージョン管理の規律を評価しています。
Galaxium Travelsプロジェクトには3つの依存関係マニフェストがあります:
booking_system_backend/requirements.txt(Python)、
booking_system_frontend/package.json(Node.js)、
booking_system_inventory_hold_service/pom.xml(Java/Maven)。3つすべてを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を開いて、4つの負債カテゴリとサマリーテーブルが
存在することを確認します。
コンプライアンスドキュメントの生成
コンプライアンスドキュメントは、規制当局、監査人、エンタープライズセキュリティチームが本番システムで 見つけることを期待する管理に対して、コードベースの現在の状態をマッピングします。エンジニアではない ステークホルダーにとって、このドキュメントは次の質問に答えます:「このシステムは機密データで何をするのか、 アクセスはどのように制御されるのか、ギャップはどこにあるのか?」
データ分類、認証とアクセス制御、データ保護、監査証跡カバレッジ、ライセンスコンプライアンスをカバーする ようにプロンプトを構造化します。
新しいタスクを開始
**+**ボタンをクリックして新しいタスクを開始します。
コンプライアンスドキュメントの生成
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つのセクションすべてが存在することを
確認します。
ステークホルダー監査レポートのコンパイル
4つの個別の分析が完了したら、Bobにそれらを1つの経営幹部向け監査レポートにまとめるよう依頼します。 ステークホルダーレポートは、トピックごとの分析とは異なります:調査結果のサマリーで始まり、最も実行可能な 項目を優先し、技術者でない読者が行動できる推奨される修復順序を提供します。
プロンプトは、前のセクションでBobがディスクに書き込んだ4つのレポートをロードするためにcontext mentions を使用します。Bobはソースコードを再分析するのではなく、これらのファイルを読み取って1つのドキュメントに 統合するため、出力はすでに確認した調査結果を反映します。
新しいタスクを開始
**+**ボタンをクリックして新しいタスクを開始します。
ステークホルダー監査レポートの生成
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は保存された4つのレポートを読み取り、その調査結果を統合してdocs/audit/stakeholder-audit-report.mdを
作成します。Bobはソースコードを再分析するのではなく、すでに確認したレポートから作業するため、統合された
レポートは詳細な調査結果と一貫性を保ちます。
レポートの確認
docs/audit/stakeholder-audit-report.mdを開いて、エグゼクティブサマリー、スコアカード、5つのセクションが
存在することを確認します。これで、ステークホルダーと共有し、修復計画のベースラインとして使用できる
docs/audit/内の完全な監査ドキュメントセットが完成しました。
トラブルシューティング
Bobの分析がサービスまたはファイルを省略する
Bobの出力に、カバーされることを期待していたコンポーネントの調査結果が欠けている場合、最も可能性の高い 原因は、プロンプトがcontext mention内にファイルまたはディレクトリを含めなかったか、コンテキストウィンドウが いっぱいすぎてBobが参照されたすべてのコンテンツを1回のパスで読み取れなかったことです。
context mentionsを確認する
プロンプト内の@メンションが正しいパスに解決されることを確認します。Bobチャットインターフェースで、
Bobはcontext mentionが解決されたかどうかを示す場合があります。Bobがメンションを認識しない場合、パスの
スペルが間違っているか、ディレクトリがローカルクローンに存在しない可能性があります。
多くのファイルを含むディレクトリの場合、Bobはサブセットのみを読み取る可能性があります。スコープを最も 関連性の高いサブディレクトリに絞り込むか、フォルダー全体を参照するのではなく特定のファイルを列挙します。
分析を焦点を絞ったプロンプトに分割する
3つのサービスすべてをカバーする単一のプロンプトの代わりに、サービスごとに1つずつ、3つの個別のプロンプトを 実行し、次にBobに調査結果をマージするよう依頼します。たとえば、PythonとTypeScriptのパスを完了した後の 3番目の焦点を絞ったプロンプトは次のとおりです:
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.クリーンアップ
このチュートリアルで作成されたアーティファクトを削除するには:
- 5つの生成されたレポートを含む
docs/audit/ディレクトリを削除します。 - Bobが生成したプロジェクトコンテキストを保持したくない場合は、
/initコマンドが作成したAGENTS.mdファイルと.bob/フォルダーを削除します。 - ワークスペースのセットアップでクローンした
galaxium-travelsディレクトリを削除します。
次のステップ
このチュートリアルでは、IBM Bobを使用して次のことを行いました:
/initでプロジェクトコンテキストを初期化して、Bobの分析がプロジェクトの構造と技術スタックを反映 するようにしました- 4つの焦点を絞った監査アーティファクト、コード品質サマリー、依存関係監査、技術的負債評価、 コンプライアンスドキュメントを生成しました。それぞれがソースファイルからの証拠に裏付けられています
- 4つの分析を、本番準備スコアカードと推奨される修復シーケンスを含む単一のステークホルダー監査レポートに コンパイルしました
- Agentモードとcontext mentionsを使用して各レポートをディスクに永続化し、分析を自己完結型で トークン効率的に保ちました
次のリソースを続けてください:
- Audit code and generate reportsに従って、開発ツールと AIエージェントが作用できる機械可読のSARIFおよびOSCALアーティファクトを生成します。
- 調査結果をベースラインとして使用し、次にGenerate secure code with an actor-critic workflowに従って、この監査で明らかになった問題を 再導入することなく修復します。
- より効果的なプロンプト戦略については、Bob best practices を読んでください。