codebase-research

コードベースの調査

Datex Studio ブランチを読み取り専用で調査し、コンポーネント、フローソース、型定義、データソース、設定など、コードの現在の状態に関する質問に回答します。変更は一切行いません。

これはユーティリティスキルです。ほかのスキルが利用できる、根拠に基づいた回答を生成します。何かを作成、変更、検証、デプロイすることはありません。

使用する場合

タスクを進める前に、現在のコードベースに関する事実を確認する必要があるときに、このスキルを呼び出してください。主な利用者は次のとおりです。

• impact-analysis — 呼び出し元を逆方向に追跡する前に、設定の役割を理解する必要があります。
• requirements-gathering — 既存のレポート／フロー／データソースを調査し、実効的な要件を抽出する必要があります。
• report-creator — 作成前に、フィールドの形状、データソースの出力、既存のレポートパターンを確認する必要があります。
• 状態を変更せずに、根拠に基づく正確な調査を必要とする、将来のあらゆるスキル。

次のような質問をユーザーから受けた場合も、直接呼び出してください。

• 「コードベースを調査して、X の仕組みを教えてください。」
• 「Y の定義場所を調べてください。」
• 「Z を参照している箇所をすべて見つけてください。」
• 「xxx_flow 関数は実際に何をしますか？」
• 「OrderStatus が受け付ける列挙値は何ですか？」

使用しない場合

• OData スキーマの検索には使用しないでください — schema-explorer に委任してください。生の OData メタデータを親コンテキストに読み込まないでください。
• ファイルの変更には使用しないでください — このスキルは厳密に読み取り専用です。回答から変更が必要になった場合は、適切な作成／編集スキルに引き継いでください。
• ライブデータに対するクエリの実行には使用しないでください — その場合は odata-execution または db-query を使用してください。
• ブランチ全体の詳細なアーキテクチャレビューには使用しないでください — その場合は branch-code-reviewer を使用してください。このスキルは、対象を絞った質問に回答します。

モード

これは読み取り専用の調査タスクです。ファイルの編集、作成、変更は行わないでください。upsert、validate --fix、その他あらゆる書き込みなど、ブランチの状態を変更するコマンドは実行しないでください。dxs CLI を通じて読み取ったブランチが信頼できる情報源です。ローカルの src/ チェックアウトが正しい情報源だと決して思い込まないでください。dxs source explore config <ref> --branch <id>（設定全体）、dxs source explore configs（一覧）、dxs source explore summary／trace／graph、dxs schema describe／search、および読み取り専用エンドポイントに対する dxs odata execute など、読み取り専用のコマンドのみを使用してください。生の JSON が必要な場合は、dxs configuration get <type> <id> -b <id> -O envelope.json の後に jq .json envelope.json を実行してください。一時的な使い捨てファイルに出力し、信頼できる情報源の永続的なコピーを作成しないでください。

利用可能な情報源

おおむね次の優先順位で情報源を調査してください。

• ブランチ上のコンポーネント設定 — アクション（*-footprintFlow）、関数（*-flow）、その他すべてのタイプ。各設定は、TypeScript を埋め込んだ JSON です。dxs source explore config <referenceName> --branch <id>（または dxs configuration get <type> <id> -b <id> -O envelope.json → jq .json）で取得してください。ブランチが信頼できる情報源です。ローカルのチェックアウトを読み取らないでください。
• 型定義 — customtype 設定（*-customType）。インターフェースと列挙型がここにあります。ブランチから取得し、要約よりもこちらを優先してください。
• OData スキーマ — エンティティ、プロパティ、キー、ナビゲーションの検索は schema-explorer スキルに委任してください。生のスキーマ文書を親に読み込まないでください。
• プラットフォームのドキュメント — datex-studio-shared、datex-studio-conventions、datex-studio-runtime の各スキルには、作成仕様、規約、ランタイムのセマンティクスが含まれています。「現在何が存在するか」ではなく、「どのように動作すべきか」が質問の対象である場合に参照してください。
• プロジェクト／機能のコンテキスト — プロジェクト内の CLAUDE.md ファイル。ドメイン知識やプロジェクト固有の規約が記載されています。古くなっている可能性があるため、信頼できる情報源ではなく、手がかりとして扱ってください。

Datex Studio 固有のパターン

このスキルを汎用的なものにしないためのパターンです。毎回適用してください。

1. フローコードは JSON の中にあり、上にあるわけではありません

アクション、関数、またはフローベースのコンポーネントを読むとき、実行可能な TypeScript はトップレベルの JSONではありません。実際のコードは、次の場所に埋め込まれた文字列です。

nodes[0].stepConfig.executeCodeConfig.code

TypeScript を分析するには、その文字列を抽出し、TypeScript として読み取って分析してください。このパスをたどらず、周囲の JSON を読むだけでは、実装ではなくメタデータしか得られません。

複数ステップのフローを調べるときは、nodes[*].stepConfig.executeCodeConfig.code を順に処理してください。各ステップには、それぞれ独自のコード本体があります。

2. OData スキーマのクエリは schema-explorer に委譲する

質問がエンティティ、プロパティ、キー、ナビゲーション、または OData メタデータに関するものである場合：

• 必ず schema-explorer スキルを、焦点を絞ったクエリで呼び出してください。
• **生のスキーマドキュメントを親コンテキストに読み込まないでください。**サイズが大きくノイズが多いため、コンテキストウィンドウを圧迫します。
• schema-explorer は簡潔で構造化された回答（エンティティの形状、プロパティ一覧、ナビゲーションチェーン）を返し、接続の解決と FootPrintApi 固有の例外処理も行います。

