docs-check-kibana-oas

Name: docs-check-kibana-oas
Author: elastic

github.com/elasticテスト・品質7247 回インストール2 日前に更新

docs-check-kibana-oas について

docs-check-kibana-oas は、Elastic API ドキュメントのルールに基づいて Kibana のプルリクエストをレビューするスキルです。ファイルと行番号を含む具体的な対応リストを作成し、生成 YAML の問題を TypeScript のソースまで追跡します。

主な機能

01Kibana API ドキュメント変更のレビュー
02ルート、スキーマ、例の確認
03生成 YAML の問題を TypeScript まで追跡
04実行可能なファイルと行番号の提示

活用シーン

01Kibana プルリクエストの OAS 変更監査
02不足しているルートメタデータや説明の検出
03変更された API スキーマの文書上の問題特定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-check-kibana-oas

インストール後、Claude Code で/docs-check-kibana-oasを入力して読み込まれたか確認します。

同梱ファイルevals/evals.json

詳細

Kibana OAS の確認

elastic/kibana の Kibana PR を、Elastic API ドキュメントのチェックリスト、基本ガイドライン、Kibana クイックスタートに照らしてレビューします。具体的な対応項目を出力してください。各項目には、変更するファイルと行を記載します。

入力

$ARGUMENTS は PR 番号または URL です。PR 番号を抽出してください。例：

/docs-check-kibana-oas 289719
/docs-check-kibana-oas https://github.com/elastic/kibana/pull/289719
/docs-check-kibana-oas https://github.com/elastic/kibana/pull/289719/changes

PR 番号が指定されていない場合は、番号を尋ねてください。

重要な原則：YAML は生成物であり、TypeScript が信頼できる情報源です

oas_docs/output/ 以下のファイル（kibana.yaml、kibana.serverless.yaml）は、TypeScript のルート定義から自動生成されます。CI は push 時に再生成します。YAML の差分を使って、問題（x-state の欠落、安定性ラベルの誤り、空の値など）を検出してください。ただし、出力する対応項目はすべて、生成元の TypeScript を指す必要があります。YAML を手動で編集するよう提案してはいけません。

ワークフロー

1. PR を取得する

gh pr diff <PR_NUMBER> --repo elastic/kibana
gh pr view <PR_NUMBER> --repo elastic/kibana --json title,body,files,headRefName

差分全体を保存してください。複数回スキャンします。

2. PR ブランチをチェックアウトする

ローカルの Kibana クローンを探します。次の順に確認してください。

現在の作業ディレクトリ（kibana リポジトリ内の場合）
~/elastic/kibana

次に、PR ブランチをチェックアウトします。

cd <KIBANA_DIR> && gh pr checkout <PR_NUMBER>

どちらの場所にもローカルクローンが見つからない場合は、ユーザーにその旨を伝え、Kibana のチェックアウト先を尋ねてください。

正確な行番号を特定するため、チェックアウトしたリポジトリから実際のソースファイルを読み取ってください。差分のハンクヘッダーから行番号を算出してはいけません。

3. 変更を分類する

差分から、変更されたファイルを次のように分類します。

ルート定義：server/routes/ 以下で router.versioned.* エンドポイントを登録する .ts ファイル
スキーマ定義：ルートの検証に使用される schema.object / schema.maybe などを含む .ts ファイル
生成された YAML：oas_docs/output/ — 問題を示すシグナルの確認にのみ使用
サンプルファイル：routes/examples/ 以下の YAML
その他：型、テスト、モック — 記録はしますが、監査はしません

4. 監査する

以下のルールセクションに記載されたすべてのルールを、差分に適用します。生成された YAML は、相互確認のためのシグナルとして使用してください。YAML に問題（x-state の欠落、x-state が空、ラベルの誤りなど）がある場合は、TypeScript のソースをたどって根本原因を特定してください。

