docfront

ドキュメントの作成

プロジェクトのドキュメントはすべて docs/ ディレクトリにあります。docfront CLI を使うと、人間も AI エージェントもターミナルを離れずにドキュメントを検索して読めます。

CLI で閲覧する

コマンドはプロジェクトのパッケージマネージャー経由で実行してください（例：npm run docfront --、pnpm docfront）。

docfront                                          # list root docs
docfront --dir topic-a --dir topic-b/sub-topic-c  # list subdirectories
docfront --recursive                              # list everything
docfront --read doc-1.md topic-a/doc-2.md         # read documents (frontmatter stripped)
docfront --check                                  # validate all files

ワークフロー

1. 対象を理解する — 何をドキュメント化する必要があるかを明確にします。不明な場合はユーザーに確認してください。
2. 配置場所を決める — 既存のドキュメントを確認します（docfront --recursive）。新しいファイルか既存ファイルか、どのサブディレクトリに置くかを決めます。不明な場合はユーザーと相談してください。
3. 執筆する — 以下の規則に従います。

執筆ガイドライン

• 対象読者： 技術的な知識はあるものの、この特定のプロジェクトには詳しくない、新たに参加した経験豊富な人を想定します。
• 簡潔かつ具体的に書きます。当たり前の情報や一般的なベストプラクティスは含めません。
• ドキュメントの一般的な長さは 40～80 行です。
• 大きなコードブロックよりも、ソースファイルへの参照を優先してください。
• タイトルから目的が明らかな場合は、summary を省略してください。

ファイルとディレクトリの命名

• 新しいファイルとディレクトリには 小文字とハイフン（ケバブケース） を使用します。
• CLI では大文字も使用できます（例：RELEASING.md）。
• 名前は シェルで安全に使用できるもの にします。スペース、引用符、特殊文字は使わないでください。CLI はファイルとディレクトリの両方についてこの条件を検証します。docfront --check を使って確認してください。
• すべてのドキュメントに .md（Markdown）を使用します。
• 短く、内容が分かる名前を付けます。
• 関連するドキュメントはサブディレクトリにまとめます。サブディレクトリは入れ子にできます。

YAML フロントマター

.md ファイルの先頭には YAML フロントマターブロックを記述できます。ファイル名や見出しだけでは内容が十分に分からない場合など、有用なときに追加してください。必須ではありません。フロントマターがない場合、CLI は本文の最初の # heading をタイトルとして使用します。フィールド：

フィールド	必須	説明
title	いいえ	一覧に表示される、人が読みやすい表示名です。省略した場合は、最初の # heading が使用されます。
summary	いいえ	簡潔な 1 文です。タイトルから目的がすでに明らかな場合は、重複を避けるため省略してください。
read_when	いいえ	短く、行動を促すヒントを記述した YAML リストです。それぞれのヒントは、「次のような場合にこのドキュメントを読んでください……」 と続く内容にします。

ドキュメント本文

フロントマターの閉じ区切り --- の後に、標準的な Markdown を記述します。本文の形式に制約はありません。必要に応じて見出し、コードブロック、表、リストを使用してください。

---
title: Your Title Here
summary: A one-sentence description of what this document covers.
read_when:
  - first situation when this document is useful
  - second situation
---

# Your Title Here

Start your content here…

参考資料

• Docfront CLI のインストール — プロジェクトに docfront CLI を追加する方法。
• ドキュメントの初期設定 — コードベースを調べて、プロジェクトのドキュメントを作成または拡張する手順。
• 既存ドキュメントの移行 — 既存の Markdown ドキュメントフォルダーを docfront の規則（命名、フロントマター）に合わせるためのガイド。
• スキルから Docfront ドキュメントへの移行 — プロジェクト内部のドキュメントをエージェントスキルから docs/ に移すためのガイド。