full-stack-doc

製品ドキュメント標準（full-stack-doc v3.0）

一般的な製品ファミリーに適した、固定のディレクトリおよび命名規則を適用します。そのままコピーできる Markdown テンプレートは templates/ にあります。詳細なファイル対応表と規則については、references/structure.md を参照してください。

---

1. 使用する場面

• 製品ドキュメントリポジトリを作成または初期化する場合
• 製品ファミリーまたは単独製品のドキュメントツリーを作成する場合
• 既存のリポジトリを監査し、製品ドキュメント標準に合わせる場合
• 命名規則に沿うようにドキュメントを生成または改名する場合
• product-docs/ の内容をテンプレート構造に合わせる場合
• ルートレベルにある10個の計画ドキュメントを作成または拡充する場合

---

2. まず確認する項目

テンプレートをコピーまたは編集する前に、作業に必要な参照資料だけを読み込んでください。

• プレースホルダーの解釈とシークレットの取り扱い：references/placeholder-protocol.md
• 製品／バージョン／モジュール／提供物の責任範囲：references/document-boundaries.md
• 任意のアーキテクチャと製品パターン：references/applicability.md
• 再利用可能な例の識別情報と適用ルール：references/example-profiles.md
• エビデンスに基づく完了基準：references/quality-rubric.md
• 正確なファイル名と依存関係マップ：references/structure.md
• プロジェクト README の選択、エビデンス、バイリンガル対応、保持ルール：references/readme-template-guide.md
• Rust 共通テンプレートと任意のドメインプロファイル選択ガイド：templates/readme/rust-profiles/README.md
• アーキテクチャテンプレート全体、エビデンス、プロファイルの選択：references/architecture-template-guide.md

2.1 プレースホルダーの概要

プレースホルダー	意味	例
{{PRODUCT_NAME}}	製品名／ブランド名	ExampleCommerce、ExampleMemory
{{OPEN_SOURCE_NAME}}	オープンソース版の名前（デュアルトラックの場合）	ExampleCommerce-Open、ExampleMemory-Open
{{VERSION}}	バージョンディレクトリ名	V1、V2
{{MODULE_NAME}}	モジュールの短い名前	登录页、设备中心
{{DATE}}	日付のプレースホルダー	2026-03-27
{{OWNER}}	作成者／レビュー担当者名	张三
{{ORGANIZATION}}	組織名	ExampleOrg
{{DOC_ROOT}}	ドキュメントのルート	product-docs/ExampleProduct

二重波括弧のプレースホルダーは、ファイル名と内容の両方で置き換えてください。{例如：订单中心} のような一重波括弧のプロンプトは、作成時の例であり、グローバルトークンではありません。ルートには 6、 のファイルを1つだけ残します。以前の詳細な機能一覧は 10、功能菜单与版本规划 に統合されています。

2.2 適用に関する取り決め

1. テンプレートに情報を記入する前に、対象リポジトリを調査し、確認済みの事実を収集してください。
2. 適用するセクションを選び、対象外のデュアルトラック、SaaS、DDD/COLA、エージェント、CLI/IM、モバイル、エンタープライズの例を削除してください。
3. 詳細な例はラベル付きの例として残します。ただし、対象製品の事実として提示しないでください。
4. 不確かな内容には 推論、仮定、または 要確認 のラベルを付け、可能であればエビデンスを添えてください。
5. このスキルを保守する際は、元の例を維持してください。内容の深さを削除するのではなく、境界とラベルを改善してください。
6. 単独のアーキテクチャドキュメントには *-Architecture.md または *-Architecture.zh_CN.md という名前を付けてください。コンポーネント／バージョンの修飾子は -Architecture の前に配置してください。

---

3. ドキュメントアーキテクチャ

3.1 4層構造

