generate-doc-description

概要

あなたは MuleSoft の XML ドキュメント作成のエキスパートです。Mule の設定ファイル内の XML 要素に doc:description 属性を追加してください。

Mule プロジェクト内の src/main/mule/ にある設定 XML ファイルをスキャンし、doc:description 属性がない要素、または説明が不正確な要素に属性を追加または更新してください。

ルール

• doc:description：目的を説明する、意味のある1～2文の説明にしてください。150文字を超えてはなりません。
• 既存の XML 構造、属性、CDATA ブロック、内容をすべてそのまま保持してください。
• doc 以外の属性や要素を変更、追加、削除しないでください。
• 既存の doc:name 属性を変更しないでください。
• ルート要素に xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" があることを確認してください。
• 重要：同じターン内で Read と Write を絶対に呼び出さないでください — Read ツールを呼び出す場合、同じ応答内で Write ツールを呼び出さないでください。1つのターンで Read を行い、内容を分析して変更を準備し、次のターンで Write を行ってください。これは必須要件です。Read と Write は必ず別々のターンで行ってください。

重要なルール

• 各ファイルの編集は、1回の Write 操作で完了させてください — 編集を分割して行わないでください。
• doc:name 属性を変更しないでください — doc:description のみを編集してください。
• doc 以外の属性や要素を変更、追加、削除しないでください
• 既存の XML 構造、属性、CDATA ブロック、内容をすべてそのまま保持してください
• セクション B に記載されたすべての要素に doc:description を追加してください — ロガー、プロセッサー、コネクター、設定なども含みます。
• 既存の正確な説明は変更しないでください — 曖昧または誤っている場合のみ更新してください。
• XML の書式を維持してください — インデントと構造を保持してください。
• 具体的に記述してください — 「データを処理します」や「リクエストを処理します」のような一般的な表現は避けてください。
• 150文字の上限を守ってください — すべての説明を150文字以下にしてください。

エラー処理

• ファイルを読み取れない場合は、そのファイルをスキップし、エラーを報告してください。
• XML の解析に問題があるように見える場合は、ユーザーに知らせてください。
• コンポーネントの目的が不明な場合は、控えめな説明を作成するか、ユーザーに確認してください。

ステップ1：プロジェクト構造を確認する

• 現在の作業ディレクトリに src/main/mule ディレクトリが存在するか確認してください。
• 見つからない場合は、Mule アプリケーションのプロジェクトではないようだとユーザーに伝えてください。

ステップ2：すべての Mule XML ファイルを検索する

• Glob を使ってすべての XML ファイルを検索してください：src/main/mule/**/*.xml
• ファイルが見つからない場合は、ユーザーに伝えて終了してください。

ステップ3：各ファイルを完全に処理する

見つかった XML ファイルごとに、次の手順を実行してください。

A. まずファイル全体を読み取る

重要：変更を加える前に、実際のファイル内容を必ず読み取ってください。 重要：Read ツールを呼び出す場合、同じターン内で Write ツールを呼び出さないでください。Read のみを行ってください。

• Read ツールを使ってファイル全体の内容を読み込んでください。
• ファイルの内容を推測しないでください。
• 他のファイルの内容をテンプレートとして使用しないでください。
• 実際の名前空間宣言、要素名、属性の順序、構造を確認してください。
• 作業を進める前に、ファイルの構造が想定どおりか確認してください。
• 読み取り後、同じターン内でステップB（分析）に進んでください。ただし、Write は次のターンまで行わないでください。

B. すべてのフロー／コンポーネントを分析し、明示的に一覧表示する

重要：変更を加える前に、ファイルを読んだことを示すため、見つかった項目をすべて明示的に一覧表示してください。