指摘事項ごとに、チェックアウトしたブランチの実際のファイルを読み、正確な行番号を確認してください。開発者が変更する必要のある行を指してください。

5. 兄弟ルートと相互確認する

PR で既存のリソースに新しいルートを追加する場合は、チェックアウトしたブランチから既存のルートを読み、規約を比較してください。新しいルートにはないものの、兄弟ルートで使われている説明用ドキュメントへのリンク、タグの使い方、サンプルファイルなどのパターンを確認します。

6. 出力する

簡潔な対応項目の一覧を出力し、その後に要約を記載します。簡潔にしてください。長い診断説明は不要です。

ファイルへのリンク

ファイルへの参照はすべて、PR の「Files changed」ビューへのクリック可能な Markdown リンクにしてください。

https://github.com/elastic/kibana/pull/<PR_NUMBER>/files#diff-<SHA256_OF_PATH>

アンカーを計算します。

echo -n "<full-repo-relative-path>" | shasum -a 256 | cut -c1-64

次のようにリンクします：agents.ts:689

ハッシュを計算できない場合は、PR のファイル一覧ページにファイルパスだけでリンクしてください。

形式

## OAS review — PR #<NUMBER>

**<PR title>**

### Actions

1. ❌ **Add `stability` to availability** — [agents.ts:689](<link>)
   `availability: { since: '9.5.0' }` → `availability: { stability: 'experimental', since: '9.5.0' }`

2. ❌ **Add description for `user_id` path param** — [agents.ts:140](<link>)
   Path parameters must have `meta: { description: '...' }`.

3. ❌ **Add narrative doc link** — [attachments.ts:105](<link>)
   Sibling conversation routes link to the agent chat docs. Consider adding a similar link.

4. ❌ **Summary exceeds 45 characters** — [agents.ts:684](<link>)
   `'Get all agent builder conversation attachments for a user'` → shorten to ~40 chars.

### Passes

- ✅ `summary` and `description` present — [agents.ts:684](<link>)
- ✅ Path params have `meta.description` — [agents.ts:700](<link>)
- ✅ Tags include `oas-tag` — [agents.ts:680](<link>)
- ✅ Example file referenced — [agents_get.yaml](<link>)

### Verdict

**N actions** (X required, Y suggested)

ルール：

❌ は、作成者が対応する必要のある項目に使用します
✅ は、問題のない項目に使用します。各項目は簡潔に、1 行で記載します
PR 作成者が今回の変更と既存の問題を区別できるよう、既存の問題には「（既存）」と記載します
修正が一行で済む場合は、必ず変更前 → 変更後を記載します
すべてのファイル参照は、PR のファイル一覧ビューへの Markdown リンクにします

ルール

これらのルールは、Elastic API docs checklist、core guidelines、organize and annotate guide、およびKibana quickstartに基づいています。また、既存の Kibana ルート全体で確認された規約も取り入れています。

1. ルートレベルの提供状況（ライフサイクルステータス）

新しいルートにはすべて、options ブロックに stability と since の両方を含む availability が必須です。これにより、公開されている API ドキュメントのバージョンバッジとテクニカルプレビューラベルが表示されます。

有効な stability 値と、表示されるラベルは次のとおりです。

値	表示されるラベル	意味
`'experimental'`	Experimental	将来のバージョンで変更または削除される可能性があります
`'tech_preview'`	Technical preview	リリース前の機能であり、変更される可能性があります
`'stable'`	Generally available	本番環境で安定して使用できます（省略時のデフォルトですが、明示してください）

since は '9.2.0' のようなバージョン文字列です。API が初めてリリースされたバージョンを示します。Elastic Stack のドキュメントには表示されますが、サーバーレスのドキュメントでは省略されます。

正しいパターン：

router.versioned.get({
  path: '...',
  options: {
    tags: ['...', 'oas-tag:Agent builder'],
    availability: {
      stability: 'experimental',
      since: '9.6.0',
    },
  },
})