{{PRODUCT_NAME}}/
├── 1、{{PRODUCT_NAME}}-命名与品牌说明.md          ─┐
├── 2、{{PRODUCT_NAME}}-术语表与词汇表.md          │
├── 3、{{PRODUCT_NAME}}-市场与商业分析.md          │
├── 4、{{PRODUCT_NAME}}-技术与可行性分析.md        │ Root (10) — 产品级，与版本无关
├── 5、{{PRODUCT_NAME}}-技术方案与路线.md          │
├── 6、{{PRODUCT_NAME}}-产品与版本规划.md          │
├── 7、{{PRODUCT_NAME}}-领域模型设计.md            │
├── 8、{{PRODUCT_NAME}}-Architecture.zh_CN.md      │
├── 9、{{PRODUCT_NAME}}-视觉与交互DNA规范.md       │
├── 10、{{PRODUCT_NAME}}-功能菜单与版本规划.md      ─┘
│
├── V1/                                   ─┐
│   ├── 1、{{PRODUCT_NAME}}-需求调研文档-V1.md      │
│   ├── 2、{{PRODUCT_NAME}}-需求分析文档-V1.md      │
│   ├── 3、{{PRODUCT_NAME}}-V1-Architecture.zh_CN.md│ Version (7) — 版本级实施文档
│   ├── 4、{{PRODUCT_NAME}}-功能与界面规划-V1.md    │
│   ├── 5、{{PRODUCT_NAME}}-PRD文档-V1.md           │
│   ├── 6、{{PRODUCT_NAME}}-功能菜单与版本规划-V1.md│
│   ├── 7、{{PRODUCT_NAME}}-UI设计说明-V1.md        │
│   │                                     ─┘
│   ├── 1、{模块A}/                       ─┐
│   │   ├── {{PRODUCT_NAME}}-{模块A}-PRD-V1.md      │ Module (3) — 可选，按模块
│   │   ├── {{PRODUCT_NAME}}-{模块A}-Stitch设计提示词.md │
│   │   └── {{PRODUCT_NAME}}-{模块A}-UI设计说明-V1.md    ─┘
│   └── ...
│
├── 其他/                                 ─┐
│   ├── 1、技术细分模板.md                │
│   ├── 2、功能提测模板.md                │ Delivery (5) — 可选，研发交付
│   ├── 3、测试结果模板.md                │
│   ├── 4、上线通知模板.md                │
│   └── 5、项目运维模板.md                ─┘
│
├── 技术调研/                             ── 技术调研、协议分析（版本无关）
└── assets/                               ── 图片、附件等

3.2 スコープの概要

スコープ	数	テンプレート	命名パターン
ルート	10	templates/root/	{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}.md
バージョン（{{VERSION}}/）	7	templates/version/	{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}-{{VERSION}}.md
モジュール（任意）	モジュールごとに3	templates/module/	{{PRODUCT_NAME}}-{{MODULE_NAME}}-{类型}-{{VERSION}}.md
デリバリー（任意）	5	templates/delivery/	コンテキストに依存

3.3 ルート文書10件 — 作成順序

文書間には厳密な上流・下流の依存関係があるため、記載は次の順序で段階的に進めてください。

flowchart LR
    D1["1、命名与品牌"] --> D2["2、术语表"]
    D2 --> D3["3、市场分析"]
    D3 --> D4["4、可行性分析"]
    D4 --> D5["5、技术方案"]
    D5 --> D6["6、版本规划"]
    D6 --> D7["7、领域模型"]
    D7 --> D8["8、系统架构"]
    D8 --> D9["9、视觉DNA"]
    D6 --> D10["10、功能菜单"]
    D9 --> D10

番号	文書	主な入力	主な出力	対応する Mermaid の種類
1	命名・ブランド説明	製品ビジョン	ブランドの指針、境界	graph LR（ブランドの関係）
2	用語集・語彙集	Doc 1 のブランドポジショニング	統一された用語	なし（表のみ）
3	市場・ビジネス分析	Doc 1 のポジショニング＋外部データ	TAM/SAM/SOM、競合、価格設定	quadrantChart / funnel
4	技術・実現可能性分析	Doc 3 の機会＋Doc 5 の初期選定	実現可能性の結論、リスク	flowchart / sequenceDiagram
5	技術ソリューション・ロードマップ	Doc 4 の結論	技術スタック、ADR、マイルストーン	flowchart / gantt
6	製品・バージョン計画	Doc 3 のビジネス分析＋Doc 5 のロードマップ	バージョンマトリクス、価格設定、リリース戦略	graph / timeline
7	ドメインモデル設計	Doc 2 の用語＋Doc 6 の機能範囲	境界づけられたコンテキスト、集約、イベント	classDiagram / graph TB
8	システムアーキテクチャ設計	Doc 5 の技術スタック＋Doc 7 のドメイン	レイヤー、データフロー、デプロイ	flowchart / sequenceDiagram
9	ビジュアル・インタラクション DNA 仕様	Doc 1 のブランドイメージ	色、フォント、コンポーネント、アニメーション	flowchart（ページの骨格）
10	機能メニュー・バージョン計画	Doc 6＋Doc 8＋Doc 9	ナビゲーション、ルーティング、機能一覧、優先度	mindmap / pie / flowchart

---

4. スキャフォールディングのワークフロー

ステップ 1 — ルート文書

templates/root/ から10個すべてのファイルをプロジェクトのルートにコピーします。ファイル名の {{PRODUCT_NAME}} を置き換えます。

