問いを決め、ソースのバージョンを固定する
読者と目的を明確にします。サービスを初めて理解するのか、影響の大きい変更をレビューするのか、リクエストがストレージに届く経路を調べるのかを決めてください。リポジトリの URL とコミットを記録し、未コミットの変更があれば併記します。これにより説明を再確認できます。
Agent は手元の開発環境でリポジトリを読みます。OWL Compose は、非公開リポジトリの URL を貼り付けるだけでソースを取得することはありません。公開する生成物に認証情報、環境の秘密情報、無関係な非公開コードを含めないでください。
図を描く前に実際の経路を一つ追う
HTTP ルート、CLI コマンド、キューのコンシューマー、定期ジョブなど、具体的な入口から始めます。問いに関係する呼び出しを追い、モジュール名、ソースのファイルパス、シンボルを根拠として記録します。実際の呼び出しと推測した依存関係は区別してください。
リクエストの方向、境界を越えて渡るデータ、重要な非同期処理を示します。パッケージの import 関係だけでは実行順序は分かりません。設定や機能フラグで動作が変わる場合は、図が前提とする設定を明記します。
読み進められる構成図を選ぶ
単一のリクエストには小さなフロー図を使い、複数のサービスや層を調べる場合はグループ化した関係図を使います。関数の詳細は所属モジュールの近くに置き、線には「呼び出す」「キューに入れる」「読む」「書く」「返す」などの意味を付けます。すべてのノードをすべての依存先につなぐ必要はありません。
インストール済みの作者スキルを使って OWX を書くよう Agent に依頼します。関係図はグループ化と対話的な探索に対応し、説明文や表も添えられます。読者が実装へ戻れるよう、説明にはソースへの参照を残してください。
説明と実際の表示を両方検証する
コンパイル後、デスクトップとモバイルの幅で作品を確認します。入口から観測できる結果まで経路をたどり、矢印がソースと一致するか調べ、問いに答えるために必要なグループを展開します。コンパイル成功は構造の妥当性を確認するもので、構成に関する主張を証明するものではありません。
共有する前に、公開後の作品を作者ビューで確認します。作品は既定で非公開です。他の人に見せる場合は、明示的に読者リンクを作成してください。後の改訂ではローカルの OWX と作品の識別情報を保持し、同じ作品の新しい版として公開して、記録したソースのバージョンも更新します。
よくある質問
よくある質問
OWL Compose はリポジトリ全体をアップロードしますか？
ソースを読むのはローカルの Agent です。公開時に送られるのはコンパイル済みの文書とパッケージ内のアセットなので、共有前に非公開情報が含まれていないか確認してください。
コードを変更した後に構成図を更新できますか？
はい。同じローカルの OWX を更新し、変更された経路を検証してから、既存の作品の新しい版を公開します。リポジトリとの同期は自動ではありません。
実際のワークフローを使う
エージェントの作品を発表しよう。
CLI をインストールし、OWX で作成してローカル検証し、非公開の作品として発表します。共有するときだけ読者リンクを作成します。