確認する項目：

❌ availability ブロックがない
❌ availability に stability がない
❌ availability に since がない
❌ stability の値が無効

2. ルートの概要

新しいルートにはすべて summary が必須です。概要は IDE、検索結果、ドキュメントの概要に表示されます。

概要のガイドライン：

5～45 文字 — 多くの場面で表示スペースが限られているため、短くします
動詞で始める — 「Get」「Create」「Update」「Delete」
基本的な動詞を使う — 「Retrieve」ではなく「Get」、「Modify」ではなく「Update」
冠詞を含める — 「Delete a space」、「Delete spaces」
文頭のみ大文字にする — 最初の単語と固有名詞のみ大文字にします
末尾にピリオドを付けない

確認する項目：

❌ summary がない
❌ 概要が45文字を超えている
❌ 概要が動詞で始まっていない
❌ 概要がタイトルケースになっている、または末尾にピリオドがある

3. ルートの説明

新しいルートにはすべて description が必須です。説明では Markdown 形式を使用できます。次の内容を記載してください。

目的と影響：この操作は何を行い、ユーザーはどのような理由で必要とするのか？
前提条件や背景：このエンドポイントを呼び出す前に、ユーザーが知っておくべきことは何か？
制約：有効な値、形式、サイズ制限、レート制限
関連性：パラメーターはどのように相互作用し、複数の値はどのように処理されるのか？

適切な説明では、概要を超える詳細を加えます。不適切な説明は、概要を言い換えただけのものです。

良い例：'エージェントとの新しい会話を作成します。会話はセッションをまたいで保持され、アクセス制御を使用して他のユーザーと共有できます。詳しくは、[エージェントチャットのドキュメント](https://www.elastic.co/docs/...)を参照してください。'

悪い例：'会話を作成します。'（概要を言い換えているだけで、何も追加していません）

確認する項目：

❌ description がない
❌ 説明が概要をそのまま複製したもの、または言い換えただけのもの
❌ ユーザーに必要な制約や前提条件が説明に記載されていない

4. ナラティブドキュメントへのリンク

ルートの説明には、関連するナラティブドキュメントのページへのリンクを末尾の文として含めてください。これは既存の Kibana ルート全体で確認された規約です。同じリソースを扱う関連ルートにすでにそのようなリンクがある場合は、特に重要です。

パターン：

description:
  'List all conversations. To learn more, refer to the [agent chat documentation](https://www.elastic.co/docs/...).',

確認方法：関連ルートと比較します。同じリソースを扱う他のルートに「詳しくは…」や「ドキュメントを参照してください」というリンクがあり、新しいルートにない場合は、指摘してください。

確認する項目：

❌ 関連ルートにリンクがあるのに、ナラティブドキュメントへのリンクがない（警告であり、エラーではありません。新機能の場合、リンク先がまだ存在しない可能性があります）

5. タグ

ルートのtags配列には、少なくとも1つのoas-tag:エントリーが必須です。タグは公開ドキュメント内でAPIを機能ごとにグループ化します。

タグのガイドライン：

文頭のみ大文字にします：'oas-tag:Agent builder'であり、'oas-tag:agent builder'ではありません
関連するルート間で一貫したタグ名を使用します
ナビゲーションを整理するため、1つのルートにつきoas-tagは1つにします

確認する項目：

❌ tags配列にoas-tag:*がない
❌ タグ名の大文字・小文字が、関連するルートと一貫していない
❌ 1つのルートに複数のoas-tag:エントリーがある

6. パスパラメーターの説明

すべてのパスパラメーターには、スキーマ定義内にmeta: { description: '...' }が必須です。

正しいパターン：

params: schema.object({
  conversation_id: schema.string({
    meta: { description: 'The unique identifier of the conversation.' },
  }),
}),

確認する項目：

❌ パスパラメーターにmetaがない、またはmeta内にdescriptionがない

