@aramassa/ai-rules 0.1.1-npmjs.20250910072942

package/artifact/instructions/python/workspace-management.md

@@ -0,0 +1,673 @@
+---
+type: workspace-management
+language: python
+category: best-practices
+focus: uv-workspace
+applyTo: "**/pyproject.toml"
+human-instruction: |-
+  ## UV Workspace Management は Python モノレポの標準的な管理手法です
+
+  このドキュメントは PR #2 で実装された成功パターンを標準化したものです。
+  UV workspace を使用することで、高速なパッケージ管理と開発モードでの効率的な開発が可能になります。
+  common/core の依存関係ルールを守ることで、循環依存を避けた健全なアーキテクチャを維持できます。
+---
+
+# UV Workspace Management Rules - Python プロジェクト管理ベストプラクティス
+
+## 概要
+
+このドキュメントは、UV workspace を使用した Python プロジェクトの標準的な管理手法を定義します。モジュラー構造、パッケージ間依存関係の設計原則、開発環境の自動化、品質チェックワークフローの統合を通じて、保守性と開発効率の高いプロジェクト運営を実現します。
+
+## 1. UV Workspace Configuration - ワークスペース設定
+
+### ワークスペース構成の原則
+
+#### 必須パッケージ構造
+
+| パッケージ名 | 役割 | 依存関係ルール |
+|:------------|:-----|:---------------|
+| `common` | 全パッケージで共通利用される機能（設定管理、ユーティリティ、Pydantic モデル等） | 他のワークスペースパッケージに依存しない |
+| `core` | プロジェクトの主要機能を提供する中核パッケージ | `common` にのみ依存可能 |
+
+#### パッケージ間依存関係の設計原則
+
+- **循環依存の禁止**: どのパッケージ間でも循環依存は厳格に禁止
+- **階層的依存**: `common` ← その他のパッケージ ← `core` の階層構造を維持
+- **その他のパッケージ**: `core` への依存は禁止、`common` への依存は許可
+
+### ルート pyproject.toml の標準設定
+
+```toml
+[project]
+name = "your-project-name"
+version = "0.1.0"
+requires-python = ">=3.11"
+description = "Project description"
+authors = [
+    {name = "Your Name", email = "your.email@example.com"},
+]
+
+[tool.uv.workspace]
+members = [
+    "packages/*",
+]
+
+[tool.uv.sources]
+your-project-common = { workspace = true }
+your-project-core = { workspace = true }
+your-project-cli = { workspace = true }
+your-project-ingest = { workspace = true }
+your-project-evaluation = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "pre-commit>=3.0.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+select = ["E", "F", "W", "C90", "I", "N", "D", "UP", "S", "B", "A", "COM", "C4", "DTZ", "T10", "EM", "EXE", "FA", "ISC", "ICN", "G", "INP", "PIE", "T20", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SLOT", "SIM", "TID", "TCH", "INT", "ARG", "PTH", "TD", "FIX", "ERA", "PD", "PGH", "PL", "TRY", "FLY", "NPY", "AIR", "PERF", "FURB", "LOG", "RUF"]
+
+[tool.ruff.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+testpaths = ["packages/*/tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "--strict-markers --strict-config --cov --cov-report=term-missing"
+```
+
+### パッケージ pyproject.toml の標準例
+
+#### packages/common/pyproject.toml
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "your-project-common"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+    "typer>=0.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/your_project_common"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+]
+```
+
+#### packages/core/pyproject.toml
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "your-project-core"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "your-project-common",
+    "langchain>=0.1.0",
+    "numpy>=1.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/your_project_core"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+]
+```
+
+## 2. Development Environment Setup - 開発環境構築
+
+### setup-dev.sh の標準実装
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🚀 Setting up development environment..."
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "📦 Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    source $HOME/.cargo/env
+    
+    # Verify installation
+    if ! command -v uv &> /dev/null; then
+        echo "❌ Failed to install uv. Please install manually."
+        exit 1
+    fi
+    echo "✅ uv installed successfully"
+fi
+
+# Install project dependencies
+echo "📦 Installing dependencies..."
+uv sync --dev
+
+# Install pre-commit hooks
+echo "🔧 Setting up pre-commit hooks..."
+if command -v pre-commit &> /dev/null || uv run pre-commit --version &> /dev/null; then
+    uv run pre-commit install
+    echo "✅ Pre-commit hooks installed"
+else
+    echo "⚠️  pre-commit not found, skipping hook installation"
+fi
+
+# Verify workspace setup
+echo "🔍 Verifying workspace setup..."
+uv run python -c "import sys; print(f'Python: {sys.version}')"
+
+echo "✅ Development environment setup complete!"
+echo "📝 Next steps:"
+echo "   - Run 'uv run pytest' to execute tests"
+echo "   - Run 'scripts/check-quality.sh' to run quality checks"
+echo "   - Run 'uv run mypy packages/' for type checking"
+```
+
+### 実行権限の設定
+
+```bash
+chmod +x scripts/setup-dev.sh
+```
+
+## 3. Quality Assurance Workflow - 品質保証ワークフロー
+
+### check-quality.sh の標準実装
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🔍 Running quality checks..."
+
+# Set up error tracking
+ERRORS=0
+
+# Function to handle errors
+handle_error() {
+    ERRORS=$((ERRORS + 1))
+    echo "❌ $1 failed"
+}
+
+# Run ruff (linting and formatting)
+echo "🧹 Running ruff linting..."
+if ! uv run ruff check packages/ scripts/; then
+    handle_error "Ruff linting"
+fi
+
+echo "🎨 Checking code formatting..."
+if ! uv run ruff format --check packages/ scripts/; then
+    handle_error "Code formatting"
+    echo "💡 Run 'uv run ruff format packages/ scripts/' to fix formatting issues"
+fi
+
+# Run mypy (type checking)
+echo "🔍 Running mypy type checking..."
+if ! uv run mypy packages/; then
+    handle_error "Type checking"
+fi
+
+# Run tests with coverage
+echo "🧪 Running tests with coverage..."
+if ! uv run pytest packages/ --cov --cov-report=term-missing --cov-fail-under=80; then
+    handle_error "Tests"
+fi
+
+# Check import sorting
+echo "📦 Checking import sorting..."
+if ! uv run ruff check --select I packages/; then
+    handle_error "Import sorting"
+fi
+
+# Summary
+echo ""
+if [ $ERRORS -eq 0 ]; then
+    echo "✅ All quality checks passed!"
+    exit 0
+else
+    echo "❌ $ERRORS quality check(s) failed"
+    exit 1
+fi
+```
+
+### 実行権限の設定
+
+```bash
+chmod +x scripts/check-quality.sh
+```
+
+## 4. Package Structure Guidelines - パッケージ構造ガイドライン
+
+### 標準パッケージ構造
+
+```text
+your-project/
+├── pyproject.toml                 # ワークスペース設定
+├── README.md
+├── .gitignore
+├── scripts/
+│   ├── setup-dev.sh              # 開発環境セットアップ
+│   ├── check-quality.sh          # 品質チェック
+│   ├── update-deps.sh            # 依存関係更新
+│   └── deploy.sh                 # デプロイスクリプト（必要に応じて）
+└── packages/
+    ├── common/
+    │   ├── src/
+    │   │   └── your_project_common/
+    │   │       ├── __init__.py
+    │   │       ├── config.py      # 設定管理
+    │   │       ├── models.py      # Pydantic モデル
+    │   │       ├── exceptions.py  # カスタム例外
+    │   │       └── utils.py       # 共通ユーティリティ
+    │   ├── tests/
+    │   │   ├── __init__.py
+    │   │   ├── test_config.py
+    │   │   ├── test_models.py
+    │   │   └── test_utils.py
+    │   ├── pyproject.toml
+    │   └── README.md
+    ├── core/
+    │   ├── src/
+    │   │   └── your_project_core/
+    │   │       ├── __init__.py
+    │   │       ├── processing.py  # データ処理ロジック
+    │   │       ├── retrieval.py   # 検索・取得ロジック
+    │   │       └── analysis.py    # 分析ロジック
+    │   ├── tests/
+    │   │   ├── __init__.py
+    │   │   ├── test_processing.py
+    │   │   └── test_retrieval.py
+    │   ├── pyproject.toml
+    │   └── README.md
+    ├── cli/
+    │   ├── src/
+    │   │   └── your_project_cli/
+    │   │       ├── __init__.py
+    │   │       ├── main.py        # CLI エントリポイント
+    │   │       └── commands/      # サブコマンド実装
+    │   ├── tests/
+    │   ├── pyproject.toml
+    │   └── README.md
+    └── ingest/
+        ├── src/
+        │   └── your_project_ingest/
+        │       ├── __init__.py
+        │       ├── loaders.py     # データローダー
+        │       └── processors.py # データ前処理
+        ├── tests/
+        ├── pyproject.toml
+        └── README.md
+```
+
+### パッケージ内ファイル構成の原則
+
+#### 1. src レイアウト採用
+
+- 各パッケージは `src/package_name/` 構造を採用
+- テストファイルは `tests/` ディレクトリに分離
+- パッケージルートに `pyproject.toml` と `README.md` を配置
+
+#### 2. 明確な責務分離
+
+- **common**: 設定、モデル、ユーティリティなど全体で使用される機能
+- **core**: ビジネスロジック、主要なアルゴリズム実装
+- **cli**: コマンドラインインターフェース
+- **ingest**: データ取得・前処理
+- **evaluation**: 評価・メトリクス計算
+
+## 5. Script Management Standards - スクリプト管理標準
+
+### scripts/ ディレクトリの構成原則
+
+```text
+scripts/
+├── setup-dev.sh       # 開発環境セットアップ
+├── check-quality.sh   # 品質チェック
+├── update-deps.sh     # 依存関係更新
+├── build.sh          # ビルドスクリプト
+├── test.sh           # テスト実行
+└── deploy.sh         # デプロイスクリプト（必要に応じて）
+```
+
+### update-deps.sh の実装例
+
+```bash
+#!/bin/bash
+set -e
+
+echo "📦 Updating dependencies..."
+
+# Update all workspace dependencies
+echo "🔄 Syncing workspace dependencies..."
+uv sync --upgrade
+
+# Check for outdated dependencies
+echo "🔍 Checking for outdated dependencies..."
+uv tree --outdated
+
+# Run tests to ensure compatibility
+echo "🧪 Running tests to verify compatibility..."
+uv run pytest packages/ -x
+
+echo "✅ Dependencies updated successfully!"
+echo "📝 Please review the changes and commit if everything looks good."
+```
+
+### build.sh の実装例
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🏗️ Building project..."
+
+# Run quality checks first
+echo "🔍 Running quality checks..."
+scripts/check-quality.sh
+
+# Build all packages
+echo "📦 Building packages..."
+uv build --all
+
+echo "✅ Build completed successfully!"
+```
+
+## 6. Template Files - テンプレートファイル
+
+### パッケージテンプレート: pyproject.toml
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "your-project-package-name"
+version = "0.1.0"
+requires-python = ">=3.11"
+description = "Package description"
+dependencies = [
+    "your-project-common",
+    # Add other dependencies here
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/your_project_package_name"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+```
+
+### パッケージテンプレート: __init__.py
+
+```python
+"""Your Project Package Name - Package initialization."""
+
+__version__ = "0.1.0"
+
+# Export main classes/functions here
+__all__ = [
+    # Add exports here
+]
+```
+
+### パッケージテンプレート: README.md
+
+```markdown
+# Your Project Package Name
+
+Brief description of the package functionality.
+
+## Installation
+
+This package is part of the your-project workspace. Install the development environment:
+
+```bash
+./scripts/setup-dev.sh
+```
+
+## Usage
+
+```python
+from your_project_package_name import SomeClass
+
+# Usage examples
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest packages/package-name/tests/
+```
+
+Run quality checks:
+
+```bash
+./scripts/check-quality.sh
+```
+
+## Dependencies
+
+- `your-project-common`: Common utilities and models
+- Other dependencies as needed
+```
+
+## 7. CI/CD Integration - 継続的インテグレーション
+
+### GitHub Actions ワークフロー例
+
+```yaml
+name: Quality Checks
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v1
+      with:
+        version: "latest"
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: uv sync --dev
+    
+    - name: Run quality checks
+      run: ./scripts/check-quality.sh
+    
+    - name: Upload coverage reports
+      uses: codecov/codecov-action@v3
+      if: matrix.python-version == '3.11'
+```
+
+## 8. Best Practices & Troubleshooting - ベストプラクティスとトラブルシューティング
+
+### 開発ワークフロー
+
+1. **新機能開発時**:
+   ```bash
+   # 1. 開発環境更新
+   uv sync --dev
+   
+   # 2. 品質チェック
+   ./scripts/check-quality.sh
+   
+   # 3. 実装
+   # ... コード変更 ...
+   
+   # 4. テスト実行
+   uv run pytest packages/target-package/tests/
+   
+   # 5. 最終品質チェック
+   ./scripts/check-quality.sh
+   ```
+
+2. **新パッケージ追加時**:
+   - テンプレートファイルを使用
+   - 依存関係ルールを確認
+   - ワークスペース設定を更新
+
+### よくある問題と解決策
+
+#### 1. 依存関係エラー
+
+```bash
+# 問題: パッケージが見つからない
+# 解決: ワークスペース同期
+uv sync --dev
+
+# 問題: 循環依存
+# 解決: 依存関係の再設計（common ← other ← core の順守）
+```
+
+#### 2. テストエラー
+
+```bash
+# 問題: インポートエラー
+# 解決: PYTHONPATH の確認とパッケージインストール
+uv run python -c "import your_project_common"
+
+# 問題: カバレッジ不足
+# 解決: テストケース追加
+uv run pytest --cov-report=html
+```
+
+#### 3. 型チェックエラー
+
+```bash
+# 問題: mypy エラー
+# 解決: 型アノテーション追加
+uv run mypy packages/target-package/ --show-error-codes
+```
+
+### パフォーマンス最適化
+
+1. **UV の高速性活用**:
+   - `uv sync` による高速依存関係解決
+   - `uv run` による仮想環境管理の自動化
+
+2. **テスト実行の最適化**:
+   - パッケージ単位でのテスト実行
+   - 並列テスト実行（`pytest -n auto`）
+
+3. **開発効率の向上**:
+   - pre-commit フックによる早期品質チェック
+   - エディタ統合（VS Code, PyCharm）
+
+## 9. Migration Guide - 既存プロジェクトの移行
+
+### Poetry/pip からの移行
+
+1. **依存関係の移行**:
+   ```bash
+   # poetry.lock から requirements.txt 生成
+   poetry export --output requirements.txt
+   
+   # UV での依存関係インストール
+   uv add $(cat requirements.txt | cut -d'=' -f1)
+   ```
+
+2. **設定ファイルの更新**:
+   - `pyproject.toml` の UV workspace 形式への変換
+   - スクリプトの `uv run` 形式への変更
+
+3. **CI/CD の更新**:
+   - GitHub Actions の UV 対応
+   - Docker イメージの UV 統合
+
+### 検証チェックリスト
+
+- [ ] 全パッケージがビルド可能
+- [ ] テストが正常実行
+- [ ] 依存関係が正しく解決
+- [ ] 品質チェックがパス
+- [ ] CI/CD パイプラインが動作
+
+このガイドラインに従うことで、保守性が高く、開発効率の良い Python プロジェクトを UV workspace で管理できます。