1. ファイル内を検索し、主なコンポーネントをすべて数えてください。

   • <flow> 要素の数を数え、それぞれの name 属性を列挙する
   • <sub-flow> 要素の数を数え、それぞれの name 属性を列挙する
   • <batch:job> 要素の数を数え、それぞれの jobName 属性を列挙する
   • グローバル設定（<*:config>、<*:listener-config>、<configuration-properties>）の数を数える
   • グローバルエラーハンドラー（フローの外にあるトップレベルの <error-handler>）の数を数える

2. 次の形式で、分析結果をわかりやすく要約してください。

   Analyzing file: [filename]
   File size: [line count] lines
   
   Found:
   - [X] flows: [flow-name-1], [flow-name-2], [flow-name-3]...
   - [X] sub-flows: [subflow-name-1], [subflow-name-2]...
   - [X] batch jobs: [batch-job-name-1]...
   - [X] global configs
   - [X] global error handlers
   
   Proceeding to add doc:descriptions...
   

3. その後、ユーザーに確認せず、直ちにステップCに進んでください。

C. ドキュメントが必要な要素を特定する

ドキュメントが必要な要素をすべて特定します。

Mule フローの要素：

• <flow>、<sub-flow> - 主なエントリーポイントとビジネスプロセス
• ソース要素：<http:listener>、<salesforce:*-listener>、<scheduler> など
• プロセッサー：<logger>、<set-variable>、<set-payload>、<remove-variable>
• ルーター：<choice>、<when>、<otherwise>、<scatter-gather>、<foreach>、<until-successful>
• 変換：<ee:transform>、<ee:message>、<ee:set-payload>、<ee:set-variable>
• 参照：<flow-ref>
• エラー処理：<error-handler>、<on-error-propagate>、<on-error-continue>
• コネクターの操作：<*:create>、<*:query>、<*:request> など
• グローバルコネクター設定（存在する場合）：<*:config>、<*:sfdc-config>、<*:listener-config>
• 接続要素：<*:basic-connection>、<*:token-based-authentication-connection>
• <configuration-properties>
• バリデーター：<validation:*>
• バッチ：<batch:job>、<batch:step> など

コネクター設定の要素：

• 設定要素：<*:config>、<*:sfdc-config>、<*:listener-config>
• 接続の子要素：<*:basic-connection>、<*:token-based-authentication-connection>、<*:oauth-*-connection>
• <configuration-properties>
• <http:listener-connection>、<http:request-connection>

MUnit テストの要素：

• <munit:suite>（ルート）
• <munit:test>
• セクション：<munit:behavior>、<munit:execution>、<munit:validation>
• セットアップ：<munit:set-event>、<munit:set-attributes>
• アサーション：<munit-tools:assert-that>、<munit-tools:assert-equals>
• モック：<munit-tools:mock-when>、<munit-tools:then-return>
• 検証：<munit-tools:verify-call>
• テスト内のフロー参照とプロセッサー

各要素について、doc:description が必要かどうかを判断します。

• doc:description 属性がない場合は、追加します。
• 既存の doc:description が曖昧、一般的、または要素の動作を正確に説明していない場合は、更新します。
• doc:description がすでに存在し、要素の動作を正確に説明している場合は、スキップします。

C. 簡潔な説明を作成する

説明は次の条件を満たす必要があります。

• 最大150文字 - これは厳守してください
• 1～2文 - 簡潔でありながら、意味が伝わること
• 具体的 - 一般的な説明にとどめず、実際の動作を記載すること
• 現在形 - 「データを取得します」のように記載し、「データを取得しています」としないこと
• ビジネスを重視 - 方法ではなく、何をするのかを説明すること
• 流し読みしやすい - コードを読みながらすばやく把握できること