7. プロパティの説明

新しいリクエストボディ、クエリ、またはレスポンスの各プロパティには、meta: { description: '...' }が必須です。

適切なプロパティの説明では、値が制御する内容、形式、および制約を説明します。

❌ 'The page size.' — 曖昧で、制約もデフォルト値もありません
✅ 'The maximum number of results to return. Must be between 1 and 1000. Defaults to 20.'

確認する項目：

❌ 新しいプロパティにmetaがない
❌ metaはあるが、descriptionがない
❌ 説明が、プロパティ名を言い換えただけの一般的な一文になっている（たとえば、nameというプロパティに対する'The name.'）

8. 列挙値の説明

プロパティでschema.oneOfまたはschema.literalを使用して固定値のセットを定義する場合は、プロパティの説明または個々のスキーマオプションで、各値を説明してください。

意味が自明な値は、説明を省略できます。

true / false、asc / desc、enabled / disabled — 名前から明らかです
read / write / admin — 自明ではありません。adminではwriteを超えて何が許可されるのでしょうか？
low / medium / high — 自明ではありません。各レベルで具体的に何が変わるのでしょうか？

確認する項目：

❌ 名前から意味や動作の違いが明確でないのに、列挙値に説明がない

9. デフォルト値

省略可能なパラメーターとプロパティには、デフォルト値を記載してください。Kibanaのルートスキーマでは、schema.maybe(schema.string({ defaultValue: '...' }))を使用するか、サーバー側のデフォルト値を説明に記載します。

正しいパターン：

page_size: schema.maybe(
  schema.number({
    defaultValue: 20,
    meta: { description: 'Number of results per page. Defaults to 20.' },
  })
),

デフォルト値がサーバー側で設定されている場合（スキーマ内ではない場合）は、代わりに説明に記載します：'Sort order. The server defaults to descending if not specified.'

確認方法：同じリソースの関連ルートと比較します。関連ルートにpage_sizeのデフォルト値が記載されているのに、新しいルートには記載されていない場合は、指摘してください。

確認する項目：

❌ 値によって動作が変わる省略可能なパラメーターに、未記載のデフォルト値がある

10. プロパティ単位の利用可能性

既存ルートのスキーマに新しいプロパティを追加し、そのプロパティがルート自体より後のバージョンで提供される場合、そのプロパティにはstabilityとsinceを含む独自のmeta.availabilityが必須です。

検出方法：既存ルートのバリデーションブロック内で追加されたschema.maybe(...)またはschema.object(...)のフィールドを探します。ルートのsince: '9.2.0'に対し、新しいプロパティが'9.6.0'で提供される場合、そのプロパティには独自の利用可能性情報が必要です。

正しいパターン：

new_field: schema.maybe(
  schema.string({
    meta: {
      availability: { stability: 'experimental', since: '9.6.0' },
      description: 'Description of the new field.',
    },
  })
),

確認する項目：

❌ 古いルートに追加された新しいプロパティにmeta.availabilityがない
❌ プロパティにavailabilityはあるが、stabilityまたはsinceがない

11. 非推奨

非推奨のルートやプロパティには、その旨を示す必要があります。Kibanaでは、ルートのoptionsでdeprecatedフラグを設定でき、プロパティの説明には非推奨であることを記載します。

確認する項目：

❌ コメントや説明文でプロパティまたはルートを非推奨としているのに、deprecated: trueのマーカーがない
❌ 非推奨のプロパティに、代わりに何を使用するかを説明する記述がない

12. レスポンスの例

新しいルートには、oasOperationObject を参照する例のファイルを SHOULD 追加してください。例を追加すると、API ドキュメントの使いやすさが大幅に向上します。

インラインの TypeScript の例（開発時に型チェックされます）：

