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

2-2. 保存場所の決定ルール

状況	アクション
既存ドキュメントが見つかった	そのファイルをそのまま使用（場所はユーザーに確認しない）
既存ドキュメントがないが、同種ドキュメント（例: documents/features/ 配下に他の機能ドキュメント）が存在する	同じディレクトリ・同じ命名規則で新規作成
上記いずれにも該当しない（プロジェクト初回）	標準候補 1)（documents/features/<feature-name>.md）を使う。ユーザーには確認しない

2-3. 標準候補

プロジェクトの規則（CLAUDE.md / AGENTS.md / .cursorrules / README）に保存場所の指定があればそれに従う。無ければ 1) を使う。

  1) documents/features/<feature-name>.md     （既存の documents/ 配下に集約）
  2) docs/features/<feature-name>.md          （docs/ 配下に新設）
  3) docs/project/features/<feature-name>.md  （プロジェクト固有として明示）

ファイル名規則: kebab-case + .md（例: user-authentication.md）

使った場所は、プロジェクト内の暗黙ルール として以後同種ドキュメントの保存場所に使う。初めて場所を決めたときは、そのことを最後の報告の「判断が必要なこと」に 1 行書く（ユーザーが別の場所を望めば、次の変更で移す。この返答はフラグ作成を止めない）。

---

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 / 目次系ドキュメントから新しいドキュメントが辿れるか（必要ならリンクを追加）

矛盾が見つかった場合：

• 軽微なら本タスク内で修正
• 大きな矛盾（既存ドキュメントの書き換えが必要等）は、承認済みの設計に沿う側に合わせて直す。設計と食い違うなら「設計との差異」として記録する（documents/development/development-policy.md §1.0「承認後の進め方」）。ユーザーには途中で確認しない

---

Step 6: コミット（確認は求めない）

ドキュメントの更新は承認済みの設計の範囲の作業なので、ユーザーに確認せずに確定する（documents/development/development-policy.md §1.0「承認後の進め方」）。

1. 更新したファイルを git add してコミットする（コミットメッセージは docs: プレフィックス。実装のコミットに含めてもよい）
2. 内容の妥当性は quality-check の統合レビュー（docs の観点）で見る。チャットでは差分を示さない
3. 設計と食い違う記述にした場合だけ、最後の報告の「設計との差異」に書く

---

チェックリスト

実行完了時、以下を満たしていることを確認する：

• 直近の変更からドキュメント化すべき対象を特定した
• 既存ドキュメントを検索し、対象との関連を確認した
• 新規作成 / 更新の判断が正しい（既存を全面書き換えしていない）
• 「設計判断 / なぜこうしたか」を埋めた（最も忘れられやすい項目）
• 「TBD」「TODO」プレースホルダーが残っていない
• 既存ドキュメントとの矛盾がない
• 関連 Issue / PR / 関連ドキュメントへのリンクを記載した
• 最終更新日が当日になっている

---

アンチパターン

以下は本スキルが防ぎたい状態。これらを再生産しないよう注意する。

• 機能を作ったが、何をする機能なのかが PR description にしか書かれていない
• 「設計判断」が会話履歴にしか残っておらず、半年後に誰も理由を説明できない
• 同じ機能の説明が複数ドキュメントに散在し、どれが正なのか分からない
• ドキュメントが「コードを日本語に翻訳しただけ」になっており、コードを読んだ方が早い
• ドキュメントの「変更履歴」セクションが手書きで管理されており、実際のコミット履歴と乖離している