# Youhei Ushio Dotclaude Public Documentation Standards > ドキュメント標準 - Skill: `tomevault-io/youhei-ushio-dotclaude-public-documentation-standards` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/youhei-ushio-dotclaude-public-documentation-standards` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/youhei-ushio-dotclaude-public-documentation-standards/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/youhei-ushio-dotclaude-public-documentation-standards --- # ドキュメント標準 ## 配置先の決定 | 種類 | 配置先 | |---|---| | 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 管理外）から読む。 処理後の選択肢: 1. 不要なら削除 2. 永続化が必要なら `docs/` の適切なサブディレクトリへ kebab-case 命名で移動 3. 顧客フィードバック等の参照価値があるなら `docs/features/{機能名}/{ISO日付}-{内容}.md` で保存 `docs/temp/` は使用しない（廃止済み）。 --- > Source: [youhei-ushio/dotclaude-public](https://github.com/youhei-ushio/dotclaude-public) — distributed by [TomeVault](https://tomevault.io).