.addVersion({
  version: '2023-10-31',
  options: {
    oasOperationObject: () => ({
      requestBody: {
        content: {
          'application/json': {
            examples: {
              example1: {
                summary: 'An example request',
                value: { name: 'Example' } as MyType,
              },
            },
          },
        },
      },
    }),
  },
})

YAML ファイルの例：

import path from 'node:path';
.addVersion({
  version: '2023-10-31',
  options: {
    oasOperationObject: () => path.join(__dirname, 'examples/my_route.yaml'),
  },
})

YAML の例の構造（server/routes/examples/ 内）：

requestBody:
  content:
    application/json:
      examples:
        example1:
          summary: Example request
          description: An example of creating a resource
          value:
            name: 'Example'
responses:
  200:
    content:
      application/json:
        examples:
          success:
            summary: Successful response
            value:
              id: '12345'
              name: 'Example'

例のガイドライン：

プレースホルダーではなく、現実的なデータを使用します
各例には、わかりやすい概要（45 文字未満）を記述します
成功レスポンスの例（HTTP 200）を少なくとも 1 つ含めます
cURL と Console の例に x-codeSamples を追加することを検討します

指摘する項目：

❌ oasOperationObject への参照がない（警告 — 強く推奨）
❌ 例のファイルにプレースホルダーや空の値が含まれている
❌ 成功ケースのレスポンス例がない

13. Operation ID（助言のみ — Actions リストには含めないでください）

パブリックルートでは、明示的な operationId を任意で設定できます。SDK と CLI のジェネレーターは、この ID をメソッド名／コマンド名として使用します。省略した場合、ジェネレーターはメソッドとパスから名前を生成します（例：post-foo）。この名前はわかりにくいことがよくあります。

適切なパターン：

router.versioned.post({
  path: '/api/foo',
  access: 'public',
  summary: 'Create a foo resource',
  operationId: 'create-foo',
  options: { ... },
});

ガイドライン：

create-foo、get-foo、delete-foo のような、kebab-case の verb-resource 名を使用します。
同じルートのバージョン間で operation ID を維持し、理由なく変更しないでください。

これは提案であり、準拠ルールではありません。❌ Actions リストに追加したり、判定に含めたりしないでください。ユーザーが SDK／CLI の生成や operation ID について具体的に質問した場合、または差分内のルートですでに kebab-case の verb-resource 規則と一貫しない operation ID が設定されている場合に限り、1 行の補足（「明示的な operationId の追加を検討してください」）として指摘してください。

14. クロスチェック：診断の手掛かりとしての生成済み YAML

oas_docs/output/ 内の YAML ファイルは自動生成されます。YAML を直接編集するよう提案してはいけません。修正はすべて TypeScript のソースに加えてください。

YAML の x-state 値を使って問題を検出します。

YAML `x-state`	TypeScript での意味
`Experimental; added in 9.6.0`	`availability: { stability: 'experimental', since: '9.6.0' }`
`Technical Preview; added in 9.2.0`	`availability: { stability: 'tech_preview', since: '9.2.0' }`
`added in 9.0.0`（ラベルなし）	`availability: { stability: 'stable', since: '9.0.0' }`
`Experimental`（バージョンなし）	`kibana.serverless.yaml` では正常です。serverless では `added in` を省略します
`''`（空文字列）	TypeScript の `availability` に `stability` がありません
欠落	TypeScript に `availability` ブロックがありません

指摘する項目（必ず TypeScript ファイルを指摘してください）：

❌ x-state が空、または欠落している → TS のルートをたどり、availability または stability の欠落を指摘します
❌ YAML のラベルが TS の stability と一致しない → TS 側の不一致を指摘します
serverless の YAML で added in が省略されている場合は想定どおりであり、指摘事項ではありません

Markdown 対応

ログインしてコメント

基本情報

作者: elastic
リポジトリ: elastic/elastic-docs-skills
カテゴリ: テスト・品質
インストール数: 47
GitHub スター: 72

問題を報告