sap-object-documenter

SAP オブジェクトドキュメンター

カスタム ABAP オブジェクトについて、パッケージ単位で安定したドキュメントを作成します。各オブジェクトをスタイル（Classic／Modern／Mixed）で分類し、目的と依存関係を要約して、リポジトリの Wiki やオンボーディング資料に適した Markdown を出力します。

このスキルは、単一のオブジェクトを対話形式で対象とする explain-abap-code を補完します。複数のオブジェクトについてまとめてドキュメントを作成したい場合にこちらを使用してください。たとえば、オンボーディング時に docs/ フォルダーを用意したり、チームへの引き継ぎ前にナレッジ移転用の資料を作成したりできます。

スマートデフォルト（黙って適用し、尋ねない）

設定	デフォルト	理由
含める対象	Z*、Y*、顧客名前空間	顧客コードのみ
深さ	1（直接の依存関係のみ）	ドキュメントを読みやすく保ち、推移的な依存関係であふれないようにします
スタイル分類	あり	追加コストなしで情報が得られます。SAPLint に尋ねるだけです
オブジェクトごとのセクションの長さ	Markdown で約30～60行	有用な情報量を保ちつつ、長すぎて読まれなくなるのを防ぎます
出力形式	Markdown ファイル	持ち運びやすく、あらゆる Wiki で使えます

入力

ユーザーは次のいずれか1つを指定します。

• パッケージ（例：Z_SALES_EXTENSIONS）— パッケージ内のカスタムオブジェクトをすべてドキュメント化します
• オブジェクト一覧 — カンマ区切り（例：ZCL_SALES_HANDLER, ZR_POSTING_JOB）
• タイプ＋プレフィックス — 例：「Z* クラスをすべてドキュメント化」→ SAPSearch(query="Z*", objectType="CLAS") を実行します

また、次の項目も指定できます。

• 出力パス — デフォルト：docs/custom-code/<package_or_group>.md
• 単一ファイルか、オブジェクトごとにファイルを分けるか — デフォルト：オブジェクトごとのセクションを含む単一ファイル。ただし30を超える場合はオブジェクトごとにファイルを作成します

対象が100オブジェクトを超える場合は処理を中止し、対象を絞るようユーザーに尋ねてください。誰にも読まれないドキュメントは、ドキュメントがないよりも望ましくありません。

ステップ 1：対象範囲の列挙

1a. パッケージのパス

SAPRead(type="DEVC", name="<package>")

1b. オブジェクト一覧のパス

それぞれを解決します。

SAPSearch(query="<name>")

ドキュメント化する価値のあるタイプに絞り込みます：CLAS, INTF, FUGR, PROG, DDLS, BDEF, SRVD, TABL。生成されたプロキシ、移送オブジェクト、テスト用インクルードクラスは除外します。

ステップ 2：各オブジェクトのソースとメタデータを取得

各オブジェクトについて、次を並列で実行します。

SAPRead(type="<type>", name="<name>")             # Source
SAPContext(type="<type>", name="<name>", depth=1) # Dependencies (CLAS/INTF/PROG/FUNC/DDLS only; BTP: CLAS/INTF/DDLS)

SAPContext がサポートしていないオブジェクトタイプ（FUGR、BDEF、SRVD、TABL、DOMA、DTEL）では、依存関係の呼び出しを省略し、ソースを正規表現でスキャンして「明らかな」呼び出し元／依存関係を列挙します。対象は CL_*、IF_*、SAP*、および CALL FUNCTION '...' です。「Dependencies」セクションには、確度が低下していることを記載します。

クラスについては、次も実行します。

SAPRead(type="CLAS", name="<name>", method="*")   # Method listing with signatures

CDS ビューについては、次も実行します。

SAPRead(type="DDLS", name="<name>", include="elements")  # Field list

ステップ 3：ABAP スタイルの分類（クラスとプログラムのみ）

SAPLint(action="lint", name="<name>")

すでにソースをメモリ上に保持している場合は、name の代わりに source=<source> を渡してください。ソースを再取得せずに済みます。

Lint の検出結果を解釈します。

Modern ABAP の兆候	Classic ABAP の兆候
CDS、RAP、インライン宣言、NEW、REDUCE、CORRESPONDING を使用	FORM/ENDFORM、TABLES 文、OCCURS を使用
SELECT * を使用せず、ORDER BY と一括処理を使用	ループ内で1行ずつ SELECT SINGLE を実行、SELECT * を使用
テストクラスを備えたクラス、DI にインターフェースを使用	グローバル状態を持つ汎用モジュール
MOVE-CORRESPONDING を使用せず、CORRESPONDING OF を使用	多用される PERFORM チェーン

次のように分類します。

• Modern — モダンなパターンが中心で、クラウド対応のスタイル
• Classic — クラシックなパターンが中心で、7.40 より前の雰囲気
• Mixed — 両方が存在（多くの場合、モダンなラッパーがクラシックな内部処理を包んでいます）

SAPLint が失敗した場合、またはオブジェクトが Lint の対象外（例：CDS ビュー、テーブル）の場合は、このセクションを省略します。

ステップ 4：（任意）mcp-sap-docs によるビジネスコンテキストの検索

名前や構造が SAP アプリケーションコンポーネント（FI、SD、MM など）を参照するオブジェクトについて、コンポーネントのコンテキストを補足します。

search("<component_code> application component")

例：ZCL_FI_GL_POSTING → 「FI-GL general ledger」を検索して、ドキュメントのヘッダーに記載する SAP アプリケーションコンポーネントの説明を取得します。

