ドキュメントの規約

このドキュメントは、『unpaged』のドキュメント群をどこに置き、どう書くかの規約を定めます。

ここが規約の一次情報源です。 人が書く場合もエージェント（task-splitter / implementation-workflow）が書く場合も、ここに従ってください。他のドキュメントやプラグインの既定と食い違って見える場合は、ここでの記述を正とします。

置き場を決めるたった1つの問い

そのドキュメントは、コードの変更と同じ PR で直されるべきか。

この問いへの答えで、置き場は5つに分かれます。

置き場	中身	時制	ステータス
VCS `docs/`（このサイト）	Living Document。いま何がどう振る舞うか	現在形	持たない
VCS `docs/06-adr/`	ADR。いつ・なぜ・何を却下したか	過去形	持つ（唯一）
ソースコード	実装詳細。フォルダ構成・クラス名・シグネチャ	—	—
GitHub Issue	時点情報。予定・未決定の論点・実装メモ	—	Issue の open / closed
Notion	参考資料。外部ツールの調査・アイデアメモ	—	—

VCS `docs/` に置くもの

「常に真である」と言い切れるものだけを置きます。ここに嘘が混じった瞬間、読み手はコードか作者に確認しに行くようになり、ドキュメントは読まれなくなります。

ゲームのルール（振る舞い仕様）
用語の定義
層の契約・コーディング規約
プロダクトのゴールとスコープ境界

腐ったら直すのではなく、腐らせないのが原則です。そのために、これらは PR レビューの対象になります。

`docs/06-adr/` に置くもの

決定の記録（ADR）です。一度書いたら書き換えません。追記のみです。 テンプレートと採番規則は ADR 索引 > 書き方にあります。

ソースコードに委ねるもの

コードを読めば分かることは書きません。 二重管理になり、必ず片方が古くなります。

フォルダツリー、クラス名、メソッドのシグネチャ
個々のテストケース
.tres の実際の値（バランスが設計意図を、.tres が実際の値を持つ）

ただし、コードを読んでも分からない「守るべき規約」は VCS に残します（コーディング規約）。「core/ に Node を入れてはいけない」はコードのどこにも書かれていません。

GitHub Issue / Notion に出すもの

時間とともに必ず陳腐化し、レビューする価値がないものです。誰も保守しなくてよいことが、この2つの利点です。

プロジェクトの進行に紐づくもの（予定・論点・実装メモ）は Issue、プロジェクトの外側にある参考資料（外部ツールの調査、アイデアメモ）は Notion に置きます。GitHub Wiki は使いません。

種類	置き場
実装の順序・マイルストーン	GitHub Issue
実装のスケッチ（コード片・型・構成案）	対応するタスク Issue のコメント
まだ決まっていない設計上の論点	`open-question` ラベルの Issue
外部ツールの調査結果・アイデアメモ	Notion の unpaged ページ（エージェントは `notion` MCP からアクセスする）

ステータスを持つのは ADR だけ

設計ドキュメントにステータス（draft / agreed / implemented）を付けてはいけません。 理由は3つあります。

draft の付いた仕様書は「この文書は嘘かもしれない」という宣言であり、SSOT を自壊させる。 Living Document は常に真でなければ存在意義がありません
implemented はドキュメント側で保証できない。 実装済みかどうかを知っているのはテストとコードだけです
draft の実体は「未決定の論点がある」ことであり、粒度が文書単位ではなく論点単位。 ヘッダに書くべき情報ではありません

ADR だけがステータスを持てるのは、ADR が不変だからです。書き換えない前提だからこそ、「この決定は今も生きているか」を外側のラベルで示す必要があります。

旧語彙の置き場は ADR である

設計ドキュメントには、いま真であることだけを現在形で書きます。 次のような節を置いてはいけません。

「廃止した柱」「廃止したルール」
「旧仕様からの変更点」
「用語の変遷」「◯◯セッションでの意味変更」

