documentation

ドキュメントスキル

バージョン： 1.0 ソース： ドキュメント標準

妥協できないドキュメント標準です。ドキュメントはコードと一緒にリリースし、後から追加するものではありません。

問題点

AI エージェントはドキュメントを任意のものとして扱います。コードは書かれても、変更履歴、機能仕様、モジュールドキュメントは省略されたり、後付けで生成されたりします。各セッションでは、次のセッションが「コードを読めばわかる」と想定しますが、ドキュメントがなければ、セッションをまたいでコンテキストが失われます。この標準により、すべての変更とともにドキュメントをリリースし、エージェントと人間が前のセッションの続きから作業できるようにします。

活用方法

• ビルダー： 機能に着手する前に ## Builder Checklist を読んでください。ドキュメントは後回しにせず、コードと一緒に計画してください。
• リファクタリング担当者： ## Enforced Rules を使ってドキュメントの不足箇所を見つけてください。形式や構成の指針については、説明セクションを読んでください。
• どちらの場合も： 説明セクションが正式な標準です。チェックリストとルール表は、同じ内容を簡潔にまとめたものです。

---

基本原則

1. ドキュメントはコードと一緒にリリースする — すべての機能に、更新されたドキュメントを含めます
2. 信頼できる唯一の情報源 — /Documentation フォルダーが唯一の参照先です
3. エージェント間の継続性 — ドキュメントにより、エージェントがコンテキストを理解できます
4. 生きたドキュメント — ドキュメントを古くせず、常に最新の状態に保ちます

---

ドキュメントのフィードバックループ

Agent reads /Documentation → Understands context → Does work → Updates /Documentation → Next agent reads

/Documentation を更新することは、次のエージェント（未来のあなたを含む）がプロジェクトを理解する助けになります。

---

セマンティックバージョニング（SemVer）

形式

MAJOR.MINOR.PATCH

種類	バージョンを上げるタイミング	例
MAJOR	動作、入力、出力、または構造に破壊的変更がある	API 契約の変更、機能の削除、ファイル名の変更
MINOR	ユーザーから見える新しい機能またはワークフロー	新機能、新しいエンドポイント、新しいコマンド
PATCH	バグ修正、小規模な改善、新機能なし	誤字の修正、パフォーマンスの改善、書式の調整

リリース命名規則

vX.Y.Z — [Program] / [Module]: [Feature]

構成要素	種類	説明
プログラム	名詞	主要な領域（例：Kitchen、Garden）
モジュール	名詞句	機能領域（例：Planning、Tasks）
機能	動詞／名詞句	具体的なアクション（例：Create meal plan）

例：

• v0.2.0 — Kitchen / Planning: Create weekly meal plan
• v0.3.0 — Garden / Tasks: Track watering routine
• v0.4.1 — Kitchen / Planning: Fix missing quantities

スコープタグ（機械処理向け）

scope: program.module.feature

例：

• scope: kitchen.planning.generate-shopping-list
• scope: garden.tasks.track-watering-routine

互換性ルール

次のいずれかに破壊的変更がある場合は、MAJOR を上げます：

• ファイル／フォルダーのパスまたは命名規則
• 必須入力またはワークフローの順序
• 出力契約（必須セクション、テンプレート）

次の場合は、MINOR を上げます：

• 新しいワークフローの成果が追加された
• モジュールにエンドツーエンドの機能が追加された
• ドキュメントに破壊的変更を伴わない新しいセクションが追加された

次の場合は、PATCH を上げます：

• バグ修正、書式調整、誤字修正
• 契約を変更しないパフォーマンスの改善

---

フォルダー構成

/Documentation/
  project-roadmap.md       # Living plan + progress tracking
  architecture.md          # System design overview
  changelog.md             # Version history (Keep a Changelog)
  features/
    [program-name]/
      [module-name]/
        _[module-name].md  # Module explainer (underscore sorts first)
        feature-name-1.md  # Feature specification
        feature-name-2.md  # Feature specification

主なファイル

ファイル	目的
project-roadmap.md	戦略的ロードマップ（v0.1 → v1.0）、マイルストーン
architecture.md	システム設計、データフロー、主要コンポーネント
changelog.md	バージョン履歴（Keep a Changelog 形式）
_*.md（モジュール）	モジュールの概要、機能一覧、依存関係
*.md（機能）	ユーザーストーリー、受け入れ基準、技術メモ

---

ルート README

README はパンフレットではなく、橋渡し役です。その役割は、読者を「これは何？」から「実行できて、使い方もわかった」まで導くことです。README を最初から最後まで読んでもプロジェクトを動かせないなら、問題があるのは読者ではなく README です。

2 種類の読者、1 つのドキュメント

• 「とにかく動かしたい」読者 — 5 分で動作する状態にしたい人です。「タイトル」「クイックスタート」「セットアップ」を読みます。
• 「仕組みを理解したい」読者 — なぜ動くのかを知りたい人です。それでも最初にクイックスタートを読みたいと考えています。実際に動かしてみてからのほうが、理解しやすいためです。

以下のセクション順は、どちらの読者にも役立ちます。ざっと読む人は、動作する状態になった時点で読み終えられます。詳しく読む人は、構造や設定まで読み進められます。

セクションの順序

#	セクション	目的
1	タイトル＋概要	「これは自分に関係があるか？」を 10 秒で判断する
2	クイックスタート	5 分以内に最初の成功を体験する
3	できること／できないこと	適切な期待値を設定する
4	前提条件	依存関係を正直に一覧表示する
5	セットアップ	検証を含む環境全体のセットアップ
6	使い方	実際の例を使って主要なワークフローを説明する
7	プロジェクト構成	各ファイルの場所と、その理由を示す
8	設定	カスタマイズできる項目と方法を説明する
9	トラブルシューティング	よくある問題と解決方法
10	コントリビューション	貢献方法と、最初に取り組むことを説明する