何らかの理由で schema-explorer を利用できない場合は、代わりに dxs schema describe / dxs schema search を直接使用してください。ただし、スキーマ全体のダンプを親コンテキストに読み込むことは、引き続き避けてください。

3. 列挙値は customType 設定にあります

「列挙型 X が受け入れる値は何か？」または「フィールド Y の値として何が可能か？」という質問の場合：

• 「メンバー名だけ」を最速で確認する方法： dxs configuration nomenclature -b <id>（必要に応じて --search <name> または --package <Pkg> --kind enum を指定）は、各 <Package>.<Type> とその列挙メンバーを constantValues から取得し、1 回の簡潔な呼び出しで返します（型ごとの取得は不要です）。../datex-studio-shared/context-navigation.md#discovering-custom-types-and-enum-members を参照してください。
• 完全な定義が必要な場合（説明、値のマッピング、インターフェースのフィールド形状）：ブランチから *-customType 設定を取得してください。dxs source explore config <enum_referenceName> --branch <id> を使用するか、dxs source explore configs --type customtype --search <name> で候補を一覧表示します。
• そこで列挙型の定義を確認してください。これが信頼できる情報源です。
• CLAUDE.md やスキルの参照情報の要約だけに依存しないでください。古くなっている可能性があります。
• フローのパラメーターから型が参照されている場合は、その参照を customType 設定までたどってください（dxs source explore trace <flow_ref> --branch <id> で型参照を確認できます）。

4. 回答／情報源／留意点の形式

常に 3 部構成の形式で回答してください（以下の「回答形式」を参照）。この形式により、回答を監査可能にし、曖昧さを明示できます。これは、このスキルの出力を利用する後続スキルにとって非常に重要です。

ワークフロー

1. 質問を言い換える — 利用者が意図を確認できるよう、1 行で記述します。
2. 情報源を選ぶ — 必要な各事実について、利用可能な情報源のうち、どれが回答に使えるかを特定します。ドキュメントよりコードを、要約より型情報を、生のスキーマより schema-explorer を優先してください。
3. 調査する — dxs source explore でブランチから設定を取得するか、OData スキーマについては schema-explorer を呼び出します。上記の Datex Studio 固有の 4 つのパターンを適用してください。調査の範囲を絞り、ブランチ全体をくまなく調べないでください。
4. 相互参照する — 質問がコードとスキーマ、またはコードと型情報にまたがる場合は、相互参照してください。情報源の内容が食い違う場合は、その相違を明示し、黙って一方を選ばないでください。
5. 回答を作成する — 回答／情報源／留意点の形式でまとめます。

ガイドライン

• 具体的に記述してください。 見つけた行、プロパティ、または値を引用してください。短い場合は、要約せずに引用してください。
• 出典を明記してください。 すべての主張は、出典となった設定（dxs source explore コマンドと referenceName）または結果を得た schema-explorer クエリまでたどれるようにしてください。
• 曖昧さを明示してください。 2つの出典が食い違う場合、CLAUDE.md の要約がコードと矛盾する場合、または入手可能な出典だけでは質問に完全に回答できない場合は、「注意事項」にその旨を記載してください。
• 対象に集中してください。 調査の依頼は、無関係なファイルを調べる許可ではありません。質問に回答したら、そこで終了してください。
• 推測しないでください。 答えが見つからない場合は、推測せずに「参照した出典には見つかりませんでした」と述べてください。
• 読み取り専用を守ってください。 調査中にバグや改善点に気付いた場合は、「注意事項」に記載してください。ただし、修正はしないでください。見つかった内容をどうするかは利用者が判断します。

回答形式

質問に直接、簡潔に回答してください。次の3部構成を使用してください。

## Answer

<the direct response — concrete, quoted from sources where possible>

## Sources

- `<file path or skill call>` — <what this source contributed>
- `<file path or skill call>` — <what this source contributed>
- ...

## Caveats

- <any ambiguity, conflicting information, assumption, or "not found" note>
- <if none, write: "None.">

例

## Answer

`update_shipment_status_flow` updates a shipment's `Status` field via the
Footprint API. It accepts `shipmentId: string` and `newStatus: ShipmentStatus`
and returns `{ success: boolean, message: string }`. The function calls
`PATCH /api/Shipments({shipmentId})` with `{ Status: newStatus }`.

## Sources

- `dxs source explore config update_shipment_status_flow --branch <id>` —
  extracted code from `nodes[0].stepConfig.executeCodeConfig.code`; parameter
  list and return shape on the top-level JSON.
- `dxs source explore config shipment-customType --branch <id>` —
  `ShipmentStatus` enum values: `Open`, `InProgress`, `Closed`, `Cancelled`.
- `schema-explorer` (entity `Shipments`) — confirmed `Status` is an
  enum-backed string property, not a navigation.

## Caveats

- The flow's JSDoc says it returns `void`, but the actual code returns
  `{ success, message }`. The JSDoc appears stale.
- `CLAUDE.md` lists a fifth status `Voided`; not present in
  `shipment-customType.json`. Type file wins.

出力要件

上記の3つのセクションを含む回答を1つだけ出力してください。ファイルへの書き込み、状態の変更、利用者に代わって追加コマンドを実行することは禁止です。

このスキルの利用者が、回答に基づいてどうするかを判断します。このスキルの役割は、コードベースの現在の状態を把握しやすくすることだけです。