| name | feature-documentation |
| description | 機能・サービス・要件・前提条件などプロジェクトの知識をドキュメント化する。新規機能/サービスを作るとき、または既存機能を変更するときに必ず実行。新規ならドキュメントを作成、既存があれば更新する。 |
Feature Documentation Skill - 機能・サービス・知識ドキュメント化
目的
プロジェクトに関する 「あとから読めば分かる」資産 を蓄積するためのスキル。
会話履歴・PR description・CHANGELOG はあくまで「いつ・誰が・何をしたか」の記録に過ぎず、「この機能は何で、なぜそうなっているのか」を後から再構築するのは難しい。
本スキルは、機能や前提条件などを 永続ドキュメント として残し、「次に触る人（人間でも AI でも）が単独で理解できる状態」を維持することを目的とする。
適用範囲（何を書くか）
このスキルは「機能詳細だけ」のものではなく、以下のすべてを対象とする：
| 種別 | 例 |
|---|
| 機能 / サービス | 認証機能、決済サービス、通知バッチ など |
| 業務要件 / ユースケース | ユーザー登録フロー、注文確定フロー など |
| プロジェクト前提条件 | 想定ユーザー、対応ブラウザ、SLA、想定負荷 など |
| 全体像 / README 的な内容 | システム構成、リポジトリ構成、用語集、ドメイン語彙 など |
| 横断的なルール / 設計判断 | 例外設計方針、リトライ戦略、命名規約のうち本プロジェクト固有のもの |
開発プロセスや汎用的なコーディング規約は shared/documents/ 配下のドキュメントを使う。本スキルが扱うのは「このプロジェクト固有の事実・判断」。
発火タイミング（必須）
以下のいずれかに該当する場合、本スキルを必ず実行する。
自動発火（AI 側で判断して実行）
- 新しい機能・サービスを実装したとき
- 例: 新しい API エンドポイント群、新しいバッチ、新しい画面 / 機能ブロック
- 既存の機能・サービスの仕様 / 振る舞いを変更したとき
- 例: API レスポンス形式の変更、認可ルールの変更、外部サービス連携の変更
- プロジェクトの前提条件 / 構成が変わったとき
- 例: 採用技術の変更、依存サービスの追加、対応ブラウザの更新
executing-plans / subagent-driven-development の各タスク完了時
- タスクが「機能の追加・変更」を含むなら、本スキルを呼び出してから次のタスクに進む
quality-check 実行時の前提条件
quality-check は本スキルが完了している（または対象なしと判断されている）ことを前提とする
手動発火
- ユーザーが
/feature-documentation を明示的に呼び出した場合
- ユーザーが「このプロジェクトの〜をドキュメントにまとめて」と依頼した場合
実行フロー
Step 1: ドキュメント対象の特定
↓
Step 2: 保存場所の決定（既存ドキュメントの探索）
↓
Step 3: 新規作成 or 更新の判断
↓
Step 4: ドキュメントの作成 / 更新
↓
Step 5: 関連ドキュメントとの整合性チェック
↓
Step 6: ユーザー確認 + コミット提案
Step 1: ドキュメント対象の特定
直近の変更（または会話の文脈）から、ドキュメント化すべき対象を 1 件以上特定する。
判断基準：
git diff origin/main...HEAD --name-only で得られるファイルのうち、以下に該当するものは対象候補
- 新規追加された機能ファイル群（同一ディレクトリ配下にまとまっている場合は 1 機能として扱う）
- 公開 API / 公開インターフェースの追加・変更
- 設定ファイル / インフラ定義の意味のある変更
- 単純なリファクタリング・バグ修正・依存パッケージのバージョンアップは 対象外 としてよい（ただし振る舞いが変わる場合は対象）
判断に迷う場合は対象としてユーザーに確認する。 過不足は後で調整可能だが、書かれていないことは検出できない。
複数の対象がある場合は、対象ごとに Step 2 以降を繰り返す。
Step 2: 保存場所の決定
2-1. 既存ドキュメントの探索
以下を順に検索し、対象に関連する既存ドキュメントがあるか確認する：
ls -la documents/ docs/ 2>/dev/null
git ls-files '*.md' | xargs grep -l "<キーワード>" 2>/dev/null
2-2. 保存場所の決定ルール
| 状況 | アクション |
|---|
| 既存ドキュメントが見つかった | そのファイルをそのまま使用（場所はユーザーに確認しない） |
既存ドキュメントがないが、同種ドキュメント（例: documents/features/ 配下に他の機能ドキュメント）が存在する | 同じディレクトリ・同じ命名規則で新規作成 |
| 上記いずれにも該当しない（プロジェクト初回） | 保存場所候補をユーザーに提示して確認する |
2-3. ユーザーに確認する場合の標準候補
以下のいずれかを推奨します。プロジェクトの方針に合うものを選んでください：
1) documents/features/<feature-name>.md （既存の documents/ 配下に集約）
2) docs/features/<feature-name>.md （docs/ 配下に新設）
3) docs/project/features/<feature-name>.md （プロジェクト固有として明示）
4) その他（パスを指定してください）
ファイル名規則: kebab-case + .md（例: user-authentication.md）
ユーザーが選択した場所は、プロジェクト内の暗黙ルール として以後同種ドキュメントの保存場所に使う。可能であれば CLAUDE.md / .cursorrules 等の設定ファイル、またはプロジェクトの README に記録するようユーザーに提案する。
Step 3: 新規作成 or 更新の判断
| 状況 | アクション |
|---|
| 既存ファイルなし | 新規作成（Step 4 のテンプレート全体を埋める） |
| 既存ファイルあり、同一機能の追記 | 更新（該当セクションのみ書き換え。無関係セクションは触らない） |
| 既存ファイルあり、別機能を扱っている | 別ファイルとして新規作成。既存ファイル末尾に「関連: ./<新ファイル>」のリンクを追加 |
禁止事項:
- 既存ドキュメントを「全面書き換え」してはいけない。差分だけを慎重に反映する
- ユーザーが手で書いた説明文や注記を、無断で簡略化・削除しない
Step 4: ドキュメントの作成 / 更新
4-1. ドキュメントテンプレート
変更履歴セクションは含めない（git で追跡可能なため）。
ドキュメントの種別に応じて、以下のテンプレートから必要なセクションを選択する。書くことがないセクションは省略してよい（プレースホルダー「TBD」のまま残さない）。
# <機能 / サービス / トピック名>
> **種別:** 機能 / サービス / 要件 / 前提条件 / 全体像 のいずれか
> **最終更新:** YYYY-MM-DD
> **関連:** #<Issue番号>, #<PR番号>, [関連ドキュメント](../path/to/related.md)
## 概要
何のためのものか、1〜3 段落で説明する。
ドメイン用語が出てくる場合は注釈する。
## 目的 / 解決したい課題
- なぜこれを作る / 持つ必要があるのか
- 解決したい課題、達成したいユーザー価値
## スコープ
- **対象:** 何を扱うか
- **対象外:** 何を扱わないか（同等の重要度で明記。スコープ外を書かないと曖昧になる）
## 前提条件 / 制約
- 利用する側が満たすべき前提（認証済みユーザーであること、特定ロールを持つこと、など）
- システム的な制約（同期処理である、N秒以内に応答すること、など）
## アーキテクチャ / 構成
```
<必要に応じて図やレイヤ構成を記述>
```
- 主要コンポーネント
- 外部依存（DB / 外部サービス / バッチ など）
- データフロー（必要なら）
## 主要ファイル / エントリポイント
| パス | 役割 |
|------|------|
| `path/to/file.ts` | 〜 |
## API / インターフェース
公開する関数・クラス・REST/GraphQL エンドポイント・CLI などを記述。
| メソッド / パス | 概要 | 入力 | 出力 |
|---------------|------|------|------|
| `POST /api/v1/...` | 〜 | `{ ... }` | `{ ... }` |
## データモデル
主要なテーブル / エンティティ / 型定義を記述。
スキーマ詳細は別ファイルにある場合はリンクで十分。
## 振る舞い / フロー
- 正常系の流れ
- 主要な分岐 / 例外パス
- リトライ / タイムアウト / 冪等性の方針
## 設計判断 / なぜこうしたか
採用しなかった案、トレードオフ、検討の経緯など。
**「なぜ」が一番あとから失われやすいので、必ず残す。**
## 運用上の注意
- デプロイ時の注意
- 環境変数 / 設定値
- 監視 / アラートの観点
- 障害時の挙動・対応
## 既知の制限 / TODO
- 現時点で未対応のこと
- 将来やる予定のこと（Issue 番号があれば併記）
## 関連リンク
- [関連ドキュメント](../path/to/related.md)
- 仕様書 / 外部資料の URL
4-2. テンプレート選択ガイド
| ドキュメント種別 | 必須セクション |
|---|
| 機能 / サービス | 概要 / 目的 / スコープ / アーキテクチャ / API / データモデル / 振る舞い / 設計判断 |
| 業務要件 / ユースケース | 概要 / 目的 / スコープ / 前提条件 / 振る舞い |
| プロジェクト前提条件 | 概要 / スコープ / 前提条件 / 制約 / 関連リンク |
| 全体像 / README 的 | 概要 / アーキテクチャ / 主要ファイル / 関連リンク |
4-3. 書き方のルール
- 未確定事項を「TBD」と書かない。「現時点未定」と理由付きで明記するか、そもそもセクションを省略する
- コードに書いてあることを丸写ししない。「なぜ」「いつ」「どういう前提で」を書く
- 更新時は最終更新日を必ず変える。 関連 Issue/PR があれば追記する
- 冗長な装飾（絵文字など）は使わない。 プロジェクトの既存ドキュメントの文体に合わせる
Step 5: 関連ドキュメントとの整合性チェック
新規作成 / 更新後、以下が破綻していないか確認する：
- 既存ドキュメントで参照されている用語と矛盾していないか
- 同じ機能を別ドキュメントで二重定義していないか（重複していたらどちらかに集約してリンクで参照する）
- README / 目次系ドキュメントから新しいドキュメントが辿れるか（必要ならリンクを追加）
矛盾が見つかった場合：
- 軽微なら本タスク内で修正
- 大きな矛盾（既存ドキュメントの書き換えが必要等）はユーザーに確認
Step 6: ユーザー確認 + コミット提案
以下を出力してユーザーに確認する：
- 対象ドキュメントの新規作成 / 更新内容（差分）を表示
- 更新したファイル一覧
- 次のアクション提案:
- そのまま
git add してコミット（コミットメッセージは docs: プレフィックス）
- 修正が必要なら指摘内容を受けて Step 4 へ戻る
ユーザーの承認後にのみ、変更を確定する。
チェックリスト
実行完了時、以下を満たしていることを確認する：
アンチパターン
以下は本スキルが防ぎたい状態。これらを再生産しないよう注意する。
- 機能を作ったが、何をする機能なのかが PR description にしか書かれていない
- 「設計判断」が会話履歴にしか残っておらず、半年後に誰も理由を説明できない
- 同じ機能の説明が複数ドキュメントに散在し、どれが正なのか分からない
- ドキュメントが「コードを日本語に翻訳しただけ」になっており、コードを読んだ方が早い
- ドキュメントの「変更履歴」セクションが手書きで管理されており、実際のコミット履歴と乖離している