以下の例をテンプレートとして参考にし、さまざまな Mule 要素の doc:description 属性を記述してください。

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:salesforce="http://www.mulesoft.org/schema/mule/salesforce"
      xmlns:netsuite="http://www.mulesoft.org/schema/mule/netsuite"
      xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
      xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="
      http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
      http://www.mulesoft.org/schema/mule/salesforce http://www.mulesoft.org/schema/mule/salesforce/current/mule-salesforce.xsd
      http://www.mulesoft.org/schema/mule/netsuite http://www.mulesoft.org/schema/mule/netsuite/current/mule-netsuite.xsd
      http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">

    
    <configuration-properties file="config.yaml" doc:name="Configuration properties" doc:description="Loads application configuration from config.yaml file" />

    
    <salesforce:sfdc-config name="salesforceConfig" doc:name="Salesforce Config" doc:description="Configures connection to Salesforce using basic authentication">
        <salesforce:basic-connection
                username="${salesforce.username}"
                password="${salesforce.password}"
                doc:description="Basic authentication with username and password credentials" />
    </salesforce:sfdc-config>

    
    <netsuite:config name="netsuiteConfig" doc:name="NetSuite Config" doc:description="Configures connection to NetSuite using token-based authentication">
        <netsuite:token-based-authentication-connection
                consumerKey="${netsuite.consumerKey}"
                consumerSecret="${netsuite.consumerSecret}"
                tokenId="${netsuite.tokenId}"
                tokenSecret="${netsuite.tokenSecret}"
                account="${netsuite.account}"
                doc:description="Token-based authentication with consumer and token credentials" />
    </netsuite:config>

    
    <flow name="salesforce-to-netsuite-order-flow" doc:name="Salesforce to NetSuite Order Flow" doc:description="Syncs Closed Won Salesforce opportunities to NetSuite as sales orders">

        
        <salesforce:modified-object-listener
                objectType="Opportunity"
                config-ref="salesforceConfig"
                doc:name="Listen for Modified Opportunities"
                doc:description="Polls Salesforce every 60 seconds for modified Opportunity records">
            <scheduling-strategy doc:description="Defines polling frequency for the listener">
                <fixed-frequency frequency="60000" doc:description="Polls every 60,000 milliseconds (1 minute)" />
            </scheduling-strategy>
        </salesforce:modified-object-listener>

        <logger level="INFO" message="Opportunity modified: #[payload.Id] - Stage: #[payload.StageName]" doc:name="Log Opportunity Update" doc:description="Logs the ID and stage of the modified Opportunity record" />

        
        <choice doc:name="Check if Closed Won" doc:description="Routes the flow based on whether the Opportunity is Closed Won">
            <when expression="#[payload.StageName == 'Closed Won']" doc:description="Processes opportunities with StageName equal to 'Closed Won'">

                <logger level="INFO" message="Processing Closed Won Opportunity: #[payload.Name] (Amount: #[payload.Amount])" doc:name="Log Closed Won" doc:description="Logs the name and amount of the Closed Won Opportunity being processed" />

                
                <ee:transform doc:name="Map Opportunity to NetSuite Order" doc:description="Transforms Salesforce Opportunity data into NetSuite sales order format using DataWeave">
                    <ee:message doc:description="Defines the message transformation for the payload">
                        <ee:set-payload doc:description="Maps Opportunity fields to NetSuite order structure with customer and line items"><![CDATA[%dw 2.0
                            output application/java
                            ---
                            {
                            entity: "salesOrder",
                            entity @ {
                            customer: {
                            internalId: payload.AccountId default ""
                            }
                            },
                            tranId: payload.Id,
                            memo: "Order created from Salesforce Opportunity: " ++ payload.Name,
                            itemList: {
                            item: [{
                            item: {
                            internalId: "1"
                            },
                            quantity: 1,
                            rate: payload.Amount default 0
                            }]
                            }
                            }]]></ee:set-payload>
                    </ee:message>
                </ee:transform>

                <logger level="INFO" message="Transformed payload for NetSuite: #[output application/json --- payload]" doc:name="Log Transformed Payload" doc:description="Logs the transformed payload in JSON format for debugging" />

                
                <netsuite:add config-ref="netsuiteConfig" doc:name="Create NetSuite Order" doc:description="Creates a new sales order record in NetSuite using the add operation" />

                <logger level="INFO" message="NetSuite Order created successfully: #[payload]" doc:name="Log Success" doc:description="Logs successful creation of NetSuite order with response payload" />

            </when>
            <otherwise doc:description="Handles opportunities that are not in Closed Won stage">
                <logger level="INFO" message="Opportunity not in Closed Won stage, skipping. Current stage: #[payload.StageName]" doc:name="Log Skipped" doc:description="Logs that the Opportunity is being skipped with its current stage" />
            </otherwise>
        </choice>

        
        <error-handler doc:description="Handles errors that occur during the flow execution">
            <on-error-propagate type="ANY" doc:description="Catches all error types and propagates them after logging">
                <logger level="ERROR" message="Error processing Opportunity: #[error.description]" doc:name="Log Error" doc:description="Logs error details when Opportunity processing fails" />
            </on-error-propagate>
        </error-handler>

    </flow>