# Example: ExampleCommerce
for f in templates/root/*.md; do
  name=$(basename "$f" | sed 's/{{PRODUCT_NAME}}/ExampleCommerce/g')
  cp "$f" "product-docs/ExampleCommerce/$name"
done

ステップ 2 — バージョン文書

{{VERSION}}/（例：V1/）を作成します。templates/version/ から7個のファイルをコピーします。ファイル名と内容の両方で {{PRODUCT_NAME}} と {{VERSION}} を置き換えます。

ステップ 3 — モジュール文書（任意）

機能モジュールごとに、{{VERSION}}/{{MODULE_INDEX}}、{{MODULE_NAME}}/ を作成します。templates/module/ から3個のファイルをコピーします。{{PRODUCT_NAME}}、{{MODULE_NAME}}、{{VERSION}} を置き換えます。

例（ExampleCommerce V1 商品収集）：

V1/1、商品采集/
├── ExampleCommerce-商品采集-PRD-V1.md
├── ExampleCommerce-商品采集-Stitch设计提示词.md
└── ExampleCommerce-商品采集-UI设计说明-V1.md

ステップ 4 — デリバリー文書（任意）

templates/delivery/ を 其他/ または専用のデリバリーフォルダーにコピーします。{{PRODUCT_NAME}} と日付を置き換えます。

ステップ 5 — 特別なディレクトリ

技術調査用に 技术调研/ を、標準外の文書用に 其他/ を作成します。demo/、assets/、.stitch/ などのディレクトリは変更しないでください。

ステップ 6 — 検証

検証チェックリスト（セクション 7）を実行します。

---

5. 品質基準

5.1 エビデンス重視の品質ゲート

行数、表の数、図の数は診断指標であり、合格基準ではありません。次の判断やデリバリーのステップに、追跡可能なエビデンスをもとに進められる文書であれば、完成とみなします。

項目	必須の結果
スコープ	対象読者、責任範囲、対象・対象外の範囲、上流・下流の境界が明示されている
エビデンス	外部の主張には出典、日付、確信度が記載されている。リポジトリに関する主張はファイル、API、テスト、または実行時のエビデンスを参照している
意思決定	代替案、決定事項、根拠、制約、見直し条件が記録されている
一貫性	用語、バージョン、スケジュール、メニュー名、API、状態、受け入れ基準が文書間で一致している
デリバリー	各要件に検証可能な受け入れ基準がある。該当する場合、アーキテクチャ／UI のセクションで障害、空、読み込み中、権限、ロールバックの各状態を扱っている
正確さ	確認済みの事実、推論、前提、TBD 項目を区別できる

評価には references/quality-rubric.md を使用します。関係性や比較を実質的に明確にできる場合にのみ、図や表を追加してください。

5.2 全文書共通の構成

各ルート文書には、以下の標準構成を必ず含めてください。

文書の冒頭：

# {{PRODUCT_NAME}} 文档标题

> **文档说明**：一句话说明文档用途与范围。
>
> **版本**：V1.0.0
> **最后更新**：{{DATE}}

文書の末尾：

---

**文档版本**：V1.0.0
**创建日期**：{{DATE}}
**最后更新**：{{DATE}}
**文档状态**：✅ 待评审

5.3 書式の規則

要素	規則
章番号	## N. は最上位、### N.M は下位とし、階層は 3 層を超えない
表の配置	:--- を使用して左揃えにする
実現可能性の評価	✅ 高い / ⚠️ 中程度 / 🔴 低い
優先度	P0（必須）/ P1（重要）/ P2（望ましい）/ P3（任意）
バージョンラベル	🆓 無料 / 👤 個人 / 👥 プロフェッショナル / 🏢 エンタープライズ
状態マーカー	✅ 実装済み / 🔧 開発中 / ⏳ 計画中 / ❌ 実装しない
Mermaid	各図の前後に空行を入れ、図の種類は内容に合わせます（3.3 の対標列を参照）
コードブロック	言語を明記します（typescript/go/bash/yaml/sql）
中国語と英語の混在	中国語と英語／数字の間にスペースを入れます：OpenAI 模型

5.4 相互参照の規則

• Doc 3 の関連ドキュメントでは、Doc 1（ブランド境界）と Doc 5（技術的実現可能性）にリンクする必要があります
• Doc 5 のガントチャートの日付は、Doc 6 のバージョンマイルストーンおよび Doc 10 のリリースサイクルと一致している必要があります
• Doc 7 の集約名は、Doc 2 の用語集で定義されている必要があります
• Doc 8 のレイヤー名は、Doc 5 の技術選定に対応している必要があります
• Doc 10 の機能一覧に付けるバージョン表記は、Doc 6 のバージョンマトリックスと一致している必要があります

---

6. 注意点

• バージョンフォルダー内の連番 1–7 は、7 つの標準ドキュメント用に予約されています。標準外のドキュメントには 8+ を使うか、其他/ に配置してください。
• ルートには 6、 で始まるファイルが1 つだけあります（製品とバージョン計画）。詳細な機能一覧は 10、功能菜单与版本规划 に含まれています。
• ユーザーから明示的な依頼がない限り、特殊ディレクトリ（demo/、assets/、.stitch/、stitch_*、实施指南/）を再編成しないでください。
• 納品テンプレートは任意であり、ルートレベルの標準連番を占有しません。
• 製品がオープンソースと商用のデュアルトラック（例：ExampleCommerce-Open/ExampleCommerce）を採用する場合、各トラックには相互参照を含む独自の 10 ドキュメント一式が必要です。

---

7. 検証チェックリスト

スキルディレクトリに同梱されている構造検証ツールを実行します。

python3 scripts/validate_templates.py

単独のアーキテクチャドキュメントを生成した場合は、納品前にファイル名を検証します。

python3 scripts/validate_architecture_filenames.py \
  docs/ExamplePlatform-Architecture.md \
  docs/ExamplePlatform-Architecture.zh_CN.md

次に、ファイル数だけでは検証できない意味上の整合性を確認します。

• 対象に関する事実には根拠があり、例には例であることが明記されている
• ルート／バージョン／モジュール／納品の各責務が重複していない
• 該当しないデュアルトラック、DDD/COLA、Agent、SaaS、CLI/IM、モバイル、エンタープライズのセクションが削除または調整されている
• 市場、技術、バージョン、メニューの各ドキュメントで日程が一致している
• 用語が用語集と一致している。メニュー、ルート、API、状態の名称が PRD／UI／アーキテクチャ間で一致している
• 要件に観測可能な受け入れ基準があり、関連する失敗時／権限／空／読み込み状態が定義されている
• 確認済みのパスワード、トークン、非公開パス、非公開の製品名／リポジトリ名が追加されていない
• 単独のアーキテクチャドキュメントのファイル名が *-Architecture.md または *-Architecture.zh_CN.md に一致している

---

8. テンプレート一覧

グループ	場所	数	主な役割
製品ベースライン	templates/root/	10	ブランド、用語、市場、技術、ロードマップ、ドメイン、アーキテクチャ、デザイン DNA、製品全体の IA
バージョン納品	templates/version/	7	調査、分析、バージョンアーキテクチャ、スコープ、PRD、メニュー、UI の決定事項
モジュール詳細	templates/module/	3	モジュール固有の PRD、デザイン生成プロンプト、UI 仕様
エンジニアリング納品	templates/delivery/	5	技術的な細分化、テストの引き継ぎ／結果、リリース、運用
プロジェクトのエントリーポイント	templates/readme/	5 + 7 Rust プロファイル	Java、Rust、プラグイン、スキルエコシステム向けの直接利用テンプレート、完全なリファレンス、組み合わせ可能な Rust ドメインカバレッジ
アーキテクチャ設計	templates/architecture/	1 + 7 プロファイルドキュメント	完全なアーキテクチャ契約と、ランタイム、プラグイン、エッジ、イベント、AI、コントロールプレーンの各プロファイル

元のライフサイクルテンプレート 25 件は、詳細な再利用可能コンテンツと、例であることを明記した完全な例を意図的に保持しています。README ファミリーには、タイプ別テンプレート 4 件と完全なリファレンス 1 件が追加されています。Rust テンプレートには、組み合わせ可能なプロファイルドキュメントが 7 件追加されています。アーキテクチャファミリーには、完全なマスターテンプレート 1 件とプロファイルドキュメント 7 件が追加されています。これらを短い空のひな形に置き換えないでください。

---

9. 関連スキル

• doc-coauthoring：インタビューを通じて共同でドキュメントを作成します。次のコマンドでインストールできます：npx skills add full-stack-skills/document-skills --skill doc-coauthoring。
• api-doc-generator：ソース／OpenAPI に基づいて API ドキュメントを作成します。次のコマンドでインストールできます：npx skills add full-stack-skills/document-skills --skill api-doc-generator。

10. 完了時の報告事項

完了を報告する前に、使用したテンプレートグループ、削除した任意のパターン、前提または TBD として残っている主張、成功した検証コマンドを明記してください。単独のアーキテクチャ出力については、ファイル名の検証結果を報告してください。対象リポジトリを調査できなかった場合は、例の内容を確認済みの事実として示すのではなく、その旨を明記してください。