ドキュメント管理ガイド¶
更新日: 2026-07-24
このページは、ドキュメントを追加・更新する人向けの管理ガイドです。文書を探すときはドキュメントサイトのトップページを利用してください。
情報が食い違う場合の優先順位¶
内容が食い違う場合は、次の順に優先します。
- アーキテクチャ: 現在の実装と設計
- 運用: 現在の実行方法
- 設計判断: 採用済みの重要判断
- ロードマップ: 今後の優先順位
- 調査・実験: 調査、仮説、失敗分析
- 開発記録: 日付順の作業記録
- 初期計画: 保存している初期計画
「調査・実験」や「開発記録」の日付が新しくても、現在の仕様とは限りません。結論が固まった内容は「アーキテクチャ」、実行手順は「運用」へ反映します。
配置ルール¶
| 内容 | 配置先 | 例 |
|---|---|---|
| 現在の手法・モジュールAPI | architecture/ |
モデル、ISMCTS、JSONLスキーマ |
| 実行・監視・再開手順 | operations/ |
self-play、学習、MLflow |
| 戻しにくい設計判断 | decisions/ |
オプティマイザーや探索方式 |
| 比較前の仮説・調査 | research/ |
アブレーション案、敗因分析 |
| 実験結果の時系列 | journal/ |
サイクル別の結果、当日の判断 |
| 外部実行環境の調査 | exploration/ |
CABT API、Kaggleへの提出 |
変更内容と更新先¶
| 変更 | 更新する文書 |
|---|---|
| 公開API・モジュール境界 | 該当モジュールのページ、API一覧 |
| CLI・設定 | ツール・設定、関連する手順書 |
| JSONL・CSV・チェックポイント | 生成物一覧 |
| self-play・学習 | 該当モジュールのページ、サーバー学習手順 |
| 評価条件・昇格判定 | 評価、関連する開発記録 |
| 採用方針 | アーキテクチャ、必要に応じてADR |
索引の更新¶
新しいMarkdownファイルを追加したら、次の場所も更新します。
- 該当ディレクトリの
README.md mkdocs.ymlの階層ナビ- 目的別の案内が必要な場合はトップページ
Cloudflare
Pagesではdocs/配下をすべて公開対象にしています。履歴文書も除外せず、ナビゲーションの「調査・実験」「開発記録」「参考資料」へ分類します。
GitHubの原文と更新履歴¶
各ページの上部には、次のリンクを表示します。
- GitHubで見る: 表示中のページに対応する
docs/配下のMarkdownをGitHubで開く - 最終更新: そのMarkdownを最後に変更した日付と短縮コミットIDを表示し、該当コミットをGitHubで開く
最終更新日はサイトのビルド日時ではなく、git logから取得したページごとのコミット日時です。Cloudflare
Pages、GitHub
Actionsのartifact、ローカルプレビューで同じ履歴を参照します。Actionsでは正しい履歴を取得するため、actions/checkoutのfetch-depthを0にします。
ローカル確認¶
npm run format:check -- docs/**/*.md mkdocs.yml
uv run --group docs mkdocs build --strict
mise run docs:serve
本文のH2/H3はサイト上で自動的に折りたたみ可能になります。Markdownへ<details>を大量に埋め込む必要はありません。意図的に初期状態を閉じたい補足だけ、pymdownx.detailsを使用します。
文書を読みやすく保つ¶
- 冒頭で文書の目的、対象、現行か履歴かを示す。
- 長い背景説明より先に結論または概要を置く。
- 1つの見出しに複数の責務を詰め込まない。
- 説明用の見出しや表の列名は日本語にする。API、CLI、クラス名、製品名などの固有名詞は原語を保つ。
- 「主要入口」「信頼する場面」「正本」のような直訳調・管理用語は避け、「まず読む文書」「参照する目的」「現在の仕様として優先する文書」のように具体的に書く。
- コマンドは前提、実行例、出力、再開方法を分ける。
- 実験数値にはチェックポイント、データ、設定、seed、実行デバイスを添える。
- 同じ説明を複数ページへ複製せず、現在の仕様を説明する文書へリンクする。
- 古い文書を残す場合は、冒頭に保存版または過去資料であることを明記する。