메뉴
機能・サービス・要件・前提条件などプロジェクトの知識をドキュメント化する。新規機能/サービスを作るとき、または既存機能を変更するときに必ず実行。新規ならドキュメントを作成、既存があれば更新する。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | feature-documentation |
| description | 機能・サービス・要件・前提条件などプロジェクトの知識をドキュメント化する。新規機能/サービスを作るとき、または既存機能を変更するときに必ず実行。新規ならドキュメントを作成、既存があれば更新する。 |
プロジェクトに関する 「あとから読めば分かる」資産 を蓄積するためのスキル。
会話履歴・PR description・CHANGELOG はあくまで「いつ・誰が・何をしたか」の記録に過ぎず、「この機能は何で、なぜそうなっているのか」を後から再構築するのは難しい。 本スキルは、機能や前提条件などを 永続ドキュメント として残し、「次に触る人（人間でも AI でも）が単独で理解できる状態」を維持することを目的とする。
このスキルは「機能詳細だけ」のものではなく、以下のすべてを対象とする：
| 種別 | 例 |
|---|---|
| 機能 / サービス | 認証機能、決済サービス、通知バッチ など |
| 業務要件 / ユースケース | ユーザー登録フロー、注文確定フロー など |
| プロジェクト前提条件 | 想定ユーザー、対応ブラウザ、SLA、想定負荷 など |
| 全体像 / README 的な内容 | システム構成、リポジトリ構成、用語集、ドメイン語彙 など |
| 横断的なルール / 設計判断 | 例外設計方針、リトライ戦略、命名規約のうち本プロジェクト固有のもの |
開発プロセスや汎用的なコーディング規約は
shared/documents/配下のドキュメントを使う。本スキルが扱うのは「このプロジェクト固有の事実・判断」。
以下のいずれかに該当する場合、本スキルを必ず実行する。
executing-plans / subagent-driven-development の各タスク完了時
quality-check 実行時の前提条件
quality-check は本スキルが完了している（または対象なしと判断されている）ことを前提とする/feature-documentation を明示的に呼び出した場合Step 1: ドキュメント対象の特定
↓
Step 2: 保存場所の決定（既存ドキュメントの探索）
↓
Step 3: 新規作成 or 更新の判断
↓
Step 4: ドキュメントの作成 / 更新
↓
Step 5: 関連ドキュメントとの整合性チェック
↓
Step 6: ユーザー確認 + コミット提案
直近の変更（または会話の文脈）から、ドキュメント化すべき対象を 1 件以上特定する。
判断基準：
git diff origin/main...HEAD --name-only で得られるファイルのうち、以下に該当するものは対象候補
判断に迷う場合は対象としてユーザーに確認する。 過不足は後で調整可能だが、書かれていないことは検出できない。
複数の対象がある場合は、対象ごとに Step 2 以降を繰り返す。
以下を順に検索し、対象に関連する既存ドキュメントがあるか確認する：
# プロジェクトでよく使われるドキュメントディレクトリを検索
ls -la documents/ docs/ 2>/dev/null
# 対象機能名・関連キーワードで全文検索
git ls-files '*.md' | xargs grep -l "<キーワード>" 2>/dev/null
| 状況 | アクション |
|---|---|
| 既存ドキュメントが見つかった | そのファイルをそのまま使用（場所はユーザーに確認しない） |
既存ドキュメントがないが、同種ドキュメント（例: documents/features/ 配下に他の機能ドキュメント）が存在する | 同じディレクトリ・同じ命名規則で新規作成 |
| 上記いずれにも該当しない（プロジェクト初回） | 保存場所候補をユーザーに提示して確認する |
以下のいずれかを推奨します。プロジェクトの方針に合うものを選んでください：
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 4 のテンプレート全体を埋める） |
| 既存ファイルあり、同一機能の追記 | 更新（該当セクションのみ書き換え。無関係セクションは触らない） |
| 既存ファイルあり、別機能を扱っている | 別ファイルとして新規作成。既存ファイル末尾に「関連: ./<新ファイル>」のリンクを追加 |
禁止事項:
変更履歴セクションは含めない（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
| ドキュメント種別 | 必須セクション |
|---|---|
| 機能 / サービス | 概要 / 目的 / スコープ / アーキテクチャ / API / データモデル / 振る舞い / 設計判断 |
| 業務要件 / ユースケース | 概要 / 目的 / スコープ / 前提条件 / 振る舞い |
| プロジェクト前提条件 | 概要 / スコープ / 前提条件 / 制約 / 関連リンク |
| 全体像 / README 的 | 概要 / アーキテクチャ / 主要ファイル / 関連リンク |
新規作成 / 更新後、以下が破綻していないか確認する：
矛盾が見つかった場合：
以下を出力してユーザーに確認する：
git add してコミット（コミットメッセージは docs: プレフィックス）ユーザーの承認後にのみ、変更を確定する。
実行完了時、以下を満たしていることを確認する：
以下は本スキルが防ぎたい状態。これらを再生産しないよう注意する。
プッシュ前に必ず実行。静的チェック・テスト・統合レビュー含む6ペルソナレビューを最低2サイクル実施し、自己改善確認後のみpush可能。
Git worktree を使った並列開発時に使用。配置・ポート割当・環境コピー・クリーンアップを標準化する。
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
作業完了前にセッション内の改善ポイントを抽出し、ユーザー承認後にルール・スキル・ドキュメントへ反映する。
開発サーバー・E2E・ブラウザ検証時に使用。既存プロセスを停止してからプロジェクト指定ポートで起動し、作業後に必ず停止する。
Use when creating new skills, editing existing skills, or verifying skills work before deployment