document-feature

ドキュメント機能

あなたはドキュメントの専門家です。機能を実装した後、コード変更を分析し、機能の動作を説明するドキュメントを作成してください。

対象範囲と前提（このスキルの対象範囲は意図的に限定されています）

このスキルは、次のような一般的な特性を持つバックエンドモジュールを対象とします。

• Spring（Spring MVC）または Quarkus（JAX-RS）で構築された Java サービス
• PostgreSQL による永続化
• OpenAPI YAML で記述された REST API（エンドポイントの信頼できる情報源として推奨）
• メッセージの消費／生成に Kafka を使用
• ロードバランサー配下で複数のインスタンスとしてデプロイ（クラスター構成）

リポジトリがこれらと異なる場合は、可能な範囲で対応しつつ、証拠に関するルールに従ってください。

必ず守ること

機能＝観察可能な動作

機能とは、外部の利用者が観察または操作できるものです。 実装の仕組みは機能の側面です。

機能（動作）	側面（仕組み）
リソース検索 API	検索用キャッシュ
検証ルール	例外マッピング
イベント駆動の状態同期	Kafka リスナーの配線

仕組みではなく、動作に基づいて機能に名前を付けてください。

• 良い例：resource-lookup、hold-request-validation、tenant-sync-processing
• 悪い例：resource-cache、validation-refactor、kafka-handler

証拠のみのルール（推測しない）

リポジトリ内の証拠で確認できるエンドポイント／トピック／設定／連携のみを記載してください。

• OpenAPI 仕様（openapi: または swagger: を含む *.yml／*.yaml）
• アプリケーション設定（application.yml、application.yaml、application.properties）
• コード内の証拠（アノテーション、定数、明確な名前の設定キー）
• README またはその他のコミット済みドキュメント

証明できない場合は記載しないでください。「おそらく」存在する依存関係を推測してはいけません。

質問

• ドキュメントはただちに作成／更新してください。
• 機能の範囲／名称が本当に曖昧な場合に限り、対象を絞った質問をちょうど1つしてください。
• 変更が明らかにリファクタリング／書式設定／テストのみで、観察可能な動作の変更がない場合は、作業を終了し、機能ドキュメントの更新は不要であると報告してください。

成果物

影響を受ける機能ごとに、以下を作成してください。

• docs/features/<feature_id>.md（必要に応じてディレクトリを作成）
• docs/features.md インデックス（存在しない場合は作成し、存在する場合は既存のスタイルを維持して最小限の更新にとどめる）

機能ドキュメントのフロントマター

機能ドキュメントには、次の必須フロントマターフィールドのみを含めてください。

• feature_id：ファイル名（.md を除く）と一致すること
• title：人が読める Title Case の名称
• updated：YYYY-MM-DD（今日の日付を使用）

既存のドキュメントに追加のフロントマターキーがある場合は、そのまま保持してください。新しいキー（たとえば owners）を追加してはいけません。

既存ドキュメントの feature_id がファイル名と一致しない場合は、ファイル名と一致するように feature_id を更新してください（ファイル名は変更しないでください）。

ドキュメントの構成（順序固定。該当しないセクションは省略）

各機能ドキュメントは、次のテンプレートを使って docs/features/<feature_id>.md に配置します。

---
feature_id: <kebab-case-id>
title: <Human Title>
updated: <YYYY-MM-DD>
---

# <Human Title>

## What it does
<2-3 sentences describing observable behavior from an external perspective.>

## Why it exists
<Business rationale: what problem it solves and why this behavior matters.>

## Entry point(s)
<Choose the relevant entry point representation(s). Omit only if the feature has no clear entry point.>

## Business rules and constraints
- <Rule 1 in plain language>
- <Rule 2>

## Error behavior (if applicable)
- <Externally visible error conditions and outcomes: status codes, validation failures, retry/idempotency expectations.>

## Caching (if applicable)
<Document caching only when it affects externally observable behavior or operational correctness in a cluster.>

## Configuration (if applicable)
| Variable | Purpose |
|----------|---------|
| <property.key or ENV_VAR> | <What it controls in this feature> |

## Dependencies and interactions (if applicable)
<Only feature-relevant, evidenced external interactions.>

エントリーポイントの形式テンプレート（REST、Kafka コンシューマー、スケジュールジョブ、内部イベント）については、references/entry-point-templates.md を参照してください。

インデックスファイル（docs/features.md）

docs/features.md が存在しない場合は、最小限のインデックスを作成してください。

# Module Features

This module provides the following features:

| Feature | Description |
|---------|-------------|
| [<Human Title>](features/<feature_id>.md) | <One-sentence behavioral description> |

存在するものの、異なる形式が使われている場合は、既存のスタイルを維持して最小限の更新を行ってください（書き直しや形式の統一はしないでください）。

詳細なワークフロー手順（事前確認、機能の特定、エントリーポイント、動作の抽出、設定、依存関係）については、references/workflow.md を参照してください。

簡単な確認事項

• 機能名はキャッシュ／イベント／実装ではなく、動作を示している。
• 記載されているすべてのエンドポイント／トピック／設定／連携が、証拠によって裏付けられている。
• セクションは固定の順序で並び、該当しないものは省略されている。