設計ドキュメントは Living Document なので、過去形の記述は永久に保守し続けなければならない負債になります。ADR はその時点のスナップショットなので、過去形の記述が置かれても腐りません。

書きたいこと	置き場
いまのルール	設計ドキュメント（現在形）
前はどうだったか・なぜ変えたか	それを変えた ADR
変更の経緯そのもの	git の履歴

インラインでの言及も同じです。 「崩壊ラインが廃止されたため、綻びを上げる危険はない」ではなく「綻びを上げる危険はない（ADR-0027）」と書きます。読み手が知る必要があるのは現在の仕様であり、そこへ至った経緯はリンクの先にあれば足ります。

例外は、廃止されたものの名残が現在の仕様に残っている場合です。デザインピラーの欠番（柱1・柱4・柱5・柱6）は、番号を再利用しないというルールの帰結であって過去の記録ではないため、そのまま残します。ただし「柱2・柱3が何だったか」は書きません。

旧語彙は「変えた側」ではなく「使っている側」に置く

用語を消したり意味を変えたりしたら、その語を使っている過去の ADR 全てに「死語」節を追記します（書き方）。

変えた側の ADR にだけ書いても足りません。 ADR-0024 が「帯」を廃止したことを ADR-0024 に書いても、ADR-0002 や ADR-0017 を読んでいる人はそこへ辿り着けず、「帯」を現行の用語だと思ったまま読み進めます。 古い ADR のほうが「この文書の語彙はもう通じない」と自分で名乗る必要があります。

✗ ADR-0024 だけが「帯を廃止した」と書いている
    → ADR-0002 の読者は取り違えたまま

✓ 「帯」を使っている ADR-0002・0016・0017・0020・0022・0023・0028 が
  それぞれ冒頭で「本文の『帯』は死語」と名乗る
    → どこから読み始めても取り違えない

この追記は ADR の改稿にあたりません。 決定・背景・却下した案の本文には手を触れず、読み手への注記だけを足す操作です。

未決定の論点の書き方

決まっていないことは、それが登場する箇所にインラインで書きます。

