Markdownで仕様書（Spec）や設計ドキュメントを管理するとき、意外と悩みやすいのがファイル名の付け方です。番号を付けるべきか、snake_caseやkebab-caseを使うべきか、将来的な追加や検索性を考えるとどの形式が良いのか迷うケースは少なくありません。この記事では、チーム開発や長期的なドキュメント管理で扱いやすいMarkdownファイルの命名規則について、それぞれの特徴とおすすめの使い分けを解説します。
Markdownのファイル命名規則で重要なポイント
仕様書や設計ドキュメントのファイル名は、単に見た目を揃えるだけではなく、後から探しやすいこと、ツールで扱いやすいこと、チームメンバーが迷わないことが重要です。
特にSpec系ドキュメントでは、プロジェクトが成長するとファイル数が増えていきます。そのため、最初は問題なくても数十個、数百個になった時に管理しやすいルールを選ぶ必要があります。
一般的には「人間が読めること」「GitやCLI環境で扱いやすいこと」「自動処理しやすいこと」の3点を基準にすると失敗しにくくなります。
最も採用されやすいのは番号付きkebab-case
Spec系ドキュメントでは、番号付きのkebab-case（ハイフン区切り）が非常によく使われる形式です。
例えば以下のような形式です。
01-product-and-market.md
02-architecture.md
03-business-model.md
この形式のメリットは、ファイル一覧を表示した時に自然な順番で並ぶことです。また、スペースを含まないため、LinuxやmacOSのターミナル操作、Git管理、自動生成ツールとの相性も良好です。
特にGitHubなどで管理するMarkdownドキュメントでは、kebab-caseは一般的な命名方法のひとつであり、他の開発者にも理解されやすい形式です。
番号を付けるメリットと注意点
仕様書では番号プレフィックスを付けることで、ドキュメント同士の関係性や読む順番を表現できます。
例えば、プロジェクト初期の考え方から詳細設計へ進む流れを以下のように表現できます。
01-overview.md
02-requirements.md
03-architecture.md
04-api-design.md
初めてプロジェクトを見る人でも、どの資料から読むべきか分かりやすくなります。
ただし、単純な連番は途中に資料を追加すると番号変更が発生する場合があります。そのため、大規模なプロジェクトでは10刻みの番号や階層番号を採用するケースもあります。
10刻み番号や階層番号を使うケース
ドキュメントの追加や分類変更が多い場合は、10刻みの番号を使う方法があります。
例として以下のような形式です。
10-product-and-market.md
20-architecture.md
30-business-model.md
後から15番や25番のドキュメントを追加できるため、既存ファイル名を変更する必要がありません。
また、設計資料が複雑になる場合は階層番号も有効です。
1-overview.md
2-architecture.md
2.1-data-model.md
2.2-api-design.md
ただし、階層番号は細かく管理しすぎると変更コストが増えるため、必要な規模のプロジェクトだけで利用するのがおすすめです。
snake_caseとkebab-caseはどちらを選ぶべきか
snake_caseとkebab-caseにはそれぞれ特徴があります。
| 形式 | 例 | 特徴 |
|---|---|---|
| snake_case | product_and_market.md | Pythonなど一部の開発文化で馴染みがある |
| kebab-case | product-and-market.md | WebやMarkdown管理で広く使われる |
Markdownドキュメントではkebab-caseが選ばれることが多い傾向があります。理由はURLやWebサービスのスラッグと相性が良く、読みやすいためです。
一方で、チーム内で既にsnake_caseの文化がある場合は無理に変更する必要はありません。重要なのはプロジェクト全体で統一することです。
番号なしファイル名が向いているケース
すべてのドキュメントに明確な順序がない場合は、番号なしの命名でも問題ありません。
例えば以下のような形式です。
product-and-market.md
architecture.md
business-model.md
機能ごとの仕様書やAPI仕様、個別設計書などでは、このような形式のほうが管理しやすい場合があります。
一方で、読み手に順番を示したいドキュメント群では番号付きのほうが親切です。
避けたほうがよいファイル命名パターン
スペースを含むファイル名や、大文字小文字が混在する形式は環境によって扱いにくくなる場合があります。
例えば以下のような形式です。
01 Product and Market.md
ProductAndMarket.md
Windowsでは問題なく見えても、Linux環境や一部のツールではスペースや大文字小文字の違いがトラブル原因になることがあります。
また、単語をすべて連結したproductandmarket.mdのような形式は、人間が内容を推測しにくいため、ドキュメント管理ではあまりおすすめできません。
Spec系Markdownでおすすめの命名ルール
仕様書や設計ドキュメントを長期間管理する場合は、以下のようなルールが扱いやすいです。
基本ルール
・小文字のみ使用する
・単語区切りはkebab-caseにする
・必要に応じて番号を付ける
・拡張子は.mdで統一する
具体例として、プロダクト仕様の場合は以下のようになります。
01-product-requirements.md
02-system-architecture.md
03-data-model.md
04-api-design.md
この形式なら、Git管理、検索、レビュー、ツール連携のすべてで扱いやすくなります。
まとめ：迷ったら番号付きkebab-caseが無難
MarkdownのSpec系ドキュメントでは、絶対的な正解はありません。プロジェクトの規模やチーム文化によって最適な形式は変わります。
ただし、新規プロジェクトで迷った場合は「番号付き + kebab-case」が最もバランスの良い選択です。
01-product-and-market.md
02-architecture.md
03-business-model.md
この形式は読みやすく、並び順も管理でき、将来的な自動処理にも対応しやすいため、長期間運用するMarkdownドキュメント管理に向いています。
コメント