update README

README.md

@@ -1,176 +1,334 @@
-# Almondo-PoC-Template
+# 🚀 Almondo PoC Template
 
-PoC 用のテンプレートリポジトリです。
-本READMEは以下の構成で作成されています。
-1. セットアップ
-2. ディレクトリ構造
+このリポジトリは、PoCプロジェクトのための包括的なテンプレートです。本READMEでは、プロジェクトのセットアップから開発プロセス、ディレクトリ構造まで、詳細かつ分かりやすく説明します。
 
-## セットアップ
-------------------
-#### 前提
+## 📑 目次
 
-- docker のインストール
+- [🚀 Almondo PoC Template](#-almondo-poc-template)
+  - [📑 目次](#-目次)
+  - [🛠 セットアップ](#-セットアップ)
+      - [前提条件](#前提条件)
+      - [セットアップ手順](#セットアップ手順)
+    - [Dockerの基本操作](#dockerの基本操作)
+    - [パッケージの管理](#パッケージの管理)
+  - [🔄 開発の手順](#-開発の手順)
+    - [開発フロー](#開発フロー)
+  - [📂 ディレクトリ構造](#-ディレクトリ構造)
+    - [主要ディレクトリの説明](#主要ディレクトリの説明)
+      - [`work/`](#work)
+      - [`data/`](#data)
+    - [`work/` ディレクトリ](#work-ディレクトリ)
+      - [`example/`](#example)
+      - [`experiments/`](#experiments)
+      - [`src/`](#src)
+      - [`tests/`](#tests)
+    - [`data/` ディレクトリ](#data-ディレクトリ)
+      - [`models/`](#models)
+      - [`preprocessed/`](#preprocessed)
+      - [`raw/`](#raw)
+      - [`results/`](#results)
+    - [VSCode上での作業(Dev container)](#vscode上での作業dev-container)
+      - [前提条件](#前提条件-1)
+      - [🔧 セットアップ手順](#-セットアップ手順)
+        - [1️⃣ 拡張機能のインストール](#1️⃣-拡張機能のインストール)
+        - [2️⃣ プロジェクトを開く](#2️⃣-プロジェクトを開く)
+        - [3️⃣ Dev Containerの設定](#3️⃣-dev-containerの設定)
+        - [4️⃣ Dev Container内でプロジェクトを再オープン](#4️⃣-dev-container内でプロジェクトを再オープン)
+        - [5️⃣ 開発開始](#5️⃣-開発開始)
+
+
+## 🛠 セットアップ
+
+#### 前提条件
+
+- git,dockerのインストール
 
 #### セットアップ手順
-1. git cloneを行う
-* 本リポジトリの右上にあるCodeボタンからリポジトリのurlを取得
-```bash
-git clone [repositry url]
-```
-2. デフォルトブランチの確認
-* develop ブランチになっているかどうか
-```bash
-git branch 
-```
-* 以下のようにdevelopに印がついていたら問題ない
-```bash
-* develop
-  main
-```
-3. .env.dev を作成する
-* env.dev.templeteがあるので,それを複製して作成する
 
-4. コンテナを起動する
-* 初回のみbuildが実行される
-```bash
-docker-compose run development bash
-```
+1. **リポジトリのクローン**
+   ```bash
+   git clone [リポジトリのurl]
+   cd [ディレクトリ名]
+   ```
 
-5. poetry でパッケージをインストールする
-* 以下のコードにてdocker container上に必要なパッケージがインストールされる。
+2. **デフォルトブランチの確認**
+   ```bash
+   git branch
+   ```
+   > 💡 `develop`ブランチがアクティブであることを確認してください。
+   ```
+   * develop
+     main
+   ```
 
-```
-poetry install
-```
-#### dockerの基本操作
-起動中のコンテナの確認
-```
-docker ps
-```
-起動中のコンテナに入る
-```
-docker exec -it [container id] bash
-```
-起動中のコンテナを落とす
-```
-docker-compose down
-```
-#### パッケージの追加削除
-パッケージの追加
-* パッケージ名にバージョンを指定することで,バージョンのアップグレード及びダウングレードができます
-```
-poetry add [パッケージ名]
-```
-パッケージの削除
-```
-poetry remove [パッケージ名]
-```
+3. **環境設定ファイルの作成**
+   ```bash
+   cp .env.dev.template .env.dev
+   ```
+   > ⚠️ `.env.dev`ファイルを編集し、必要な環境変数を設定してください。
 
-#### VScode上での作業
+4. **Dockerコンテナの起動**
+   ```bash
+   docker-compose run development bash
+   ```
+   > 🔔 初回実行時はイメージのビルドが行われるため、時間がかかる場合があります。
 
+5. **パッケージのインストール**
+   ```bash
+   poetry install
+   ```
+   > 📘 これにより、`pyproject.toml`に定義された全ての依存パッケージがインストールされます。
 
+### Dockerの基本操作
 
-## 開発の手順
-Issue driven開発手法での開発をしていただきます。
-詳細は以下ページに記載してあります
-- Issue driven運用のドキュメント
-https://www.notion.so/Issue-driven-5378336f66c243f7933b52a15ce15ee7?p=9b275fa3a5e841eea11133f900a80499&pm=s
+| コマンド | 説明 |
+|---------|------|
+| `docker ps` | 実行中のコンテナ一覧を表示 |
+| `docker exec -it [container_id] bash` | 実行中のコンテナに接続 |
+| `docker-compose down` | コンテナを停止し削除 |
 
-Issue　driven開発の大まかな手順は以下の8つです．
+### パッケージの管理
 
-1. **Issueを作成**
-  - 本ページの画面上部にあるIssuesから作成してください
-2. **ブランチを切る**
-   - brach名は以下の2つの規則に従ってください
-    - feature/~~~~~
-        - 新規機能の追加などの際に使用するブランチ
-    - fix/~~~~~
-        - 様々な改修や、バグ修正を行うブランチ
-3. **2で切ったブランチで作業**
-```
-   git fetch origin
-git checkout branch名
-```
+Poetryを使用してパッケージを管理します。
 
-1. **作業内容をpush**
-   変更内容をaddする前に，必ず以下のコマンドを実行し，最新のmainブランチの内容を反映させてください．
+- **パッケージの追加**:
+  ```bash
+  poetry add [パッケージ名]
+  ```
+  特定のバージョンを指定する場合:
+  ```bash
+  poetry add [パッケージ名]=[バージョン]
+  ```
 
-※最新のmainの内容が反映されていない場合，プルリクエストをマージする際にコンフリクトが発生する可能性があります．
-基本的なpushまでの流れ
+- **パッケージの削除**:
+  ```bash
+  poetry remove [パッケージ名]
+  ```
 
-addをします
-```bash
-git add file名
-```
-commitをします
+> 📝 パッケージの追加や削除を行った後は、必ず変更をコミットしてください。
 
-```bash
-git commit -m "commit message"
-```
+## 🔄 開発の手順
 
-最後に以下のコマンドでpushをします．
+本プロジェクトでは、効率的かつ体系的な開発を行うため、Issue driven開発手法を採用しています。
 
-```bash
-git push
-```
-1. **プルリクエストの作成**
-   本画面の上部に「Compare & pull request」と表示されるのでそれをクリックしてプルリクエストを作成してください
-2. **プルリクエストをレビュー(レビュワーが担当)**
-   作成されたPRからPjMがレビューを行います
-3. **mainブランチにマージをして，作業ブランチを削除する**
-　 レビュー内容を確認し問題がなければ,developブランチにマージをして作業ブランチを削除してください
+> 📚 詳細は[Issue driven運用のドキュメント](https://www.notion.so/Issue-driven-5378336f66c243f7933b52a15ce15ee7?p=9b275fa3a5e841eea11133f900a80499&pm=s)をご参照ください。
+
+### 開発フロー
+
+1. **Issueの作成** 
+   - リポジトリの「Issues」タブから新規Issueを作成
+   - タスクの詳細、目的、期待される結果を明確に記述
+
+2. **ブランチの作成** 
+   作成したIssueからGUI上でbranchを作成してください
+   - 命名規則:
+     - 新機能追加: `feature/[機能名]`
+     - バグ修正/改善: `fix/[修正内容]`
+
+3. **開発作業** 
+   GUI上で作成したbranchをローカルにfetchします
+   ```bash
+   git fetch origin
+   git checkout [branch名]
+   ```
+   - コードの実装
+   - ユニットテストの作成・実行
+
+4. **変更内容のコミットとプッシュ** 
+   ```bash
+   git add .
+   git commit -m "commit message"
+   git push origin [branch名]
+   ```
+
+5. **プルリクエスト(PR)の作成** 
+   - GitHub上で「Compare & pull request」ボタンをクリック
+   - PRの説明を記入する
+
+6. **コードレビュー** 
+   - PjMがコードをチェック
+   - フィードバックがある場合は修正を行い、再度プッシュ
+
+7. **マージと後処理** 
+   - レビュー承認後、GUI上で`develop`ブランチにマージ
+   - GUI上で作業ブランチの削除
 
+> 💡 **Tip**: 常に`develop`ブランチの最新状態を維持するよう心がけましょう。作業開始前に以下のコマンドを実行することをおすすめします：
+> ```bash
+> git checkout develop
+> git pull origin develop
+> git switch [branch名]
+> git merge —no-ff develop
+> ```
+
+## 📂 ディレクトリ構造
 
-## ディレクトリ構造
-------------------
-主なディレクトリ構造
 ```
 root/
 ├── .github/
-│   └── workflows/        # CI/CDワークフロー定義
-│       └── pysen-python-app.yaml         # データモデル
-├── data/                 # プロジェクトドキュメント
-│   ├── models/           # データモデル
-│   ├── preprocessed/         # ビジネスロジック
-│   └── raw/            # ユーティリティ関数
-│   └── results/  
-├── work/                  # ソースコード        
-│   ├── example/           # データモデル
-│   ├── experiments/         # ビジネスロジック
-│   └── src/            # ユーティリティ���数
-│   └── tests/            # ユーティリティ関数
-├── .env.dev.template     # 開発環境変数テンプレート
-├── .gitignore            # Gitが無視するファイル設定
-├── Dockerfile            # Dockerイメージ定義
-├── README.md             # プロジェクト説明（本ファイル）
-├── docker-compose.yml    # Docker Compose設定
-├── entrypoint.sh    # Docker Compose設定
-├── poetry.lock        # Poetryプロジェクト設定
-├── pyproject.toml        # Poetryプロジェクト設定
-└── LICENSE               # ライセンス情報
+│   └── workflows/           # CI/CDワークフロー定義
+│       └── pysen-python-app.yaml
+├── data/                    # データ関連ファイル (Gitで管理されません)
+│   ├── models/              # 学習済みモデル (.pth等)
+│   ├── preprocessed/        # 前処理済みデータ (CSV等)
+│   ├── raw/                 # 生データ (提供されたExcel等)
+│   └── results/             # 解析結果
+├── work/                    # プロジェクトのメインコード
+│   ├── example/             # デモやサンプルコード
+│   ├── experiments/         # 実験用コード
+│   ├── src/                 # 共通ライブラリやユーティリティ
+│   └── tests/               # テストコード
+├── .env.dev.template        # 開発環境変数テンプレート
+├── .gitignore               # Git除外設定
+├── Dockerfile               # Dockerイメージ定義
+├── README.md                # プロジェクト説明 (本ファイル)
+├── docker-compose.yml       # Docker Compose設定
+├── entrypoint.sh            # Dockerエントリーポイントスクリプト
+├── poetry.lock              # 依存関係ロックファイル
+├── pyproject.toml           # Poetryプロジェクト設定
+└── LICENSE                  # ライセンス情報
 ```
-### work
-#### exmaple
-- 先方にコードの実行例を見せるときやデモ等の共有の際に必要な綺麗なコードをまとめる場所
-- spacesのデモ等
-#### experiments
-- 実行コード置き場
-- 基本的な実験的なコードはここに置く
-- 種々の実験はここで行う
-- promptのようなプロジェクトに依存するものはこちら
-#### src
-- プロジェクトごとに使いまわせるようなやつプロジェクトに依存しない基本クラス
-- クラス化されたsrc code 置き場
-- 各コードに共通する基本クラスはここ
-#### tests
-* 単体テストを置くフォルダ
-### dataフォルダ
-githubには上がらないようになっていますが以下の構成で分けてください
-#### model
-（モデル保存場所、tuningしたpthファイルなど）
-#### preprocessed
-（前処理済みデータ,csvやtextファイルなど）
-#### raw
-生データ保管場所（先方から提供されたexcelファイルなど）
-#### results
-（結果保存場所、各タスクごとの出力結果保存）
+
+### 主要ディレクトリの説明
+
+#### `work/`
+- **example/**: クリーンなデモ用コード、Spaces用スクリプトなど
+- **experiments/**: 実験的コードや一時的なスクリプト
+- **src/**: プロジェクト共通の基本クラスやユーティリティ
+- **tests/**: 単体テストコード
+
+#### `data/`
+- **models/**: 学習済みモデル（.pthファイルなど）
+- **preprocessed/**: 前処理済みデータ（CSVやテキストファイル）
+- **raw/**: 元データ（提供されたExcelファイルなど）
+- **results/**: 各タスクの出力結果
+
+
+
+### `work/` ディレクトリ
+
+`work/` ディレクトリは、プロジェクトの主要なコードベースを含みます。各サブディレクトリの詳細は以下の通りです：
+
+#### `example/`
+- **目的**: デモンストレーションやサンプルコードの保管
+- **内容**:
+  - クリーンで理解しやすいコード例
+  - Hugging Face Spacesのデモスクリプト
+  - クライアントへの提示用コードサンプル
+
+#### `experiments/`
+- **目的**: 実験的なコードや一時的なスクリプトの保管
+- **内容**:
+  - 新しいアルゴリズムの試験実装
+  - パラメータチューニングスクリプト
+  - プロジェクト固有のプロンプトやコンフィグ
+
+#### `src/`
+- **目的**: 再利用可能な共通コンポーネントの保管
+- **内容**:
+  - プロジェクト間で共有できる基本クラス
+  - ユーティリティ関数
+  - データ処理パイプライン
+
+#### `tests/`
+- **目的**: 単体テストとその関連ファイルの保管
+- **内容**:
+  - 各モジュールの単体テスト
+
+### `data/` ディレクトリ
+
+`data/` ディレクトリは、プロジェクトで使用する様々なデータ��保管します。
+#### `models/`
+- **目的**: 学習済みモデルの保存
+- **内容**:
+  - PyTorchモデル（.pthファイル）
+  - TensorFlowモデル（.h5ファイル）
+  - その他の機械学習モデル
+
+#### `preprocessed/`
+- **目的**: 前処理済みデータの保存
+- **内容**:
+  - クリーニング済みCSVファイル
+  - トークン化されたテキストファイル
+  - 正規化された数値データ
+
+#### `raw/`
+- **目的**: 元データの保管
+- **内容**:
+  - クライアントから提供された元のExcelファイル
+  - ウェブスクレイピングで取得した生データ
+  - 未処理のログファイル
+
+#### `results/`
+- **目的**: 分析結果や出力データの保存
+- **内容**:
+  - モデルの予測結果
+  - 統計分析のレポート
+  - 生成されたグラフや図表
+
+> ⚠️ 注意: `data/`ディレクトリの内容はGitで管理されません。重要なデータは別途バックアップを取ってください。
+
+
+### VSCode上での作業(Dev container)
+vscode上でdocker環境で作業する方法に[Dev container]という拡張機能があるのでご紹介します
+
+#### 前提条件
+
+以下のツールがインストールされていることを確認してください：
+
+- ✅ [Visual Studio Code](https://code.visualstudio.com/)
+- ✅ [Docker Desktop](https://www.docker.com/products/docker-desktop) (起動済みであること)
+
+#### 🔧 セットアップ手順
+
+##### 1️⃣ 拡張機能のインストール
+
+<details>
+<summary>詳細手順を表示</summary>
+
+1. VSCodeを開く
+2. 左サイドバーの拡張機能アイコン（🧩）をクリック（または `Ctrl+Shift+X` / `Cmd+Shift+X`）
+3. 検索バーに "Remote Development" と入力
+4. 表示された拡張機能をインストール
+
+</details>
+
+##### 2️⃣ プロジェクトを開く
+
+<details>
+<summary>詳細手順を表示</summary>
+
+1. VSCodeで開発したいプロジェクトのフォルダを開く（`File > Open Folder`）
+
+</details>
+
+##### 3️⃣ Dev Containerの設定
+
+<details>
+<summary>詳細手順を表示</summary>
+
+1. コマンドパレットを開く（`Ctrl+Shift+P` または `Cmd+Shift+P`）
+2. "Dev containers:Add Dev Containers Configuration Files..." と入力し選択
+3. プロジェクトに適したテンプレートを選択（例：Python, Node.js など）
+
+</details>
+
+##### 4️⃣ Dev Container内でプロジェクトを再オープン
+
+<details>
+<summary>詳細手順を表示</summary>
+
+1. コマンドパレットを再度開く
+2. "Dev-Containers: Reopen in Container" を選択
+3. VSCodeがコンテナをビルドし、プロジェクトを開くのを待つ
+
+</details>
+
+##### 5️⃣ 開発開始
+
+- 🎉 コンテナ内でVSCodeが起動したら、開発を開始できます
+- 💻 ターミナルも自動的にコンテナ内で動作します
+
+
+🔗 詳細情報は[公式VSCode Dev Containersドキュメント](https://code.visualstudio.com/docs/remote/containers)をご覧ください。
+