> **[未決定 → [#24](https://github.com/k1nak0/unpaged/issues/24)]** 各作用の具体的な数値と、
> プロトタイプで実装する作用の範囲。

Issue には open-question ラベルを付けます
文書の末尾に「未確定事項」節をまとめて置かないこと。 本文のどこが不確かなのかが読み取れなくなります
Issue が閉じたら、そのマーカーを消して本文を確定形に書き換えます

数値は「未決定」ではない

バランスの個別の数値は、プレイテストのたびに変わる前提で書かれています。仮であること自体が仕様なので、未決定マーカーは付けません。確定しているのは目標比率（R1〜R7）のほうです。

書き分けルール

階層の責務

階層	扱うもの	主な読者
`01-concept`	面白さの定義・世界観・用語	全員。ここが揺れると下流が全部揺れる
`02-game`	ゲームルールの確定仕様（振る舞い仕様）	実装者・バランス調整者
`03-ux`	画面遷移・情報設計	UI実装者
`04-tech`	層の契約・データ構造・規約・テスト戦略	実装者
`05-project`	ゴールとスコープ境界	プロジェクト管理
`06-adr`	ADR	全員

振る舞い仕様と実装仕様を混ぜない

この分離が、このドキュメント群で最も重要な規約です。

02-game には「プレイヤーから何が観測できるか」だけを書く。 クラス名・アルゴリズム・ファイル構成は書かない
04-tech には「何を守るか」を書く。 ゲームルールの内容そのもの（→ 02-game）も、実装の現況（→ コード）も書かない

一次情報源を1つに保つ

同じ事実を2箇所に書かないでください。書いた瞬間に、片方が古くなります。

種類	一次情報源	他のドキュメントでの扱い
用語の定義	用語集	定義を書き写さず、リンクする
具体的な数値	バランス	「値」ではなく「レンジと設計意図」を書く
設計判断の理由	ADR	結論だけ書き、背景はリンクする
ドキュメントの規約	このドキュメント	—

数値をバランスに集約しているのは、バランス調整のたびに仕様書を書き換えなくて済むようにするためです。仕様ドキュメントに直接数値を書くと、この性質が壊れます。

ファイル規約

置き場所

記事の実体はリポジトリルートの docs/ にあります（サイトの実装は site/）。新しいドキュメントは、上の「階層の責務」に従ってカテゴリディレクトリに置いてください。どの階層にも当てはまらないと感じたら、それは1本のドキュメントに2つの責務が入っているサインです。

ファイル名は英小文字のケバブケース（battle-system.md）にします。日本語のタイトルは frontmatter の title に書きます。

frontmatter

---
title: サイドバーとページ見出しに出る名前
description: 検索結果と OGP に出る説明
---

title — 必須
description — 必須
sidebar_position — 並び順を明示したいときだけ書く。省略時はファイル名の辞書順

内部リンク

末尾スラッシュ付きの絶対パスで書きます。見出しへのリンクはアンカーを付けます。

[バランス](/02-game/balance/)
[ADR-0001](/06-adr/adr-0001-hp-economy-directional/)

リンク切れと壊れたアンカーはビルドを失敗させます（onBrokenLinks / onBrokenAnchors が throw）。CI で落ちる前に、ローカルで確認できます。

cd site && npm run build

Issue や Notion へのリンクは絶対 URL で書きます。外部 URL の生存確認は、docs/ か site/ を触った PR で lychee が行います（.github/workflows/link-check.yml）。認証が要る Notion と、まだデプロイされていない自サイトの URL は検証対象外です（除外設定は lychee.toml）。

Markdown

.md は CommonMark として処理されます（markdown.format: 'detect'）。 の HTML コメントがそのまま使えます。

サイドバーは docs/ のディレクトリ構造から自動生成されるため、md を追加してもサイト側の設定を編集する必要はありません。

索引の更新規則

docs/index.md は、全設計ドキュメントの索引です。task-splitter が既存設計との衝突を検出するために読む機械可読索引を兼ねているため、ドキュメントを増減させたら必ず追従させてください。

操作	索引への反映
ドキュメントを追加した	表に行を追加する（Title / Summary / Link）
ドキュメントを廃止した	行を削除する。履歴は git が持っている
タイトル・要約が変わった	Title / Summary 列を更新する

Summary 列は1行で「そのドキュメントを読めば何が分かるか」を書きます。ドキュメント冒頭の description と揃えておくと、齟齬が起きません。

索引に載せるのは設計ドキュメント本体だけです。このドキュメントや docs/tool.md のようなメタ文書、そして ADR は載せません（ADR には専用の索引があります）。

プラグインの既定を上書きしている箇所

task-splitter / implementation-workflow の既定と、本プロジェクトの規約が異なる点です。本ドキュメントを正とします。

プラグインの既定	本プロジェクト
設計ドキュメントに `Status: draft` を書く	書かない（ステータスは ADR のみ）
設計ドキュメントは `docs/design/` に置く	カテゴリ別ディレクトリ（`01-concept` 〜 `05-project`）
索引は `docs/design/index.md`	`docs/index.md`
PRD は `docs/prd.md`	`docs/05-project/prd.md`

置き場を決めるたった1つの問い​

VCS docs/ に置くもの​

docs/06-adr/ に置くもの​

ソースコードに委ねるもの​

GitHub Issue / Notion に出すもの​

ステータスを持つのは ADR だけ​

旧語彙の置き場は ADR である​

旧語彙は「変えた側」ではなく「使っている側」に置く​

未決定の論点の書き方​

数値は「未決定」ではない​

書き分けルール​

階層の責務​

振る舞い仕様と実装仕様を混ぜない​

一次情報源を1つに保つ​

ファイル規約​

置き場所​

frontmatter​

内部リンク​

Markdown​

索引の更新規則​

プラグインの既定を上書きしている箇所​