From 94e326d40c2ee2889c67ece331233299d97c79b5 Mon Sep 17 00:00:00 2001
From: bnbong <bbbong9@gmail.com>
Date: Sun, 10 May 2026 21:32:44 +0900
Subject: [PATCH 1/3] [DOCS] ja translation - Phase 1

---
 docs/en/reference/translation-status.md  |   4 +-
 docs/ja/index.md                         | 577 +++++++++++++++++++++
 docs/ja/reference/translation-status.md  |  82 +++
 docs/ja/user-guide/choosing-a-starter.md | 145 ++++++
 docs/ja/user-guide/creating-projects.md  | 540 ++++++++++++++++++++
 docs/ja/user-guide/installation.md       | 209 ++++++++
 docs/ja/user-guide/quick-start.md        | 366 ++++++++++++++
 docs/ja/user-guide/using-templates.md    | 608 +++++++++++++++++++++++
 docs/ko/reference/translation-status.md  |   4 +-
 9 files changed, 2531 insertions(+), 4 deletions(-)
 create mode 100644 docs/ja/index.md
 create mode 100644 docs/ja/reference/translation-status.md
 create mode 100644 docs/ja/user-guide/choosing-a-starter.md
 create mode 100644 docs/ja/user-guide/creating-projects.md
 create mode 100644 docs/ja/user-guide/installation.md
 create mode 100644 docs/ja/user-guide/quick-start.md
 create mode 100644 docs/ja/user-guide/using-templates.md

diff --git a/docs/en/reference/translation-status.md b/docs/en/reference/translation-status.md
index 2611b38..2920eff 100644
--- a/docs/en/reference/translation-status.md
+++ b/docs/en/reference/translation-status.md
@@ -35,13 +35,13 @@ next section explains).
 |---|---|---:|---|
 | 🇬🇧 English (`en`) | ✅ Source of truth | 26 / 26 | Authoritative. |
 | 🇰🇷 Korean (`ko`) | ✅ Complete | 26 / 26 | All locale pages are present. Phase 1: top-level + core user-guide; Phase 2: remaining user-guide + all tutorials; Phase 3: contributing + reference. `docs/ko/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇯🇵 Japanese (`ja`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+| 🇯🇵 Japanese (`ja`) | 🟡 Partial | 7 / 26 | Phase 1 landed: top-level + core user-guide + `reference/translation-status.md`. Remaining pages fall back to English. |
 | 🇨🇳 Chinese (`zh`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇪🇸 Spanish (`es`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇫🇷 French (`fr`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇩🇪 German (`de`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 
-*Snapshot verified 2026-05-07; ko row recounted for the current branch after Phase 3 (contributing + reference) landed. Korean now has all locale pages present, while `docs/ko/changelog.md` intentionally points to the canonical English changelog.* These counts are maintained by hand;
+*Snapshot verified 2026-05-10; ja row recounted for the current branch after Phase 1 (top-level + core user-guide + `reference/translation-status.md`) landed.* These counts are maintained by hand;
 to recount the current state from the repo root, run:
 
 ```console
diff --git a/docs/ja/index.md b/docs/ja/index.md
new file mode 100644
index 0000000..43a25ed
--- /dev/null
+++ b/docs/ja/index.md
@@ -0,0 +1,577 @@
+<p align="center">
+    <img align="top" width="70%" src="https://bnbong.github.io/projects/img/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
+</p>
+<p align="center">
+<em><b>FastAPI-fastkit</b>: Python と FastAPI を初めて使う方のための、速くて使いやすいスターターキット</em>
+</p>
+<p align="center">
+<a href="https://pypi.org/project/fastapi-fastkit" target="_blank">
+    <img src="https://img.shields.io/pypi/v/fastapi-fastkit" alt="PyPI - Version">
+</a>
+<a href="https://github.com/bnbong/FastAPI-fastkit/releases" target="_blank">
+    <img src="https://img.shields.io/github/v/release/bnbong/FastAPI-fastkit" alt="GitHub Release">
+</a>
+<a href="https://pepy.tech/project/fastapi-fastkit">
+    <img src="https://static.pepy.tech/personalized-badge/fastapi-fastkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads">
+</a>
+</p>
+
+---
+
+このプロジェクトは、Python と [FastAPI](https://github.com/fastapi/fastapi) を初めて使う方が、Python ベースの Web アプリ開発をより早く始められるように作られました。
+
+このプロジェクトは `SpringBoot initializer` と Python Django の `django-admin` CLI から着想を得ています。
+
+!!! info "翻訳ステータス"
+    このドキュメントの **原典は英語 (`en`)** です。言語切替メニューに表示される他のロケールは部分翻訳の状態であったり、ページ単位で英語にフォールバックする場合があります。各ロケールの実際の翻訳進捗は [翻訳ステータス](reference/translation-status.md) を参照してください。
+
+## 主な機能
+
+- **⚡ FastAPI プロジェクトを即座に作成**: [Python Django](https://github.com/django/django) の `django-admin` 機能から着想を得て、CLI から FastAPI のワークスペースとプロジェクトを高速生成
+- **✨ 対話型プロジェクトビルダー**: データベース、認証、キャッシュ、モニタリングなどを段階的に選択し、選択内容を反映したコードを自動生成
+- **🎨 見やすい CLI 出力**: [rich library](https://github.com/Textualize/rich) を使った読みやすい CLI 体験
+- **📋 標準準拠の FastAPI プロジェクトテンプレート**: FastAPI-fastkit のすべてのテンプレートは Python の標準と FastAPI の一般的な利用パターンに基づいて構成
+- **🔍 自動化されたテンプレート品質保証**: 週次の自動テストですべてのテンプレートが動作し最新であることを保証
+- **🚀 多彩なプロジェクトテンプレート**: async CRUD、Docker、PostgreSQL など、ユースケース別の事前構成テンプレートを用意
+- **📦 複数のパッケージマネージャーに対応**: 好みの Python パッケージマネージャー (pip、uv、pdm、poetry) を選択可能
+
+## インストール
+
+Python 環境に `FastAPI-fastkit` をインストールしましょう。
+
+<div class="termy">
+
+```console
+$ pip install FastAPI-fastkit
+---> 100%
+```
+
+</div>
+
+
+## 使い方
+
+### 新しい FastAPI プロジェクトの開発環境をすぐに作成
+
+FastAPI-fastkit を使えば、新しい FastAPI プロジェクトをすばやく開始できます。
+
+次のコマンドで、新しい FastAPI プロジェクトの開発環境をすぐに作成できます:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my-awesome-project
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: My awesome FastAPI project
+
+           Project Information
+┌──────────────┬────────────────────────────┐
+│ Project Name │ my-awesome-project         │
+│ Author       │ John Doe                   │
+│ Author Email │ john@example.com           │
+│ Description  │ My awesome FastAPI project │
+└──────────────┴────────────────────────────┘
+
+Available Stacks and Dependencies:
+           MINIMAL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+           STANDARD Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ pydantic          │
+│ Dependency 7 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+             FULL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ redis             │
+│ Dependency 7 │ celery            │
+│ Dependency 8 │ pydantic          │
+│ Dependency 9 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+Select stack (minimal, standard, full): minimal
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+FastAPI project will deploy at '~your-project-path~'
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Injected metadata into setup.py                    │
+╰──────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Injected metadata into config file                 │
+╰──────────────────────────────────────────────────────╯
+
+        Creating Project:
+       my-awesome-project
+┌───────────────────┬───────────┐
+│ Component         │ Collected │
+│ fastapi           │ ✓         │
+│ uvicorn           │ ✓         │
+│ pydantic          │ ✓         │
+│ pydantic-settings │ ✓         │
+└───────────────────┴───────────┘
+
+Creating virtual environment...
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ venv created at                                    │
+│ ~your-project-path~/my-awesome-project/.venv         │
+│ To activate the virtual environment, run:            │
+│                                                      │
+│     source                                           │
+│ ~your-project-path~/my-awesome-project/.venv/bin/act │
+│ ivate                                                │
+╰──────────────────────────────────────────────────────╯
+
+Installing dependencies...
+⠙ Setting up project environment...Collecting <packages~>
+
+---> 100%
+
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Dependencies installed successfully                │
+╰───────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ FastAPI project 'my-awesome-project' has been      │
+│ created successfully and saved to                     │
+│ ~your-project-path~!                                  │
+╰───────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ To start your project, run 'fastkit runserver' at  │
+│ newly created FastAPI project directory              │
+╰──────────────────────────────────────────────────────╯
+```
+
+</div>
+
+このコマンドは、Python の仮想環境を含む新しい FastAPI プロジェクトの開発環境を作成します。
+
+### 対話型モードでプロジェクトを作成 ✨ NEW!
+
+より複雑なプロジェクトには、**対話型モード** を使って、賢い機能選択とともに段階的に FastAPI アプリケーションを組み立てましょう:
+
+<div class="termy">
+
+```console
+$ fastkit init --interactive
+
+⚡ FastAPI-fastkit Interactive Project Setup ⚡
+
+📋 Basic Project Information
+Enter the project name: my-fullstack-project
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: Full-stack FastAPI project with PostgreSQL and JWT
+
+🧱 Architecture Preset
+Pick a project layout. Press Enter to accept the recommended default.
+  1. minimal           - Smallest viable FastAPI app
+  2. single-module     - Everything in one module (prototypes / scripts)
+  3. classic-layered   - api/routes + crud + schemas + core (à la fastapi-default)
+  4. domain-starter    - Domain-oriented src/app/domains/<concept>/ (recommended)
+
+Select architecture preset: [4]
+
+🗄️ Database Selection
+Select database (PostgreSQL, MySQL, MongoDB, Redis, SQLite, None):
+  1. PostgreSQL - PostgreSQL database with SQLAlchemy
+  2. MySQL - MySQL database with SQLAlchemy
+  3. MongoDB - MongoDB with motor async driver
+  4. Redis - Redis for caching and session storage
+  5. SQLite - SQLite database for development
+  6. None - No database
+
+Select database: 1
+
+🔐 Authentication Selection
+Select authentication (JWT, OAuth2, FastAPI-Users, Session-based, None):
+  1. JWT - JSON Web Token authentication
+  2. OAuth2 - OAuth2 with password flow
+  3. FastAPI-Users - Full featured user management
+  4. Session-based - Cookie-based sessions
+  5. None - No authentication
+
+Select authentication: 1
+
+⚙️ Background Tasks Selection
+Select background tasks (Celery, Dramatiq, None):
+  1. Celery - Distributed task queue
+  2. Dramatiq - Fast and reliable task processing
+  3. None - No background tasks
+
+Select background tasks: 1
+
+💾 Caching Selection
+Select caching (Redis, fastapi-cache2, None):
+  1. Redis - Redis caching
+  2. fastapi-cache2 - Simple caching for FastAPI
+  3. None - No caching
+
+Select caching: 1
+
+📊 Monitoring Selection
+Select monitoring (Loguru, OpenTelemetry, Prometheus, None):
+  1. Loguru - Simple and powerful logging
+  2. OpenTelemetry - Observability framework
+  3. Prometheus - Metrics and monitoring
+  4. None - No monitoring
+
+Select monitoring: 3
+
+🧪 Testing Framework Selection
+Select testing framework (Basic, Coverage, Advanced, None):
+  1. Basic - pytest + httpx for API testing
+  2. Coverage - Basic + code coverage
+  3. Advanced - Coverage + faker + factory-boy for fixtures
+  4. None - No testing framework
+
+Select testing framework: 2
+
+🛠️ Additional Utilities
+Select utilities (comma-separated numbers, e.g., 1,3,4):
+  1. CORS - Cross-Origin Resource Sharing
+  2. Rate-Limiting - Request rate limiting
+  3. Pagination - Pagination support
+  4. WebSocket - WebSocket support
+
+Select utilities: 1
+
+🚀 Deployment Configuration
+Select deployment option:
+  1. Docker - Generate Dockerfile
+  2. docker-compose - Generate docker-compose.yml (includes Docker)
+  3. None - No deployment configuration
+
+Select deployment option: 2
+
+📦 Package Manager Selection
+Select package manager (pip, uv, pdm, poetry): uv
+
+📝 Custom Packages (optional)
+Enter custom package names (comma-separated, press Enter to skip):
+
+📋 Project Configuration Summary
+┌─────────────────────┬───────────────────────────────────────────────────────────────────────────┐
+│ Setting             │ Value                                                                     │
+├─────────────────────┼───────────────────────────────────────────────────────────────────────────┤
+│ Project Name        │ my-fullstack-project                                                      │
+│ Author              │ John Doe                                                                  │
+│ Email               │ john@example.com                                                          │
+│ Description         │ Full-stack FastAPI project with PostgreSQL and JWT                        │
+│ Architecture Preset │ domain-starter — Domain-oriented: src/app/domains/<concept>/ (recommended)│
+│ Database            │ PostgreSQL                                                                │
+│ Authentication      │ JWT                                                                       │
+│ Async Tasks         │ Celery                                                                    │
+│ Caching             │ Redis                                                                     │
+│ Monitoring          │ Prometheus                                                                │
+│ Testing             │ Coverage                                                                  │
+│ Utilities           │ CORS                                                                      │
+│ Package Manager     │ uv                                                                        │
+└─────────────────────┴───────────────────────────────────────────────────────────────────────────┘
+
+Total dependencies to install: 18
+
+Proceed with project creation? [Y/n]: y
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Injected metadata into pyproject.toml              │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated dependency file with 18 packages         │
+╰───────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Preserving template-shipped main.py for preset     │
+│ 'domain-starter'.                                    │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated Docker deployment files                  │
+╰───────────────────────────────────────────────────────╯
+╭────────────────────── Warning ────────────────────────╮
+│ ⚠ Preset compatibility                               │
+│ fastapi-domain-starter's shipped src/app/main.py is  │
+│ preserved. The selections below need manual wiring   │
+│ there (CORS is already wired — set                   │
+│ BACKEND_CORS_ORIGINS in .env to activate it).        │
+│ Affected selections (packages installed, but no      │
+│ dynamic main.py edits applied for the                │
+│ 'domain-starter' preset): Prometheus                 │
+╰───────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated configuration files for selected stack   │
+╰───────────────────────────────────────────────────────╯
+
+Creating virtual environment...
+Installing dependencies...
+
+----> 100%
+
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ FastAPI project 'my-fullstack-project' from        │
+│ 'fastapi-domain-starter' has been created!            │
+╰───────────────────────────────────────────────────────╯
+```
+
+</div>
+
+対話型モードが提供する機能:
+
+- **アーキテクチャプリセット選択** (`minimal` / `single-module` / `classic-layered` / `domain-starter`) — 適切なベーステンプレートとプロジェクトレイアウトを決定
+- データベース、認証、バックグラウンドタスク、キャッシュ、モニタリングなどに対する **ガイド付き選択**
+- 選択した機能向けの **コードの自動生成** — プリセットに応じて挙動が異なる (`minimal` / `single-module` は `main.py` を再生成、`classic-layered` / `domain-starter` はテンプレート同梱の `main.py` を保存し、設定モジュールのみ追加)
+- **プリセット対応の Docker 生成** — 生成された `Dockerfile` の `CMD` がそのプリセットの実際のエントリポイント (`src.main:app` または `src.app.main:app`) を指す
+- 自動 pip 互換性を備えた **スマートな依存関係管理**
+- プリセットが自動配線できない選択について手動配線の警告を出力する **機能検証**
+- 生成された `pyproject.toml` への **識別マーカー** 注入 (description マーカー + `[tool.fastapi-fastkit]` テーブル) — 後で `is_fastkit_project()` が生成済みプロジェクトを認識可能
+
+### FastAPI プロジェクトに新しいルートを追加
+
+`FastAPI-fastkit` は FastAPI プロジェクトの拡張を簡単にします。
+
+次のコマンドで FastAPI プロジェクトに新しいルートエンドポイントを追加できます:
+
+<div class="termy">
+
+```console
+$ fastkit addroute user my-awesome-project
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-awesome-project                       │
+│ Route Name       │ user                                     │
+│ Target Directory │ ~your-project-path~                      │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'user' to project 'my-awesome-project'? [Y/n]: y
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Updated main.py to include the API router          │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Successfully added new route 'user' to project     │
+│ `my-awesome-project`                                  │
+╰───────────────────────────────────────────────────────╯
+```
+
+</div>
+
+### 構造化された FastAPI デモプロジェクトを即座に展開
+
+構造化された FastAPI デモプロジェクトから始めることもできます。
+
+デモプロジェクトはさまざまな技術スタックで構成されており、シンプルな item CRUD エンドポイントが実装されています。
+
+次のコマンドで、構造化された FastAPI デモプロジェクトを即座に展開できます:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo
+Enter the project name: my-awesome-demo
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: My awesome FastAPI demo
+Deploying FastAPI project using 'fastapi-default' template
+Template path:
+/~fastapi_fastkit-package-path~/fastapi_project_template/fastapi-default
+
+           Project Information
+┌──────────────┬─────────────────────────┐
+│ Project Name │ my-awesome-demo         │
+│ Author       │ John Doe                │
+│ Author Email │ john@example.com        │
+│ Description  │ My awesome FastAPI demo │
+└──────────────┴─────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+│ Dependency 5 │ python-dotenv     │
+└──────────────┴───────────────────┘
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+FastAPI template project will deploy at '~your-project-path~'
+
+---> 100%
+
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Dependencies installed successfully                │
+╰───────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ FastAPI project 'my-awesome-demo' from             │
+│ 'fastapi-default' has been created and saved to       │
+│ ~your-project-path~!                                  │
+╰───────────────────────────────────────────────────────╯
+```
+
+</div>
+
+利用可能な FastAPI デモの一覧を表示するには、次のコマンドを実行してください:
+
+<div class="termy">
+
+```console
+$ fastkit list-templates
+                              Available Templates
+┌────────────────────────┬───────────────────────────────────────────────────────┐
+│ fastapi-custom-response│ Async Item Management API with Custom Response System │
+│ fastapi-mcp            │ FastAPI MCP Project                                   │
+│ fastapi-domain-starter │ FastAPI Domain Starter                                │
+│ fastapi-dockerized     │ Dockerized FastAPI Item Management API                │
+│ fastapi-empty          │ Minimal FastAPI Template                              │
+│ fastapi-async-crud     │ Async Item Management API Server                      │
+│ fastapi-psql-orm       │ Dockerized FastAPI Item Management API with           │
+│                        │ PostgreSQL                                            │
+│ fastapi-default        │ Simple FastAPI Project                                │
+│ fastapi-single-module  │ FastAPI Single Module Template                        │
+└────────────────────────┴───────────────────────────────────────────────────────┘
+```
+
+</div>
+
+## ドキュメント
+
+包括的なガイドと詳細な使い方は、ドキュメントを参照してください:
+
+- 📚 **[ユーザーガイド](user-guide/quick-start.md)** - 詳細なインストール / 利用ガイド
+- 🎯 **[チュートリアル](tutorial/getting-started.md)** - 初心者向けの段階的なチュートリアル
+- 📖 **[CLI リファレンス](user-guide/cli-reference.md)** - コマンドの完全リファレンス
+- 🔍 **[テンプレート品質保証](reference/template-quality-assurance.md)** - 自動化されたテストと品質基準
+
+## 🚀 テンプレート別チュートリアル
+
+事前構築されたテンプレートを使った実践的なユースケースで、FastAPI 開発を学びましょう:
+
+### 📖 コアチュートリアル
+
+- **[基本 API サーバーの構築](tutorial/basic-api-server.md)** - `fastapi-default` テンプレートで初めての FastAPI サーバーを作成
+- **[非同期 CRUD API の構築](tutorial/async-crud-api.md)** - `fastapi-async-crud` テンプレートで高パフォーマンスな非同期 API を開発
+- **[ドメイン指向プロジェクト (Domain Starter)](tutorial/domain-starter.md)** - 推奨される現代的デフォルトである `fastapi-domain-starter` テンプレートで中規模 API を構築
+
+### 🗄️ データベースとインフラ
+
+- **[データベース統合](tutorial/database-integration.md)** - `fastapi-psql-orm` テンプレートで PostgreSQL + SQLAlchemy を活用
+- **[Docker でのデプロイ](tutorial/docker-deployment.md)** - `fastapi-dockerized` テンプレートで本番デプロイ環境を構築
+
+### ⚡ 高度な機能
+
+- **[カスタムレスポンス処理と高度な API 設計](tutorial/custom-response-handling.md)** - `fastapi-custom-response` テンプレートでエンタープライズグレードの API を構築
+- **[MCP との統合](tutorial/mcp-integration.md)** - `fastapi-mcp` テンプレートで AI モデルと連携する API サーバーを作成
+
+各チュートリアルが提供するもの:
+
+- ✅ **実用的な例** - 実際のプロジェクトでそのまま使えるコード
+- ✅ **段階的なガイド** - 初心者でも追えるよう詳しく解説
+- ✅ **ベストプラクティス** - 業界標準のパターンとセキュリティ上の考慮
+- ✅ **拡張のヒント** - プロジェクトを次のレベルへ進めるためのガイダンス
+
+## コントリビュート
+
+コミュニティからの貢献を歓迎します! FastAPI-fastkit は Python と FastAPI の入門者を支援するために設計されており、皆さんの貢献は大きな影響を生み出します。
+
+### 貢献できること
+
+- 🚀 **新しい FastAPI テンプレート** - さまざまなユースケース向けのテンプレート追加
+- 🐛 **バグ修正** - 安定性と信頼性の向上に協力
+- 📚 **ドキュメント** - ガイド、サンプル、翻訳の改善
+- 🧪 **テスト** - テストカバレッジの拡大と統合テストの追加
+- 💡 **機能** - 新しい CLI 機能の提案と実装
+
+### コントリビュートを始める
+
+FastAPI-fastkit へのコントリビュートを始めるには、次の包括的なガイドを参照してください:
+
+- **[開発環境のセットアップ](contributing/development-setup.md)** - 開発環境を整えるための完全ガイド
+- **[コードガイドライン](contributing/code-guidelines.md)** - コーディング標準とベストプラクティス
+- **[CONTRIBUTING.md](https://github.com/bnbong/FastAPI-fastkit/blob/main/CONTRIBUTING.md)** - 包括的なコントリビュートガイド
+- **[CODE_OF_CONDUCT.md](https://github.com/bnbong/FastAPI-fastkit/blob/main/CODE_OF_CONDUCT.md)** - プロジェクトの原則とコミュニティ基準
+- **[SECURITY.md](https://github.com/bnbong/FastAPI-fastkit/blob/main/SECURITY.md)** - セキュリティガイドラインと報告手順
+
+## FastAPI-fastkit が目指すもの
+
+FastAPI-fastkit は、Python と FastAPI を初めて使う方に対して、速くて使いやすいスターターキットを提供することを目標にしています。
+
+このアイデアは、FastAPI 入門者が最初から段階的に学べるように支援したいという思いから生まれました。これは [FastAPI 0.111.0 のバージョンアップ](https://github.com/fastapi/fastapi/releases/tag/0.111.0) で追加された FastAPI-cli パッケージが持つ実践的な意義とも軌を一にしています。
+
+長く FastAPI を愛用してきた者として、FastAPI 開発者 [tiangolo](https://github.com/tiangolo) が表明した [素晴らしい動機](https://github.com/fastapi/fastapi/pull/11522#issuecomment-2264639417) を少しでも実現する手助けになるプロジェクトを作りたいと考えました。
+
+FastAPI-fastkit は次の価値を提供することで、「最初の一歩」と「本番運用に耐えるアプリケーション」の間のギャップを埋めようとしています:
+
+- **即座の生産性** - セットアップの複雑さに圧倒されがちな新規ユーザーに即時の生産性を提供
+- **ベストプラクティス** - すべてのテンプレートにベストプラクティスが組み込まれており、利用者が正しい FastAPI のパターンを学べる
+- **拡張可能な土台** - 初心者からエキスパートへ成長するに従って、共に拡張していける土台
+- **コミュニティ駆動のテンプレート** - 実世界の FastAPI 利用パターンを反映したコミュニティ中心のテンプレート
+
+## 次のステップ
+
+FastAPI-fastkit を始める準備ができたら、次の流れで進めてみましょう:
+
+### 🚀 クイックスタート
+
+1. **[インストール](user-guide/installation.md)**: FastAPI-fastkit をインストール
+2. **[クイックスタート](user-guide/quick-start.md)**: 5 分で最初のプロジェクトを作成
+3. **[入門チュートリアル](tutorial/getting-started.md)**: 段階的な詳細チュートリアル
+
+### 📚 さらに学ぶ
+
+- **[プロジェクトの作成](user-guide/creating-projects.md)**: さまざまなスタックでプロジェクトを作成
+- **[ルートの追加](user-guide/adding-routes.md)**: プロジェクトに API エンドポイントを追加
+- **[テンプレートの利用](user-guide/using-templates.md)**: あらかじめ用意されたプロジェクトテンプレートを活用
+
+### 🛠️ コントリビュート
+
+FastAPI-fastkit に貢献したいですか?
+
+- **[開発環境のセットアップ](contributing/development-setup.md)**: 開発環境を整える
+- **[コードガイドライン](contributing/code-guidelines.md)**: コーディング標準とベストプラクティスに従う
+- **[コントリビュートガイドライン](https://github.com/bnbong/FastAPI-fastkit/blob/main/CONTRIBUTING.md)**: 包括的な貢献ガイド
+
+### 🔍 リファレンス
+
+- **[CLI リファレンス](user-guide/cli-reference.md)**: 全 CLI コマンドのリファレンス
+- **[テンプレート品質保証](reference/template-quality-assurance.md)**: 自動化されたテストと品質基準
+- **[FAQ](reference/faq.md)**: よくある質問
+- **[GitHub リポジトリ](https://github.com/bnbong/FastAPI-fastkit)**: ソースコードと Issue トラッキング
+
+## ライセンス
+
+このプロジェクトは MIT ライセンスのもとで提供されます — 詳細は [LICENSE](https://github.com/bnbong/FastAPI-fastkit/blob/main/LICENSE) ファイルを参照してください。
diff --git a/docs/ja/reference/translation-status.md b/docs/ja/reference/translation-status.md
new file mode 100644
index 0000000..24627cc
--- /dev/null
+++ b/docs/ja/reference/translation-status.md
@@ -0,0 +1,82 @@
+# 翻訳ステータス
+
+FastAPI-fastkit のドキュメントは複数の言語でビルドされますが、すべての翻訳が **同じ完成度になっているわけではありません**。このページでは、翻訳がどこまで進んでいるか、未翻訳ページがどのように表示されるか、そしてどう貢献できるかをまとめています。
+
+## 信頼できる情報源 (Source of truth)
+
+> **英語 (`en`) が原典です。** ドキュメントに記載されている製品・CLI・API の挙動は、すべて英語ファイルを基準に最初に記述されます。他の言語はその英語原典を翻訳したものであり、リリース時点より遅れる場合があります。
+>
+> 翻訳されたページが英語ページと食い違う場合は、翻訳が更新されるまで **英語ページを信頼してください**。
+
+英語ドキュメントは [`docs/en/`](https://github.com/bnbong/FastAPI-fastkit/tree/main/docs/en) 配下にあります。それ以外のすべてのロケール (`docs/ko/`, `docs/ja/`, ...) は翻訳対象です。
+
+リポジトリルートの `CHANGELOG.md` も、この英語原典に含まれます。ロケール固有の `changelog.md` ページがある場合でも、翻訳版のリリース履歴を別に維持するのではなく、正式な英語版 changelog への入口として扱うのが現在の方針です。
+
+## ロケールごとの完成度
+
+下記の数値は、英語原典に対して各ロケールのディレクトリツリーに実在する Markdown ページ数を示します。言語切替メニューに表示されるロケール一覧 (次のセクションで説明) ではなく、リポジトリに実際にチェックインされているファイル数を基準にしています。
+
+| ロケール | ステータス | Markdown ページ | 備考 |
+|---|---|---:|---|
+| 🇬🇧 English (`en`) | ✅ 原典 (Source of truth) | 26 / 26 | すべての基準になる原文です。 |
+| 🇰🇷 Korean (`ko`) | ✅ 完了 | 26 / 26 | ロケール側のページはすべてそろっています。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。`docs/ko/changelog.md` は英語の `CHANGELOG.md` を意図的に再利用しています。 |
+| 🇯🇵 Japanese (`ja`) | 🟡 部分 | 7 / 26 | Phase 1 を反映済み: トップレベル + コアの user-guide + `reference/translation-status.md`。残りのページは英語にフォールバックします。 |
+| 🇨🇳 Chinese (`zh`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
+| 🇪🇸 Spanish (`es`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
+| 🇫🇷 French (`fr`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
+| 🇩🇪 German (`de`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
+
+*スナップショット検証日: 2026-05-10。Phase 1 (トップレベル + コアの user-guide + `reference/translation-status.md`) を反映した現在のブランチ基準で `ja` 行を再集計しました。* この表は手動で管理されています。リポジトリルートで現在の状態を再カウントしたい場合は、次のコマンドを実行してください:
+
+```console
+$ for loc in en ko ja zh es fr de; do
+    echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
+  done
+```
+
+再カウント結果が表と異なる場合、表が古くなっていますので、直接更新するか PR / Issue で報告してください。
+
+凡例:
+
+- ✅ **原典 (Source of truth)** — ドキュメントを記述する際に基準とするロケールです。
+- 🟡 **部分** — 一部のページのみ翻訳済み。未翻訳のページは英語にフォールバックします。
+- 🔴 **スケルトン** — 言語切替メニューには表示されますが、翻訳済みのページがまだチェックインされていない状態です。翻訳済みのナビゲーションラベルの下に、英語コンテンツがそのまま表示されます。
+
+## フォールバックの仕組み
+
+ドキュメントサイトは [`mkdocs-static-i18n`](https://github.com/ultrabug/mkdocs-static-i18n) を `fallback_to_default: true` オプション付きで使用しています。これは次を意味します:
+
+- 各翻訳ロケールについて、MkDocs はそのロケールディレクトリに実在するページのみをビルドして出力します。
+- そのロケールに存在 **しない** ページは、英語版のページにフォールバックします。
+- サイト全体の言語切替メニューは、各ロケールの翻訳量にかかわらず、設定されたすべてのロケールを常に表示します。ビルドが各ページに対して到達可能な URL を生成するため (必要に応じて英語ページがフォールバック表示されます)。
+
+つまり言語切替メニューに表示される 🔴 スケルトンの項目は **翻訳済みである保証ではなく**、そのロケールがビルドターゲットとして設定されていることを示すだけです。外部の貢献者が 1 ページずつ翻訳しても、リンクグラフを壊さずに済むよう意図された動作ですが、その分、言語切替メニューが実際の翻訳進捗より完成しているように見えてしまいます。
+
+## ドキュメントサイトの読み方
+
+- **最も正確で最新の情報** が必要であれば、常に英語ドキュメントを優先してください。
+- **翻訳されたロケール** を参照する場合は、まずこのページで該当ロケールのステータスを確認してください。🟡 または 🔴 状態のロケールで未翻訳の話題に飛んだ場合、翻訳されたナビゲーションラベルの下で英語のフォールバックページを見ていることになります。
+
+## 貢献方法
+
+現在のロールアウトは **ロケールごとに 1 つのトラッキング Issue** を立て、その中で **複数のフェーズ (phase)** に分けて進める形を取っています。たとえば `ko` は Phase 1 (トップレベル + コアの user-guide)、Phase 2 (残りの user-guide + すべての tutorial)、Phase 3 (contributing + reference) の各フェーズに分けて段階的に反映しました。各フェーズは独立した PR として提出されるため、レビュアーはロケール全体の完了を待たずに、まとまりのある単位でレビューして承認できます。
+
+貢献したい場合は:
+
+1. 作業フロー、ツール、スタイル規約については [翻訳ガイド](../contributing/translation-guide.md) を参照してください。
+2. **まずロケールごとのトラッキング Issue を確認するか、新しく開いてください。** すでにオープン中のトラッキング Issue があるロケールでは、その中でフェーズ (またはフェーズ内の特定ページ) を担当宣言し、作業の重複を避けてください。トラッキング Issue がないロケールを始める場合は、どのページをどのフェーズに割り当てるかを整理した Issue を新規に開き、Phase 1 から進めてください。
+3. **フェーズごとに 1 PR** という形を推奨します。「このページだけ修正」のような小さな PR — 特に英語原典とずれた翻訳の修正 — は引き続き歓迎しますが、ロケールを新規に立ち上げる作業ではフェーズ単位でまとめることで、用語集の決定や相互リンクの表記をスライス内で一貫させやすくなります。
+4. `docs/<locale>/<same path>` 配下にファイルを追加する PR を提出してください。MkDocs が自動で取り込めるよう、英語原典とファイル名を同じに保ってください。
+5. ロケール別の changelog ページが必要な場合は、翻訳版のリリース履歴を新しく書くのではなく、正式な英語版 `CHANGELOG.md` にリンクするラッパーとして維持してください (プロジェクト方針が明示的に変わらない限り)。
+6. 新しい翻訳が反映されたら、このページの表も更新してください。ページ上部の再カウントスニペットでカウントを再集計し、最終検証日が分かるよう「スナップショット検証日」も合わせて更新してください。ロケールがまだ部分翻訳の状態であれば、どのフェーズまで進んだかを「備考」列に記入してください。
+
+翻訳ページが英語原典とずれているというバグ報告も歓迎します。トリアージしやすいように、英語ページと翻訳ページの両方をリンクしてください。
+
+## 🔴 スケルトンのロケールをそのまま維持する理由
+
+理由は 2 つあります:
+
+1. **予測しやすい URL 空間。** 各ロケールはすでに自身の `/<locale>/` サブツリーに到達可能なため、翻訳ページが反映された初日から安定したリンクとして機能します — このガイドに掲載されているリンクも同様です。
+2. **貢献者の参入障壁を下げる。** 1 ページだけ翻訳する貢献者が、新しいロケールビルドを MkDocs 設定に追加する作業まで一緒に行わずに済むよう、ファイルを置くだけで動作するようにしてあります。
+
+🔴 スケルトン状態のまま長期間貢献がないロケールがある場合、ビルドターゲットとして残し続けるかを別途検討する可能性があります。ただしその判断は別の場所で追跡されており、このステータスページが暗黙的に書き換えるものでは **ありません**。
diff --git a/docs/ja/user-guide/choosing-a-starter.md b/docs/ja/user-guide/choosing-a-starter.md
new file mode 100644
index 0000000..aeb6475
--- /dev/null
+++ b/docs/ja/user-guide/choosing-a-starter.md
@@ -0,0 +1,145 @@
+# どのスターターを選ぶべき?
+
+FastAPI-fastkit には、プロジェクトを始めるための方法がいくつか用意されています。このページは初めての方のための **選び方ガイド** です。ここで方向性を決めたうえで、実際のプロジェクト生成は [クイックスタート](quick-start.md) に進んでください。
+
+迷っている場合の答えは次のとおりです:
+
+> **`fastkit init --interactive` で始め、`domain-starter` プリセットを選んでください。** これは現代的な API プロジェクトに対する推奨デフォルトです。
+
+このページの残りの部分では、その理由と、別の選択を取るべき場面を説明します。
+
+## TL;DR — ユーザータイプ別の選び方
+
+| あなたが... | 出発点 |
+|---|---|
+| FastAPI が初めてで、ガイド付きで進めたい | `fastkit init --interactive` (preset: **`domain-starter`**) |
+| 動作する CRUD デモを読み・書き換えながら学びたい | `fastkit startdemo fastapi-default` |
+| 可能な限り小さいスキャフォールドが欲しい | `fastkit init --interactive` (preset: **`minimal`**) |
+| 簡単なプロトタイプ / 単一ファイルのスクリプトを書く | `fastkit init --interactive` (preset: **`single-module`**) |
+| 実際のデータベースが必要 (PostgreSQL + SQLAlchemy + Alembic) | `fastkit startdemo fastapi-psql-orm` |
+| 中規模 API のための本番志向のドメインレイアウトが欲しい | `fastkit init --interactive` (preset: **`domain-starter`**) |
+
+## `startdemo` と `init --interactive` の違いは?
+
+これらが 2 つの主なエントリポイントで、それぞれ異なる用途を持ちます。
+
+### `fastkit startdemo <template>`
+
+同梱テンプレート (`fastapi-default`、`fastapi-async-crud`、`fastapi-psql-orm`、`fastapi-domain-starter`、...) のいずれかをもとに、**完成済みで動作する例題プロジェクト** をディスクに展開します。テンプレートのソースコードはほぼそのままコピーされ、メタデータのプレースホルダ (`<project_name>` など) のみが埋め込まれます。
+
+- ✅ 動作するデモまでの最短ルート。
+- ✅ コードはすべて実際に動き、読みやすい — 例題による学習に最適。
+- ❌ テンプレートのスタックと構造は固定されており、生成時に「CORS だけ入れて認証は外す」といった組み合わせはできません。
+
+```console
+$ fastkit list-templates              # 利用可能なテンプレート一覧を表示
+$ fastkit startdemo fastapi-default   # その中の 1 つでプロジェクトを生成
+```
+
+### `fastkit init --interactive`
+
+**対話型ウィザード** に沿って進めます: プロジェクトメタデータ → アーキテクチャプリセット → 機能選択 (データベース、認証、テスト、デプロイ、...) → パッケージマネージャー → 確認、という流れです。ジェネレーターはプリセットごとに適切なベーステンプレートを選び、その上に選択した機能を重ねていきます。
+
+- ✅ 自分が本当に欲しいスタックを組み立てられる。
+- ✅ アーキテクチャプリセットがプロジェクトレイアウト (単一ファイル、レイヤー型、ドメイン指向、...) を決定。
+- ❌ `main.py` をそのまま使う構成の充実したプリセット (`classic-layered`、`domain-starter`) では、設定モジュールは生成されますが、それを同梱のルーターに組み込む配線はユーザー自身が行う前提です。プリセット / 機能ごとの仕様は [アーキテクチャプリセットマトリクス](../reference/preset-feature-matrix.md) を参照してください。
+
+```console
+$ fastkit init --interactive
+```
+
+## 4 種類のアーキテクチャプリセット
+
+これらは `fastkit init --interactive` のプロジェクト情報入力後に表示されます。どのプリセットを選ぶか決める際にこのセクションを使ってください。
+
+### `minimal` — 最小から始め、後で育てる
+
+最小構成の動作可能な FastAPI アプリ。空のスキャフォールド + 機能フラグから再生成された単一の `src/main.py` です。CORS、レート制限、Prometheus 計装は、選択時に自動で `main.py` に配線されます。
+
+- 👤 **対象**: プロジェクトが成長するにつれて自分で構造を組み立てたい人や、特定のレイアウトに縛られず FastAPI を試したい人。
+- 📦 **ベーステンプレート**: `fastapi-empty`。
+- 🧠 **メンタルモデル**: 「FastAPI を import した 1 ファイルだけ用意してくれれば、残りは自分でやる」。
+
+### `single-module` — スクリプト型プロトタイプ
+
+すべてのコードが 1 モジュールの中にあります。`minimal` と同じ `main.py` 再生成オーバーレイを使います。
+
+- 👤 **対象**: グルースクリプト、小さな webhook、あるいはパッケージ境界が不要な 1 日でできるプロトタイプ。
+- 📦 **ベーステンプレート**: `fastapi-single-module`。
+- 🧠 **メンタルモデル**: 「実行も通読もひと息でできる Python ファイル 1 つあれば十分」。
+
+### `classic-layered` — レイヤー型分割 (api / crud / schemas / core)
+
+「Django 風」レイアウト — コードを関心事ごとに水平分割します: ルーターはすべて `api/` に、CRUD ロジックはすべて `crud/` に、pydantic スキーマはすべて `schemas/` に、設定はすべて `core/` にまとめます。同梱の `main.py` は **保存** されており (CORS の配線済み)、生成されたデータベース / 認証設定は `src/core/` 配下に配置されます。
+
+- 👤 **対象**: Django / Rails 風レイアウトに慣れたチーム、共通の CRUD 配管を共有する小さなエンドポイントが多いプロジェクト。
+- 📦 **ベーステンプレート**: `fastapi-default`。
+- 🧠 **メンタルモデル**: 「コードを *何であるか* で分ける」。
+
+### `domain-starter` — ドメイン指向 (推奨デフォルト)
+
+コードを **ビジネス概念ごと** に垂直分割します: 各ドメインが自身のルーター、サービス、リポジトリ、スキーマを `src/app/domains/<concept>/` 配下に持ちます。`/health` エンドポイントと、新しい概念ごとにコピーしてリネームする雛形となる `items` ドメインの例が同梱されています。同梱の `main.py` (`src/app/` 配下) は保存され、生成された設定は `src/app/core/` 配下に配置されます。
+
+- 👤 **対象**: 複数の異なるビジネス概念 (users、orders、billing、...) に成長していく中規模 API。推奨される現代的なデフォルトです。
+- 📦 **ベーステンプレート**: `fastapi-domain-starter`。
+- 🧠 **メンタルモデル**: 「コードを *ビジネスにとって何をするか* で分ける」。
+
+## 比較マトリクス
+
+横並びで一目で比べられるようにしたものです。
+
+| | `minimal` | `single-module` | `classic-layered` | `domain-starter` |
+|---|---|---|---|---|
+| ベーステンプレート | `fastapi-empty` | `fastapi-single-module` | `fastapi-default` | `fastapi-domain-starter` |
+| プロジェクト入口 | `src/main.py` | `src/main.py` | `src/main.py` | `src/app/main.py` |
+| ルーター配置 | (自分で追加) | (`main.py` の中) | `src/api/routes/` | `src/app/domains/<concept>/router.py` |
+| ドメイン別フォルダ | ❌ | ❌ | ❌ | ✅ |
+| `/health` エンドポイント標準搭載 | ✅ | ✅ | ❌ | ✅ |
+| `main.py` を機能から再生成 | ✅ | ✅ | ❌ | ❌ |
+| `main.py` に CORS 事前配線 | 選択時に追加 | 選択時に追加 | あり (環境変数駆動) | あり (環境変数駆動) |
+| pyproject ファースト | 任意 | 任意 | 任意 | ✅ |
+| 適した用途 | 「自分で構造を育てたい」 | 「1 ファイルのプロトタイプ」 | 「関心事で分ける」 | 「ビジネス概念で分ける」 |
+
+機能ごとの完全な契約 (データベース / 認証の設定が配置されるパス、自動配線されない選択、警告が出る条件) は [アーキテクチャプリセットマトリクス](../reference/preset-feature-matrix.md) を参照してください。
+
+## `startdemo` テンプレートの選び方
+
+`fastkit startdemo <template>` は、ガイド付きで組み立てるよりも **完成済みで実行可能な例題** が欲しいときに最適です。ほとんどのテンプレートは前述の 4 つのプリセットのいずれかにおおむね対応していますが、追加のサンプルコード (モックストア上の CRUD エンドポイント、カスタムレスポンス処理、Docker ツールなど) を同梱しています。
+
+| テンプレート | 最も近いプリセット | 選ぶ場面 |
+|---|---|---|
+| `fastapi-default` | `classic-layered` | レイヤー型レイアウトで動く CRUD デモ。最初の出発点として手堅い。 |
+| `fastapi-empty` | `minimal` | 素のスキャフォールド。`minimal` と同じ形になります。 |
+| `fastapi-single-module` | `single-module` | 単一ファイルのデモ。 |
+| `fastapi-domain-starter` | `domain-starter` | 推奨される現代的デフォルト。items ドメインの例を同梱。 |
+| `fastapi-async-crud` | `classic-layered` | `fastapi-default` の非同期版。 |
+| `fastapi-custom-response` | `classic-layered` | カスタムレスポンスエンベロープ / フォーマットのデモ。 |
+| `fastapi-dockerized` | `classic-layered` | デフォルトレイアウトに本番用の Dockerfile を追加。 |
+| `fastapi-psql-orm` | (直接対応するプリセットなし) | PostgreSQL + SQLAlchemy + Alembic。実際のデータベースが必要なときに選択。 |
+| `fastapi-mcp` | (直接対応するプリセットなし) | Model Context Protocol 連携。 |
+
+`fastkit list-templates` で 1 行説明付きの最新リストを確認できます。
+
+## よくある質問
+
+**Q. プリセット / テンプレートは最初に決めないといけない?**
+いいえ — 後から手動で生成済みコードを再構成することはいつでもできます。プリセットはあくまで出発点であり契約ではありません。選択を考え過ぎないでください。
+
+**Q. 「現代的」な選択肢はどれ?**
+`domain-starter` です。pyproject ファーストで、`/health` エンドポイントが付属し、よく運営されている中規模 FastAPI プロジェクトが収束していくレイアウトを採用しています。
+
+**Q. 後から `classic-layered` から `domain-starter` に切り替えできる?**
+できますが手動のリファクタリングです — マイグレーションコマンドはありません。プロジェクトがドメインフォルダを必要とするほど成長すると思うなら、最初からそこを選んでください。
+
+**Q. とにかく FastAPI を学びたいだけ。**
+まず `fastkit startdemo fastapi-default` から始めてください — コードを読み、テストを実行し、いくつかのエンドポイントを書き換えてみましょう。慣れてきたら、`fastkit init --interactive` で `domain-starter` プリセットを選ぶのが自然な次の一歩です。
+
+**Q. 各プリセットが生成する正確なファイル一覧はどこで見られる?**
+[アーキテクチャプリセットマトリクス](../reference/preset-feature-matrix.md) がそのリファレンスページです。
+
+## 次のステップ
+
+- [クイックスタート](quick-start.md) — 実際に最初のプロジェクトを作成。
+- [プロジェクトの作成](creating-projects.md) — CLI フラグのより踏み込んだウォークスルー。
+- [ドメイン指向プロジェクトのチュートリアル](../tutorial/domain-starter.md) — `domain-starter` を選んだ場合の、生成ツリー、同梱の `items` 例、次のドメインの追加方法までを通したエンドツーエンドの解説。
+- [アーキテクチャプリセットマトリクス](../reference/preset-feature-matrix.md) — プリセット / 機能ごとの完全な契約。
diff --git a/docs/ja/user-guide/creating-projects.md b/docs/ja/user-guide/creating-projects.md
new file mode 100644
index 0000000..1ba98eb
--- /dev/null
+++ b/docs/ja/user-guide/creating-projects.md
@@ -0,0 +1,540 @@
+# プロジェクトの作成
+
+FastAPI-fastkit でさまざまな種類の FastAPI プロジェクトを作成する詳細ガイドです。
+
+## 基本のプロジェクト作成
+
+### 1. 対話型モードでのプロジェクト作成
+
+最も基本的な方法は、対話型でプロジェクトを作成することです:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my-awesome-api
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: Awesome FastAPI project
+
+           Project Information
+┌──────────────┬─────────────────────────┐
+│ Project Name │ my-awesome-api          │
+│ Author       │ John Doe                │
+│ Author Email │ john@example.com        │
+│ Description  │ Awesome FastAPI project │
+└──────────────┴─────────────────────────┘
+```
+
+</div>
+
+### 2. スタックの選択
+
+プロジェクトに含める依存関係スタックを選びます:
+
+#### MINIMAL スタック (デフォルト)
+
+最も基本的な FastAPI プロジェクトです:
+
+- `fastapi` - FastAPI フレームワーク
+- `uvicorn` - ASGI サーバー
+- `pydantic` - データ検証
+- `pydantic-settings` - 設定管理
+
+**適した用途:**
+
+- FastAPI の学習
+- シンプルな API
+- プロトタイプ
+- マイクロサービス
+
+#### STANDARD スタック
+
+データベース対応とテストを含みます:
+
+- MINIMAL のすべての依存関係
+- `sqlalchemy` - データベース操作のための ORM
+- `alembic` - データベースマイグレーション
+- `pytest` - テストフレームワーク
+
+**適した用途:**
+
+- 多くの Web アプリケーション
+- データベースを使う API
+- 本番運用を見据えたアプリケーション
+- チームプロジェクト
+
+#### FULL スタック
+
+完全な開発環境を提供します:
+
+- STANDARD のすべての依存関係
+- `redis` - キャッシュとセッションストレージ
+- `celery` - バックグラウンドタスク処理
+
+**適した用途:**
+
+- 大規模アプリケーション
+- 高パフォーマンスが要求される場面
+- 複雑なビジネスロジック
+- エンタープライズアプリケーション
+
+## 高度なプロジェクトオプション
+
+### プロジェクト構成のカスタマイズ
+
+作成時にプロジェクトをカスタマイズできます:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: advanced-api
+Enter the author name: Development Team
+Enter the author email: dev@company.com
+Enter the project description: Advanced FastAPI application with custom features
+
+# データベース対応のため STANDARD スタックを選択
+Select stack (minimal, standard, full): standard
+Do you want to proceed with project creation? [y/N]: y
+```
+
+</div>
+
+### プロジェクト構造の説明
+
+プロジェクトを作成すると、FastAPI-fastkit は次の構造を生成します:
+
+```
+my-awesome-api/
+├── .venv/                      # 仮想環境
+├── src/                        # ソースコード
+│   ├── __init__.py
+│   ├── main.py                # アプリケーションのエントリポイント
+│   ├── core/                  # コア設定
+│   │   ├── __init__.py
+│   │   └── config.py         # 設定 / 環境変数
+│   ├── api/                   # API レイヤー
+│   │   ├── __init__.py
+│   │   ├── api.py            # メインの API ルーター
+│   │   └── routes/           # 個別のルートモジュール
+│   │       ├── __init__.py
+│   │       └── items.py      # サンプルの items エンドポイント
+│   ├── crud/                  # データベース操作
+│   │   ├── __init__.py
+│   │   └── items.py          # items 用の CRUD 操作
+│   ├── schemas/               # Pydantic モデル
+│   │   ├── __init__.py
+│   │   └── items.py          # データ検証スキーマ
+│   └── mocks/                 # テストデータ
+│       ├── __init__.py
+│       └── mock_items.json   # 開発用のサンプルデータ
+├── tests/                     # テストスイート
+│   ├── __init__.py
+│   ├── conftest.py           # テスト設定
+│   └── test_items.py         # サンプルテスト
+├── scripts/                   # ユーティリティスクリプト
+│   ├── test.sh               # テスト実行
+│   ├── coverage.sh           # カバレッジ測定
+│   └── lint.sh               # コードリンティング
+├── requirements.txt           # Python 依存関係
+├── setup.py                  # パッケージ設定
+└── README.md                 # プロジェクトドキュメント
+```
+
+### 3. パッケージマネージャーの選択
+
+FastAPI-fastkit は複数の Python パッケージマネージャーをサポートしています。開発ワークフローに最も合うものを選んでください:
+
+#### 利用可能なパッケージマネージャー
+
+<div class="termy">
+
+```console
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+```
+
+</div>
+
+各パッケージマネージャーの利点は次のとおりです:
+
+#### UV (デフォルト・推奨)
+
+**Rust 製の高速パッケージマネージャー**
+
+- ⚡ **超高速**: pip より 10〜100 倍高速
+- 🔧 **そのまま置き換えやすい**: pip のワークフローとほぼ同じ感覚で使える
+- 📦 **モダン**: PEP 621 を完全サポート
+- 🛠️ **信頼性**: 再現性のある依存関係解決
+
+**生成されるファイル:**
+
+- `pyproject.toml` (PEP 621 形式)
+- `uv.lock` (ロックファイル)
+
+**作成後の使い方:**
+```console
+cd my-project
+uv sync              # 依存関係をインストール
+uv add requests      # 新しい依存関係を追加
+uv run pytest       # テストを実行
+```
+
+#### PDM
+
+**モダンな Python 依存関係管理**
+
+- 🚀 **モダン**: PEP 582 / PEP 621 をサポート
+- 🧠 **賢い**: 高度な依存関係解決
+- 💼 **業務向け**: ワークスペースとマルチプロジェクト対応
+- 📊 **解析**: 依存関係解析ツール
+
+**生成されるファイル:**
+
+- `pyproject.toml` (PEP 621 形式)
+- `pdm.lock` (ロックファイル)
+
+**作成後の使い方:**
+```console
+cd my-project
+pdm install          # 依存関係をインストール
+pdm add requests     # 新しい依存関係を追加
+pdm run pytest      # テストを実行
+```
+
+#### Poetry
+
+**成熟した依存関係管理とパッケージング**
+
+- ✅ **定番**: 成熟しており広く採用されている
+- 📦 **統合**: ビルド・公開までサポート
+- 🔒 **再現可能**: poetry.lock により厳密なバージョン管理
+- 🏗️ **包括的**: プロジェクトのライフサイクル全体を管理
+
+**生成されるファイル:**
+
+- `pyproject.toml` (Poetry 形式)
+- `poetry.lock` (ロックファイル)
+
+**作成後の使い方:**
+```console
+cd my-project
+poetry install       # 依存関係をインストール
+poetry add requests  # 新しい依存関係を追加
+poetry run pytest   # テストを実行
+```
+
+#### PIP
+
+**標準の Python パッケージマネージャー**
+
+- 🏠 **同梱**: Python に標準で含まれる
+- 🌍 **どこでも動く**: あらゆる環境で利用可能
+- 📚 **慣れている**: 多くの開発者がすでに知っている
+- 🔧 **シンプル**: 素直なワークフロー
+
+**生成されるファイル:**
+
+- `requirements.txt`
+
+**作成後の使い方:**
+```console
+cd my-project
+source .venv/bin/activate    # Linux/macOS
+.venv\Scripts\activate       # Windows
+pip install -r requirements.txt
+pip install requests
+pytest
+```
+
+#### パッケージマネージャーの指定
+
+好みのパッケージマネージャーは次の方法で指定できます:
+
+**対話型選択 (デフォルト):**
+```console
+$ fastkit init
+# ... パッケージマネージャー選択のプロンプトに従う
+```
+
+**コマンドラインオプション:**
+```console
+$ fastkit init --package-manager poetry
+$ fastkit init --package-manager pdm
+$ fastkit init --package-manager uv
+$ fastkit init --package-manager pip
+```
+
+### 各ディレクトリの役割
+
+#### `src/` ディレクトリ
+
+Python のパッケージングのベストプラクティスである **src レイアウト** に従って、アプリケーションのソースコードをすべて格納します。
+
+#### `core/` モジュール
+
+- **config.py**: アプリケーションの設定、環境変数、構成
+- すべての設定管理を一元化
+- 環境別設定のための `.env` ファイルをサポート
+
+#### `api/` モジュール
+
+- **api.py**: すべてのサブルーターをまとめるメインの API ルーター
+- **routes/**: 各リソースに対応する個別のルートモジュール
+- API エンドポイントごとに関心事を明確に分離
+
+#### `crud/` モジュール
+
+- データベース操作とビジネスロジック
+- **C**reate、**R**ead、**U**pdate、**D**elete の操作
+- API ルートとデータストレージの間の抽象化レイヤー
+
+#### `schemas/` モジュール
+
+- データ検証のための Pydantic モデル
+- リクエスト / レスポンススキーマ
+- 型定義とデータモデル
+
+#### `tests/` ディレクトリ
+
+- アプリケーションの完全なテストスイート
+- ユニットテストと統合テストを含む
+- pytest であらかじめ構成済み
+
+## スタック比較
+
+| 機能 | MINIMAL | STANDARD | FULL |
+|---|---|---|---|
+| FastAPI と Uvicorn | ✅ | ✅ | ✅ |
+| データ検証 | ✅ | ✅ | ✅ |
+| データベース対応 | ❌ | ✅ | ✅ |
+| マイグレーション | ❌ | ✅ | ✅ |
+| テストフレームワーク | ❌ | ✅ | ✅ |
+| キャッシュ (Redis) | ❌ | ❌ | ✅ |
+| バックグラウンドタスク | ❌ | ❌ | ✅ |
+| **適した用途** | 学習 / シンプルな API | 多くのアプリケーション | エンタープライズ / 複雑なアプリ |
+
+## プロジェクト作成の例
+
+### 例 1: 学習用プロジェクト
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: fastapi-learning
+Enter the author name: Student
+Enter the author email: student@example.com
+Enter the project description: Learning FastAPI basics
+
+Select stack (minimal, standard, full): minimal
+Do you want to proceed with project creation? [y/N]: y
+```
+
+</div>
+
+### 例 2: EC サイト API
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: ecommerce-api
+Enter the author name: E-commerce Team
+Enter the author email: team@ecommerce.com
+Enter the project description: E-commerce platform API
+
+Select stack (minimal, standard, full): standard
+Do you want to proceed with project creation? [y/N]: y
+```
+
+</div>
+
+### 例 3: 高パフォーマンスアプリケーション
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: enterprise-api
+Enter the author name: Enterprise Team
+Enter the author email: enterprise@company.com
+Enter the project description: High-performance enterprise API
+
+Select stack (minimal, standard, full): full
+Do you want to proceed with project creation? [y/N]: y
+```
+
+</div>
+
+## プロジェクト作成後
+
+### 1. 仮想環境の有効化
+
+<div class="termy">
+
+```console
+$ cd my-awesome-api
+$ source .venv/bin/activate  # Linux/macOS
+$ .venv\Scripts\activate     # Windows
+```
+
+</div>
+
+### 2. インストールの確認
+
+<div class="termy">
+
+```console
+$ pip list
+Package         Version
+fastapi         0.104.1
+uvicorn         0.24.0
+pydantic        2.5.0
+...
+```
+
+</div>
+
+### 3. 開発の開始
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+## 設定管理
+
+### 環境変数
+
+プロジェクトは `.env` ファイルによる環境ベースの設定をサポートしています。
+
+プロジェクトルートに `.env` ファイルを作成しましょう:
+
+```env
+# .env
+APP_NAME=My Awesome API
+APP_VERSION=1.0.0
+DEBUG=True
+DATABASE_URL=sqlite:///./app.db
+SECRET_KEY=your-secret-key-here
+```
+
+### コードからの設定
+
+生成された `src/core/config.py` がこれらの変数を自動で読み込みます:
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    APP_NAME: str = "FastAPI Application"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+    DATABASE_URL: str = "sqlite:///./app.db"
+    SECRET_KEY: str = "dev-secret-key"
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+## カスタマイズ
+
+### 依存関係の追加
+
+プロジェクト作成後、追加の依存関係をインストールできます:
+
+<div class="termy">
+
+```console
+$ pip install requests httpx python-jose
+$ pip freeze > requirements.txt
+```
+
+</div>
+
+### プロジェクト構造の変更
+
+生成された構造はベストプラクティスに従っていますが、必要に応じて変更できます:
+
+- `src/` に新しいモジュールを追加
+- `api/routes/` にルートファイルを追加
+- `crud/` で CRUD 操作を拡張
+- `schemas/` にスキーマを追加
+
+## ベストプラクティス
+
+### 1. 仮想環境
+
+プロジェクトの依存関係を分離するため、常に仮想環境を使いましょう:
+
+```bash
+# 仮想環境付きでプロジェクトを作成
+$ fastkit init  # .venv/ が自動生成される
+
+# 作業時に有効化
+$ source .venv/bin/activate
+```
+
+### 2. バージョン管理
+
+プロジェクト作成後に Git リポジトリを初期化しましょう:
+
+<div class="termy">
+
+```console
+$ cd my-awesome-api
+$ git init
+$ git add .
+$ git commit -m "Initial commit - FastAPI project setup"
+```
+
+</div>
+
+### 3. 環境設定
+
+- ローカル開発には `.env` ファイルを使用
+- 本番環境では環境変数を利用
+- 機密データはバージョン管理に決してコミットしない
+
+### 4. テスト
+
+同梱のテストフレームワークを活用しましょう:
+
+<div class="termy">
+
+```console
+$ python -m pytest
+$ bash scripts/test.sh
+```
+
+</div>
+
+## 次のステップ
+
+プロジェクトを作成したら:
+
+1. **[ルートの追加](adding-routes.md)**: 新しい API エンドポイントの追加方法を学ぶ
+2. **[CLI リファレンス](cli-reference.md)**: 利用可能なすべてのコマンドを習得
+3. **[最初のプロジェクトのチュートリアル](../tutorial/first-project.md)**: 完全なアプリケーションを構築
+
+!!! tip "プロジェクト作成のヒント"
+    - プロジェクト要件にマッチするスタックを選びましょう
+    - 学習なら MINIMAL、ほとんどのプロジェクトなら STANDARD から
+    - プロジェクト構造は拡張性と保守性を意識した設計です
+    - 生成されるコードはすべて FastAPI のベストプラクティスに従っています
diff --git a/docs/ja/user-guide/installation.md b/docs/ja/user-guide/installation.md
new file mode 100644
index 0000000..ecfa762
--- /dev/null
+++ b/docs/ja/user-guide/installation.md
@@ -0,0 +1,209 @@
+# インストール
+
+このガイドでは、FastAPI-fastkit のインストール方法を説明します。
+
+## 動作要件
+
+FastAPI-fastkit を使用するには、次の要件を満たす必要があります:
+
+- **Python**: 3.12 以上
+- **オペレーティングシステム**: Windows、macOS、Linux に対応
+
+## インストール方法
+
+### pip でインストール (推奨)
+
+最もシンプルなインストール方法です:
+
+<div class="termy">
+
+```console
+$ pip install FastAPI-fastkit
+---> 100%
+Successfully installed FastAPI-fastkit
+```
+
+</div>
+
+### 特定バージョンをインストール
+
+特定のバージョンをインストールする場合:
+
+<div class="termy">
+
+```console
+$ pip install FastAPI-fastkit==1.0.0
+---> 100%
+Successfully installed FastAPI-fastkit-1.0.0
+```
+
+</div>
+
+### 開発版をインストール
+
+GitHub から直接、最新の開発版をインストールする場合:
+
+<div class="termy">
+
+```console
+$ pip install git+https://github.com/bnbong/FastAPI-fastkit.git
+---> 100%
+Successfully installed FastAPI-fastkit
+```
+
+</div>
+
+!!! warning "開発版に関する注意"
+    開発版は不安定な可能性があり、本番環境での利用は推奨されません。
+
+## 仮想環境のセットアップ (推奨)
+
+依存関係の競合を避けるため、仮想環境の利用を強く推奨します:
+
+### venv を使う
+
+<div class="termy">
+
+```console
+$ python -m venv fastapi-env
+$ source fastapi-env/bin/activate  # Linux/macOS
+$ fastapi-env\Scripts\activate     # Windows
+$ pip install FastAPI-fastkit
+```
+
+</div>
+
+### conda を使う
+
+<div class="termy">
+
+```console
+$ conda create -n fastapi-env python=3.12
+$ conda activate fastapi-env
+$ pip install FastAPI-fastkit
+```
+
+</div>
+
+## インストールの確認
+
+インストール後、FastAPI-fastkit が正しくインストールされているか確認しましょう:
+
+<div class="termy">
+
+```console
+$ fastkit --version
+FastAPI-fastkit version 1.0.0
+```
+
+</div>
+
+<div class="termy">
+
+```console
+$ fastkit --help
+Usage: fastkit [OPTIONS] COMMAND [ARGS]...
+
+  FastAPI-fastkit CLI
+
+Options:
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  addroute       Add a new route to FastAPI project
+  init           Create a new FastAPI project
+  list-templates List available FastAPI templates
+  runserver      Start FastAPI development server
+  startdemo      Create FastAPI project from template
+```
+
+</div>
+
+## トラブルシューティング
+
+### コマンドが見つからない
+
+「command not found」エラーが出る場合:
+
+1. **FastAPI-fastkit がインストールされているか確認**:
+
+   <div class="termy">
+   ```console
+   $ pip show FastAPI-fastkit
+   ```
+   </div>
+
+2. **仮想環境を確認**:
+
+   <div class="termy">
+   ```console
+   $ which python
+   $ which pip
+   ```
+   </div>
+
+3. **FastAPI-fastkit を再インストール**:
+
+   <div class="termy">
+   ```console
+   $ pip uninstall FastAPI-fastkit
+   $ pip install FastAPI-fastkit
+   ```
+   </div>
+
+### パーミッションエラー
+
+インストール時にパーミッションエラーが発生する場合:
+
+**Linux/macOS の場合:**
+
+<div class="termy">
+
+```console
+$ pip install --user FastAPI-fastkit
+```
+
+</div>
+
+**Windows の場合 (管理者として実行):**
+
+<div class="termy">
+
+```console
+$ pip install FastAPI-fastkit
+```
+
+</div>
+
+### Python バージョンの互換性
+
+FastAPI-fastkit は Python 3.12 以上が必要です。Python のバージョンを確認しましょう:
+
+<div class="termy">
+
+```console
+$ python --version
+Python 3.12.0
+```
+
+</div>
+
+古いバージョンを使っている場合、Python をアップグレードしてください:
+
+- **公式 Python**: [python.org/downloads](https://www.python.org/downloads/)
+- **pyenv の場合**: `pyenv install 3.12.0`
+- **conda の場合**: `conda install python=3.12`
+
+## 次のステップ
+
+インストールが完了したら:
+
+1. **[クイックスタート](quick-start.md)**: 5 分で最初のプロジェクトを作成
+2. **[入門チュートリアル](../tutorial/getting-started.md)**: 段階的な詳細チュートリアル
+3. **[CLI リファレンス](cli-reference.md)**: 全コマンドのリファレンス
+
+!!! tip "インストールのヒント"
+    - プロジェクト分離のため、常に仮想環境を利用しましょう
+    - FastAPI-fastkit は最新版に更新を保ちましょう
+    - 更新情報や Issue は [GitHub リポジトリ](https://github.com/bnbong/FastAPI-fastkit) で確認しましょう
diff --git a/docs/ja/user-guide/quick-start.md b/docs/ja/user-guide/quick-start.md
new file mode 100644
index 0000000..6c59dd5
--- /dev/null
+++ b/docs/ja/user-guide/quick-start.md
@@ -0,0 +1,366 @@
+# クイックスタート
+
+FastAPI-fastkit で 5 分以内に最初の FastAPI プロジェクトを作成しましょう!
+
+!!! tip "どのスターターを選べばよいか分からないとき"
+    `startdemo` テンプレートと対話型のアーキテクチャプリセット (`minimal` / `single-module` / `classic-layered` / `domain-starter`) を初心者向けに比較した [**どのスターターを選ぶべき?**](choosing-a-starter.md) を参照してください。短く言えば、**`fastkit init --interactive` の `domain-starter` プリセットが現在の推奨デフォルト** です。
+
+## 1. プロジェクトの作成
+
+FastAPI-fastkit の `init` コマンドで新しいプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my-first-app
+Enter the author name: Your Name
+Enter the author email: your.email@example.com
+Enter the project description: My first FastAPI application
+
+           Project Information
+┌──────────────┬─────────────────────────────┐
+│ Project Name │ my-first-app                │
+│ Author       │ Your Name                   │
+│ Author Email │ your.email@example.com      │
+│ Description  │ My first FastAPI application│
+└──────────────┴─────────────────────────────┘
+
+Available Stacks and Dependencies:
+           MINIMAL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+           STANDARD Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ pydantic          │
+│ Dependency 7 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+             FULL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ redis             │
+│ Dependency 7 │ celery            │
+│ Dependency 8 │ pydantic          │
+│ Dependency 9 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+Select stack (minimal, standard, full): minimal
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'my-first-app' has been created successfully!
+```
+
+</div>
+
+## 2. 仮想環境の有効化
+
+プロジェクトディレクトリへ移動し、仮想環境を有効化します:
+
+<div class="termy">
+
+```console
+$ cd my-first-app
+$ source .venv/bin/activate  # Linux/macOS
+$ .venv\Scripts\activate     # Windows
+```
+
+</div>
+
+## 3. 開発サーバーの起動
+
+FastAPI 開発サーバーを起動します:
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [28720]
+INFO:     Started server process [28722]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+</div>
+
+!!! success "おめでとうございます!"
+    FastAPI サーバーが起動中です! ブラウザで確認してみましょう。
+
+## 4. API のテスト
+
+ブラウザで次の URL を開いてみましょう:
+
+### メインエンドポイント
+
+[http://127.0.0.1:8000](http://127.0.0.1:8000) にアクセスすると、次のように表示されます:
+
+```json
+{"message": "Hello World"}
+```
+
+### 対話型 API ドキュメント
+
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) を開いてください。
+
+これは自動生成される **Swagger UI** ドキュメントで、以下のことが可能です:
+
+- すべての API エンドポイントを表示
+- ブラウザから直接エンドポイントをテスト
+- リクエスト / レスポンススキーマを確認
+
+### 代替ドキュメント
+
+[http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) を開いてください。
+
+別のすっきりしたデザインの **ReDoc** ドキュメント画面です。
+
+## 5. 最初のルートの追加
+
+プロジェクトに新しい API ルートを追加してみましょう:
+
+<div class="termy">
+
+```console
+$ fastkit addroute users my-first-app
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-first-app                             │
+│ Route Name       │ users                                    │
+│ Target Directory │ ~/my-first-app                           │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'users' to project 'my-first-app'? [Y/n]: y
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Updated main.py to include the API router          │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Successfully added new route 'users' to project    │
+│ `my-first-app`                                        │
+╰───────────────────────────────────────────────────────╯
+```
+
+</div>
+
+サーバーは自動的に再読み込みされ、新しいエンドポイントが利用可能になります:
+
+- `GET /api/v1/users/` - すべてのユーザーを取得
+- `POST /api/v1/users/` - 新しいユーザーを作成
+- `GET /api/v1/users/{user_id}` - 特定のユーザーを取得
+- `PUT /api/v1/users/{user_id}` - ユーザーを更新
+- `DELETE /api/v1/users/{user_id}` - ユーザーを削除
+
+## 6. 新しい API のテスト
+
+### curl を使う
+
+**すべてのユーザーを取得:**
+
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000/api/v1/users/
+[]
+```
+
+</div>
+
+**新しいユーザーを作成:**
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/users/" \
+     -H "Content-Type: application/json" \
+     -d '{"title": "John Doe", "description": "Software Developer"}'
+{
+  "id": 1,
+  "title": "John Doe",
+  "description": "Software Developer"
+}
+```
+
+</div>
+
+### 対話型ドキュメントを使う
+
+1. [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) にアクセスします。
+2. **"users"** セクションを展開します。
+3. **"POST /api/v1/users/"** をクリックします。
+4. **"Try it out"** をクリックします。
+5. リクエストボディを入力します:
+   ```json
+   {
+     "title": "Jane Smith",
+     "description": "Product Manager"
+   }
+   ```
+6. **"Execute"** をクリックします。
+
+## 7. プロジェクト構造の確認
+
+生成されたプロジェクトは整理された構造を持ちます:
+
+```
+my-first-app/
+├── .venv/                    # 仮想環境
+├── src/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI アプリのエントリポイント
+│   ├── core/
+│   │   ├── __init__.py
+│   │   └── config.py        # アプリ設定
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── api.py          # API ルーターをまとめる
+│   │   └── routes/
+│   │       ├── __init__.py
+│   │       ├── items.py     # デフォルトの items ルート
+│   │       └── users.py     # 新しく追加した users ルート
+│   ├── crud/
+│   │   ├── __init__.py
+│   │   ├── items.py         # items 用の CRUD 操作
+│   │   └── users.py         # users 用の CRUD 操作
+│   ├── schemas/
+│   │   ├── __init__.py
+│   │   ├── items.py         # items 用 Pydantic スキーマ
+│   │   └── users.py         # users 用 Pydantic スキーマ
+│   └── mocks/
+│       ├── __init__.py
+│       └── mock_items.json  # テストデータ
+├── tests/                   # テストファイル
+├── scripts/                 # ユーティリティスクリプト
+├── requirements.txt         # Python 依存関係
+├── setup.py                # パッケージ設定
+└── README.md               # プロジェクトドキュメント
+```
+
+## 8. パッケージマネージャーの選択肢
+
+FastAPI-fastkit は好みに合わせて複数の Python パッケージマネージャーをサポートしています:
+
+### 利用可能なパッケージマネージャー
+
+| マネージャー | 説明 | 適している場面 |
+|---|---|---|
+| **UV** | 高速な Python パッケージマネージャー (デフォルト) | 速度とパフォーマンス |
+| **PDM** | モダンな Python 依存関係管理 | 高度な依存関係解決 |
+| **Poetry** | Python 依存関係管理とパッケージング | Poetry 中心のワークフロー |
+| **PIP** | 標準の Python パッケージマネージャー | 伝統的な Python 開発 |
+
+### パッケージマネージャーの指定方法
+
+好みのパッケージマネージャーは次の方法で指定できます:
+
+#### 1. 対話型選択 (デフォルト)
+
+`fastkit init` または `fastkit startdemo` を実行すると、選択プロンプトが表示されます:
+
+<div class="termy">
+
+```console
+$ fastkit init
+# ... プロジェクト情報とスタックを選択した後 ...
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+```
+
+</div>
+
+#### 2. コマンドラインオプション
+
+対話型プロンプトを飛ばし、パッケージマネージャーを直接指定できます:
+
+<div class="termy">
+
+```console
+$ fastkit init --package-manager poetry
+$ fastkit startdemo --package-manager pdm
+```
+
+</div>
+
+### 生成される依存関係ファイル
+
+各パッケージマネージャーはそれぞれ適切な依存関係ファイルを生成します:
+
+- **UV/PDM**: `pyproject.toml` (PEP 621 形式)
+- **Poetry**: `pyproject.toml` (Poetry 形式)
+- **PIP**: `requirements.txt`
+
+## 9. 次のステップ
+
+おめでとうございます! 以下をすべて達成しました:
+
+✅ 最初の FastAPI プロジェクトを作成
+✅ 開発サーバーを起動
+✅ 新しい API ルートを追加
+✅ API をテスト
+
+### 学習を続ける
+
+1. **[最初のプロジェクトを作る](../tutorial/first-project.md)**: より複雑なブログ API を構築
+2. **[プロジェクトの作成](creating-projects.md)**: 様々なスタックとオプションを学ぶ
+3. **[ルートの追加](adding-routes.md)**: API 開発のスキルを身につける
+4. **[テンプレートの利用](using-templates.md)**: あらかじめ用意されたプロジェクトテンプレートを試す
+
+### さらに試してみる
+
+次のコマンドで、より多くの機能を探索できます:
+
+<div class="termy">
+
+```console
+# 利用可能なテンプレート一覧
+$ fastkit list-templates
+
+# テンプレートからプロジェクトを生成
+$ fastkit startdemo
+
+# ルートをさらに追加 (ルート名が先、プロジェクトディレクトリが後)
+$ fastkit addroute products my-first-app
+$ fastkit addroute orders my-first-app
+```
+
+</div>
+
+!!! tip "開発のヒント"
+    - ファイルを変更するとサーバーが自動的に再読み込みされます
+    - 新機能を追加するたびに `/docs` で対話型ドキュメントを確認しましょう
+    - 依存関係の分離のために仮想環境を活用しましょう
+    - 生成されたコードを読んでプロジェクト構造を理解しましょう
diff --git a/docs/ja/user-guide/using-templates.md b/docs/ja/user-guide/using-templates.md
new file mode 100644
index 0000000..1b4df25
--- /dev/null
+++ b/docs/ja/user-guide/using-templates.md
@@ -0,0 +1,608 @@
+# テンプレートの利用
+
+FastAPI-fastkit は、さまざまな技術スタックですばやく開発を始められるよう、あらかじめ用意されたプロジェクトテンプレートを提供しています。
+
+## 利用可能なテンプレート
+
+`list-templates` コマンドで利用可能なテンプレートを確認できます:
+
+<div class="termy">
+
+```console
+$ fastkit list-templates
+                      Available Templates
+┌─────────────────────────┬───────────────────────────────────┐
+│ fastapi-custom-response │ Async Item Management API with    │
+│                         │ Custom Response System            │
+│ fastapi-dockerized      │ Dockerized FastAPI Item           │
+│                         │ Management API                    │
+│ fastapi-empty           │ No description                    │
+│ fastapi-async-crud      │ Async Item Management API Server  │
+│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
+│                         │ Management API with PostgreSQL    │
+│ fastapi-default         │ Simple FastAPI Project            │
+└─────────────────────────┴───────────────────────────────────┘
+```
+
+</div>
+
+## テンプレートの説明
+
+### 1. `fastapi-default`
+
+**シンプルな FastAPI プロジェクト**
+
+- 必要十分な機能を備えた基本的な FastAPI セットアップ
+- モックデータを使ったアイテム管理
+- 学習やシンプルな API に最適
+- 基本的な CRUD 操作を含む
+
+**適した用途:**
+
+- FastAPI の初心者
+- シンプルな Web API
+- 学習やプロトタイピング
+
+### 2. `fastapi-async-crud`
+
+**非同期アイテム管理 API サーバー**
+
+- 完全に非同期な FastAPI アプリケーション
+- async / await を使った高度な CRUD 操作
+- I/O 操作のパフォーマンス向上
+- 非同期パターンを用いたモックデータストレージ
+
+**適した用途:**
+
+- 高パフォーマンスアプリケーション
+- I/O 集約的な処理
+- モダンな非同期 Python 開発
+
+### 3. `fastapi-custom-response`
+
+**カスタムレスポンス機構を備えた非同期アイテム管理 API**
+
+- カスタムレスポンスモデルとフォーマット
+- 高度なエラーハンドリング
+- ページネーション対応
+- カスタム HTTP ステータスコードとレスポンス
+
+**適した用途:**
+
+- 特定のレスポンス形式が要求される API
+- 高度なエラーハンドリングが必要な場面
+- レスポンスにカスタムビジネスロジックを含める場合
+
+### 4. `fastapi-dockerized`
+
+**Docker 化された FastAPI アイテム管理 API**
+
+- 完全な Docker コンテナ化
+- 本番運用向けのデプロイ構成
+- マルチステージ Docker ビルド
+- 環境ベースの設定
+
+**適した用途:**
+
+- 本番デプロイ
+- コンテナ化された環境
+- DevOps と CI/CD パイプライン
+
+### 5. `fastapi-psql-orm`
+
+**PostgreSQL 対応の Docker 化された FastAPI アイテム管理 API**
+
+- PostgreSQL データベース統合
+- SQLAlchemy ORM と Alembic マイグレーション
+- ローカル開発のための Docker Compose
+- フル機能のデータベース CRUD 操作
+
+**適した用途:**
+
+- データベース駆動のアプリケーション
+- 本番品質のデータストレージ
+- 複雑なデータリレーションシップ
+
+### 6. `fastapi-empty`
+
+**最小構成の FastAPI プロジェクト**
+
+- 必要最小限の FastAPI セットアップ
+- あらかじめ用意された機能はありません
+- カスタム開発のためのまっさらなスタート
+
+**適した用途:**
+
+- ゼロから始める
+- 最小限の依存関係
+- 独自のアーキテクチャ要件
+
+## テンプレートからプロジェクトを作成する
+
+`startdemo` コマンドでテンプレートからプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo
+Enter the project name: my-blog-api
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: Blog API with PostgreSQL
+
+Available Templates:
+           fastapi-default
+┌─────────────┬──────────────────────┐
+│ Description │ Simple FastAPI       │
+│             │ Project              │
+│ Stack       │ FastAPI, Uvicorn     │
+│ Database    │ Mock Data            │
+│ Features    │ Basic CRUD           │
+└─────────────┴──────────────────────┘
+
+           fastapi-psql-orm
+┌─────────────┬──────────────────────┐
+│ Description │ Dockerized FastAPI   │
+│             │ Item Management API  │
+│             │ with PostgreSQL      │
+│ Stack       │ FastAPI, PostgreSQL, │
+│             │ SQLAlchemy, Docker   │
+│ Database    │ PostgreSQL           │
+│ Features    │ Full ORM, Migrations │
+└─────────────┴──────────────────────┘
+
+Select template (fastapi-default, fastapi-async-crud, fastapi-custom-response, fastapi-dockerized, fastapi-psql-orm, fastapi-empty): fastapi-psql-orm
+
+           Project Information
+┌──────────────┬─────────────────────┐
+│ Project Name │ my-blog-api         │
+│ Author       │ John Doe            │
+│ Author Email │ john@example.com    │
+│ Description  │ Blog API with       │
+│              │ PostgreSQL          │
+└──────────────┴─────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ psycopg2-binary   │
+│ Dependency 6 │ python-dotenv     │
+│ Dependency 7 │ pytest            │
+└──────────────┴───────────────────┘
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'my-blog-api' from 'fastapi-psql-orm' has been created successfully!
+```
+
+</div>
+
+## テンプレートの機能比較
+
+| 機能 | Default | Async CRUD | Custom Response | Dockerized | PostgreSQL ORM | Empty |
+|---|---|---|---|---|---|---|
+| **基本 FastAPI** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **モックデータ** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| **非同期サポート** | 基本 | ✅ | ✅ | ✅ | ✅ | ❌ |
+| **カスタムレスポンス** | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| **Docker** | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
+| **データベース** | モック | モック | モック | モック | PostgreSQL | なし |
+| **ORM** | ❌ | ❌ | ❌ | ❌ | SQLAlchemy | ❌ |
+| **マイグレーション** | ❌ | ❌ | ❌ | ❌ | Alembic | ❌ |
+| **テスト** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| **適した用途** | 学習 | パフォーマンス | カスタム API | 本番運用 | DB アプリ | カスタム |
+
+## テンプレートごとのセットアップ
+
+### `fastapi-psql-orm` を使う
+
+このテンプレートは PostgreSQL のフルセットアップを含みます。作成後:
+
+1. **Docker で PostgreSQL を起動:**
+
+<div class="termy">
+
+```console
+$ cd my-blog-api
+$ docker-compose up -d postgres
+Starting my-blog-api_postgres_1 ... done
+```
+
+</div>
+
+2. **データベースマイグレーションを実行:**
+
+<div class="termy">
+
+```console
+$ source .venv/bin/activate
+$ alembic upgrade head
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.runtime.migration] Running upgrade -> bedcdc35b64a, first alembic
+```
+
+</div>
+
+3. **API サーバーを起動:**
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+### `fastapi-dockerized` を使う
+
+このテンプレートは Docker のフル機能を提供します:
+
+1. **Docker イメージのビルド:**
+
+<div class="termy">
+
+```console
+$ cd my-dockerized-api
+$ docker build -t my-dockerized-api .
+Successfully built abc123def456
+Successfully tagged my-dockerized-api:latest
+```
+
+</div>
+
+2. **コンテナの起動:**
+
+<div class="termy">
+
+```console
+$ docker run -p 8000:8000 my-dockerized-api
+INFO:     Uvicorn running on http://0.0.0.0:8000
+```
+
+</div>
+
+### `fastapi-custom-response` を使う
+
+このテンプレートには高度なレスポンス処理が含まれています:
+
+1. **カスタムレスポンスモデル:**
+
+```python
+from src.helper.pagination import PaginatedResponse
+from src.schemas.base import StandardResponse
+
+@router.get("/", response_model=PaginatedResponse[Item])
+def read_items(skip: int = 0, limit: int = 10):
+    items = items_crud.get_multi(skip=skip, limit=limit)
+    total = items_crud.count()
+
+    return PaginatedResponse(
+        data=items,
+        total=total,
+        page=skip // limit + 1,
+        pages=(total + limit - 1) // limit
+    )
+
+@router.post("/", response_model=StandardResponse[Item])
+def create_item(item: ItemCreate):
+    new_item = items_crud.create(item)
+    return StandardResponse(
+        data=new_item,
+        message="Item created successfully",
+        status_code=201
+    )
+```
+
+2. **拡張されたエラーハンドリング:**
+
+```python
+from src.helper.exceptions import ItemNotFoundError, ValidationError
+
+@router.get("/{item_id}", response_model=StandardResponse[Item])
+def read_item(item_id: int):
+    try:
+        item = items_crud.get(item_id)
+        return StandardResponse(data=item)
+    except ItemNotFoundError:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Item with id {item_id} not found"
+        )
+```
+
+## テンプレートのプロジェクト構造
+
+各テンプレートは一貫した、しかしテンプレートごとに調整された構造を持ちます:
+
+### `fastapi-default` の構造
+```
+my-project/
+├── src/
+│   ├── main.py
+│   ├── core/config.py
+│   ├── api/
+│   │   ├── api.py
+│   │   └── routes/items.py
+│   ├── crud/items.py
+│   ├── schemas/items.py
+│   └── mocks/mock_items.json
+├── tests/
+├── scripts/
+└── requirements.txt
+```
+
+### `fastapi-psql-orm` の構造
+```
+my-project/
+├── src/
+│   ├── main.py
+│   ├── core/
+│   │   ├── config.py
+│   │   └── db.py
+│   ├── api/
+│   │   ├── api.py
+│   │   ├── deps.py
+│   │   └── routes/items.py
+│   ├── crud/items.py
+│   ├── schemas/items.py
+│   ├── alembic/
+│   │   ├── env.py
+│   │   └── versions/
+│   └── utils/
+├── tests/
+├── scripts/
+├── docker-compose.yml
+├── Dockerfile
+├── alembic.ini
+└── requirements.txt
+```
+
+## テンプレートのカスタマイズ
+
+テンプレートからプロジェクトを作成した後、必要に応じてカスタマイズできます:
+
+### 1. 新しいルートを追加
+
+<div class="termy">
+
+```console
+$ fastkit addroute posts my-blog-api
+$ fastkit addroute users my-blog-api
+$ fastkit addroute comments my-blog-api
+```
+
+</div>
+
+### 2. 設定の変更
+
+`src/core/config.py` を編集してニーズに合わせます:
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "My Blog API"
+    VERSION: str = "1.0.0"
+    API_V1_STR: str = "/api/v1"
+
+    # Database settings (for PostgreSQL templates)
+    DATABASE_URL: str = "postgresql://user:password@localhost/dbname"
+
+    # Security settings
+    SECRET_KEY: str = "your-secret-key-here"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+### 3. 環境変数の追加
+
+プロジェクトルートに `.env` ファイルを作成します:
+
+```env
+# .env
+PROJECT_NAME=My Blog API
+VERSION=1.0.0
+DEBUG=True
+
+# Database (for PostgreSQL templates)
+DATABASE_URL=postgresql://user:password@localhost:5432/myblogdb
+POSTGRES_USER=user
+POSTGRES_PASSWORD=password
+POSTGRES_DB=myblogdb
+
+# Security
+SECRET_KEY=your-super-secret-key-here
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+```
+
+## テンプレートのテスト
+
+各テンプレートはあらかじめ構成されたテストを備えています:
+
+<div class="termy">
+
+```console
+$ cd my-blog-api
+$ source .venv/bin/activate
+$ python -m pytest
+
+======================== test session starts ========================
+tests/test_items.py::test_create_item PASSED
+tests/test_items.py::test_read_items PASSED
+tests/test_items.py::test_read_item PASSED
+tests/test_items.py::test_update_item PASSED
+tests/test_items.py::test_delete_item PASSED
+======================== 5 passed in 0.23s ========================
+```
+
+</div>
+
+## テンプレート開発のワークフロー
+
+### 1. 適切なテンプレートを選ぶ
+
+- **学習 / シンプルな API**: `fastapi-default`
+- **高パフォーマンス**: `fastapi-async-crud`
+- **カスタムレスポンス形式**: `fastapi-custom-response`
+- **本番デプロイ**: `fastapi-dockerized`
+- **データベースアプリケーション**: `fastapi-psql-orm`
+- **独自アーキテクチャ**: `fastapi-empty`
+
+### 2. 作成とセットアップ
+
+<div class="termy">
+
+```console
+$ fastkit startdemo
+# プロンプトに従う
+$ cd your-project
+$ source .venv/bin/activate
+```
+
+</div>
+
+### 3. 開発
+
+<div class="termy">
+
+```console
+# 開発サーバーを起動
+$ fastkit runserver
+
+# テストを実行
+$ python -m pytest
+
+# 新機能を追加
+$ fastkit addroute new-resource your-project
+```
+
+</div>
+
+### 4. デプロイ
+
+本番向けテンプレート (`fastapi-dockerized`、`fastapi-psql-orm`) の場合:
+
+<div class="termy">
+
+```console
+# 本番ビルド
+$ docker build -t your-app .
+
+# Docker Compose でデプロイ
+$ docker-compose up -d
+```
+
+</div>
+
+## ベストプラクティス
+
+### 1. テンプレートを賢く選ぶ
+
+- 学習にはシンプルなテンプレートから始める
+- データ駆動型アプリにはデータベース対応のテンプレート
+- 本番デプロイには Docker 対応テンプレート
+
+### 2. 環境管理
+
+- 設定には常に `.env` ファイルを使う
+- 機密データはバージョン管理にコミットしない
+- 開発と本番で異なる環境を使う
+
+### 3. カスタマイズの方針
+
+- 新しいルートは `fastkit addroute` で追加
+- 既存コードは自分のビジネスロジックに合わせて変更
+- プロジェクト構造は整理された状態を維持
+
+### 4. テスト
+
+- 開発中は定期的にテストを実行
+- 実装した新機能にはテストを追加
+- 同梱のテスト構造をガイドとして活用
+
+## トラブルシューティング
+
+### データベース接続の問題 (PostgreSQL テンプレート)
+
+PostgreSQL に接続できない場合:
+
+1. **Docker が動作しているか確認:**
+
+   <div class="termy">
+   ```console
+   $ docker ps
+   ```
+   </div>
+
+2. **PostgreSQL コンテナを確認:**
+
+   <div class="termy">
+   ```console
+   $ docker-compose logs postgres
+   ```
+   </div>
+
+3. **環境変数を確認:**
+
+   ```env
+   DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+   ```
+
+### Docker ビルドの失敗
+
+Docker ビルドに失敗する場合:
+
+1. **Dockerfile の構文を確認**
+2. **必要なファイルがすべて存在するか確認**
+3. **Docker デーモンが動作しているか確認**
+
+### 依存関係が見つからない
+
+import エラーが出る場合:
+
+1. **仮想環境を有効化:**
+   <div class="termy">
+   ```console
+   $ source .venv/bin/activate
+   ```
+   </div>
+
+2. **依存関係をインストール:**
+   <div class="termy">
+   ```console
+   $ pip install -r requirements.txt
+   ```
+   </div>
+
+## 次のステップ
+
+テンプレートを理解できたら:
+
+1. **[最初のプロジェクト](../tutorial/first-project.md)**: 完全なアプリケーションを構築
+2. **[ルートの追加](adding-routes.md)**: テンプレートベースのプロジェクトを拡張
+3. **[CLI リファレンス](cli-reference.md)**: 利用可能なすべてのコマンドを習得
+
+!!! tip "テンプレートのヒント"
+    - テンプレートは出発点であって最終的な解ではありません
+    - 自分の要件に合わせてテンプレートをカスタマイズしましょう
+    - テンプレートのコードを読み、FastAPI のベストプラクティスを学びましょう
+    - 自分のカスタマイズを追えるようバージョン管理を活用しましょう
diff --git a/docs/ko/reference/translation-status.md b/docs/ko/reference/translation-status.md
index f73f7d4..3dca383 100644
--- a/docs/ko/reference/translation-status.md
+++ b/docs/ko/reference/translation-status.md
@@ -20,13 +20,13 @@ FastAPI-fastkit 문서는 여러 언어로 빌드되지만, 모든 번역이 **
 |---|---|---:|---|
 | 🇬🇧 English (`en`) | ✅ 원본 | 26 / 26 | 기준이 되는 원문입니다. |
 | 🇰🇷 한국어 (`ko`) | ✅ 완료 | 26 / 26 | 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. `docs/ko/changelog.md` 는 영문 기준 `CHANGELOG.md` 를 그대로 사용합니다. |
-| 🇯🇵 일본어 (`ja`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
+| 🇯🇵 일본어 (`ja`) | 🟡 부분 번역 | 7 / 26 | Phase 1 반영: 최상위 + 핵심 user-guide + `reference/translation-status.md`. 나머지 페이지는 영어 원문으로 대체됩니다. |
 | 🇨🇳 중국어 (`zh`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇪🇸 스페인어 (`es`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇫🇷 프랑스어 (`fr`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇩🇪 독일어 (`de`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 
-*스냅샷 검증 시점: 2026-05-07. Phase 3(contributing + reference) 작업이 반영된 현재 브랜치 기준으로 `ko` 행을 다시 집계했습니다. 한국어는 언어별 페이지가 모두 존재하며, `docs/ko/changelog.md` 는 영문 기준 changelog를 그대로 가리킵니다.* 이 표는 수동으로 관리됩니다. 리포지토리 루트에서 현재 상태를 다시 세고 싶다면 다음 명령을 실행하세요:
+*스냅샷 검증 시점: 2026-05-10. Phase 1(최상위 + 핵심 user-guide + `reference/translation-status.md`) 작업이 반영된 현재 브랜치 기준으로 `ja` 행을 다시 집계했습니다.* 이 표는 수동으로 관리됩니다. 리포지토리 루트에서 현재 상태를 다시 세고 싶다면 다음 명령을 실행하세요:
 
 ```console
 $ for loc in en ko ja zh es fr de; do

From a9dead2e1fdd391f01e65d43d6e6002185ad54ea Mon Sep 17 00:00:00 2001
From: bnbong <bbbong9@gmail.com>
Date: Sun, 10 May 2026 22:40:17 +0900
Subject: [PATCH 2/3] [DOCS] ja translation - Phase 2, 3

---
 docs/en/reference/translation-status.md       |    4 +-
 docs/ja/changelog.md                          |    1 +
 docs/ja/contributing/code-guidelines.md       |  748 +++++++
 docs/ja/contributing/development-setup.md     |  816 ++++++++
 .../contributing/template-creation-guide.md   |  576 ++++++
 docs/ja/contributing/translation-guide.md     |  367 ++++
 docs/ja/reference/faq.md                      |  784 ++++++++
 docs/ja/reference/preset-feature-matrix.md    |   60 +
 .../reference/template-quality-assurance.md   |  218 +++
 docs/ja/reference/translation-status.md       |   18 +-
 docs/ja/tutorial/async-crud-api.md            |  665 +++++++
 docs/ja/tutorial/basic-api-server.md          |  398 ++++
 docs/ja/tutorial/custom-response-handling.md  | 1393 +++++++++++++
 docs/ja/tutorial/database-integration.md      | 1027 ++++++++++
 docs/ja/tutorial/docker-deployment.md         | 1177 +++++++++++
 docs/ja/tutorial/domain-starter.md            |  392 ++++
 docs/ja/tutorial/first-project.md             | 1252 ++++++++++++
 docs/ja/tutorial/getting-started.md           |  564 ++++++
 docs/ja/tutorial/mcp-integration.md           | 1730 +++++++++++++++++
 docs/ja/user-guide/adding-routes.md           |  581 ++++++
 docs/ja/user-guide/cli-reference.md           |  832 ++++++++
 docs/ko/reference/translation-status.md       |    4 +-
 22 files changed, 13594 insertions(+), 13 deletions(-)
 create mode 100644 docs/ja/changelog.md
 create mode 100644 docs/ja/contributing/code-guidelines.md
 create mode 100644 docs/ja/contributing/development-setup.md
 create mode 100644 docs/ja/contributing/template-creation-guide.md
 create mode 100644 docs/ja/contributing/translation-guide.md
 create mode 100644 docs/ja/reference/faq.md
 create mode 100644 docs/ja/reference/preset-feature-matrix.md
 create mode 100644 docs/ja/reference/template-quality-assurance.md
 create mode 100644 docs/ja/tutorial/async-crud-api.md
 create mode 100644 docs/ja/tutorial/basic-api-server.md
 create mode 100644 docs/ja/tutorial/custom-response-handling.md
 create mode 100644 docs/ja/tutorial/database-integration.md
 create mode 100644 docs/ja/tutorial/docker-deployment.md
 create mode 100644 docs/ja/tutorial/domain-starter.md
 create mode 100644 docs/ja/tutorial/first-project.md
 create mode 100644 docs/ja/tutorial/getting-started.md
 create mode 100644 docs/ja/tutorial/mcp-integration.md
 create mode 100644 docs/ja/user-guide/adding-routes.md
 create mode 100644 docs/ja/user-guide/cli-reference.md

diff --git a/docs/en/reference/translation-status.md b/docs/en/reference/translation-status.md
index 2920eff..4c8c1be 100644
--- a/docs/en/reference/translation-status.md
+++ b/docs/en/reference/translation-status.md
@@ -35,13 +35,13 @@ next section explains).
 |---|---|---:|---|
 | 🇬🇧 English (`en`) | ✅ Source of truth | 26 / 26 | Authoritative. |
 | 🇰🇷 Korean (`ko`) | ✅ Complete | 26 / 26 | All locale pages are present. Phase 1: top-level + core user-guide; Phase 2: remaining user-guide + all tutorials; Phase 3: contributing + reference. `docs/ko/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇯🇵 Japanese (`ja`) | 🟡 Partial | 7 / 26 | Phase 1 landed: top-level + core user-guide + `reference/translation-status.md`. Remaining pages fall back to English. |
+| 🇯🇵 Japanese (`ja`) | ✅ Complete | 26 / 26 | All locale pages are present. Phase 1: top-level + core user-guide; Phase 2: remaining user-guide + all tutorials; Phase 3: contributing + reference. `docs/ja/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
 | 🇨🇳 Chinese (`zh`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇪🇸 Spanish (`es`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇫🇷 French (`fr`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 | 🇩🇪 German (`de`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
 
-*Snapshot verified 2026-05-10; ja row recounted for the current branch after Phase 1 (top-level + core user-guide + `reference/translation-status.md`) landed.* These counts are maintained by hand;
+*Snapshot verified 2026-05-10; ja row recounted for the current branch after Phase 3 (contributing + reference) landed. Japanese now has all locale pages present, while `docs/ja/changelog.md` intentionally points to the canonical English changelog.* These counts are maintained by hand;
 to recount the current state from the repo root, run:
 
 ```console
diff --git a/docs/ja/changelog.md b/docs/ja/changelog.md
new file mode 100644
index 0000000..f4d16fd
--- /dev/null
+++ b/docs/ja/changelog.md
@@ -0,0 +1 @@
+{!CHANGELOG.md!}
diff --git a/docs/ja/contributing/code-guidelines.md b/docs/ja/contributing/code-guidelines.md
new file mode 100644
index 0000000..2a392d6
--- /dev/null
+++ b/docs/ja/contributing/code-guidelines.md
@@ -0,0 +1,748 @@
+# コードガイドライン
+
+FastAPI-fastkit へ貢献する際のコーディング標準とベストプラクティスをまとめた包括的なガイドです。
+
+## 概要
+
+これらのガイドラインは、FastAPI-fastkit プロジェクト全体でコード品質、一貫性、保守性を保つためのものです。これらの基準に従うことで、読みやすく、保守しやすく、拡張しやすいコードベースが維持できます。
+
+## Python のコードスタイル
+
+### PEP 8 準拠
+
+[PEP 8](https://www.python.org/dev/peps/pep-0008/) に従い、次の固有設定を使用します:
+
+- **行長**: 88 文字 (Black デフォルト)
+- **インデント**: スペース 4 つ (タブ禁止)
+- **末尾カンマ**: 複数行の構造では必須
+- **文字列クオート**: ダブルクオート推奨
+
+### コードフォーマット
+
+自動フォーマットには **Black** を使用します:
+
+```python
+# 良い例 ✅
+def create_project(
+    name: str,
+    template: str,
+    options: Dict[str, Any],
+) -> ProjectResult:
+    """Create a new FastAPI project."""
+    return ProjectResult(name=name, template=template)
+
+# 悪い例 ❌
+def create_project(name: str, template: str, options: Dict[str,Any])->ProjectResult:
+    """Create a new FastAPI project."""
+    return ProjectResult(name=name,template=template)
+```
+
+### import の整理
+
+import の整理には **isort** を使用します:
+
+```python
+# 標準ライブラリ
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+
+# サードパーティ
+import click
+import pydantic
+from fastapi import FastAPI
+
+# ローカル
+from fastapi_fastkit.commands import BaseCommand
+from fastapi_fastkit.utils import validation
+from fastapi_fastkit.templates.manager import TemplateManager
+```
+
+## 型ヒント
+
+### 必須の型ヒント
+
+すべての公開関数とメソッドには型ヒントが必要です:
+
+```python
+# 良い例 ✅
+def validate_project_name(name: str) -> bool:
+    """Validate project name format."""
+    return name.isidentifier() and not name.startswith('_')
+
+def create_files(
+    files: List[Path],
+    template_data: Dict[str, Any]
+) -> List[Path]:
+    """Create files from template data."""
+    created_files = []
+    for file_path in files:
+        # 実装 ...
+        created_files.append(file_path)
+    return created_files
+
+# 悪い例 ❌
+def validate_project_name(name):
+    return name.isidentifier() and not name.startswith('_')
+```
+
+### 複雑な型注釈
+
+複雑な構造には適切な型注釈を使用します:
+
+```python
+from typing import Dict, List, Optional, Union, Tuple, Any
+from pathlib import Path
+
+# 複雑な型のエイリアス
+ProjectConfig = Dict[str, Union[str, bool, List[str]]]
+FileMapping = Dict[Path, str]
+ValidationResult = Tuple[bool, Optional[str]]
+
+def process_template(
+    template_path: Path,
+    config: ProjectConfig,
+    output_dir: Optional[Path] = None,
+) -> ValidationResult:
+    """Process template with configuration."""
+    # 実装 ...
+    return True, None
+```
+
+## 命名規則
+
+### 変数と関数
+
+- 変数と関数には **snake_case**
+- **目的が分かる名前** を付ける
+- **省略形は避ける** (一般的に通じるものを除く)
+
+```python
+# 良い例 ✅
+project_name = "my-api"
+template_directory = Path("templates")
+user_input_data = get_user_input()
+
+def validate_email_address(email: str) -> bool:
+    """Validate email address format."""
+    return "@" in email and "." in email
+
+# 悪い例 ❌
+proj_nm = "my-api"
+temp_dir = Path("templates")
+usr_data = get_input()
+
+def validate_email(e):
+    return "@" in e and "." in e
+```
+
+### クラス
+
+- クラス名には **PascalCase**
+- **記述的かつ具体的** な名前
+
+```python
+# 良い例 ✅
+class SomeClass:
+    """Represents example class of FastAPI-fastkit."""
+    pass
+
+class SomeClassValidationError(Exception):
+    """Raised when example class validation fails."""
+    pass
+
+class UserInputHandler:
+    """Handles user input validation and processing."""
+    pass
+
+# 悪い例 ❌
+class Class:
+    pass
+
+class Error(Exception):
+    pass
+
+class Handler:
+    pass
+```
+
+### 定数
+
+- アンダースコア区切りの **UPPER_CASE**
+- **モジュールレベル** に限定
+
+```python
+# 良い例 ✅
+DEFAULT_TEMPLATE_NAME = "fastapi-default"
+MAX_PROJECT_NAME_LENGTH = 50
+SUPPORTED_PYTHON_VERSIONS = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+# 悪い例 ❌
+default_template = "fastapi-default"
+maxLength = 50
+versions = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+```
+
+## ドキュメント標準
+
+### docstring
+
+すべての公開 API には **Google スタイルの docstring** を使用します:
+
+```python
+def create_project_structure(
+    project_name: str,
+    template_path: Path,
+    output_directory: Optional[Path] = None,
+    overwrite: bool = False,
+) -> List[Path]:
+    """Create project structure from template.
+
+    Creates a new FastAPI project structure by copying and processing
+    template files. Supports variable substitution and file customization.
+
+    Args:
+        project_name: Name of the project to create. Must be a valid
+            Python identifier.
+        template_path: Path to the template directory containing
+            source files and configuration.
+        output_directory: Directory where project will be created.
+            Defaults to current working directory.
+        overwrite: Whether to overwrite existing files. If False,
+            raises error when files exist.
+
+    Returns:
+        List of created file paths in order of creation.
+
+    Raises:
+        ValueError: If project_name is invalid or empty.
+        FileExistsError: If output directory exists and overwrite is False.
+        TemplateNotFoundError: If template_path doesn't exist.
+        PermissionError: If insufficient permissions to create files.
+
+    Example:
+        ```python
+        template_path = Path("templates/fastapi-default")
+        created_files = create_project_structure(
+            project_name="my-api",
+            template_path=template_path,
+            output_directory=Path("./projects"),
+            overwrite=False
+        )
+        print(f"Created {len(created_files)} files")
+        ```
+    """
+    # 実装 ...
+    pass
+```
+
+### コメント
+
+- **何 (WHAT) ではなく、なぜ (WHY) を説明**
+- **必要最小限** に — コードは自己説明的であるべき
+- **コード変更時にコメントも更新**
+
+```python
+# 良い例 ✅
+def validate_dependencies(requirements: List[str]) -> bool:
+    """Validate project dependencies."""
+    # 実験的なパッケージを許可するため、開発モードでは検証をスキップする
+    if os.getenv("FASTKIT_DEV_MODE"):
+        return True
+
+    # 既知のセキュリティ脆弱性に対して各要件を確認する
+    for requirement in requirements:
+        if is_vulnerable_package(requirement):
+            return False
+
+    return True
+
+# 悪い例 ❌
+def validate_dependencies(requirements: List[str]) -> bool:
+    """Validate project dependencies."""
+    # dev モードかチェック
+    if os.getenv("FASTKIT_DEV_MODE"):
+        return True
+
+    # 要件をループ
+    for requirement in requirements:
+        # 脆弱かチェック
+        if is_vulnerable_package(requirement):
+            return False
+
+    # true を返す
+    return True
+```
+
+## エラー処理
+
+### 例外処理
+
+- 可能な限り **具体的な例外をキャッチ**
+- **意味のあるエラーメッセージ** を提供
+- **エラーは適切にログ出力**
+
+```python
+# 良い例 ✅
+def load_template_config(template_path: Path) -> Dict[str, Any]:
+    """Load template configuration from file."""
+    config_file = template_path / "template.yaml"
+
+    try:
+        with open(config_file, 'r') as f:
+            return yaml.safe_load(f)
+    except FileNotFoundError:
+        raise TemplateNotFoundError(
+            f"Template configuration not found: {config_file}"
+        )
+    except yaml.YAMLError as e:
+        raise TemplateConfigError(
+            f"Invalid YAML syntax in {config_file}: {e}"
+        )
+    except PermissionError:
+        raise TemplateAccessError(
+            f"Permission denied reading {config_file}"
+        )
+
+# 悪い例 ❌
+def load_template_config(template_path: Path) -> Dict[str, Any]:
+    """Load template configuration from file."""
+    config_file = template_path / "template.yaml"
+
+    try:
+        with open(config_file, 'r') as f:
+            return yaml.safe_load(f)
+    except Exception as e:
+        raise Exception(f"Error loading config: {e}")
+```
+
+### カスタム例外
+
+エラー条件ごとに専用の例外を定義します:
+
+```python
+class FastKitError(Exception):
+    """Base exception for FastAPI-fastkit errors."""
+    pass
+
+class ProjectCreationError(FastKitError):
+    """Raised when project creation fails."""
+    pass
+
+class TemplateNotFoundError(FastKitError):
+    """Raised when template is not found."""
+    pass
+
+class ValidationError(FastKitError):
+    """Raised when input validation fails."""
+
+    def __init__(self, message: str, field: str = None):
+        super().__init__(message)
+        self.field = field
+```
+
+## テスト基準
+
+### テスト構造
+
+明快な構成と命名でテストを整理します:
+
+```python
+class TestProjectCreation:
+    """Test project creation functionality."""
+
+    def test_create_project_with_valid_name(self, tmp_path):
+        """Test project creation with valid project name."""
+        project_name = "test-project"
+        result = create_project(project_name, template="minimal", output=tmp_path)
+
+        assert result.success is True
+        assert (tmp_path / project_name).exists()
+        assert (tmp_path / project_name / "src" / "main.py").exists()
+
+    def test_create_project_with_invalid_name(self):
+        """Test project creation fails with invalid name."""
+        with pytest.raises(ValueError, match="Invalid project name"):
+            create_project("invalid-project-name!", template="minimal")
+
+    def test_create_project_overwrites_existing(self, tmp_path):
+        """Test project creation overwrites existing directory when forced."""
+        project_name = "existing-project"
+        project_dir = tmp_path / project_name
+        project_dir.mkdir()
+
+        result = create_project(
+            project_name,
+            template="minimal",
+            output=tmp_path,
+            overwrite=True
+        )
+
+        assert result.success is True
+        assert project_dir.exists()
+```
+
+### テストカバレッジ
+
+- 新規コードでは **90% 以上のカバレッジ** を目標に
+- **エッジケースとエラー条件** をテスト
+- **外部依存はモック**
+
+```python
+def test_template_download_with_network_error(mock_requests):
+    """Test template download handles network errors gracefully."""
+    mock_requests.get.side_effect = requests.ConnectionError("Network unreachable")
+
+    with pytest.raises(TemplateDownloadError, match="Network error"):
+        download_template("https://example.com/template.zip")
+
+def test_file_creation_with_permission_error(mock_open):
+    """Test file creation handles permission errors."""
+    mock_open.side_effect = PermissionError("Permission denied")
+
+    with pytest.raises(FileCreationError, match="Permission denied"):
+        create_file(Path("/restricted/file.py"), content="test")
+```
+
+## import ガイドライン
+
+### import の整理
+
+!!! note
+
+    `isort` フォーマッタが自動で import を整えます。`bash scripts/format.sh` を実行するだけで簡単に整理できます。
+
+1. **標準ライブラリ** を最初
+2. **サードパーティ** を次に
+3. **ローカルアプリケーション** を最後に
+4. 各グループの間に **空行 1 行**
+
+```python
+# 標準ライブラリ
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# サードパーティ
+import click
+import pydantic
+import yaml
+from fastapi import FastAPI
+
+# ローカルアプリケーション
+from fastapi_fastkit.commands.base import BaseCommand
+from fastapi_fastkit.utils.validation import validate_project_name
+from fastapi_fastkit.templates import TemplateManager
+```
+
+### import のベストプラクティス
+
+- **ワイルドカード import を避ける** (`from module import *`)
+- 明快さのため **絶対 import を使う**
+- 多数の項目を import するときは **モジュールを import する** (個別項目ではなく)
+
+```python
+# 良い例 ✅
+from fastapi_fastkit.utils import validation, files, formatting
+
+# 良い例 ✅ (少数のみ import する場合)
+from fastapi_fastkit.utils.validation import validate_email, validate_project_name
+
+# 悪い例 ❌
+from fastapi_fastkit.utils.validation import *
+
+# 悪い例 ❌ (多数の項目を import する場合)
+from fastapi_fastkit.utils.validation import (
+    validate_email, validate_project_name, validate_template_name,
+    validate_dependencies, validate_python_version, validate_directory
+)
+```
+
+## セキュリティガイドライン
+
+### 入力検証
+
+ユーザー入力は常に検証 / サニタイズしてください:
+
+```python
+def validate_project_name(name: str) -> str:
+    """Validate and sanitize project name."""
+    if not name:
+        raise ValueError("Project name cannot be empty")
+
+    if not name.isidentifier():
+        raise ValueError("Project name must be a valid Python identifier")
+
+    if name.startswith('_'):
+        raise ValueError("Project name cannot start with underscore")
+
+    if len(name) > 50:
+        raise ValueError("Project name too long (max 50 characters)")
+
+    # 危険な文字を取り除いてサニタイズ
+    sanitized = re.sub(r'[^a-zA-Z0-9_-]', '', name)
+
+    return sanitized
+```
+
+### ファイル操作
+
+ファイルパスや操作には注意してください:
+
+```python
+def create_file_safely(file_path: Path, content: str, base_dir: Path) -> None:
+    """Create file safely within base directory."""
+    # ディレクトリトラバーサル攻撃を防ぐためにパスを解決
+    resolved_path = file_path.resolve()
+    resolved_base = base_dir.resolve()
+
+    # ファイルがベースディレクトリ内にあることを確認
+    try:
+        resolved_path.relative_to(resolved_base)
+    except ValueError:
+        raise SecurityError(f"File path outside base directory: {file_path}")
+
+    # 親ディレクトリを安全に作成
+    resolved_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 適切な権限でファイルを書き込み
+    resolved_path.write_text(content, encoding='utf-8')
+    resolved_path.chmod(0o644)  # 所有者は読み書き、それ以外は読み取りのみ
+```
+
+## パフォーマンスガイドライン
+
+### 効率的なコードの書き方
+
+- 大きなデータセットには **ジェネレータを使う**
+- **早すぎる最適化は避ける**
+- **最適化前にプロファイル**
+
+```python
+# 良い例 ✅ — メモリ効率のためのジェネレータ
+def process_large_template(template_files: List[Path]) -> Iterator[ProcessedFile]:
+    """Process template files efficiently."""
+    for file_path in template_files:
+        content = file_path.read_text()
+        processed_content = process_template_content(content)
+        yield ProcessedFile(path=file_path, content=processed_content)
+
+# 悪い例 ❌ — すべてをメモリにロード
+def process_large_template(template_files: List[Path]) -> List[ProcessedFile]:
+    """Process template files."""
+    results = []
+    for file_path in template_files:
+        content = file_path.read_text()
+        processed_content = process_template_content(content)
+        results.append(ProcessedFile(path=file_path, content=processed_content))
+    return results
+```
+
+### キャッシュ
+
+重い処理にはキャッシュを使います:
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=128)
+def get_template_metadata(template_path: Path) -> TemplateMetadata:
+    """Get template metadata with caching."""
+    config_file = template_path / "template.yaml"
+
+    if not config_file.exists():
+        return TemplateMetadata(name=template_path.name)
+
+    config = yaml.safe_load(config_file.read_text())
+    return TemplateMetadata.from_config(config)
+```
+
+## Git コミットガイドライン
+
+### コミットメッセージ形式
+
+Conventional Commits 形式を使います:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### コミット種別
+
+- **feat**: 新機能
+- **fix**: バグ修正
+- **docs**: ドキュメント変更
+- **style**: コードスタイル変更 (フォーマットなど)
+- **refactor**: リファクタリング
+- **test**: テストの追加 / 更新
+- **chore**: メンテナンス作業
+
+### 例
+
+```bash
+# 良い例 ✅
+feat(cli): add template validation command
+
+Add new command to validate template structure and configuration.
+The command checks for required files, validates YAML syntax,
+and ensures template follows conventions.
+
+Closes #123
+
+# 良い例 ✅
+fix(templates): handle missing dependency files gracefully
+
+When a template references a requirements file that doesn't exist,
+show a clear error message instead of crashing.
+
+# 悪い例 ❌
+update stuff
+
+# 悪い例 ❌
+Fixed bug
+```
+
+## コードレビューガイドライン
+
+### 著者向け
+
+レビュー依頼前に確認してほしいこと:
+
+1. **すべてのテストを実行** し、通過していることを確認
+2. **コードカバレッジ** が維持されているか確認
+3. 必要に応じて **ドキュメントを更新**
+4. **コミットメッセージ規約** に従う
+5. PR は **小さく、焦点を絞った形** で
+
+### レビュアー向け
+
+コードレビューの際の観点:
+
+1. **機能性** — 意図どおり動作するか?
+2. **テスト** — エッジケースまでカバーされているか?
+3. **ドキュメント** — 明快で最新か?
+4. **コードスタイル** — プロジェクト規約に従っているか?
+5. **セキュリティ** — 潜在的な脆弱性はないか?
+
+### レビューチェックリスト
+
+- [ ] コードがスタイルガイドラインに従っている
+- [ ] テストが十分で、すべて通過している
+- [ ] ドキュメントが更新されている
+- [ ] セキュリティ上の問題がない
+- [ ] パフォーマンス考慮がされている
+- [ ] エラーハンドリングが適切
+- [ ] コミットメッセージが規約に従っている
+
+## ツールと自動化
+
+### Pre-commit フック
+
+基準の徹底に pre-commit フックを使用します:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-toml
+
+-   repo: local
+    hooks:
+    -   id: format
+        name: format
+        entry: black --config pyproject.toml --check .
+        language: python
+        types: [python]
+        additional_dependencies: ['black>=24.10.0']
+        pass_filenames: false
+
+    -   id: isort-check
+        name: isort check
+        entry: isort --sp pyproject.toml --check-only --diff .
+        language: python
+        types: [python]
+        additional_dependencies: ['isort>=5.13.2']
+        pass_filenames: false
+
+    -   id: isort-fix
+        name: isort fix
+        entry: isort --sp pyproject.toml .
+        language: python
+        types: [python]
+        additional_dependencies: ['isort>=5.13.2']
+        pass_filenames: false
+
+    -   id: black-fix
+        name: black fix
+        entry: black --config pyproject.toml .
+        language: python
+        types: [python]
+        additional_dependencies: ['black>=24.10.0']
+        pass_filenames: false
+
+    -   id: mypy
+        name: mypy
+        entry: mypy --config-file pyproject.toml src
+        language: python
+        types: [python]
+        additional_dependencies:
+          - mypy>=1.12.0
+          - rich>=13.9.2
+          - click>=8.1.7
+          - pyyaml>=6.0.0
+          - types-PyYAML>=6.0.12
+        pass_filenames: false
+
+ci:
+    autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
+    autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate
+```
+
+!!! note
+
+    Pre-commit フックは隔離された Python 環境 (`language: python`) を使います。
+
+### IDE 設定
+
+VS Code の推奨設定:
+
+```json
+{
+    "python.linting.enabled": true,
+    "python.linting.mypyEnabled": true,
+    "python.formatting.provider": "black",
+    "python.sortImports.path": "isort",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+        "source.organizeImports": true
+    }
+}
+```
+
+## 次のステップ
+
+このガイドラインを把握したら:
+
+1. [開発環境セットアップ](development-setup.md) に従って **開発環境を構築**
+2. **小さな貢献から始めて** 慣れる
+3. 不明点があれば GitHub Discussions で **質問**
+4. ガイドラインの実例を確認するため **既存コードを読む**
+
+!!! tip "クイックリファレンス"
+    - `make check-all` でコードがガイドラインに準拠しているか検証
+    - 早期発見のため pre-commit フックをセットアップ
+    - 迷ったら既存コードを参照
+    - コードレビューでの質問もどうぞ気軽に
+
+これらのガイドラインに従うことで、FastAPI-fastkit の高いコード品質が保たれ、誰にとっても協働がしやすくなります! 🚀
diff --git a/docs/ja/contributing/development-setup.md b/docs/ja/contributing/development-setup.md
new file mode 100644
index 0000000..97f557b
--- /dev/null
+++ b/docs/ja/contributing/development-setup.md
@@ -0,0 +1,816 @@
+# 開発環境のセットアップ
+
+FastAPI-fastkit に貢献するための開発環境を整える包括的なガイドです。
+
+## 前提条件
+
+開始前に、次が用意されているか確認してください:
+
+- **Python 3.12 以上** がインストール済み
+- **Git** がインストールされ設定済み
+- **Python と FastAPI の基礎知識**
+- **テキストエディタまたは IDE** (VS Code、PyCharm など)
+
+## Makefile による簡単セットアップ
+
+FastAPI-fastkit には、開発環境を簡単に整えるための Makefile が用意されています:
+
+<div class="termy">
+
+```console
+$ git clone https://github.com/bnbong/FastAPI-fastkit.git
+$ cd FastAPI-fastkit
+$ make install-dev
+Setting up development environment...
+Creating virtual environment...
+Installing dependencies...
+Installing pre-commit hooks...
+✅ Development environment ready!
+```
+
+</div>
+
+このコマンド 1 つで:
+
+- パッケージを開発用依存関係込みの editable モードでインストール
+- pre-commit フックをセットアップ
+- 開発ツールを設定
+
+!!! note
+
+    このコマンドを実行する前に、仮想環境を作成して有効化しておくのが推奨です。
+
+## 手動セットアップ
+
+手動セットアップを好む場合、または Makefile が動作しない環境では:
+
+### 1. リポジトリをクローン
+
+<div class="termy">
+
+```console
+$ git clone https://github.com/bnbong/FastAPI-fastkit.git
+$ cd FastAPI-fastkit
+```
+
+</div>
+
+### 2. 仮想環境の作成
+
+<div class="termy">
+
+```console
+$ python -m venv .venv
+$ source .venv/bin/activate  # Windows の場合: .venv\Scripts\activate
+```
+
+</div>
+
+### 3. 依存関係のインストール
+
+<div class="termy">
+
+```console
+# editable モードで開発用依存も含めてインストール
+$ pip install -e ".[dev]"
+
+# あるいは requirements ファイルから
+$ pip install -r requirements.txt
+$ pip install -r requirements-dev.txt
+```
+
+</div>
+
+### 4. Pre-commit フックの設定
+
+<div class="termy">
+
+```console
+$ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```
+
+</div>
+
+### 5. インストールの確認
+
+<div class="termy">
+
+```console
+$ fastkit --version
+fastapi-fastkit, version 1.2.1
+
+$ python -m pytest tests/
+======================== test session starts ========================
+collected 45 items
+tests/test_cli.py::test_init_command PASSED
+tests/test_templates.py::test_template_listing PASSED
+...
+======================== 45 passed in 2.34s ========================
+```
+
+</div>
+
+## 開発ツール
+
+開発環境にはコード品質を保つためのツールが含まれます:
+
+### ワンライナーコマンド
+
+Makefile を使う:
+
+```console
+$ make format lint
+Running isort...
+Running black...
+Running mypy...
+✅ All checks passed!
+```
+
+付属のスクリプトを使う:
+
+```console
+$ ./scripts/format.sh
+$ ./scripts/lint.sh
+```
+
+### コードフォーマット
+
+**Black** — コードフォーマッタ:
+
+<div class="termy">
+
+```console
+$ black src/ tests/
+reformatted src/main.py
+reformatted tests/test_cli.py
+All done! ✨ 🍰 ✨
+```
+
+</div>
+
+**isort** — import ソーター:
+
+<div class="termy">
+
+```console
+$ isort src/ tests/
+Fixing import order in src/main.py
+```
+
+</div>
+
+### コードリンティング
+
+**mypy** — 型チェック:
+
+<div class="termy">
+
+```console
+$ mypy src/
+Success: no issues found in 12 source files
+```
+
+</div>
+
+## 利用できる Make コマンド
+
+プロジェクトの Makefile は、よくある開発作業に便利なコマンドを提供します:
+
+### セットアップコマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make install` | パッケージを本番モードでインストール |
+| `make install-dev` | 開発用依存関係込みでインストール |
+| `make install-test` | テスト用にインストール (アンインストール + 再インストール) |
+| `make uninstall` | パッケージをアンインストール |
+| `make clean` | ビルド成果物とキャッシュを削除 |
+
+### コード品質コマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make format` | black と isort でコードをフォーマット |
+| `make format-check` | 変更せずにフォーマットを確認 |
+| `make lint` | すべてのリンティング (isort、black、mypy) を実行 |
+
+### テストコマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make test` | すべてのテストを実行 |
+| `make test-verbose` | 詳細出力付きでテスト実行 |
+| `make test-coverage` | カバレッジレポート付きでテスト実行 |
+| `make coverage-report` | 詳細なカバレッジレポートを生成 (FORMAT=html/xml/json/all) |
+
+### テンプレート検査コマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make inspect-templates` | すべてのテンプレートを検査 |
+| `make inspect-templates-verbose` | 詳細出力付きで検査 |
+| `make inspect-template` | 特定のテンプレートを検査 (TEMPLATES パラメータ) |
+
+### ドキュメントコマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make serve-docs` | ドキュメントをローカルで配信 |
+| `make build-docs` | ドキュメントをビルド |
+
+### 翻訳コマンド
+
+| コマンド | 説明 |
+|---|---|
+| `make translate` | ドキュメントを翻訳 (LANG、PROVIDER、MODEL パラメータ) |
+
+### 例
+
+<div class="termy">
+
+```console
+# コードをフォーマットしてすべてのチェックを実行
+$ make format lint
+Running isort...
+Running black...
+Running mypy...
+✅ All checks passed!
+
+# カバレッジ付きでテスト実行
+$ make test-coverage
+======================== test session starts ========================
+collected 45 items
+tests/test_cli.py::test_init_command PASSED
+...
+======================== 45 passed in 2.34s ========================
+
+---------- coverage: platform darwin, python 3.12.1-final-0 ----------
+Name                     Stmts   Miss  Cover
+--------------------------------------------
+src/main.py                 45      2    96%
+src/cli.py                  89      5    94%
+src/templates.py            67      3    96%
+--------------------------------------------
+TOTAL                      201     10    95%
+
+# HTML カバレッジレポートを生成
+$ make coverage-report FORMAT=html
+🌐 Opening HTML coverage report in browser...
+
+# ドキュメントを韓国語へ翻訳
+$ make translate LANG=ko PROVIDER=github MODEL=gpt-4o-mini
+Starting translation...
+Running: python scripts/translate.py --target-lang ko --api-provider github --model gpt-4o-mini
+```
+
+</div>
+
+## プロジェクト構造
+
+開発の前にプロジェクト構造を理解しておきましょう:
+
+```bash
+FastAPI-fastkit/
+├── src/
+│   ├── fastapi_fastkit/
+│   │   ├── __main__.py                      # アプリのエントリポイント
+│   │   ├── backend/
+│   │   │   ├── inspector.py                 # FastAPI-fastkit テンプレートインスペクタ
+│   │   │   ├── interactive/
+│   │   │   │   ├── config_builder.py        # 対話型モードの設定ビルダー
+│   │   │   │   ├── prompts.py               # 対話型モードのプロンプト
+│   │   │   │   ├── selectors.py             # 対話型モードのセレクタ
+│   │   │   │   └── validators.py            # 対話型モードの入力バリデータ
+│   │   │   ├── main.py                      # バックエンドのロジックエントリポイント
+│   │   │   ├── package_managers/
+│   │   │   │   ├── base.py                  # パッケージマネージャーのベースクラス
+│   │   │   │   ├── factory.py               # パッケージマネージャーファクトリ
+│   │   │   │   ├── pdm_manager.py           # PDM パッケージマネージャー
+│   │   │   │   ├── pip_manager.py           # pip パッケージマネージャー
+│   │   │   │   ├── poetry_manager.py        # Poetry パッケージマネージャー
+│   │   │   │   └── uv_manager.py            # uv パッケージマネージャー
+│   │   │   ├── project_builder/
+│   │   │   │   ├── config_generator.py      # 設定ジェネレータ
+│   │   │   │   └── dependency_collector.py  # 依存関係収集
+│   │   │   └── transducer.py                # プロジェクトビルダー用トランスデューサ
+│   │   ├── cli.py                           # FastAPI-fastkit のメイン CLI エントリポイント
+│   │   ├── core/
+│   │   │   ├── exceptions.py                # 例外処理
+│   │   │   └── settings.py                  # 設定
+│   │   ├── fastapi_project_template/
+│   │   │   ├── PROJECT_README_TEMPLATE.md   # fastkit テンプレート用 README ベース
+│   │   │   ├── README.md                    # fastkit テンプレートの README
+│   │   │   ├── fastapi-async-crud/
+│   │   │   ├── fastapi-custom-response/
+│   │   │   ├── fastapi-default/
+│   │   │   ├── fastapi-dockerized/
+│   │   │   ├── fastapi-empty/
+│   │   │   ├── fastapi-mcp/
+│   │   │   ├── fastapi-psql-orm/
+│   │   │   ├── fastapi-single-module/
+│   │   │   └── modules/
+│   │   │       ├── api/
+│   │   │       │   └── routes/
+│   │   │       ├── crud/
+│   │   │       └── schemas/
+│   │   ├── py.typed
+│   │   └── utils/
+│   │       ├── logging.py                   # ロギング設定
+│   │       └── main.py                      # FastAPI-fastkit のメインエントリポイント
+│   └── logs
+├── tests
+│   ├── conftest.py                          # pytest 設定
+│   ├── test_backends/
+│   ├── test_cli_operations/
+│   ├── test_core.py
+│   ├── test_rich/
+│   ├── test_templates/
+│   └── test_utils.py
+├── uv.lock
+├── docs/                                    # ドキュメント
+├── scripts/                                 # 開発スクリプト
+├── mkdocs.yml
+├── overrides/                               # mkdocs オーバーライド
+├── pdm.lock
+├── pyproject.toml
+├── requirements-docs.txt                    # ドキュメント用依存
+├── requirements.txt                         # 開発用依存
+├── CHANGELOG.md
+├── CITATION.cff
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── MANIFEST.in
+├── Makefile
+├── README.md
+├── SECURITY.md
+└── env.example                              # 環境変数の例 (翻訳用 AI モデルの env を構成)
+```
+
+### 主要ディレクトリ
+
+- **`src/fastapi_fastkit/`** — メインパッケージのソース
+    - **`cli.py`** — メイン CLI のエントリポイント
+    - **`backend/`** — コアのバックエンドロジック
+        - **`inspector.py`** — テンプレートインスペクタ
+        - **`interactive/`** — 対話型モードの構成要素 (プロンプト、セレクタ、バリデータ)
+        - **`package_managers/`** — パッケージマネージャー実装 (pip、uv、pdm、poetry)
+        - **`project_builder/`** — プロジェクト構築ユーティリティ
+        - **`transducer.py`** — テンプレートトランスデューサ
+    - **`core/`** — コアの設定と例外
+    - **`fastapi_project_template/`** — プロジェクトテンプレート (fastapi-default、fastapi-async-crud など)
+    - **`utils/`** — 共有ユーティリティ
+- **`tests/`** — テストスイート
+    - **`test_backends/`** — バックエンド固有のテスト
+    - **`test_cli_operations/`** — CLI 操作のテスト
+    - **`test_templates/`** — テンプレートシステムのテスト
+- **`docs/`** — ドキュメント (MkDocs)
+    - ユーザーガイド、チュートリアル、API リファレンス
+
+## 開発ワークフロー
+
+### 1. 機能ブランチを作成
+
+<div class="termy">
+
+```console
+$ git checkout -b feature/add-new-template
+Switched to a new branch 'feature/add-new-template'
+```
+
+</div>
+
+### 2. 変更を実装
+
+コードを編集し、機能を追加・バグを修正します...
+
+### 3. テストとチェックを実行
+
+<div class="termy">
+
+```console
+$ make dev-check
+Running all quality checks...
+Running all tests...
+✅ All tests passed!
+```
+
+</div>
+
+### 4. 変更をコミット
+
+pre-commit フックが自動的に実行されます:
+
+<div class="termy">
+
+```console
+$ git add .
+$ git commit -m "Add new FastAPI template with authentication"
+format...................................................................Passed
+isort-check..............................................................Passed
+black-fix................................................................Passed
+mypy.....................................................................Passed
+[feature/add-new-template abc1234] Add new FastAPI template with authentication
+```
+
+</div>
+
+### 5. push して PR を作成する
+
+<div class="termy">
+
+```console
+$ git push origin feature/add-new-template
+$ gh pr create --title "Add new FastAPI template with authentication"
+```
+
+</div>
+
+## テスト
+
+### テストの実行
+
+**すべてのテスト:**
+
+<div class="termy">
+
+```console
+$ make test
+# または
+$ python -m pytest
+```
+
+</div>
+
+**特定のテストファイル:**
+
+<div class="termy">
+
+```console
+$ python -m pytest tests/test_cli.py -v
+```
+
+</div>
+
+**カバレッジ付き:**
+
+<div class="termy">
+
+```console
+$ make test-coverage
+# または
+$ python -m pytest --cov=src --cov-report=html
+```
+
+</div>
+
+### テストの書き方
+
+新機能を追加する際は、必ずテストも含めてください:
+
+```python
+# tests/test_commands/test_new_feature.py
+import pytest
+from fastapi_fastkit.commands.new_feature import NewFeatureCommand
+
+class TestNewFeatureCommand:
+    def test_command_success(self):
+        """Test successful command execution"""
+        command = NewFeatureCommand()
+        result = command.execute(valid_args)
+        assert result.success is True
+        assert result.message == "Feature executed successfully"
+
+    def test_command_validation_error(self):
+        """Test command with invalid arguments"""
+        command = NewFeatureCommand()
+        with pytest.raises(ValueError, match="Invalid argument"):
+            command.execute(invalid_args)
+
+    def test_command_edge_case(self):
+        """Test edge case handling"""
+        command = NewFeatureCommand()
+        result = command.execute(edge_case_args)
+        assert result.success is True
+        assert "warning" in result.message.lower()
+```
+
+### テストの種類
+
+**単体テスト** — 個別の関数やクラスをテスト:
+
+```python
+def test_validate_project_name():
+    assert validate_project_name("valid-name") is True
+    assert validate_project_name("invalid name!") is False
+```
+
+**統合テスト** — コマンドの相互作用をテスト:
+
+```python
+def test_init_command_creates_project(tmp_path):
+    result = runner.invoke(cli, ['init'], input='test-project\n...')
+    assert result.exit_code == 0
+    assert (tmp_path / "test-project").exists()
+```
+
+**エンドツーエンドテスト** — 完全なワークフローをテスト:
+
+```python
+def test_full_project_creation_workflow(tmp_path):
+    # プロジェクトを作成
+    result = runner.invoke(cli, ['init'], input='...')
+    assert result.exit_code == 0
+
+    # ルートを追加
+    result = runner.invoke(cli, ['addroute', 'test-project', 'users'])
+    assert result.exit_code == 0
+
+    # ファイルが存在することを検証
+    assert (tmp_path / "test-project" / "src" / "api" / "routes" / "users.py").exists()
+```
+
+## ドキュメント
+
+### ドキュメントをローカルで配信
+
+<div class="termy">
+
+```console
+$ make serve-docs
+INFO     -  Building documentation...
+INFO     -  Cleaning site directory
+INFO     -  Documentation built in 0.43 seconds
+INFO     -  [14:30:00] Serving on http://127.0.0.1:8000/
+```
+
+</div>
+
+### ドキュメントのビルド
+
+<div class="termy">
+
+```console
+$ make build-docs
+INFO     -  Building documentation...
+INFO     -  Documentation built in 0.43 seconds
+```
+
+</div>
+
+### ドキュメントの書き方
+
+ドキュメントは Markdown で書かれ、MkDocs でビルドされます。例の構造:
+
+**機能ガイドのテンプレート:**
+
+````markdown
+# New Feature Guide
+
+This guide explains how to use the new feature.
+
+## Prerequisites
+
+- FastAPI-fastkit installed
+- Basic Python knowledge
+
+## Usage
+
+<div class="termy">
+
+```console
+$ fastkit new-feature --option value
+✅ Feature executed successfully!
+```
+
+</div>
+
+!!! tip "Pro Tip"
+    Use `--help` to see all available options.
+````
+
+`mkdocs-material` の詳しい使い方は、[mkdocs-material のドキュメント](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) を参照してください。
+
+## コードスタイルガイドライン
+
+### Python のコードスタイル
+
+[PEP 8](https://www.python.org/dev/peps/pep-0008/) に従い、次の固有ルールを採用:
+
+- **行長**: 88 文字 (Black デフォルト)
+- **import**: isort で整理
+- **型ヒント**: すべての公開関数で必須
+- **docstring**: すべての公開 API で Google スタイル
+
+### 例
+
+```python
+from typing import List, Optional
+from pathlib import Path
+
+def create_project_structure(
+    project_name: str,
+    template_path: Path,
+    output_dir: Optional[Path] = None,
+) -> List[Path]:
+    """Create project structure from template.
+
+    Args:
+        project_name: Name of the project to create
+        template_path: Path to the template directory
+        output_dir: Output directory, defaults to current directory
+
+    Returns:
+        List of created file paths
+
+    Raises:
+        ValueError: If project_name is invalid
+        FileNotFoundError: If template_path doesn't exist
+    """
+    if not project_name.isidentifier():
+        raise ValueError(f"Invalid project name: {project_name}")
+
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_path}")
+
+    # 実装 ...
+    return created_files
+```
+
+## 環境変数
+
+開発時には次の環境変数を設定できます:
+
+| 変数 | 説明 | デフォルト |
+|---|---|---|
+| `FASTKIT_DEBUG` | デバッグログを有効化 | `False` |
+| `FASTKIT_DEV_MODE` | 開発機能を有効化 | `False` |
+| `FASTKIT_TEMPLATE_DIR` | カスタムテンプレートディレクトリ | 組み込みテンプレート |
+| `FASTKIT_CONFIG_DIR` | 設定ディレクトリ | `~/.fastkit` |
+| `TRANSLATION_API_KEY` | 翻訳 API キー ([Github AI モデルプロバイダ](https://github.com/marketplace/models/azure-openai) を使う場合は GitHub PAT を指定) | `None` |
+
+<div class="termy">
+
+```console
+$ export FASTKIT_DEBUG=true
+$ export FASTKIT_DEV_MODE=true
+$ fastkit init
+DEBUG: Loading configuration from /home/user/.fastkit/
+DEBUG: Available templates: ['fastapi-default', ...]
+```
+
+</div>
+
+ほかの環境変数設定については、[@settings.py](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/core/settings.py) モジュールを参照してください。
+
+## トラブルシューティング
+
+### よくある問題
+
+**1. pre-commit フックが失敗する:**
+
+<div class="termy">
+
+```console
+$ git commit -m "Fix bug"
+black....................................................................Failed
+hookid: black
+
+Files were modified by this hook. Additional output:
+
+would reformat src/cli.py
+```
+
+</div>
+
+**解決策:** フォーマッタを実行し、再度コミット:
+
+<div class="termy">
+
+```console
+$ make format
+$ git add .
+$ git commit -m "Fix bug"
+```
+
+</div>
+
+**2. 異なる Python バージョンでテストが失敗する:**
+
+**解決策:** tox で複数の Python バージョンをテスト:
+
+<div class="termy">
+
+```console
+$ pip install tox
+$ tox
+py38: commands succeeded
+py39: commands succeeded
+py310: commands succeeded
+py311: commands succeeded
+py312: commands succeeded
+```
+
+</div>
+
+**3. 開発時の import エラー:**
+
+**解決策:** editable モードでインストール:
+<div class="termy">
+
+```console
+$ pip install -e .
+```
+
+</div>
+
+### ヘルプ
+
+- **[GitHub Issues](https://github.com/bnbong/FastAPI-fastkit/issues)**: バグ報告と機能リクエスト
+- **[GitHub Discussions](https://github.com/bnbong/FastAPI-fastkit/discussions)**: 質問とアイデア共有
+- **ドキュメント**: [ユーザーガイド](../user-guide/installation.md) を参照
+
+## コントリビュートガイドライン
+
+### PR 提出前
+
+1. **すべてのチェックを実行:** `make dev-check`
+2. 必要に応じて **ドキュメントを更新**
+3. 新機能には **テストを追加**
+4. **コミットメッセージ規約に従う**
+
+### コミットメッセージ形式
+
+```
+type(scope): brief description
+
+Longer description if needed
+
+Fixes #123
+```
+
+**種別:**
+
+- `feat`: 新機能
+- `fix`: バグ修正
+- `docs`: ドキュメント変更
+- `style`: コードスタイル変更
+- `refactor`: リファクタリング
+- `test`: テストの追加・変更
+- `chore`: メンテナンス作業
+
+**例:**
+
+```
+feat(cli): add new template command
+
+Add support for creating projects from custom templates.
+The command accepts a template path and creates a new
+project with the specified configuration.
+
+Fixes #45
+
+fix(templates): handle missing template files gracefully
+
+When a template file is missing, show a clear error message
+instead of crashing with a stack trace.
+
+Fixes #67
+```
+
+## リリースプロセス
+
+メンテナー向けのリリース手順:
+
+1. `setup.py` と `__init__.py` で **バージョンを更新**
+2. **CHANGELOG.md を更新**
+3. **リリース PR を作成**
+4. マージ後に **タグを付与**
+5. **GitHub Actions** が自動でビルドおよび公開
+
+<div class="termy">
+
+```console
+$ git tag v1.2.0
+$ git push origin v1.2.0
+```
+
+</div>
+
+## 次のステップ
+
+開発環境が整ったら:
+
+1. アーキテクチャを把握するため [**コードベースを探索**](https://github.com/bnbong/FastAPI-fastkit/tree/main/src/fastapi_fastkit) する
+2. **テストスイートを実行** してすべて動作することを確認
+3. GitHub から取り組む [**Issue**](https://github.com/bnbong/FastAPI-fastkit/issues) を選ぶ
+4. ほかの貢献者とつながるため [**Discussions**](https://github.com/bnbong/FastAPI-fastkit/discussions) に参加
+
+Happy coding! 🚀
+
+!!! tip "開発のヒント"
+    - コミット前に `make dev-check` を実行
+    - テストを先に書く (TDD アプローチ)
+    - コミットは小さく、焦点を絞る
+    - 新機能には合わせてドキュメントを更新
diff --git a/docs/ja/contributing/template-creation-guide.md b/docs/ja/contributing/template-creation-guide.md
new file mode 100644
index 0000000..b39b641
--- /dev/null
+++ b/docs/ja/contributing/template-creation-guide.md
@@ -0,0 +1,576 @@
+# FastAPI テンプレート作成ガイド
+
+FastAPI-fastkit に新しい FastAPI プロジェクトテンプレートを追加するための包括的なガイドです。
+
+## 🎯 概要
+
+新しいテンプレートの追加は、次の 5 ステップで進めます:
+
+1. **📋 計画と設計** — テンプレートの目的と構成を定義
+2. **🏗️ テンプレートの実装** — 必要な構造とファイルを作成
+3. **🔍 ローカル検証** — インスペクタでテンプレートを検証
+4. **📚 ドキュメント** — README と利用ガイドを記述
+5. **🚀 提出とレビュー** — PR を作成しコミュニティのレビューを受ける
+
+## 📋 ステップ 1: 計画と設計
+
+### テンプレートの目的を定義する
+
+新しいテンプレートを作る前に、次の問いに答えてください:
+
+- **このテンプレート固有の価値は何か?**
+- **既存のテンプレートとどう差別化されるか?**
+- **どのユーザー層が想定読者か?**
+- **どんな技術スタックを含めるか?**
+
+### テンプレートの命名規則
+
+```
+fastapi-{purpose}-{stack}
+```
+
+例:
+
+- `fastapi-microservice` (マイクロサービステンプレート)
+- `fastapi-graphql` (GraphQL 統合テンプレート)
+- `fastapi-auth-jwt` (JWT 認証テンプレート)
+
+### 技術スタックの計画
+
+含めるメイン技術を事前に定義します:
+
+```yaml
+# 例: fastapi-microservice テンプレート
+core_dependencies:
+  - fastapi
+  - uvicorn
+  - pydantic
+  - pydantic-settings
+
+additional_features:
+  - sqlalchemy (ORM)
+  - alembic (マイグレーション)
+  - redis (キャッシュ)
+  - celery (バックグラウンドタスク)
+  - pytest (テスト)
+
+development_tools:
+  - black (コードフォーマット)
+  - isort (import ソート)
+  - mypy (型チェック)
+  - pre-commit (Git フック)
+```
+
+## 🏗️ ステップ 2: テンプレートの実装
+
+### 必須ディレクトリ構造
+
+```
+fastapi-{template-name}/
+├── src/                          # アプリケーションのソース
+│   ├── main.py-tpl              # ✅ FastAPI アプリのエントリポイント (必須)
+│   ├── __init__.py-tpl
+│   ├── api/                     # API ルーター
+│   │   ├── __init__.py-tpl
+│   │   ├── api.py-tpl           # メインの API ルーター
+│   │   └── routes/              # 個別ルート
+│   │       ├── __init__.py-tpl
+│   │       └── items.py-tpl     # サンプルルート
+│   ├── core/                    # コア設定
+│   │   ├── __init__.py-tpl
+│   │   └── config.py-tpl        # 設定管理
+│   ├── crud/                    # CRUD ロジック
+│   │   ├── __init__.py-tpl
+│   │   └── items.py-tpl
+│   ├── schemas/                 # Pydantic モデル
+│   │   ├── __init__.py-tpl
+│   │   └── items.py-tpl
+│   └── utils/                   # ユーティリティ
+│       ├── __init__.py-tpl
+│       └── helpers.py-tpl
+├── tests/                       # ✅ テスト (必須)
+│   ├── __init__.py-tpl
+│   ├── conftest.py-tpl         # pytest 設定
+│   └── test_items.py-tpl       # サンプルテスト
+├── scripts/                     # スクリプト
+│   ├── format.sh-tpl           # コードフォーマット
+│   ├── lint.sh-tpl             # リンティング
+│   ├── run-server.sh-tpl       # サーバー起動
+│   └── test.sh-tpl             # テスト実行
+├── pyproject.toml-tpl           # ✅ 一次メタデータ (PEP 621、推奨)
+├── setup.py-tpl                # 🟡 レガシーメタデータ (互換のため受け付け)
+├── requirements.txt-tpl         # 🟡 pyproject が依存関係を宣言する場合は任意
+├── setup.cfg-tpl               # 開発ツール設定
+├── README.md-tpl               # ✅ プロジェクトドキュメント (必須)
+├── .env-tpl                    # 環境変数テンプレート
+└── .gitignore-tpl              # Git ignore ファイル
+```
+
+**最低限必要なファイル。** テンプレートは次を提供する必要があります:
+
+- `tests/` ディレクトリ
+- `README.md-tpl`
+- 少なくとも 1 つのメタデータファイル: `pyproject.toml-tpl` (推奨、PEP 621) または `setup.py-tpl` (レガシー、引き続き受け付け)
+- 次のいずれかに `fastapi` を依存関係として宣言: `pyproject.toml-tpl` の `[project].dependencies`、`requirements.txt-tpl`、または `setup.py-tpl` の `install_requires`
+
+`requirements.txt-tpl` は、`pyproject.toml-tpl` が `[project].dependencies` を宣言している場合は厳密には不要です。新しいテンプレートは **`pyproject.toml-tpl` を一次メタデータファイルとして採用すべきです**。
+
+### ファイル作成ガイド
+
+#### 1. main.py-tpl の書き方
+
+```python
+"""
+FastAPI アプリのエントリポイント
+
+このファイルは、FastAPI-fastkit で作成された <project_name> プロジェクトの
+メインアプリケーションです。
+"""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from api.api import api_router
+from core.config import settings
+
+# FastAPI アプリを作成 (インスペクタの検証で必須)
+app = FastAPI(
+    title="<project_name>",
+    description="Project created with FastAPI-fastkit",
+    version="1.0.0",
+)
+
+# CORS ミドルウェア設定
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# API ルーターを登録
+app.include_router(api_router, prefix="/api/v1")
+
+@app.get("/")
+async def root():
+    """ルートエンドポイント"""
+    return {"message": "Hello from <project_name>!"}
+
+@app.get("/health")
+async def health_check():
+    """ヘルスチェックエンドポイント"""
+    return {"status": "healthy"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+#### 2. pyproject.toml-tpl の書き方 (推奨)
+
+新しいテンプレートは PEP 621 形式の `pyproject.toml-tpl` でメタデータと依存関係を宣言すべきです。最低限、`[project]` セクションに `name`、`version`、`description`、そして `fastapi` を含む `dependencies` リストを公開してください。テンプレートは、`is_fastkit_project()` がユーザーのワークスペース内の無関係な FastAPI プロジェクトと区別できるよう、FastAPI-fastkit の識別マーカーを 2 つ持つ必要があります:
+
+- `description` の `[FastAPI-fastkit templated]` 接頭辞
+- `managed = true` を持つ専用の `[tool.fastapi-fastkit]` テーブル
+
+検出はどちらかのマーカーがあれば成功します (大文字小文字は区別しません)。テンプレートが省略していてもプロジェクト生成時にメタデータ注入が両方を追加しますが、作者は明示的に含めるべきです。
+
+```toml
+[project]
+name = "<project_name>"
+version = "0.1.0"
+description = "[FastAPI-fastkit templated] <description>"
+authors = [
+    {name = "<author>", email = "<author_email>"},
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.7.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "httpx>=0.28.0",
+]
+
+[tool.fastapi-fastkit]
+managed = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+#### 3. requirements.txt-tpl の書き方 (任意)
+
+`pyproject.toml-tpl` が `[project].dependencies` を宣言している場合は任意です。`pip` 中心のワークフローを好むテンプレートでは引き続き有用です。
+
+```txt
+# FastAPI コア依存 (必須)
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+
+# データ検証
+pydantic==2.5.0
+pydantic-settings==2.1.0
+
+# 環境変数管理
+python-dotenv==1.0.0
+
+# データベース (必要な場合)
+sqlalchemy==2.0.23
+alembic==1.13.0
+
+# 開発ツール
+pytest==7.4.3
+pytest-asyncio==0.21.1
+httpx==0.25.2
+
+# コード品質
+black==23.11.0
+isort==5.12.0
+mypy==1.7.1
+```
+
+#### 4. setup.py-tpl の書き方 (レガシー — pyproject がある場合は任意)
+
+レガシーテンプレートのために残されています。`pyproject.toml-tpl` を提供する新規テンプレートでは、このファイルは不要です。
+
+```python
+"""
+<project_name> パッケージのセットアップ
+
+FastAPI-fastkit で作成されたプロジェクトです。
+"""
+from setuptools import find_packages, setup
+
+# 依存関係リスト (型注釈が必要)
+install_requires: list[str] = [
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+    "python-dotenv>=1.0.0",
+]
+
+setup(
+    name="<project_name>",
+    version="1.0.0",
+    description="[FastAPI-fastkit templated] <description>",  # is_fastkit_project() が利用する識別マーカー
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="<author>",
+    author_email="<author_email>",
+    packages=find_packages(),
+    install_requires=install_requires,
+    python_requires=">=3.8",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+)
+```
+
+#### 5. テストファイルの書き方
+
+```python
+# tests/test_items.py-tpl
+"""
+Items API テストモジュール
+"""
+import pytest
+from fastapi.testclient import TestClient
+from main import app
+
+client = TestClient(app)
+
+def test_read_root():
+    """ルートエンドポイントのテスト"""
+    response = client.get("/")
+    assert response.status_code == 200
+    assert "message" in response.json()
+
+def test_health_check():
+    """ヘルスチェックのテスト"""
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "healthy"}
+
+def test_create_item():
+    """item 作成のテスト"""
+    item_data = {
+        "name": "Test Item",
+        "description": "Test Description"
+    }
+    response = client.post("/api/v1/items/", json=item_data)
+    assert response.status_code == 200
+    data = response.json()
+    assert data["name"] == item_data["name"]
+    assert data["description"] == item_data["description"]
+
+def test_read_items():
+    """item 一覧取得のテスト"""
+    response = client.get("/api/v1/items/")
+    assert response.status_code == 200
+    assert isinstance(response.json(), list)
+```
+
+## 🔍 ステップ 3: ローカル検証
+
+### 自動検証スクリプトの実行
+
+新しいテンプレートが準備できたら、次のコマンドで検証します:
+
+```bash
+# すべてのテンプレートを検証
+make inspect-templates
+
+# 特定のテンプレートだけ検証
+make inspect-template TEMPLATES="fastapi-your-template"
+
+# 詳細出力付きで検証
+python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose
+```
+
+!!! note
+
+    PR を提出すると、**Template PR Inspection** ワークフローが自動的に走り、テンプレート変更を検証します。フィードバックは PR に直接届きます。
+
+### 検証チェックリスト
+
+インスペクタが自動で確認する項目です:
+
+#### ✅ ファイル構造の検証
+
+- [ ] `tests/` ディレクトリが存在
+- [ ] `README.md-tpl` ファイルが存在
+- [ ] `pyproject.toml-tpl` (推奨) または `setup.py-tpl` (レガシー) のいずれかが存在
+
+#### ✅ 拡張子の検証
+
+- [ ] すべての Python ファイルが `.py-tpl` 拡張子
+- [ ] `.py` 拡張子のファイルが存在しない
+
+#### ✅ 依存関係の検証
+
+- [ ] 次のいずれかに `fastapi` が宣言されている:
+    - [ ] `pyproject.toml-tpl` の `[project].dependencies` (推奨)
+    - [ ] `requirements.txt-tpl`
+    - [ ] `setup.py-tpl` の `install_requires`
+
+#### ✅ FastAPI 実装の検証
+
+- [ ] `main.py-tpl` に `FastAPI` import がある
+- [ ] `main.py-tpl` に `app = FastAPI()` のようなアプリ生成がある
+
+#### ✅ テスト実行の検証
+
+- [ ] 仮想環境の作成に成功
+- [ ] 依存関係のインストールに成功
+- [ ] すべての pytest テストが通過
+
+#### ✅ 自動テンプレートテスト
+
+FastAPI-fastkit には、すべてのテンプレートで包括的テストを走らせる **自動テンプレートテスト** が含まれます:
+
+**テストカバレッジ:**
+
+- ✅ テンプレート生成プロセス
+- ✅ プロジェクトメタデータの注入
+- ✅ 仮想環境のセットアップ
+- ✅ 依存関係のインストール (すべてのパッケージマネージャー)
+- ✅ 基本的なプロジェクト構造の検証
+- ✅ FastAPI プロジェクトの識別
+
+**テストの実行:**
+```console
+# すべてのテンプレートを自動テスト
+$ pytest tests/test_templates/test_all_templates.py -v
+
+# 特定のテンプレートをテスト
+$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
+```
+
+**テンプレートテストの自動検出:**
+新しいテンプレートは **設定なしで自動検出** されてテストされます:
+
+1. ✅ **設定不要**: テンプレートを追加 → 自動でテスト
+2. ✅ **一貫したテスト**: すべてのテンプレートに同じ品質基準
+3. ✅ **複数のパッケージマネージャー**: UV、PDM、Poetry、PIP でテスト
+4. ✅ **包括的な検証**: 構造、メタデータ、機能のチェック
+
+**これがあなたにとって意味すること:**
+
+- 🚀 **`FastAPI-fastkit` 本体側にテストファイルを追加する必要なし**: テンプレートは自動でテストされます
+- ⚡ **開発の高速化**: テンプレート内容に集中、テストのお膳立て不要
+- 🛡️ **品質保証**: すべてのテンプレートで一貫したテスト
+- 🔄 **CI/CD 連携**: PR で自動的にテスト
+
+**手動テストもまだ必要なケース:**
+
+- 🧪 **テンプレート固有の機能**: ビジネスロジックや独自機能
+- 🔧 **統合テスト**: 外部サービスや複雑なワークフロー
+- 📱 **エンドツーエンドシナリオ**: ユーザーワークフロー全体
+
+**テストのベストプラクティス:**
+```console
+# 1. テンプレートをローカルでテスト
+$ fastkit startdemo your-template-name
+
+# 2. 自動テストを実行
+$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
+
+# 3. 異なるパッケージマネージャーでテスト
+$ fastkit startdemo your-template-name --package-manager poetry
+$ fastkit startdemo your-template-name --package-manager pdm
+$ fastkit startdemo your-template-name --package-manager uv
+```
+
+### 手動検証チェックリスト
+
+自動検証に加えて、次の項目を手動でチェックしてください:
+
+#### 🔧 コード品質
+
+- [ ] PEP 8 スタイルガイドに従っている
+- [ ] 適切な型ヒントを使用
+- [ ] 意味のある変数名・関数名
+- [ ] 適切なコメントと docstring
+
+#### 🏗️ アーキテクチャ
+
+- [ ] 関心事の分離 (API、ビジネスロジック、データアクセス)
+- [ ] 再利用可能なコンポーネント設計
+- [ ] 拡張可能な構造
+- [ ] セキュリティのベストプラクティス適用
+
+#### 📚 ドキュメント
+
+- [ ] README.md-tpl が PROJECT_README_TEMPLATE.md の形式に従っている
+- [ ] インストール / 実行方法が明記されている
+- [ ] API ドキュメント (OpenAPI/Swagger)
+- [ ] 環境変数の説明
+
+## 📚 ステップ 4: ドキュメント
+
+### README.md-tpl の作成
+
+[PROJECT_README_TEMPLATE.md](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/PROJECT_README_TEMPLATE.md) のガイドに沿って書いてください。
+
+### テンプレート説明ドキュメントの作成
+
+新しいテンプレートの説明を `src/fastapi_fastkit/fastapi_project_template/README.md` に追加します:
+
+```markdown
+## fastapi-your-template
+
+新しいテンプレートの簡単な説明とユースケースをここに書きます。
+
+### 機能:
+- 機能 1
+- 機能 2
+- 機能 3
+
+### ユースケース:
+- ユースケース 1
+- ユースケース 2
+```
+
+## 🚀 ステップ 5: 提出とレビュー
+
+### PR 作成前のチェックリスト
+
+- [ ] すべての自動検証が通過 (`make inspect-templates`)
+- [ ] コードフォーマット完了 (`make format`)
+- [ ] リンティングチェック通過 (`make lint`)
+- [ ] すべてのテスト通過 (`make test`)
+- [ ] ドキュメント完成
+- [ ] CONTRIBUTING.md ガイドラインに準拠
+
+### PR タイトルと説明
+
+```
+[TEMPLATE] Add fastapi-{template-name} template
+
+## Overview
+Adds a new {purpose} template.
+
+## Key Features
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Validation Results
+- [ ] Inspector validation passed
+- [ ] All tests passed
+- [ ] Documentation completed
+
+## Usage Example
+\```bash
+fastkit startdemo
+# Select template: fastapi-{template-name}
+\```
+
+## Related Issues
+Closes #issue-number
+```
+
+### レビュープロセス
+
+1. **自動検証**: GitHub Actions がテンプレートを自動検証します
+    - **Template PR Inspection**: テンプレートを変更する PR で `inspect-changed-templates.py` を実行
+    - **週次検査**: 毎週水曜日にテンプレート全体を検証
+2. **コードレビュー**: メンテナーとコミュニティがコードをレビュー
+3. **テスト**: テンプレートをさまざまな環境でテスト
+4. **ドキュメントレビュー**: ドキュメントの正確性と完全性を確認
+5. **承認とマージ**: すべての要件が満たされたら main ブランチへマージ
+
+!!! note
+
+    検証結果は PR に自動コメントとして届きます。レビュー依頼前に必ず確認してください!
+
+## 🎯 ベストプラクティス
+
+### セキュリティの考慮
+
+- 機密情報は環境変数で管理
+- 適切な CORS 設定
+- 入力データの検証
+- SQL インジェクション対策
+
+### パフォーマンス最適化
+
+- 非同期処理を活用
+- データベースクエリの最適化
+- 適切なキャッシュ戦略
+- レスポンス圧縮の設定
+
+### 保守性
+
+- 明快なコード構造
+- 包括的なテストカバレッジ
+- 詳細なドキュメント
+- ロギングとモニタリングのセットアップ
+
+## 🆘 ヘルプが必要な場合
+
+- 📖 [開発環境セットアップガイド](development-setup.md)
+- 📋 [コードガイドライン](code-guidelines.md)
+- 💬 [GitHub Discussions](https://github.com/bnbong/FastAPI-fastkit/discussions)
+- 📧 [メンテナーへ連絡](mailto:bbbong9@gmail.com)
+
+新しいテンプレートの追加は FastAPI-fastkit コミュニティへの大きな貢献です。
+あなたのアイデアと努力が、ほかの開発者にとって大きな助けになります! 🚀
diff --git a/docs/ja/contributing/translation-guide.md b/docs/ja/contributing/translation-guide.md
new file mode 100644
index 0000000..1ca60df
--- /dev/null
+++ b/docs/ja/contributing/translation-guide.md
@@ -0,0 +1,367 @@
+# 翻訳ガイド
+
+このガイドでは、FastAPI-fastkit ドキュメントの翻訳に貢献する方法を説明します。
+
+## 原典と翻訳ポリシー
+
+> **英語 (`en`) が FastAPI-fastkit ドキュメントの基準となる原文** です。それ以外のロケールは翻訳対象であり、リリース単位またはページ単位で英語より遅れる可能性があります。
+>
+> 翻訳されたページが英語ページと食い違う場合は、翻訳が追いつくまで **英語ページを信頼してください**。翻訳は貢献者が到達した範囲でそのまま提供されます — 部分的なカバレッジは通常の状態です。
+
+このポリシーに対応するユーザー向けページは [翻訳ステータス](../reference/translation-status.md) で、各ロケールの実際の完成度と、未翻訳ページが MkDocs でどう表示されるかが書かれています (要約: 英語にフォールバックします)。
+
+リポジトリルートの `CHANGELOG.md` も、正式なリリース履歴として英語のまま維持されます。ロケールが `changelog.md` を持つ場合、そのページは別途翻訳された changelog を維持するのではなく、正式な英語 changelog にリンクするか取り込む形にしてください (今後プロジェクト方針が変わった場合を除く)。
+
+翻訳を貢献するときは、ステータスページの表も合わせて更新してください。これにより、利用者が言語切替メニューだけでは判断できない実際の利用可否を把握できます。
+
+## 概要
+
+FastAPI-fastkit は、AI を活用してドキュメントを複数言語へ翻訳する自動化システムを使用しています。このシステムは:
+
+- 英語のソースドキュメントを読み込みます
+- AI API (OpenAI または Anthropic) を使ってコンテンツを翻訳します
+- 翻訳結果を言語別ディレクトリへ保存します
+- レビュー用の GitHub Pull Request を作成します
+
+自動化はあくまでたたき台を作るだけであり、マージ前には人によるレビューが必要です。AI が生成した翻訳は PR の "draft" として明示し、その言語に十分慣れたレビュアーが確認してから反映してください。
+
+## 対応言語
+
+下記はドキュメントサイトが現在 **ビルド** しているロケールです。ビルド対象として設定されているだけでは、そのロケールのページが翻訳済みであるとは **限りません** — ロケールごとの実際の完成度は [翻訳ステータス](../reference/translation-status.md) を参照してください。
+
+- 🇰🇷 韓国語 (ko)
+- 🇯🇵 日本語 (ja)
+- 🇨🇳 中国語 (zh)
+- 🇪🇸 スペイン語 (es)
+- 🇫🇷 フランス語 (fr)
+- 🇩🇪 ドイツ語 (de)
+
+## 前提条件
+
+### 1. 翻訳の依存関係をインストール
+
+```bash
+# pip でインストール
+pip install openai anthropic
+
+# または pdm
+pdm install -G translation
+```
+
+### 2. API キーの設定
+
+OpenAI または Anthropic のいずれかの API キーが必要です:
+
+```bash
+# OpenAI 用
+export TRANSLATION_API_KEY="sk-..."
+
+# または Anthropic 用
+export TRANSLATION_API_KEY="sk-ant-..."
+```
+
+### 3. GitHub CLI のインストール (任意)
+
+PR を自動生成する場合:
+
+```bash
+# macOS
+brew install gh
+
+# Linux
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+sudo apt update
+sudo apt install gh
+
+# 認証
+gh auth login
+```
+
+## 使い方
+
+### Make コマンドを使う (推奨)
+
+最も簡単な実行方法です:
+
+```bash
+# すべてのドキュメントをすべての言語へ翻訳
+make translate
+
+# 特定の言語へ翻訳
+make translate LANG=ko
+
+# API プロバイダとモデルを指定
+make translate LANG=ko PROVIDER=openai MODEL=gpt-4
+make translate LANG=ko PROVIDER=github MODEL=gpt-4o-mini
+```
+
+### スクリプトを直接使う
+
+#### すべてのドキュメントを翻訳
+
+すべての対応言語へドキュメント全体を翻訳:
+
+```bash
+python scripts/translate.py --api-provider openai
+```
+
+### 特定の言語へ翻訳
+
+韓国語のみへ翻訳:
+
+```bash
+python scripts/translate.py --target-lang ko --api-provider openai
+```
+
+### 特定のファイルだけ翻訳
+
+特定のドキュメントファイルのみ翻訳:
+
+```bash
+python scripts/translate.py \
+  --target-lang ko \
+  --files user-guide/installation.md user-guide/quick-start.md \
+  --api-provider openai
+```
+
+### PR 作成をスキップ
+
+GitHub PR を作らずに翻訳のみ実行:
+
+```bash
+python scripts/translate.py --target-lang ko --no-pr --api-provider openai
+```
+
+### Anthropic Claude を使う
+
+OpenAI の代わりに Anthropic の Claude を使用:
+
+```bash
+python scripts/translate.py \
+  --target-lang ko \
+  --api-provider anthropic \
+  --api-key "sk-ant-..."
+```
+
+## ディレクトリ構造
+
+翻訳後のドキュメント構造は次のようになります:
+
+```
+docs/
+├── en/                    # 英語 (原文)
+│   ├── index.md
+│   ├── user-guide/
+│   │   ├── installation.md
+│   │   ├── quick-start.md
+│   │   └── ...
+│   ├── tutorial/
+│   └── ...
+├── ko/                    # 韓国語
+│   ├── index.md
+│   ├── user-guide/
+│   └── ...
+├── ja/                    # 日本語
+├── zh/                    # 中国語
+├── es/                    # スペイン語
+├── fr/                    # フランス語
+├── de/                    # ドイツ語
+├── css/                   # 共有アセット
+├── js/                    # 共有アセット
+└── img/                   # 共有アセット
+```
+
+## 翻訳ワークフロー
+
+### 1. 英語でドキュメントを書く
+
+すべてのドキュメントは、まず英語で `docs/` ディレクトリに記述します:
+
+```bash
+# 新しいドキュメントを作成
+vim docs/user-guide/new-feature.md
+```
+
+### 2. 翻訳を実行
+
+英語ドキュメントが完成したら、翻訳スクリプトを実行します:
+
+```bash
+python scripts/translate.py --target-lang ko
+```
+
+### 3. プルリクエストのレビュー
+
+スクリプトは翻訳結果を含む Pull Request を作成します。PR を確認する際のポイント:
+
+1. Markdown フォーマットが保持されているか
+2. 技術用語が適切に扱われているか
+3. コードサンプルが変更されていないか
+4. 言語固有の問題がないか
+
+### Changelog ポリシー
+
+- リポジトリルートの `CHANGELOG.md` は英語のまま維持してください。
+- ルート changelog 内のリリース履歴を別言語に書き換えるための翻訳 PR を出さないでください。
+- ロケールに changelog ページが必要な場合は、`docs/<locale>/changelog.md` を基準となる英語版 changelog へのラッパーまたは案内ページとして扱ってください。
+
+### 4. 承認とマージ (メンテナー向け)
+
+翻訳が確認できたら:
+
+```bash
+gh pr review <pr-number> --approve
+gh pr merge <pr-number>
+```
+
+### 5. ドキュメントのデプロイ
+
+ドキュメントサイトは新しい翻訳を取り込んで自動的に再ビルドされます。
+
+## 翻訳の設定
+
+`scripts/translation_config.json` を編集してカスタマイズします:
+
+```json
+{
+  "source_language": "en",
+  "target_languages": [
+    {
+      "code": "ko",
+      "name": "Korean",
+      "native_name": "한국어",
+      "enabled": true
+    }
+  ],
+  "translation_settings": {
+    "default_api_provider": "openai",
+    "batch_size": 5,
+    "preserve_formatting": true
+  },
+  "github_settings": {
+    "create_pr_by_default": true,
+    "branch_prefix": "translation"
+  }
+}
+```
+
+## ベストプラクティス
+
+### ソースドキュメント
+
+1. **明快な英語**: 翻訳しやすい平易で明確な英語を書く
+2. **一貫した用語**: 技術用語は一貫して使う
+3. **正しいコードブロック**: コードブロックには必ず言語を指定する
+4. **リンクの検証**: すべての内部リンクは相対パスで指定する
+
+### 翻訳レビュー
+
+1. **技術用語**: 対象言語に適した訳になっているか確認
+2. **文化的コンテキスト**: 例題のローカライズが必要かを確認
+3. **フォーマット**: Markdown のフォーマットがすべて保持されているか確認
+4. **コードの整合性**: コードブロックが書き換えられていないか確認
+
+## トラブルシューティング
+
+### API レート制限
+
+API のレート制限に達した場合は、より小さなバッチで翻訳します:
+
+```bash
+# user guide のみ翻訳
+python scripts/translate.py \
+  --target-lang ko \
+  --files user-guide/*.md
+```
+
+### 翻訳品質の問題
+
+翻訳品質が低い場合:
+
+1. API キーが有効か確認
+2. 別の AI プロバイダを試す
+3. 複雑なドキュメントを小さなセクションに分割
+4. 翻訳結果を手動でレビューおよび編集
+
+### GitHub PR 作成の失敗
+
+PR 作成に失敗する場合:
+
+```bash
+# PR を作らずに翻訳
+python scripts/translate.py --target-lang ko --no-pr
+
+# 手動で PR を作成
+git checkout -b translation/ko
+git add docs/ko/
+git commit -m "Add Korean translations"
+git push -u origin translation/ko
+gh pr create --title "Add Korean translations"
+```
+
+## 手動翻訳
+
+手動で翻訳することもできます:
+
+1. 英語ファイルを対象言語ディレクトリへコピー:
+```bash
+mkdir -p docs/ko/user-guide
+cp docs/en/user-guide/installation.md docs/ko/user-guide/installation.md
+```
+
+2. 好みのエディタで編集
+3. コミットして PR を作成
+
+## 言語切替
+
+ドキュメントサイトのトップナビゲーションには言語切替メニューがあります。利用者は次のことができます:
+
+1. 言語セレクタをクリック
+2. 好みの言語を選択
+3. 翻訳済みドキュメント間を移動
+
+## 新しい言語の追加
+
+新しい言語を追加するには:
+
+1. `scripts/translation_config.json` を編集:
+```json
+{
+  "code": "pt",
+  "name": "Portuguese",
+  "native_name": "Português",
+  "enabled": true
+}
+```
+
+2. `mkdocs.yml` を更新:
+```yaml
+- locale: pt
+  name: Português
+  build: true
+```
+
+3. 翻訳を実行:
+```bash
+python scripts/translate.py --target-lang pt
+```
+
+## ヘルプが必要な場合
+
+- **Issue**: 翻訳に関する問題は [GitHub Issues](https://github.com/bnbong/FastAPI-fastkit/issues) で報告してください
+- **Discussions**: 質問は [GitHub Discussions](https://github.com/bnbong/FastAPI-fastkit/discussions) でどうぞ
+- **コントリビュート**: [CONTRIBUTING.md](https://github.com/bnbong/FastAPI-fastkit/blob/main/CONTRIBUTING.md) を参照
+
+## 翻訳品質基準
+
+すべての翻訳は次の基準を満たす必要があります:
+
+- ✅ Markdown フォーマットをすべて保持
+- ✅ コードブロックは変更しない
+- ✅ 技術用語を適切に扱う
+- ✅ 正しい文法と表記
+- ✅ 言語固有の慣習に従う
+- ✅ すべてのリンクが正しく動作することを確認
+
+FastAPI-fastkit の翻訳に貢献いただき、ありがとうございます! 🌍
diff --git a/docs/ja/reference/faq.md b/docs/ja/reference/faq.md
new file mode 100644
index 0000000..8ba8971
--- /dev/null
+++ b/docs/ja/reference/faq.md
@@ -0,0 +1,784 @@
+# よくある質問
+
+FastAPI-fastkit に関するよくある質問とその回答です。
+
+## インストールとセットアップ
+
+### Q: 対応している Python バージョンは?
+
+**A:** FastAPI-fastkit は **Python 3.12 以上** が必要です。最良の体験のため、最新の安定 Python バージョンの利用を推奨します。
+
+<div class="termy">
+
+```console
+$ python --version
+Python 3.12.1
+
+$ pip install fastapi-fastkit
+```
+
+</div>
+
+### Q: FastAPI-fastkit はどうインストールしますか?
+
+**A:** pip でインストールできます:
+
+<div class="termy">
+
+```console
+# 最新の安定版
+$ pip install fastapi-fastkit
+
+# GitHub からの開発版
+$ pip install git+https://github.com/bnbong/FastAPI-fastkit.git
+
+# 特定のバージョン
+$ pip install fastapi-fastkit==1.0.0
+```
+
+</div>
+
+### Q: パーミッションエラーでインストールに失敗します
+
+**A:** 仮想環境内、またはユーザー権限でインストールしてください:
+
+<div class="termy">
+
+```console
+# 仮想環境を作成
+$ python -m venv fastapi-env
+$ source fastapi-env/bin/activate  # Windows の場合: fastapi-env\Scripts\activate
+
+# 仮想環境にインストール
+$ pip install fastapi-fastkit
+
+# あるいは現在のユーザーのみにインストール
+$ pip install --user fastapi-fastkit
+```
+
+</div>
+
+### Q: インストール後に `fastkit` コマンドが見つかりません
+
+**A:** たいていは、インストール先が PATH に含まれていないことが原因です:
+
+<div class="termy">
+
+```console
+# インストール済みか確認
+$ pip show fastapi-fastkit
+
+# インストール場所を確認
+$ python -c "import fastapi_fastkit; print(fastapi_fastkit.__file__)"
+
+# 直接実行を試す
+$ python -m fastapi_fastkit --version
+
+# PATH に追加 (Linux/macOS)
+$ export PATH="$HOME/.local/bin:$PATH"
+```
+
+</div>
+
+## プロジェクトの作成
+
+### Q: 利用できる依存関係スタックは?
+
+**A:** FastAPI-fastkit は 3 つの依存関係スタックを提供します:
+
+- **MINIMAL**: FastAPI、Uvicorn、Pydantic、Pydantic-Settings (基本的な Web API)
+- **STANDARD**: SQLAlchemy、Alembic、pytest を追加 (データベース対応)
+- **FULL**: Redis、Celery を追加 (バックグラウンドタスク)
+
+!!! tip "デフォルトのパッケージマネージャー"
+    デフォルトのパッケージマネージャーは依存関係インストールが速い `uv` です。`pip`、`pdm`、`poetry` も選択できます。
+
+<div class="termy">
+
+```console
+$ fastkit init
+# プロジェクト作成中に好みのスタックを選択
+```
+
+</div>
+
+### Q: プロジェクトテンプレートはカスタマイズできますか?
+
+**A:** はい、次のいずれかの方法で:
+
+1. **既存テンプレートを使う** — `fastkit startdemo`
+2. **カスタムテンプレートを作る** — 既存をコピーして変更
+3. **段階的にルートを追加** — `fastkit addroute`
+
+<div class="termy">
+
+```console
+# あらかじめ用意されたテンプレートを使う
+$ fastkit list-templates
+$ fastkit startdemo
+
+# 既存プロジェクトにルートを追加
+$ fastkit addroute users .          # 現在のディレクトリに 'users' ルートを追加
+$ fastkit addroute users my-project # 'my-project' に 'users' ルートを追加
+```
+
+</div>
+
+### Q: プロジェクト名にはどんな形式が使えますか?
+
+**A:** プロジェクト名は妥当な Python 識別子である必要があります:
+
+- ✅ `my-api`、`blog_system`、`UserService`
+- ❌ `my api`、`123project`、`project-name!`
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my_awesome_api  # 妥当
+Enter the project name: my-awesome-api  # 妥当 (ハイフンはアンダースコアに変換)
+```
+
+</div>
+
+### Q: 「ディレクトリは既に存在する」というエラーで作成に失敗します
+
+**A:** プロジェクトディレクトリが既に存在しています。次のいずれかで対処してください:
+
+1. **別の名前を選ぶ**
+2. **既存ディレクトリを削除** (安全な場合のみ)
+3. **別の場所に作成**
+
+<div class="termy">
+
+```console
+# ディレクトリの存在を確認
+$ ls my-project
+
+# 安全なら削除 (注意!)
+$ rm -rf my-project
+
+# あるいは別の場所に作成
+$ mkdir projects
+$ cd projects
+$ fastkit init
+```
+
+</div>
+
+### Q: 対話型モードでプロジェクトをセットアップするには?
+
+**A:** `fastkit init --interactive` を使うと、賢い機能選択を伴うガイド付きの段階的なセットアップが可能です:
+
+<div class="termy">
+
+```console
+$ fastkit init --interactive
+```
+
+</div>
+
+対話型モードは次の順序で進みます:
+
+1. **プロジェクト情報** — 名前、作者、メール、説明。
+2. **アーキテクチャプリセット** — プロジェクトレイアウトを選択。推奨デフォルトは `domain-starter`。Enter で受け入れられます。各プリセットが生成する正確なレイアウトと、手動配線が必要な機能組み合わせは [プリセット / 機能マトリクス](preset-feature-matrix.md) を参照してください。
+3. **機能選択** — データベース、認証、バックグラウンドタスク、キャッシュ、モニタリング、テスト、ユーティリティ、デプロイ。
+4. **パッケージマネージャーとカスタムパッケージ** — pip / uv / pdm / poetry、および固定したい追加パッケージ。
+5. **確認** — プロジェクト作成前に、すべての選択 (アーキテクチャプリセット含む) を表で表示します。
+
+対話型モードでは、次の包括的な機能カタログから選べます:
+
+| カテゴリ | 利用可能な選択肢 |
+|---|---|
+| **アーキテクチャ** | minimal、single-module、classic-layered、**domain-starter** (推奨デフォルト) |
+| **データベース** | PostgreSQL、MySQL、MongoDB、Redis、SQLite |
+| **認証** | JWT、OAuth2、FastAPI-Users、セッションベース |
+| **バックグラウンドタスク** | Celery、Dramatiq |
+| **テスト** | Basic (pytest)、Coverage、Advanced (faker、factory-boy 付き) |
+| **キャッシュ** | Redis with fastapi-cache2 |
+| **モニタリング** | Loguru、OpenTelemetry、Prometheus |
+| **ユーティリティ** | CORS、レート制限、ページネーション、WebSocket |
+| **デプロイ** | Docker、docker-compose (自動生成設定付き) |
+
+対話型モードは次を自動生成します:
+
+- 選択した機能を統合した `main.py`
+- データベースおよび認証の設定ファイル (コード生成に対応する選択肢の場合 — 例: データベースの PostgreSQL/MySQL/SQLite/MongoDB、認証の JWT/FastAPI-Users。それ以外の選択肢は必要パッケージのインストールのみ)
+- 選択したデプロイオプションに対応するデプロイファイル (`Docker` 選択時は `Dockerfile`、`docker-compose` 選択時は `docker-compose.yml`)
+- 選択したテストオプションに応じたテスト設定 (カバレッジ設定は `Coverage` または `Advanced` を選んだ場合のみ含まれます)
+
+### Q: 対話型モードで利用できる機能を確認するには?
+
+**A:** `list-features` コマンドで、利用可能なすべての機能とパッケージを表示できます:
+
+<div class="termy">
+
+```console
+$ fastkit list-features
+# カテゴリ別に整理されたすべての機能と
+# 関連パッケージが表示されます
+```
+
+</div>
+
+これで、各機能を選んだ場合にどのパッケージがインストールされるかを把握できます。
+
+## ルート開発
+
+### Q: ルートに認証を追加するには?
+
+**A:** 認証用の依存性を作成します:
+
+```python
+# src/api/deps.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer
+
+security = HTTPBearer()
+
+def get_current_user(token: str = Depends(security)):
+    # トークンを検証してユーザーを返す
+    if not verify_token(token):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials"
+        )
+    return get_user_from_token(token)
+
+# src/api/routes/users.py
+@router.get("/me")
+def get_current_user_profile(user = Depends(get_current_user)):
+    return user
+```
+
+### Q: プロジェクトにデータベースモデルを追加するには?
+
+**A:** STANDARD または FULL スタックで、SQLAlchemy モデルを作成します:
+
+```python
+# src/models/users.py
+from sqlalchemy import Column, Integer, String, Boolean
+from sqlalchemy.ext.declarative import declarative_base
+
+Base = declarative_base()
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    email = Column(String, unique=True, index=True)
+    username = Column(String, unique=True, index=True)
+    hashed_password = Column(String)
+    is_active = Column(Boolean, default=True)
+```
+
+### Q: リクエストデータの検証を追加するには?
+
+**A:** スキーマで Pydantic モデルを使います:
+
+```python
+# src/schemas/users.py
+from pydantic import BaseModel, EmailStr, Field
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    username: str = Field(..., min_length=3, max_length=50)
+    password: str = Field(..., min_length=8)
+
+    @validator('username')
+    def validate_username(cls, v):
+        if not v.isalnum():
+            raise ValueError('Username must be alphanumeric')
+        return v
+```
+
+### Q: ファイルアップロードはどう扱いますか?
+
+**A:** FastAPI の `UploadFile` を使います:
+
+```python
+from fastapi import UploadFile, File
+
+@router.post("/upload")
+async def upload_file(file: UploadFile = File(...)):
+    contents = await file.read()
+
+    # ファイルを保存
+    with open(f"uploads/{file.filename}", "wb") as f:
+        f.write(contents)
+
+    return {"filename": file.filename, "size": len(contents)}
+```
+
+## テンプレート
+
+### Q: 利用できるテンプレートは?
+
+**A:** FastAPI-fastkit には、あらかじめ用意されたテンプレートが複数含まれています:
+
+<div class="termy">
+
+```console
+$ fastkit list-templates
+                      Available Templates
+┌─────────────────────────┬───────────────────────────────────┐
+│ fastapi-default         │ Simple FastAPI Project            │
+│ fastapi-async-crud      │ Async Item Management API Server  │
+│ fastapi-custom-response │ Custom Response System            │
+│ fastapi-dockerized      │ Dockerized FastAPI API            │
+│ fastapi-empty           │ Minimal FastAPI Project           │
+│ fastapi-mcp             │ MCP (Model Context Protocol) API  │
+│ fastapi-psql-orm        │ PostgreSQL FastAPI API            │
+│ fastapi-single-module   │ Single-file FastAPI Project       │
+└─────────────────────────┴───────────────────────────────────┘
+```
+
+</div>
+
+### Q: 特定のテンプレートを使うには?
+
+**A:** `startdemo` コマンドを使います:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo
+Enter the project name: my-blog
+Select template: fastapi-psql-orm
+```
+
+</div>
+
+### Q: 自分でテンプレートを作れますか?
+
+**A:** 作れます。ディレクトリ構造を用意し、テンプレート変数を使います:
+
+```
+my-template/
+├── src/
+│   └── main.py-tpl
+├── requirements.txt-tpl
+└── template.yaml
+```
+
+```python
+# main.py-tpl
+from fastapi import FastAPI
+
+app = FastAPI(title="{{PROJECT_NAME}}")
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello from {{PROJECT_NAME}}!"}
+```
+
+### Q: 既存のテンプレートを変更するには?
+
+**A:** テンプレートは `fastapi_project_template` ディレクトリにあります:
+
+1. **リポジトリをフォーク** してテンプレートを変更
+2. 既存をベースに **カスタムテンプレートを作成**
+3. プロジェクト作成後に **特定のファイルを上書き**
+
+## 開発サーバー
+
+### Q: 開発サーバーを起動するには?
+
+**A:** プロジェクトディレクトリで `runserver` コマンドを使います:
+
+<div class="termy">
+
+```console
+$ cd my-project
+$ source .venv/bin/activate  # 仮想環境を有効化
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+### Q: サーバーが起動しない — "Address already in use"
+
+**A:** ポート 8000 がビジー状態です。別のポートを使うか、既存プロセスを終了してください:
+
+<div class="termy">
+
+```console
+# 別のポートを使う
+$ fastkit runserver --port 8080
+
+# あるいは既存プロセスを特定して終了
+$ lsof -ti:8000 | xargs kill -9
+
+# Windows
+$ netstat -ano | findstr :8000
+$ taskkill /PID <PID> /F
+```
+
+</div>
+
+### Q: 自動リロードが動きません
+
+**A:** プロジェクトディレクトリにいて、仮想環境が有効化されているか確認してください:
+
+<div class="termy">
+
+```console
+# 現在のディレクトリを確認
+$ pwd
+/path/to/my-project
+
+# 仮想環境を確認
+$ which python
+/path/to/my-project/.venv/bin/python
+
+# 明示的に reload を指定
+$ fastkit runserver --reload
+```
+
+</div>
+
+### Q: 本番運用向けにサーバーをどう設定すれば?
+
+**A:** 本番では開発サーバーを使わないでください。次のようにします:
+
+```python
+# gunicorn などの WSGI サーバーを使う
+$ pip install gunicorn
+$ gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker
+
+# あるいは fastapi-dockerized テンプレートで Docker
+$ fastkit startdemo  # fastapi-dockerized を選択
+$ docker build -t my-app .
+$ docker run -p 8000:8000 my-app
+```
+
+## パフォーマンスと最適化
+
+### Q: API のパフォーマンスを向上させるには?
+
+**A:** いくつかの最適化戦略があります:
+
+1. I/O 操作には **async/await を使用**
+2. 重い処理には **キャッシュを追加**
+3. **データベースクエリを最適化**
+4. 重い処理には **バックグラウンドタスクを使用**
+
+```python
+# 非同期エンドポイント
+@router.get("/users/{user_id}")
+async def get_user(user_id: int):
+    user = await users_service.get_user_async(user_id)
+    return user
+
+# バックグラウンドタスク
+from fastapi import BackgroundTasks
+
+@router.post("/send-email")
+def send_email(background_tasks: BackgroundTasks, email: str):
+    background_tasks.add_task(send_notification_email, email)
+    return {"message": "Email will be sent in background"}
+```
+
+### Q: キャッシュを追加するには?
+
+**A:** Redis でキャッシュします:
+
+```python
+import redis
+from functools import wraps
+
+redis_client = redis.Redis(host='localhost', port=6379, db=0)
+
+def cache_result(expiration: int = 300):
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            cache_key = f"{func.__name__}:{hash(str(args) + str(kwargs))}"
+
+            # キャッシュから取得を試みる
+            cached = redis_client.get(cache_key)
+            if cached:
+                return json.loads(cached)
+
+            # 関数を実行して結果をキャッシュ
+            result = await func(*args, **kwargs)
+            redis_client.setex(cache_key, expiration, json.dumps(result))
+            return result
+        return wrapper
+    return decorator
+
+@cache_result(expiration=600)
+async def get_expensive_data():
+    # 重い処理
+    return complex_calculation()
+```
+
+### Q: 大量の同時リクエストはどう扱えば?
+
+**A:** 適切なサーバー設定を使います:
+
+<div class="termy">
+
+```console
+# 開発
+$ fastkit runserver --workers 1  # 開発はシングルワーカー
+
+# 本番
+$ gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker
+$ uvicorn src.main:app --workers 4 --host 0.0.0.0 --port 8000
+```
+
+</div>
+
+## テスト
+
+### Q: テストを実行するには?
+
+**A:** プロジェクトディレクトリで pytest を使います:
+
+<div class="termy">
+
+```console
+$ cd my-project
+$ source .venv/bin/activate
+$ python -m pytest
+
+# カバレッジ付き
+$ python -m pytest --cov=src
+
+# 特定のテストファイル
+$ python -m pytest tests/test_users.py
+
+# 詳細出力
+$ python -m pytest -v
+```
+
+</div>
+
+### Q: API テストはどう書けば?
+
+**A:** FastAPI のテストクライアントを使います:
+
+```python
+from fastapi.testclient import TestClient
+from src.main import app
+
+client = TestClient(app)
+
+def test_create_user():
+    response = client.post(
+        "/api/v1/users/",
+        json={"email": "test@example.com", "username": "testuser"}
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "test@example.com"
+
+def test_get_user():
+    response = client.get("/api/v1/users/1")
+    assert response.status_code == 200
+```
+
+### Q: 外部依存をモックするには?
+
+**A:** pytest フィクスチャとモックを使います:
+
+```python
+import pytest
+from unittest.mock import Mock, patch
+
+@pytest.fixture
+def mock_database():
+    with patch('src.database.get_db') as mock_db:
+        mock_db.return_value = Mock()
+        yield mock_db
+
+def test_user_creation_with_mock_db(mock_database):
+    # モックされた DB でテスト
+    response = client.post("/api/v1/users/", json=user_data)
+    assert response.status_code == 201
+```
+
+## コントリビュート
+
+### Q: FastAPI-fastkit にどう貢献すれば?
+
+**A:** 次の手順で進めてください:
+
+1. GitHub で **リポジトリをフォーク**
+2. **開発環境をセットアップ**
+3. **機能ブランチを作成**
+4. テスト付きで **変更を実装**
+5. **プルリクエストを送信**
+
+<div class="termy">
+
+```console
+$ git clone https://github.com/yourusername/FastAPI-fastkit.git
+$ cd FastAPI-fastkit
+$ make dev-setup  # 開発環境をセットアップ
+$ git checkout -b feature/my-feature
+# 変更を実装 ...
+$ make dev-check  # フォーマット、リント、テスト
+$ git commit -m "feat: add new feature"
+$ git push origin feature/my-feature
+```
+
+</div>
+
+### Q: プルリクエストには何を含めるべき?
+
+**A:** すべての PR に次を含めてください:
+
+- [ ] **明確な変更内容の説明**
+- [ ] 新機能には **テスト**
+- [ ] 必要に応じて **ドキュメント更新**
+- [ ] **コードガイドラインの遵守**
+- [ ] **すべてのチェックを通過**
+
+### Q: バグはどう報告すれば?
+
+**A:** GitHub Issue を作成し、次を含めてください:
+
+1. **バグの説明** と期待される挙動
+2. **再現手順**
+3. **環境情報** (OS、Python バージョンなど)
+4. **エラーメッセージ** やログ
+5. 可能なら **最小再現例**
+
+### Q: 新機能はどうリクエストすれば?
+
+**A:** 機能リクエスト Issue を開き、次を含めてください:
+
+1. 機能の **明確な説明**
+2. **ユースケース** と動機
+3. **実装案** (任意)
+4. 類似機能の **例**
+
+## トラブルシューティング
+
+### Q: import エラーが出ます
+
+**A:** Python パスと仮想環境を確認してください:
+
+<div class="termy">
+
+```console
+# 仮想環境が有効か確認
+$ which python
+/path/to/project/.venv/bin/python
+
+# Python パスを確認
+$ python -c "import sys; print(sys.path)"
+
+# 開発時は editable モードで再インストール
+$ pip install -e .
+```
+
+</div>
+
+### Q: データベース接続の問題
+
+**A:** データベーステンプレートでは、データベースが起動しているか確認してください:
+
+<div class="termy">
+
+```console
+# PostgreSQL テンプレート
+$ docker-compose up -d postgres  # データベース起動
+$ alembic upgrade head            # マイグレーション実行
+
+# 接続を確認
+$ docker-compose logs postgres
+```
+
+</div>
+
+### Q: テンプレートファイルが見つからない
+
+**A:** テンプレートパスの問題が原因のことが多いです:
+
+<div class="termy">
+
+```console
+# 利用可能なテンプレートを確認
+$ fastkit list-templates
+
+# テンプレートディレクトリを確認
+$ python -c "import fastapi_fastkit; print(fastapi_fastkit.__path__)"
+
+# テンプレートが欠けている場合は再インストール
+$ pip uninstall fastapi-fastkit
+$ pip install fastapi-fastkit
+```
+
+</div>
+
+### Q: pre-commit フックが失敗します
+
+**A:** フックをインストールして実行します:
+
+<div class="termy">
+
+```console
+$ pip install pre-commit
+$ pre-commit install
+$ pre-commit run --all-files
+
+# フォーマット問題を修正
+$ black src/ tests/
+$ isort src/ tests/
+```
+
+</div>
+
+### Q: CI ではテストが落ちるのにローカルでは通る
+
+**A:** よくある原因と対処:
+
+1. **環境差**: Python バージョンが一致しているか確認
+2. **依存関係不足**: テスト要件が入っているか確認
+3. **パスの問題**: 絶対 import を使う
+4. **タイミング問題**: 非同期テストに適切な待機を入れる
+
+<div class="termy">
+
+```console
+# CI と同じ Python バージョンでテスト
+$ python3.12 -m pytest
+
+# 不足している依存関係を確認
+$ pip install -r requirements-dev.txt
+
+# 隔離環境でテストを実行
+$ tox
+```
+
+</div>
+
+## ヘルプ
+
+### Q: どこでヘルプを得られますか?
+
+**A:** いくつか方法があります:
+
+- **GitHub Issues**: バグや機能リクエスト
+- **GitHub Discussions**: 質問やコミュニティサポート
+- **ドキュメント**: ユーザーガイドとチュートリアル
+- **コード例**: 既存テンプレートとテスト
+
+### Q: 最新情報を追うには?
+
+**A:** プロジェクトの更新を追ってください:
+
+- GitHub で **リポジトリを Watch**
+- 新機能は **リリース** で確認
+- 破壊的変更は **changelog** を読む
+- ドキュメントの **ベストプラクティス** に従う
+
+!!! tip "プロのコツ"
+    - Python プロジェクトでは常に仮想環境を使う
+    - FastAPI-fastkit を最新に保つ
+    - 利用可能なコマンドは `fastkit --help` で確認
+    - 困ったらドキュメントを見る
+    - 質問は GitHub Discussions で気軽にどうぞ
diff --git a/docs/ja/reference/preset-feature-matrix.md b/docs/ja/reference/preset-feature-matrix.md
new file mode 100644
index 0000000..1747cbe
--- /dev/null
+++ b/docs/ja/reference/preset-feature-matrix.md
@@ -0,0 +1,60 @@
+# アーキテクチャプリセット / 機能マトリクス
+
+`fastkit init --interactive` は機能選択の前に **アーキテクチャプリセット** を尋ねます ([issue #44](https://github.com/bnbong/FastAPI-fastkit/issues/44))。プリセットは生成されるプロジェクトのレイアウトを決めます。プリセットごとに異なるベーステンプレートを使い、生成された設定ファイルを既存の構造に並べる形で配置します (並列の `src/config/` ツリーを作るのではなく)。
+
+このページは、各プリセットの動作、ファイルの配置先、手動配線が必要な機能の組み合わせを確認するための基準ページです。
+
+## プリセット → ベーステンプレート
+
+| プリセット | ベーステンプレート | 説明 |
+|---|---|---|
+| `minimal` | `fastapi-empty` | 最小構成の動作可能な FastAPI アプリ — プレースホルダの `main.py` は機能選択から再生成されます。 |
+| `single-module` | `fastapi-single-module` | 単一ファイル FastAPI アプリ — `main.py` は再生成されます。 |
+| `classic-layered` | `fastapi-default` | レイヤー型分割 (`api/routes`、`crud`、`schemas`、`core`)。テンプレートに含まれる `main.py` はそのまま使われます。 |
+| `domain-starter` | `fastapi-domain-starter` | ドメイン指向 (`src/app/domains/<concept>/`)。テンプレートに含まれる `main.py` はそのまま使われます。**推奨デフォルト。** |
+
+## 生成ファイルの配置先
+
+| プリセット | `main.py` オーバーレイ | データベース設定の配置先 | 認証設定の配置先 |
+|---|---|---|---|
+| `minimal` | `src/main.py` で再生成 | `src/config/database.py` | `src/config/auth.py` |
+| `single-module` | `src/main.py` で再生成 | `src/config/database.py` | `src/config/auth.py` |
+| `classic-layered` | 保存 (テンプレートに含まれるものをそのまま使用) | `src/core/database.py` | `src/core/auth.py` |
+| `domain-starter` | 保存 (テンプレートに含まれるものをそのまま使用) | `src/app/core/database.py` | `src/app/core/auth.py` |
+
+## プリセット別のデータベース / 認証機能サポート
+
+これらの機能は **すべての** プリセットでサポートされます — パッケージインストールは常に成功します。違いは、動的な `main.py` オーバーレイが自動でそれらを配線するかどうかです。
+
+| 機能 | `minimal` / `single-module` | `classic-layered` / `domain-starter` |
+|---|---|---|
+| **データベース** (PostgreSQL、MySQL、SQLite、MongoDB) | 設定モジュールを生成し、再生成された `main.py` に `await init_db()` 呼び出しのスタブも入ります。 | プリセットごとのパスに設定モジュールを生成します。テンプレートに含まれる `main.py` は **そのまま残る** ため、`get_db()` はルーター側で手動で配線してください。 |
+| **認証** (JWT、FastAPI-Users、OAuth2、セッションベース) | 認証設定モジュールを生成します。JWT の場合は再生成された `main.py` に `HTTPBearer` も import されます。 | プリセットのパスに認証設定モジュールを生成します。`main.py` への import は追加されません — 依存性は手動で配線してください。 |
+| **バックグラウンドタスク** (Celery、Dramatiq) | パッケージはインストールされますが、現状は main.py オーバーレイなし。 | 同上。 |
+| **キャッシュ** (Redis) | パッケージはインストールされますが、現状は main.py オーバーレイなし。 | 同上。 |
+| **CORS** (ユーティリティ) | 再生成された `main.py` に `CORSMiddleware` が `allow_origins=['*']` で追加されます。 | テンプレートに含まれる `main.py` に **すでに組み込み済み** です (`settings.all_cors_origins` に応じて条件分岐)。`.env` の `BACKEND_CORS_ORIGINS` を設定すれば有効化されます — コード変更は不要です。 |
+| **テスト** (Basic / Coverage / Advanced) | プロジェクトルートに `pytest.ini` を生成。 | 同上。 |
+| **デプロイ** (Docker、docker-compose) | プロジェクトルートに `Dockerfile` または `docker-compose.yml` を作成。 | 同上。 |
+
+## "Preset compatibility" 警告が出る場面
+
+テンプレートに含まれる `main.py` を **そのまま使う** プリセット (`classic-layered`、`domain-starter`) では、一部の機能選択が自動配線されません。CLI は生成の最後に、手動配線が必要な選択を 1 回だけまとめて警告します:
+
+| 選択した機能 | `classic-layered` / `domain-starter` で警告が出るか? |
+|---|---|
+| `CORS` (ユーティリティ) | ❌ — テンプレートに含まれる `main.py` で配線済み。`.env` の `BACKEND_CORS_ORIGINS` を埋めるだけ。 |
+| `Rate-Limiting` (ユーティリティ) | ✅ — `slowapi` リミッタのセットアップは追加されない |
+| `Prometheus` (モニタリング) | ✅ — `Instrumentator().instrument(app)` は呼び出されない |
+| 任意のデータベース / 認証選択 | ⚠️ — 設定ファイルは生成されますが、自分で `Depends()` をルーターに組み込む必要があります |
+
+`minimal` と `single-module` プリセットでは、動的 `main.py` オーバーレイが CORS、レート制限、Prometheus 計装を自動で扱います。警告は出ません。
+
+## サポート外の組み合わせ (安全側に倒す)
+
+ストラテジストはあえて **テンプレートに含まれる `main.py` に生成コードを差し込みません**。差し込むと import が壊れたり、ルーターが重複登録されたりするリスクがあるためです。現在の前提は次のとおりです:
+
+- 選択されたパッケージは常にインストールされます (`pip freeze` がユーザーの意図と一致します)。
+- 生成された設定モジュールは常にプリセットに応じた配置先へ作られます。
+- main 保存型プリセットでは、コードが暗黙に壊れるのではなく、どの選択がまだ手動配線を要するかを利用者に明示します。
+
+すべての機能を完全に自動配線したい場合は `minimal` または `single-module` を選んでください — それらは機能フラグから `main.py` を再生成します。
diff --git a/docs/ja/reference/template-quality-assurance.md b/docs/ja/reference/template-quality-assurance.md
new file mode 100644
index 0000000..b156947
--- /dev/null
+++ b/docs/ja/reference/template-quality-assurance.md
@@ -0,0 +1,218 @@
+# テンプレート品質保証
+
+FastAPI-fastkit はテンプレートの品質を高く保ち、さまざまな環境やパッケージマネージャーで確実に動作することを保証するため、包括的な自動検証の仕組みを提供しています。
+
+## 多層的な品質保証
+
+FastAPI-fastkit は **2 つの相補的な品質保証システム** を採用しています:
+
+### 1. 静的テンプレート検査
+**テンプレートの構造と構文を毎週自動で検証**
+
+### 2. 動的テンプレートテスト
+**実際にプロジェクトを生成して行うエンドツーエンドの包括的テスト**
+
+## 自動週次検査
+
+毎週水曜日の午前 0 時 (UTC) に、GitHub Actions のワークフローがすべての FastAPI テンプレートを自動で検査し、品質基準を満たしているかを確認します:
+
+- ✅ **ファイル構造の検証** — 必要なファイルとディレクトリがすべて存在することを確認
+- ✅ **拡張子の検証** — テンプレートファイルが正しい `.py-tpl` 拡張子を使っていることを検証
+- ✅ **依存関係チェック** — FastAPI と必要な依存関係が正しく宣言されていることを確認
+- ✅ **FastAPI 実装の検証** — テンプレートに適切な FastAPI アプリ初期化が含まれていることを検証
+- ✅ **テスト実行** — テンプレートに含まれるテストを実行して機能を確認
+
+## 自動テンプレートテストシステム
+
+FastAPI-fastkit には、すべてのテンプレートを包括的に検証する **革新的な自動テストシステム** が含まれています:
+
+### 動的テンプレート検出
+
+テストシステムは **手動設定なしですべてのテンプレートを自動検出** します:
+
+```console
+# すべてのテンプレートを自動でテスト
+$ pytest tests/test_templates/test_all_templates.py -v
+
+# 検出されたすべてのテンプレートが結果に表示されます
+PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-default]
+PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-async-crud]
+PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-dockerized]
+PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-psql-orm]
+```
+
+### 包括的なテストカバレッジ
+
+各テンプレートは **包括的なエンドツーエンドテスト** を受けます:
+
+#### ✅ プロジェクト生成プロセス
+- テンプレートのコピーとファイル変換
+- プロジェクトメタデータの注入 (名前、作者、説明)
+- ファイル構造の検証
+
+#### ✅ パッケージマネージャー互換性
+- **UV** (デフォルト): Rust 製の高速パッケージマネージャー
+- **PDM**: モダンな Python 依存関係管理
+- **Poetry**: 定番の依存関係管理
+- **PIP**: 伝統的な Python パッケージマネージャー
+
+#### ✅ 仮想環境の管理
+- 各パッケージマネージャーごとの環境作成
+- 依存関係インストールの検証
+- マネージャー固有のワークフロー
+
+#### ✅ 依存関係の解決
+- `pyproject.toml` 生成 (UV、PDM、Poetry)
+- `requirements.txt` 生成 (PIP)
+- メタデータの準拠 (PEP 621)
+- ビルドシステム設定
+
+#### ✅ プロジェクト構造の検証
+- FastAPI プロジェクトの識別
+- 必須ファイルの存在
+- ディレクトリ構造の検証
+
+### テスト実行例
+
+**すべてのテンプレートテストを実行:**
+```console
+$ pytest tests/test_templates/test_all_templates.py -v
+```
+
+**特定のテンプレートをテスト:**
+```console
+$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-default] -v
+```
+
+**PDM 環境でテスト:**
+```console
+$ pdm run pytest tests/test_templates/test_all_templates.py -v
+```
+
+### 継続的インテグレーション
+
+自動テストシステムは **CI/CD パイプライン** で動作します:
+
+- ✅ **プルリクエスト検証**: 各 PR が影響を受けるテンプレートをテスト
+- ✅ **夜間テスト**: テンプレートスイート全体の検証
+- ✅ **パッケージマネージャーテスト**: すべてのマネージャーで相互検証
+- ✅ **環境テスト**: 複数の Python バージョンとプラットフォームで検証
+
+### コントリビューターへのメリット
+
+**設定不要のテスト:**
+
+- 🚀 新しいテンプレートを追加 → 自動でテスト
+- ⚡ テストファイルを手動で作成する必要なし
+- 🛡️ 一貫した品質基準
+
+**包括的なカバレッジ:**
+
+- 🔍 エンドツーエンドのプロジェクト生成テスト
+- 📦 複数のパッケージマネージャーでの検証
+- 🏗️ 依存関係解決の完全テスト
+- ✅ 実利用シナリオのシミュレーション
+
+**開発体験:**
+
+- 🎯 **テンプレート内容に集中**: テストは自動
+- 🔄 **即時フィードバック**: 高速なテスト実行
+- 📊 **明快な結果**: 詳細なテストレポート
+- 🚫 **ボイラープレート不要**: テスト設定はゼロ
+
+## 手動でのテンプレート検査
+
+開発やデバッグ用途では、ローカル検査スクリプトまたは Makefile コマンドでテンプレートを手動検査できます:
+
+### 検査スクリプトを直接使う
+
+```console
+# すべてのテンプレートを検査
+$ python scripts/inspect-templates.py
+
+# 特定のテンプレートを検査
+$ python scripts/inspect-templates.py --templates fastapi-default,fastapi-async-crud
+
+# 詳細情報付きで検査
+$ python scripts/inspect-templates.py --verbose
+
+# 結果を任意のファイルに保存
+$ python scripts/inspect-templates.py --output my_results.json
+```
+
+### Makefile コマンドを使う
+
+```console
+# すべてのテンプレートを検査
+$ make inspect-templates
+
+# 詳細出力付きで検査
+$ make inspect-templates-verbose
+
+# 特定のテンプレートを検査
+$ make inspect-template TEMPLATES="fastapi-default,fastapi-async-crud"
+```
+
+## 検査結果
+
+- **検査が成功した場合** はワークフローの出力およびアーティファクトに記録されます
+- **検査が失敗した場合** は GitHub Issue が自動で作成され、詳細なエラーレポートが添付されます
+- **検査履歴** は GitHub Actions のアーティファクトとして 30 日間保存されます
+
+## 検査出力の読み方
+
+テンプレート検査を実行すると、次のような出力が得られます:
+
+```console
+📋 Found 6 templates to inspect: fastapi-async-crud, fastapi-custom-response, fastapi-default, fastapi-dockerized, fastapi-empty, fastapi-psql-orm
+============================================================
+🔍 Inspecting template: fastapi-async-crud
+   Path: /path/to/src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud
+✅ fastapi-async-crud: PASSED
+----------------------------------------
+🔍 Inspecting template: fastapi-custom-response
+   Path: /path/to/src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response
+✅ fastapi-custom-response: PASSED
+----------------------------------------
+...
+============================================================
+📊 INSPECTION SUMMARY
+   Total templates: 6
+   ✅ Passed: 6
+   ❌ Failed: 0
+🎉 All templates passed inspection!
+📄 Results saved to: template_inspection_results.json
+```
+
+## テンプレート要件
+
+テンプレートが検査を通過するには、次の要件を満たす必要があります:
+
+### ファイル構造
+- Python ソースファイルを含む `src/` ディレクトリが存在すること
+- Python ファイルは `.py-tpl` 拡張子を使用すること
+- `tests/` ディレクトリと `README.md-tpl` ファイルを含むこと
+- 次のメタデータファイルのうち **少なくとも 1 つ** を含むこと:
+    - `pyproject.toml-tpl` (推奨、PEP 621)、または
+    - `setup.py-tpl` (レガシー、引き続き受け付け)
+- `requirements.txt-tpl` は、`pyproject.toml-tpl` が `[project].dependencies` を宣言している場合は任意です
+
+### FastAPI 要件
+- FastAPI アプリの初期化を含むこと
+- 次のいずれかに `fastapi` が依存関係として宣言されていること: `pyproject.toml-tpl` の `[project].dependencies`、`requirements.txt-tpl`、または `setup.py-tpl` の `install_requires`
+- すべてのテンプレートファイルが妥当な Python 構文であること
+
+### 識別マーカー
+テンプレートは FastAPI-fastkit の識別マーカーを保持すべきです。これにより、生成されたプロジェクトが、ユーザーのワークスペース内の無関係な FastAPI プロジェクトと区別できるようになります:
+
+- `pyproject.toml-tpl` — `description` の `[FastAPI-fastkit templated]` 接頭辞と、`managed = true` を持つ `[tool.fastapi-fastkit]` テーブルの両方。
+- `setup.py-tpl` — `setup()` の `description` 引数に `[FastAPI-fastkit templated]` 接頭辞。
+
+`is_fastkit_project()` はこれらのいずれかがあれば判定対象として扱います (pyproject が優先され、setup.py はレガシーフォールバック。マッチングは大文字小文字を区別しません)。メタデータ注入により、テンプレートがマーカーを入れ忘れていても、生成されたプロジェクトには確実に含まれます。
+
+### 品質基準
+- すべてのテンプレートファイルが構文的に正しいこと
+- 依存関係が正しく指定されていること
+- テンプレート構造が FastAPI-fastkit の規約に従っていること
+
+この自動品質保証により、すべてのテンプレートは信頼性が高く、本番運用に耐える状態で維持されます。
diff --git a/docs/ja/reference/translation-status.md b/docs/ja/reference/translation-status.md
index 24627cc..bf3c99d 100644
--- a/docs/ja/reference/translation-status.md
+++ b/docs/ja/reference/translation-status.md
@@ -10,7 +10,7 @@ FastAPI-fastkit のドキュメントは複数の言語でビルドされます
 
 英語ドキュメントは [`docs/en/`](https://github.com/bnbong/FastAPI-fastkit/tree/main/docs/en) 配下にあります。それ以外のすべてのロケール (`docs/ko/`, `docs/ja/`, ...) は翻訳対象です。
 
-リポジトリルートの `CHANGELOG.md` も、この英語原典に含まれます。ロケール固有の `changelog.md` ページがある場合でも、翻訳版のリリース履歴を別に維持するのではなく、正式な英語版 changelog への入口として扱うのが現在の方針です。
+リポジトリルートの `CHANGELOG.md` も、この英語原典に含まれます。ロケール固有の `changelog.md` ページがある場合でも、翻訳版のリリース履歴を別に維持するのではなく、基準となる英語版 changelog への案内ページとして扱うのが現在の方針です。
 
 ## ロケールごとの完成度
 
@@ -20,13 +20,13 @@ FastAPI-fastkit のドキュメントは複数の言語でビルドされます
 |---|---|---:|---|
 | 🇬🇧 English (`en`) | ✅ 原典 (Source of truth) | 26 / 26 | すべての基準になる原文です。 |
 | 🇰🇷 Korean (`ko`) | ✅ 完了 | 26 / 26 | ロケール側のページはすべてそろっています。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。`docs/ko/changelog.md` は英語の `CHANGELOG.md` を意図的に再利用しています。 |
-| 🇯🇵 Japanese (`ja`) | 🟡 部分 | 7 / 26 | Phase 1 を反映済み: トップレベル + コアの user-guide + `reference/translation-status.md`。残りのページは英語にフォールバックします。 |
+| 🇯🇵 Japanese (`ja`) | ✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。`docs/ja/changelog.md` は英語の `CHANGELOG.md` を意図的に再利用しています。 |
 | 🇨🇳 Chinese (`zh`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
 | 🇪🇸 Spanish (`es`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
 | 🇫🇷 French (`fr`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
 | 🇩🇪 German (`de`) | 🔴 スケルトン | 0 / 26 | ビルドターゲットのみ。すべてのページが英語にフォールバックします。 |
 
-*スナップショット検証日: 2026-05-10。Phase 1 (トップレベル + コアの user-guide + `reference/translation-status.md`) を反映した現在のブランチ基準で `ja` 行を再集計しました。* この表は手動で管理されています。リポジトリルートで現在の状態を再カウントしたい場合は、次のコマンドを実行してください:
+*スナップショット検証日: 2026-05-10。Phase 3 (contributing + reference) を反映した現在のブランチを基準に `ja` 行を再集計しました。日本語はロケール側のページがすべてそろっており、`docs/ja/changelog.md` は英語版 changelog をそのまま参照します。* この表は手動で管理されています。リポジトリルートで現在の状態を再カウントしたい場合は、次のコマンドを実行してください:
 
 ```console
 $ for loc in en ko ja zh es fr de; do
@@ -40,7 +40,7 @@ $ for loc in en ko ja zh es fr de; do
 
 - ✅ **原典 (Source of truth)** — ドキュメントを記述する際に基準とするロケールです。
 - 🟡 **部分** — 一部のページのみ翻訳済み。未翻訳のページは英語にフォールバックします。
-- 🔴 **スケルトン** — 言語切替メニューには表示されますが、翻訳済みのページがまだチェックインされていない状態です。翻訳済みのナビゲーションラベルの下に、英語コンテンツがそのまま表示されます。
+- 🔴 **スケルトン** — 言語切替メニューには表示されますが、翻訳済みのページがまだリポジトリに追加されていない状態です。翻訳済みのナビゲーションラベルの下に、英語コンテンツがそのまま表示されます。
 
 ## フォールバックの仕組み
 
@@ -48,9 +48,9 @@ $ for loc in en ko ja zh es fr de; do
 
 - 各翻訳ロケールについて、MkDocs はそのロケールディレクトリに実在するページのみをビルドして出力します。
 - そのロケールに存在 **しない** ページは、英語版のページにフォールバックします。
-- サイト全体の言語切替メニューは、各ロケールの翻訳量にかかわらず、設定されたすべてのロケールを常に表示します。ビルドが各ページに対して到達可能な URL を生成するため (必要に応じて英語ページがフォールバック表示されます)。
+- サイト全体の言語切替メニューは、各ロケールの翻訳量にかかわらず、設定されたすべてのロケールを常に表示します。各ページについて到達可能な URL をビルド時に生成するためで、必要に応じて英語ページがフォールバック表示されます。
 
-つまり言語切替メニューに表示される 🔴 スケルトンの項目は **翻訳済みである保証ではなく**、そのロケールがビルドターゲットとして設定されていることを示すだけです。外部の貢献者が 1 ページずつ翻訳しても、リンクグラフを壊さずに済むよう意図された動作ですが、その分、言語切替メニューが実際の翻訳進捗より完成しているように見えてしまいます。
+つまり、言語切替メニューに表示される 🔴 スケルトンの項目は **翻訳済みであることを保証するものではなく**、そのロケールがビルドターゲットとして設定されていることを示すだけです。これは、外部の貢献者が 1 ページずつ翻訳してもリンク構造が壊れないようにするための挙動ですが、その分、言語切替メニューが実際の翻訳進捗より整って見えることがあります。
 
 ## ドキュメントサイトの読み方
 
@@ -59,15 +59,15 @@ $ for loc in en ko ja zh es fr de; do
 
 ## 貢献方法
 
-現在のロールアウトは **ロケールごとに 1 つのトラッキング Issue** を立て、その中で **複数のフェーズ (phase)** に分けて進める形を取っています。たとえば `ko` は Phase 1 (トップレベル + コアの user-guide)、Phase 2 (残りの user-guide + すべての tutorial)、Phase 3 (contributing + reference) の各フェーズに分けて段階的に反映しました。各フェーズは独立した PR として提出されるため、レビュアーはロケール全体の完了を待たずに、まとまりのある単位でレビューして承認できます。
+現在のロールアウトは **ロケールごとに 1 つのトラッキング Issue** を立て、その中で **複数のフェーズ (phase)** に分けて進める形を取っています。たとえば `ko` は Phase 1 (トップレベル + コアの user-guide)、Phase 2 (残りの user-guide + すべての tutorial)、Phase 3 (contributing + reference) という形で、段階的に反映してきました。各フェーズは独立した PR として提出されるため、レビュアーはロケール全体の完了を待たずに、まとまりのある単位でレビューして承認できます。
 
 貢献したい場合は:
 
 1. 作業フロー、ツール、スタイル規約については [翻訳ガイド](../contributing/translation-guide.md) を参照してください。
 2. **まずロケールごとのトラッキング Issue を確認するか、新しく開いてください。** すでにオープン中のトラッキング Issue があるロケールでは、その中でフェーズ (またはフェーズ内の特定ページ) を担当宣言し、作業の重複を避けてください。トラッキング Issue がないロケールを始める場合は、どのページをどのフェーズに割り当てるかを整理した Issue を新規に開き、Phase 1 から進めてください。
-3. **フェーズごとに 1 PR** という形を推奨します。「このページだけ修正」のような小さな PR — 特に英語原典とずれた翻訳の修正 — は引き続き歓迎しますが、ロケールを新規に立ち上げる作業ではフェーズ単位でまとめることで、用語集の決定や相互リンクの表記をスライス内で一貫させやすくなります。
+3. **フェーズごとに 1 PR** という形を推奨します。「このページだけ修正」のような小さな PR — 特に英語原典とずれた翻訳の修正 — も引き続き歓迎しますが、ロケールを新規に立ち上げる作業ではフェーズ単位でまとめることで、用語集の決定や相互リンクの表記をその範囲内で一貫させやすくなります。
 4. `docs/<locale>/<same path>` 配下にファイルを追加する PR を提出してください。MkDocs が自動で取り込めるよう、英語原典とファイル名を同じに保ってください。
-5. ロケール別の changelog ページが必要な場合は、翻訳版のリリース履歴を新しく書くのではなく、正式な英語版 `CHANGELOG.md` にリンクするラッパーとして維持してください (プロジェクト方針が明示的に変わらない限り)。
+5. ロケール別の changelog ページが必要な場合は、翻訳版のリリース履歴を新しく書くのではなく、基準となる英語版 `CHANGELOG.md` に案内するラッパーページとして維持してください (プロジェクト方針が明示的に変わらない限り)。
 6. 新しい翻訳が反映されたら、このページの表も更新してください。ページ上部の再カウントスニペットでカウントを再集計し、最終検証日が分かるよう「スナップショット検証日」も合わせて更新してください。ロケールがまだ部分翻訳の状態であれば、どのフェーズまで進んだかを「備考」列に記入してください。
 
 翻訳ページが英語原典とずれているというバグ報告も歓迎します。トリアージしやすいように、英語ページと翻訳ページの両方をリンクしてください。
diff --git a/docs/ja/tutorial/async-crud-api.md b/docs/ja/tutorial/async-crud-api.md
new file mode 100644
index 0000000..08a302a
--- /dev/null
+++ b/docs/ja/tutorial/async-crud-api.md
@@ -0,0 +1,665 @@
+# 非同期 CRUD API の構築
+
+FastAPI の非同期処理を使って高性能な CRUD API を構築する方法を学びます。このチュートリアルでは `fastapi-async-crud` テンプレートを使い、非同期ファイル I/O と効率的なデータ処理を実装します。
+
+## このチュートリアルで学ぶこと
+
+- 非同期 FastAPI アプリケーションの理解
+- `async/await` 構文を用いた非同期 CRUD 操作
+- aiofiles による非同期ファイル処理
+- 非同期テストの書き方と実行
+- パフォーマンス最適化の手法
+
+## 前提条件
+
+- [基本 API サーバーチュートリアル](basic-api-server.md) を完了済み
+- Python の `async/await` の基礎を理解していること
+- FastAPI-fastkit がインストール済み
+
+## なぜ非同期処理が必要か
+
+同期処理と非同期処理の違いを把握しておきましょう:
+
+### 同期処理
+
+```python
+def process_items():
+    item1 = read_file("item1.json")      # 2 秒待つ
+    item2 = read_file("item2.json")      # 2 秒待つ
+    item3 = read_file("item3.json")      # 2 秒待つ
+    return [item1, item2, item3]         # 合計: 6 秒
+```
+
+### 非同期処理
+
+```python
+async def process_items():
+    item1_task = read_file_async("item1.json")  # 同時に開始
+    item2_task = read_file_async("item2.json")  # 同時に開始
+    item3_task = read_file_async("item3.json")  # 同時に開始
+
+    items = await asyncio.gather(item1_task, item2_task, item3_task)
+    return items                                # 合計: 2 秒
+```
+
+## ステップ 1: 非同期 CRUD プロジェクトの作成
+
+`fastapi-async-crud` テンプレートでプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-async-crud
+Enter the project name: async-todo-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: Asynchronous todo management API
+Deploying FastAPI project using 'fastapi-async-crud' template
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────┐
+│ Project Name │ async-todo-api                          │
+│ Author       │ Developer Kim                           │
+│ Author Email │ developer@example.com                   │
+│ Description  │ Asynchronous todo management API        │
+└──────────────┴─────────────────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+│ Dependency 5 │ aiofiles          │
+│ Dependency 6 │ pytest-asyncio    │
+└──────────────┴───────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'async-todo-api' from 'fastapi-async-crud' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: プロジェクト構造の解析
+
+生成プロジェクトの主な違いを確認しましょう:
+
+```
+async-todo-api/
+├── src/
+│   ├── main.py                    # 非同期 FastAPI アプリ
+│   ├── api/
+│   │   └── routes/
+│   │       └── items.py          # 非同期 CRUD エンドポイント
+│   ├── crud/
+│   │   └── items.py              # 非同期データ処理ロジック
+│   ├── schemas/
+│   │   └── items.py              # データモデル (同じ)
+│   ├── mocks/
+│   │   └── mock_items.json       # JSON ファイルデータベース
+│   └── core/
+│       └── config.py             # 設定ファイル
+└── tests/
+    ├── conftest.py               # 非同期テスト設定
+    └── test_items.py             # 非同期テストケース
+```
+
+### 主な違い
+
+1. **aiofiles**: 非同期ファイル I/O 処理
+2. **pytest-asyncio**: 非同期テストのサポート
+3. **async/await パターン**: すべての CRUD 操作が非同期で実装
+
+## ステップ 3: 非同期 CRUD ロジックの理解
+
+### 非同期データ処理 (`src/crud/items.py`)
+
+```python
+import json
+import asyncio
+from typing import List, Optional
+from aiofiles import open as aio_open
+from pathlib import Path
+
+from src.schemas.items import Item, ItemCreate, ItemUpdate
+
+class AsyncItemCRUD:
+    def __init__(self, data_file: str = "src/mocks/mock_items.json"):
+        self.data_file = Path(data_file)
+
+    async def _read_data(self) -> List[dict]:
+        """非同期に JSON ファイルからデータを読み込む"""
+        try:
+            async with aio_open(self.data_file, 'r', encoding='utf-8') as f:
+                content = await f.read()
+                return json.loads(content)
+        except FileNotFoundError:
+            return []
+
+    async def _write_data(self, data: List[dict]) -> None:
+        """非同期に JSON ファイルへデータを書き込む"""
+        async with aio_open(self.data_file, 'w', encoding='utf-8') as f:
+            await f.write(json.dumps(data, indent=2, ensure_ascii=False))
+
+    async def get_items(self) -> List[Item]:
+        """すべての items を取得 (非同期)"""
+        data = await self._read_data()
+        return [Item(**item) for item in data]
+
+    async def get_item(self, item_id: int) -> Optional[Item]:
+        """特定の item を取得 (非同期)"""
+        data = await self._read_data()
+        item_data = next((item for item in data if item["id"] == item_id), None)
+        return Item(**item_data) if item_data else None
+
+    async def create_item(self, item: ItemCreate) -> Item:
+        """新しい item を作成 (非同期)"""
+        data = await self._read_data()
+        new_id = max([item["id"] for item in data], default=0) + 1
+
+        new_item = Item(id=new_id, **item.dict())
+        data.append(new_item.dict())
+
+        await self._write_data(data)
+        return new_item
+
+    async def update_item(self, item_id: int, item_update: ItemUpdate) -> Optional[Item]:
+        """item を更新 (非同期)"""
+        data = await self._read_data()
+
+        for i, item in enumerate(data):
+            if item["id"] == item_id:
+                update_data = item_update.dict(exclude_unset=True)
+                data[i].update(update_data)
+                await self._write_data(data)
+                return Item(**data[i])
+
+        return None
+
+    async def delete_item(self, item_id: int) -> bool:
+        """item を削除 (非同期)"""
+        data = await self._read_data()
+        original_length = len(data)
+
+        data = [item for item in data if item["id"] != item_id]
+
+        if len(data) < original_length:
+            await self._write_data(data)
+            return True
+
+        return False
+```
+
+### 非同期 API エンドポイント (`src/api/routes/items.py`)
+
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException, status
+
+from src.schemas.items import Item, ItemCreate, ItemUpdate
+from src.crud.items import AsyncItemCRUD
+
+router = APIRouter()
+crud = AsyncItemCRUD()
+
+@router.get("/", response_model=List[Item])
+async def read_items():
+    """すべての items を取得 (非同期)"""
+    return await crud.get_items()
+
+@router.get("/{item_id}", response_model=Item)
+async def read_item(item_id: int):
+    """特定の item を取得 (非同期)"""
+    item = await crud.get_item(item_id)
+    if item is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item with id {item_id} not found"
+        )
+    return item
+
+@router.post("/", response_model=Item, status_code=status.HTTP_201_CREATED)
+async def create_item(item: ItemCreate):
+    """新しい item を作成 (非同期)"""
+    return await crud.create_item(item)
+
+@router.put("/{item_id}", response_model=Item)
+async def update_item(item_id: int, item_update: ItemUpdate):
+    """item を更新 (非同期)"""
+    updated_item = await crud.update_item(item_id, item_update)
+    if updated_item is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item with id {item_id} not found"
+        )
+    return updated_item
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(item_id: int):
+    """item を削除 (非同期)"""
+    deleted = await crud.delete_item(item_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item with id {item_id} not found"
+        )
+```
+
+## ステップ 4: サーバーの起動とテスト
+
+プロジェクトディレクトリへ移動してサーバーを起動します:
+
+<div class="termy">
+
+```console
+$ cd async-todo-api
+$ fastkit runserver
+Starting FastAPI server at 127.0.0.1:8000...
+
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [12345] using WatchFiles
+INFO:     Started server process [12346]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+</div>
+
+### パフォーマンステスト
+
+非同期処理のパフォーマンスを確認しましょう。複数のリクエストを同時に送ってみます:
+
+**同時リクエストテスト (Python スクリプト)**
+
+```python
+import asyncio
+import aiohttp
+import time
+
+async def create_item(session, item_data):
+    async with session.post("http://127.0.0.1:8000/items/", json=item_data) as response:
+        return await response.json()
+
+async def test_concurrent_requests():
+    start_time = time.time()
+
+    items_to_create = [
+        {"name": f"Item {i}", "description": f"Description {i}", "price": i * 10, "tax": i}
+        for i in range(1, 11)  # 10 件の item を同時生成
+    ]
+
+    async with aiohttp.ClientSession() as session:
+        tasks = [create_item(session, item) for item in items_to_create]
+        results = await asyncio.gather(*tasks)
+
+    end_time = time.time()
+    print(f"Created 10 items in: {end_time - start_time:.2f} seconds")
+    print(f"Number of items created: {len(results)}")
+
+# 実行
+# asyncio.run(test_concurrent_requests())
+```
+
+## ステップ 5: 非同期テストの作成
+
+### テスト設定 (`tests/conftest.py`)
+
+```python
+import pytest
+import asyncio
+from httpx import AsyncClient
+from src.main import app
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """イベントループの設定"""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture
+async def async_client():
+    """非同期テストクライアント"""
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+```
+
+### 非同期テストケース (`tests/test_items.py`)
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_item_async(async_client: AsyncClient):
+    """非同期 item 作成テスト"""
+    item_data = {
+        "name": "Test Item",
+        "description": "Item for asynchronous testing",
+        "price": 100.0,
+        "tax": 10.0
+    }
+
+    response = await async_client.post("/items/", json=item_data)
+
+    assert response.status_code == 201
+    data = response.json()
+    assert data["name"] == item_data["name"]
+    assert data["price"] == item_data["price"]
+    assert "id" in data
+
+@pytest.mark.asyncio
+async def test_read_items_async(async_client: AsyncClient):
+    """非同期 item 一覧取得テスト"""
+    response = await async_client.get("/items/")
+
+    assert response.status_code == 200
+    items = response.json()
+    assert isinstance(items, list)
+
+@pytest.mark.asyncio
+async def test_concurrent_operations(async_client: AsyncClient):
+    """同時操作テスト"""
+    import asyncio
+
+    # 複数の item を同時作成
+    tasks = []
+    for i in range(5):
+        item_data = {
+            "name": f"ConcurrentItem{i}",
+            "description": f"Description{i}",
+            "price": i * 10,
+            "tax": i
+        }
+        task = async_client.post("/items/", json=item_data)
+        tasks.append(task)
+
+    responses = await asyncio.gather(*tasks)
+
+    # すべてのリクエストが成功したか確認
+    for response in responses:
+        assert response.status_code == 201
+
+    # 作成された item を確認
+    response = await async_client.get("/items/")
+    items = response.json()
+    assert len(items) >= 5
+```
+
+### テスト実行
+
+<div class="termy">
+
+```console
+$ pytest tests/ -v --asyncio-mode=auto
+======================== test session starts ========================
+collected 8 items
+
+tests/test_items.py::test_create_item_async PASSED            [ 12%]
+tests/test_items.py::test_read_items_async PASSED             [ 25%]
+tests/test_items.py::test_read_item_async PASSED              [ 37%]
+tests/test_items.py::test_update_item_async PASSED            [ 50%]
+tests/test_items.py::test_delete_item_async PASSED            [ 62%]
+tests/test_items.py::test_concurrent_operations PASSED        [ 75%]
+tests/test_items.py::test_item_not_found_async PASSED         [ 87%]
+tests/test_items.py::test_invalid_item_data_async PASSED      [100%]
+
+======================== 8 passed in 0.24s ========================
+```
+
+</div>
+
+## ステップ 6: パフォーマンス監視と最適化
+
+### レスポンス時間計測ミドルウェアの追加
+
+`src/main.py` にパフォーマンス監視を追加しましょう:
+
+```python
+import time
+from fastapi import FastAPI, Request
+from src.api.api import api_router
+from src.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    description=settings.DESCRIPTION,
+)
+
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    """リクエストの処理時間をヘッダーに追加"""
+    start_time = time.time()
+    response = await call_next(request)
+    process_time = time.time() - start_time
+    response.headers["X-Process-Time"] = str(process_time)
+    return response
+
+app.include_router(api_router)
+
+@app.get("/")
+async def read_root():
+    return {"message": "Welcome to the Asynchronous Todo API!"}
+```
+
+### 非同期バッチ処理の実装
+
+複数の item を一度に処理するバッチエンドポイントを追加しましょう:
+
+```python
+# src/api/routes/items.py に追加
+
+@router.post("/batch", response_model=List[Item])
+async def create_items_batch(items: List[ItemCreate]):
+    """複数の item を同時作成 (バッチ処理)"""
+    import asyncio
+
+    # すべての作成タスクを同時実行
+    tasks = [crud.create_item(item) for item in items]
+    created_items = await asyncio.gather(*tasks)
+
+    return created_items
+
+@router.get("/batch/{item_ids}")
+async def read_items_batch(item_ids: str):
+    """複数の item を同時取得 (バッチ処理)"""
+    import asyncio
+
+    # カンマ区切りの ID をパース
+    ids = [int(id.strip()) for id in item_ids.split(",")]
+
+    # すべての取得タスクを同時実行
+    tasks = [crud.get_item(item_id) for item_id in ids]
+    items = await asyncio.gather(*tasks)
+
+    # None でない item のみ返す
+    return [item for item in items if item is not None]
+```
+
+### バッチ処理のテスト
+
+<div class="termy">
+
+```console
+# バッチ作成のテスト
+$ curl -X POST "http://127.0.0.1:8000/items/batch" \
+  -H "Content-Type: application/json" \
+  -d '[
+    {"name": "Item1", "description": "Description1", "price": 10.0, "tax": 1.0},
+    {"name": "Item2", "description": "Description2", "price": 20.0, "tax": 2.0},
+    {"name": "Item3", "description": "Description3", "price": 30.0, "tax": 3.0}
+  ]'
+
+# バッチ取得のテスト
+$ curl -X GET "http://127.0.0.1:8000/items/batch/1,2,3"
+```
+
+</div>
+
+## ステップ 7: 高度な非同期パターン
+
+### レート制限の実装
+
+```python
+import asyncio
+from collections import defaultdict
+from fastapi import HTTPException, Request
+from datetime import datetime, timedelta
+
+class AsyncRateLimiter:
+    def __init__(self, max_requests: int = 100, window_seconds: int = 60):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests = defaultdict(list)
+
+    async def is_allowed(self, client_ip: str) -> bool:
+        now = datetime.now()
+        cutoff = now - timedelta(seconds=self.window_seconds)
+
+        # 古いリクエスト履歴を削除
+        self.requests[client_ip] = [
+            req_time for req_time in self.requests[client_ip]
+            if req_time > cutoff
+        ]
+
+        # 現在のリクエスト数を確認
+        if len(self.requests[client_ip]) >= self.max_requests:
+            return False
+
+        # 現在のリクエストを記録
+        self.requests[client_ip].append(now)
+        return True
+
+# グローバルなレートリミッタ
+rate_limiter = AsyncRateLimiter()
+
+@app.middleware("http")
+async def rate_limit_middleware(request: Request, call_next):
+    client_ip = request.client.host
+
+    if not await rate_limiter.is_allowed(client_ip):
+        raise HTTPException(
+            status_code=429,
+            detail="Too many requests"
+        )
+
+    response = await call_next(request)
+    return response
+```
+
+### 非同期キャッシュの実装
+
+```python
+import asyncio
+from typing import Optional, Any
+from datetime import datetime, timedelta
+
+class AsyncCache:
+    def __init__(self):
+        self._cache = {}
+        self._expiry = {}
+
+    async def get(self, key: str) -> Optional[Any]:
+        # 期限切れの項目を削除
+        if key in self._expiry and datetime.now() > self._expiry[key]:
+            del self._cache[key]
+            del self._expiry[key]
+            return None
+
+        return self._cache.get(key)
+
+    async def set(self, key: str, value: Any, ttl_seconds: int = 300):
+        self._cache[key] = value
+        self._expiry[key] = datetime.now() + timedelta(seconds=ttl_seconds)
+
+    async def delete(self, key: str):
+        self._cache.pop(key, None)
+        self._expiry.pop(key, None)
+
+# グローバルなキャッシュ
+cache = AsyncCache()
+
+# CRUD メソッドをキャッシュ利用に変更
+async def get_items_cached(self) -> List[Item]:
+    """キャッシュを利用した item 取得"""
+    cache_key = "all_items"
+    cached_items = await cache.get(cache_key)
+
+    if cached_items:
+        return cached_items
+
+    # キャッシュがなければファイルから読み込む
+    items = await self.get_items()
+    await cache.set(cache_key, items, ttl_seconds=60)  # 1 分間キャッシュ
+
+    return items
+```
+
+## ステップ 8: 本番運用での考慮事項
+
+### コネクションプールの管理
+
+```python
+# src/core/config.py に追加
+class Settings(BaseSettings):
+    # ... 既存の設定 ...
+
+    # 非同期処理関連の設定
+    MAX_CONCURRENT_REQUESTS: int = 100
+    REQUEST_TIMEOUT: int = 30
+    CONNECTION_POOL_SIZE: int = 20
+
+settings = Settings()
+```
+
+### エラーハンドリングの改善
+
+```python
+import logging
+from fastapi import HTTPException
+from typing import Union
+
+logger = logging.getLogger(__name__)
+
+async def safe_async_operation(operation, *args, **kwargs) -> Union[Any, None]:
+    """安全な非同期操作の実行"""
+    try:
+        return await operation(*args, **kwargs)
+    except asyncio.TimeoutError:
+        logger.error(f"Timeout in {operation.__name__}")
+        raise HTTPException(status_code=504, detail="Request timeout")
+    except Exception as e:
+        logger.error(f"Error in {operation.__name__}: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+# 利用例
+@router.get("/safe/{item_id}")
+async def read_item_safe(item_id: int):
+    return await safe_async_operation(crud.get_item, item_id)
+```
+
+## 次のステップ
+
+非同期 CRUD API の構築が完了しました! 次に試すこと:
+
+1. **[データベース統合](database-integration.md)** - 非同期 SQLAlchemy で PostgreSQL を利用
+2. **[Docker でのデプロイ](docker-deployment.md)** - 非同期アプリケーションをコンテナ化
+3. **[カスタムレスポンス処理](custom-response-handling.md)** - 高度なレスポンス形式とエラーハンドリング
+
+<!-- 4. **[Building Real-time APIs](websocket-realtime-api.md)** - Real-time communication with WebSocket -->
+
+## まとめ
+
+このチュートリアルでは、非同期 FastAPI を使って次を行いました:
+
+- ✅ 非同期 CRUD 操作の実装
+- ✅ aiofiles によるファイル I/O の最適化
+- ✅ 同時リクエストとパフォーマンステスト
+- ✅ 非同期テストの作成と実行
+- ✅ バッチ処理と高度な非同期パターンの実装
+- ✅ 本番運用での考慮 (キャッシュ、エラーハンドリング、コネクション管理)
+
+非同期処理を習得すれば、高性能な API サーバーを構築できます!
diff --git a/docs/ja/tutorial/basic-api-server.md b/docs/ja/tutorial/basic-api-server.md
new file mode 100644
index 0000000..981dd45
--- /dev/null
+++ b/docs/ja/tutorial/basic-api-server.md
@@ -0,0 +1,398 @@
+# 基本 API サーバーの構築
+
+FastAPI-fastkit を使って、シンプルな REST API サーバーを素早く構築する方法を学びます。このチュートリアルは FastAPI 初心者向けで、基本的な CRUD API の作成を扱います。
+
+## このチュートリアルで学ぶこと
+
+- `fastkit startdemo` コマンドによる基本 API サーバーの作成
+- FastAPI プロジェクト構造の理解
+- 基本的な CRUD エンドポイントの利用
+- API テストとドキュメント
+- プロジェクトの拡張方法
+
+## 前提条件
+
+- Python 3.12 以上がインストール済み
+- FastAPI-fastkit がインストール済み (`pip install fastapi-fastkit`)
+- 基本的な Python の知識
+
+## ステップ 1: 基本 API プロジェクトの作成
+
+`fastapi-default` テンプレートで基本 API サーバーを作成しましょう。
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-default
+Enter the project name: my-first-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: My first FastAPI server
+Deploying FastAPI project using 'fastapi-default' template
+
+           Project Information
+┌──────────────┬────────────────────────────┐
+│ Project Name │ my-first-api               │
+│ Author       │ Developer Kim              │
+│ Author Email │ developer@example.com      │
+│ Description  │ My first FastAPI server    │
+└──────────────┴────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+│ Dependency 5 │ python-dotenv     │
+└──────────────┴───────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'my-first-api' from 'fastapi-default' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: 生成されたプロジェクト構造の理解
+
+生成されたプロジェクト構造を確認しましょう:
+
+```
+my-first-api/
+├── README.md                 # プロジェクトドキュメント
+├── requirements.txt          # 依存パッケージのリスト
+├── setup.py                  # パッケージ設定
+├── scripts/
+│   └── run-server.sh        # サーバー起動スクリプト
+├── src/                     # メインのソースコード
+│   ├── main.py              # FastAPI アプリのエントリポイント
+│   ├── core/
+│   │   └── config.py        # 設定管理
+│   ├── api/
+│   │   ├── api.py           # API ルーター集約
+│   │   └── routes/
+│   │       └── items.py     # items 関連エンドポイント
+│   ├── schemas/
+│   │   └── items.py         # データモデル定義
+│   ├── crud/
+│   │   └── items.py         # データ処理ロジック
+│   └── mocks/
+│       └── mock_items.json  # テストデータ
+└── tests/                   # テストコード
+    ├── __init__.py
+    ├── conftest.py
+    └── test_items.py
+```
+
+### 主要ファイルの説明
+
+- **`src/main.py`**: FastAPI アプリのエントリポイント
+- **`src/api/routes/items.py`**: items 関連の API エンドポイント定義
+- **`src/schemas/items.py`**: リクエスト / レスポンスのデータ構造定義
+- **`src/crud/items.py`**: データベース操作のロジック
+- **`src/mocks/mock_items.json`**: 開発用のサンプルデータ
+
+## ステップ 3: サーバーの起動
+
+生成されたプロジェクトディレクトリへ移動してサーバーを起動します。
+
+<div class="termy">
+
+```console
+$ cd my-first-api
+$ fastkit runserver
+Starting FastAPI server at 127.0.0.1:8000...
+
+INFO:     Will watch for changes in these directories: ['/path/to/my-first-api']
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [12345] using WatchFiles
+INFO:     Started server process [12346]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+</div>
+
+サーバーが起動したら、ブラウザで次の URL にアクセスできます:
+
+- **API サーバー**: http://127.0.0.1:8000
+- **Swagger UI ドキュメント**: http://127.0.0.1:8000/docs
+- **ReDoc ドキュメント**: http://127.0.0.1:8000/redoc
+
+## ステップ 4: API エンドポイントの確認
+
+生成された API は標準で次のエンドポイントを提供します:
+
+| メソッド | エンドポイント | 説明 |
+|---|---|---|
+| GET | `/items/` | すべての items を取得 |
+| GET | `/items/{item_id}` | 特定の item を取得 |
+| POST | `/items/` | 新しい item を作成 |
+| PUT | `/items/{item_id}` | item を更新 |
+| DELETE | `/items/{item_id}` | item を削除 |
+
+### API のテスト
+
+**1. すべての items を取得**
+
+<div class="termy">
+
+```console
+$ curl -X GET "http://127.0.0.1:8000/items/"
+[
+  {
+    "id": 1,
+    "name": "Laptop",
+    "description": "High-performance laptop",
+    "price": 999.99,
+    "tax": 99.99
+  },
+  {
+    "id": 2,
+    "name": "Mouse",
+    "description": "Wireless mouse",
+    "price": 29.99,
+    "tax": 2.99
+  }
+]
+```
+
+</div>
+
+**2. 新しい item を作成**
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/items/" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "name": "Keyboard",
+       "description": "Mechanical keyboard",
+       "price": 150.00,
+       "tax": 15.00
+     }'
+
+{
+  "id": 3,
+  "name": "Keyboard",
+  "description": "Mechanical keyboard",
+  "price": 150.0,
+  "tax": 15.0
+}
+```
+
+</div>
+
+**3. 特定の item を取得**
+
+<div class="termy">
+
+```console
+$ curl -X GET "http://127.0.0.1:8000/items/1"
+{
+  "id": 1,
+  "name": "Laptop",
+  "description": "High-performance laptop",
+  "price": 999.99,
+  "tax": 99.99
+}
+```
+
+</div>
+
+## ステップ 5: Swagger UI で API をテスト
+
+ブラウザで http://127.0.0.1:8000/docs に移動すると、自動生成された API ドキュメントを確認できます。
+
+Swagger UI でできること:
+
+1. **API エンドポイントの一覧表示**: 利用可能なすべてのエンドポイントを視覚的に確認
+2. **リクエスト / レスポンススキーマの確認**: 各エンドポイントの入出力フォーマットを確認
+3. **API を直接テスト**: 「Try it out」ボタンで実際に API を呼び出す
+4. **サンプルデータの参照**: 各エンドポイントのリクエスト / レスポンス例を確認
+
+### Swagger UI の使い方
+
+1. `/items/` GET エンドポイントをクリック
+2. 「Try it out」ボタンをクリック
+3. 「Execute」ボタンをクリック
+4. サーバーのレスポンスを確認
+
+## ステップ 6: コード構造の理解
+
+### メインアプリケーション (`src/main.py`)
+
+```python
+from fastapi import FastAPI
+from src.api.api import api_router
+from src.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    description=settings.DESCRIPTION,
+)
+
+app.include_router(api_router)
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello World"}
+```
+
+### Item スキーマ (`src/schemas/items.py`)
+
+```python
+from pydantic import BaseModel
+from typing import Optional
+
+class ItemBase(BaseModel):
+    name: str
+    description: Optional[str] = None
+    price: float
+    tax: Optional[float] = None
+
+class ItemCreate(ItemBase):
+    pass
+
+class ItemUpdate(ItemBase):
+    name: Optional[str] = None
+    price: Optional[float] = None
+
+class Item(ItemBase):
+    id: int
+
+    class Config:
+        from_attributes = True
+```
+
+### CRUD ロジック (`src/crud/items.py`)
+
+```python
+from typing import List, Optional
+from src.schemas.items import Item, ItemCreate, ItemUpdate
+
+class ItemCRUD:
+    def __init__(self):
+        self.items: List[Item] = []
+        self.next_id = 1
+
+    def create_item(self, item: ItemCreate) -> Item:
+        new_item = Item(id=self.next_id, **item.dict())
+        self.items.append(new_item)
+        self.next_id += 1
+        return new_item
+
+    def get_items(self) -> List[Item]:
+        return self.items
+
+    def get_item(self, item_id: int) -> Optional[Item]:
+        return next((item for item in self.items if item.id == item_id), None)
+```
+
+## ステップ 7: プロジェクトの拡張
+
+### 新しいルートの追加
+
+`fastkit addroute` コマンドで新しいエンドポイントを追加できます:
+
+<div class="termy">
+
+```console
+$ fastkit addroute user
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-first-api                             │
+│ Route Name       │ user                                     │
+│ Target Directory │ /path/to/my-first-api                   │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'user' to the current project? [Y/n]: y
+
+✨ Successfully added new route 'user' to the current project!
+```
+
+</div>
+
+このコマンドは次のファイルを作成します:
+
+- `src/api/routes/user.py` - user 関連エンドポイント
+- `src/schemas/user.py` - user データモデル
+- `src/crud/user.py` - user データ処理ロジック
+
+### 設定のカスタマイズ
+
+`src/core/config.py` を変更してプロジェクト設定を調整できます:
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "My First API"
+    VERSION: str = "1.0.0"
+    DESCRIPTION: str = "My first FastAPI server"
+    API_V1_STR: str = "/api/v1"
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+## ステップ 8: テストの実行
+
+プロジェクトには基本テストが含まれます:
+
+<div class="termy">
+
+```console
+$ pytest tests/ -v
+======================== test session starts ========================
+collected 4 items
+
+tests/test_items.py::test_create_item PASSED                   [ 25%]
+tests/test_items.py::test_read_items PASSED                    [ 50%]
+tests/test_items.py::test_read_item PASSED                     [ 75%]
+tests/test_items.py::test_update_item PASSED                   [100%]
+
+======================== 4 passed in 0.15s ========================
+```
+
+</div>
+
+## 次のステップ
+
+基本 API サーバーの構築が完了しました! 次に試すこと:
+
+1. **[非同期 CRUD API の構築](async-crud-api.md)** - より複雑な非同期処理を学ぶ
+2. **[データベース統合](database-integration.md)** - PostgreSQL と SQLAlchemy の利用
+3. **[Docker でのデプロイ](docker-deployment.md)** - 本番デプロイの準備
+4. **[カスタムレスポンス処理](custom-response-handling.md)** - 高度なレスポンス形式の構成
+
+## トラブルシューティング
+
+### よくある問題
+
+**Q: サーバーが起動しない**
+A: 仮想環境が有効化され、依存関係が正しくインストールされているか確認してください。
+
+**Q: API エンドポイントにアクセスできない**
+A: サーバーが正常に起動していること、ポート番号 (デフォルト: 8000) が正しいことを確認してください。
+
+**Q: API が Swagger UI に表示されない**
+A: ルーターが `src/main.py` に正しく取り込まれているか確認してください。
+
+## まとめ
+
+このチュートリアルでは、FastAPI-fastkit を使って次を行いました:
+
+- ✅ 基本的な FastAPI プロジェクトの作成
+- ✅ プロジェクト構造の理解
+- ✅ CRUD API エンドポイントの利用
+- ✅ API ドキュメントとテスト
+- ✅ プロジェクトの拡張方法
+
+FastAPI の基礎を理解できたら、より複雑なプロジェクトに挑戦してみましょう!
diff --git a/docs/ja/tutorial/custom-response-handling.md b/docs/ja/tutorial/custom-response-handling.md
new file mode 100644
index 0000000..2822578
--- /dev/null
+++ b/docs/ja/tutorial/custom-response-handling.md
@@ -0,0 +1,1393 @@
+# カスタムレスポンス処理と高度な API 設計
+
+FastAPI の応用機能を使い、一貫したレスポンス形式、エラー処理、ページネーション、カスタム OpenAPI ドキュメントを実装する方法を学びます。`fastapi-custom-response` テンプレートを使い、エンタープライズグレードの API 設計パターンを実装します。
+
+## このチュートリアルで学ぶこと
+
+- 標準化された API レスポンス形式の設計
+- グローバル例外処理とカスタムエラーレスポンス
+- ページネーションシステムの実装
+- フィルタリングとソート機能
+- OpenAPI ドキュメントのカスタマイズ
+- API バージョン管理
+- レスポンスキャッシュと最適化
+
+## 前提条件
+
+- [Docker でのデプロイチュートリアル](docker-deployment.md) を完了済み
+- REST API 設計原則の理解
+- HTTP ステータスコードの知識
+- OpenAPI / Swagger の基本概念
+
+## 標準化された API レスポンスの重要性
+
+### バラバラなレスポンスと標準化されたレスポンス
+
+**問題のあるレスポンス形式:**
+```json
+// 成功
+{"id": 1, "name": "item"}
+
+// エラー
+{"detail": "Not found"}
+
+// 一覧取得
+[{"id": 1}, {"id": 2}]
+```
+
+**標準化されたレスポンス形式:**
+```json
+// 成功
+{
+  "success": true,
+  "data": {"id": 1, "name": "item"},
+  "message": "Item retrieved successfully",
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+
+// エラー
+{
+  "success": false,
+  "error": {
+    "code": "ITEM_NOT_FOUND",
+    "message": "Item not found",
+    "details": {"item_id": 123}
+  },
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+## ステップ 1: カスタムレスポンスプロジェクトの作成
+
+`fastapi-custom-response` テンプレートでプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-custom-response
+Enter the project name: advanced-api-server
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: API server with advanced response handling
+Deploying FastAPI project using 'fastapi-custom-response' template
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────────┐
+│ Project Name │ advanced-api-server                         │
+│ Author       │ Developer Kim                               │
+│ Author Email │ developer@example.com                       │
+│ Description  │ API server with advanced response handling  │
+└──────────────┴─────────────────────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+│ Dependency 5 │ aiofiles          │
+│ Dependency 6 │ python-multipart  │
+└──────────────┴───────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'advanced-api-server' from 'fastapi-custom-response' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: プロジェクト構造の解析
+
+生成されたプロジェクトの応用機能を確認しましょう:
+
+```
+advanced-api-server/
+├── src/
+│   ├── main.py                     # FastAPI アプリ
+│   ├── schemas/
+│   │   ├── base.py                 # ベースレスポンススキーマ
+│   │   ├── items.py                # item スキーマ
+│   │   └── responses.py            # レスポンス形式の定義
+│   ├── helper/
+│   │   ├── exceptions.py           # カスタム例外クラス
+│   │   └── pagination.py           # ページネーションヘルパ
+│   ├── utils/
+│   │   ├── responses.py            # レスポンスユーティリティ
+│   │   └── documents.py            # OpenAPI ドキュメントカスタマイズ
+│   ├── api/
+│   │   └── routes/
+│   │       └── items.py            # 高度な API エンドポイント
+│   ├── crud/
+│   │   └── items.py                # CRUD ロジック
+│   └── core/
+│       └── config.py               # 設定
+└── tests/
+    └── test_responses.py           # レスポンス形式テスト
+```
+
+## ステップ 3: 標準化されたレスポンススキーマの実装
+
+### ベースレスポンススキーマ (`src/schemas/base.py`)
+
+```python
+from typing import Generic, TypeVar, Optional, Any, Dict, List
+from pydantic import BaseModel, Field
+from datetime import datetime
+from enum import Enum
+
+T = TypeVar('T')
+
+class ResponseStatus(str, Enum):
+    """レスポンスステータス"""
+    SUCCESS = "success"
+    ERROR = "error"
+    WARNING = "warning"
+
+class ErrorDetail(BaseModel):
+    """エラー詳細情報"""
+    code: str = Field(..., description="Error code")
+    message: str = Field(..., description="Error message")
+    field: Optional[str] = Field(None, description="Field where error occurred")
+    details: Optional[Dict[str, Any]] = Field(None, description="Additional error information")
+
+class BaseResponse(BaseModel, Generic[T]):
+    """ベースレスポンス形式"""
+    success: bool = Field(..., description="Request success status")
+    status: ResponseStatus = Field(..., description="Response status")
+    data: Optional[T] = Field(None, description="Response data")
+    message: Optional[str] = Field(None, description="Response message")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Response timestamp")
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+
+class ErrorResponse(BaseModel):
+    """エラーレスポンス形式"""
+    success: bool = Field(False, description="Request success status")
+    status: ResponseStatus = Field(ResponseStatus.ERROR, description="Response status")
+    error: ErrorDetail = Field(..., description="Error information")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Response timestamp")
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+
+class PaginationMeta(BaseModel):
+    """ページネーションのメタデータ"""
+    page: int = Field(..., ge=1, description="Current page")
+    size: int = Field(..., ge=1, le=100, description="Page size")
+    total: int = Field(..., ge=0, description="Total number of items")
+    pages: int = Field(..., ge=0, description="Total number of pages")
+    has_next: bool = Field(..., description="Whether next page exists")
+    has_prev: bool = Field(..., description="Whether previous page exists")
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """ページネーション付きレスポンス"""
+    success: bool = Field(True, description="Request success status")
+    status: ResponseStatus = Field(ResponseStatus.SUCCESS, description="Response status")
+    data: List[T] = Field(..., description="Data list")
+    meta: PaginationMeta = Field(..., description="Pagination information")
+    message: Optional[str] = Field(None, description="Response message")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Response time")
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+
+class ValidationErrorDetail(BaseModel):
+    """バリデーションエラー詳細"""
+    field: str = Field(..., description="Validation failed field")
+    message: str = Field(..., description="Error message")
+    invalid_value: Any = Field(..., description="Invalid value")
+
+class ValidationErrorResponse(BaseModel):
+    """バリデーションエラーレスポンス"""
+    success: bool = Field(False, description="Request success status")
+    status: ResponseStatus = Field(ResponseStatus.ERROR, description="Response status")
+    error: ErrorDetail = Field(..., description="Error information")
+    validation_errors: List[ValidationErrorDetail] = Field(..., description="Validation error list")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Response time")
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+```
+
+### レスポンスユーティリティ関数 (`src/utils/responses.py`)
+
+```python
+from typing import Any, Optional, List, TypeVar
+from fastapi import Request
+from fastapi.responses import JSONResponse
+import uuid
+
+from src.schemas.base import (
+    BaseResponse, ErrorResponse, PaginatedResponse,
+    ResponseStatus, ErrorDetail, PaginationMeta
+)
+
+T = TypeVar('T')
+
+def generate_request_id() -> str:
+    """リクエストトラッキング ID を生成"""
+    return str(uuid.uuid4())
+
+def success_response(
+    data: Any = None,
+    message: Optional[str] = None,
+    request_id: Optional[str] = None,
+    status_code: int = 200
+) -> JSONResponse:
+    """成功レスポンスを生成"""
+    response_data = BaseResponse[Any](
+        success=True,
+        status=ResponseStatus.SUCCESS,
+        data=data,
+        message=message or "Request processed successfully",
+        request_id=request_id or generate_request_id()
+    )
+
+    return JSONResponse(
+        status_code=status_code,
+        content=response_data.dict(exclude_none=True)
+    )
+
+def error_response(
+    error_code: str,
+    error_message: str,
+    details: Optional[dict] = None,
+    status_code: int = 400,
+    request_id: Optional[str] = None
+) -> JSONResponse:
+    """エラーレスポンスを生成"""
+    error_detail = ErrorDetail(
+        code=error_code,
+        message=error_message,
+        details=details
+    )
+
+    response_data = ErrorResponse(
+        error=error_detail,
+        request_id=request_id or generate_request_id()
+    )
+
+    return JSONResponse(
+        status_code=status_code,
+        content=response_data.dict(exclude_none=True)
+    )
+
+def paginated_response(
+    data: List[T],
+    page: int,
+    size: int,
+    total: int,
+    message: Optional[str] = None,
+    request_id: Optional[str] = None
+) -> JSONResponse:
+    """ページネーション付きレスポンスを生成"""
+    pages = (total + size - 1) // size  # 切り上げ
+    has_next = page < pages
+    has_prev = page > 1
+
+    meta = PaginationMeta(
+        page=page,
+        size=size,
+        total=total,
+        pages=pages,
+        has_next=has_next,
+        has_prev=has_prev
+    )
+
+    response_data = PaginatedResponse[T](
+        data=data,
+        meta=meta,
+        message=message or f"Page {page}/{pages} data retrieved",
+        request_id=request_id or generate_request_id()
+    )
+
+    return JSONResponse(
+        status_code=200,
+        content=response_data.dict(exclude_none=True)
+    )
+
+class ResponseHelper:
+    """レスポンスヘルパクラス"""
+
+    @staticmethod
+    def created(data: Any, message: str = "Resource created successfully") -> JSONResponse:
+        return success_response(data=data, message=message, status_code=201)
+
+    @staticmethod
+    def updated(data: Any, message: str = "Resource updated successfully") -> JSONResponse:
+        return success_response(data=data, message=message, status_code=200)
+
+    @staticmethod
+    def deleted(message: str = "Resource deleted successfully") -> JSONResponse:
+        return success_response(data=None, message=message, status_code=204)
+
+    @staticmethod
+    def not_found(resource: str = "Resource") -> JSONResponse:
+        return error_response(
+            error_code="RESOURCE_NOT_FOUND",
+            error_message=f"{resource} not found",
+            status_code=404
+        )
+
+    @staticmethod
+    def bad_request(message: str = "Bad request") -> JSONResponse:
+        return error_response(
+            error_code="BAD_REQUEST",
+            error_message=message,
+            status_code=400
+        )
+
+    @staticmethod
+    def unauthorized(message: str = "Authentication required") -> JSONResponse:
+        return error_response(
+            error_code="UNAUTHORIZED",
+            error_message=message,
+            status_code=401
+        )
+
+    @staticmethod
+    def forbidden(message: str = "Permission denied") -> JSONResponse:
+        return error_response(
+            error_code="FORBIDDEN",
+            error_message=message,
+            status_code=403
+        )
+
+    @staticmethod
+    def server_error(message: str = "Server internal error occurred") -> JSONResponse:
+        return error_response(
+            error_code="INTERNAL_SERVER_ERROR",
+            error_message=message,
+            status_code=500
+        )
+```
+
+## ステップ 4: カスタム例外処理システム
+
+### カスタム例外クラス (`src/helper/exceptions.py`)
+
+```python
+from typing import Optional, Dict, Any
+from fastapi import HTTPException
+
+class BaseAPIException(HTTPException):
+    """ベース API 例外クラス"""
+
+    def __init__(
+        self,
+        error_code: str,
+        message: str,
+        status_code: int = 400,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.error_code = error_code
+        self.message = message
+        self.details = details or {}
+        super().__init__(status_code=status_code, detail=message)
+
+class ValidationException(BaseAPIException):
+    """バリデーション例外"""
+
+    def __init__(self, message: str, field: Optional[str] = None, details: Optional[Dict] = None):
+        super().__init__(
+            error_code="VALIDATION_ERROR",
+            message=message,
+            status_code=422,
+            details=details or {"field": field} if field else None
+        )
+
+class ResourceNotFoundException(BaseAPIException):
+    """リソース未発見の例外"""
+
+    def __init__(self, resource: str, resource_id: Any):
+        super().__init__(
+            error_code="RESOURCE_NOT_FOUND",
+            message=f"{resource}(ID: {resource_id}) not found",
+            status_code=404,
+            details={"resource": resource, "id": resource_id}
+        )
+
+class DuplicateResourceException(BaseAPIException):
+    """重複リソース例外"""
+
+    def __init__(self, resource: str, field: str, value: Any):
+        super().__init__(
+            error_code="DUPLICATE_RESOURCE",
+            message=f"{resource} {field} '{value}' already exists",
+            status_code=409,
+            details={"resource": resource, "field": field, "value": value}
+        )
+
+class BusinessLogicException(BaseAPIException):
+    """ビジネスロジック例外"""
+
+    def __init__(self, message: str, error_code: str = "BUSINESS_LOGIC_ERROR"):
+        super().__init__(
+            error_code=error_code,
+            message=message,
+            status_code=422
+        )
+
+class RateLimitException(BaseAPIException):
+    """リクエスト制限例外"""
+
+    def __init__(self, retry_after: int = 60):
+        super().__init__(
+            error_code="RATE_LIMIT_EXCEEDED",
+            message="Request limit exceeded. Please try again later",
+            status_code=429,
+            details={"retry_after": retry_after}
+        )
+
+class AuthenticationException(BaseAPIException):
+    """認証例外"""
+
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(
+            error_code="AUTHENTICATION_REQUIRED",
+            message=message,
+            status_code=401
+        )
+
+class AuthorizationException(BaseAPIException):
+    """認可例外"""
+
+    def __init__(self, message: str = "Permission denied"):
+        super().__init__(
+            error_code="INSUFFICIENT_PERMISSIONS",
+            message=message,
+            status_code=403
+        )
+```
+
+### グローバル例外ハンドラ (`src/main.py`)
+
+```python
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+import logging
+import traceback
+
+from src.helper.exceptions import BaseAPIException
+from src.utils.responses import error_response, generate_request_id
+from src.schemas.base import ValidationErrorDetail, ValidationErrorResponse
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(
+    title="Advanced API Server",
+    description="API server with advanced response handling",
+    version="1.0.0"
+)
+
+@app.exception_handler(BaseAPIException)
+async def custom_api_exception_handler(request: Request, exc: BaseAPIException):
+    """カスタム API 例外ハンドラ"""
+    request_id = generate_request_id()
+
+    logger.error(
+        f"API Exception: {exc.error_code} - {exc.message}",
+        extra={
+            "request_id": request_id,
+            "path": request.url.path,
+            "method": request.method,
+            "details": exc.details
+        }
+    )
+
+    return error_response(
+        error_code=exc.error_code,
+        error_message=exc.message,
+        details=exc.details,
+        status_code=exc.status_code,
+        request_id=request_id
+    )
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Pydantic バリデーション例外ハンドラ"""
+    request_id = generate_request_id()
+
+    validation_errors = []
+    for error in exc.errors():
+        field = ".".join(str(loc) for loc in error["loc"])
+        validation_errors.append(
+            ValidationErrorDetail(
+                field=field,
+                message=error["msg"],
+                invalid_value=error.get("input", "")
+            )
+        )
+
+    error_response_data = ValidationErrorResponse(
+        error={
+            "code": "VALIDATION_ERROR",
+            "message": "Input data validation failed",
+            "details": {"error_count": len(validation_errors)}
+        },
+        validation_errors=validation_errors,
+        request_id=request_id
+    )
+
+    logger.warning(
+        f"Validation Error: {len(validation_errors)} validation errors",
+        extra={
+            "request_id": request_id,
+            "path": request.url.path,
+            "method": request.method,
+            "errors": [err.dict() for err in validation_errors]
+        }
+    )
+
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content=error_response_data.dict(exclude_none=True)
+    )
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    """HTTP 例外ハンドラ"""
+    request_id = generate_request_id()
+
+    error_code_map = {
+        400: "BAD_REQUEST",
+        401: "UNAUTHORIZED",
+        403: "FORBIDDEN",
+        404: "NOT_FOUND",
+        405: "METHOD_NOT_ALLOWED",
+        500: "INTERNAL_SERVER_ERROR"
+    }
+
+    error_code = error_code_map.get(exc.status_code, "HTTP_ERROR")
+
+    return error_response(
+        error_code=error_code,
+        error_message=exc.detail,
+        status_code=exc.status_code,
+        request_id=request_id
+    )
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    """汎用例外ハンドラ"""
+    request_id = generate_request_id()
+
+    logger.error(
+        f"Unhandled Exception: {type(exc).__name__} - {str(exc)}",
+        extra={
+            "request_id": request_id,
+            "path": request.url.path,
+            "method": request.method,
+            "traceback": traceback.format_exc()
+        }
+    )
+
+    return error_response(
+        error_code="INTERNAL_SERVER_ERROR",
+        error_message="Unexpected error occurred",
+        status_code=500,
+        request_id=request_id
+    )
+```
+
+## ステップ 5: 高度なページネーションシステム
+
+### ページネーションヘルパ (`src/helper/pagination.py`)
+
+```python
+from typing import List, Optional, Any, Dict, Callable
+from pydantic import BaseModel, Field
+from fastapi import Query
+from enum import Enum
+
+class SortOrder(str, Enum):
+    """ソート順"""
+    ASC = "asc"
+    DESC = "desc"
+
+class PaginationParams(BaseModel):
+    """ページネーションパラメータ"""
+    page: int = Field(1, ge=1, description="Page number")
+    size: int = Field(20, ge=1, le=100, description="Page size")
+    sort_by: Optional[str] = Field(None, description="Sort field")
+    sort_order: SortOrder = Field(SortOrder.ASC, description="Sort order")
+
+class FilterParams(BaseModel):
+    """フィルタリングパラメータ"""
+    search: Optional[str] = Field(None, description="Search term")
+    category: Optional[str] = Field(None, description="Category")
+    status: Optional[str] = Field(None, description="Status")
+    date_from: Optional[str] = Field(None, description="Start date (YYYY-MM-DD)")
+    date_to: Optional[str] = Field(None, description="End date (YYYY-MM-DD)")
+
+def pagination_params(
+    page: int = Query(1, ge=1, description="Page number"),
+    size: int = Query(20, ge=1, le=100, description="Page size"),
+    sort_by: Optional[str] = Query(None, description="Sort field"),
+    sort_order: SortOrder = Query(SortOrder.ASC, description="Sort order")
+) -> PaginationParams:
+    """ページネーションパラメータの依存"""
+    return PaginationParams(
+        page=page,
+        size=size,
+        sort_by=sort_by,
+        sort_order=sort_order
+    )
+
+def filter_params(
+    search: Optional[str] = Query(None, description="Search term"),
+    category: Optional[str] = Query(None, description="Category"),
+    status: Optional[str] = Query(None, description="Status"),
+    date_from: Optional[str] = Query(None, description="Start date (YYYY-MM-DD)"),
+    date_to: Optional[str] = Query(None, description="End date (YYYY-MM-DD)")
+) -> FilterParams:
+    """フィルタリングパラメータの依存"""
+    return FilterParams(
+        search=search,
+        category=category,
+        status=status,
+        date_from=date_from,
+        date_to=date_to
+    )
+
+class AdvancedPaginator:
+    """高度なページネーションクラス"""
+
+    def __init__(self, data: List[Any], pagination: PaginationParams, filters: FilterParams):
+        self.data = data
+        self.pagination = pagination
+        self.filters = filters
+        self.filtered_data = self._apply_filters()
+        self.sorted_data = self._apply_sorting()
+
+    def _apply_filters(self) -> List[Any]:
+        """フィルタを適用"""
+        filtered = self.data
+
+        if self.filters.search:
+            # 検索語でフィルタ (例: name や description フィールドを検索)
+            search_term = self.filters.search.lower()
+            filtered = [
+                item for item in filtered
+                if (hasattr(item, 'name') and search_term in item.name.lower()) or
+                   (hasattr(item, 'description') and item.description and search_term in item.description.lower())
+            ]
+
+        if self.filters.category:
+            filtered = [item for item in filtered if hasattr(item, 'category') and item.category == self.filters.category]
+
+        if self.filters.status:
+            filtered = [item for item in filtered if hasattr(item, 'status') and item.status == self.filters.status]
+
+        # 日付フィルタ (date フィールドが存在する場合)
+        if self.filters.date_from or self.filters.date_to:
+            from datetime import datetime
+            filtered = self._apply_date_filter(filtered)
+
+        return filtered
+
+    def _apply_date_filter(self, data: List[Any]) -> List[Any]:
+        """日付フィルタを適用"""
+        from datetime import datetime
+
+        if not self.filters.date_from and not self.filters.date_to:
+            return data
+
+        filtered = []
+        for item in data:
+            if not hasattr(item, 'created_at'):
+                continue
+
+            item_date = item.created_at.date() if hasattr(item.created_at, 'date') else item.created_at
+
+            if self.filters.date_from:
+                start_date = datetime.strptime(self.filters.date_from, "%Y-%m-%d").date()
+                if item_date < start_date:
+                    continue
+
+            if self.filters.date_to:
+                end_date = datetime.strptime(self.filters.date_to, "%Y-%m-%d").date()
+                if item_date > end_date:
+                    continue
+
+            filtered.append(item)
+
+        return filtered
+
+    def _apply_sorting(self) -> List[Any]:
+        """ソートを適用"""
+        if not self.pagination.sort_by:
+            return self.filtered_data
+
+        reverse = self.pagination.sort_order == SortOrder.DESC
+
+        try:
+            return sorted(
+                self.filtered_data,
+                key=lambda x: getattr(x, self.pagination.sort_by, 0),
+                reverse=reverse
+            )
+        except (AttributeError, TypeError):
+            # ソート不能なら元データを返す
+            return self.filtered_data
+
+    def get_page(self) -> tuple[List[Any], int]:
+        """現在ページのデータと総件数を返す"""
+        total = len(self.sorted_data)
+        start = (self.pagination.page - 1) * self.pagination.size
+        end = start + self.pagination.size
+
+        page_data = self.sorted_data[start:end]
+        return page_data, total
+
+    def get_metadata(self) -> Dict[str, Any]:
+        """ページネーションのメタデータを返す"""
+        total = len(self.sorted_data)
+        pages = (total + self.pagination.size - 1) // self.pagination.size
+
+        return {
+            "page": self.pagination.page,
+            "size": self.pagination.size,
+            "total": total,
+            "pages": pages,
+            "has_next": self.pagination.page < pages,
+            "has_prev": self.pagination.page > 1,
+            "filters_applied": {
+                "search": self.filters.search,
+                "category": self.filters.category,
+                "status": self.filters.status,
+                "date_range": f"{self.filters.date_from} ~ {self.filters.date_to}" if self.filters.date_from or self.filters.date_to else None
+            },
+            "sorting": {
+                "field": self.pagination.sort_by,
+                "order": self.pagination.sort_order
+            } if self.pagination.sort_by else None
+        }
+```
+
+## ステップ 6: 高度な API エンドポイントの実装
+
+### Item API ルーター (`src/api/routes/items.py`)
+
+```python
+from typing import List, Optional
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, BackgroundTasks
+from fastapi.responses import JSONResponse
+
+from src.schemas.items import Item, ItemCreate, ItemUpdate, ItemResponse
+from src.helper.pagination import pagination_params, filter_params, PaginationParams, FilterParams, AdvancedPaginator
+from src.helper.exceptions import ResourceNotFoundException, DuplicateResourceException, ValidationException
+from src.utils.responses import success_response, paginated_response, ResponseHelper
+from src.crud.items import ItemCRUD
+
+router = APIRouter(prefix="/items", tags=["items"])
+crud = ItemCRUD()
+
+@router.post("/", response_model=dict, status_code=201)
+async def create_item(
+    item_create: ItemCreate,
+    background_tasks: BackgroundTasks
+) -> JSONResponse:
+    """
+    新しい item を作成
+
+    - **name**: item 名 (必須)
+    - **description**: item の説明 (任意)
+    - **price**: 価格 (必須、0 以上)
+    - **category**: カテゴリ (任意)
+    """
+    # 重複チェック
+    existing_item = await crud.get_by_name(item_create.name)
+    if existing_item:
+        raise DuplicateResourceException("Item", "name", item_create.name)
+
+    # ビジネスロジックの検証
+    if item_create.price < 0:
+        raise ValidationException("Price must be 0 or greater", "price")
+
+    # item を作成
+    created_item = await crud.create(item_create)
+
+    # バックグラウンドタスク (例: 通知送信、ロギングなど)
+    background_tasks.add_task(send_creation_notification, created_item.id)
+
+    return ResponseHelper.created(
+        data=created_item.dict(),
+        message=f"Item '{created_item.name}' created successfully"
+    )
+
+@router.get("/", response_model=dict)
+async def list_items(
+    pagination: PaginationParams = Depends(pagination_params),
+    filters: FilterParams = Depends(filter_params)
+) -> JSONResponse:
+    """
+    item 一覧を取得 (ページネーション、フィルタ、ソート対応)
+
+    **ページネーション:**
+    - page: ページ番号 (デフォルト: 1)
+    - size: ページサイズ (デフォルト: 20、最大: 100)
+
+    **ソート:**
+    - sort_by: ソートフィールド (name、price、created_at など)
+    - sort_order: ソート順 (asc、desc)
+
+    **フィルタ:**
+    - search: 検索語 (name や description フィールドを検索)
+    - category: カテゴリフィルタ
+    - status: ステータスフィルタ
+    - date_from: 開始日 (YYYY-MM-DD)
+    - date_to: 終了日 (YYYY-MM-DD)
+    """
+    # すべての item を取得
+    all_items = await crud.get_all()
+
+    # 高度なページネーションを適用
+    paginator = AdvancedPaginator(all_items, pagination, filters)
+    page_data, total = paginator.get_page()
+
+    # 追加メタデータをレスポンスに含める
+    metadata = paginator.get_metadata()
+
+    # カスタムメッセージを生成
+    message = f"Total {total} items, {len(page_data)} items retrieved"
+    if filters.search:
+        message += f" (Search term: '{filters.search}')"
+
+    return paginated_response(
+        data=[item.dict() for item in page_data],
+        page=pagination.page,
+        size=pagination.size,
+        total=total,
+        message=message
+    )
+
+@router.get("/search/advanced", response_model=dict)
+async def advanced_search(
+    q: str = Query(..., min_length=1, description="Search term"),
+    fields: List[str] = Query(["name", "description"], description="Search fields"),
+    exact_match: bool = Query(False, description="Exact match"),
+    case_sensitive: bool = Query(False, description="Case sensitive"),
+    pagination: PaginationParams = Depends(pagination_params)
+) -> JSONResponse:
+    """
+    高度な検索機能
+
+    - **q**: 検索語 (必須)
+    - **fields**: 検索対象フィールドのリスト
+    - **exact_match**: 完全一致
+    - **case_sensitive**: 大文字小文字を区別
+    """
+    results = await crud.advanced_search(
+        query=q,
+        fields=fields,
+        exact_match=exact_match,
+        case_sensitive=case_sensitive
+    )
+
+    # ページネーションを適用
+    total = len(results)
+    start = (pagination.page - 1) * pagination.size
+    end = start + pagination.size
+    page_data = results[start:end]
+
+    return paginated_response(
+        data=[item.dict() for item in page_data],
+        page=pagination.page,
+        size=pagination.size,
+        total=total,
+        message=f"'{q}' search results: {total} items"
+    )
+
+@router.get("/{item_id}", response_model=dict)
+async def get_item(
+    item_id: int = Path(..., gt=0, description="Item ID")
+) -> JSONResponse:
+    """特定の item を取得"""
+    item = await crud.get_by_id(item_id)
+    if not item:
+        raise ResourceNotFoundException("Item", item_id)
+
+    return success_response(
+        data=item.dict(),
+        message=f"Item '{item.name}' retrieved successfully"
+    )
+
+@router.put("/{item_id}", response_model=dict)
+async def update_item(
+    item_id: int = Path(..., gt=0, description="Item ID"),
+    item_update: ItemUpdate
+) -> JSONResponse:
+    """item を更新"""
+    existing_item = await crud.get_by_id(item_id)
+    if not existing_item:
+        raise ResourceNotFoundException("Item", item_id)
+
+    # 他の item との name 重複チェック
+    if item_update.name and item_update.name != existing_item.name:
+        duplicate = await crud.get_by_name(item_update.name)
+        if duplicate:
+            raise DuplicateResourceException("Item", "name", item_update.name)
+
+    updated_item = await crud.update(item_id, item_update)
+
+    return ResponseHelper.updated(
+        data=updated_item.dict(),
+        message=f"Item '{updated_item.name}' updated successfully"
+    )
+
+@router.delete("/{item_id}", response_model=dict, status_code=204)
+async def delete_item(
+    item_id: int = Path(..., gt=0, description="Item ID"),
+    force: bool = Query(False, description="Force delete")
+) -> JSONResponse:
+    """item を削除"""
+    item = await crud.get_by_id(item_id)
+    if not item:
+        raise ResourceNotFoundException("Item", item_id)
+
+    # 削除前の検証 (例: 関連する注文がある場合)
+    if not force and await crud.has_related_orders(item_id):
+        raise ValidationException(
+            "Related orders exist, cannot be deleted. Use force=true to force delete"
+        )
+
+    await crud.delete(item_id)
+
+    return ResponseHelper.deleted(
+        message=f"Item '{item.name}' deleted successfully"
+    )
+
+@router.post("/bulk", response_model=dict)
+async def bulk_create_items(
+    items: List[ItemCreate],
+    skip_duplicates: bool = Query(False, description="Skip duplicates")
+) -> JSONResponse:
+    """item を一括作成"""
+    if len(items) > 100:
+        raise ValidationException("Maximum 100 items can be created at once")
+
+    created_items = []
+    skipped_items = []
+    errors = []
+
+    for i, item_create in enumerate(items):
+        try:
+            # 重複チェック
+            existing = await crud.get_by_name(item_create.name)
+            if existing:
+                if skip_duplicates:
+                    skipped_items.append({"index": i, "name": item_create.name, "reason": "Duplicate name"})
+                    continue
+                else:
+                    errors.append({"index": i, "name": item_create.name, "error": "Duplicate name"})
+                    continue
+
+            created_item = await crud.create(item_create)
+            created_items.append(created_item)
+
+        except Exception as e:
+            errors.append({"index": i, "name": item_create.name, "error": str(e)})
+
+    result = {
+        "created_count": len(created_items),
+        "skipped_count": len(skipped_items),
+        "error_count": len(errors),
+        "created_items": [item.dict() for item in created_items],
+        "skipped_items": skipped_items,
+        "errors": errors
+    }
+
+    message = f"{len(created_items)} items created"
+    if skipped_items:
+        message += f", {len(skipped_items)} skipped"
+    if errors:
+        message += f", {len(errors)} errors"
+
+    return success_response(data=result, message=message)
+
+async def send_creation_notification(item_id: int):
+    """item 作成通知 (バックグラウンドタスク)"""
+    # 実装ではメール、Slack などで通知を送信する
+    import asyncio
+    await asyncio.sleep(1)  # シミュレーション
+    print(f"Item {item_id} creation notification sent")
+```
+
+## ステップ 7: OpenAPI ドキュメントのカスタマイズ
+
+### OpenAPI ドキュメントカスタマイズ (`src/utils/documents.py`)
+
+```python
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+from typing import Dict, Any
+
+def custom_openapi(app: FastAPI) -> Dict[str, Any]:
+    """カスタム OpenAPI スキーマを生成"""
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    )
+
+    # カスタム情報を追加
+    openapi_schema["info"].update({
+        "contact": {
+            "name": "API Support",
+            "url": "https://example.com/support",
+            "email": "support@example.com"
+        },
+        "license": {
+            "name": "MIT",
+            "url": "https://opensource.org/licenses/MIT"
+        },
+        "termsOfService": "https://example.com/terms"
+    })
+
+    # サーバー情報を追加
+    openapi_schema["servers"] = [
+        {
+            "url": "https://api.example.com",
+            "description": "Production server"
+        },
+        {
+            "url": "https://staging-api.example.com",
+            "description": "Staging server"
+        },
+        {
+            "url": "http://localhost:8000",
+            "description": "Development server"
+        }
+    ]
+
+    # 共通レスポンススキーマを追加
+    openapi_schema["components"]["schemas"].update({
+        "SuccessResponse": {
+            "type": "object",
+            "properties": {
+                "success": {"type": "boolean", "example": True},
+                "status": {"type": "string", "example": "success"},
+                "data": {"type": "object"},
+                "message": {"type": "string", "example": "Request processed successfully"},
+                "timestamp": {"type": "string", "format": "date-time"},
+                "request_id": {"type": "string", "example": "123e4567-e89b-12d3-a456-426614174000"}
+            }
+        },
+        "ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "success": {"type": "boolean", "example": False},
+                "status": {"type": "string", "example": "error"},
+                "error": {
+                    "type": "object",
+                    "properties": {
+                        "code": {"type": "string", "example": "RESOURCE_NOT_FOUND"},
+                        "message": {"type": "string", "example": "Resource not found"},
+                        "details": {"type": "object"}
+                    }
+                },
+                "timestamp": {"type": "string", "format": "date-time"},
+                "request_id": {"type": "string", "example": "123e4567-e89b-12d3-a456-426614174000"}
+            }
+        }
+    })
+
+    # タググループと説明を追加
+    openapi_schema["tags"] = [
+        {
+            "name": "items",
+            "description": "Item management API",
+            "externalDocs": {
+                "description": "More information",
+                "url": "https://example.com/docs/items"
+            }
+        },
+        {
+            "name": "health",
+            "description": "System status check API"
+        }
+    ]
+
+    # セキュリティスキーマを追加
+    openapi_schema["components"]["securitySchemes"] = {
+        "BearerAuth": {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "JWT"
+        },
+        "ApiKeyAuth": {
+            "type": "apiKey",
+            "in": "header",
+            "name": "X-API-Key"
+        }
+    }
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+def setup_docs(app: FastAPI):
+    """ドキュメントのセットアップ"""
+    app.openapi = lambda: custom_openapi(app)
+
+    # Swagger UI 設定
+    app.docs_url = "/docs"
+    app.redoc_url = "/redoc"
+
+    # 追加のドキュメントエンドポイント
+    @app.get("/openapi.json", include_in_schema=False)
+    async def get_openapi_endpoint():
+        return custom_openapi(app)
+```
+
+### メインアプリへの適用 (`src/main.py` への追加)
+
+```python
+from src.utils.documents import setup_docs
+from src.api.routes import items
+
+# ルーターを取り込む
+app.include_router(items.router, prefix="/api/v1")
+
+# ドキュメントセットアップを適用
+setup_docs(app)
+
+# リクエスト ID ミドルウェアを追加
+@app.middleware("http")
+async def add_request_id(request: Request, call_next):
+    request_id = generate_request_id()
+    request.state.request_id = request_id
+
+    response = await call_next(request)
+    response.headers["X-Request-ID"] = request_id
+
+    return response
+```
+
+## ステップ 8: キャッシュシステムの実装
+
+### レスポンスキャッシュ (`src/utils/cache.py`)
+
+```python
+from typing import Optional, Any, Dict
+from functools import wraps
+import asyncio
+import json
+import hashlib
+from datetime import datetime, timedelta
+
+class MemoryCache:
+    """メモリベースのキャッシュ"""
+
+    def __init__(self):
+        self._cache: Dict[str, Dict[str, Any]] = {}
+
+    async def get(self, key: str) -> Optional[Any]:
+        """キャッシュから値を取得"""
+        if key not in self._cache:
+            return None
+
+        item = self._cache[key]
+        if datetime.utcnow() > item["expires_at"]:
+            del self._cache[key]
+            return None
+
+        return item["value"]
+
+    async def set(self, key: str, value: Any, ttl_seconds: int = 300):
+        """値をキャッシュに保存"""
+        self._cache[key] = {
+            "value": value,
+            "expires_at": datetime.utcnow() + timedelta(seconds=ttl_seconds),
+            "created_at": datetime.utcnow()
+        }
+
+    async def delete(self, key: str):
+        """キャッシュから値を削除"""
+        self._cache.pop(key, None)
+
+    async def clear(self):
+        """すべてのキャッシュを削除"""
+        self._cache.clear()
+
+    def get_stats(self) -> Dict[str, Any]:
+        """キャッシュ統計"""
+        now = datetime.utcnow()
+        valid_items = [
+            item for item in self._cache.values()
+            if now <= item["expires_at"]
+        ]
+
+        return {
+            "total_items": len(self._cache),
+            "valid_items": len(valid_items),
+            "expired_items": len(self._cache) - len(valid_items),
+            "memory_usage_mb": len(str(self._cache)) / 1024 / 1024
+        }
+
+# グローバルキャッシュ
+cache = MemoryCache()
+
+def cache_response(ttl_seconds: int = 300, key_prefix: str = ""):
+    """レスポンスキャッシュデコレータ"""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # キャッシュキーを生成
+            cache_key = generate_cache_key(func.__name__, args, kwargs, key_prefix)
+
+            # キャッシュから取得
+            cached_response = await cache.get(cache_key)
+            if cached_response:
+                return cached_response
+
+            # 関数を実行
+            response = await func(*args, **kwargs)
+
+            # レスポンスをキャッシュ
+            await cache.set(cache_key, response, ttl_seconds)
+
+            return response
+        return wrapper
+    return decorator
+
+def generate_cache_key(func_name: str, args: tuple, kwargs: dict, prefix: str = "") -> str:
+    """キャッシュキーを生成"""
+    # 関数名と引数からユニークキーを生成
+    key_data = {
+        "function": func_name,
+        "args": str(args),
+        "kwargs": sorted(kwargs.items())
+    }
+
+    key_string = json.dumps(key_data, sort_keys=True)
+    key_hash = hashlib.md5(key_string.encode()).hexdigest()
+
+    return f"{prefix}:{func_name}:{key_hash}" if prefix else f"{func_name}:{key_hash}"
+
+# キャッシュ管理エンドポイント
+@app.get("/admin/cache/stats")
+async def get_cache_stats():
+    """キャッシュ統計を取得"""
+    stats = cache.get_stats()
+    return success_response(data=stats, message="Cache statistics retrieved")
+
+@app.delete("/admin/cache/clear")
+async def clear_cache():
+    """すべてのキャッシュを削除"""
+    await cache.clear()
+    return success_response(message="Cache deleted successfully")
+```
+
+### キャッシュ利用例
+
+```python
+# src/api/routes/items.py にキャッシュを適用
+
+from src.utils.cache import cache_response
+
+@router.get("/", response_model=dict)
+@cache_response(ttl_seconds=60, key_prefix="items_list")  # 1 分間キャッシュ
+async def list_items(
+    pagination: PaginationParams = Depends(pagination_params),
+    filters: FilterParams = Depends(filter_params)
+) -> JSONResponse:
+    # ... 既存コード ...
+
+@router.get("/{item_id}", response_model=dict)
+@cache_response(ttl_seconds=300, key_prefix="item_detail")  # 5 分間キャッシュ
+async def get_item(item_id: int = Path(..., gt=0)) -> JSONResponse:
+    # ... 既存コード ...
+```
+
+## ステップ 9: API テスト
+
+### サーバー起動と基本テスト
+
+<div class="termy">
+
+```console
+$ cd advanced-api-server
+$ fastkit runserver
+Starting FastAPI server at 127.0.0.1:8000...
+
+# カスタムレスポンス形式のテスト
+$ curl -X POST "http://localhost:8000/api/v1/items/" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Advanced notebook",
+    "description": "Notebook with latest technology",
+    "price": 2500000,
+    "category": "electronics"
+  }'
+
+{
+  "success": true,
+  "status": "success",
+  "data": {
+    "id": 1,
+    "name": "Advanced notebook",
+    "description": "Notebook with latest technology",
+    "price": 2500000,
+    "category": "electronics",
+    "created_at": "2024-01-01T12:00:00Z"
+  },
+  "message": "Item 'Advanced notebook' created successfully",
+  "timestamp": "2024-01-01T12:00:00.123456Z",
+  "request_id": "123e4567-e89b-12d3-a456-426614174000"
+}
+
+# ページネーションとフィルタのテスト
+$ curl "http://localhost:8000/api/v1/items/?page=1&size=10&search=notebook&sort_by=price&sort_order=desc"
+
+# 高度な検索のテスト
+$ curl "http://localhost:8000/api/v1/items/search/advanced?q=notebook&fields=name&fields=description&exact_match=false"
+
+# エラーレスポンスのテスト
+$ curl "http://localhost:8000/api/v1/items/999"
+
+{
+  "success": false,
+  "status": "error",
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "Item (ID: 999) not found",
+    "details": {
+      "resource": "Item",
+      "id": 999
+    }
+  },
+  "timestamp": "2024-01-01T12:00:00.123456Z",
+  "request_id": "123e4567-e89b-12d3-a456-426614174000"
+}
+```
+
+</div>
+
+### OpenAPI ドキュメントの確認
+
+ブラウザで http://localhost:8000/docs を開いて、カスタマイズされた API ドキュメントを確認しましょう。
+
+## 次のステップ
+
+カスタムレスポンス処理システムが完成しました! 次に試すこと:
+
+1. **[MCP との統合](mcp-integration.md)** - Model Context Protocol の実装
+<!-- 2. **[Building Authentication Systems](authentication-system.md)** - JWT-based authentication/authorization -->
+<!-- 3. **[Building Real-time APIs](realtime-api.md)** - WebSocket and Server-Sent Events -->
+<!-- 4. **[Microservices Architecture](microservices-architecture.md)** - Service separation and scaling -->
+
+## まとめ
+
+このチュートリアルでは、高度なレスポンス処理システムを実装しました:
+
+- ✅ 標準化された API レスポンス形式の設計
+- ✅ グローバル例外処理とカスタムエラーレスポンス
+- ✅ 高度なページネーションとフィルタリング
+- ✅ OpenAPI ドキュメントのカスタマイズ
+- ✅ レスポンスキャッシュとパフォーマンス最適化
+- ✅ リクエスト追跡システム
+- ✅ バックグラウンドタスク処理
+- ✅ 一括操作 API
+
+これでエンタープライズグレードの API サーバーに必要な中核機能をすべて実装できるようになりました!
diff --git a/docs/ja/tutorial/database-integration.md b/docs/ja/tutorial/database-integration.md
new file mode 100644
index 0000000..b688d10
--- /dev/null
+++ b/docs/ja/tutorial/database-integration.md
@@ -0,0 +1,1027 @@
+# データベース統合 (PostgreSQL + SQLAlchemy)
+
+PostgreSQL データベースと SQLAlchemy ORM を使い、本番環境で利用できる FastAPI アプリケーションを構築します。このチュートリアルでは `fastapi-psql-orm` テンプレートを使い、完全なデータベース統合システムを実装します。
+
+## このチュートリアルで学ぶこと
+
+- PostgreSQL データベースのセットアップと統合
+- SQLAlchemy ORM によるデータモデリング
+- Alembic を使ったデータベースマイグレーション
+- Docker Compose による開発環境構築
+- データベースのコネクションプール管理
+- トランザクション処理とデータ整合性
+
+## 前提条件
+
+- [非同期 CRUD API チュートリアル](async-crud-api.md) を完了済み
+- Docker と Docker Compose がインストール済み
+- PostgreSQL の基礎知識
+- SQLAlchemy ORM の基本概念の理解
+
+## なぜ PostgreSQL と SQLAlchemy か
+
+### JSON ファイルと PostgreSQL の比較
+
+| 項目 | JSON ファイル | PostgreSQL |
+|---|---|---|
+| **パフォーマンス** | 限定的 | 高速なインデックス |
+| **同時実行性** | ファイルロックの問題 | トランザクション対応 |
+| **拡張性** | メモリ上限あり | 大規模データ処理 |
+| **整合性** | 保証されない | ACID 保証 |
+| **クエリ** | 全データ読込が必要 | 複雑なクエリに対応 |
+| **バックアップ** | ファイルコピー | フルバックアップ / 復元 |
+
+## ステップ 1: PostgreSQL + ORM プロジェクトの作成
+
+`fastapi-psql-orm` テンプレートでプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-psql-orm
+Enter the project name: todo-postgres-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: Todo management API using PostgreSQL
+Deploying FastAPI project using 'fastapi-psql-orm' template
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────┐
+│ Project Name │ todo-postgres-api                       │
+│ Author       │ Developer Kim                           │
+│ Author Email │ developer@example.com                   │
+│ Description  │ Todo management API using PostgreSQL    │
+└──────────────┴─────────────────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬────────────────┐
+│ Dependency 1 │ fastapi        │
+│ Dependency 2 │ uvicorn        │
+│ Dependency 3 │ sqlalchemy     │
+│ Dependency 4 │ alembic        │
+│ Dependency 5 │ psycopg2       │
+│ Dependency 6 │ asyncpg        │
+│ Dependency 7 │ sqlmodel       │
+└──────────────┴────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'todo-postgres-api' from 'fastapi-psql-orm' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: プロジェクト構造の解析
+
+生成されたプロジェクトは、完全なデータベース統合環境を提供します:
+
+```
+todo-postgres-api/
+├── docker-compose.yml           # PostgreSQL コンテナの構成
+├── Dockerfile                   # アプリケーションコンテナ
+├── alembic.ini                  # Alembic 設定
+├── template-config.yml          # テンプレート設定
+├── scripts/
+│   ├── pre-start.sh            # 起動前の初期化
+│   └── test.sh                 # テスト実行スクリプト
+├── src/
+│   ├── main.py                 # FastAPI アプリ
+│   ├── core/
+│   │   ├── config.py           # 環境設定
+│   │   └── db.py               # データベース接続設定
+│   ├── api/
+│   │   ├── deps.py             # 依存性注入
+│   │   └── routes/
+│   │       └── items.py        # API エンドポイント
+│   ├── crud/
+│   │   └── items.py            # データベース操作
+│   ├── schemas/
+│   │   └── items.py            # Pydantic モデル
+│   ├── utils/
+│   │   ├── backend_pre_start.py # バックエンド初期化
+│   │   ├── init_data.py        # 初期データロード
+│   │   └── tests_pre_start.py  # テスト準備
+│   └── alembic/
+│       ├── env.py              # Alembic 環境設定
+│       └── versions/           # マイグレーションファイル
+└── tests/
+    ├── conftest.py             # テスト設定
+    └── test_items.py           # API テスト
+```
+
+### 中核コンポーネント
+
+1. **SQLModel**: SQLAlchemy + Pydantic 統合
+2. **Alembic**: データベーススキーママイグレーション
+3. **asyncpg**: 非同期 PostgreSQL ドライバ
+4. **Docker Compose**: 開発環境のコンテナ化
+
+## ステップ 3: データベース設定の理解
+
+### データベース接続設定 (`src/core/db.py`)
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+from sqlmodel import SQLModel
+
+from src.core.config import settings
+
+# 非同期 PostgreSQL エンジンの作成
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,  # SQL ログを出力
+    pool_size=20,         # コネクションプールのサイズ
+    max_overflow=0,       # 追加で許可する接続数
+    pool_pre_ping=True,   # 接続状態を確認
+)
+
+# 非同期セッションファクトリ
+AsyncSessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+async def create_tables():
+    """データベースのテーブルを作成"""
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+async def get_session() -> AsyncSession:
+    """データベースセッションを提供 (依存性注入用)"""
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+```
+
+### 環境設定 (`src/core/config.py`)
+
+```python
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "Todo PostgreSQL API"
+    VERSION: str = "1.0.0"
+    DESCRIPTION: str = "Todo management API using PostgreSQL"
+
+    # データベース設定
+    POSTGRES_SERVER: str = "localhost"
+    POSTGRES_USER: str = "postgres"
+    POSTGRES_PASSWORD: str = "password"
+    POSTGRES_DB: str = "todoapp"
+    POSTGRES_PORT: int = 5432
+
+    # テスト用データベース
+    TEST_DATABASE_URL: Optional[str] = None
+
+    # デバッグモード
+    DEBUG: bool = False
+
+    @property
+    def DATABASE_URL(self) -> str:
+        """PostgreSQL 接続 URL を生成"""
+        return (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:"
+            f"{self.POSTGRES_PASSWORD}@{self.POSTGRES_SERVER}:"
+            f"{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+## ステップ 4: データモデルの定義
+
+### SQLModel を使ったデータモデル (`src/schemas/items.py`)
+
+```python
+from sqlmodel import SQLModel, Field
+from typing import Optional
+from datetime import datetime
+
+# 共通フィールドの定義
+class ItemBase(SQLModel):
+    name: str = Field(index=True, max_length=100)
+    description: Optional[str] = Field(default=None, max_length=500)
+    price: float = Field(gt=0, description="Price must be greater than 0")
+    tax: Optional[float] = Field(default=None, ge=0)
+    is_active: bool = Field(default=True)
+
+# データベーステーブルモデル
+class Item(ItemBase, table=True):
+    __tablename__ = "items"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: Optional[datetime] = Field(default=None)
+
+    # インデックスの設定
+    class Config:
+        schema_extra = {
+            "example": {
+                "name": "notebook",
+                "description": "High-performance gaming notebook",
+                "price": 1500000.0,
+                "tax": 150000.0,
+                "is_active": True
+            }
+        }
+
+# API リクエスト / レスポンスモデル
+class ItemCreate(ItemBase):
+    pass
+
+class ItemUpdate(SQLModel):
+    name: Optional[str] = Field(default=None, max_length=100)
+    description: Optional[str] = Field(default=None, max_length=500)
+    price: Optional[float] = Field(default=None, gt=0)
+    tax: Optional[float] = Field(default=None, ge=0)
+    is_active: Optional[bool] = Field(default=None)
+
+class ItemResponse(ItemBase):
+    id: int
+    created_at: datetime
+    updated_at: Optional[datetime]
+```
+
+## ステップ 5: CRUD 操作の実装
+
+### データベース CRUD ロジック (`src/crud/items.py`)
+
+```python
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, update, delete
+from sqlalchemy.orm import selectinload
+from datetime import datetime
+
+from src.schemas.items import Item, ItemCreate, ItemUpdate
+
+class ItemCRUD:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def create(self, item_create: ItemCreate) -> Item:
+        """新しい item を作成"""
+        db_item = Item(**item_create.dict())
+
+        self.db.add(db_item)
+        await self.db.commit()
+        await self.db.refresh(db_item)
+
+        return db_item
+
+    async def get_by_id(self, item_id: int) -> Optional[Item]:
+        """ID で item を取得"""
+        statement = select(Item).where(Item.id == item_id)
+        result = await self.db.execute(statement)
+        return result.scalar_one_or_none()
+
+    async def get_many(
+        self,
+        skip: int = 0,
+        limit: int = 100,
+        active_only: bool = True
+    ) -> List[Item]:
+        """複数の item を取得 (ページネーション対応)"""
+        statement = select(Item)
+
+        if active_only:
+            statement = statement.where(Item.is_active == True)
+
+        statement = statement.offset(skip).limit(limit)
+        result = await self.db.execute(statement)
+        return result.scalars().all()
+
+    async def update(self, item_id: int, item_update: ItemUpdate) -> Optional[Item]:
+        """item を更新"""
+        # 更新データを準備
+        update_data = item_update.dict(exclude_unset=True)
+        if update_data:
+            update_data["updated_at"] = datetime.utcnow()
+
+        # 更新を実行
+        statement = (
+            update(Item)
+            .where(Item.id == item_id)
+            .values(**update_data)
+            .returning(Item)
+        )
+
+        result = await self.db.execute(statement)
+        await self.db.commit()
+
+        return result.scalar_one_or_none()
+
+    async def delete(self, item_id: int) -> bool:
+        """item を削除 (論理削除)"""
+        statement = (
+            update(Item)
+            .where(Item.id == item_id)
+            .values(is_active=False, updated_at=datetime.utcnow())
+        )
+
+        result = await self.db.execute(statement)
+        await self.db.commit()
+
+        return result.rowcount > 0
+
+    async def hard_delete(self, item_id: int) -> bool:
+        """item を物理削除"""
+        statement = delete(Item).where(Item.id == item_id)
+        result = await self.db.execute(statement)
+        await self.db.commit()
+
+        return result.rowcount > 0
+
+    async def search(self, query: str) -> List[Item]:
+        """item を検索 (name、description)"""
+        statement = select(Item).where(
+            (Item.name.ilike(f"%{query}%")) |
+            (Item.description.ilike(f"%{query}%"))
+        ).where(Item.is_active == True)
+
+        result = await self.db.execute(statement)
+        return result.scalars().all()
+
+    async def get_total_count(self, active_only: bool = True) -> int:
+        """item の合計数を取得"""
+        from sqlalchemy import func
+
+        statement = select(func.count(Item.id))
+        if active_only:
+            statement = statement.where(Item.is_active == True)
+
+        result = await self.db.execute(statement)
+        return result.scalar()
+```
+
+## ステップ 6: API エンドポイントの実装
+
+### 依存性注入の設定 (`src/api/deps.py`)
+
+```python
+from typing import AsyncGenerator
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.core.db import get_session
+from src.crud.items import ItemCRUD
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """データベースセッションの依存性"""
+    async for session in get_session():
+        yield session
+
+def get_item_crud(db: AsyncSession = Depends(get_db)) -> ItemCRUD:
+    """Item CRUD の依存性"""
+    return ItemCRUD(db)
+```
+
+### API ルーターの実装 (`src/api/routes/items.py`)
+
+```python
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from src.api.deps import get_item_crud
+from src.crud.items import ItemCRUD
+from src.schemas.items import Item, ItemCreate, ItemUpdate, ItemResponse
+
+router = APIRouter()
+
+@router.post("/", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
+async def create_item(
+    item_create: ItemCreate,
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """新しい item を作成"""
+    return await crud.create(item_create)
+
+@router.get("/", response_model=List[ItemResponse])
+async def read_items(
+    skip: int = Query(0, ge=0, description="Skip items"),
+    limit: int = Query(100, ge=1, le=1000, description="Maximum items to retrieve"),
+    active_only: bool = Query(True, description="Only active items"),
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """item の一覧を取得 (ページネーション対応)"""
+    return await crud.get_many(skip=skip, limit=limit, active_only=active_only)
+
+@router.get("/search", response_model=List[ItemResponse])
+async def search_items(
+    q: str = Query(..., min_length=1, description="Search term"),
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """item を検索"""
+    return await crud.search(q)
+
+@router.get("/count")
+async def get_items_count(
+    active_only: bool = Query(True, description="Only active items"),
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """item の合計数を取得"""
+    count = await crud.get_total_count(active_only)
+    return {"total": count}
+
+@router.get("/{item_id}", response_model=ItemResponse)
+async def read_item(
+    item_id: int,
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """特定の item を取得"""
+    item = await crud.get_by_id(item_id)
+    if not item:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item ID {item_id} not found"
+        )
+    return item
+
+@router.put("/{item_id}", response_model=ItemResponse)
+async def update_item(
+    item_id: int,
+    item_update: ItemUpdate,
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """item を更新"""
+    updated_item = await crud.update(item_id, item_update)
+    if not updated_item:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item ID {item_id} not found"
+        )
+    return updated_item
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(
+    item_id: int,
+    hard_delete: bool = Query(False, description="Complete delete"),
+    crud: ItemCRUD = Depends(get_item_crud)
+):
+    """item を削除"""
+    if hard_delete:
+        deleted = await crud.hard_delete(item_id)
+    else:
+        deleted = await crud.delete(item_id)
+
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item ID {item_id} not found"
+        )
+```
+
+## ステップ 7: Docker コンテナの起動
+
+### Docker Compose 設定の確認 (`docker-compose.yml`)
+
+```yaml
+version: '3.8'
+
+services:
+  db:
+    image: postgres:15
+    restart: always
+    environment:
+      POSTGRES_DB: todoapp
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  app:
+    build: .
+    restart: always
+    ports:
+      - "8000:8000"
+    environment:
+      POSTGRES_SERVER: db
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: todoapp
+    depends_on:
+      - db
+    volumes:
+      - ./src:/app/src
+
+volumes:
+  postgres_data:
+```
+
+### コンテナの実行
+
+<div class="termy">
+
+```console
+$ cd todo-postgres-api
+
+# サービスをバックグラウンドで起動
+$ docker-compose up -d
+Creating network "todo-postgres-api_default" with the default driver
+Creating volume "todo-postgres-api_postgres_data" with default driver
+Pulling db (postgres:15)...
+Creating todo-postgres-api_db_1 ... done
+Building app
+Creating todo-postgres-api_app_1 ... done
+
+# サービス状態を確認
+$ docker-compose ps
+           Name                          Command              State           Ports
+-------------------------------------------------------------------------------------
+todo-postgres-api_app_1    uvicorn src.main:app --host=0.0.0.0 --port=8000   Up   0.0.0.0:8000->8000/tcp
+todo-postgres-api_db_1     docker-entrypoint.sh postgres   Up   0.0.0.0:5432->5432/tcp
+
+# ログを確認
+$ docker-compose logs app
+```
+
+</div>
+
+## ステップ 8: データベースマイグレーション
+
+### Alembic で初回マイグレーションを作成
+
+<div class="termy">
+
+```console
+# コンテナ内でマイグレーションを実行
+$ docker-compose exec app alembic revision --autogenerate -m "Create items table"
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.autogenerate.compare] Detected added table 'items'
+Generating migration script /app/src/alembic/versions/001_create_items_table.py ... done
+
+# マイグレーションを適用
+$ docker-compose exec app alembic upgrade head
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.runtime.migration] Running upgrade -> 001, Create items table
+```
+
+</div>
+
+### マイグレーションファイルの確認
+
+生成されたマイグレーションファイルを確認します:
+
+```python
+# src/alembic/versions/001_create_items_table.py
+"""Create items table
+
+Revision ID: 001
+Revises:
+Create Date: 2024-01-01 12:00:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+# revision identifiers
+revision = '001'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('items',
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(length=100), nullable=False),
+    sa.Column('description', sqlmodel.sql.sqltypes.AutoString(length=500), nullable=True),
+    sa.Column('price', sa.Float(), nullable=False),
+    sa.Column('tax', sa.Float(), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_items_name'), 'items', ['name'], unique=False)
+    # ### end Alembic commands ###
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_items_name'), table_name='items')
+    op.drop_table('items')
+    # ### end Alembic commands ###
+```
+
+## ステップ 9: API テスト
+
+### 基本的な CRUD テスト
+
+<div class="termy">
+
+```console
+# 新しい item を作成
+$ curl -X POST "http://localhost:8000/items/" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "MacBook Pro",
+    "description": "M2 chipset-equipped high-performance notebook",
+    "price": 2500000,
+    "tax": 250000
+  }'
+
+{
+  "id": 1,
+  "name": "MacBook Pro",
+  "description": "M2 chipset-equipped high-performance notebook",
+  "price": 2500000.0,
+  "tax": 250000.0,
+  "is_active": true,
+  "created_at": "2024-01-01T12:00:00.123456",
+  "updated_at": null
+}
+
+# item の一覧を取得
+$ curl "http://localhost:8000/items/"
+
+# ページネーション付きで一覧を取得
+$ curl "http://localhost:8000/items/?skip=0&limit=10"
+
+# item を検索
+$ curl "http://localhost:8000/items/search?q=MacBook"
+
+# item の合計数を取得
+$ curl "http://localhost:8000/items/count"
+{"total": 1}
+```
+
+</div>
+
+### 高度なクエリ機能のテスト
+
+<div class="termy">
+
+```console
+# 非アクティブの item も含めて取得
+$ curl "http://localhost:8000/items/?active_only=false"
+
+# item を更新
+$ curl -X PUT "http://localhost:8000/items/1" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "price": 2300000,
+    "tax": 230000
+  }'
+
+# item を論理削除
+$ curl -X DELETE "http://localhost:8000/items/1"
+
+# item を物理削除
+$ curl -X DELETE "http://localhost:8000/items/1?hard_delete=true"
+```
+
+</div>
+
+## ステップ 10: 高度なデータベース機能
+
+### トランザクション処理
+
+```python
+# src/crud/items.py に追加
+
+from sqlalchemy.exc import SQLAlchemyError
+
+async def create_items_batch(self, items_create: List[ItemCreate]) -> List[Item]:
+    """複数の item を 1 つのトランザクションで作成"""
+    created_items = []
+
+    try:
+        for item_create in items_create:
+            db_item = Item(**item_create.dict())
+            self.db.add(db_item)
+            created_items.append(db_item)
+
+        await self.db.commit()
+
+        # すべての item をリフレッシュ
+        for item in created_items:
+            await self.db.refresh(item)
+
+        return created_items
+
+    except SQLAlchemyError:
+        await self.db.rollback()
+        raise
+```
+
+### リレーショナルデータモデリング
+
+```python
+# src/schemas/items.py に追加
+
+from sqlmodel import Relationship
+
+class Category(SQLModel, table=True):
+    __tablename__ = "categories"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(max_length=50, unique=True)
+    description: Optional[str] = None
+
+    # リレーションの設定
+    items: List["Item"] = Relationship(back_populates="category")
+
+class Item(ItemBase, table=True):
+    __tablename__ = "items"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: Optional[datetime] = Field(default=None)
+
+    # 外部キーの追加
+    category_id: Optional[int] = Field(foreign_key="categories.id")
+
+    # リレーションの設定
+    category: Optional[Category] = Relationship(back_populates="items")
+```
+
+### インデックスの最適化
+
+```python
+# src/schemas/items.py に追加
+
+from sqlalchemy import Index
+
+class Item(ItemBase, table=True):
+    __tablename__ = "items"
+
+    # ... 既存フィールド ...
+
+    # 複合インデックスの設定
+    __table_args__ = (
+        Index('ix_items_price_active', 'price', 'is_active'),
+        Index('ix_items_created_at', 'created_at'),
+        Index('ix_items_name_description', 'name', 'description'),  # 全文検索用
+    )
+```
+
+## ステップ 11: テストの作成
+
+### データベーステストの設定 (`tests/conftest.py`)
+
+```python
+import pytest
+import asyncio
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+from sqlmodel import SQLModel
+
+from src.main import app
+from src.core.db import get_session
+from src.core.config import settings
+
+# テスト用データベースエンジン
+test_engine = create_async_engine(
+    settings.TEST_DATABASE_URL or "sqlite+aiosqlite:///./test.db",
+    echo=False,
+)
+
+TestSessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=test_engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+@pytest.fixture(scope="session")
+def event_loop():
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture(scope="function")
+async def db_session():
+    # テスト用テーブルを作成
+    async with test_engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    # セッションを提供
+    async with TestSessionLocal() as session:
+        yield session
+
+    # テスト後にテーブルを削除
+    async with test_engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.drop_all)
+
+@pytest.fixture
+async def client(db_session: AsyncSession):
+    # 依存性をオーバーライド
+    async def override_get_session():
+        yield db_session
+
+    app.dependency_overrides[get_session] = override_get_session
+
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+    app.dependency_overrides.clear()
+```
+
+### 統合テスト (`tests/test_items.py`)
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_and_read_item(client: AsyncClient):
+    """item の作成と取得の統合テスト"""
+    # item を作成
+    item_data = {
+        "name": "Test Item",
+        "description": "Database test",
+        "price": 50000,
+        "tax": 5000
+    }
+
+    response = await client.post("/items/", json=item_data)
+    assert response.status_code == 201
+
+    created_item = response.json()
+    assert created_item["name"] == item_data["name"]
+    assert "id" in created_item
+    assert "created_at" in created_item
+
+    # 作成した item を取得
+    item_id = created_item["id"]
+    response = await client.get(f"/items/{item_id}")
+    assert response.status_code == 200
+
+    retrieved_item = response.json()
+    assert retrieved_item["id"] == item_id
+    assert retrieved_item["name"] == item_data["name"]
+
+@pytest.mark.asyncio
+async def test_item_pagination(client: AsyncClient):
+    """ページネーション機能のテスト"""
+    # 複数の item を作成
+    for i in range(15):
+        item_data = {
+            "name": f"Item {i}",
+            "description": f"Description {i}",
+            "price": i * 1000,
+            "tax": i * 100
+        }
+        await client.post("/items/", json=item_data)
+
+    # 最初のページを取得
+    response = await client.get("/items/?skip=0&limit=10")
+    assert response.status_code == 200
+
+    items = response.json()
+    assert len(items) == 10
+
+    # 2 ページ目を取得
+    response = await client.get("/items/?skip=10&limit=10")
+    assert response.status_code == 200
+
+    items = response.json()
+    assert len(items) == 5
+
+@pytest.mark.asyncio
+async def test_item_search(client: AsyncClient):
+    """検索機能のテスト"""
+    # テスト用の item を作成
+    items = [
+        {"name": "iPhone 15", "description": "Latest smartphone", "price": 1200000, "tax": 120000},
+        {"name": "Galaxy S24", "description": "Samsung flagship", "price": 1100000, "tax": 110000},
+        {"name": "MacBook Air", "description": "Apple notebook", "price": 1500000, "tax": 150000},
+    ]
+
+    for item in items:
+        await client.post("/items/", json=item)
+
+    # 「iPhone」で検索
+    response = await client.get("/items/search?q=iPhone")
+    assert response.status_code == 200
+
+    results = response.json()
+    assert len(results) == 1
+    assert results[0]["name"] == "iPhone 15"
+
+    # 「smartphone」で検索 (description にヒット)
+    response = await client.get("/items/search?q=smartphone")
+    assert response.status_code == 200
+
+    results = response.json()
+    assert len(results) == 1
+    assert results[0]["description"] == "Latest smartphone"
+```
+
+### テストの実行
+
+<div class="termy">
+
+```console
+# コンテナ内でテストを実行
+$ docker-compose exec app python -m pytest tests/ -v
+======================== test session starts ========================
+collected 12 items
+
+tests/test_items.py::test_create_and_read_item PASSED         [ 8%]
+tests/test_items.py::test_item_pagination PASSED             [16%]
+tests/test_items.py::test_item_search PASSED                 [25%]
+tests/test_items.py::test_update_item PASSED                 [33%]
+tests/test_items.py::test_delete_item PASSED                 [41%]
+tests/test_items.py::test_soft_delete PASSED                 [50%]
+tests/test_items.py::test_item_not_found PASSED              [58%]
+tests/test_items.py::test_invalid_item_data PASSED           [66%]
+tests/test_items.py::test_database_transaction PASSED        [75%]
+tests/test_items.py::test_concurrent_operations PASSED       [83%]
+tests/test_items.py::test_item_count PASSED                  [91%]
+tests/test_items.py::test_batch_operations PASSED           [100%]
+
+======================== 12 passed in 2.34s ========================
+```
+
+</div>
+
+## ステップ 12: 本番デプロイの考慮事項
+
+### コネクションプールの最適化
+
+```python
+# src/core/config.py に追加
+
+class Settings(BaseSettings):
+    # ... 既存設定 ...
+
+    # データベースコネクションプール設定
+    DB_POOL_SIZE: int = 20
+    DB_MAX_OVERFLOW: int = 0
+    DB_POOL_PRE_PING: bool = True
+    DB_POOL_RECYCLE: int = 300  # 5 分
+
+    # クエリタイムアウト
+    DB_QUERY_TIMEOUT: int = 30
+
+    # 接続リトライ設定
+    DB_RETRY_ATTEMPTS: int = 3
+    DB_RETRY_DELAY: int = 1
+```
+
+### データベース監視
+
+```python
+# src/core/db.py に追加
+
+import logging
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+
+logger = logging.getLogger(__name__)
+
+@event.listens_for(Engine, "before_cursor_execute")
+def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
+    """クエリ実行前のログ"""
+    context._query_start_time = time.time()
+
+@event.listens_for(Engine, "after_cursor_execute")
+def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
+    """クエリ実行後のログ"""
+    total = time.time() - context._query_start_time
+    if total > 1.0:  # 遅いクエリをログ (1 秒以上)
+        logger.warning(f"Slow query: {total:.2f}s - {statement[:100]}...")
+```
+
+## 次のステップ
+
+PostgreSQL データベース統合が完了しました! 次に試すこと:
+
+1. **[Docker でのデプロイ](docker-deployment.md)** - 本番デプロイ環境の構築
+2. **[カスタムレスポンス処理](custom-response-handling.md)** - 高度な API レスポンス形式
+<!-- 3. **[Building Authentication Systems](authentication-system.md)** - JWT-based user authentication -->
+<!-- 4. **[Building Caching Systems](caching-system.md)** - Performance optimization with Redis -->
+
+## まとめ
+
+このチュートリアルでは、PostgreSQL と SQLAlchemy を使って次を行いました:
+
+- ✅ PostgreSQL データベースを統合
+- ✅ SQLModel で ORM を実装
+- ✅ Alembic マイグレーションシステムをセットアップ
+- ✅ 高度な CRUD 操作とクエリ最適化
+- ✅ トランザクション処理とデータ整合性
+- ✅ ページネーション、検索、ソート機能
+- ✅ 統合テストとデータベーステスト
+- ✅ 本番デプロイの考慮事項
+
+これで、本番環境でも使える堅牢なデータベース駆動 API を構築できます。
diff --git a/docs/ja/tutorial/docker-deployment.md b/docs/ja/tutorial/docker-deployment.md
new file mode 100644
index 0000000..2ec8f24
--- /dev/null
+++ b/docs/ja/tutorial/docker-deployment.md
@@ -0,0 +1,1177 @@
+# Docker でのコンテナ化とデプロイ
+
+FastAPI アプリケーションを Docker でコンテナ化して、一貫した開発環境と本番デプロイの準備を整える方法を学びます。`fastapi-dockerized` テンプレートを使い、完全な Docker ベースのデプロイ環境を構築します。
+
+## このチュートリアルで学ぶこと
+
+- Docker による FastAPI アプリケーションのコンテナ化
+- マルチステージビルドで最適化された Docker イメージの作成
+- Docker Compose による開発環境のセットアップ
+- 本番デプロイ向けの Docker 構成
+- コンテナ監視とログ管理
+- CI/CD パイプラインの構築
+
+## 前提条件
+
+- [データベース統合チュートリアル](database-integration.md) を完了済み
+- Docker と Docker Compose がインストール済み
+- 基本的な Docker コマンドの理解
+- コンテナの基礎概念
+
+## Docker コンテナ化の利点
+
+### 従来手法と Docker 手法の比較
+
+| 項目 | 従来手法 | Docker 手法 |
+|---|---|---|
+| **環境の一貫性** | 環境ごとに差異 | どこでも同じ環境 |
+| **依存関係管理** | 手動インストールが必要 | すべての依存関係をイメージに含む |
+| **デプロイ速度** | 遅い | 高速デプロイが可能 |
+| **拡張性** | 限定的 | 容易にスケール |
+| **ロールバック** | 複雑 | 直前バージョンへ即座に戻せる |
+| **リソース利用** | 重い | 軽量なコンテナ |
+
+## ステップ 1: Docker ベースプロジェクトの作成
+
+`fastapi-dockerized` テンプレートでプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-dockerized
+Enter the project name: dockerized-todo-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: Dockerized todo management API
+Deploying FastAPI project using 'fastapi-dockerized' template
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────────┐
+│ Project Name │ dockerized-todo-api                         │
+│ Author       │ Developer Kim                               │
+│ Author Email │ developer@example.com                       │
+│ Description  │ Dockerized todo management API              │
+└──────────────┴─────────────────────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+│ Dependency 5 │ python-dotenv     │
+└──────────────┴───────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'dockerized-todo-api' from 'fastapi-dockerized' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: Docker 設定ファイルの解析
+
+生成プロジェクトに含まれる Docker 関連ファイルを見ていきましょう:
+
+```
+dockerized-todo-api/
+├── Dockerfile                    # Docker イメージのビルド設定
+├── docker-compose.yml           # 開発環境のコンテナ構成
+├── docker-compose.prod.yml      # 本番環境の構成
+├── .dockerignore               # Docker ビルドから除外するファイル
+├── scripts/
+│   ├── start.sh                # コンテナ起動スクリプト
+│   ├── prestart.sh             # 起動前の初期化スクリプト
+│   └── gunicorn.conf.py        # Gunicorn 設定
+├── src/
+│   ├── main.py                 # FastAPI アプリ
+│   └── ...                     # その他のソースコード
+└── requirements.txt            # Python 依存関係
+```
+
+### Dockerfile の解析
+
+```dockerfile
+# マルチステージビルドで最適化した Dockerfile
+
+# ============================================
+# ステージ 1: ビルドステージ
+# ============================================
+FROM python:3.12-slim as builder
+
+# ビルドツールをインストール
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 依存関係ファイルをコピーしてインストール
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# ============================================
+# ステージ 2: ランタイムステージ
+# ============================================
+FROM python:3.12-slim
+
+# システム更新と必要パッケージのインストール
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# 非 root ユーザーを作成 (セキュリティ強化)
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+
+# アプリケーションディレクトリを作成
+WORKDIR /app
+
+# ビルドステージから Python パッケージをコピー
+COPY --from=builder /root/.local /home/appuser/.local
+
+# アプリケーションコードをコピー
+COPY . .
+
+# ファイル権限を設定
+RUN chown -R appuser:appuser /app
+RUN chmod +x scripts/start.sh scripts/prestart.sh
+
+# Python パッケージのパスを PATH に追加
+ENV PATH=/home/appuser/.local/bin:$PATH
+
+# 非 root ユーザーへ切り替え
+USER appuser
+
+# ヘルスチェックを設定
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# ポートを公開
+EXPOSE 8000
+
+# 起動スクリプトを実行
+CMD ["./scripts/start.sh"]
+```
+
+### Docker Compose 開発環境 (`docker-compose.yml`)
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: dockerized-todo-api
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      - ENVIRONMENT=development
+      - DEBUG=true
+      - RELOAD=true
+    volumes:
+      # 開発用にボリュームをマウント (コード変更で自動リロード)
+      - ./src:/app/src:ro
+      - ./scripts:/app/scripts:ro
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # Redis (キャッシュとセッションストア用)
+  redis:
+    image: redis:7-alpine
+    container_name: dockerized-todo-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  # Nginx (リバースプロキシ)
+  nginx:
+    image: nginx:alpine
+    container_name: dockerized-todo-nginx
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./nginx/ssl:/etc/nginx/ssl:ro
+    depends_on:
+      - app
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  redis_data:
+
+networks:
+  app-network:
+    driver: bridge
+```
+
+### Docker Compose 本番環境 (`docker-compose.prod.yml`)
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: always
+    environment:
+      - ENVIRONMENT=production
+      - DEBUG=false
+      - WORKERS=4
+      - MAX_WORKERS=8
+    volumes:
+      - app_logs:/app/logs
+    networks:
+      - app-network
+    deploy:
+      replicas: 2
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 1G
+        reservations:
+          cpus: '0.5'
+          memory: 512M
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 3
+
+  redis:
+    image: redis:7-alpine
+    restart: always
+    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
+    volumes:
+      - redis_data:/data
+    networks:
+      - app-network
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+
+  nginx:
+    image: nginx:alpine
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/nginx.prod.conf:/etc/nginx/nginx.conf:ro
+      - ./nginx/ssl:/etc/nginx/ssl:ro
+      - nginx_logs:/var/log/nginx
+    depends_on:
+      - app
+    networks:
+      - app-network
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 256M
+
+volumes:
+  redis_data:
+  app_logs:
+  nginx_logs:
+
+networks:
+  app-network:
+    driver: overlay
+    attachable: true
+```
+
+## ステップ 3: 起動スクリプトの設定
+
+### メイン起動スクリプト (`scripts/start.sh`)
+
+```bash
+#!/bin/bash
+
+set -e
+
+# 環境変数を設定
+export PYTHONPATH=/app:$PYTHONPATH
+
+# 起動前スクリプトを実行
+echo "Running pre-start script..."
+./scripts/prestart.sh
+
+# 環境に応じて実行モードを決定
+if [[ "$ENVIRONMENT" == "production" ]]; then
+    echo "Starting production server with Gunicorn..."
+    exec gunicorn src.main:app \
+        --config scripts/gunicorn.conf.py \
+        --bind 0.0.0.0:8000 \
+        --workers ${WORKERS:-4} \
+        --worker-class uvicorn.workers.UvicornWorker \
+        --max-requests 1000 \
+        --max-requests-jitter 100 \
+        --preload \
+        --access-logfile - \
+        --error-logfile -
+else
+    echo "Starting development server with Uvicorn..."
+    if [[ "$RELOAD" == "true" ]]; then
+        exec uvicorn src.main:app \
+            --host 0.0.0.0 \
+            --port 8000 \
+            --reload \
+            --reload-dir src \
+            --log-level debug
+    else
+        exec uvicorn src.main:app \
+            --host 0.0.0.0 \
+            --port 8000 \
+            --log-level info
+    fi
+fi
+```
+
+### 起動前スクリプト (`scripts/prestart.sh`)
+
+```bash
+#!/bin/bash
+
+set -e
+
+echo "Running pre-start checks..."
+
+# Python モジュールと依存関係をチェック
+echo "Checking Python dependencies..."
+python -c "import fastapi, uvicorn, pydantic; print('✓ Core dependencies OK')"
+
+# 環境変数を確認
+if [[ -z "$ENVIRONMENT" ]]; then
+    export ENVIRONMENT="development"
+    echo "ℹ ENVIRONMENT not set, defaulting to development"
+fi
+
+# ログディレクトリを作成
+mkdir -p /app/logs
+touch /app/logs/app.log
+
+# health エンドポイントが存在するか確認
+echo "Checking health endpoint..."
+python -c "
+from src.main import app
+routes = [route.path for route in app.routes]
+if '/health' not in routes:
+    print('⚠ Warning: /health endpoint not found')
+else:
+    print('✓ Health endpoint OK')
+"
+
+echo "Pre-start checks completed successfully!"
+```
+
+### Gunicorn 設定 (`scripts/gunicorn.conf.py`)
+
+```python
+import multiprocessing
+import os
+
+# サーバーソケット
+bind = "0.0.0.0:8000"
+backlog = 2048
+
+# ワーカープロセス
+workers = int(os.getenv("WORKERS", multiprocessing.cpu_count() * 2 + 1))
+worker_class = "uvicorn.workers.UvicornWorker"
+worker_connections = 1000
+max_requests = 1000
+max_requests_jitter = 100
+
+# ワーカー再起動設定
+preload_app = True
+timeout = 120
+keepalive = 2
+
+# ロギング
+accesslog = "-"
+errorlog = "-"
+loglevel = "info"
+access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'
+
+# プロセス名
+proc_name = "dockerized-todo-api"
+
+# セキュリティ
+limit_request_line = 4094
+limit_request_fields = 100
+limit_request_field_size = 8190
+
+# パフォーマンスチューニング
+def when_ready(server):
+    server.log.info("Server is ready. Spawning workers")
+
+def worker_int(worker):
+    worker.log.info("worker received INT or QUIT signal")
+
+def pre_fork(server, worker):
+    server.log.info("Worker spawned (pid: %s)", worker.pid)
+
+def post_fork(server, worker):
+    server.log.info("Worker spawned (pid: %s)", worker.pid)
+
+def worker_abort(worker):
+    worker.log.info("worker received SIGABRT signal")
+```
+
+## ステップ 4: ヘルスチェックとモニタリングの実装
+
+### ヘルスチェックエンドポイントを追加 (`src/main.py`)
+
+```python
+from fastapi import FastAPI, status, Depends
+from fastapi.responses import JSONResponse
+import psutil
+import time
+from datetime import datetime
+
+app = FastAPI(
+    title="Dockerized Todo API",
+    description="Dockerized todo management API",
+    version="1.0.0"
+)
+
+# アプリケーション開始時刻
+start_time = time.time()
+
+@app.get("/health", status_code=status.HTTP_200_OK)
+async def health_check():
+    """
+    コンテナのヘルスチェックエンドポイント
+    """
+    current_time = time.time()
+    uptime = current_time - start_time
+
+    # システムリソース情報
+    memory_info = psutil.virtual_memory()
+    cpu_percent = psutil.cpu_percent(interval=1)
+
+    health_data = {
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+        "uptime_seconds": round(uptime, 2),
+        "version": app.version,
+        "system": {
+            "memory_usage_percent": memory_info.percent,
+            "memory_available_mb": round(memory_info.available / 1024 / 1024, 2),
+            "cpu_usage_percent": cpu_percent,
+        },
+        "checks": {
+            "database": await check_database_connection(),
+            "redis": await check_redis_connection(),
+            "disk_space": check_disk_space(),
+        }
+    }
+
+    # すべてのチェックが通ったか確認
+    all_checks_passed = all(health_data["checks"].values())
+
+    if not all_checks_passed:
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content=health_data
+        )
+
+    return health_data
+
+async def check_database_connection() -> bool:
+    """データベース接続状態を確認"""
+    try:
+        # 実装ではデータベース接続をテストする
+        return True
+    except Exception:
+        return False
+
+async def check_redis_connection() -> bool:
+    """Redis 接続状態を確認"""
+    try:
+        # 実装では Redis 接続をテストする
+        return True
+    except Exception:
+        return False
+
+def check_disk_space() -> bool:
+    """ディスク空き容量を確認"""
+    disk_usage = psutil.disk_usage('/')
+    free_percentage = (disk_usage.free / disk_usage.total) * 100
+    return free_percentage > 10  # 10% 以上の空きが必要
+
+@app.get("/health/ready", status_code=status.HTTP_200_OK)
+async def readiness_check():
+    """
+    Kubernetes readiness プローブのエンドポイント
+    """
+    # アプリケーションがトラフィックを受け入れる準備ができているか確認
+    return {"status": "ready", "timestamp": datetime.utcnow().isoformat()}
+
+@app.get("/health/live", status_code=status.HTTP_200_OK)
+async def liveness_check():
+    """
+    Kubernetes liveness プローブのエンドポイント
+    """
+    return {"status": "alive", "timestamp": datetime.utcnow().isoformat()}
+```
+
+## ステップ 5: Nginx リバースプロキシの構成
+
+### 開発環境の Nginx 設定 (`nginx/nginx.conf`)
+
+```nginx
+events {
+    worker_connections 1024;
+}
+
+http {
+    upstream fastapi_backend {
+        # コンテナ名でバックエンドを指定
+        server app:8000;
+    }
+
+    # ログフォーマットを定義
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for" '
+                    'rt=$request_time uct="$upstream_connect_time" '
+                    'uht="$upstream_header_time" urt="$upstream_response_time"';
+
+    access_log /var/log/nginx/access.log main;
+    error_log /var/log/nginx/error.log warn;
+
+    # デフォルト設定
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 2048;
+    client_max_body_size 100M;
+
+    # gzip 圧縮
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript
+               application/json application/javascript application/xml+rss
+               application/atom+xml image/svg+xml;
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        # セキュリティヘッダー
+        add_header X-Content-Type-Options nosniff;
+        add_header X-Frame-Options DENY;
+        add_header X-XSS-Protection "1; mode=block";
+
+        # ヘルスチェックエンドポイント
+        location /health {
+            proxy_pass http://fastapi_backend;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+
+            # ヘルスチェックは素早く応答する
+            proxy_connect_timeout 5s;
+            proxy_send_timeout 5s;
+            proxy_read_timeout 5s;
+        }
+
+        # API エンドポイント
+        location / {
+            proxy_pass http://fastapi_backend;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+
+            # タイムアウト設定
+            proxy_connect_timeout 30s;
+            proxy_send_timeout 30s;
+            proxy_read_timeout 30s;
+
+            # バッファ設定
+            proxy_buffering on;
+            proxy_buffer_size 4k;
+            proxy_buffers 8 4k;
+        }
+
+        # 静的ファイルのキャッシュ (将来用)
+        location /static {
+            expires 1y;
+            add_header Cache-Control public;
+            add_header ETag "";
+        }
+    }
+}
+```
+
+### 本番環境の Nginx 設定 (`nginx/nginx.prod.conf`)
+
+```nginx
+events {
+    worker_connections 2048;
+}
+
+http {
+    upstream fastapi_backend {
+        # 複数 app インスタンスのロードバランス
+        server app:8000 max_fails=3 fail_timeout=30s;
+        # server app2:8000 max_fails=3 fail_timeout=30s;  # スケール用
+
+        # Keep-alive
+        keepalive 32;
+    }
+
+    # セキュリティ設定
+    server_tokens off;
+
+    # レート制限
+    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+    limit_req_zone $binary_remote_addr zone=health:10m rate=100r/s;
+
+    # SSL 設定
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    server {
+        listen 80;
+        server_name your-domain.com;
+        return 301 https://$server_name$request_uri;
+    }
+
+    server {
+        listen 443 ssl http2;
+        server_name your-domain.com;
+
+        ssl_certificate /etc/nginx/ssl/cert.pem;
+        ssl_certificate_key /etc/nginx/ssl/key.pem;
+
+        # セキュリティヘッダー
+        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-Frame-Options DENY always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+        # ヘルスチェック (レート制限あり)
+        location /health {
+            limit_req zone=health burst=20 nodelay;
+            proxy_pass http://fastapi_backend;
+            include /etc/nginx/proxy_params;
+        }
+
+        # API エンドポイント (レート制限あり)
+        location / {
+            limit_req zone=api burst=20 nodelay;
+            proxy_pass http://fastapi_backend;
+            include /etc/nginx/proxy_params;
+        }
+    }
+}
+```
+
+## ステップ 6: コンテナのビルドと実行
+
+### 開発環境での実行
+
+<div class="termy">
+
+```console
+$ cd dockerized-todo-api
+
+# Docker イメージをビルド
+$ docker-compose build
+Building app
+Step 1/15 : FROM python:3.12-slim as builder
+ ---> abc123def456
+Step 2/15 : RUN apt-get update && apt-get install -y build-essential curl
+ ---> Running in xyz789abc123
+...
+Successfully built def456ghi789
+Successfully tagged dockerized-todo-api_app:latest
+
+# コンテナをバックグラウンドで起動
+$ docker-compose up -d
+Creating network "dockerized-todo-api_app-network" with driver "bridge"
+Creating volume "dockerized-todo-api_redis_data" with default driver
+Creating dockerized-todo-redis ... done
+Creating dockerized-todo-api   ... done
+Creating dockerized-todo-nginx ... done
+
+# コンテナ状態を確認
+$ docker-compose ps
+        Name                      Command               State                    Ports
+------------------------------------------------------------------------------------------------
+dockerized-todo-api    ./scripts/start.sh               Up (healthy)   8000/tcp
+dockerized-todo-nginx  /docker-entrypoint.sh ngin ...   Up             0.0.0.0:80->80/tcp, :::80->80/tcp
+dockerized-todo-redis  docker-entrypoint.sh redis ...   Up (healthy)   0.0.0.0:6379->6379/tcp, :::6379->6379/tcp
+```
+
+</div>
+
+### ログの確認
+
+<div class="termy">
+
+```console
+# すべてのサービスのログを表示
+$ docker-compose logs
+
+# 特定サービスのログを表示
+$ docker-compose logs app
+$ docker-compose logs nginx
+$ docker-compose logs redis
+
+# リアルタイムログ
+$ docker-compose logs -f app
+```
+
+</div>
+
+### ヘルスチェックのテスト
+
+<div class="termy">
+
+```console
+# 基本のヘルスチェック
+$ curl http://localhost/health
+{
+  "status": "healthy",
+  "timestamp": "2024-01-01T12:00:00.123456",
+  "uptime_seconds": 45.67,
+  "version": "1.0.0",
+  "system": {
+    "memory_usage_percent": 25.3,
+    "memory_available_mb": 3072.45,
+    "cpu_usage_percent": 5.2
+  },
+  "checks": {
+    "database": true,
+    "redis": true,
+    "disk_space": true
+  }
+}
+
+# Kubernetes プローブのテスト
+$ curl http://localhost/health/ready
+$ curl http://localhost/health/live
+```
+
+</div>
+
+## ステップ 7: 本番デプロイ
+
+### 環境変数の設定 (`.env.prod`)
+
+```bash
+# アプリケーション設定
+ENVIRONMENT=production
+DEBUG=false
+SECRET_KEY=your-super-secret-key-here
+WORKERS=4
+
+# データベース設定
+DATABASE_URL=postgresql://user:password@db:5432/todoapp
+REDIS_URL=redis://:password@redis:6379/0
+REDIS_PASSWORD=your-redis-password
+
+# ロギング設定
+LOG_LEVEL=info
+LOG_FILE=/app/logs/app.log
+
+# セキュリティ設定
+ALLOWED_HOSTS=["your-domain.com"]
+CORS_ORIGINS=["https://your-frontend.com"]
+
+# モニタリング
+SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
+```
+
+### 本番デプロイコマンド
+
+<div class="termy">
+
+```console
+# 本番環境にデプロイ
+$ docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
+
+# スケーリング (app インスタンスのスケール)
+$ docker-compose -f docker-compose.prod.yml up -d --scale app=3
+
+# ローリングアップデート
+$ docker-compose -f docker-compose.prod.yml build app
+$ docker-compose -f docker-compose.prod.yml up -d --no-deps app
+
+# バックアップ前の安全な停止
+$ docker-compose -f docker-compose.prod.yml down --timeout 30
+```
+
+</div>
+
+## ステップ 8: モニタリングとロギング
+
+### Docker コンテナのリソース監視
+
+<div class="termy">
+
+```console
+# リアルタイムのリソース使用量を確認
+$ docker stats
+
+CONTAINER ID   NAME                    CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O         PIDS
+abc123def456   dockerized-todo-api     2.34%     128.5MiB / 1GiB       12.55%    1.23MB / 456kB    12.3MB / 4.56MB   15
+def456ghi789   dockerized-todo-nginx   0.12%     12.5MiB / 256MiB      4.88%     456kB / 1.23MB    1.23MB / 456kB    3
+ghi789jkl012   dockerized-todo-redis   1.45%     32.1MiB / 512MiB      6.27%     789kB / 2.34MB    4.56MB / 1.23MB   4
+
+# 特定コンテナの詳細
+$ docker inspect dockerized-todo-api
+
+# コンテナ内部のプロセスを確認
+$ docker-compose exec app ps aux
+```
+
+</div>
+
+### ログ集約と分析
+
+```yaml
+# docker-compose.logging.yml
+version: '3.8'
+
+services:
+  # ELK Stack (ログ集約)
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.6.0
+    environment:
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+    volumes:
+      - elasticsearch_data:/usr/share/elasticsearch/data
+    networks:
+      - logging
+
+  logstash:
+    image: docker.elastic.co/logstash/logstash:8.6.0
+    volumes:
+      - ./logstash/pipeline:/usr/share/logstash/pipeline:ro
+      - ./logstash/config:/usr/share/logstash/config:ro
+    networks:
+      - logging
+    depends_on:
+      - elasticsearch
+
+  kibana:
+    image: docker.elastic.co/kibana/kibana:8.6.0
+    ports:
+      - "5601:5601"
+    environment:
+      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
+    networks:
+      - logging
+    depends_on:
+      - elasticsearch
+
+  # Fluentd (ログ収集)
+  fluentd:
+    image: fluent/fluentd:v1.16-debian-1
+    volumes:
+      - ./fluentd/conf:/fluentd/etc:ro
+      - /var/log:/var/log:ro
+    networks:
+      - logging
+    depends_on:
+      - elasticsearch
+
+volumes:
+  elasticsearch_data:
+
+networks:
+  logging:
+    driver: bridge
+```
+
+### Prometheus メトリクス収集
+
+```python
+# src/monitoring.py
+from prometheus_client import Counter, Histogram, Gauge, generate_latest
+from fastapi import Request, Response
+import time
+
+# メトリクスの定義
+REQUEST_COUNT = Counter(
+    'http_requests_total',
+    'Total HTTP requests',
+    ['method', 'endpoint', 'status_code']
+)
+
+REQUEST_DURATION = Histogram(
+    'http_request_duration_seconds',
+    'HTTP request duration in seconds',
+    ['method', 'endpoint']
+)
+
+ACTIVE_CONNECTIONS = Gauge(
+    'active_connections',
+    'Number of active connections'
+)
+
+async def metrics_middleware(request: Request, call_next):
+    """Prometheus メトリクス収集ミドルウェア"""
+    start_time = time.time()
+    method = request.method
+    endpoint = request.url.path
+
+    ACTIVE_CONNECTIONS.inc()
+
+    try:
+        response = await call_next(request)
+        status_code = response.status_code
+    except Exception as e:
+        status_code = 500
+        raise
+    finally:
+        duration = time.time() - start_time
+        REQUEST_DURATION.labels(method=method, endpoint=endpoint).observe(duration)
+        REQUEST_COUNT.labels(method=method, endpoint=endpoint, status_code=status_code).inc()
+        ACTIVE_CONNECTIONS.dec()
+
+    return response
+
+@app.get("/metrics")
+async def get_metrics():
+    """Prometheus メトリクスエンドポイント"""
+    return Response(generate_latest(), media_type="text/plain")
+```
+
+## ステップ 9: CI/CD パイプラインの構築
+
+### GitHub Actions ワークフロー (`.github/workflows/deploy.yml`)
+
+```yaml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest pytest-asyncio httpx
+
+      - name: Run tests
+        run: |
+          pytest tests/ -v --cov=src --cov-report=xml
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy to production
+        uses: appleboy/ssh-action@v1.0.0
+        with:
+          host: ${{ secrets.PROD_HOST }}
+          username: ${{ secrets.PROD_USERNAME }}
+          key: ${{ secrets.PROD_SSH_KEY }}
+          script: |
+            cd /opt/dockerized-todo-api
+
+            # 新しいイメージをプル
+            docker-compose -f docker-compose.prod.yml pull
+
+            # ローリングアップデート
+            docker-compose -f docker-compose.prod.yml up -d --no-deps app
+
+            # ヘルスチェック
+            sleep 30
+            curl -f http://localhost/health || exit 1
+
+            # 古いイメージを削除
+            docker image prune -f
+```
+
+## ステップ 10: セキュリティの強化
+
+### コンテナのセキュリティ設定
+
+```dockerfile
+# Dockerfile にセキュリティ設定を追加
+
+# 非 root ユーザーで実行
+USER appuser
+
+# 読み取り専用ルートファイルシステム
+# docker run --read-only --tmpfs /tmp dockerized-todo-api
+
+# 権限の制限
+# docker run --cap-drop=ALL dockerized-todo-api
+
+# ネットワーク隔離
+# docker run --network=none dockerized-todo-api
+```
+
+### Docker Compose のセキュリティ設定
+
+```yaml
+# docker-compose.yml にセキュリティ設定を追加
+services:
+  app:
+    # ... 既存の設定 ...
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /app/logs
+    user: "1000:1000"
+```
+
+### シークレットの管理
+
+```yaml
+# docker-compose.yml に secrets 設定を追加
+version: '3.8'
+
+services:
+  app:
+    secrets:
+      - db_password
+      - api_key
+    environment:
+      - DB_PASSWORD_FILE=/run/secrets/db_password
+      - API_KEY_FILE=/run/secrets/api_key
+
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+  api_key:
+    external: true
+```
+
+## 次のステップ
+
+Docker でのコンテナ化が完了しました! 次に試すこと:
+
+1. **[カスタムレスポンス処理](custom-response-handling.md)** - 高度な API レスポンス形式の実装
+<!-- 2. **[Kubernetes Deployment](kubernetes-deployment.md)** - Kubernetes orchestration -->
+<!-- 3. **[Microservices Architecture](microservices-architecture.md)** - Service separation and scaling -->
+<!-- 4. **[Performance Optimization](performance-optimization.md)** - Caching, load balancing, CDN -->
+
+## まとめ
+
+このチュートリアルでは、Docker を使って次を行いました:
+
+- ✅ マルチステージビルドで最適化したコンテナイメージを作成
+- ✅ Docker Compose で開発 / 本番環境を構築
+- ✅ Nginx リバースプロキシとロードバランスを設定
+- ✅ ヘルスチェックとモニタリング体制を構築
+- ✅ CI/CD パイプラインによる自動デプロイを実装
+- ✅ 本番レベルのセキュリティ設定を実施
+- ✅ ログとメトリクス収集の仕組みを構築
+
+これで FastAPI アプリケーションを本番環境へ安全かつ効率的にデプロイできます!
diff --git a/docs/ja/tutorial/domain-starter.md b/docs/ja/tutorial/domain-starter.md
new file mode 100644
index 0000000..16e60b1
--- /dev/null
+++ b/docs/ja/tutorial/domain-starter.md
@@ -0,0 +1,392 @@
+# `fastapi-domain-starter` によるドメイン指向 FastAPI
+
+推奨される現代的なレイアウト — `src/app/domains/` 配下に **ビジネス概念ごとに 1 フォルダ** — を使って、中規模の FastAPI サービスを構築します。このチュートリアルでは `fastapi-domain-starter` テンプレートを最初から最後まで取り上げます。生成方法、各トップレベルパッケージの役割、付属の `items` サンプルの配線、そして次のドメインを追加する手順まで順に確認します。
+
+## 学べること
+
+- `fastkit startdemo fastapi-domain-starter` でプロジェクトを生成する
+- レイアウトにおける `core`、`db`、`domains`、`tests` の役割
+- ドメインを router → service → repository → schemas → models に分割する考え方
+- 新しいドメインを追加するための手順 (items フォルダをコピーし、ルーターを登録)
+- 付属の `/health` エンドポイントと `/api/v1/items` CRUD が、どのようにアプリに組み込まれているか
+
+## 前提条件
+
+- Python 3.12 以上
+- FastAPI-fastkit がインストール済み (`pip install fastapi-fastkit`)
+- 基本的な FastAPI の概念 (パス操作、Pydantic スキーマ、依存性) に慣れていること
+
+これが初めての FastAPI プロジェクトであれば、まず [基本 API サーバーの構築](basic-api-server.md) から始めましょう — そちらはよりシンプルな `fastapi-default` テンプレートを使います。
+
+## ステップ 1: プロジェクトを生成
+
+```console
+$ fastkit startdemo fastapi-domain-starter
+Enter the project name: orders-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: Domain-oriented orders service
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+```
+
+`fastkit` がテンプレートを展開し、プレースホルダを埋め、仮想環境を作成し、依存関係をインストールします。完了したらプロジェクトに入りましょう:
+
+```console
+$ cd orders-api
+$ bash scripts/run-server.sh    # または: uvicorn src.app.main:app --reload
+```
+
+API ドキュメントは <http://127.0.0.1:8000/docs> で提供されます。
+
+## ステップ 2: 生成されるツリー
+
+```
+orders-api/
+├── README.md
+├── pyproject.toml              # PEP 621 メタデータ + [tool.fastapi-fastkit]
+├── requirements.txt            # 固定された依存関係一覧 (テンプレートには両方が含まれます。パッケージを追加した場合は自分で更新)
+├── .env                        # SECRET_KEY、ENVIRONMENT
+├── .gitignore
+├── scripts/
+│   ├── format.sh               # black + isort
+│   ├── lint.sh                 # black --check + isort --check + mypy
+│   ├── run-server.sh           # uvicorn src.app.main:app --reload
+│   └── test.sh                 # pytest
+├── src/
+│   ├── __init__.py
+│   └── app/                    # アプリケーションパッケージ
+│       ├── __init__.py
+│       ├── main.py             # FastAPI() + ミドルウェア + api_router の取り込み
+│       ├── core/               # 横断的な設定
+│       │   ├── __init__.py
+│       │   └── config.py       # pydantic-settings (PROJECT_NAME、CORS、...)
+│       ├── db/                 # 永続化の抽象化
+│       │   ├── __init__.py
+│       │   └── memory.py       # InMemoryStore[T] ジェネリック KV ストア
+│       ├── api/                # トランスポート層のルーティング
+│       │   ├── __init__.py
+│       │   ├── health.py       # GET /health
+│       │   └── router.py       # health + 各ドメインルーターを集約
+│       └── domains/            # ビジネス概念 (1 フォルダにつき 1 概念)
+│           ├── __init__.py
+│           └── items/          # 例題のドメイン
+│               ├── __init__.py
+│               ├── models.py       # @dataclass Item (エンティティ)
+│               ├── schemas.py      # ItemCreate、ItemRead (pydantic)
+│               ├── repository.py   # InMemoryStore を包む ItemRepository
+│               ├── service.py      # ItemService + ItemNotFoundError
+│               └── router.py       # APIRouter(prefix="/items")
+└── tests/
+    ├── __init__.py
+    ├── conftest.py             # TestClient フィクスチャ、ストアリセット
+    ├── test_health.py
+    └── test_items.py
+```
+
+押さえておきたい 2 つの考え方:
+
+1. **`src/app/`** が **アプリケーションパッケージ** です — ランタイムが import するものはすべてここに置かれます。テストもここから import します (`from src.app.main import app`)。外側の `src/` は、プロジェクトを `pip install` 可能にするために存在します。
+2. **`src/app/domains/<concept>/`** が **概念ごとのスライス** です — 各ビジネス概念 (items、orders、users、...) が、自身の router / service / repository / schemas / models だけを所有します。
+
+## ステップ 3: 各トップレベルパッケージの役割
+
+### `src/app/core/` — 設定
+
+横断的なアプリケーション設定をまとめる場所です。付属の `config.py` は `.env` / 環境変数から読み込まれる、pydantic-settings ベースの `Settings` クラスを公開します:
+
+```python
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "<project_name>"
+    ENVIRONMENT: Literal["development", "staging", "production"] = "development"
+    SECRET_KEY: str = secrets.token_urlsafe(32)
+    API_V1_PREFIX: str = "/api/v1"
+    BACKEND_CORS_ORIGINS: ... = []
+    ...
+
+settings = Settings()
+```
+
+`main.py` は `settings.PROJECT_NAME`、`settings.API_V1_PREFIX`、`settings.all_cors_origins` を読み取って FastAPI アプリを配線します。
+
+**`core/` に追加するもの:** どの 1 つのドメインにも特有でないもの — グローバル設定、構造化ロギング、カスタムミドルウェア、セキュリティヘルパなど。
+
+### `src/app/db/` — 永続化の境界
+
+データストアに対する抽象化をまとめる場所です。スターターには `memory.py` が付属しており、エンティティ型に対してジェネリックなプロセスローカルの `InMemoryStore[T]` を提供します。各ドメインの repository は `InMemoryStore` を包むため、後で SQLAlchemy / 非同期ドライバに差し替える際の影響範囲を小さくできます。修正が必要になるのは基本的に repository だけです。
+
+```python
+class InMemoryStore(Generic[T]):
+    def list(self) -> Iterable[T]: ...
+    def get(self, id_: int) -> Optional[T]: ...
+    def add(self, item: T) -> int: ...
+    def replace(self, id_: int, item: T) -> bool: ...
+    def delete(self, id_: int) -> bool: ...
+    def clear(self) -> None: ...
+```
+
+**`db/` を育てるとき:** `InMemoryStore` から本物のデータベースへ移行したら、`session.py` を追加して実際のセッションファクトリを置きます。ドメイン側 repository の内部契約を変えなくて済むよう、公開メソッドの形 (`list` / `get` / `add` / ...) は揃えておきましょう。
+
+### `src/app/api/` — トランスポートルーティング
+
+2 つの要素から構成されます:
+
+- `health.py` — `{"status": "ok"}` を返す `GET /health` を公開する小さな `APIRouter`。副作用がなく、liveness プローブに最適です。
+- `router.py` — **トップレベル集約** です。health ルーターと各ドメインのルーターを取り込み、その単一の `api_router` を `/api/v1` の下にマウントします:
+
+```python
+# src/app/api/router.py
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(items_router.router)
+```
+
+```python
+# src/app/main.py
+app.include_router(api_router, prefix=settings.API_V1_PREFIX)
+```
+
+**ここで集約する理由:** 新しいドメインを追加するとき、`src/app/api/router.py` を編集してそのルーターを登録するだけで済みます。`main.py` は変更不要です。
+
+### `src/app/domains/<concept>/` — ビジネススライス
+
+プロジェクトが大きくなるにつれて、コードの大部分はここに集まります。各ドメインは 5 つのファイルを所有します:
+
+| ファイル | 役割 |
+|---|---|
+| `models.py` | ドメインエンティティ (スターターでは `@dataclass`、後で SQLAlchemy / SQLModel に差し替え可能)。内部の形 — wire 形式ではない。 |
+| `schemas.py` | API の入出力スキーマ (pydantic)。エンティティと分離されているため、ドメインロジックを触らずに wire 形式を進化させられる。 |
+| `repository.py` | データアクセス。ストアをエンティティ型のメソッドで包む。永続化を入れ替える接合点。 |
+| `service.py` | ビジネスロジック。router は `service` を呼び、`repository` を直接呼ばない。ドメイン固有の例外 (例: `ItemNotFoundError`) はここに置く。 |
+| `router.py` | HTTP トランスポート。pydantic スキーマ ↔ サービス呼び出しの変換を行い、ドメイン例外を `HTTPException` に変換する。 |
+
+**依存方向** は `router → service → repository → store` です。各層は自身より下の層にしか依存しません。schemas は router と service が参照し、models は repository と service が参照します。
+
+### `tests/`
+
+ランタイムのレイアウトを反映する形で、振る舞いを固定したいポイントごとに 1 つずつテストモジュールを置きます。スターターに含まれているものは次のとおりです:
+
+- `conftest.py` — テストの間に items ストアをリセットする autouse フィクスチャ、および `TestClient(app)` をラップした `client` フィクスチャ。
+- `test_health.py` — `GET /api/v1/health` が 200 と `{"status": "ok"}` を返すことを検証。
+- `test_items.py` — items エンドポイントの完全な CRUD をカバー。未知の id に対する 404、不正なペイロードに対する 422 を含む。
+
+実行方法:
+
+```console
+$ bash scripts/test.sh         # または: pytest
+```
+
+## ステップ 4: 付属の `items` ドメインを読む
+
+例題ドメインは小さなエンティティに対する CRUD です:
+
+```python
+# src/app/domains/items/models.py
+@dataclass
+class Item:
+    id: int
+    name: str
+    price: float
+    in_stock: bool = True
+```
+
+API スキーマは入力形式と出力形式を分離し、サーバー制御のフィールド (`id`) と検証 (price ≥ 0) を加えられるようになっています:
+
+```python
+# src/app/domains/items/schemas.py
+class ItemCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=120)
+    price: float = Field(ge=0)
+    in_stock: bool = True
+
+class ItemRead(BaseModel):
+    id: int
+    name: str
+    price: float
+    in_stock: bool
+    model_config = ConfigDict(from_attributes=True)
+```
+
+repository はインメモリストアを包み、insert 時に id を割り当てます:
+
+```python
+# src/app/domains/items/repository.py
+class ItemRepository:
+    def __init__(self, store: Optional[InMemoryStore[Item]] = None) -> None:
+        self._store = store if store is not None else _store
+
+    def add(self, name: str, price: float, in_stock: bool = True) -> Item:
+        item = Item(id=0, name=name, price=price, in_stock=in_stock)
+        new_id = self._store.add(item)
+        item.id = new_id
+        return item
+    # list_all / get / replace / delete / reset は省略
+```
+
+service 層はビジネスルールを集約する場所です。今は薄いパススルーにカスタム例外が 1 つあるだけですが、将来のポリシー (「未確定の注文に紐づく item は削除できない」など) はここに置かれます:
+
+```python
+# src/app/domains/items/service.py
+class ItemNotFoundError(Exception): ...
+
+class ItemService:
+    def __init__(self, repository: Optional[ItemRepository] = None) -> None:
+        self._repository = repository if repository is not None else ItemRepository()
+
+    def get_item(self, item_id: int) -> Item:
+        item = self._repository.get(item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item {item_id} does not exist")
+        return item
+    # list_items / create_item / replace_item / delete_item は省略
+```
+
+router だけが HTTP を知る部分です。FastAPI の `Depends(...)` を介して service を受け取るのでテストで差し替えやすく、`ItemNotFoundError` を `HTTPException(404)` にマップしている点に注目してください:
+
+```python
+# src/app/domains/items/router.py
+router = APIRouter(prefix="/items", tags=["items"])
+
+def get_item_service() -> ItemService:
+    return ItemService()
+
+@router.get("/{item_id}", response_model=ItemRead)
+def get_item(item_id: int, service: ItemService = Depends(get_item_service)) -> ItemRead:
+    try:
+        return ItemRead.model_validate(service.get_item(item_id))
+    except ItemNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+```
+
+完全な router は次を公開します:
+
+| メソッド | パス | 動作 |
+|---|---|---|
+| `GET` | `/api/v1/items` | items の一覧 |
+| `GET` | `/api/v1/items/{item_id}` | 1 件取得 |
+| `POST` | `/api/v1/items` | 作成 (201 を返す) |
+| `PUT` | `/api/v1/items/{item_id}` | 置換 |
+| `DELETE` | `/api/v1/items/{item_id}` | 削除 (204 を返す) |
+| `GET` | `/api/v1/health` | Liveness プローブ |
+
+試してみましょう:
+
+```console
+$ curl -X POST http://127.0.0.1:8000/api/v1/items \
+       -H 'Content-Type: application/json' \
+       -d '{"name":"Mug","price":9.5,"in_stock":true}'
+{"id":1,"name":"Mug","price":9.5,"in_stock":true}
+
+$ curl http://127.0.0.1:8000/api/v1/items
+[{"id":1,"name":"Mug","price":9.5,"in_stock":true}]
+
+$ curl http://127.0.0.1:8000/api/v1/items/999
+{"detail":"Item 999 does not exist"}
+```
+
+## ステップ 5: 次のドメインを追加する
+
+スターターは **ドメインの追加がコピーとリネームの操作で済む** ように設計されています。たとえば `items` の隣に `users` ドメインを置きたい場合:
+
+### 1. `items/` フォルダをコピー
+
+```console
+$ cp -r src/app/domains/items src/app/domains/users
+```
+
+### 2. エンティティ、スキーマ、各ファイルのクラス名を書き換える
+
+```python
+# src/app/domains/users/models.py
+from dataclasses import dataclass
+
+@dataclass
+class User:
+    id: int
+    email: str
+    is_active: bool = True
+```
+
+```python
+# src/app/domains/users/schemas.py
+from pydantic import BaseModel, ConfigDict, Field
+
+class UserCreate(BaseModel):
+    # 単純な ``str`` のままにしておけば、このスニペットはそのまま動きます。
+    # pydantic 組み込みのメール検証を使いたい場合は、オプション依存を追加で
+    # 入れて (``pip install 'pydantic[email]'`` — ``email-validator`` が
+    # 入ります)、``str`` を ``EmailStr`` に切り替えてください。
+    email: str = Field(min_length=3, max_length=320)
+    is_active: bool = True
+
+class UserRead(BaseModel):
+    id: int
+    email: str
+    is_active: bool
+    model_config = ConfigDict(from_attributes=True)
+```
+
+`Item → User`、`ItemNotFoundError → UserNotFoundError`、`ItemRepository → UserRepository`、`ItemService → UserService` を `models.py`、`schemas.py`、`repository.py`、`service.py`、`router.py` の全体でリネームします。router 内の `prefix="/items"` を `prefix="/users"` に、`tags=["items"]` を `tags=["users"]` に変更するのも忘れずに。
+
+repository は同じく `InMemoryStore` ベースのパターンをそのまま流用できます — エンティティ型に対してジェネリックだからです:
+
+```python
+# src/app/domains/users/repository.py
+_store: InMemoryStore[User] = InMemoryStore()
+
+class UserRepository:
+    def __init__(self, store: Optional[InMemoryStore[User]] = None) -> None:
+        self._store = store if store is not None else _store
+    # ... ItemRepository と同じ形 ...
+```
+
+### 3. ドメインの `__init__.py` を更新する
+
+items ドメインは、呼び出し側が `from src.app.domains.items import service` と書けるよう、自身のモジュールを再エクスポートしています。users でも同様にミラーします:
+
+```python
+# src/app/domains/users/__init__.py
+from src.app.domains.users import (  # noqa: F401
+    models,
+    repository,
+    router,
+    schemas,
+    service,
+)
+```
+
+### 4. 集約点に router を登録する
+
+これが **`domains/users/` の外で唯一触る必要のあるファイル** です:
+
+```python
+# src/app/api/router.py
+from src.app.api import health
+from src.app.domains.items import router as items_router
+from src.app.domains.users import router as users_router  # ← 追加
+
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(items_router.router)
+api_router.include_router(users_router.router)             # ← 追加
+```
+
+サーバーを再起動すると、`/docs` に `/api/v1/users` がマウントされます。
+
+### 5. テストを追加する
+
+`tests/test_items.py` をミラーして `tests/test_users.py` を作成します — クライアント駆動の同じ形のまま、新しいエンドポイントを叩くだけです。`conftest.py` の autouse なストアリセットフィクスチャが、各テストを引き続き分離してくれます。
+
+`InMemoryStore` を使う 2 つ目のドメインを追加する場合は、フィクスチャを拡張してそのストアもリセットするか、ドメインごとにフィクスチャを分けてください。
+
+## ステップ 6: 次に学ぶこと
+
+- [アーキテクチャプリセットマトリクス](../reference/preset-feature-matrix.md) は、`fastkit init --interactive` がプリセットごとに何を生成するかを示しています。`domain-starter` のもとで手動配線が必要な機能選択も確認できます。
+- [`fastapi-default` チュートリアル](basic-api-server.md) は、レイアウトを比較した上でコミットしたい場合のレイヤー型オルタナティブをカバーします。
+- データベース統合については、[データベース統合チュートリアル](database-integration.md) で PostgreSQL + SQLAlchemy + Alembic のパターンを示しています。同じ考え方が `src/app/db/` とドメインごとの `repository.py` に当てはまります。
+
+## まとめ
+
+- **生成**: `fastkit startdemo fastapi-domain-starter` → `bash scripts/run-server.sh` → ドキュメントは `/docs`。
+- **レイアウト**: 設定は `core/`、永続化抽象化は `db/`、ビジネススライスは `domains/<concept>/`、唯一の集約点が `api/router.py`、`tests/` はランタイムモジュールをミラー。
+- **ドメインの追加**: `items/` をコピー、エンティティ / スキーマ / クラスをリネーム、`__init__.py` の再エクスポートを更新、`src/app/api/router.py` で router を登録、テストモジュールを追加。`main.py` の編集は不要です。
diff --git a/docs/ja/tutorial/first-project.md b/docs/ja/tutorial/first-project.md
new file mode 100644
index 0000000..7e7cc03
--- /dev/null
+++ b/docs/ja/tutorial/first-project.md
@@ -0,0 +1,1252 @@
+# 最初のプロジェクト
+
+FastAPI-fastkit を使って、ユーザー管理・投稿作成・コメント機能を備えた完全なブログ API を構築します。
+
+## プロジェクト概要
+
+このチュートリアルでは、次の機能を持つ **ブログ API** を作成します:
+
+- **ユーザー管理**: ユーザー登録、認証、プロフィール
+- **投稿管理**: ブログ投稿の作成・取得・更新・削除
+- **コメント機能**: ブログ投稿にコメントを追加
+- **データ検証**: 堅牢な入力検証とエラー処理
+- **API ドキュメント**: 自動 OpenAPI ドキュメント
+- **テスト**: 包括的なテストスイート
+
+### 学べること
+
+このチュートリアルを終えると、次が理解できます:
+
+- FastAPI-fastkit プロジェクトの応用的な構造
+- SQLAlchemy によるデータベース統合
+- ユーザー認証と認可
+- 複雑なデータ関係
+- エラー処理と検証
+- テストのベストプラクティス
+
+## 前提条件
+
+開始前に、次が用意されていることを確認してください:
+
+- [はじめに](getting-started.md) チュートリアルを完了済み
+- REST API の基本理解
+- Python 3.12 以上がインストール済み
+- テキストエディタまたは IDE が利用可能
+
+## ステップ 1: プロジェクトの作成
+
+データベース対応を含めるため、**STANDARD** スタックで新しいプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: blog-api
+Enter the author name: Your Name
+Enter the author email: your.email@example.com
+Enter the project description: A complete blog API with users, posts, and comments
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────┐
+│ Project Name │ blog-api                                │
+│ Author       │ Your Name                               │
+│ Author Email │ your.email@example.com                  │
+│ Description  │ A complete blog API with users, posts,  │
+│              │ and comments                            │
+└──────────────┴─────────────────────────────────────────┘
+
+Available Stacks and Dependencies:
+           MINIMAL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+           STANDARD Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ pydantic          │
+│ Dependency 7 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+Select stack (minimal, standard, full): standard
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'blog-api' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: プロジェクトのセットアップ
+
+プロジェクトに移動し、仮想環境を有効化します:
+
+<div class="termy">
+
+```console
+$ cd blog-api
+$ source .venv/bin/activate
+```
+
+</div>
+
+## ステップ 3: 必要なルートを追加
+
+ブログ API のメインリソースを追加しましょう:
+
+<div class="termy">
+
+```console
+$ fastkit addroute users blog-api
+✨ Successfully added new route 'users' to project 'blog-api'
+
+$ fastkit addroute posts blog-api
+✨ Successfully added new route 'posts' to project 'blog-api'
+
+$ fastkit addroute comments blog-api
+✨ Successfully added new route 'comments' to project 'blog-api'
+```
+
+</div>
+
+## ステップ 4: データモデルの設計
+
+データスキーマを設計します。より実用的な内容にするため、まずユーザースキーマを更新しましょう。
+
+### ユーザースキーマの更新
+
+`src/schemas/users.py` を編集します:
+
+```python
+from typing import Optional, List
+from datetime import datetime
+from pydantic import BaseModel, EmailStr, Field
+
+class UserBase(BaseModel):
+    email: EmailStr
+    username: str = Field(..., min_length=3, max_length=50)
+    full_name: Optional[str] = None
+    bio: Optional[str] = Field(None, max_length=500)
+    is_active: bool = True
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+class UserUpdate(BaseModel):
+    email: Optional[EmailStr] = None
+    username: Optional[str] = Field(None, min_length=3, max_length=50)
+    full_name: Optional[str] = None
+    bio: Optional[str] = Field(None, max_length=500)
+    is_active: Optional[bool] = None
+
+class User(UserBase):
+    id: int
+    created_at: datetime
+    posts_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+class UserInDB(User):
+    hashed_password: str
+```
+
+### 投稿スキーマの作成
+
+`src/schemas/posts.py` を編集します:
+
+```python
+from typing import Optional, List
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+class PostBase(BaseModel):
+    title: str = Field(..., min_length=1, max_length=200)
+    content: str = Field(..., min_length=1)
+    published: bool = True
+
+class PostCreate(PostBase):
+    pass
+
+class PostUpdate(BaseModel):
+    title: Optional[str] = Field(None, min_length=1, max_length=200)
+    content: Optional[str] = Field(None, min_length=1)
+    published: Optional[bool] = None
+
+class Post(PostBase):
+    id: int
+    author_id: int
+    created_at: datetime
+    updated_at: datetime
+    comments_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+class PostWithAuthor(Post):
+    author: "User"
+
+class PostWithComments(Post):
+    comments: List["Comment"] = []
+
+# 循環インポートを避けるためのインポート
+from src.schemas.users import User
+from src.schemas.comments import Comment
+PostWithAuthor.model_rebuild()
+PostWithComments.model_rebuild()
+```
+
+### コメントスキーマの作成
+
+`src/schemas/comments.py` を編集します:
+
+```python
+from typing import Optional
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+class CommentBase(BaseModel):
+    content: str = Field(..., min_length=1, max_length=1000)
+
+class CommentCreate(CommentBase):
+    post_id: int
+
+class CommentUpdate(BaseModel):
+    content: Optional[str] = Field(None, min_length=1, max_length=1000)
+
+class Comment(CommentBase):
+    id: int
+    post_id: int
+    author_id: int
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+class CommentWithAuthor(Comment):
+    author: "User"
+
+# 循環インポートを避けるためのインポート
+from src.schemas.users import User
+CommentWithAuthor.model_rebuild()
+```
+
+## ステップ 5: 高度な CRUD 操作の実装
+
+### ユーザー CRUD の拡張
+
+`src/crud/users.py` を更新します:
+
+```python
+from typing import List, Optional
+from datetime import datetime
+import hashlib
+from src.schemas.users import UserCreate, UserUpdate, UserInDB
+
+class UsersCRUD:
+    def __init__(self):
+        self._users: List[UserInDB] = []
+        self._next_id = 1
+
+    def _hash_password(self, password: str) -> str:
+        """シンプルなパスワードハッシュ (本番では bcrypt を使用)"""
+        return hashlib.sha256(password.encode()).hexdigest()
+
+    def _verify_password(self, plain_password: str, hashed_password: str) -> bool:
+        """ハッシュとパスワードを照合"""
+        return self._hash_password(plain_password) == hashed_password
+
+    def get_all(self) -> List[UserInDB]:
+        """すべてのユーザーを取得"""
+        return [user for user in self._users if user.is_active]
+
+    def get_by_id(self, user_id: int) -> Optional[UserInDB]:
+        """ID でユーザーを取得"""
+        return next((user for user in self._users if user.id == user_id), None)
+
+    def get_by_email(self, email: str) -> Optional[UserInDB]:
+        """メールアドレスでユーザーを取得"""
+        return next((user for user in self._users if user.email == email), None)
+
+    def get_by_username(self, username: str) -> Optional[UserInDB]:
+        """ユーザー名でユーザーを取得"""
+        return next((user for user in self._users if user.username == username), None)
+
+    def create(self, user: UserCreate) -> UserInDB:
+        """検証付きで新しいユーザーを作成"""
+        # 重複チェック
+        if self.get_by_email(user.email):
+            raise ValueError("Email already registered")
+        if self.get_by_username(user.username):
+            raise ValueError("Username already taken")
+
+        new_user = UserInDB(
+            id=self._next_id,
+            email=user.email,
+            username=user.username,
+            full_name=user.full_name,
+            bio=user.bio,
+            is_active=user.is_active,
+            created_at=datetime.now(),
+            posts_count=0,
+            hashed_password=self._hash_password(user.password)
+        )
+        self._next_id += 1
+        self._users.append(new_user)
+        return new_user
+
+    def update(self, user_id: int, user_update: UserUpdate) -> Optional[UserInDB]:
+        """既存ユーザーを更新"""
+        user = self.get_by_id(user_id)
+        if not user:
+            return None
+
+        # メール / ユーザー名の重複チェック
+        update_data = user_update.dict(exclude_unset=True)
+        if "email" in update_data and update_data["email"] != user.email:
+            if self.get_by_email(update_data["email"]):
+                raise ValueError("Email already registered")
+
+        if "username" in update_data and update_data["username"] != user.username:
+            if self.get_by_username(update_data["username"]):
+                raise ValueError("Username already taken")
+
+        for field, value in update_data.items():
+            setattr(user, field, value)
+
+        return user
+
+    def delete(self, user_id: int) -> bool:
+        """ユーザーを論理削除 (非アクティブ化)"""
+        user = self.get_by_id(user_id)
+        if user:
+            user.is_active = False
+            return True
+        return False
+
+    def authenticate(self, email: str, password: str) -> Optional[UserInDB]:
+        """メールとパスワードでユーザーを認証"""
+        user = self.get_by_email(email)
+        if user and self._verify_password(password, user.hashed_password):
+            return user
+        return None
+
+users_crud = UsersCRUD()
+```
+
+### 投稿の CRUD
+
+`src/crud/posts.py` を更新します:
+
+```python
+from typing import List, Optional
+from datetime import datetime
+from src.schemas.posts import PostCreate, PostUpdate, Post
+
+class PostsCRUD:
+    def __init__(self):
+        self._posts: List[Post] = []
+        self._next_id = 1
+
+    def get_all(self, skip: int = 0, limit: int = 100, published_only: bool = True) -> List[Post]:
+        """ページネーション付きで全投稿を取得"""
+        posts = self._posts
+        if published_only:
+            posts = [post for post in posts if post.published]
+        return posts[skip:skip + limit]
+
+    def get_by_id(self, post_id: int) -> Optional[Post]:
+        """ID で投稿を取得"""
+        return next((post for post in self._posts if post.id == post_id), None)
+
+    def get_by_author(self, author_id: int, skip: int = 0, limit: int = 100) -> List[Post]:
+        """作者ごとの投稿を取得"""
+        author_posts = [post for post in self._posts if post.author_id == author_id]
+        return author_posts[skip:skip + limit]
+
+    def create(self, post: PostCreate, author_id: int) -> Post:
+        """新しい投稿を作成"""
+        now = datetime.now()
+        new_post = Post(
+            id=self._next_id,
+            title=post.title,
+            content=post.content,
+            published=post.published,
+            author_id=author_id,
+            created_at=now,
+            updated_at=now,
+            comments_count=0
+        )
+        self._next_id += 1
+        self._posts.append(new_post)
+
+        # 作者の投稿数を更新
+        from src.crud.users import users_crud
+        author = users_crud.get_by_id(author_id)
+        if author:
+            author.posts_count += 1
+
+        return new_post
+
+    def update(self, post_id: int, post_update: PostUpdate, author_id: int) -> Optional[Post]:
+        """既存投稿を更新"""
+        post = self.get_by_id(post_id)
+        if not post or post.author_id != author_id:
+            return None
+
+        update_data = post_update.dict(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(post, field, value)
+
+        post.updated_at = datetime.now()
+        return post
+
+    def delete(self, post_id: int, author_id: int) -> bool:
+        """投稿を削除"""
+        post = self.get_by_id(post_id)
+        if post and post.author_id == author_id:
+            self._posts.remove(post)
+
+            # 作者の投稿数を更新
+            from src.crud.users import users_crud
+            author = users_crud.get_by_id(author_id)
+            if author:
+                author.posts_count = max(0, author.posts_count - 1)
+
+            return True
+        return False
+
+    def search(self, query: str, skip: int = 0, limit: int = 100) -> List[Post]:
+        """タイトルや本文で投稿を検索"""
+        query_lower = query.lower()
+        matching_posts = [
+            post for post in self._posts
+            if post.published and (
+                query_lower in post.title.lower() or
+                query_lower in post.content.lower()
+            )
+        ]
+        return matching_posts[skip:skip + limit]
+
+posts_crud = PostsCRUD()
+```
+
+### コメントの CRUD
+
+`src/crud/comments.py` を更新します:
+
+```python
+from typing import List, Optional
+from datetime import datetime
+from src.schemas.comments import CommentCreate, CommentUpdate, Comment
+
+class CommentsCRUD:
+    def __init__(self):
+        self._comments: List[Comment] = []
+        self._next_id = 1
+
+    def get_all(self) -> List[Comment]:
+        """すべてのコメントを取得"""
+        return self._comments
+
+    def get_by_id(self, comment_id: int) -> Optional[Comment]:
+        """ID でコメントを取得"""
+        return next((comment for comment in self._comments if comment.id == comment_id), None)
+
+    def get_by_post(self, post_id: int, skip: int = 0, limit: int = 100) -> List[Comment]:
+        """特定投稿のコメントを取得"""
+        post_comments = [comment for comment in self._comments if comment.post_id == post_id]
+        return post_comments[skip:skip + limit]
+
+    def get_by_author(self, author_id: int, skip: int = 0, limit: int = 100) -> List[Comment]:
+        """作者ごとのコメントを取得"""
+        author_comments = [comment for comment in self._comments if comment.author_id == author_id]
+        return author_comments[skip:skip + limit]
+
+    def create(self, comment: CommentCreate, author_id: int) -> Comment:
+        """新しいコメントを作成"""
+        # 投稿の存在確認
+        from src.crud.posts import posts_crud
+        post = posts_crud.get_by_id(comment.post_id)
+        if not post:
+            raise ValueError("Post not found")
+
+        now = datetime.now()
+        new_comment = Comment(
+            id=self._next_id,
+            content=comment.content,
+            post_id=comment.post_id,
+            author_id=author_id,
+            created_at=now,
+            updated_at=now
+        )
+        self._next_id += 1
+        self._comments.append(new_comment)
+
+        # 投稿のコメント数を更新
+        post.comments_count += 1
+
+        return new_comment
+
+    def update(self, comment_id: int, comment_update: CommentUpdate, author_id: int) -> Optional[Comment]:
+        """既存コメントを更新"""
+        comment = self.get_by_id(comment_id)
+        if not comment or comment.author_id != author_id:
+            return None
+
+        update_data = comment_update.dict(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(comment, field, value)
+
+        comment.updated_at = datetime.now()
+        return comment
+
+    def delete(self, comment_id: int, author_id: int) -> bool:
+        """コメントを削除"""
+        comment = self.get_by_id(comment_id)
+        if comment and comment.author_id == author_id:
+            self._comments.remove(comment)
+
+            # 投稿のコメント数を更新
+            from src.crud.posts import posts_crud
+            post = posts_crud.get_by_id(comment.post_id)
+            if post:
+                post.comments_count = max(0, post.comments_count - 1)
+
+            return True
+        return False
+
+comments_crud = CommentsCRUD()
+```
+
+## ステップ 6: 高度な API ルートの実装
+
+### ユーザールートの拡張
+
+`src/api/routes/users.py` を更新します:
+
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException, status, Depends, Query
+from src.schemas.users import User, UserCreate, UserUpdate
+from src.crud.users import users_crud
+
+router = APIRouter()
+
+# 現在のユーザーを取得するヘルパ (チュートリアル用に簡略化)
+def get_current_user_id() -> int:
+    # 実際のアプリでは JWT を検証してユーザー ID を返す
+    return 1  # チュートリアル用
+
+@router.get("/", response_model=List[User])
+def read_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100)
+):
+    """ページネーション付きで全ユーザーを取得"""
+    users = users_crud.get_all()[skip:skip + limit]
+    return [User(**user.dict()) for user in users]
+
+@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
+def create_user(user: UserCreate):
+    """新しいユーザーを登録"""
+    try:
+        new_user = users_crud.create(user)
+        return User(**new_user.dict())
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+@router.get("/{user_id}", response_model=User)
+def read_user(user_id: int):
+    """特定のユーザーを取得"""
+    user = users_crud.get_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"User with id {user_id} not found"
+        )
+    return User(**user.dict())
+
+@router.put("/{user_id}", response_model=User)
+def update_user(
+    user_id: int,
+    user_update: UserUpdate,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """ユーザープロフィールを更新"""
+    if user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You can only update your own profile"
+        )
+
+    try:
+        updated_user = users_crud.update(user_id, user_update)
+        if not updated_user:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User not found"
+            )
+        return User(**updated_user.dict())
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_user(
+    user_id: int,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """ユーザーアカウントを非アクティブ化"""
+    if user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You can only delete your own account"
+        )
+
+    success = users_crud.delete(user_id)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+@router.post("/login")
+def login(email: str, password: str):
+    """ユーザーを認証"""
+    user = users_crud.authenticate(email, password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password"
+        )
+
+    # 実アプリでは JWT を返す
+    return {
+        "message": "Login successful",
+        "user_id": user.id,
+        "username": user.username
+    }
+```
+
+### 投稿ルートの拡張
+
+`src/api/routes/posts.py` を更新します:
+
+```python
+from typing import List, Optional
+from fastapi import APIRouter, HTTPException, status, Depends, Query
+from src.schemas.posts import Post, PostCreate, PostUpdate
+from src.crud.posts import posts_crud
+
+router = APIRouter()
+
+def get_current_user_id() -> int:
+    return 1  # チュートリアル用に簡略化
+
+@router.get("/", response_model=List[Post])
+def read_posts(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100),
+    search: Optional[str] = Query(None)
+):
+    """検索オプション付きで全投稿を取得"""
+    if search:
+        posts = posts_crud.search(search, skip, limit)
+    else:
+        posts = posts_crud.get_all(skip, limit)
+    return posts
+
+@router.post("/", response_model=Post, status_code=status.HTTP_201_CREATED)
+def create_post(
+    post: PostCreate,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """新しいブログ投稿を作成"""
+    new_post = posts_crud.create(post, current_user_id)
+    return new_post
+
+@router.get("/{post_id}", response_model=Post)
+def read_post(post_id: int):
+    """特定の投稿を取得"""
+    post = posts_crud.get_by_id(post_id)
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+    return post
+
+@router.put("/{post_id}", response_model=Post)
+def update_post(
+    post_id: int,
+    post_update: PostUpdate,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """ブログ投稿を更新"""
+    updated_post = posts_crud.update(post_id, post_update, current_user_id)
+    if not updated_post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found or you don't have permission to edit it"
+        )
+    return updated_post
+
+@router.delete("/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_post(
+    post_id: int,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """ブログ投稿を削除"""
+    success = posts_crud.delete(post_id, current_user_id)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found or you don't have permission to delete it"
+        )
+
+@router.get("/author/{author_id}", response_model=List[Post])
+def read_posts_by_author(
+    author_id: int,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100)
+):
+    """特定の作者の投稿を取得"""
+    posts = posts_crud.get_by_author(author_id, skip, limit)
+    return posts
+```
+
+### コメントルートの拡張
+
+`src/api/routes/comments.py` を更新します:
+
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException, status, Depends, Query
+from src.schemas.comments import Comment, CommentCreate, CommentUpdate
+from src.crud.comments import comments_crud
+
+router = APIRouter()
+
+def get_current_user_id() -> int:
+    return 1  # チュートリアル用に簡略化
+
+@router.get("/", response_model=List[Comment])
+def read_comments(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100)
+):
+    """すべてのコメントを取得"""
+    comments = comments_crud.get_all()[skip:skip + limit]
+    return comments
+
+@router.post("/", response_model=Comment, status_code=status.HTTP_201_CREATED)
+def create_comment(
+    comment: CommentCreate,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """新しいコメントを作成"""
+    try:
+        new_comment = comments_crud.create(comment, current_user_id)
+        return new_comment
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+@router.get("/{comment_id}", response_model=Comment)
+def read_comment(comment_id: int):
+    """特定のコメントを取得"""
+    comment = comments_crud.get_by_id(comment_id)
+    if not comment:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found"
+        )
+    return comment
+
+@router.put("/{comment_id}", response_model=Comment)
+def update_comment(
+    comment_id: int,
+    comment_update: CommentUpdate,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """コメントを更新"""
+    updated_comment = comments_crud.update(comment_id, comment_update, current_user_id)
+    if not updated_comment:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found or you don't have permission to edit it"
+        )
+    return updated_comment
+
+@router.delete("/{comment_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_comment(
+    comment_id: int,
+    current_user_id: int = Depends(get_current_user_id)
+):
+    """コメントを削除"""
+    success = comments_crud.delete(comment_id, current_user_id)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found or you don't have permission to delete it"
+        )
+
+@router.get("/post/{post_id}", response_model=List[Comment])
+def read_comments_by_post(
+    post_id: int,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100)
+):
+    """特定投稿のコメントを取得"""
+    comments = comments_crud.get_by_post(post_id, skip, limit)
+    return comments
+
+@router.get("/author/{author_id}", response_model=List[Comment])
+def read_comments_by_author(
+    author_id: int,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=100)
+):
+    """特定作者のコメントを取得"""
+    comments = comments_crud.get_by_author(author_id, skip, limit)
+    return comments
+```
+
+## ステップ 7: ブログ API のテスト
+
+サーバーを起動して、完成したブログ API をテストしましょう:
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+### ユーザー登録のテスト
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/users/" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "email": "john@example.com",
+       "username": "john_doe",
+       "full_name": "John Doe",
+       "bio": "Software developer and blogger",
+       "password": "securepassword123"
+     }'
+
+{
+  "id": 1,
+  "email": "john@example.com",
+  "username": "john_doe",
+  "full_name": "John Doe",
+  "bio": "Software developer and blogger",
+  "is_active": true,
+  "created_at": "2023-12-07T10:30:00",
+  "posts_count": 0
+}
+```
+
+</div>
+
+### ログインのテスト
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/users/login" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "email": "john@example.com",
+       "password": "securepassword123"
+     }'
+
+{
+  "message": "Login successful",
+  "user_id": 1,
+  "username": "john_doe"
+}
+```
+
+</div>
+
+### 投稿作成のテスト
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/posts/" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "title": "My First Blog Post",
+       "content": "This is the content of my first blog post. It'\''s about learning FastAPI with FastAPI-fastkit!",
+       "published": true
+     }'
+
+{
+  "id": 1,
+  "title": "My First Blog Post",
+  "content": "This is the content of my first blog post. It's about learning FastAPI with FastAPI-fastkit!",
+  "published": true,
+  "author_id": 1,
+  "created_at": "2023-12-07T10:35:00",
+  "updated_at": "2023-12-07T10:35:00",
+  "comments_count": 0
+}
+```
+
+</div>
+
+### コメント作成のテスト
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/comments/" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "content": "Great post! I learned a lot from this.",
+       "post_id": 1
+     }'
+
+{
+  "id": 1,
+  "content": "Great post! I learned a lot from this.",
+  "post_id": 1,
+  "author_id": 1,
+  "created_at": "2023-12-07T10:40:00",
+  "updated_at": "2023-12-07T10:40:00"
+}
+```
+
+</div>
+
+### 検索機能のテスト
+
+<div class="termy">
+
+```console
+$ curl "http://127.0.0.1:8000/api/v1/posts/?search=FastAPI"
+
+[
+  {
+    "id": 1,
+    "title": "My First Blog Post",
+    "content": "This is the content of my first blog post. It's about learning FastAPI with FastAPI-fastkit!",
+    "published": true,
+    "author_id": 1,
+    "created_at": "2023-12-07T10:35:00",
+    "updated_at": "2023-12-07T10:35:00",
+    "comments_count": 1
+  }
+]
+```
+
+</div>
+
+## ステップ 8: API ドキュメント
+
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) を開いて、完成した API ドキュメントを確認しましょう。次が表示されるはずです:
+
+- **Users**: 登録、ログイン、プロフィール管理
+- **Posts**: CRUD、検索、作者フィルタ
+- **Comments**: CRUD、投稿 / 作者によるフィルタ
+- **Items**: 元のサンプルエンドポイント
+
+ドキュメントには次が含まれます:
+
+- 利用可能なすべてのエンドポイント
+- リクエスト / レスポンススキーマ
+- データ検証ルール
+- エラーレスポンス
+
+## ステップ 9: テストの作成
+
+ブログ API の包括的なテストを作成しましょう。`tests/test_blog_api.py` を作成します:
+
+```python
+from fastapi.testclient import TestClient
+from src.main import app
+
+client = TestClient(app)
+
+class TestUserAPI:
+    def test_create_user(self):
+        user_data = {
+            "email": "test@example.com",
+            "username": "testuser",
+            "full_name": "Test User",
+            "bio": "Test bio",
+            "password": "testpassword123"
+        }
+        response = client.post("/api/v1/users/", json=user_data)
+        assert response.status_code == 201
+        data = response.json()
+        assert data["email"] == user_data["email"]
+        assert data["username"] == user_data["username"]
+        assert "id" in data
+        assert "hashed_password" not in data  # パスワードを露出させない
+
+    def test_duplicate_email(self):
+        # 1 人目のユーザー
+        user_data1 = {
+            "email": "duplicate@example.com",
+            "username": "user1",
+            "password": "password123"
+        }
+        response1 = client.post("/api/v1/users/", json=user_data1)
+        assert response1.status_code == 201
+
+        # 2 人目を同じメールで作成
+        user_data2 = {
+            "email": "duplicate@example.com",
+            "username": "user2",
+            "password": "password123"
+        }
+        response2 = client.post("/api/v1/users/", json=user_data2)
+        assert response2.status_code == 400
+        assert "Email already registered" in response2.json()["detail"]
+
+    def test_login(self):
+        # まずユーザーを作成
+        user_data = {
+            "email": "login@example.com",
+            "username": "loginuser",
+            "password": "loginpassword123"
+        }
+        client.post("/api/v1/users/", json=user_data)
+
+        # ログインをテスト
+        login_data = {
+            "email": "login@example.com",
+            "password": "loginpassword123"
+        }
+        response = client.post("/api/v1/users/login", json=login_data)
+        assert response.status_code == 200
+        data = response.json()
+        assert "user_id" in data
+        assert data["username"] == "loginuser"
+
+class TestPostAPI:
+    def test_create_post(self):
+        post_data = {
+            "title": "Test Post",
+            "content": "This is a test post content",
+            "published": True
+        }
+        response = client.post("/api/v1/posts/", json=post_data)
+        assert response.status_code == 201
+        data = response.json()
+        assert data["title"] == post_data["title"]
+        assert data["content"] == post_data["content"]
+        assert "id" in data
+        assert "author_id" in data
+
+    def test_read_posts(self):
+        response = client.get("/api/v1/posts/")
+        assert response.status_code == 200
+        data = response.json()
+        assert isinstance(data, list)
+
+    def test_search_posts(self):
+        # 特定の内容を含む投稿を作成
+        post_data = {
+            "title": "FastAPI Tutorial",
+            "content": "Learn how to build APIs with FastAPI",
+            "published": True
+        }
+        client.post("/api/v1/posts/", json=post_data)
+
+        # 投稿を検索
+        response = client.get("/api/v1/posts/?search=FastAPI")
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data) > 0
+        assert any("FastAPI" in post["title"] or "FastAPI" in post["content"] for post in data)
+
+class TestCommentAPI:
+    def test_create_comment(self):
+        # まず投稿を作成
+        post_data = {
+            "title": "Post for Comments",
+            "content": "This post will receive comments",
+            "published": True
+        }
+        post_response = client.post("/api/v1/posts/", json=post_data)
+        post_id = post_response.json()["id"]
+
+        # コメントを作成
+        comment_data = {
+            "content": "This is a test comment",
+            "post_id": post_id
+        }
+        response = client.post("/api/v1/comments/", json=comment_data)
+        assert response.status_code == 201
+        data = response.json()
+        assert data["content"] == comment_data["content"]
+        assert data["post_id"] == post_id
+
+    def test_get_comments_by_post(self):
+        # まず投稿とコメントを作成
+        post_data = {
+            "title": "Post with Comments",
+            "content": "This post has comments",
+            "published": True
+        }
+        post_response = client.post("/api/v1/posts/", json=post_data)
+        post_id = post_response.json()["id"]
+
+        comment_data = {
+            "content": "Comment on post",
+            "post_id": post_id
+        }
+        client.post("/api/v1/comments/", json=comment_data)
+
+        # 投稿のコメントを取得
+        response = client.get(f"/api/v1/comments/post/{post_id}")
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data) > 0
+        assert all(comment["post_id"] == post_id for comment in data)
+
+# テスト実行
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__])
+```
+
+### テストを実行する
+
+<div class="termy">
+
+```console
+$ python -m pytest tests/test_blog_api.py -v
+======================== test session starts ========================
+tests/test_blog_api.py::TestUserAPI::test_create_user PASSED
+tests/test_blog_api.py::TestUserAPI::test_duplicate_email PASSED
+tests/test_blog_api.py::TestUserAPI::test_login PASSED
+tests/test_blog_api.py::TestPostAPI::test_create_post PASSED
+tests/test_blog_api.py::TestPostAPI::test_read_posts PASSED
+tests/test_blog_api.py::TestPostAPI::test_search_posts PASSED
+tests/test_blog_api.py::TestCommentAPI::test_create_comment PASSED
+tests/test_blog_api.py::TestCommentAPI::test_get_comments_by_post PASSED
+======================== 8 passed in 1.23s ========================
+```
+
+</div>
+
+## 構築したもの
+
+おめでとうございます! 次の機能を備えた完全なブログ API を構築できました:
+
+### ✅ 実装した機能
+
+- **ユーザー管理**
+    - 検証付きのユーザー登録
+    - ユーザー認証 (ログイン)
+    - プロフィール管理
+    - 重複防止
+
+- **ブログ投稿**
+    - 投稿の作成、取得、更新、削除
+    - 作者によるフィルタ
+    - 検索機能
+    - 公開 / 下書きの状態
+
+- **コメント機能**
+    - 投稿へのコメント追加
+    - 投稿 / 作者ごとのコメント表示
+    - コメント管理
+
+- **データ検証**
+    - メールアドレスの検証
+    - パスワード要件
+    - コンテンツ長の制限
+    - 必須フィールドの検証
+
+- **エラー処理**
+    - 適切な HTTP ステータスコード
+    - 説明的なエラーメッセージ
+    - 入力検証エラー
+
+- **API ドキュメント**
+    - 自動 OpenAPI 生成
+    - 対話型テストインターフェイス
+    - リクエスト / レスポンススキーマ
+
+- **テスト**
+    - 包括的なテストカバレッジ
+    - 全エンドポイントの単体テスト
+    - エッジケースのテスト
+
+## 次のステップ
+
+### 拡張のアイデア
+
+1. **本格的な認証**
+    - JWT トークンの実装
+    - bcrypt によるパスワードハッシュ
+    - ロールベースの権限管理
+
+2. **データベース統合**
+    - PostgreSQL や MySQL の利用
+    - 適切なデータベースモデル
+    - データベースマイグレーション
+
+3. **高度な機能**
+    - 画像のファイルアップロード
+    - メール通知
+    - 投稿カテゴリ / タグ
+    - いいね / よくないね機能
+
+4. **本番運用への対応**
+    - ログの追加
+    - キャッシュの実装
+    - レート制限
+    - 環境ごとの設定
+
+### 学習を続ける
+
+1. **[テンプレートの利用](../user-guide/using-templates.md)**: データベース統合のために `fastapi-psql-orm` テンプレートを試す
+2. **[ルートの追加](../user-guide/adding-routes.md)**: より高度なルーティングパターンを学ぶ
+3. **[コントリビュート](../contributing/development-setup.md)**: FastAPI-fastkit に貢献する
+
+!!! tip "学んだベストプラクティス"
+    - **モジュール型アーキテクチャ**: schemas、CRUD、routes による関心事の分離
+    - **データ検証**: Pydantic を使った堅牢な入力検証
+    - **エラー処理**: 適切な HTTP ステータスコードとエラーメッセージ
+    - **テスト**: すべての機能の包括的なテストカバレッジ
+    - **ドキュメント**: 自動 API ドキュメント生成の活用
+
+これで FastAPI-fastkit を使ってプロダクション品質の API を構築するスキルが身につきました! 🚀
diff --git a/docs/ja/tutorial/getting-started.md b/docs/ja/tutorial/getting-started.md
new file mode 100644
index 0000000..351c6b1
--- /dev/null
+++ b/docs/ja/tutorial/getting-started.md
@@ -0,0 +1,564 @@
+# はじめに
+
+FastAPI-fastkit を始めるための、包括的かつ段階的なチュートリアルです。インストールから最初の API の起動まで、約 15 分で進められます。
+
+## 前提条件
+
+開始前に、次が用意されているか確認してください:
+
+- システムに **Python 3.12 以上** がインストールされていること
+- **Python の基礎知識** (変数・関数・クラス)
+- **ターミナル / コマンドライン** の利用
+- **テキストエディタまたは IDE** (VS Code、PyCharm など)
+
+## ステップ 1: インストール
+
+まず FastAPI-fastkit をインストールしましょう。プロジェクトを分離するため、仮想環境の利用を推奨します。
+
+### オプション A: pip を使う (従来型)
+
+<div class="termy">
+
+```console
+$ pip install fastapi-fastkit
+---> 100%
+Successfully installed fastapi-fastkit
+```
+
+</div>
+
+### オプション B: UV を使う (推奨・高速)
+
+UV は高速な Python パッケージマネージャーです。UV をまだ入れていない場合:
+
+<div class="termy">
+
+```console
+# まず UV をインストール
+$ curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 次に FastAPI-fastkit をインストール
+$ uv pip install fastapi-fastkit
+---> 100%
+Successfully installed fastapi-fastkit
+```
+
+</div>
+
+### オプション C: 仮想環境を使う
+
+<div class="termy">
+
+```console
+$ python -m venv fastapi-env
+$ source fastapi-env/bin/activate  # Windows の場合: fastapi-env\Scripts\activate
+$ pip install fastapi-fastkit
+```
+
+</div>
+
+### インストールの確認
+
+FastAPI-fastkit が正しくインストールされたか確認します:
+
+<div class="termy">
+
+```console
+$ fastkit --version
+FastAPI-fastkit version 1.0.0
+```
+
+</div>
+
+## ステップ 2: 最初のプロジェクトを作成
+
+対話型の `init` コマンドで、最初の FastAPI プロジェクトを作成しましょう:
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my-first-api
+Enter the author name: Your Name
+Enter the author email: your.email@example.com
+Enter the project description: My first FastAPI project
+
+           Project Information
+┌──────────────┬─────────────────────────┐
+│ Project Name │ my-first-api            │
+│ Author       │ Your Name               │
+│ Author Email │ your.email@example.com  │
+│ Description  │ My first FastAPI project│
+└──────────────┴─────────────────────────┘
+
+Available Stacks and Dependencies:
+           MINIMAL Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ pydantic          │
+│ Dependency 4 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+           STANDARD Stack
+┌──────────────┬───────────────────┐
+│ Dependency 1 │ fastapi           │
+│ Dependency 2 │ uvicorn           │
+│ Dependency 3 │ sqlalchemy        │
+│ Dependency 4 │ alembic           │
+│ Dependency 5 │ pytest            │
+│ Dependency 6 │ pydantic          │
+│ Dependency 7 │ pydantic-settings │
+└──────────────┴───────────────────┘
+
+Select stack (minimal, standard, full): minimal
+
+Available Package Managers:
+                   Package Managers
+┌────────┬────────────────────────────────────────────┐
+│ PIP    │ Standard Python package manager            │
+│ UV     │ Fast Python package manager                │
+│ PDM    │ Modern Python dependency management        │
+│ POETRY │ Python dependency management and packaging │
+└────────┴────────────────────────────────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+Creating virtual environment...
+Installing dependencies...
+✨ FastAPI project 'my-first-api' has been created successfully!
+```
+
+</div>
+
+!!! note "スタックの選択"
+    このチュートリアルでは話を簡潔に保つため **MINIMAL** を選びました。実プロジェクトでは、**STANDARD** (データベース対応を含む) や **FULL** (バックグラウンドタスクを含む) の利用も検討しましょう。
+
+## ステップ 3: プロジェクトに移動
+
+新しく作られたプロジェクトディレクトリへ移動します:
+
+<div class="termy">
+
+```console
+$ cd my-first-api
+$ ls -la
+total 32
+drwxr-xr-x  8 user user  256 Dec  7 10:30 .
+drwxr-xr-x  3 user user   96 Dec  7 10:30 ..
+drwxr-xr-x  5 user user  160 Dec  7 10:30 .venv
+-rw-r--r--  1 user user  156 Dec  7 10:30 README.md
+-rw-r--r--  1 user user  243 Dec  7 10:30 requirements.txt
+drwxr-xr-x  3 user user   96 Dec  7 10:30 scripts
+-rw-r--r--  1 user user 1245 Dec  7 10:30 setup.py
+drwxr-xr-x  8 user user  256 Dec  7 10:30 src
+drwxr-xr-x  3 user user   96 Dec  7 10:30 tests
+```
+
+</div>
+
+## ステップ 4: 仮想環境を有効化
+
+プロジェクトには、仮想環境があらかじめ用意されています。これを有効化しましょう:
+
+<div class="termy">
+
+```console
+$ source .venv/bin/activate  # Windows の場合: .venv\Scripts\activate
+(my-first-api) $
+```
+
+</div>
+
+ターミナルのプロンプトに `(my-first-api)` と表示され、仮想環境が有効になっていることが分かります。
+
+## ステップ 5: 開発サーバーを起動
+
+ここからが楽しい部分です — FastAPI サーバーを起動しましょう:
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [28720] using StatReload
+INFO:     Started server process [28722]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+</div>
+
+🎉 **おめでとうございます!** あなたの FastAPI サーバーが起動しています。
+
+## ステップ 6: API のテスト
+
+API をいくつかの方法でテストしてみましょう:
+
+### 方法 1: ブラウザ
+
+Web ブラウザで次にアクセスします:
+
+- **メイン API エンドポイント**: [http://127.0.0.1:8000](http://127.0.0.1:8000)
+
+次のように表示されるはずです:
+```json
+{"message": "Hello World"}
+```
+
+### 方法 2: 対話型 API ドキュメント
+
+自動生成された API ドキュメントを開きます:
+
+- **Swagger UI**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
+- **ReDoc**: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)
+
+特に Swagger UI は便利です。次のことができます:
+
+- 利用可能なエンドポイントの一覧表示
+- ブラウザから直接エンドポイントをテスト
+- リクエスト / レスポンススキーマの確認
+- OpenAPI 仕様のダウンロード
+
+### 方法 3: コマンドライン
+
+新しいターミナルを開いて (サーバーは起動したまま)、curl でテストします:
+
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000
+{"message":"Hello World"}
+
+$ curl http://127.0.0.1:8000/api/v1/items/
+[]
+
+$ curl -X POST "http://127.0.0.1:8000/api/v1/items/" \
+     -H "Content-Type: application/json" \
+     -d '{"title": "My First Item", "description": "This is a test item"}'
+{
+  "id": 1,
+  "title": "My First Item",
+  "description": "This is a test item"
+}
+```
+
+</div>
+
+## ステップ 7: プロジェクト構造の理解
+
+FastAPI-fastkit が何を生成したかを確認しましょう:
+
+<div class="termy">
+
+```console
+$ tree src
+src/
+├── __init__.py
+├── main.py                 # FastAPI アプリケーションのエントリポイント
+├── core/
+│   ├── __init__.py
+│   └── config.py          # アプリケーション設定
+├── api/
+│   ├── __init__.py
+│   ├── api.py             # メインの API ルーター
+│   └── routes/
+│       ├── __init__.py
+│       └── items.py       # Items API エンドポイント
+├── crud/
+│   ├── __init__.py
+│   └── items.py           # items のビジネスロジック
+├── schemas/
+│   ├── __init__.py
+│   └── items.py           # データ検証スキーマ
+└── mocks/
+    ├── __init__.py
+    └── mock_items.json    # サンプルデータ
+```
+
+</div>
+
+### 主要ファイルの解説
+
+**`src/main.py`** — アプリケーションの中核:
+```python
+from fastapi import FastAPI
+from src.api.api import api_router
+from src.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    openapi_url=f"{settings.API_V1_STR}/openapi.json"
+)
+
+app.include_router(api_router, prefix=settings.API_V1_STR)
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello World"}
+```
+
+**`src/core/config.py`** — アプリケーション設定:
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "my-first-api"
+    VERSION: str = "1.0.0"
+    API_V1_STR: str = "/api/v1"
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+**`src/api/routes/items.py`** — API エンドポイント:
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException
+from src.schemas.items import Item, ItemCreate, ItemUpdate
+from src.crud.items import items_crud
+
+router = APIRouter()
+
+@router.get("/", response_model=List[Item])
+def read_items():
+    """Get all items"""
+    return items_crud.get_all()
+
+@router.post("/", response_model=Item)
+def create_item(item: ItemCreate):
+    """Create a new item"""
+    return items_crud.create(item)
+```
+
+## ステップ 8: 最初のカスタムルートを追加
+
+学んだことを実践するため、新しい API ルートを追加してみましょう:
+
+<div class="termy">
+
+```console
+$ fastkit addroute users my-first-api
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-first-api                             │
+│ Route Name       │ users                                    │
+│ Target Directory │ ~/my-first-api                           │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'users' to project 'my-first-api'? [Y/n]: y
+
+✨ Successfully added new route 'users' to project 'my-first-api'
+```
+
+</div>
+
+サーバーは自動的に再起動し、新しいエンドポイントが使えるようになります:
+
+- `GET /api/v1/users/` - すべてのユーザーを取得
+- `POST /api/v1/users/` - 新しいユーザーを作成
+- `GET /api/v1/users/{user_id}` - 特定のユーザーを取得
+- ほか
+
+### 新しいルートをテストする
+
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/users/" \
+     -H "Content-Type: application/json" \
+     -d '{"title": "John Doe", "description": "Software Developer"}'
+{
+  "id": 1,
+  "title": "John Doe",
+  "description": "Software Developer"
+}
+
+$ curl http://127.0.0.1:8000/api/v1/users/
+[
+  {
+    "id": 1,
+    "title": "John Doe",
+    "description": "Software Developer"
+  }
+]
+```
+
+</div>
+
+## ステップ 9: コードを読んで変更する
+
+コードがどのように動くかを理解するため、小さな変更を加えてみましょう。
+
+### ウェルカムメッセージの変更
+
+エディタで `src/main.py` を開き、ルートエンドポイントを変更します:
+
+```python
+@app.get("/")
+def read_root():
+    return {"message": "Welcome to my first FastAPI application!"}
+```
+
+ファイルを保存します。自動リロードのおかげでサーバーは自動的に再起動します。
+
+### 変更をテストする
+
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000
+{"message":"Welcome to my first FastAPI application!"}
+```
+
+</div>
+
+### 新しいエンドポイントを追加する
+
+`src/main.py` にシンプルなエンドポイントを追加します:
+
+```python
+@app.get("/hello/{name}")
+def say_hello(name: str):
+    return {"message": f"Hello, {name}!"}
+```
+
+### 新しいエンドポイントをテストする
+
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000/hello/World
+{"message":"Hello, World!"}
+
+$ curl http://127.0.0.1:8000/hello/FastAPI
+{"message":"Hello, FastAPI!"}
+```
+
+</div>
+
+## ステップ 10: テストを実行
+
+プロジェクトには事前構成済みのテストが含まれます。実行してみましょう:
+
+<div class="termy">
+
+```console
+$ python -m pytest
+======================== test session starts ========================
+collected 5 items
+
+tests/test_items.py::test_create_item PASSED
+tests/test_items.py::test_read_items PASSED
+tests/test_items.py::test_read_item PASSED
+tests/test_items.py::test_update_item PASSED
+tests/test_items.py::test_delete_item PASSED
+
+======================== 5 passed in 0.45s ========================
+```
+
+</div>
+
+## 中核となる概念
+
+### 1. FastAPI アプリケーションの構造
+
+FastAPI-fastkit は **モジュール型アーキテクチャ** に従います:
+
+- **`main.py`**: アプリケーションのエントリポイントとグローバルエンドポイント
+- **`api/`**: API ルートの整理
+- **`core/`**: アプリケーション設定
+- **`crud/`**: ビジネスロジックとデータ操作
+- **`schemas/`**: データ検証とシリアライズ
+- **`tests/`**: 自動テスト
+
+### 2. 依存関係管理
+
+プロジェクトはモダンな Python の依存関係管理を使います:
+
+- **仮想環境**: 隔離された Python 環境
+- **requirements.txt**: すべての依存関係をリスト
+- **自動インストール**: プロジェクト作成時に依存関係が自動でインストールされる
+
+### 3. 開発サーバー
+
+FastAPI-fastkit は **Uvicorn** を ASGI サーバーとして利用します:
+
+- **自動リロード**: コード変更時に自動再起動
+- **高速起動**: 開発のイテレーションが速い
+- **本番運用対応**: 本番でも同じサーバーを利用
+
+### 4. API ドキュメント
+
+FastAPI が次を自動生成します:
+
+- **OpenAPI 仕様**: 業界標準の API ドキュメント
+- **Swagger UI**: 対話型のテストインターフェイス
+- **ReDoc**: 別形式のドキュメント表示
+
+## 次のステップ
+
+おめでとうございます! 以下を達成しました:
+
+✅ FastAPI-fastkit のインストール
+✅ 最初のプロジェクト作成
+✅ 開発サーバーの起動
+✅ API エンドポイントのテスト
+✅ 新しいルートの追加
+✅ 既存コードの変更
+✅ テストの実行
+
+### 学習を続ける
+
+1. **[最初のプロジェクト](first-project.md)**: 高度な機能を含む完全なブログ API を構築
+2. **[ルートの追加](../user-guide/adding-routes.md)**: より複雑な API エンドポイントを学ぶ
+3. **[テンプレートの利用](../user-guide/using-templates.md)**: 事前構築済みテンプレートを試す
+
+### さらに試す
+
+次の課題に挑戦してみましょう:
+
+1. **検証の追加**: スキーマにデータ検証ルールを追加
+2. **カスタムレスポンス**: ルートのレスポンス形式を変更
+3. **環境変数**: `.env` ファイルで設定
+4. **ミドルウェアの追加**: CORS や認証を実装
+5. **データベース統合**: STANDARD スタックにアップグレードしてデータベース対応
+
+### よくある問題と解決法
+
+**サーバーが起動しない:**
+
+- プロジェクトディレクトリにいるか確認
+- 仮想環境が有効化されているか確認
+- コードに構文エラーがないか確認
+
+**インポートエラー:**
+
+- すべての `__init__.py` ファイルが存在するか確認
+- インポートパスが正しいか確認
+- 仮想環境を使っているか確認
+
+**ポートが既に使用中:**
+```console
+$ fastkit runserver --port 8080
+```
+
+## 学んだベストプラクティス
+
+1. **仮想環境**: 常に隔離された環境を使う
+2. **プロジェクト構造**: 整理されたモジュール型アーキテクチャに従う
+3. **自動リロード**: 開発サーバーで素早くイテレーション
+4. **API ドキュメント**: 自動ドキュメント生成を活用
+5. **テスト**: 開発中は定期的にテストを実行
+
+!!! tip "開発のヒント"
+    - コーディング中は開発サーバーを起動したままにする
+    - 対話型ドキュメント (`/docs`) で API をテストする
+    - 役立つエラーメッセージはターミナルに表示される
+    - こまめにバージョン管理にコミットする
+
+これで FastAPI-fastkit を使って素晴らしい API を構築する準備が整いました! 🚀
diff --git a/docs/ja/tutorial/mcp-integration.md b/docs/ja/tutorial/mcp-integration.md
new file mode 100644
index 0000000..835b390
--- /dev/null
+++ b/docs/ja/tutorial/mcp-integration.md
@@ -0,0 +1,1730 @@
+# MCP (Model Context Protocol) との統合
+
+Model Context Protocol (MCP) を FastAPI と統合し、AI モデルが API エンドポイントをツールとして利用できるシステムを構築します。`fastapi-mcp` テンプレートを使い、認証、権限管理、MCP サーバー実装まで含む完全な AI 統合 API を実装します。
+
+## このチュートリアルで学ぶこと
+
+- Model Context Protocol (MCP) の概念と実装
+- JWT ベースの認証システム構築
+- ロールベースアクセス制御 (RBAC) の実装
+- MCP ツールの公開と管理
+- AI モデルとの安全な API 通信
+- ユーザーセッションとコンテキスト管理
+
+## 前提条件
+
+- [カスタムレスポンス処理チュートリアル](custom-response-handling.md) を完了済み
+- JWT と OAuth2 の基本概念の理解
+- AI / LLM モデルとの API 通信の基礎
+- MCP プロトコルの基礎知識
+
+## Model Context Protocol (MCP) とは
+
+MCP は AI モデルが外部システムとやり取りできるようにするための標準化されたプロトコルです。
+
+### 従来のアプローチと MCP アプローチの比較
+
+**従来のアプローチ (直接 API 呼び出し):**
+```
+AI モデル → HTTP リクエスト → API サーバー → レスポンス
+```
+
+**MCP アプローチ:**
+```
+AI モデル → MCP クライアント → MCP サーバー (FastAPI) → 安全なツール実行 → レスポンス
+```
+
+### MCP の利点
+
+- **セキュリティ**: 認証と権限管理を統合
+- **標準化**: 一貫したインターフェイスを提供
+- **コンテキスト管理**: セッションベースの状態保持
+- **ツール抽象化**: 複雑な API をシンプルなツールとして公開
+
+## ステップ 1: MCP 統合プロジェクトの作成
+
+`fastapi-mcp` テンプレートでプロジェクトを作成します:
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-mcp
+Enter the project name: ai-integrated-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: MCP-based API server integrated with AI models
+Deploying FastAPI project using 'fastapi-mcp' template
+
+           Project Information
+┌──────────────┬─────────────────────────────────────────────┐
+│ Project Name │ ai-integrated-api                           │
+│ Author       │ Developer Kim                               │
+│ Author Email │ developer@example.com                       │
+│ Description  │ MCP-based API server integrated with AI models │
+└──────────────┴─────────────────────────────────────────────┘
+
+       Template Dependencies
+┌──────────────┬────────────────┐
+│ Dependency 1 │ fastapi        │
+│ Dependency 2 │ uvicorn        │
+│ Dependency 3 │ pydantic       │
+│ Dependency 4 │ python-jose    │
+│ Dependency 5 │ passlib        │
+│ Dependency 6 │ python-multipart│
+│ Dependency 7 │ mcp            │
+└──────────────┴────────────────┘
+
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'ai-integrated-api' from 'fastapi-mcp' has been created successfully!
+```
+
+</div>
+
+## ステップ 2: プロジェクト構造の解析
+
+生成プロジェクトの構造を見ていきます:
+
+```
+ai-integrated-api/
+├── src/
+│   ├── main.py                     # FastAPI アプリ
+│   ├── auth/
+│   │   ├── __init__.py
+│   │   ├── models.py               # 認証関連データモデル
+│   │   ├── jwt_handler.py          # JWT トークン処理
+│   │   ├── dependencies.py         # 認証用依存性
+│   │   └── routes.py               # 認証ルーター
+│   ├── mcp/
+│   │   ├── __init__.py
+│   │   ├── server.py               # MCP サーバー実装
+│   │   ├── tools.py                # MCP ツール定義
+│   │   └── client.py               # MCP クライアント (テスト用)
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── api.py                  # API ルーター集約
+│   │   └── routes/
+│   │       ├── items.py            # item 管理 API
+│   │       ├── users.py            # ユーザー管理 API
+│   │       └── admin.py            # 管理 API
+│   ├── schemas/
+│   │   ├── __init__.py
+│   │   ├── auth.py                 # 認証スキーマ
+│   │   ├── users.py                # ユーザースキーマ
+│   │   └── items.py                # item スキーマ
+│   └── core/
+│       ├── __init__.py
+│       ├── config.py               # 設定
+│       ├── database.py             # データベース (インメモリ)
+│       └── security.py             # セキュリティ設定
+└── tests/
+    ├── test_auth.py                # 認証テスト
+    ├── test_mcp.py                 # MCP テスト
+    └── test_integration.py         # 統合テスト
+```
+
+## ステップ 3: 認証システムの実装
+
+### JWT トークン処理 (`src/auth/jwt_handler.py`)
+
+```python
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from src.core.config import settings
+
+# パスワードハッシュ化
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """パスワード検証"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def get_password_hash(password: str) -> str:
+    """パスワードハッシュ化"""
+    return pwd_context.hash(password)
+
+def create_access_token(data: Dict[str, Any], expires_delta: Optional[timedelta] = None) -> str:
+    """アクセストークン生成"""
+    to_encode = data.copy()
+
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+
+    to_encode.update({"exp": expire, "iat": datetime.utcnow()})
+
+    encoded_jwt = jwt.encode(
+        to_encode,
+        settings.SECRET_KEY,
+        algorithm=settings.ALGORITHM
+    )
+
+    return encoded_jwt
+
+def create_refresh_token(user_id: str) -> str:
+    """リフレッシュトークン生成"""
+    data = {"sub": user_id, "type": "refresh"}
+    expire = datetime.utcnow() + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
+
+    to_encode = data.copy()
+    to_encode.update({"exp": expire, "iat": datetime.utcnow()})
+
+    return jwt.encode(
+        to_encode,
+        settings.SECRET_KEY,
+        algorithm=settings.ALGORITHM
+    )
+
+def decode_token(token: str) -> Optional[Dict[str, Any]]:
+    """トークンをデコード"""
+    try:
+        payload = jwt.decode(
+            token,
+            settings.SECRET_KEY,
+            algorithms=[settings.ALGORITHM]
+        )
+        return payload
+    except JWTError:
+        return None
+
+def verify_token(token: str, token_type: str = "access") -> Optional[str]:
+    """トークン検証とユーザー ID の返却"""
+    payload = decode_token(token)
+
+    if not payload:
+        return None
+
+    # トークン種別の検証
+    if token_type == "refresh" and payload.get("type") != "refresh":
+        return None
+
+    user_id = payload.get("sub")
+    if not user_id:
+        return None
+
+    return user_id
+
+class TokenManager:
+    """トークン管理クラス"""
+
+    def __init__(self):
+        self.blacklisted_tokens = set()
+
+    def blacklist_token(self, token: str):
+        """トークンをブラックリストに追加"""
+        self.blacklisted_tokens.add(token)
+
+    def is_blacklisted(self, token: str) -> bool:
+        """トークンがブラックリストかを確認"""
+        return token in self.blacklisted_tokens
+
+    def create_token_pair(self, user_id: str, user_role: str) -> Dict[str, str]:
+        """access / refresh トークンペアを生成"""
+        access_token_data = {
+            "sub": user_id,
+            "role": user_role,
+            "type": "access"
+        }
+
+        access_token = create_access_token(access_token_data)
+        refresh_token = create_refresh_token(user_id)
+
+        return {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "token_type": "bearer"
+        }
+
+# グローバルトークンマネージャ
+token_manager = TokenManager()
+```
+
+### ユーザーモデルとデータベース (`src/auth/models.py`)
+
+```python
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, EmailStr
+from enum import Enum
+from datetime import datetime
+
+class UserRole(str, Enum):
+    """ユーザーロール"""
+    ADMIN = "admin"
+    USER = "user"
+    AI_AGENT = "ai_agent"
+    READONLY = "readonly"
+
+class Permission(str, Enum):
+    """権限"""
+    READ_ITEMS = "read:items"
+    WRITE_ITEMS = "write:items"
+    DELETE_ITEMS = "delete:items"
+    MANAGE_USERS = "manage:users"
+    USE_MCP_TOOLS = "use:mcp_tools"
+    ADMIN_MCP = "admin:mcp"
+
+class User(BaseModel):
+    """ユーザーモデル"""
+    id: str
+    email: EmailStr
+    username: str
+    full_name: Optional[str] = None
+    role: UserRole
+    permissions: List[Permission]
+    is_active: bool = True
+    created_at: datetime
+    last_login: Optional[datetime] = None
+    api_key: Optional[str] = None  # MCP クライアント用
+
+class UserInDB(User):
+    """データベース保存用ユーザーモデル"""
+    hashed_password: str
+
+class UserCreate(BaseModel):
+    """ユーザー作成スキーマ"""
+    email: EmailStr
+    username: str
+    password: str
+    full_name: Optional[str] = None
+    role: UserRole = UserRole.USER
+
+class UserUpdate(BaseModel):
+    """ユーザー更新スキーマ"""
+    email: Optional[EmailStr] = None
+    username: Optional[str] = None
+    full_name: Optional[str] = None
+    role: Optional[UserRole] = None
+    is_active: Optional[bool] = None
+
+class LoginRequest(BaseModel):
+    """ログインリクエストスキーマ"""
+    username: str
+    password: str
+
+class TokenResponse(BaseModel):
+    """トークンレスポンススキーマ"""
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    expires_in: int
+    user: User
+
+# ロールごとのデフォルト権限
+ROLE_PERMISSIONS = {
+    UserRole.ADMIN: [
+        Permission.READ_ITEMS,
+        Permission.WRITE_ITEMS,
+        Permission.DELETE_ITEMS,
+        Permission.MANAGE_USERS,
+        Permission.USE_MCP_TOOLS,
+        Permission.ADMIN_MCP
+    ],
+    UserRole.USER: [
+        Permission.READ_ITEMS,
+        Permission.WRITE_ITEMS,
+        Permission.USE_MCP_TOOLS
+    ],
+    UserRole.AI_AGENT: [
+        Permission.READ_ITEMS,
+        Permission.WRITE_ITEMS,
+        Permission.USE_MCP_TOOLS
+    ],
+    UserRole.READONLY: [
+        Permission.READ_ITEMS
+    ]
+}
+
+class UserDatabase:
+    """メモリベースのユーザーデータベース"""
+
+    def __init__(self):
+        self.users: Dict[str, UserInDB] = {}
+        self._init_default_users()
+
+    def _init_default_users(self):
+        """デフォルトユーザーを作成"""
+        from src.auth.jwt_handler import get_password_hash
+        import uuid
+
+        # 管理者アカウント
+        admin_id = str(uuid.uuid4())
+        self.users[admin_id] = UserInDB(
+            id=admin_id,
+            email="admin@example.com",
+            username="admin",
+            full_name="System Administrator",
+            role=UserRole.ADMIN,
+            permissions=ROLE_PERMISSIONS[UserRole.ADMIN],
+            hashed_password=get_password_hash("admin123"),
+            created_at=datetime.utcnow(),
+            api_key=str(uuid.uuid4())
+        )
+
+        # AI エージェントアカウント
+        ai_id = str(uuid.uuid4())
+        self.users[ai_id] = UserInDB(
+            id=ai_id,
+            email="ai@example.com",
+            username="ai_agent",
+            full_name="AI Assistant",
+            role=UserRole.AI_AGENT,
+            permissions=ROLE_PERMISSIONS[UserRole.AI_AGENT],
+            hashed_password=get_password_hash("ai123"),
+            created_at=datetime.utcnow(),
+            api_key=str(uuid.uuid4())
+        )
+
+    def get_user_by_username(self, username: str) -> Optional[UserInDB]:
+        """ユーザー名で検索"""
+        return next(
+            (user for user in self.users.values() if user.username == username),
+            None
+        )
+
+    def get_user_by_id(self, user_id: str) -> Optional[UserInDB]:
+        """ID で検索"""
+        return self.users.get(user_id)
+
+    def get_user_by_api_key(self, api_key: str) -> Optional[UserInDB]:
+        """API キーで検索"""
+        return next(
+            (user for user in self.users.values() if user.api_key == api_key),
+            None
+        )
+
+    def create_user(self, user_create: UserCreate) -> UserInDB:
+        """ユーザーを作成"""
+        import uuid
+        from src.auth.jwt_handler import get_password_hash
+
+        user_id = str(uuid.uuid4())
+        user = UserInDB(
+            id=user_id,
+            email=user_create.email,
+            username=user_create.username,
+            full_name=user_create.full_name,
+            role=user_create.role,
+            permissions=ROLE_PERMISSIONS[user_create.role],
+            hashed_password=get_password_hash(user_create.password),
+            created_at=datetime.utcnow(),
+            api_key=str(uuid.uuid4())
+        )
+
+        self.users[user_id] = user
+        return user
+
+    def update_user(self, user_id: str, user_update: UserUpdate) -> Optional[UserInDB]:
+        """ユーザーを更新"""
+        if user_id not in self.users:
+            return None
+
+        user = self.users[user_id]
+        update_data = user_update.dict(exclude_unset=True)
+
+        for field, value in update_data.items():
+            setattr(user, field, value)
+
+        # ロール変更時は権限も更新
+        if "role" in update_data:
+            user.permissions = ROLE_PERMISSIONS[user.role]
+
+        return user
+
+    def update_last_login(self, user_id: str):
+        """最終ログイン時刻を更新"""
+        if user_id in self.users:
+            self.users[user_id].last_login = datetime.utcnow()
+
+# グローバルデータベース
+user_db = UserDatabase()
+```
+
+## ステップ 4: 認証用依存性の実装
+
+### 認証用依存性 (`src/auth/dependencies.py`)
+
+```python
+from typing import Optional, List
+from fastapi import Depends, HTTPException, status, Security
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials, APIKeyHeader
+from jose import JWTError
+
+from src.auth.jwt_handler import decode_token, token_manager
+from src.auth.models import User, UserInDB, Permission, user_db
+
+# セキュリティスキーマ
+security = HTTPBearer()
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Security(security)
+) -> User:
+    """現在の認証済みユーザーを取得"""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+    try:
+        token = credentials.credentials
+
+        # ブラックリストを確認
+        if token_manager.is_blacklisted(token):
+            raise credentials_exception
+
+        payload = decode_token(token)
+        if payload is None:
+            raise credentials_exception
+
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+
+    except JWTError:
+        raise credentials_exception
+
+    user = user_db.get_user_by_id(user_id)
+    if user is None:
+        raise credentials_exception
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Inactive user"
+        )
+
+    return User(**user.dict())
+
+async def get_current_user_by_api_key(
+    api_key: Optional[str] = Security(api_key_header)
+) -> Optional[User]:
+    """API キーでユーザーを認証"""
+    if not api_key:
+        return None
+
+    user = user_db.get_user_by_api_key(api_key)
+    if not user or not user.is_active:
+        return None
+
+    return User(**user.dict())
+
+async def get_current_user_flexible(
+    token_user: Optional[User] = Depends(get_current_user),
+    api_key_user: Optional[User] = Depends(get_current_user_by_api_key)
+) -> User:
+    """トークンまたは API キーで認証 (柔軟な認証)"""
+    user = token_user or api_key_user
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required"
+        )
+
+    return user
+
+def require_permissions(*required_permissions: Permission):
+    """特定の権限を要求する依存性"""
+    def permission_checker(current_user: User = Depends(get_current_user_flexible)) -> User:
+        for permission in required_permissions:
+            if permission not in current_user.permissions:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Permission '{permission}' required"
+                )
+        return current_user
+
+    return permission_checker
+
+def require_roles(*required_roles):
+    """特定のロールを要求する依存性"""
+    def role_checker(current_user: User = Depends(get_current_user_flexible)) -> User:
+        if current_user.role not in required_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Role must be one of: {', '.join(required_roles)}"
+            )
+        return current_user
+
+    return role_checker
+
+# よく使う権限依存性
+RequireAdmin = require_roles("admin")
+RequireReadItems = require_permissions(Permission.READ_ITEMS)
+RequireWriteItems = require_permissions(Permission.WRITE_ITEMS)
+RequireDeleteItems = require_permissions(Permission.DELETE_ITEMS)
+RequireMCPTools = require_permissions(Permission.USE_MCP_TOOLS)
+RequireAdminMCP = require_permissions(Permission.ADMIN_MCP)
+```
+
+### 認証ルーター (`src/auth/routes.py`)
+
+```python
+from datetime import timedelta
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+
+from src.auth.models import (
+    User, UserCreate, UserUpdate, LoginRequest, TokenResponse,
+    user_db, UserRole
+)
+from src.auth.jwt_handler import (
+    verify_password, token_manager, verify_token, create_access_token
+)
+from src.auth.dependencies import get_current_user, RequireAdmin
+from src.core.config import settings
+
+router = APIRouter(prefix="/auth", tags=["authentication"])
+
+@router.post("/register", response_model=User)
+async def register_user(user_create: UserCreate):
+    """ユーザーを登録"""
+    # ユーザー名重複チェック
+    if user_db.get_user_by_username(user_create.username):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Username already registered"
+        )
+
+    # 最初のユーザーは自動的に管理者に
+    if not user_db.users:
+        user_create.role = UserRole.ADMIN
+
+    user = user_db.create_user(user_create)
+    return User(**user.dict())
+
+@router.post("/login", response_model=TokenResponse)
+async def login_user(form_data: OAuth2PasswordRequestForm = Depends()):
+    """ユーザーログイン"""
+    user = user_db.get_user_by_username(form_data.username)
+
+    if not user or not verify_password(form_data.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Inactive user"
+        )
+
+    # トークンを生成
+    tokens = token_manager.create_token_pair(user.id, user.role)
+
+    # 最終ログイン時刻を更新
+    user_db.update_last_login(user.id)
+
+    return TokenResponse(
+        access_token=tokens["access_token"],
+        refresh_token=tokens["refresh_token"],
+        token_type=tokens["token_type"],
+        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+        user=User(**user.dict())
+    )
+
+@router.post("/refresh", response_model=dict)
+async def refresh_token(refresh_token: str):
+    """トークンをリフレッシュ"""
+    user_id = verify_token(refresh_token, "refresh")
+
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid refresh token"
+        )
+
+    user = user_db.get_user_by_id(user_id)
+    if not user or not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found or inactive"
+        )
+
+    # 新しいトークンペアを生成
+    tokens = token_manager.create_token_pair(user.id, user.role)
+
+    return {
+        "access_token": tokens["access_token"],
+        "refresh_token": tokens["refresh_token"],
+        "token_type": tokens["token_type"],
+        "expires_in": settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
+    }
+
+@router.post("/logout")
+async def logout_user(current_user: User = Depends(get_current_user)):
+    """ユーザーログアウト"""
+    # 実装ではトークンをブラックリストへ追加
+    return {"message": "Successfully logged out"}
+
+@router.get("/me", response_model=User)
+async def get_current_user_info(current_user: User = Depends(get_current_user)):
+    """現在のユーザー情報を取得"""
+    return current_user
+
+@router.put("/me", response_model=User)
+async def update_current_user(
+    user_update: UserUpdate,
+    current_user: User = Depends(get_current_user)
+):
+    """現在のユーザー情報を更新"""
+    # 一般ユーザーはロール変更不可
+    if user_update.role and current_user.role != UserRole.ADMIN:
+        user_update.role = None
+
+    updated_user = user_db.update_user(current_user.id, user_update)
+    if not updated_user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+    return User(**updated_user.dict())
+
+@router.get("/users", response_model=list[User])
+async def list_users(admin_user: User = Depends(RequireAdmin)):
+    """ユーザー一覧を取得 (管理者のみ)"""
+    return [User(**user.dict()) for user in user_db.users.values()]
+
+@router.post("/users/{user_id}/generate-api-key")
+async def generate_api_key(
+    user_id: str,
+    admin_user: User = Depends(RequireAdmin)
+):
+    """ユーザーの API キーを生成 (管理者のみ)"""
+    import uuid
+
+    user = user_db.get_user_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+    # 新しい API キーを生成
+    new_api_key = str(uuid.uuid4())
+    user.api_key = new_api_key
+
+    return {
+        "api_key": new_api_key,
+        "message": "API key generated successfully"
+    }
+```
+
+## ステップ 5: MCP サーバーの実装
+
+### MCP ツールの定義 (`src/mcp/tools.py`)
+
+```python
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, Field
+from enum import Enum
+
+class ToolCategory(str, Enum):
+    """ツールカテゴリ"""
+    DATA_MANAGEMENT = "data_management"
+    SEARCH = "search"
+    ANALYSIS = "analysis"
+    ADMIN = "admin"
+
+class MCPTool(BaseModel):
+    """MCP ツール定義"""
+    name: str = Field(..., description="Tool name")
+    description: str = Field(..., description="Tool description")
+    category: ToolCategory = Field(..., description="Tool category")
+    parameters: Dict[str, Any] = Field(default_factory=dict, description="Parameter schema")
+    required_permissions: List[str] = Field(default_factory=list, description="Required permissions")
+    examples: List[Dict[str, Any]] = Field(default_factory=list, description="Usage examples")
+
+class ToolRegistry:
+    """ツールレジストリ"""
+
+    def __init__(self):
+        self.tools: Dict[str, MCPTool] = {}
+        self._register_default_tools()
+
+    def _register_default_tools(self):
+        """デフォルトツールを登録"""
+
+        # item 作成ツール
+        self.register_tool(MCPTool(
+            name="create_item",
+            description="Create a new item",
+            category=ToolCategory.DATA_MANAGEMENT,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Item name"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Item description"
+                    },
+                    "price": {
+                        "type": "number",
+                        "description": "Item price",
+                        "minimum": 0
+                    },
+                    "category": {
+                        "type": "string",
+                        "description": "Item category"
+                    }
+                },
+                "required": ["name", "price"]
+            },
+            required_permissions=["write:items"],
+            examples=[
+                {
+                    "name": "Notebook",
+                    "description": "High-performance gaming notebook",
+                    "price": 1500000,
+                    "category": "electronics"
+                }
+            ]
+        ))
+
+        # item 検索ツール
+        self.register_tool(MCPTool(
+            name="search_items",
+            description="Search for items",
+            category=ToolCategory.SEARCH,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Search query"
+                    },
+                    "category": {
+                        "type": "string",
+                        "description": "Category filter"
+                    },
+                    "min_price": {
+                        "type": "number",
+                        "description": "Minimum price"
+                    },
+                    "max_price": {
+                        "type": "number",
+                        "description": "Maximum price"
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Result count limit",
+                        "default": 10,
+                        "maximum": 100
+                    }
+                },
+                "required": ["query"]
+            },
+            required_permissions=["read:items"],
+            examples=[
+                {
+                    "query": "Notebook",
+                    "category": "electronics",
+                    "max_price": 2000000,
+                    "limit": 5
+                }
+            ]
+        ))
+
+        # item 分析ツール
+        self.register_tool(MCPTool(
+            name="analyze_items",
+            description="Analyze item data",
+            category=ToolCategory.ANALYSIS,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "analysis_type": {
+                        "type": "string",
+                        "enum": ["price_distribution", "category_breakdown", "trend_analysis"],
+                        "description": "Analysis type"
+                    },
+                    "date_range": {
+                        "type": "object",
+                        "properties": {
+                            "start_date": {"type": "string", "format": "date"},
+                            "end_date": {"type": "string", "format": "date"}
+                        },
+                        "description": "Analysis period"
+                    }
+                },
+                "required": ["analysis_type"]
+            },
+            required_permissions=["read:items"],
+            examples=[
+                {
+                    "analysis_type": "price_distribution",
+                    "date_range": {
+                        "start_date": "2024-01-01",
+                        "end_date": "2024-12-31"
+                    }
+                }
+            ]
+        ))
+
+        # ユーザー管理ツール (管理者のみ)
+        self.register_tool(MCPTool(
+            name="manage_users",
+            description="Manage users",
+            category=ToolCategory.ADMIN,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": ["list", "create", "update", "deactivate"],
+                        "description": "Action to perform"
+                    },
+                    "user_data": {
+                        "type": "object",
+                        "description": "User data (create/update)"
+                    },
+                    "user_id": {
+                        "type": "string",
+                        "description": "User ID (update/deactivate)"
+                    }
+                },
+                "required": ["action"]
+            },
+            required_permissions=["manage:users"],
+            examples=[
+                {
+                    "action": "list"
+                },
+                {
+                    "action": "create",
+                    "user_data": {
+                        "username": "newuser",
+                        "email": "newuser@example.com",
+                        "role": "user"
+                    }
+                }
+            ]
+        ))
+
+    def register_tool(self, tool: MCPTool):
+        """ツールを登録"""
+        self.tools[tool.name] = tool
+
+    def get_tool(self, tool_name: str) -> Optional[MCPTool]:
+        """ツールを取得"""
+        return self.tools.get(tool_name)
+
+    def list_tools(self, user_permissions: List[str] = None) -> List[MCPTool]:
+        """ユーザー権限に応じてツール一覧を返す"""
+        if user_permissions is None:
+            return list(self.tools.values())
+
+        available_tools = []
+        for tool in self.tools.values():
+            # 権限チェック
+            if all(perm in user_permissions for perm in tool.required_permissions):
+                available_tools.append(tool)
+
+        return available_tools
+
+    def get_tools_by_category(self, category: ToolCategory, user_permissions: List[str] = None) -> List[MCPTool]:
+        """カテゴリ別のツール一覧"""
+        tools = self.list_tools(user_permissions)
+        return [tool for tool in tools if tool.category == category]
+
+# グローバルツールレジストリ
+tool_registry = ToolRegistry()
+```
+
+### MCP サーバー実装 (`src/mcp/server.py`)
+
+```python
+from typing import Dict, Any, List, Optional
+from fastapi import HTTPException, status
+import asyncio
+import json
+
+from src.mcp.tools import tool_registry, ToolCategory
+from src.auth.models import User, Permission
+from src.api.routes.items import ItemCRUD
+from src.auth.models import user_db
+
+class MCPServer:
+    """Model Context Protocol サーバー"""
+
+    def __init__(self):
+        self.item_crud = ItemCRUD()
+        self.active_sessions: Dict[str, Dict[str, Any]] = {}
+
+    async def create_session(self, user: User) -> str:
+        """MCP セッションを作成"""
+        import uuid
+
+        session_id = str(uuid.uuid4())
+        self.active_sessions[session_id] = {
+            "user_id": user.id,
+            "user": user,
+            "created_at": datetime.utcnow(),
+            "context": {},
+            "tool_usage_count": 0,
+            "last_activity": datetime.utcnow()
+        }
+
+        return session_id
+
+    async def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """セッションを取得"""
+        session = self.active_sessions.get(session_id)
+        if session:
+            session["last_activity"] = datetime.utcnow()
+        return session
+
+    async def close_session(self, session_id: str):
+        """セッションを閉じる"""
+        if session_id in self.active_sessions:
+            del self.active_sessions[session_id]
+
+    async def list_tools(self, user: User) -> List[Dict[str, Any]]:
+        """ユーザーが利用可能なツール一覧"""
+        user_permissions = [perm.value for perm in user.permissions]
+        tools = tool_registry.list_tools(user_permissions)
+
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "category": tool.category,
+                "parameters": tool.parameters,
+                "examples": tool.examples
+            }
+            for tool in tools
+        ]
+
+    async def execute_tool(
+        self,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        user: User,
+        session_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """ツールを実行"""
+
+        # ツールの存在確認
+        tool = tool_registry.get_tool(tool_name)
+        if not tool:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Tool '{tool_name}' not found"
+            )
+
+        # 権限チェック
+        user_permissions = [perm.value for perm in user.permissions]
+        for required_perm in tool.required_permissions:
+            if required_perm not in user_permissions:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Permission '{required_perm}' required for tool '{tool_name}'"
+                )
+
+        # セッション更新
+        if session_id:
+            session = await self.get_session(session_id)
+            if session:
+                session["tool_usage_count"] += 1
+
+        # ツール実行
+        try:
+            result = await self._execute_tool_logic(tool_name, parameters, user)
+
+            return {
+                "success": True,
+                "tool": tool_name,
+                "result": result,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "tool": tool_name,
+                "error": str(e),
+                "timestamp": datetime.utcnow().isoformat()
+            }
+
+    async def _execute_tool_logic(
+        self,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        user: User
+    ) -> Any:
+        """ツールロジックの実行"""
+
+        if tool_name == "create_item":
+            return await self._create_item(parameters)
+
+        elif tool_name == "search_items":
+            return await self._search_items(parameters)
+
+        elif tool_name == "analyze_items":
+            return await self._analyze_items(parameters)
+
+        elif tool_name == "manage_users":
+            return await self._manage_users(parameters, user)
+
+        else:
+            raise ValueError(f"Tool '{tool_name}' implementation not found")
+
+    async def _create_item(self, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        """item 作成ツールの実装"""
+        from src.schemas.items import ItemCreate
+
+        try:
+            item_create = ItemCreate(**parameters)
+            created_item = await self.item_crud.create(item_create)
+
+            return {
+                "action": "create_item",
+                "item": created_item.dict(),
+                "message": f"Item '{created_item.name}' created successfully"
+            }
+        except Exception as e:
+            raise ValueError(f"Failed to create item: {str(e)}")
+
+    async def _search_items(self, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        """item 検索ツールの実装"""
+        query = parameters.get("query", "")
+        category = parameters.get("category")
+        min_price = parameters.get("min_price")
+        max_price = parameters.get("max_price")
+        limit = parameters.get("limit", 10)
+
+        # 検索ロジックの実装
+        all_items = await self.item_crud.get_all()
+        filtered_items = []
+
+        for item in all_items:
+            # テキスト検索
+            if query.lower() not in item.name.lower() and query.lower() not in (item.description or "").lower():
+                continue
+
+            # カテゴリフィルタ
+            if category and getattr(item, 'category', None) != category:
+                continue
+
+            # 価格フィルタ
+            if min_price is not None and item.price < min_price:
+                continue
+            if max_price is not None and item.price > max_price:
+                continue
+
+            filtered_items.append(item)
+
+        # 件数制限
+        result_items = filtered_items[:limit]
+
+        return {
+            "action": "search_items",
+            "query": query,
+            "total_found": len(filtered_items),
+            "returned_count": len(result_items),
+            "items": [item.dict() for item in result_items]
+        }
+
+    async def _analyze_items(self, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        """item 分析ツールの実装"""
+        analysis_type = parameters.get("analysis_type")
+        date_range = parameters.get("date_range", {})
+
+        all_items = await self.item_crud.get_all()
+
+        if analysis_type == "price_distribution":
+            prices = [item.price for item in all_items]
+            if not prices:
+                return {"analysis": "price_distribution", "result": "No items found"}
+
+            return {
+                "analysis": "price_distribution",
+                "result": {
+                    "total_items": len(prices),
+                    "min_price": min(prices),
+                    "max_price": max(prices),
+                    "average_price": sum(prices) / len(prices),
+                    "price_ranges": {
+                        "under_100k": len([p for p in prices if p < 100000]),
+                        "100k_to_500k": len([p for p in prices if 100000 <= p < 500000]),
+                        "500k_to_1m": len([p for p in prices if 500000 <= p < 1000000]),
+                        "over_1m": len([p for p in prices if p >= 1000000])
+                    }
+                }
+            }
+
+        elif analysis_type == "category_breakdown":
+            categories = {}
+            for item in all_items:
+                category = getattr(item, 'category', 'uncategorized')
+                categories[category] = categories.get(category, 0) + 1
+
+            return {
+                "analysis": "category_breakdown",
+                "result": {
+                    "total_categories": len(categories),
+                    "categories": categories
+                }
+            }
+
+        else:
+            raise ValueError(f"Unknown analysis type: {analysis_type}")
+
+    async def _manage_users(self, parameters: Dict[str, Any], requesting_user: User) -> Dict[str, Any]:
+        """ユーザー管理ツールの実装"""
+        action = parameters.get("action")
+
+        # 管理者権限チェック
+        if Permission.MANAGE_USERS not in requesting_user.permissions:
+            raise ValueError("Insufficient permissions for user management")
+
+        if action == "list":
+            users = [User(**user.dict()) for user in user_db.users.values()]
+            return {
+                "action": "list_users",
+                "total_users": len(users),
+                "users": [user.dict() for user in users]
+            }
+
+        elif action == "create":
+            user_data = parameters.get("user_data", {})
+            from src.auth.models import UserCreate
+
+            user_create = UserCreate(**user_data)
+            created_user = user_db.create_user(user_create)
+
+            return {
+                "action": "create_user",
+                "user": User(**created_user.dict()).dict(),
+                "message": f"User '{created_user.username}' created successfully"
+            }
+
+        else:
+            raise ValueError(f"Unknown user management action: {action}")
+
+# グローバル MCP サーバー
+mcp_server = MCPServer()
+```
+
+## ステップ 6: MCP API エンドポイントの実装
+
+### MCP API ルーター (`src/api/routes/mcp.py`)
+
+```python
+from typing import Dict, Any, Optional
+from fastapi import APIRouter, Depends, HTTPException, status, BackgroundTasks
+from pydantic import BaseModel
+
+from src.auth.dependencies import get_current_user_flexible, RequireMCPTools
+from src.auth.models import User
+from src.mcp.server import mcp_server
+from src.mcp.tools import ToolCategory
+
+router = APIRouter(prefix="/mcp", tags=["MCP"])
+
+class ToolExecuteRequest(BaseModel):
+    """ツール実行リクエスト"""
+    tool_name: str
+    parameters: Dict[str, Any]
+    session_id: Optional[str] = None
+
+class SessionCreateResponse(BaseModel):
+    """セッション作成レスポンス"""
+    session_id: str
+    message: str
+
+@router.post("/session", response_model=SessionCreateResponse)
+async def create_mcp_session(
+    current_user: User = Depends(RequireMCPTools)
+):
+    """MCP セッションを作成"""
+    session_id = await mcp_server.create_session(current_user)
+
+    return SessionCreateResponse(
+        session_id=session_id,
+        message=f"MCP session created (User: {current_user.username})"
+    )
+
+@router.delete("/session/{session_id}")
+async def close_mcp_session(
+    session_id: str,
+    current_user: User = Depends(RequireMCPTools)
+):
+    """MCP セッションを閉じる"""
+    session = await mcp_server.get_session(session_id)
+
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
+        )
+
+    # セッション所有者を確認
+    if session["user_id"] != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Cannot close another user's session"
+        )
+
+    await mcp_server.close_session(session_id)
+
+    return {"message": "Session closed successfully"}
+
+@router.get("/tools")
+async def list_mcp_tools(
+    category: Optional[ToolCategory] = None,
+    current_user: User = Depends(RequireMCPTools)
+):
+    """利用可能な MCP ツールの一覧"""
+    tools = await mcp_server.list_tools(current_user)
+
+    if category:
+        tools = [tool for tool in tools if tool["category"] == category]
+
+    return {
+        "user": current_user.username,
+        "total_tools": len(tools),
+        "tools": tools
+    }
+
+@router.post("/execute")
+async def execute_mcp_tool(
+    request: ToolExecuteRequest,
+    background_tasks: BackgroundTasks,
+    current_user: User = Depends(RequireMCPTools)
+):
+    """MCP ツールを実行"""
+
+    # セッション確認 (任意)
+    if request.session_id:
+        session = await mcp_server.get_session(request.session_id)
+        if not session:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Session not found"
+            )
+
+        if session["user_id"] != current_user.id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Cannot use another user's session"
+            )
+
+    # ツールを実行
+    result = await mcp_server.execute_tool(
+        tool_name=request.tool_name,
+        parameters=request.parameters,
+        user=current_user,
+        session_id=request.session_id
+    )
+
+    # 利用ログをバックグラウンドで記録
+    background_tasks.add_task(
+        log_tool_usage,
+        current_user.id,
+        request.tool_name,
+        result["success"]
+    )
+
+    return result
+
+@router.get("/sessions")
+async def list_user_sessions(
+    current_user: User = Depends(RequireMCPTools)
+):
+    """ユーザーのアクティブセッション一覧"""
+    user_sessions = []
+
+    for session_id, session_data in mcp_server.active_sessions.items():
+        if session_data["user_id"] == current_user.id:
+            user_sessions.append({
+                "session_id": session_id,
+                "created_at": session_data["created_at"],
+                "tool_usage_count": session_data["tool_usage_count"],
+                "last_activity": session_data["last_activity"]
+            })
+
+    return {
+        "user": current_user.username,
+        "active_sessions": len(user_sessions),
+        "sessions": user_sessions
+    }
+
+@router.get("/stats")
+async def get_mcp_stats(
+    current_user: User = Depends(RequireMCPTools)
+):
+    """MCP 利用統計"""
+    total_sessions = len(mcp_server.active_sessions)
+    user_sessions = len([
+        s for s in mcp_server.active_sessions.values()
+        if s["user_id"] == current_user.id
+    ])
+
+    return {
+        "user_stats": {
+            "username": current_user.username,
+            "active_sessions": user_sessions,
+            "permissions": [perm.value for perm in current_user.permissions]
+        },
+        "server_stats": {
+            "total_active_sessions": total_sessions,
+            "available_tools": len(await mcp_server.list_tools(current_user))
+        }
+    }
+
+async def log_tool_usage(user_id: str, tool_name: str, success: bool):
+    """ツール利用ログ (バックグラウンドジョブ)"""
+    import logging
+
+    logger = logging.getLogger("mcp.usage")
+    logger.info(
+        f"Tool usage - User: {user_id}, Tool: {tool_name}, Success: {success}"
+    )
+```
+
+## ステップ 7: アプリケーションの統合とテスト
+
+### メインアプリケーション (`src/main.py`)
+
+```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from src.auth.routes import router as auth_router
+from src.api.routes.items import router as items_router
+from src.api.routes.mcp import router as mcp_router
+from src.core.config import settings
+
+app = FastAPI(
+    title="AI Integrated API",
+    description="AI model integrated MCP-based API server",
+    version="1.0.0"
+)
+
+# CORS 設定
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_HOSTS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ルーターを取り込む
+app.include_router(auth_router)
+app.include_router(items_router, prefix="/api/v1")
+app.include_router(mcp_router, prefix="/api/v1")
+
+@app.get("/")
+async def root():
+    return {
+        "message": "AI Integrated API with MCP Support",
+        "version": "1.0.0",
+        "endpoints": {
+            "authentication": "/auth",
+            "items": "/api/v1/items",
+            "mcp": "/api/v1/mcp",
+            "docs": "/docs"
+        }
+    }
+
+@app.get("/health")
+async def health_check():
+    """ヘルスチェックエンドポイント"""
+    return {
+        "status": "healthy",
+        "version": "1.0.0",
+        "services": {
+            "auth": "operational",
+            "mcp": "operational",
+            "database": "operational"
+        }
+    }
+```
+
+### サーバーの起動とテスト
+
+<div class="termy">
+
+```console
+$ cd ai-integrated-api
+$ fastkit runserver
+Starting FastAPI server at 127.0.0.1:8000...
+
+# ユーザーログイン
+$ curl -X POST "http://localhost:8000/auth/login" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=admin&password=admin123"
+
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "expires_in": 1800,
+  "user": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "email": "admin@example.com",
+    "username": "admin",
+    "role": "admin",
+    "permissions": ["read:items", "write:items", ...]
+  }
+}
+
+# MCP セッションを作成
+$ curl -X POST "http://localhost:8000/api/v1/mcp/session" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+
+{
+  "session_id": "abc123-def456-ghi789",
+  "message": "MCP session created (User: admin)"
+}
+
+# 利用可能なツールを一覧
+$ curl "http://localhost:8000/api/v1/mcp/tools" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+
+{
+  "user": "admin",
+  "total_tools": 4,
+  "tools": [
+    {
+      "name": "create_item",
+      "description": "Create a new item",
+      "category": "data_management",
+      "parameters": {...},
+      "examples": [...]
+    },
+    ...
+  ]
+}
+
+# MCP ツールを実行 (item 作成)
+$ curl -X POST "http://localhost:8000/api/v1/mcp/execute" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool_name": "create_item",
+    "parameters": {
+      "name": "AI generated item",
+      "description": "MCP through AI generated item",
+      "price": 500000,
+      "category": "ai_generated"
+    },
+    "session_id": "abc123-def456-ghi789"
+  }'
+
+{
+  "success": true,
+  "tool": "create_item",
+  "result": {
+    "action": "create_item",
+    "item": {
+      "id": 1,
+      "name": "AI generated item",
+      "description": "MCP through AI generated item",
+      "price": 500000,
+      "category": "ai_generated",
+      "created_at": "2024-01-01T12:00:00Z"
+    },
+    "message": "Item 'AI generated item' created successfully"
+  },
+  "timestamp": "2024-01-01T12:00:00.123456Z"
+}
+
+# MCP ツールを実行 (item 検索)
+$ curl -X POST "http://localhost:8000/api/v1/mcp/execute" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool_name": "search_items",
+    "parameters": {
+      "query": "AI",
+      "limit": 5
+    }
+  }'
+```
+
+</div>
+
+## ステップ 8: AI クライアント例
+
+### Python MCP クライアント例
+
+```python
+# client_example.py
+import asyncio
+import aiohttp
+from typing import Dict, Any, List
+
+class MCPClient:
+    """MCP クライアント例"""
+
+    def __init__(self, base_url: str, api_key: str):
+        self.base_url = base_url
+        self.api_key = api_key
+        self.session_id = None
+        self.session = None
+
+    async def __aenter__(self):
+        self.session = aiohttp.ClientSession(
+            headers={"X-API-Key": self.api_key}
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self.session_id:
+            await self.close_session()
+        if self.session:
+            await self.session.close()
+
+    async def create_session(self) -> str:
+        """MCP セッションを作成"""
+        async with self.session.post(f"{self.base_url}/api/v1/mcp/session") as resp:
+            data = await resp.json()
+            self.session_id = data["session_id"]
+            return self.session_id
+
+    async def close_session(self):
+        """MCP セッションを閉じる"""
+        if self.session_id:
+            async with self.session.delete(f"{self.base_url}/api/v1/mcp/session/{self.session_id}"):
+                pass
+            self.session_id = None
+
+    async def list_tools(self) -> List[Dict[str, Any]]:
+        """利用可能ツールの一覧"""
+        async with self.session.get(f"{self.base_url}/api/v1/mcp/tools") as resp:
+            data = await resp.json()
+            return data["tools"]
+
+    async def execute_tool(self, tool_name: str, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        """ツールを実行"""
+        payload = {
+            "tool_name": tool_name,
+            "parameters": parameters,
+            "session_id": self.session_id
+        }
+
+        async with self.session.post(
+            f"{self.base_url}/api/v1/mcp/execute",
+            json=payload
+        ) as resp:
+            return await resp.json()
+
+    async def ai_assistant_workflow(self, user_request: str) -> str:
+        """AI アシスタントのワークフローシミュレーション"""
+
+        # 1. セッション作成
+        await self.create_session()
+        print(f"Session created: {self.session_id}")
+
+        # 2. ユーザーリクエストを解析して適切なツールを選択
+        if "Create item" in user_request or "Create" in user_request:
+            # item 作成リクエスト
+            result = await self.execute_tool("create_item", {
+                "name": "AI recommended item",
+                "description": "AI generated item based on user request",
+                "price": 100000,
+                "category": "ai_recommended"
+            })
+
+            if result["success"]:
+                item_name = result["result"]["item"]["name"]
+                return f"✅ '{item_name}' item created successfully!"
+            else:
+                return f"❌ Item creation failed: {result.get('error', 'Unknown error')}"
+
+        elif "Search" in user_request or "Find" in user_request:
+            # 検索リクエスト
+            search_query = "Item"  # 実際は NLP で抽出
+            result = await self.execute_tool("search_items", {
+                "query": search_query,
+                "limit": 5
+            })
+
+            if result["success"]:
+                items = result["result"]["items"]
+                item_list = "\n".join([f"- {item['name']} (₩{item['price']:,})" for item in items])
+                return f"🔍 Search results ({len(items)} items):\n{item_list}"
+            else:
+                return f"❌ Search failed: {result.get('error', 'Unknown error')}"
+
+        elif "Analyze" in user_request:
+            # 分析リクエスト
+            result = await self.execute_tool("analyze_items", {
+                "analysis_type": "price_distribution"
+            })
+
+            if result["success"]:
+                analysis = result["result"]["result"]
+                return f"📊 Price analysis:\nAverage price: ₩{analysis['average_price']:,.0f}\nMinimum: ₩{analysis['min_price']:,} - Maximum: ₩{analysis['max_price']:,}"
+            else:
+                return f"❌ Analysis failed: {result.get('error', 'Unknown error')}"
+
+        else:
+            return "Sorry, I couldn't find a tool to handle that request."
+
+async def main():
+    """クライアントテスト"""
+    async with MCPClient("http://localhost:8000", "your-api-key-here") as client:
+
+        # 利用可能なツールを表示
+        tools = await client.list_tools()
+        print(f"Available tools: {len(tools)}")
+        for tool in tools:
+            print(f"- {tool['name']}: {tool['description']}")
+
+        print("\n" + "="*50 + "\n")
+
+        # AI アシスタントのシミュレーション
+        test_requests = [
+            "Create a new item",
+            "Search for items",
+            "Analyze price distribution"
+        ]
+
+        for request in test_requests:
+            print(f"User request: {request}")
+            response = await client.ai_assistant_workflow(request)
+            print(f"AI response: {response}")
+            print("-" * 30)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<!-- ## Next Steps
+
+You've completed MCP integration! Here are things you can try next: -->
+
+<!-- 1. **[Real-time Communication Implementation](websocket-realtime.md)** - Real-time MCP communication using WebSocket
+2. **[Microservices Architecture](microservices-architecture.md)** - Separating MCP server as a standalone service
+3. **[Performance Optimization](performance-optimization.md)** - Optimizing high-volume AI request processing
+4. **[Monitoring System](monitoring-system.md)** - MCP usage and performance monitoring -->
+
+## まとめ
+
+このチュートリアルでは、MCP (Model Context Protocol) の統合として次を実装しました:
+
+- ✅ JWT ベースの認証システム構築
+- ✅ ロールベースアクセス制御 (RBAC) の実装
+- ✅ MCP サーバーとツールシステムの実装
+- ✅ セッションベースのコンテキスト管理
+- ✅ AI モデルとの安全な API 通信
+- ✅ ツール権限管理と利用追跡
+- ✅ 実際の AI クライアント例の実装
+
+これで、AI モデルが API 機能を安全かつ効率的に利用できる MCP ベースのシステムを構築できます。
diff --git a/docs/ja/user-guide/adding-routes.md b/docs/ja/user-guide/adding-routes.md
new file mode 100644
index 0000000..d2e1078
--- /dev/null
+++ b/docs/ja/user-guide/adding-routes.md
@@ -0,0 +1,581 @@
+# ルートの追加
+
+既存の FastAPI プロジェクトに新しい API ルートを追加する方法を学びます。
+
+## 基本的なルート追加
+
+### `addroute` コマンドを使う
+
+FastAPI-fastkit の `addroute` コマンドは、新しいルートの追加を簡単にします:
+
+<div class="termy">
+
+```console
+$ fastkit addroute users my-awesome-api
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-awesome-api                           │
+│ Route Name       │ users                                    │
+│ Target Directory │ ~/my-awesome-api                         │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'users' to project 'my-awesome-api'? [Y/n]: y
+
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Updated main.py to include the API router          │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Successfully added new route 'users' to project    │
+│ `my-awesome-api`                                      │
+╰───────────────────────────────────────────────────────╯
+```
+
+</div>
+
+## 何が作成されるか
+
+ルートを追加すると、FastAPI-fastkit は次のファイルや設定を自動で生成します:
+
+### 1. ルートファイル: `src/api/routes/users.py`
+
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException, status
+from src.schemas.users import User, UserCreate, UserUpdate
+from src.crud.users import users_crud
+
+router = APIRouter()
+
+@router.get("/", response_model=List[User])
+def read_users():
+    """Get all users"""
+    return users_crud.get_all()
+
+@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
+def create_user(user: UserCreate):
+    """Create a new user"""
+    return users_crud.create(user)
+
+@router.get("/{user_id}", response_model=User)
+def read_user(user_id: int):
+    """Get a specific user"""
+    user = users_crud.get_by_id(user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+@router.put("/{user_id}", response_model=User)
+def update_user(user_id: int, user: UserUpdate):
+    """Update a user"""
+    updated_user = users_crud.update(user_id, user)
+    if updated_user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return updated_user
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_user(user_id: int):
+    """Delete a user"""
+    success = users_crud.delete(user_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="User not found")
+```
+
+### 2. CRUD 操作: `src/crud/users.py`
+
+```python
+from typing import List, Optional
+from src.schemas.users import User, UserCreate, UserUpdate
+
+class UsersCRUD:
+    def __init__(self):
+        self._users: List[User] = []
+        self._next_id = 1
+
+    def get_all(self) -> List[User]:
+        """Get all users"""
+        return self._users
+
+    def get_by_id(self, user_id: int) -> Optional[User]:
+        """Get user by ID"""
+        return next((user for user in self._users if user.id == user_id), None)
+
+    def create(self, user: UserCreate) -> User:
+        """Create a new user"""
+        new_user = User(
+            id=self._next_id,
+            title=user.title,
+            description=user.description
+        )
+        self._next_id += 1
+        self._users.append(new_user)
+        return new_user
+
+    def update(self, user_id: int, user: UserUpdate) -> Optional[User]:
+        """Update an existing user"""
+        existing_user = self.get_by_id(user_id)
+        if existing_user:
+            update_data = user.dict(exclude_unset=True)
+            for field, value in update_data.items():
+                setattr(existing_user, field, value)
+            return existing_user
+        return None
+
+    def delete(self, user_id: int) -> bool:
+        """Delete a user"""
+        user = self.get_by_id(user_id)
+        if user:
+            self._users.remove(user)
+            return True
+        return False
+
+users_crud = UsersCRUD()
+```
+
+### 3. Pydantic スキーマ: `src/schemas/users.py`
+
+```python
+from typing import Optional
+from pydantic import BaseModel
+
+class UserBase(BaseModel):
+    title: str
+    description: Optional[str] = None
+
+class UserCreate(UserBase):
+    pass
+
+class UserUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+
+class User(UserBase):
+    id: int
+
+    class Config:
+        from_attributes = True
+```
+
+### 4. ルーターの登録
+
+このコマンドは `src/api/api.py` を自動で更新し、新しいルーターを取り込みます:
+
+```python
+from fastapi import APIRouter
+from src.api.routes import items, users
+
+api_router = APIRouter()
+
+api_router.include_router(items.router, prefix="/items", tags=["items"])
+api_router.include_router(users.router, prefix="/users", tags=["users"])
+```
+
+## 生成される API エンドポイント
+
+`users` ルートを追加すると、次のエンドポイントが使えるようになります:
+
+| メソッド | エンドポイント | 説明 |
+|---|---|---|
+| `GET` | `/api/v1/users/` | すべてのユーザーを取得 |
+| `POST` | `/api/v1/users/` | 新しいユーザーを作成 |
+| `GET` | `/api/v1/users/{user_id}` | 特定のユーザーを取得 |
+| `PUT` | `/api/v1/users/{user_id}` | ユーザーを更新 |
+| `DELETE` | `/api/v1/users/{user_id}` | ユーザーを削除 |
+
+## 新しいルートのテスト
+
+### 1. サーバーの起動
+
+<div class="termy">
+
+```console
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+### 2. API ドキュメントの確認
+
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) にアクセスして、対話型ドキュメントで新しいエンドポイントを確認しましょう。
+
+### 3. curl でのテスト
+
+**ユーザーを作成:**
+<div class="termy">
+
+```console
+$ curl -X POST "http://127.0.0.1:8000/api/v1/users/" \
+     -H "Content-Type: application/json" \
+     -d '{"title": "John Doe", "description": "Software Developer"}'
+
+{
+  "id": 1,
+  "title": "John Doe",
+  "description": "Software Developer"
+}
+```
+
+</div>
+
+**すべてのユーザーを取得:**
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000/api/v1/users/
+
+[
+  {
+    "id": 1,
+    "title": "John Doe",
+    "description": "Software Developer"
+  }
+]
+```
+
+</div>
+
+**特定のユーザーを取得:**
+<div class="termy">
+
+```console
+$ curl http://127.0.0.1:8000/api/v1/users/1
+
+{
+  "id": 1,
+  "title": "John Doe",
+  "description": "Software Developer"
+}
+```
+
+</div>
+
+## 生成コードのカスタマイズ
+
+生成されたコードは完全にカスタマイズ可能です。よく行う変更例を示します:
+
+### 1. ユーザースキーマの拡張
+
+`src/schemas/users.py` をより実用的なユーザーデータ向けに変更します:
+
+```python
+from typing import Optional
+from datetime import datetime
+from pydantic import BaseModel, EmailStr, Field
+
+class UserBase(BaseModel):
+    email: EmailStr
+    username: str = Field(..., min_length=3, max_length=50)
+    full_name: Optional[str] = None
+    is_active: bool = True
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+class UserUpdate(BaseModel):
+    email: Optional[EmailStr] = None
+    username: Optional[str] = Field(None, min_length=3, max_length=50)
+    full_name: Optional[str] = None
+    is_active: Optional[bool] = None
+
+class User(UserBase):
+    id: int
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+class UserInDB(User):
+    hashed_password: str
+```
+
+### 2. 検証つきの CRUD 拡張
+
+`src/crud/users.py` を、より洗練された検証で更新します:
+
+```python
+from typing import List, Optional
+from datetime import datetime
+import hashlib
+from src.schemas.users import UserCreate, UserUpdate, UserInDB
+
+class UsersCRUD:
+    def __init__(self):
+        self._users: List[UserInDB] = []
+        self._next_id = 1
+
+    def _hash_password(self, password: str) -> str:
+        """Simple password hashing (use bcrypt in production)"""
+        return hashlib.sha256(password.encode()).hexdigest()
+
+    def get_by_email(self, email: str) -> Optional[UserInDB]:
+        """Get user by email"""
+        return next((user for user in self._users if user.email == email), None)
+
+    def get_by_username(self, username: str) -> Optional[UserInDB]:
+        """Get user by username"""
+        return next((user for user in self._users if user.username == username), None)
+
+    def create(self, user: UserCreate) -> UserInDB:
+        """Create a new user with validation"""
+        # Check for duplicates
+        if self.get_by_email(user.email):
+            raise ValueError("Email already registered")
+        if self.get_by_username(user.username):
+            raise ValueError("Username already taken")
+
+        new_user = UserInDB(
+            id=self._next_id,
+            email=user.email,
+            username=user.username,
+            full_name=user.full_name,
+            is_active=user.is_active,
+            created_at=datetime.now(),
+            hashed_password=self._hash_password(user.password)
+        )
+        self._next_id += 1
+        self._users.append(new_user)
+        return new_user
+
+users_crud = UsersCRUD()
+```
+
+### 3. エラーハンドリングを強化したルート
+
+`src/api/routes/users.py` を、より丁寧なエラーハンドリングで更新します:
+
+```python
+from typing import List
+from fastapi import APIRouter, HTTPException, status
+from src.schemas.users import User, UserCreate, UserUpdate
+from src.crud.users import users_crud
+
+router = APIRouter()
+
+@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
+def create_user(user: UserCreate):
+    """Create a new user"""
+    try:
+        new_user = users_crud.create(user)
+        # Return user without password hash
+        return User(**new_user.dict())
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+@router.get("/{user_id}", response_model=User)
+def read_user(user_id: int):
+    """Get a specific user"""
+    user = users_crud.get_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"User with id {user_id} not found"
+        )
+    return User(**user.dict())
+```
+
+## 複数のルートを追加する
+
+複数のルートを追加して、本格的な API に育てていくこともできます:
+
+<div class="termy">
+
+```console
+# リソースルートを追加 (ルート名が先、プロジェクトディレクトリが後)
+$ fastkit addroute products my-awesome-api
+$ fastkit addroute orders my-awesome-api
+$ fastkit addroute categories my-awesome-api
+
+# それぞれが完全な CRUD 構造を生成します
+```
+
+</div>
+
+これで次のような包括的な API が生成されます:
+
+- `/api/v1/users/` - ユーザー管理
+- `/api/v1/products/` - 商品カタログ
+- `/api/v1/orders/` - 注文処理
+- `/api/v1/categories/` - カテゴリ管理
+
+## ルートの整理
+
+### 関連エンドポイントのグループ化
+
+ドメインごとにルートを整理できます:
+
+```python
+# src/api/api.py
+from fastapi import APIRouter
+from src.api.routes import users, products, orders, categories
+
+api_router = APIRouter()
+
+# User management
+api_router.include_router(
+    users.router,
+    prefix="/users",
+    tags=["User Management"]
+)
+
+# E-commerce
+api_router.include_router(
+    products.router,
+    prefix="/products",
+    tags=["E-commerce"]
+)
+api_router.include_router(
+    orders.router,
+    prefix="/orders",
+    tags=["E-commerce"]
+)
+api_router.include_router(
+    categories.router,
+    prefix="/categories",
+    tags=["E-commerce"]
+)
+```
+
+### ルートに依存性を追加
+
+認証などの依存性を追加します:
+
+```python
+from fastapi import APIRouter, Depends
+from src.core.auth import get_current_user
+
+router = APIRouter()
+
+@router.get("/profile", response_model=User)
+def get_user_profile(current_user: User = Depends(get_current_user)):
+    """Get current user's profile"""
+    return current_user
+
+@router.post("/", response_model=User)
+def create_user(
+    user: UserCreate,
+    current_user: User = Depends(get_current_user)
+):
+    """Create a new user (admin only)"""
+    if not current_user.is_admin:
+        raise HTTPException(status_code=403, detail="Admin access required")
+    return users_crud.create(user)
+```
+
+## ベストプラクティス
+
+### 1. 一貫した命名
+
+一貫した命名規則に従いましょう:
+
+- **ルート名**: 複数形の名詞を使用 (`users`、`products`、`orders`)
+- **スキーマ名**: 単数形を使用 (`User`、`Product`、`Order`)
+- **CRUD クラス**: 末尾を `CRUD` に統一 (`UsersCRUD`、`ProductsCRUD`)
+
+### 2. エラーハンドリング
+
+常にエラーを丁寧に扱いましょう:
+
+```python
+@router.post("/", response_model=User)
+def create_user(user: UserCreate):
+    try:
+        return users_crud.create(user)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail="Internal server error")
+```
+
+### 3. ドキュメント
+
+充実した docstring を書きましょう:
+
+```python
+@router.get("/{user_id}", response_model=User)
+def read_user(user_id: int):
+    """
+    Get a specific user by ID.
+
+    Args:
+        user_id: The unique identifier for the user
+
+    Returns:
+        User: The user object with all details
+
+    Raises:
+        HTTPException: 404 if user not found
+    """
+    user = users_crud.get_by_id(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+### 4. テスト
+
+新しいルートには必ずテストを書きましょう:
+
+```python
+# tests/test_users.py
+from fastapi.testclient import TestClient
+from src.main import app
+
+client = TestClient(app)
+
+def test_create_user():
+    user_data = {
+        "email": "test@example.com",
+        "username": "testuser",
+        "password": "securepassword123"
+    }
+    response = client.post("/api/v1/users/", json=user_data)
+    assert response.status_code == 201
+    assert response.json()["email"] == user_data["email"]
+
+def test_get_user():
+    response = client.get("/api/v1/users/1")
+    assert response.status_code == 200
+```
+
+## トラブルシューティング
+
+### ルートが表示されない
+
+API ドキュメントにルートが表示されない場合:
+
+1. `src/api/api.py` の **ルーター登録を確認**
+2. ルート追加後に **サーバーを再起動**
+3. ルートファイルに **インポートエラーがないか確認**
+
+### インポートエラー
+
+インポートエラーが発生する場合:
+
+1. **ファイル構造** が想定どおりか確認
+2. ルートと CRUD ファイルの **スキーマインポート** を確認
+3. **すべての `__init__.py` ファイルが存在するか確認**
+
+### サーバーが起動しない
+
+ルート追加後にサーバーが起動しない場合:
+
+1. 生成ファイルに **構文エラーがないか確認**
+2. ファイル間の **スキーマ互換性** を確認
+3. 具体的なエラーメッセージについて **ログを確認**
+
+## 次のステップ
+
+ルートの追加方法を理解できたら:
+
+1. **[最初のプロジェクト](../tutorial/first-project.md)**: 完全なブログ API を構築
+2. **[CLI リファレンス](cli-reference.md)**: 利用可能なすべてのコマンドを学ぶ
+3. **[テンプレートの利用](using-templates.md)**: 事前構築済みのプロジェクトテンプレートを試す
+
+!!! tip "ルート開発のヒント"
+    - 新しいルートは常に対話型ドキュメント (`/docs`) でテストしましょう
+    - 意味のある HTTP ステータスコードを使いましょう
+    - すべてのエンドポイントに適切なエラーハンドリングを実装しましょう
+    - ルートハンドラはシンプルに保ち、ビジネスロジックは CRUD クラスへ委譲しましょう
diff --git a/docs/ja/user-guide/cli-reference.md b/docs/ja/user-guide/cli-reference.md
new file mode 100644
index 0000000..1235793
--- /dev/null
+++ b/docs/ja/user-guide/cli-reference.md
@@ -0,0 +1,832 @@
+# CLI リファレンス
+
+FastAPI-fastkit の全 CLI コマンドを網羅したリファレンスです。
+
+## グローバルオプション
+
+すべてのコマンドは次のグローバルオプションをサポートしています:
+
+```console
+$ fastkit [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]
+```
+
+### グローバルオプション
+
+| オプション | 説明 |
+|---|---|
+| `--version` | FastAPI-fastkit のバージョンを表示 |
+| `--help` | ヘルプメッセージを表示 |
+
+### 例
+
+<div class="termy">
+
+```console
+$ fastkit --version
+FastAPI-fastkit version 1.0.0
+
+$ fastkit --help
+Usage: fastkit [OPTIONS] COMMAND [ARGS]...
+
+  FastAPI-fastkit CLI
+
+Options:
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  addroute       Add a new route to FastAPI project
+  init           Create a new FastAPI project
+  list-templates List available FastAPI templates
+  runserver      Start FastAPI development server
+  startdemo      Create FastAPI project from template
+```
+
+</div>
+
+## コマンド
+
+### `init`
+
+対話型セットアップで新しい FastAPI プロジェクトを作成します。
+
+#### 構文
+
+```console
+$ fastkit init [OPTIONS]
+```
+
+#### オプション
+
+| オプション | 説明 | デフォルト |
+|---|---|---|
+| `--package-manager` | 使用するパッケージマネージャー (pip, uv, pdm, poetry) | uv |
+| `--help` | コマンドのヘルプを表示 | - |
+
+#### 対話型プロンプト
+
+`init` コマンドは以下を尋ねます:
+
+1. **プロジェクト名**: ディレクトリ名およびパッケージ名
+2. **作者名**: パッケージの作者情報
+3. **作者メール**: パッケージの連絡先メール
+4. **プロジェクト説明**: プロジェクトの概要
+5. **スタック選択**: minimal、standard、full から選択
+6. **パッケージマネージャー選択**: pip、uv、pdm、poetry から選択 (`--package-manager` で指定しない場合)
+
+#### スタックオプション
+
+**MINIMAL スタック:**
+
+- `fastapi` - FastAPI フレームワーク
+- `uvicorn` - ASGI サーバー
+- `pydantic` - データ検証
+- `pydantic-settings` - 設定管理
+
+**STANDARD スタック:**
+
+- MINIMAL スタックのすべてのパッケージ
+- `sqlalchemy` - SQL ツールキットおよび ORM
+- `alembic` - データベースマイグレーションツール
+- `pytest` - テストフレームワーク
+
+**FULL スタック:**
+
+- STANDARD スタックのすべてのパッケージ
+- `redis` - インメモリデータストア
+- `celery` - 分散タスクキュー
+
+#### 例
+
+<div class="termy">
+
+```console
+$ fastkit init
+Enter the project name: my-api
+Enter the author name: John Doe
+Enter the author email: john@example.com
+Enter the project description: My awesome API
+
+Select stack (minimal, standard, full): standard
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'my-api' has been created successfully!
+```
+
+</div>
+
+#### 生成される構造
+
+次の構造のプロジェクトが作成されます:
+
+```
+my-api/
+├── .venv/                    # 仮想環境
+├── src/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI アプリケーション
+│   ├── core/
+│   │   ├── __init__.py
+│   │   └── config.py        # 設定
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── api.py          # API ルーター集約
+│   │   └── routes/
+│   │       ├── __init__.py
+│   │       └── items.py     # サンプルルート
+│   ├── crud/
+│   │   ├── __init__.py
+│   │   └── items.py         # CRUD 操作
+│   ├── schemas/
+│   │   ├── __init__.py
+│   │   └── items.py         # Pydantic スキーマ
+│   └── mocks/
+│       ├── __init__.py
+│       └── mock_items.json  # テストデータ
+├── tests/
+├── scripts/
+├── requirements.txt
+├── setup.py
+└── README.md
+```
+
+### `addroute`
+
+既存の FastAPI プロジェクトに新しい API ルートを追加します。
+
+#### 構文
+
+```console
+$ fastkit addroute ROUTE_NAME [PROJECT_DIR] [OPTIONS]
+```
+
+#### 引数
+
+| 引数 | 説明 | 必須 |
+|---|---|---|
+| `ROUTE_NAME` | 新しいルート名 (複数形を推奨) | はい |
+| `PROJECT_DIR` | 対象のプロジェクトディレクトリ (デフォルトは `.` (現在のディレクトリ)) | いいえ |
+
+#### オプション
+
+| オプション | 説明 | デフォルト |
+|---|---|---|
+| `--help` | コマンドのヘルプを表示 | - |
+
+#### 例
+
+<div class="termy">
+
+```console
+$ cd my-api
+$ fastkit addroute users
+                       Adding New Route
+┌──────────────────┬──────────────────────────────────────────┐
+│ Project          │ my-api                                   │
+│ Route Name       │ users                                    │
+│ Target Directory │ ~/my-api                                 │
+└──────────────────┴──────────────────────────────────────────┘
+
+Do you want to add route 'users' to project 'my-api'? [Y/n]: y
+
+✨ Successfully added new route 'users' to project 'my-api'
+```
+
+</div>
+
+`cd` しなくても、対象のプロジェクトを名前で指定できます:
+
+<div class="termy">
+
+```console
+$ fastkit addroute users my-api
+```
+
+</div>
+
+#### 生成されるファイル
+
+プロジェクトに次のファイルが作成されます:
+
+- `src/api/routes/users.py` - ルートハンドラ
+- `src/crud/users.py` - CRUD 操作
+- `src/schemas/users.py` - Pydantic スキーマ
+
+また、新しいルーターを取り込むよう `src/api/api.py` も自動更新されます。
+
+#### 生成されるエンドポイント
+
+完全な CRUD エンドポイントが作成されます:
+
+| メソッド | エンドポイント | 説明 |
+|---|---|---|
+| `GET` | `/api/v1/users/` | すべてのユーザーを取得 |
+| `POST` | `/api/v1/users/` | 新しいユーザーを作成 |
+| `GET` | `/api/v1/users/{user_id}` | 特定のユーザーを取得 |
+| `PUT` | `/api/v1/users/{user_id}` | ユーザーを更新 |
+| `DELETE` | `/api/v1/users/{user_id}` | ユーザーを削除 |
+
+### `startdemo`
+
+あらかじめ用意されたテンプレートから FastAPI プロジェクトを作成します。
+
+#### 構文
+
+```console
+$ fastkit startdemo [OPTIONS]
+```
+
+#### オプション
+
+| オプション | 説明 | デフォルト |
+|---|---|---|
+| `--package-manager` | 使用するパッケージマネージャー (pip, uv, pdm, poetry) | uv |
+| `--help` | コマンドのヘルプを表示 | - |
+
+#### 対話型プロンプト
+
+`startdemo` コマンドは以下を尋ねます:
+
+1. **プロジェクト名**: 新しいプロジェクトのディレクトリ名
+2. **作者名**: パッケージの作者情報
+3. **作者メール**: 連絡先メール
+4. **プロジェクト説明**: プロジェクトの概要
+5. **パッケージマネージャー選択**: pip、uv、pdm、poetry から選択 (`--package-manager` で指定しない場合)
+
+#### 利用可能なテンプレート
+
+| テンプレート | 説明 | 機能 |
+|---|---|---|
+| `fastapi-default` | シンプルな FastAPI プロジェクト | 基本的な CRUD、モックデータ |
+| `fastapi-async-crud` | 非同期アイテム管理 API | async/await、パフォーマンス重視 |
+| `fastapi-custom-response` | カスタムレスポンス機構 | カスタムレスポンス、ページネーション |
+| `fastapi-dockerized` | Docker 化された FastAPI API | Docker、本番運用対応 |
+| `fastapi-psql-orm` | PostgreSQL 連携 FastAPI API | PostgreSQL、SQLAlchemy、Alembic |
+| `fastapi-empty` | 最小構成 FastAPI プロジェクト | 必要最低限のセットアップ |
+
+#### 例
+
+<div class="termy">
+
+```console
+$ fastkit startdemo fastapi-psql-orm
+Enter the project name: my-blog
+Enter the author name: Jane Smith
+Enter the author email: jane@example.com
+Enter the project description: Blog API with PostgreSQL
+
+Select package manager (pip, uv, pdm, poetry) [uv]: poetry
+Do you want to proceed with project creation? [y/N]: y
+
+✨ FastAPI project 'my-blog' from 'fastapi-psql-orm' has been created!
+```
+
+</div>
+
+### `runserver`
+
+FastAPI 開発サーバーを起動します。
+
+#### 構文
+
+```console
+$ fastkit runserver [OPTIONS]
+```
+
+#### オプション
+
+| オプション | 短縮形 | 説明 | デフォルト |
+|---|---|---|---|
+| `--host` | `-h` | バインドするホスト | `127.0.0.1` |
+| `--port` | `-p` | バインドするポート | `8000` |
+| `--reload` | `-r` | 自動リロードを有効化 | `True` |
+| `--workers` | `-w` | ワーカー数 | `1` |
+| `--help` | | コマンドのヘルプを表示 | - |
+
+#### 例
+
+<div class="termy">
+
+```console
+# 基本的な使い方 (デフォルト設定)
+$ fastkit runserver
+INFO:     Uvicorn running on http://127.0.0.1:8000
+
+# ホストとポートのカスタマイズ
+$ fastkit runserver --host 0.0.0.0 --port 8080
+INFO:     Uvicorn running on http://0.0.0.0:8080
+
+# 自動リロードを無効化
+$ fastkit runserver --no-reload
+INFO:     Uvicorn running on http://127.0.0.1:8000
+
+# 複数ワーカー (本番運用)
+$ fastkit runserver --workers 4
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+</div>
+
+#### 動作要件
+
+- FastAPI プロジェクトのディレクトリで実行する必要がある
+- プロジェクトに FastAPI アプリを含む `src/main.py` が存在する必要がある
+- 仮想環境を有効化しておくこと
+
+### `list-templates`
+
+利用可能なすべての FastAPI プロジェクトテンプレートを一覧表示します。
+
+#### 構文
+
+```console
+$ fastkit list-templates [OPTIONS]
+```
+
+#### オプション
+
+| オプション | 説明 | デフォルト |
+|---|---|---|
+| `--help` | コマンドのヘルプを表示 | - |
+
+#### 例
+
+<div class="termy">
+
+```console
+$ fastkit list-templates
+                      Available Templates
+┌─────────────────────────┬───────────────────────────────────┐
+│ fastapi-custom-response │ Async Item Management API with    │
+│                         │ Custom Response System            │
+│ fastapi-dockerized      │ Dockerized FastAPI Item           │
+│                         │ Management API                    │
+│ fastapi-empty           │ No description                    │
+│ fastapi-async-crud      │ Async Item Management API Server  │
+│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
+│                         │ Management API with PostgreSQL    │
+│ fastapi-default         │ Simple FastAPI Project            │
+└─────────────────────────┴───────────────────────────────────┘
+```
+
+</div>
+
+## 環境変数
+
+FastAPI-fastkit は次の環境変数を尊重します:
+
+| 変数 | 説明 | デフォルト |
+|---|---|---|
+| `FASTKIT_CONFIG_DIR` | 設定ディレクトリ | `~/.fastkit` |
+| `FASTKIT_TEMPLATES_DIR` | カスタムテンプレートのディレクトリ | 組み込みテンプレート |
+| `FASTKIT_LOG_LEVEL` | ロギングレベル | `INFO` |
+
+### 例
+
+<div class="termy">
+
+```console
+# 設定ディレクトリのカスタマイズ
+$ export FASTKIT_CONFIG_DIR=~/my-fastkit-config
+$ fastkit init
+
+# カスタムテンプレートディレクトリ
+$ export FASTKIT_TEMPLATES_DIR=~/my-templates
+$ fastkit list-templates
+
+# デバッグログ
+$ export FASTKIT_LOG_LEVEL=DEBUG
+$ fastkit init
+```
+
+</div>
+
+## 設定ファイル
+
+FastAPI-fastkit はデフォルト設定として設定ファイルを利用できます。
+
+### 設定ファイルの場所
+
+1. `$FASTKIT_CONFIG_DIR/config.yaml` (`FASTKIT_CONFIG_DIR` が設定されている場合)
+2. `~/.fastkit/config.yaml` (デフォルト)
+3. `./fastkit.yaml` (プロジェクト固有)
+
+### 設定ファイル形式
+
+```yaml
+# ~/.fastkit/config.yaml
+default:
+  author:
+    name: "Your Name"
+    email: "your.email@example.com"
+
+  project:
+    stack: "standard"
+    create_venv: true
+    install_deps: true
+
+  server:
+    host: "127.0.0.1"
+    port: 8000
+    reload: true
+
+templates:
+  custom_dir: "~/my-templates"
+
+logging:
+  level: "INFO"
+  file: "~/.fastkit/logs/fastkit.log"
+```
+
+## よくあるワークフロー
+
+### 1. 新しいプロジェクトを作成する
+
+<div class="termy">
+
+```console
+# 新しいプロジェクトを作成
+$ fastkit init
+# プロンプトに従う ...
+
+# プロジェクトに移動
+$ cd my-awesome-api
+
+# 仮想環境を有効化
+$ source .venv/bin/activate
+
+# 開発サーバーを起動
+$ fastkit runserver
+```
+
+</div>
+
+### 2. 既存プロジェクトに機能を追加する
+
+<div class="termy">
+
+```console
+# 複数のルートを追加 (2 番目の位置引数 = 対象のプロジェクトディレクトリ)
+$ fastkit addroute users my-api
+$ fastkit addroute products my-api
+$ fastkit addroute orders my-api
+
+# API をテスト
+$ fastkit runserver
+# http://127.0.0.1:8000/docs を開く
+```
+
+</div>
+
+### 3. 複雑なプロジェクトのためにテンプレートを利用する
+
+<div class="termy">
+
+```console
+# 利用可能なテンプレートを表示
+$ fastkit list-templates
+
+# テンプレートから作成
+$ fastkit startdemo
+# データベースプロジェクトには fastapi-psql-orm を選択
+
+# データベースのセットアップ (PostgreSQL テンプレートの場合)
+$ cd my-project
+$ docker-compose up -d postgres
+$ source .venv/bin/activate
+$ alembic upgrade head
+$ fastkit runserver
+```
+
+</div>
+
+## トラブルシューティング
+
+### コマンドが見つからない
+
+`fastkit` コマンドが見つからない場合:
+
+1. **インストールを確認:**
+   <div class="termy">
+   ```console
+   $ pip show fastapi-fastkit
+   ```
+   </div>
+
+2. **必要に応じて再インストール:**
+   <div class="termy">
+   ```console
+   $ pip uninstall fastapi-fastkit
+   $ pip install fastapi-fastkit
+   ```
+   </div>
+
+3. **PATH を確認:**
+   <div class="termy">
+   ```console
+   $ which fastkit
+   ```
+   </div>
+
+### 仮想環境の問題
+
+仮想環境の作成に失敗する場合:
+
+1. **Python のバージョンを確認:**
+   <div class="termy">
+   ```console
+   $ python --version  # 3.12+ である必要があります
+   ```
+   </div>
+
+2. **venv モジュールを確認:**
+   <div class="termy">
+   ```console
+   $ python -m venv --help
+   ```
+   </div>
+
+3. **手動で仮想環境を作成:**
+   <div class="termy">
+   ```console
+   $ python -m venv .venv
+   $ source .venv/bin/activate
+   $ pip install -r requirements.txt
+   ```
+   </div>
+
+### サーバーが起動しない
+
+`fastkit runserver` に失敗する場合:
+
+1. **プロジェクトディレクトリにいるか確認**
+2. **`src/main.py` が存在するか確認**
+3. **仮想環境を有効化:**
+   <div class="termy">
+   ```console
+   $ source .venv/bin/activate
+   ```
+   </div>
+
+4. **構文エラーを確認:**
+   <div class="termy">
+   ```console
+   $ python -c "from src.main import app"
+   ```
+   </div>
+
+### ポートが既に使われている
+
+ポート 8000 がビジー状態の場合:
+
+<div class="termy">
+
+```console
+# 別のポートを使う
+$ fastkit runserver --port 8080
+
+# あるいは既存プロセスを終了
+$ lsof -ti:8000 | xargs kill -9
+```
+
+</div>
+
+## 高度な使い方
+
+### カスタムテンプレート
+
+次の手順でカスタムテンプレートを作成できます:
+
+1. **テンプレートディレクトリを作成:**
+   ```
+   my-template/
+   ├── src/
+   │   └── main.py-tpl
+   ├── requirements.txt-tpl
+   └── setup.py-tpl
+   ```
+
+2. **環境変数を設定:**
+   <div class="termy">
+   ```console
+   $ export FASTKIT_TEMPLATES_DIR=~/my-templates
+   ```
+   </div>
+
+3. **カスタムテンプレートを利用:**
+   <div class="termy">
+   ```console
+   $ fastkit startdemo
+   # 一覧にカスタムテンプレートが表示されます
+   ```
+   </div>
+
+### FastAPI-fastkit をスクリプトから使う
+
+FastAPI-fastkit はスクリプトから利用できます:
+
+```bash
+#!/bin/bash
+# create-microservices.sh
+
+for service in users products orders; do
+    echo "Creating $service service..."
+    fastkit init <<EOF
+$service-service
+Company Team
+team@company.com
+$service microservice
+minimal
+y
+EOF
+
+    cd "$service-service"
+    fastkit addroute "$service"
+    cd ..
+done
+```
+
+### CI/CD との統合
+
+GitHub Actions ワークフローの例:
+
+```yaml
+name: Test FastAPI-fastkit Project
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.12'
+
+    - name: Install FastAPI-fastkit
+      run: pip install fastapi-fastkit
+
+    - name: Create test project
+      run: |
+        fastkit init <<EOF
+        test-project
+        CI
+        ci@example.com
+        Test project
+        standard
+        y
+        EOF
+
+    - name: Test project
+      run: |
+        cd test-project
+        source .venv/bin/activate
+        python -m pytest
+```
+
+## パッケージマネージャーのサポート
+
+FastAPI-fastkit は複数の Python パッケージマネージャーをサポートしており、ワークフローに最も合うものを選べます。
+
+### サポートされるパッケージマネージャー
+
+| マネージャー | 説明 | 依存関係ファイル | 適した用途 |
+|---|---|---|---|
+| **UV** (デフォルト) | 高速な Python パッケージマネージャー | `pyproject.toml` | 速度とパフォーマンス |
+| **PDM** | モダンな Python 依存関係管理 | `pyproject.toml` | 高度な依存関係解決 |
+| **Poetry** | Python の依存関係管理とパッケージング | `pyproject.toml` | Poetry 中心のワークフロー |
+| **PIP** | 標準の Python パッケージマネージャー | `requirements.txt` | 伝統的な Python 開発 |
+
+### パッケージマネージャーの指定
+
+#### グローバル設定
+
+すべてのプロジェクトで使うパッケージマネージャーを指定できます:
+
+```console
+# コマンドラインオプションで指定
+$ fastkit init --package-manager poetry
+$ fastkit startdemo --package-manager pdm
+```
+
+#### プロジェクトごとの選択
+
+各プロジェクトで異なるパッケージマネージャーを使えます。プロジェクト作成時に選択し、次に影響します:
+
+- **依存関係ファイル形式**: 各マネージャーが適切なファイルを作成
+- **仮想環境管理**: 有効化方法が異なる
+- **依存関係のインストール**: マネージャー固有のコマンド
+
+### パッケージマネージャーの特徴
+
+#### UV (デフォルト)
+- **高速**: Rust 製で非常に高速な依存関係解決
+- **互換性**: pip・pip-tools をそのまま置き換えられる
+- **モダン**: PEP 621 のプロジェクトメタデータをサポート
+
+<div class="termy">
+
+```console
+$ fastkit init --package-manager uv
+# UV 用設定の pyproject.toml を生成
+```
+
+</div>
+
+#### PDM
+- **モダン**: PEP 582 / PEP 621 をサポート
+- **高度**: 洗練された依存関係解決
+- **柔軟**: 複数のプロジェクトレイアウトに対応
+
+<div class="termy">
+
+```console
+$ fastkit init --package-manager pdm
+# PDM 用設定の pyproject.toml を生成
+```
+
+</div>
+
+#### Poetry
+- **定番**: 成熟しており広く採用
+- **統合**: ビルド・公開までサポート
+- **ロックファイル**: poetry.lock により再現可能なビルド
+
+<div class="termy">
+
+```console
+$ fastkit init --package-manager poetry
+# Poetry 用設定の pyproject.toml を生成
+```
+
+</div>
+
+#### PIP
+- **標準**: Python に標準で含まれる
+- **互換性**: あらゆる環境で動作
+- **シンプル**: 素直な依存関係管理
+
+<div class="termy">
+
+```console
+$ fastkit init --package-manager pip
+# requirements.txt を生成
+```
+
+</div>
+
+### プロジェクトでの作業
+
+特定のパッケージマネージャーでプロジェクトを作成した後は:
+
+#### UV プロジェクト
+```console
+cd my-project
+uv sync          # 依存関係をインストール
+uv add requests  # 新しい依存関係を追加
+uv run pytest   # 環境内でコマンドを実行
+```
+
+#### PDM プロジェクト
+```console
+cd my-project
+pdm install      # 依存関係をインストール
+pdm add requests # 新しい依存関係を追加
+pdm run pytest  # 環境内でコマンドを実行
+```
+
+#### Poetry プロジェクト
+```console
+cd my-project
+poetry install      # 依存関係をインストール
+poetry add requests # 新しい依存関係を追加
+poetry run pytest  # 環境内でコマンドを実行
+```
+
+#### PIP プロジェクト
+```console
+cd my-project
+source .venv/bin/activate  # Linux/macOS
+.venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+pip install requests
+pytest
+```
+
+## 次のステップ
+
+CLI を理解できたら:
+
+1. **[クイックスタート](quick-start.md)**: コマンドを実際に試す
+2. **[最初のプロジェクト](../tutorial/first-project.md)**: 完全なアプリケーションを構築
+3. **[コントリビュート](../contributing/development-setup.md)**: FastAPI-fastkit に貢献する
+
+!!! tip "CLI のヒント"
+    - 詳細なヘルプを得るには各コマンドに `--help` を付けましょう
+    - 既定値を設定すると、プロジェクト作成を高速化できます
+    - 構成が複雑なプロジェクトではテンプレートを活用しましょう
+    - コマンドを組み合わせて強力なワークフローを作りましょう
diff --git a/docs/ko/reference/translation-status.md b/docs/ko/reference/translation-status.md
index 3dca383..3de70f9 100644
--- a/docs/ko/reference/translation-status.md
+++ b/docs/ko/reference/translation-status.md
@@ -20,13 +20,13 @@ FastAPI-fastkit 문서는 여러 언어로 빌드되지만, 모든 번역이 **
 |---|---|---:|---|
 | 🇬🇧 English (`en`) | ✅ 원본 | 26 / 26 | 기준이 되는 원문입니다. |
 | 🇰🇷 한국어 (`ko`) | ✅ 완료 | 26 / 26 | 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. `docs/ko/changelog.md` 는 영문 기준 `CHANGELOG.md` 를 그대로 사용합니다. |
-| 🇯🇵 일본어 (`ja`) | 🟡 부분 번역 | 7 / 26 | Phase 1 반영: 최상위 + 핵심 user-guide + `reference/translation-status.md`. 나머지 페이지는 영어 원문으로 대체됩니다. |
+| 🇯🇵 일본어 (`ja`) | ✅ 완료 | 26 / 26 | 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. `docs/ja/changelog.md` 는 영문 기준 `CHANGELOG.md` 를 그대로 사용합니다. |
 | 🇨🇳 중국어 (`zh`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇪🇸 스페인어 (`es`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇫🇷 프랑스어 (`fr`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 | 🇩🇪 독일어 (`de`) | 🔴 기본 구조만 있음 | 0 / 26 | 빌드 대상만 설정되어 있으며, 모든 페이지는 영어 원문으로 표시됩니다. |
 
-*스냅샷 검증 시점: 2026-05-10. Phase 1(최상위 + 핵심 user-guide + `reference/translation-status.md`) 작업이 반영된 현재 브랜치 기준으로 `ja` 행을 다시 집계했습니다.* 이 표는 수동으로 관리됩니다. 리포지토리 루트에서 현재 상태를 다시 세고 싶다면 다음 명령을 실행하세요:
+*스냅샷 검증 시점: 2026-05-10. Phase 3(contributing + reference) 작업이 반영된 현재 브랜치 기준으로 `ja` 행을 다시 집계했습니다. 일본어는 언어별 페이지가 모두 존재하며, `docs/ja/changelog.md` 는 영문 기준 changelog를 그대로 가리킵니다.* 이 표는 수동으로 관리됩니다. 리포지토리 루트에서 현재 상태를 다시 세고 싶다면 다음 명령을 실행하세요:
 
 ```console
 $ for loc in en ko ja zh es fr de; do

From 12635867f50653dd0a216fd251aa0e2704efeac4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=A4=80=ED=98=81?= <bbbong9@gmail.com>
Date: Mon, 11 May 2026 10:00:21 +0900
Subject: [PATCH 3/3] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 docs/ja/contributing/translation-guide.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ja/contributing/translation-guide.md b/docs/ja/contributing/translation-guide.md
index 1ca60df..da8d57f 100644
--- a/docs/ja/contributing/translation-guide.md
+++ b/docs/ja/contributing/translation-guide.md
@@ -176,11 +176,11 @@ docs/
 
 ### 1. 英語でドキュメントを書く
 
-すべてのドキュメントは、まず英語で `docs/` ディレクトリに記述します:
+すべてのドキュメントは、まず英語で `docs/en/` ディレクトリに記述します:
 
 ```bash
 # 新しいドキュメントを作成
-vim docs/user-guide/new-feature.md
+vim docs/en/user-guide/new-feature.md
 ```
 
 ### 2. 翻訳を実行