オブジェクト名から手掛かりが得られない場合は、このステップを省略します。

ステップ 5：Markdown を作成

5a. 単一ファイルの構成（オブジェクト数が30以下）

# <Package or group name> — Custom Code Documentation

_Generated <date> via sap-object-documenter skill on system <SID>._

## Overview

| Object | Type | Style | Purpose (1 line) |
|---|---|---|---|
| ZCL_SALES_HANDLER | CLAS | Modern | Behavior implementation for sales order RAP service |
| ZR_OLD_POSTING | PROG | Classic | Nightly batch for legacy FI posting |
| ...

## Objects

### ZCL_SALES_HANDLER

- **Type:** CLAS
- **Package:** Z_SALES_EXTENSIONS
- **Style:** Modern (uses RAP, inline decls, no SELECT *)
- **Purpose:** Handle validations and determinations for the Sales Order RAP business object.

**Public API**
- `validate_credit_limit( i_order )` — checks customer credit limit before save
- `determine_currency( c_order )` — defaults currency from sales org

**Dependencies**
- ZI_SALESORDER (CDS — root entity)
- CL_SALV_TABLE (A — released ALV class)
- ZCL_CREDIT_SERVICE (Z — custom credit service wrapper)

**Notes**
- No direct DB access; routes everything through the RAP entity.
- Tests: `ZCL_SALES_HANDLER_UT` (present, 8 test methods).

---

### ZR_OLD_POSTING
...

5b. オブジェクトごとに1ファイルの構成（>30 オブジェクト）

概要テーブル（各ファイルへのリンクを記載）を含む docs/custom-code/<package>/README.md を作成し、各オブジェクトについて、上記と同じセクションを含む <object_name>.md を1つずつ作成します。

5c. オブジェクトごとのヘッダー（正規フィールド）

- **Type:** <TADIR type>
- **Package:** <package>
- **Style:** Modern | Classic | Mixed | n/a
- **Purpose:** <one-sentence summary>
- **Last change:** <SAPRead VERSIONS — most recent timestamp + user>
- **Current transport:** <SAPTransport action="history" — current lock request, or "unlocked"; candidates are assignment choices, not history>

「Last change」と「Current transport」の行は、ARC-1 のリビジョン API と現在の割り当て API から取得します。 完全な移送履歴は、従来の history アクションでは取得できません。

Step 6: ディスクに書き込み、報告する

ローカルファイルシステム（Write ツール）を使って、Markdown ファイルを出力します。次のように短くまとめて返します。

Wrote 42 object docs to docs/custom-code/Z_SALES_EXTENSIONS/
  12 Modern | 18 Classic | 8 Mixed | 4 n/a (CDS/tables)

Longest objects (may need deeper docs):
  ZCL_SALES_HANDLER   (847 lines, 14 methods)
  ZR_OLD_POSTING      (1,204 lines)
  ...

追加の選択肢

• 「これらの中から、さらに詳しく説明したいものはありますか？」（→ explain-abap-code）
• 「このパッケージのクリーンコア対応状況を確認しますか？」（→ sap-clean-core-atc）
• 「まず使用されていないものを整理しますか？」（→ sap-unused-code）
• 「ドキュメント、使用方法、ATC、レビューカードを移行用ドシエにまとめますか？」（→ sap-migration-dossier）

エラー処理

エラー	原因	修正
オブジェクトが見つからない	名前が間違っている、または削除されている	記録してスキップし、残りの処理を続けます
SAPContext が失敗する	サポートされていない型	ソースを正規表現でスキャンし、インポートを手動で一覧表示します
SAPLint が失敗する	ソースがない（テーブル、CDS）、またはサポートされていない構文	そのオブジェクトのスタイル分類をスキップします
ソースが空	生成されたプロキシまたはスタブ	ドキュメントに「ソースが利用できません」と記載し、他のメタデータは引き続き出力します
出力パスがすでに存在する	ファイルの競合	タイムスタンプのサフィックスを追加するか、ユーザーに確認します
対象範囲に100件を超えるオブジェクトがある	ドキュメントが読みにくくなる	処理を停止し、対象範囲を絞るようユーザーに依頼します

注意事項

このスキルで行わないこと

• コード生成は行いません — 読み取りと要約のみです。
• 業務ロジックの英訳は行いません — 「Purpose」の行は、命名、クラスヘッダーのコメント、テストクラス名から導き出します。それらがない場合は、その旨を記載します。
• 適切なコードコメントの代わりにはなりません — 出力の質は、ソース内の命名の質に左右されます。
• オブジェクト間の統合は行いません — 各オブジェクトを個別に記述します。パッケージレベルのアーキテクチャ説明は対象外です。

このスキルを使用するタイミング

• カスタムコードパッケージについて、新しい開発者に説明するとき
• コンサルティング業務の引き継ぎ前 — 組織内の知識をドキュメントとして記録するとき
• 移行前のドキュメント作成（書き換え前の現状を記録するとき）
• コンプライアンス／監査証跡（オブジェクトごとのドキュメント作成が求められる組織もあります）
• ナレッジベースやリポジトリの Wiki の初期コンテンツ作成

このスキルを使用しないタイミング

• 単一のオブジェクトの場合 — explain-abap-code を使用します。より高速で、対話的に利用できます。
• SAP 提供のコードの場合 — このスキルは Z/Y のみが対象です。SAP オブジェクトには、直接 mcp-sap-docs を使用します。
• コード品質の分析が目的の場合 — migrate-custom-code を使用します。