この順序にする理由： セクション 1～2 は読者を引きつけるための関門です（ここで失敗すると、読者は離れてしまいます）。セクション 3～5 は土台です（ここを飛ばすと、後で読者がつまずきます）。セクション 6～8 はリファレンスです（必要に応じて参照できます）。セクション 9～10 はセーフティネットです（問題が起きたときや、誰かが貢献したいときに役立ちます）。

主な原則

1. 成功までの見通し — 各手順の最後に、読者が確認する内容を示します。npm run db:migrate だけでは不十分です。次のように追加します：表示される内容：Migrations complete. 12 tables created.
2. 前提条件を正直に示す — 正確なバージョンと確認コマンドを記載します。隠れた要件はサポートへの問い合わせにつながります。
3. 抽象的な表現より具体的な表現 — {placeholder} 形式ではなく、プロジェクトで実際に使われている名前やパスを使います。
4. 専門用語を言い換える — 読者が手を止めて検索したくなる用語は、すぐに言い換えて説明します。
5. 失敗時の対処 — よくある失敗は本文中に記載し（> **[エラー] が表示された場合：** [原因]。解決方法：[対処方法]）、それ以外は「トラブルシューティング」で扱います。
6. ざっと読める構成 — 見出し、コードブロック、表、短い段落を使います。長文の壁を作らないでください。

完全版ガイド： references/readme-guide.md — セクションごとの詳細、良い例／悪い例、アンチパターン テンプレート： assets/readme-template.md — 10 セクションすべてを含むコピーして使えるひな形

---

機能仕様

必須項目

すべての機能ファイルに、以下を必ず含めてください。

1. 1 行の説明
2. モジュールの参照先とステータス
3. ユーザーストーリー（As a / I want / So that）
4. 概要と基本的なシナリオ
5. 受け入れ基準（テスト可能なチェックボックス）
6. データモデル（該当する場合）
7. 標準チェックリストを含む技術メモ
8. 未解決の質問
9. 関連機能

assets/feature-template.md のテンプレートを使用してください。すべての機能ファイルには、1 行の説明、モジュールの参照先とステータス、ユーザーストーリー（As／Want／So）、基本的なシナリオを含む概要、テスト可能な受け入れ基準、データモデル（該当する場合）、標準チェックリストを含む技術メモ、未解決の質問、関連機能を含めてください。

---

モジュール解説

assets/module-template.md のテンプレートを使用してください。各モジュール解説には、1 行の説明、プログラムの参照先とステータス数、概要、機能一覧表（ステータスとリンクを含む）、依存関係、アーキテクチャに関するメモを含めてください。

---

変更履歴の形式

Keep a Changelog の形式に従ってください。assets/changelog-template.md のテンプレートを使用してください。

変更の種類

種類	説明
追加	新機能
変更	既存機能の変更
非推奨	まもなく削除される機能
削除	削除済みの機能
修正	バグ修正
セキュリティ	脆弱性の修正

---

ステータス形式

コンテキスト	形式	値
project-roadmap.md	絵文字	⏳ 計画中、🔄 進行中、✅ 完了、🚫 ブロック中
機能／モジュールファイル	テキスト	計画中、進行中、完了
未解決の質問	テキスト	未解決、解決済み

理由： ロードマップでは、視覚的に把握しやすいように絵文字を使います。機能ファイルでは、AI が解析しやすいようにテキストを使います。

---

ビルダー向けチェックリスト

このスキルの対象となるコードを書く前に、計画がこれらの制約に沿っていることを確認してください。ビルダーは作業を始める前にこのセクションを読み、リファクタリング担当者は「適用ルール」表と全体の説明を使います。

ドキュメントを完成とみなす前に、次を確認してください。

機能ファイル

• 1 行の説明がある
• ステータスが最新かつ正確である
• ユーザーストーリーが「As／Want／So」の形式に従っている
• 受け入れ条件がテスト可能なチェックボックスになっている
• 標準チェックリストが完了している
• 未解決の質問に対応している、または記録している

モジュールの説明

• 機能表が最新である
• ステータスの件数が正確である
• 依存関係を記載している

プロジェクトレベル

• ロードマップに現在の状態が反映されている
• リリースに合わせて変更履歴を更新している
• アーキテクチャドキュメントが最新である

---

適用ルール

現在、ドキュメント標準は決定論的なリンターによって適用されていません。ドキュメントチェッカーが追加されたら、ルールをここおよびチェッカーの RULE_SKILLS レジストリに登録してください。

ルール ID	重大度	チェック内容
—	—	自動ルールはまだありません。すべての確認は上記のビルダー向けチェックリストを使って手動で行います

---

参考資料

• references/semver-guide.md — セマンティックバージョニングの完全ガイド
• references/changelog-format.md — Keep a Changelog 形式
• references/feature-spec-guide.md — 機能仕様書の作成ガイド
• references/readme-guide.md — ルート README の作成ガイド

アセット

• assets/feature-template.md — 機能ファイルのテンプレート
• assets/module-template.md — モジュール説明のテンプレート
• assets/changelog-template.md — 変更履歴のテンプレート
• assets/readme-template.md — README のテンプレート

スクリプト

• scripts/validate_docs.py — ドキュメント構造を検証
• scripts/generate_feature.py — テンプレートから機能ファイルを生成