feature-documentation

Feature Documentation Skill - 機能・サービス・知識ドキュメント化

目的

プロジェクトに関する 「あとから読めば分かる」資産 を蓄積するためのスキル。

会話履歴・PR description・CHANGELOG はあくまで「いつ・誰が・何をしたか」の記録に過ぎず、「この機能は何で、なぜそうなっているのか」を後から再構築するのは難しい。 本スキルは、機能や前提条件などを 永続ドキュメント として残し、「次に触る人（人間でも AI でも）が単独で理解できる状態」を維持することを目的とする。

---

適用範囲（何を書くか）

このスキルは「機能詳細だけ」のものではなく、以下のすべてを対象とする：

種別	例
機能 / サービス	認証機能、決済サービス、通知バッチ など
業務要件 / ユースケース	ユーザー登録フロー、注文確定フロー など
プロジェクト前提条件	想定ユーザー、対応ブラウザ、SLA、想定負荷 など
全体像 / README 的な内容	システム構成、リポジトリ構成、用語集、ドメイン語彙 など
横断的なルール / 設計判断	例外設計方針、リトライ戦略、命名規約のうち本プロジェクト固有のもの

開発プロセスや汎用的なコーディング規約は documents/development/ 配下のドキュメントを使う。本スキルが扱うのは「このプロジェクト固有の事実・判断」。

---

発火タイミング（必須）

以下のいずれかに該当する場合、本スキルを必ず実行する。

自動発火（AI 側で判断して実行）

1. 新しい機能・サービスを実装したとき
   • 例: 新しい API エンドポイント群、新しいバッチ、新しい画面 / 機能ブロック
2. 既存の機能・サービスの仕様 / 振る舞いを変更したとき
   • 例: API レスポンス形式の変更、認可ルールの変更、外部サービス連携の変更
3. プロジェクトの前提条件 / 構成が変わったとき
   • 例: 採用技術の変更、依存サービスの追加、対応ブラウザの更新
4. executing-plans / subagent-driven-development の各タスク完了時
   • タスクが「機能の追加・変更」を含むなら、本スキルを呼び出してから次のタスクに進む
5. 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