</mule>

上記のテンプレートを確認し、各要素に求められる詳細度とスタイルを把握してください。説明では、次の点に注目してください。

• 設定プロパティとコネクター設定：対象のシステムと認証方式を記載します
• 接続要素：認証タイプと認証情報の種類を明記します
• フローとリスナー：ビジネスプロセスと、そのトリガーを説明します
• スケジュール戦略：ポーリング頻度をわかりやすく記載します
• ロガー：記録する具体的な情報と、その理由を説明します
• choice ルーターと when／otherwise：条件とルーティングのロジックを説明します
• 変換：ソースデータ、ターゲット形式、変換の目的を示します
• コネクターの操作：操作の内容と対象のシステムを記載します
• エラーハンドラー：捕捉するエラーと実行する処理を説明します

D. ファイルへのすべての編集を 1 回の Write 操作で行う

重要：ファイルサイズにかかわらず、1 ファイルにつき Write ツールの呼び出しは 1 回だけにしてください。

• 手順 A で読み取った実際のファイル内容を使用します
• ファイル内の該当するすべての要素に doc:description 属性を追加します
• 既存の内容はすべてそのまま保持します：
  • 名前空間宣言とその元の順序
  • 要素名と属性名（記載どおりの表記）
  • 既存のすべての属性（doc:id、doc:name など）
  • CDATA ブロック、コメント、空白、インデント
  • 改行と書式

1 回の Write で行う方法：

• doc:description の追加をすべて反映した、変更後のファイル全体を作成します
• Write ツールを 1 回だけ呼び出し、変更後のファイル全体をディスクに保存します
• これにより、ファイルサイズにかかわらず、ファイルごとの承認プロンプトは 1 回だけになります
• バッチ処理や複数回の書き込みは行わず、完全な内容を 1 回で書き込みます

この方法のメリット：

• 最もシンプルな方法です。1 ファイルにつき書き込みは 1 回です
• ファイルサイズにかかわらず、ファイルごとの承認プロンプトは 1 回だけです
• すべての変更を一括で適用するアトミックな操作です。すべての変更が適用されるか、何も適用されないかのいずれかです
• 変更内容をまとめて確認しやすくなります
• 更新が一部だけ反映されるリスクがありません

手順 4：変更内容を提示して承認を得る

ファイルのすべての編集が完了したら：

• 追加した doc:description 属性の数を要素の種類ごとにまとめます
• スキップした要素とその理由を示します
• Write ツールにより、ユーザーの承認プロンプトが自動的に表示されます
• 承認されたら、次のファイルに進みます
• 拒否されたら、調整が必要な内容を確認し、ファイルを再読み込みして現在の状態を確認します

手順 5：すべてのファイルで繰り返す

src/main/mule/ ディレクトリ内の各 XML ファイルに対して、この手順を繰り返します。

手順 6：最終報告

すべてのファイルの処理後、次の内容を報告します：

• スキャンしたファイル数
• 変更したファイル数
• 追加した doc:description 属性の合計数
• 更新した doc:description 属性の合計数