アプリケーション開発環境セットアップ手順書¶
概要¶
本ドキュメントは、{プロジェクト名}のアプリケーション開発環境をセットアップする手順を説明します。
テスト駆動開発（TDD）のゴールは 動作するきれいなコード です。それを実現するためには ソフトウェア開発の三種の神器 が必要です。
今日のソフトウェア開発の世界において絶対になければならない 3 つの技術的な柱があります。 三本柱と言ったり、三種の神器と言ったりしていますが、それらは
- バージョン管理
- テスティング
- 自動化
の 3 つです。
— https://t-wada.hatenablog.jp/entry/clean-code-that-works
1. 前提条件¶
以下のツールがインストールされていることを確認してください。
| ツール | バージョン | 確認コマンド |
|---|---|---|
| {言語ランタイム} | {バージョン} | {確認コマンド} |
| {ビルドツール} | {バージョン} | {確認コマンド} |
| Docker | 最新 | docker -v |
| Docker Compose | v2.x | docker compose version |
| Git | 最新 | git -v |
| Node.js | v22.x LTS | node -v |
| npm | v10.x | npm -v |
{言語ランタイム}のインストール¶
{言語ランタイム}をインストールします。バージョン管理ツールを使用すると複数バージョンの管理が容易です。
# バージョン管理ツールでインストール
{インストールコマンド}
# バージョン確認
{確認コマンド}
公式サイトから直接ダウンロードする場合：
- {公式サイト URL}
Docker のインストール¶
Docker Desktop をインストールします。
- Windows: https://docs.docker.com/desktop/install/windows-install/
- macOS: https://docs.docker.com/desktop/install/mac-install/
# バージョン確認
docker -v
docker compose version
Node.js のインストール¶
コミット前の品質チェック（husky + lint-staged）に Node.js が必要です。
- https://nodejs.org/
# バージョン確認
node -v
npm -v
2. プロジェクトの取得¶
リポジトリのクローン¶
git clone {リポジトリ URL}
cd {プロジェクトディレクトリ}
Node.js 依存パッケージのインストール¶
npm install
Note: husky（Git Hooks）が
prepareスクリプトで自動的にセットアップされます。
3. サブシステム一覧¶
{プロジェクト名}は以下のサブシステムで構成されています。
| システム | ディレクトリ | 説明 | ポート (DB / App) |
|---|---|---|---|
| {システム名} | {ディレクトリ} |
{説明} | {DB ポート} / |
4. 技術スタック¶
バックエンド¶
| カテゴリ | 技術 | バージョン |
|---|---|---|
| 言語 | {言語} | {バージョン} |
| フレームワーク | {フレームワーク} | {バージョン} |
| ビルドツール | {ビルドツール} | {バージョン} |
| ORM | {ORM} | {バージョン} |
| データベース | {データベース} | {バージョン} |
| マイグレーション | {マイグレーションツール} | - |
| テスト | {テストフレームワーク} | {バージョン} |
| 品質管理 | {品質管理ツール} | - |
フロントエンド¶
| カテゴリ | 技術 | バージョン |
|---|---|---|
| 言語 | {言語} | {バージョン} |
| フレームワーク | {フレームワーク} | {バージョン} |
| CSS | {CSS フレームワーク} | {バージョン} |
インフラストラクチャ¶
| カテゴリ | 技術 |
|---|---|
| コンテナ | Docker / Docker Compose |
| CI/CD | {CI/CD ツール} |
5. プロファイル構成¶
開発効率を高めるため、複数のプロファイルを使い分けます。
| プロファイル | データベース | Docker | 用途 |
|---|---|---|---|
| default | {開発用 DB}（インメモリ等） | 不要 | 日常開発・即座起動 |
| product | {本番用 DB} | 必要 | 本番互換テスト |
default プロファイル（推奨：日常開発）¶
Docker なしで即座に起動できます。
cd {バックエンドディレクトリ}
{起動コマンド}
product プロファイル（本番互換）¶
# データベースコンテナを起動
cd {サブシステムディレクトリ}
docker compose up -d {DB サービス名}
# product プロファイルで起動
cd {バックエンドディレクトリ}
{product 起動コマンド}
6. 開発サーバーの起動¶
タスクランナー経由（推奨）¶
# 開発サーバー起動（default プロファイル）
{タスクランナーコマンド}
# TDD モード（テスト自動再実行）
{TDD コマンド}
# タスク一覧を表示
{ヘルプコマンド}
ビルドツール直接実行¶
cd {バックエンドディレクトリ}
# default プロファイルで起動
{起動コマンド}
# TDD モード（テストを常に再実行）
{TDD コマンド}
アクセス確認¶
| サービス | URL | 説明 |
|---|---|---|
| アプリケーション | http://localhost:{ポート} | メインアプリケーション |
| API ドキュメント | http://localhost:{ポート}/{パス} | API ドキュメント |
| DB 管理ツール | http://localhost:{ポート}/{パス} | データベース管理（default プロファイル） |
| ヘルスチェック | http://localhost:{ポート}/{パス} | ヘルスチェック |
7. Docker Compose のセットアップ¶
データベースコンテナの起動¶
cd {サブシステムディレクトリ}
# データベースを起動
docker compose up -d {DB サービス名}
# コンテナの状態確認
docker compose ps
Docker Compose の便利なコマンド¶
# データベースを起動
docker compose up -d {DB サービス名}
# コンテナの停止と削除
docker compose down
# ログを確認
docker compose logs -f {DB サービス名}
# データベースに接続
docker compose exec {DB サービス名} {DB クライアントコマンド}
8. テストの実行¶
全テスト実行¶
cd {バックエンドディレクトリ}
# テスト実行（カバレッジレポート付き）
{テスト実行コマンド}
テストの種類¶
| テスト種別 | ツール | 説明 |
|---|---|---|
| 単体テスト | {テストフレームワーク} | ドメインロジックのテスト |
| 統合テスト | {統合テストツール} | データベースを使用したテスト |
| アーキテクチャテスト | {アーキテクチャテストツール} | レイヤー依存関係検証 |
テストカバレッジ¶
# テストを実行してカバレッジレポートを生成
{カバレッジコマンド}
# レポートの表示
# {レポートパス}
9. コード品質管理¶
静的コード解析ツール¶
| ツール | 目的 | コマンド |
|---|---|---|
| {リンター} | コーディング規約の検証 | {コマンド} |
| {バグ検出ツール} | バグパターン検出 | {コマンド} |
| {カバレッジツール} | テストカバレッジ | {コマンド} |
品質チェックの実行¶
cd {バックエンドディレクトリ}
# 品質チェックのみ
{品質チェックコマンド}
# すべてのテストと品質チェック
{フルチェックコマンド}
コード複雑度の基準¶
| 指標 | 閾値 | 説明 |
|---|---|---|
| 循環的複雑度 | 10 | 分岐・ループの複雑さ |
| ファイルサイズ | 500 行 | 1 ファイルの最大行数 |
| メソッドサイズ | 150 行 | 1 メソッドの最大行数 |
| パラメータ数 | 7 | メソッドの最大パラメータ数 |
レポートの確認¶
品質チェック後、以下のディレクトリにレポートが生成されます。
| ツール | レポートパス |
|---|---|
| {リンター} | {レポートパス} |
| {バグ検出ツール} | {レポートパス} |
| {カバレッジツール} | {レポートパス} |
| テスト結果 | {レポートパス} |
10. ディレクトリ構造¶
{プロジェクト名}/
├── .husky/ # Git Hooks (Husky)
│ └── pre-commit # コミット前品質チェック
├── apps/
│ └── {サブシステム}/
│ ├── backend/
│ │ ├── {ビルド設定ファイル}
│ │ ├── Dockerfile
│ │ ├── config/ # 品質管理ツール設定
│ │ └── src/
│ │ ├── main/
│ │ │ ├── {ソースディレクトリ}/
│ │ │ │ ├── domain/ # ドメイン層
│ │ │ │ ├── application/ # アプリケーション層
│ │ │ │ └── infrastructure/ # インフラストラクチャ層
│ │ │ └── resources/
│ │ │ ├── {設定ファイル}
│ │ │ └── db/migration/ # マイグレーション
│ │ └── test/
│ └── docker-compose.yml
├── docs/ # ドキュメント
├── ops/ # 運用スクリプト
└── package.json # Node.js 依存関係（husky, lint-staged）
11. 命名規則¶
プロジェクトの命名規則を定義します。
| 要素 | 規則 | 例 |
|---|---|---|
| テーブル名 | {規則} | {例} |
| カラム名 | {規則} | {例} |
| クラス名 | {規則} | {例} |
| フィールド名 | {規則} | {例} |
12. Git 規約¶
コミットメッセージ¶
Conventional Commits に従います。
| タイプ | 説明 |
|---|---|
feat |
新機能 |
fix |
バグ修正 |
docs |
ドキュメントのみの変更 |
style |
コードの意味に影響しない変更 |
refactor |
バグ修正でも機能追加でもないコード変更 |
perf |
パフォーマンス改善 |
test |
テストの追加・修正 |
chore |
ビルドプロセス・補助ツールの変更 |
スコープ¶
サブシステムを示すスコープを使用します。
feat({スコープ}): {変更内容}
fix({スコープ}): {変更内容}
docs: {変更内容}
Git Hooks（Husky + lint-staged）¶
コミット時に自動で品質チェックが実行されます。
セットアップ¶
npm install 実行時に Husky は自動的にセットアップされます（prepare スクリプト）。
# 手動でセットアップする場合
npx husky init
pre-commit フック¶
ソースファイルに変更がある場合、以下のチェックが自動実行されます。
| ツール | 目的 |
|---|---|
| {リンター} | コーディング規約の検証 |
| {バグ検出ツール} | バグパターン検出 |
いずれかのチェックが失敗すると、コミットがブロックされます。
フックをスキップする場合¶
緊急時にフックをスキップしてコミットする場合（非推奨）：
git commit --no-verify -m "メッセージ"
Warning: フックのスキップは緊急時のみ使用してください。品質チェックを通過しないコードはチームに影響を与える可能性があります。
13. セットアップの確認¶
すべてのセットアップが完了したら、以下のコマンドで動作確認を行います。
# 1. Node.js 依存パッケージのインストール
npm install
# 2. ビルド確認
cd {バックエンドディレクトリ}
{ビルドコマンド}
# 3. テスト実行
{テスト実行コマンド}
# 4. 品質チェック
{品質チェックコマンド}
# 5. 開発サーバー起動（default プロファイル）
{起動コマンド}
アクセス確認¶
| サービス | URL | 説明 |
|---|---|---|
| アプリケーション | http://localhost:{ポート} | メインアプリケーション |
| API ドキュメント | http://localhost:{ポート}/{パス} | API ドキュメント |
| DB 管理ツール | http://localhost:{ポート}/{パス} | データベース管理ツール |
| ヘルスチェック | http://localhost:{ポート}/{パス} | ヘルスチェック |
14. CI/CD¶
CI/CD による継続的インテグレーション・デプロイを設定しています。
ワークフロー一覧¶
| ワークフロー | ファイル | トリガー | 説明 |
|---|---|---|---|
| Backend CI | {ワークフローファイル} |
{トリガーパス} 変更時 |
品質チェック・テスト・ビルド |
| Docker Publish | {ワークフローファイル} |
タグ push / 手動実行 | イメージを Registry に公開 |
| Docs Deploy | {ワークフローファイル} |
main ブランチ push | ドキュメントをデプロイ |
Backend CI¶
バックエンドの変更時に自動実行されます。
実行内容:
1. 環境セットアップ
2. キャッシュ復元
3. 品質チェック（リンター、バグ検出）
4. テスト実行（単体・統合・アーキテクチャ）
5. カバレッジレポート生成
6. ビルド（成果物生成）
7. レポートアップロード
Docker Image Publish¶
タグ push 時または手動実行時に、Docker イメージをビルドして Registry に公開します。
# 手動実行
{手動実行コマンド}
# タグによる自動実行
git tag v1.0.0
git push origin v1.0.0
# イメージの取得
docker pull {レジストリ}/{イメージ名}:latest
トラブルシューティング¶
{問題タイトル 1}¶
問題: {問題の説明}
{エラーメッセージ}
解決策: {解決策の説明}
{解決コマンド}
{問題タイトル 2}¶
問題: {問題の説明}
解決策: {解決策の説明}
{解決コマンド}
pre-commit フックが失敗する場合¶
cd {バックエンドディレクトリ}
# 品質チェックを手動実行してエラーを確認
{品質チェックコマンド}
# エラーを修正してから再度コミット
関連ドキュメント¶
- {関連ドキュメント 1}
- {関連ドキュメント 2}
- {関連ドキュメント 3}