tomevault-io ドキュメント標準
配置先の決定
| 種類 | 配置先 |
|---|---|
| API 仕様 | docs/api/specification.md |
| 機能仕様（開発者向け） | docs/features/{機能名}/specification.md |
| 機能の 1 ページサマリー | docs/features/{機能名}/README.md |
| 操作マニュアル（顧客向け） | docs/business/manuals/{機能名}.md |
| 業務フロー（顧客向け） | docs/business/workflows/{内容}.md |
| トレーニング資料 | docs/business/training/{内容}.md |
| アーキテクチャ決定記録 (ADR) | docs/adr/{4桁連番}-{タイトル}.md |
| リリースノート | docs/release-notes/{ISO日付}.md |
| 運用・デプロイ・トラブルシュート | docs/operations/{内容}.md |
| 開発者向けガイド | docs/development/{内容}.md |
| 一時ファイル（処理待ち） | inbox/ (リポジトリルート、git 管理外) |
docs/ 直下に新規ファイルを作らない（README.md と各サブディレクトリのみ）。
audience による分岐
同じ機能でも、想定読者によって配置先と書き方が異なる:
| 観点 | 開発者向け (docs/features/) | 顧客現場担当向け (docs/business/) |
|---|---|---|
| 用語 | 技術用語 OK | 業務用語のみ。開発用語禁止 |
| 内容 | 業務ロジック、データモデル、API設計、エッジケース | 画面操作、ユースケース、よくある質問 |
| スクリーンショット | 必須ではない | 多用する |
| 読者の前提知識 | システム構造を理解 | システム構造を知らない |
両方が必要な機能では、両方のディレクトリに作成し相互参照リンクを置く。
顧客向け資料での開発用語禁止例
| 開発用語（禁止） | 業務用語（推奨） |
|---|---|
| バリデーションエラー | 入力エラー |
| マイグレーション | データ更新 |
| デプロイ | システム更新 |
| API・エンドポイント | 触れない、または「他システムへの問い合わせ」 |
| クエリ | 検索処理 |
| キャッシュ | 一時保存 |
| トランザクション | 一括処理 |
| バグ | 不具合 |
| パッチ | 修正版 |
| セッションタイムアウト | 自動ログアウト |
| リフレッシュ | 画面の再読み込み |
迷ったら「読み手が IT 部門ではない現場担当者」と仮定し、技術用語を平易な業務用語に置き換える。判断に迷う用語が出たら人間に確認する。
命名規則
ファイル名・ディレクトリ名
- kebab-case 必須（例:
api-specification.md,transfer-instruction/） - 拡張子は
.mdのみ（.markdown禁止） - 日本語ファイル名禁止
- 日付を含む場合は ISO 8601 形式を先頭:
2026-05-08-{内容}.md
ADR 専用ルール
- ファイル名:
{4桁連番}-{kebab-case-title}.md - 例:
0001-adopt-feature-flags.md,0042-introduce-event-sourcing.md - 連番は
docs/adr/内の最大値+1（既存を確認してから採番）
リリースノート専用ルール
- ファイル名:
{ISO日付}.md（例:2026-05-08.md） - バージョン番号運用をしないプロジェクト向け。SemVer 等を採用しているなら
v1.2.3.md形式に変えて運用する
禁止する命名
temp.md,tmp.md,new_*.md,*-old.md,*-backup.md（残骸化）untitled.md,memo.md（内容を表さない）snake_case.md（例:api_specification.md）- 末尾に日付のみ（
spec_20260508.md）
内容ルール
技術情報の最新性
- 「最新版」ではなく具体的なバージョン番号を記載
- 確認日時を本文冒頭に明記（例:
> 確認日: 2026-05-08） - 公式サイトでの確認を経てから記載
- 読者向けに「最新情報を別途確認すること」の注意書きを追加
重複の禁止
- 同じ内容を別ファイルに重複させない
- 該当機能の仕様書が
docs/features/{機能名}/に既にあるなら、 そこに追記するか参照する。再調査・再記述しない
README.md の役割
- 各サブディレクトリの最初に読まれるべきインデックス
- そのディレクトリの目的、主要ファイルへの導線、関連リンクを提供
- 機能ディレクトリの README.md は 1 ページサマリー的な内容にする
顧客向け資料の PDF 生成
docs/business/ 配下のドキュメントは、編集後に PDF を生成して配布する。
生成手順
/pdf skill を使用する。代表的なトリガー:
- 「.md の PDF を再生成して」
- 「docs/business/ 配下の資料を最新化して」
詳細手順は ~/.claude/skills/pdf/SKILL.md を参照。
drawio 図が含まれる場合
drawio 図が更新されているなら PDF 生成の前に
~/.claude/hooks/run-drawio-export.sh で SVG を最新化する。
制約
- PDF はローカル保存されるが git には含めない（
docs/**/*.pdfを.gitignore推奨）
配布先（任意）
Google Drive 等のドラフト管理サービスへ自動同期したい場合は、自プロジェクト
側で skill を追加し、本 skill から呼び出す形にする（pdf-gdrive-sync の
ような skill を独自に作る運用が想定される）。
一時ファイルの扱い
ユーザーから一時的に渡されたファイル（CSV、ログ、画像、参考資料等）は
inbox/ （リポジトリルート、git 管理外）から読む。
処理後の選択肢:
- 不要なら削除
- 永続化が必要なら
docs/の適切なサブディレクトリへ kebab-case 命名で移動 - 顧客フィードバック等の参照価値があるなら
docs/features/{機能名}/{ISO日付}-{内容}.mdで保存
docs/temp/ は使用しない（廃止済み）。
Source: youhei-ushio/dotclaude-public — distributed by TomeVault.