CLAUDE.md
同樣寫在前面
經過數個月在各種 Python 專案開發中使用 Claude Code 的經驗，毫無意外的如果我們要讓 AI 助理產出高品質、符合產業標準的程式碼，關鍵在於提供一份詳盡的 CLAUDE.md。這份 CLAUDE.md 是我們團隊經過無數次迭代優化的成果（當然沒有完美這件事），目前已經大量應用在公司內部的各種 Python 專案開發上，從簡單的腳本工具到複雜的企業級應用都能穩定產出專業級程式碼。這份規範的核心目標是建立一個完全自主可控、結構清晰、品質可靠的 Python 開發生態系統。
核心目標
這套 CLAUDE.md 的目標是「開箱即用、專業可靠」的 Python 專案開發標準。我們的目標是讓『Claude Code』能夠產出符合業界最佳實務的程式碼，不需要額外的修正或重構。當 Claude 完成程式開發後，產出的就是可以直接部署到正式環境的最終版本。我們使用現代 Python 語法，確保與 Python 3.10+ 版本完全相容，絕對不允許產出需要大幅修改才能使用的程式碼。每個專案都必須具備完整的測試覆蓋率、詳細的文件說明、以及穩定的執行效能。
專案架構設計原則
在 CLAUDE.md 中我們指引 Claude Code 要遵循符合 Python 最佳實務的專案架構。我們明確指引 Claude 採用 src/ 目錄布局，將原始碼與測試、文件、設定檔完全分離。絕對不使用扁平化的檔案結構，一律使用分層架構設計。所有 Python 套件都必須使用適當的 __init__.py 檔案進行模組化管理，確保匯入路徑清晰明確。我們使用 pyproject.toml 作為現代 Python 專案的標準設定檔，完全摒棄過時的 setup.py 方式。每個專案都必須包含完整的相依性管理、版本控制、以及自動化測試機制。
虛擬環境隔離需求
我們希望所有 Python 專案都必須使用虛擬環境來完全隔離相依性套件，確保不同專案之間絕對不會發生套件衝突。這是不可妥協的關鍵需求，所有開發環境都必須在獨立的虛擬環境中執行。我們嚴格禁止在系統層級安裝專案相依性套件，避免版本衝突和環境污染問題。
每個專案都必須使用 .venv 目錄作為虛擬環境根目錄，使用更有效率的 poetry 或傳統的 venv 工具進行管理。所有相依性都必須明確記錄在 requirements.txt 和 requirements-dev.txt 中，使用版本鎖定確保環境一致性。我們要求在 README.md 中提供完整的環境設定指令，包含虛擬環境建立、啟動、套件安裝的詳細步驟。每個專案都必須包含環境檢查腳本，確保執行環境的正確性。
分層架構和責任分離
所有功能都必須按照明確的分層架構進行組織，確保程式結構清楚易懂。我們強制要求使用 Services、Models、Repositories、Controllers 的分層設計模式。所有業務邏輯都必須封裝在 Services 層，資料模型定義在 Models 層，資料存取邏輯隔離在 Repositories 層，外部介面處理集中在 Controllers 層。每一層都有明確的職責邊界，絕對不允許跨層直接存取或邏輯混雜。
我們要求所有類別都使用具有高度語意的方式命名，即使名稱較長也要確保語意清楚。每個方法都必須有明確的輸入參數型別提示和回傳值型別提示。所有複雜的業務邏輯都要有詳細的 docstring 說明，遵循 Google 或 NumPy 格式規範。這種設計模式讓開發者可以快速理解程式結構，也讓後續的維護和擴展變得容易。
日誌記錄和可觀測性
我們指引 Claude Code 必須實作完整的日誌記錄機制，涵蓋所有重要的執行過程。程式啟動、設定載入、外部服務連線、資料處理進度、錯誤處理、成功完成等所有關鍵節點都要有對應的日誌輸出。使用 emoji 圖示增加日誌的可讀性，🚀 表示啟動、📋 表示設定載入、✅ 表示成功、❌ 表示錯誤、⚠️ 表示警告。所有日誌都要包含時間戳記、模組名稱、執行等級等完整資訊。
日誌系統必須支援不同等級的輸出控制，DEBUG、INFO、WARNING、ERROR、CRITICAL 各有其適用場景。正式環境中只輸出重要訊息，開發環境中可以顯示詳細的除錯資訊。所有日誌檔案都要按日期進行輪轉，避免檔案過大影響系統效能。敏感資訊絕對不能記錄到日誌檔案中，確保資安合規性。
程式碼品質保證機制
我們設置多層次的程式碼品質檢查機制，確保產出的程式碼符合專業標準。使用 Black 進行程式碼格式化，確保所有程式碼都有一致的外觀風格。使用 isort 管理匯入語句的排序，使用 flake8 進行語法和風格檢查，使用 mypy 執行型別檢查。所有這些工具都要整合到 pre-commit hooks 中，在程式碼提交前自動執行檢查。
測試覆蓋率必須達到 85% 以上，使用 pytest 作為測試框架。每個功能都要有對應的單元測試、整合測試、端對端測試。所有測試都要能自動執行，不能依賴外部環境或手動操作。我們使用 tox 進行多版本測試，確保程式碼在不同 Python 版本下都能正常運作。持續整合流程會自動執行所有品質檢查和測試，只有通過所有檢查的程式碼才能合併到主分支。
命令列介面和使用者體驗
所有需要使用者互動的程式都必須提供清楚直觀的命令列介面。我們嚴格要求使用 –key=value 格式的參數，優先選擇 argparse 或 click 套件來處理命令列參數。每個參數都要有詳細的說明文件，提供預設值和使用範例。
命令列程式必須提供完整的執行回饋，包含進度顯示、狀態更新、錯誤提示等。所有錯誤訊息都要提供具體的解決建議，不能只是顯示技術性的錯誤代碼。使用者應該能夠透過 –help 參數獲得完整的使用說明。命令列介面要支援除錯模式，透過 –debug 參數可以顯示詳細的執行資訊。
資料庫操作和安全性
所有資料庫操作都必須透過 Repository 層執行，絕對不允許在其他層級直接撰寫 SQL 語句。我們使用 SQLAlchemy 或 asyncpg 進行資料庫連接，確保所有查詢都使用參數化綁定，完全防止 SQL 注入攻擊。資料庫欄位命名統一使用 snake_case 格式，所有資料表都必須包含 uuid、status、since、lastupdate 等標準欄位。
實作軟刪除機制，使用 status 欄位標記資料狀態，避免物理刪除造成的資料遺失。使用 Alembic 進行資料庫結構版本控制，所有資料庫變更都要透過遷移腳本執行。資料庫連線要使用連線池管理，避免連線洩漏問題。所有敏感資料都要進行適當的加密處理，符合資料保護法規要求。
錯誤處理和回復機制
我們透過 CLAUDE.md 指引 Claude Code 建立完善的錯誤處理機制，確保程式在遇到異常狀況時能優雅地處理。所有可能發生錯誤的地方都要有適當的 try-catch 區塊，錯誤訊息要清楚說明問題原因和可能的解決方案。使用自定義例外類別來分類不同類型的錯誤，讓錯誤處理更加精確。
重要的操作要提供重試機制，使用『指數退避算法』避免對外部服務造成過大壓力。所有錯誤都要記錄到日誌檔案中，包含完整的堆疊追蹤資訊。在分散式系統中要實作斷路器模式，防止故障擴散。提供健康檢查端點，讓監控系統能夠及時發現問題。
開發工具整合和自動化
CLAUDE.md 中明確要求整合現代化的開發工具鏈來提升開發效率和程式碼品質，使用 pre-commit hooks 在提交前自動執行格式化、語法檢查、測試等操作。設定 GitHub Actions 或 GitLab CI 進行持續整合，自動執行測試和部署流程。
使用 Makefile 提供常用指令的快捷方式，包含環境設定、測試執行、程式碼檢查等。整合 IDE 設定檔，確保團隊成員都使用一致的開發環境設定。提供 Docker 設定檔，讓專案能在容器化環境中執行。使用依賴性掃描工具檢查安全漏洞，定期更新套件版本。
文件撰寫和維護原則
每一次的程式修改都要 100% 避免破壞性變更，確保向後相容性。所有的 API 變更都要提供 migration guide，讓使用者能絲滑升級。確保寫的任何程式都是正式環境可用的，經過充分測試和驗證。
我們要求撰寫完整的技術文件，包含 API 說明、使用範例、疑難排解指南等。使用 Sphinx 或 MkDocs 建立文件網站，提供搜尋和版本控制功能。所有程式碼都要有適當的註解和 docstring，遵循 PEP 257 規範。維護 CHANGELOG.md 記錄版本變更，讓使用者了解每個版本的更新內容。
效能最佳化和監控
在程式執行效能上我們透過 CLAUDE.md 要求 Claude Code 使用最適當的演算法和資料結構。對於耗時操作要提供非同步處理機制，避免阻塞主執行緒。使用快取機制減少重複計算和外部服務呼叫。實作適當的分頁機制處理大量資料。
建立效能監控機制，追蹤關鍵指標如回應時間、記憶體使用量、錯誤率等。使用 profiling 工具找出效能瓶頸，針對性地進行最佳化。在高負載情況下要進行壓力測試，確保系統穩定性。提供效能調校指南，讓維運人員能根據實際情況調整參數。
透過這套 CLAUDE.md 的制定，我們團隊在跟 Claude Code 互動時普遍能生成足夠專業、穩定且可維護的 Python Code。開發者不需要擔心程式碼品質與 Coding Style 不一致的問題，大大降低了處理環境相容性的時間消耗，只需要專注於業務邏輯的實作。通過完整的測試覆蓋和品質保證機制，確保產出的程式碼能在正式環境中穩定運作。
透過良好的 CLAUDE.md 進行開發流程的規範化大幅提升了團隊的開發效率，也降低了後續維護的成本。
# Code Style
- This is a Python project, so all code should be written in Python.
- If I don't specify a Python framework, always use standard Python (no frameworks).
- If I don't specifically mention it, don't apply any Python frameworks.
- Claude must generate code compatible with Python 3.10 + Python 3.12.
- Claude must use Python requests or httpx for HTTP-related operations.
- **Claude must use `--boo=bar` format when handling command-line arguments, prioritizing argparse or click packages**
- **Claude must provide complete CLI log output during all execution processes, including but not limited to: execution
start, processing steps, error messages, warnings, success messages, execution end**
- **Claude must provide usage examples and documentation every time code is provided**, demonstrating how to actually
use the code
- **Always use highly semantic and descriptive class, function, and parameter names, even if they might be longer**
- **All test files must follow the pattern in the tests directory, with file names uniformly
named `test_skelton_module_comprehensive_executor.py`**
- **Claude must follow the pattern and architecture of `test_skelton_module_comprehensive_executor.py` when writing test
files and example code**
- **Claude must use specific module names instead of generic placeholders when generating tests and usage examples**
- **Claude must use specific module names for appropriate naming when writing all test files and example usage files**
- **Always generate example usage files in the tests folder that conform to
the `test_skelton_module_comprehensive_executor.py` pattern, named `usage_example.py`**
- **Prioritize chainable getter and setter patterns to configure all required and optional parameters and settings, all
setter methods must return self to support method chaining**
- **Claude must write README.md files to demonstrate "how to use" examples of modules**
- **Claude must create a centralized configuration management mechanism to configure all required and optional
configuration parameters, such as API keys, service names and other parameters, avoiding scattering across individual
classes**
- **Claude must use the following pattern for initial setup when writing tests and example usage files:**
```python
import os
import sys
from pathlib import Path
# Set project root directory
current_working_directory = Path.cwd()
project_root = current_working_directory
sys.path.insert(0, str(project_root))
```
- **Claude must use the following pattern when writing scripts that require command-line arguments:**
```python
import argparse
def setup_argument_parser():
parser = argparse.ArgumentParser(description='Module description')
parser.add_argument('--config', help='Configuration file path')
parser.add_argument('--debug', action='store_true', help='Enable debug mode')
return parser
if __name__ == "__main__":
parser = setup_argument_parser()
args = parser.parse_args()
# Usage: python script.py --config=settings.json --debug
```
- **Claude must implement complete CLI logging output mechanisms for all scripts and services:**
```python
import logging
import sys
from datetime import datetime
# Set up logging format
def setup_logging(debug_mode=False):
log_level = logging.DEBUG if debug_mode else logging.INFO
log_format = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
logging.basicConfig(
level=log_level,
format=log_format,
handlers=[
logging.StreamHandler(sys.stdout),
logging.FileHandler(f'logs/{datetime.now().strftime("%Y%m%d")}.log')
]
)
return logging.getLogger(__name__)
# Logging output examples
logger = setup_logging()
logger.info("🚀 Application startup initiated")
logger.info("📋 Loading configuration file...")
logger.warning("⚠️ Potential issue detected, but execution can continue")
logger.error("❌ Execution failed: detailed error message")
logger.info("✅ Operation completed successfully")
logger.info("🏁 Application execution finished")
```
- **All important execution steps must have corresponding log output, including:**
- 📋 Configuration loading and validation
- 🔗 External service connection status
- 📊 Data processing progress
- ⏱️ Performance statistics
- 🔍 Debug information (debug mode)
- ⚠️ Warning messages
- ❌ Error handling
- ✅ Success messages
- 📈 Execution result statistics
- **Module structure follows Python best practices and the following basic architecture, flexibly adjusted according to
actual needs:**
```
{module_name}/
├── README.md
├── pyproject.toml # Modern Python package configuration
├── requirements.txt # Dependency package list
├── requirements-dev.txt # Development environment dependencies
├── .env.example # Environment variables example
├── .gitignore # Git ignore file
├── .pre-commit-config.yaml # pre-commit configuration
├── mypy.ini # Type checking configuration
├── pytest.ini # Test configuration
├── Makefile # Common command shortcuts
├── logs/ # Log file directory
│ └── .gitkeep
├── venv/ # Virtual environment directory (.gitignore)
├── .venv/ # Alternative virtual environment directory (.gitignore)
├── src/ # Source code directory (package isolation)
│ └── {module_name}/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # CLI entry point (python -m {module_name})
│ ├── py.typed # Type marker file
│ ├── version.py # Version information
│ ├── exceptions.py # Custom exceptions
│ ├── constants.py # Constants definition
│ ├── config/ # Configuration management
│ │ ├── __init__.py
│ │ ├── settings.py # Main configuration class
│ │ ├── environment.py # Environment variable handling
│ │ └── logging_config.py # Logging configuration
│ ├── core/ # Core business logic
│ │ ├── __init__.py
│ │ ├── services/ # Business logic layer (required)
│ │ │ ├── __init__.py
│ │ │ ├── base_service.py # Base service class
│ │ │ └── {module_name}_service.py
│ │ ├── models/ # Data models (optional)
│ │ │ ├── __init__.py
│ │ │ ├── base_model.py # Base model class
│ │ │ ├── {module_name}_model.py
│ │ │ └── {module_name}_model_iterator.py
│ │ └── repositories/ # Data access layer (optional: formerly DAO)
│ │ ├── __init__.py
│ │ ├── base_repository.py
│ │ └── {module_name}_repository.py
│ ├── api/ # API layer (optional)
│ │ ├── __init__.py
│ │ ├── controllers/ # Controllers
│ │ │ ├── __init__.py
│ │ │ ├── base_controller.py
│ │ │ └── {module_name}_controller.py
│ │ ├── schemas/ # API structure definitions
│ │ │ ├── __init__.py
│ │ │ ├── requests.py # Request structures
│ │ │ └── responses.py # Response structures
│ │ └── middleware/ # Middleware
│ │ ├── __init__.py
│ │ └── auth_middleware.py
│ ├── cli/ # Command line interface (optional)
│ │ ├── __init__.py
│ │ ├── commands/ # CLI commands
│ │ │ ├── __init__.py
│ │ │ └── {module_name}_commands.py
│ │ └── utils/ # CLI utilities
│ │ ├── __init__.py
│ │ └── cli_helpers.py
│ └── utils/ # Common utilities
│ ├── __init__.py
│ ├── logger.py # Logging utilities
│ ├── validators.py # Validation utilities
│ ├── decorators.py # Decorators
│ └── helpers.py # Helper functions
├── tests/ # Test directory (separated from src)
│ ├── __init__.py
│ ├── conftest.py # pytest configuration
│ ├── fixtures/ # Test data
│ │ ├── __init__.py
│ │ └── sample_data.py
│ ├── unit/ # Unit tests
│ │ ├── __init__.py
│ │ ├── test_services/
│ │ │ ├── __init__.py
│ │ │ └── test_{module_name}_service.py
│ │ ├── test_models/
│ │ │ ├── __init__.py
│ │ │ └── test_{module_name}_model.py
│ │ └── test_repositories/
│ │ ├── __init__.py
│ │ └── test_{module_name}_repository.py
│ ├── integration/ # Integration tests
│ │ ├── __init__.py
│ │ └── test_{module_name}_integration.py
│ ├── e2e/ # End-to-end tests
│ │ ├── __init__.py
│ │ └── test_{module_name}_e2e.py
│ ├── comprehensive/ # Comprehensive tests (original pattern)
│ │ ├── __init__.py
│ │ ├── test_skelton_module_comprehensive_executor.py
│ │ └── usage_example.py
│ └── performance/ # Performance tests
│ ├── __init__.py
│ └── test_{module_name}_performance.py
├── docs/ # Documentation directory
│ ├── api.md # API documentation
│ ├── usage.md # Usage instructions
│ ├── development.md # Development guide
│ └── changelog.md # Change log
├── scripts/ # Scripts directory
│ ├── setup.py # Environment setup script
│ ├── deploy.py # Deployment script
│ └── data_migration.py # Data migration script
└── examples/ # Usage examples
├── basic_usage.py # Basic usage example
├── advanced_usage.py # Advanced usage example
└── cli_examples.py # CLI usage examples
```
- **Python package structure best practices**:
- Use `src/` directory layout to avoid import issues and test pollution
- All directories must include `__init__.py` files
- Use `pyproject.toml` as the modern Python project configuration file
- Separate test directory from source code to avoid including test code in packages
- Use Type Hints and configure mypy checking
- Set up pre-commit hooks to ensure code quality
- Create dedicated `logs/` directory for storing log files
- **Service layer is required**: All modules should at least include Service classes to handle business logic
- **RESTful API service specific rules**: If the requirement is to create services using RESTful APIs, only the Service
layer needs to be created, **Model, Model Iterator, Repository and Controller are not needed**
- **Layer responsibility division**:
- **Core/Services**: Core business logic (required)
- **Core/Models**: Data models and entities (optional)
- **Core/Repositories**: Data access abstraction layer, formerly DAO (optional)
- **API/Controllers**: HTTP request handling (optional)
- **API/Schemas**: API input/output structure definitions (optional)
- **CLI**: Command line interface (optional)
- **Utils**: Common utilities and helper functions
- **Module development reference template**: Use `@module_skelton/module_skelton/` as the development template for all
new modules
- Copy the entire `module_skelton` directory structure
- Replace all `skelton_module` in file names with actual module names
- Replace `SkeltonModule` in code with actual module names
- Replace database table name `skelton_module` with actual table names
- Ensure all import paths, class names, and file references are correctly updated
- **Python code quality requirements**:
- Use Black for code formatting
- Use isort for import sorting
- Use flake8 for syntax checking
- Use mypy for type checking
- Use pytest for testing
- Code coverage target 85% or above
- If I don't specify a CSS framework, always use native CSS.
- CSS must always prefix all classes and IDs with `deus-` to avoid conflicts with other styles.
- CSS should be written in a modular way for easy overriding and extension.
- CSS should be organized in an easily readable and maintainable way, with clear comments and structure.
- CSS should be written with well-structured namespacing to avoid conflicts with other styles.
- CSS should have responsive design, working properly on both desktop and mobile devices.
- If I don't specify HTML, always use standard HTML5.
- Ensure you use appropriate Python modules and class encapsulation to isolate code and avoid conflicts with global
scope.
- **Especially important: Every code modification must 100% avoid breaking changes and absolutely cannot break existing
functionality.**
- Ensure any code you write is production-ready and can run directly.
## Python Virtual Environment Best Practices
- **Claude must use virtual environments to isolate dependency packages when creating any Python project**
- **Virtual environment creation and management standards**:
```bash
# Use venv (built-in with Python 3.3+)
python -m venv venv
# Or use .venv directory (modern convention)
python -m venv .venv
# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Or
source .venv/bin/activate
# Windows:
venv\Scripts\activate
# Or
.venv\Scripts\activate
# Deactivate virtual environment
deactivate
```
- **Claude must include complete virtual environment setup instructions in README.md**:
```markdown
## Environment Setup
### 1. Create Virtual Environment
```bash
python -m venv .venv
```
### 2. Activate Virtual Environment
```bash
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
```
### 3. Install Dependencies
```bash
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt # Development environment
```
### 4. Verify Installation
```bash
python --version
pip list
```
```
- **Dependency management best practices**:
```bash
# Generate requirements.txt
pip freeze > requirements.txt
# Use pip-tools for version locking (recommended)
pip install pip-tools
pip-compile requirements.in
pip-compile requirements-dev.in
# Update dependencies
pip-compile --upgrade requirements.in
```
- **Virtual environment tool selection guide**:
- **venv**: Built-in Python, suitable for simple projects
- **virtualenv**: More features, supports more Python versions
- **pipenv**: Integrates pip and virtualenv, automatically manages Pipfile
- **poetry**: Modern package management, recommended for complex projects
- **conda**: Suitable for scientific computing and data analysis projects
- **Modern approach using Poetry (recommended)**:
```bash
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# Initialize project
poetry init
# Install dependencies
poetry install
# Activate virtual environment
poetry shell
# Run commands
poetry run python script.py
# Add packages
poetry add requests
poetry add --group dev pytest
```
- **Environment isolation checklist**:
```python
# Claude must include environment check script in every project
import sys
import os
from pathlib import Path
def check_virtual_environment():
"""Check if running in virtual environment"""
if hasattr(sys, 'real_prefix') or (
hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix
):
print("✅ Running in virtual environment")
print(f"Virtual environment path: {sys.prefix}")
return True
else:
print("❌ Not running in virtual environment")
print("Please activate virtual environment first: source .venv/bin/activate")
return False
def check_python_version():
"""Check Python version"""
version = sys.version_info
if version.major == 3 and version.minor >= 10:
print(f"✅ Python version meets requirements: {version.major}.{version.minor}.{version.micro}")
return True
else:
print(f"❌ Python version does not meet requirements: {version.major}.{version.minor}.{version.micro}")
print("Requires Python 3.10 or above")
return False
```
- **.gitignore virtual environment configuration**:
```gitignore
# Virtual environment directories
venv/
.venv/
env/
.env/
ENV/
# Poetry virtual environment
.venv/
poetry.lock # Decide whether to ignore based on project needs
# Pipenv
Pipfile.lock # Decide whether to ignore based on project needs
# Conda
.conda/
# Python compiled files
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
```
- **Makefile automated virtual environment management**:
```makefile
# Virtual environment related commands
.PHONY: venv install install-dev clean test lint format
venv:
python -m venv .venv
@echo "Virtual environment created. Please run: source .venv/bin/activate"
install: venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt
install-dev: install
.venv/bin/pip install -r requirements-dev.txt
test:
.venv/bin/python -m pytest
lint:
.venv/bin/flake8 src/ tests/
.venv/bin/mypy src/
format:
.venv/bin/black src/ tests/
.venv/bin/isort src/ tests/
clean:
rm -rf .venv/
rm -rf __pycache__/
rm -rf .pytest_cache/
rm -rf *.egg-info/
find . -type f -name "*.pyc" -delete
```
- **Environment variable management**:
```python
# Use python-dotenv for environment variable management
from dotenv import load_dotenv
import os
# Load .env file
load_dotenv()
# Get environment variables
DATABASE_URL = os.getenv('DATABASE_URL', 'sqlite:///default.db')
API_KEY = os.getenv('API_KEY')
DEBUG = os.getenv('DEBUG', 'False').lower() == 'true'
```
- **Multi-environment management strategy**:
```bash
# Development environment
.env.development
# Testing environment
.env.testing
# Production environment
.env.production
# Local overrides (don't commit to version control)
.env.local
```
## Logging Output Standards
- **Log level usage standards**:
- `DEBUG`: Detailed debugging information, only used during development
- `INFO`: General information messages, records normal execution flow
- `WARNING`: Warning messages, issues are not serious but need attention
- `ERROR`: Error messages, program encounters problems but can continue execution
- `CRITICAL`: Critical errors, program cannot continue execution
- **Log message format requirements**:
- Use emoji icons to enhance readability (🚀 ✅ ❌ ⚠️ 📋 etc.)
- Include timestamp, module name, level and detailed messages
- Error messages must include specific error reasons and possible solutions
- Success messages must include key information about execution results
- **File log management**:
- Log files named by date (YYYYMMDD.log)
- Implement log rotation to avoid oversized files
- Sensitive information must not be recorded in log files
## Database Operation Standards
- All database operations must be performed through the Repository layer (formerly DAO layer), direct SQL writing in
Controllers or Services is not allowed
- Use SQLAlchemy or asyncpg for database connections, ensure parameterized queries to prevent SQL injection
- All SQL queries must use parameter binding, string concatenation is prohibited
- Database field naming uses snake_case (e.g.: user_name, created_at)
- All data tables must include: uuid (primary key), status, since, lastupdate fields
- Soft deletion always uses status field, do not physically delete data
- Python class and function naming uses snake_case
- Constants use UPPER_SNAKE_CASE
- Class names use PascalCase
- Use Alembic for database migration management
## Type Hints and Documentation Standards
- All functions and methods must include complete type hints
- Use docstrings to document function functionality, parameters and return values
- Follow Google or NumPy style docstring formats
- Complex business logic requires detailed comment explanationsPRD.md
同樣寫在前面
在實務上，我們團隊是用 CLAUDE.md 來指引 Claude Code 做軟體開發環境的高階配置，在個別模組規範的定義上，我們則會另外寫一份結構完整、內容詳盡的產品需求文件（PRD.md）來引導。這份 PRD.md 是我們團隊迭代了多次的一個版本（同樣是遠非完美），用來指引 Claude Code 撰寫元件開發 PRD 的指引性樣板，涵蓋了從需求分析到部署上線的完整開發週期，一份好的 PRD 不只是開發團隊的指引手冊，更是專案成功的重要基石。這份範本已經大量應用在我們公司內部的 Python 元件開發上，現階段大都套用在小型元件開發上，至於大型企業級系統我們倒是還在持續實驗中，期待之後到一定實戰洗鍊後再來分享。
核心文件理念
這份 PRD 範本的目標是建立「全面涵蓋、結構清晰、可執行性強」的產品需求文件基礎，我們的目標是讓開發團隊能夠根據這份文件直接進行開發工作，不需要額外的需求澄清或規格補充。當產品經理完成 PRD 撰寫後，產出的就是開發團隊可以直接執行的完整需求藍圖。我們涵蓋從商業目標到技術實作的所有層面，確保每個專案參與者都能清楚理解自己的職責和目標。這份文件必須具備完整的功能規格、詳細的技術需求、以及明確的驗收標準。
專案概述和商業價值
這份 PRD template 強調商業價值和技術實作的平衡。我們明確指引產品經理必須先定義專案的核心價值主張、目標使用者群體、以及要解決的主要問題。避免許為了技術而技術，一律以解決實際商業問題為出發點。所有功能設計都必須有明確的商業理由和使用者需求支撐，確保開發資源投入在正確的方向上。我們要求詳細分析市場需求、競品狀況、商業價值等關鍵因素，為專案建立堅實的商業基礎。
專案背景分析必須包含市場痛點識別、競爭對手分析、預期商業效益等完整資訊。每個功能都要能追溯回具體的商業目標，避免功能膨脹或偏離核心價值的風險。我們透過 PRD.md 作為範本指引 Claude Code 在規劃 PRD 時強調數據驅動的決策過程，要求提供具體的市場研究資料、使用者回饋、競品分析等客觀依據來支撐產品決策。
功能需求架構設計
PRD.md 要求 Claude Code 設計所有功能需求時都必須按照明確的層次結構進行組織，確保需求文件清楚易懂。我們團隊強制要求 Claude Code 使用核心功能、進階功能、使用者介面的分層設計模式。每個功能都必須有詳細的子功能分解、具體的操作流程描述、明確的輸入輸出規格定義。不允許模糊不清或含糊其辭的需求描述，每個功能點都要有具體可測試的驗收標準。
我們也透過文件要求每個功能都使用結構化的描述方式，包含功能說明、使用情境、預期行為、效能要求等完整資訊。所有複雜的業務流程都要有詳細的流程圖或使用者旅程說明，讓開發團隊能夠準確理解需求意圖。這種結構化的需求描述方式讓開發估算、測試設計、專案排程都變得更加準確可靠。
技術架構和實作規範
我們嘗試透過 PRD.md 實作完整的技術需求規劃，涵蓋技術選型、架構設計、相依性管理等所有技術層面。技術堆疊選擇、資料庫設計、第三方服務整合、部署環境規劃等都要有明確的技術決策和理由說明。模組結構設計要遵循軟體工程最佳實務，採用分層架構、關注點分離、模組化設計等原則。
所有技術決策都要考慮可擴展性、可維護性、效能表現、安全性等非功能性需求。我們要求詳細說明設計模式的選擇理由、資料儲存方案的考量、系統架構的可擴展性設計。技術風險評估和緩解策略也是技術需求的重要組成部分，確保專案在技術實作過程中能夠預見和處理潜在問題。
介面設計和使用者體驗
我們建立完善的介面設計規範，確保產品具備優秀的使用者體驗。CLI Interface、網頁介面、API 介面等不同類型的介面都要有詳細的設計規格和互動流程說明。所有介面都要考慮易用性、一致性、可存取性等使用者體驗原則。
設定管理系統的設計要支援多環境配置、動態配置更新、配置驗證等功能。使用者介面的視覺化需求要明確定義資訊呈現方式、互動回饋機制、錯誤處理提示等細節。團隊在 PRD.md 中特別重視錯誤處理的使用者體驗，要求提供清楚的錯誤訊息、有用的解決建議、優雅的錯誤恢復機制。
錯誤處理和系統穩定性
所有可能的錯誤情況都必須有明確的處理策略和恢復機制。我們分類定義不同類型的錯誤：使用者輸入錯誤、系統內部錯誤、外部服務錯誤、網路連線問題等，每種錯誤都要有對應的偵測方法、處理策略、使用者通知機制。
重要操作要提供自動重試機制、資料備份機制、狀態恢復機制等容錯設計。我們要求 Claude Code 建立完整的監控和警報系統，及時發現和處理系統異常。錯誤分類和編碼系統讓問題追蹤和除錯變得更加高效。所有錯誤訊息都要提供使用者友善的說明和具體的解決步驟。
需要額外注意的是在錯誤編碼與分類系統上，我們會提供另外一份名為『ERROR_TAXONOMY.md』的文件來指引 Claude Code。
效能監控和最佳化策略
透過 PRD.md 團隊針對元件開發上設置多面向的效能監控機制，追蹤系統的各項關鍵指標。回應時間、吞吐量、資源使用率、錯誤率等效能指標都要有明確的監控方法和閾值設定。效能最佳化策略要考慮快取機制、資料庫最佳化、演算法改善、資源管理等多個層面。
長期效能趨勢分析幫助團隊預見潛在的效能問題，提前進行容量規劃和系統調校。我們要求建立自動化的效能測試流程，在開發過程中持續監控系統效能表現。效能報告要提供詳細的統計資訊、趨勢分析、瓶頸識別等內容，為系統最佳化提供數據支撐。
日誌管理和可觀測性
PRD.md 中我們指引 Claude Code 去建立完整的日誌管理體系，涵蓋不同等級的日誌記錄、結構化的日誌格式、自動化的日誌輪轉機制。主控台輸出和檔案記錄要使用統一的格式標準，確保日誌資訊的一致性和可讀性。敏感資訊保護機制防止重要資料洩漏到日誌檔案中。
日誌檔案的命名規則、保存期限、存取控制等管理制度確保日誌系統的可維護性和安全性。我們很重視日誌的結構化設計，讓自動化監控和分析工具能夠有效處理日誌資料。除錯資訊、效能統計、錯誤追蹤等不同類型的日誌要有適當的分類和標記。
設定檔管理和環境適配
所有系統設定都必須外部化，支援不同環境的配置管理。主要設定檔要使用結構化格式（JSON、YAML 等），提供清楚的設定項目分類和預設值定義。環境變數配置讓系統能夠在不同部署環境中靈活調整行為。
功能開關機制讓團隊能夠動態控制功能的啟用狀態，支援灰度發布和快速回滾。設定驗證機制確保配置資料的正確性和完整性。多環境配置管理讓開發、測試、正式環境能夠使用不同的配置參數，滿足不同階段的需求。
整合擴展和外掛系統
我們嘗試設計靈活的整合機制，支援與外部服務和工具的無縫整合。API 整合、資料交換、服務通訊等整合需求都要有詳細的技術規格和實作指引。外掛系統的設計要提供清楚的擴展介面定義和實作範例。
內建擴展功能提供常用的功能模組，讓使用者能夠快速啟用所需功能。第三方工具整合要考慮版本相容性、配置管理、錯誤處理等技術細節。PRD.md 中強調擴展機制的穩定性和安全性，確保第三方擴展不會影響系統核心功能的穩定運作。
測試策略和品質保證
完整的測試策略涵蓋單元測試、整合測試、效能測試、使用者驗收測試等多個層面。每種測試都要有明確的測試範圍、測試方法、驗收標準。測試覆蓋率要求確保程式碼品質和功能完整性。
自動化測試流程整合到 CI/CD 流水線中，確保每次程式碼變更都經過充分測試。測試環境管理讓不同類型的測試能夠在適當的環境中執行。我們指引 Claude Code 要重視使用者驗收測試，確保產品功能符合實際使用需求和使用者期望。
部署運維和版本管理
部署需求規範涵蓋不同部署環境的配置要求、自動化部署流程、版本管理策略。監控運維機制確保系統在正式環境中的穩定運作，包含監控指標設定、告警機制配置、事故處理流程。
版本發布流程要有完整的檢查清單和回滾機制，確保新版本發布的安全性和可控性。我們在 PRD.md 中詳細指引 Claude Code 建立標準化的運維流程，讓維運團隊能夠高效處理日常維護工作。容量規劃和效能調校指引幫助運維團隊根據實際負載情況最佳化系統配置。
安全合規和資料保護
全面的安全考量涵蓋資料加密、存取控制、安全稽核等多個層面。認證授權機制確保只有經過驗證的使用者能夠存取系統功能。資料備份和恢復策略保護重要資料的安全性和可用性。
法規合規要求讓產品能夠滿足相關行業標準和法律規範。隱私保護機制確保個人資料的合規處理。安全認證和稽核流程提供可追溯的安全操作記錄。我們用 PRD.md 指示 Claude Code 要特別重視資料安全和隱私保護，確保產品在資料處理過程中符合最新的資料保護法規要求。
專案時程和里程碑管理
詳細的專案時程規劃將整個開發過程分解為可管理的階段，每個階段都有明確的交付物和驗收條件。關鍵里程碑的設定讓專案進度追蹤變得更加清楚可控。我們要求每個開發階段都有具體的時間規劃和資源配置。
風險管理機制識別潛在的技術風險和專案風險，為每個風險制定相應的緩解策略。成功標準和驗收條件提供明確的專案完成判準，確保專案交付符合既定目標。專案時程要考慮依賴關係、資源約束、風險緩衝等實際因素，制定可執行的開發計畫。
雖然目前不知道這項標準 PRD 中會有的規範對 Claude Code 運作成效的影響，但為了維持文件的完整性，我們還是會象徵性的加上這一個章節。
PRD.md 範本的目標在於全面、準確、可執行的去指引 Clause Code 精準的完成指定的任務，就像 PRD 讓產品經理不需要擔心需求遺漏問題，開發團隊不需要花時間處理需求澄清，所有專案參與者都能專注於自己的核心工作，讓結構化的需求描述和完整的技術規劃來極小化生成式 AI 的 non-deterministic 輸出。這種標準化的需求文件了理論上能大幅提升了團隊的協作效率，進而降低了專案失敗的風險，總之這麼猴功的制定這份 PRD.md 就是希望透過層層的緊箍咒讓 Claude Code 在執行複雜的軟體專案過程變得可預測、可控制並極大化的對齊團隊既有的各項規範與 Coding Style。
# Product Requirements Document (PRD) Universal Template
## 1. Project Overview
### 1.1 Project Name
**[Project Name]** - [Brief Project Description]
### 1.2 Project Objectives
[Describe the main objectives of the project, including the product's core value proposition, target users, and primary problems being solved]
### 1.3 Project Background
- **Market Demand**: [Explain market pain points and opportunities]
- **Competitive Analysis**: [Limitations of existing solutions]
- **Business Value**: [Expected business benefits]
## 2. Functional Requirements
### 2.1 Core Features
#### 2.1.1 [Primary Feature One]
- **[Sub-feature A]**:
- [Specific feature description]
- [Supported operation types]
- [Input/output specifications]
- **[Sub-feature B]**:
- [Detailed feature explanation]
- [Use case description]
- [Expected behavior definition]
#### 2.1.2 [Primary Feature Two]
- **[Sub-feature C]**:
- [Detailed feature requirements]
- [Integration requirements]
- [Performance standards]
### 2.2 Advanced Features
#### 2.2.1 [Advanced Feature One]
- [Feature description]
- [Implementation requirements]
- [Dependency explanation]
#### 2.2.2 [Advanced Feature Two]
- [Feature specifications]
- [User experience requirements]
- [Technical constraints]
### 2.3 User Interface
#### 2.3.1 [Interface Type One] (e.g., Web Interface, CLI, API)
- [Interface design requirements]
- [Interaction flow design]
- [Visualization requirements]
#### 2.3.2 [Configuration & Settings System]
- [Configuration file format]
- [Environment variable support]
- [Multi-environment configuration]
## 3. Technical Requirements
### 3.1 Technology Stack
- **Primary Technology**: [Programming language/framework]
- **Database**: [Database choice and rationale]
- **Third-party Services**: [External APIs or services]
- **Deployment Environment**: [Cloud platform or deployment method]
### 3.2 Dependencies
```
[package-name]>=[version] # [Purpose description]
[package-name]>=[version] # [Purpose description]
[package-name]>=[version] # [Purpose description]
```
### 3.3 Architecture Design
#### 3.3.1 Module Structure
```
[project-name]/
├── src/
│ └── [project-name]/
│ ├── __init__.py
│ ├── core/
│ │ ├── services/
│ │ │ ├── [service-one]_service.py
│ │ │ └── [service-two]_service.py
│ │ ├── models/
│ │ │ ├── [data-model-one]_model.py
│ │ │ └── [data-model-two]_model.py
│ │ └── repositories/
│ │ └── [data-access-layer]_repository.py
│ ├── [interface-layer]/
│ │ ├── commands/
│ │ └── utils/
│ ├── config/
│ │ ├── settings.py
│ │ └── environment.py
│ └── utils/
│ ├── [utility-class-one].py
│ └── [utility-class-two].py
```
#### 3.3.2 Design Patterns
- **[Pattern One]**: [Usage rationale and scenarios]
- **[Pattern Two]**: [Usage rationale and scenarios]
- **[Pattern Three]**: [Usage rationale and scenarios]
### 3.4 Data Storage
- **[Storage Type One]**: [Purpose and format]
- **[Storage Type Two]**: [Purpose and format]
- **[Storage Type Three]**: [Purpose and format]
## 4. [Primary Interface] Command Design (if applicable)
### 4.1 Basic Commands
```bash
# [Basic Operation One]
[command-prefix] --[parameter-one]="[value]" --[parameter-two]="[value]"
# [Basic Operation Two]
[command-prefix] --[parameter-three]="[value]" --[output-directory]="[path]"
# [Basic Operation Three]
[command-prefix] --[input-file]="[file]" --[format]="[format]"
```
### 4.2 Advanced Commands
```bash
# [Advanced Operation One]
[command-prefix] --[parameter] --[option-one] --[option-two]
# [Advanced Operation Two]
[command-prefix] --[config-file]="[file]" --[debug-mode]
# [Advanced Operation Three]
[command-prefix] --[monitor] --[performance-analysis]
```
### 4.3 Management Commands
```bash
# [Management Operation One]
[command-prefix] --[check] --[validate]
# [Management Operation Two]
[command-prefix] --[cleanup] --[maintenance]
# [Management Operation Three]
[command-prefix] --[update] --[upgrade]
```
## 5. Error Handling & Recovery Mechanisms
### 5.1 [Error Type One] Handling
- **[Specific Error Condition One]**:
- [Detection mechanism]
- [Handling strategy]
- [Recovery method]
- **[Specific Error Condition Two]**:
- [Error identification]
- [Automated handling process]
- [User notification mechanism]
### 5.2 [Error Type Two] Handling
- **[Error Scenario]**: [Handling approach]
- **[Exception Condition]**: [Response strategy]
- **[System Failure]**: [Recovery process]
### 5.3 User Error Handling
- **Input Validation**: [Validation rules]
- **User-friendly Error Messages**: [Message design principles]
- **Error Classification**: [Error code system]
## 6. [State Management & Persistence] (if applicable)
### 6.1 State Preservation
- **[State Type One] Format**:
```json
{
"[state-id]": "[value]",
"[state-attribute-one]": "[value]",
"[state-attribute-two]": {
"[sub-attribute-one]": "[value]",
"[sub-attribute-two]": "[value]"
},
"[timestamp]": {
"[created-time]": "[ISO-format-time]",
"[updated-time]": "[ISO-format-time]"
}
}
```
### 6.2 Recovery Mechanisms
- **Automatic Recovery**: [Automated process]
- **Manual Recovery**: [Manual operation method]
- **State Validation**: [Integrity checking]
## 7. Performance Monitoring & Optimization
### 7.1 Performance Metrics
- **[Performance Metric One]**: [Measurement method and standards]
- **[Performance Metric Two]**: [Monitoring frequency and thresholds]
- **[System Resource Metrics]**: [Resource usage monitoring]
### 7.2 Optimization Strategies
- **[Optimization Aspect One]**: [Specific strategies]
- **[Optimization Aspect Two]**: [Implementation methods]
- **[Resource Management]**: [Resource allocation strategies]
### 7.3 Performance Reporting
- **Statistical Information**: [Collected metrics]
- **Report Format**: [Output methods]
- **Trend Analysis**: [Long-term monitoring]
## 8. Logging Management & Output Standards
### 8.1 Log Level Definitions
- **DEBUG**: [Debug information scope]
- **INFO**: [General information content]
- **WARNING**: [Warning condition definitions]
- **ERROR**: [Error event recording]
- **CRITICAL**: [Critical error handling]
### 8.2 Log Format Standards
#### 8.2.1 Console Output
```
'[time-format] - [module-name] - [level] - [message-content]'
```
#### 8.2.2 File Logging
```
'[detailed-time-format] [process-info] [module]:[line-number] - [level] - [message]'
```
### 8.3 Log File Management
- **File Naming**: [Naming conventions]
- **Rotation Mechanism**: [File size and time limits]
- **Retention Policy**: [File retention period]
### 8.4 Sensitive Information Protection
- **Prohibited Logging**: [Sensitive data types]
- **Information Masking**: [Masking rules]
- **Access Control**: [Log file permissions]
## 9. Configuration File Specifications
### 9.1 Main Configuration File ([filename])
```json
{
"[feature-module-one]": {
"[config-item-one]": "[default-value]",
"[config-item-two]": "[default-value]",
"[config-item-three]": [
"[option-one]",
"[option-two]"
]
},
"[feature-module-two]": {
"[config-item-four]": "[default-value]",
"[config-item-five]": {
"[sub-config-one]": "[value]",
"[sub-config-two]": "[value]"
}
},
"[logging-config]": {
"level": "INFO",
"file_enabled": true,
"console_enabled": true
},
"[performance-config]": {
"[monitoring-switch]": true,
"[monitoring-interval]": 30,
"[optimization-switch]": true
}
}
```
### 9.2 Environment Variable Configuration
```bash
# Basic Configuration
[project-prefix]_[config-item-one]=[value]
[project-prefix]_[config-item-two]=[value]
# Performance Configuration
[project-prefix]_[performance-param-one]=[value]
[project-prefix]_[performance-param-two]=[value]
# Feature Toggles
[project-prefix]_[feature-toggle-one]=[boolean-value]
[project-prefix]_[feature-toggle-two]=[boolean-value]
```
## 10. Integration & Extension Features
### 10.1 External Integration
#### 10.1.1 [External Service Type One]
- **[Service One]**: [Integration purpose and method]
- **[Service Two]**: [API integration and data exchange]
#### 10.1.2 [External Tool Type Two]
- **[Tool One]**: [Integration method]
- **[Tool Two]**: [Configuration requirements]
### 10.2 Extension Mechanisms
#### 10.2.1 [Extension Type One] (e.g., Plugin System)
```python
# [Extension Interface Definition]
class [ExtensionBaseClass]:
def [method_one](self, [parameter]): pass
def [method_two](self, [parameter]): pass
def [method_three](self, [parameter]): pass
# [Concrete Implementation Example]
class [ConcreteExtensionClass]:
def [implementation_method](self, [parameter]): pass
```
#### 10.2.2 Built-in Extensions
- **[Extension One]**: [Feature description]
- **[Extension Two]**: [Use cases]
- **[Extension Three]**: [Configuration method]
## 11. Testing Requirements
### 11.1 Unit Testing
- [Test Scope One]: [Test objectives and methods]
- [Test Scope Two]: [Testing tools and frameworks]
- [Test Scope Three]: [Coverage requirements]
### 11.2 Integration Testing
- [Integration Scenario One]: [Test process]
- [Integration Scenario Two]: [Validation standards]
- [Integration Scenario Three]: [Test environment requirements]
### 11.3 Performance Testing
- [Performance Scenario One]: [Load testing]
- [Performance Scenario Two]: [Stress testing]
- [Performance Scenario Three]: [Stability testing]
### 11.4 User Acceptance Testing
- [Test Scenario One]: [User story validation]
- [Test Scenario Two]: [User experience evaluation]
- [Test Scenario Three]: [Feature completeness confirmation]
## 12. Deployment & Operations
### 12.1 Deployment Requirements
- **[Deployment Environment One]**: [Environment specifications and requirements]
- **[Deployment Environment Two]**: [Configuration and dependencies]
- **[Deployment Process]**: [Automated deployment steps]
### 12.2 Monitoring & Operations
- **[Monitoring Metrics]**: [Monitoring items and alerts]
- **[Operations Process]**: [Daily maintenance operations]
- **[Incident Handling]**: [Emergency response procedures]
### 12.3 Version Management
- **[Version Strategy]**: [Version numbering rules]
- **[Release Process]**: [Release checklist]
- **[Rollback Mechanism]**: [Version rollback procedures]
## 13. Security Considerations
### 13.1 Data Security
- **[Data Encryption]**: [Encryption methods and standards]
- **[Access Control]**: [Permission management mechanisms]
- **[Data Backup]**: [Backup strategies and recovery]
### 13.2 System Security
- **[Authentication]**: [Authentication mechanisms]
- **[Authorization Management]**: [Permission hierarchy]
- **[Security Auditing]**: [Audit logs and monitoring]
### 13.3 Compliance Requirements
- **[Regulatory Compliance]**: [Relevant regulations and standards]
- **[Privacy Protection]**: [Personal data processing principles]
- **[Security Certification]**: [Security standard compliance]
## 14. Project Timeline & Milestones
### 14.1 Development Phases
| Phase | Timeline | Key Deliverables | Acceptance Criteria |
|---------------|----------|--------------------|-------------------------|
| [Phase One] | [Time] | [Deliverable List] | [Acceptance Conditions] |
| [Phase Two] | [Time] | [Deliverable List] | [Acceptance Conditions] |
| [Phase Three] | [Time] | [Deliverable List] | [Acceptance Conditions] |
### 14.2 Key Milestones
- **[Milestone One]**: [Time] - [Achievement Goals]
- **[Milestone Two]**: [Time] - [Achievement Goals]
- **[Milestone Three]**: [Time] - [Achievement Goals]
## 15. Risk Management
### 15.1 Technical Risks
| Risk Item | Probability | Impact | Mitigation Strategy |
|----------------------|-------------------|-------------------|------------------------------------|
| [Technical Risk One] | [High/Medium/Low] | [High/Medium/Low] | [Prevention and handling measures] |
| [Technical Risk Two] | [High/Medium/Low] | [High/Medium/Low] | [Prevention and handling measures] |
### 15.2 Project Risks
| Risk Item | Probability | Impact | Mitigation Strategy |
|--------------------|-------------------|-------------------|------------------------------------|
| [Project Risk One] | [High/Medium/Low] | [High/Medium/Low] | [Prevention and handling measures] |
| [Project Risk Two] | [High/Medium/Low] | [High/Medium/Low] | [Prevention and handling measures] |
## 16. Success Criteria & Acceptance Conditions
### 16.1 Functional Acceptance Criteria
- **[Functional Aspect One]**: [Specific acceptance conditions]
- **[Functional Aspect Two]**: [Test passing standards]
- **[Integration Aspect]**: [System integration acceptance]
### 16.2 Non-functional Acceptance Criteria
- **[Performance Standards]**: [Specific metrics and thresholds]
- **[Stability Standards]**: [Availability requirements]
- **[User Experience Standards]**: [User satisfaction metrics]
### 16.3 Business Objective Achievement
- **[Business Metric One]**: [Measurement methods and target values]
- **[Business Metric Two]**: [Achievement standards]
- **[Return on Investment]**: [ROI evaluation criteria]
---
## Template Usage Guidelines
1. **Customization**: Adjust section content based on project nature, remove inapplicable sections
2. **Content Completion**: Replace `[placeholders]` with actual project information
3. **Structure Extension**: Add or refine sections based on project complexity
4. **Version Control**: Recommend using version control systems to manage PRD documents
5. **Regular Updates**: Periodically review and update PRD content as the project progresses
---實際用 PRD.md 範本生成的 Python module-specific PRD.md
專案核心定位與商業價值
『Deus YouTube Transcription Detector』是一個輕量級的 YouTube 影片 Transcription 檢測工具，設計來用於快速檢查 YouTube 影片是否提供官方或使用者上傳的轉錄文字。這個工具的商業價值主要體現在解決研究人員、內容創作者和字幕工作者的實際痛點：他們需要快速識別哪些 YouTube 影片有可用的轉錄內容，而現有工具缺乏專門的轉錄檢測功能，大多需要完整下載影片才能檢查可用性。
專案的核心目標是節省手動檢查時間、提升字幕工作流程效率，並支援大規模內容分析。這種明確的商業價值導向確保了開發資源投入在解決實際問題上，而不是追求技術本身。工具支援批次檢測、多語言轉錄識別，以及詳細的報告功能，讓使用者能夠高效處理大量影片的轉錄狀態檢查工作。
分層式功能架構設計
PRD 採用清晰的分層功能架構，將功能需求分為核心功能、進階功能和使用者介面三個層次。核心功能層包含轉錄可用性檢測、批次檢測處理和快速查詢模式。轉錄可用性檢測能夠識別自動產生字幕、手動上傳字幕、社群貢獻字幕等不同類型，同時支援多語言檢測和品質評估。批次檢測處理支援 URL 清單批次處理、完整播放清單掃描、頻道影片批次檢測，以及結果匯總分析。
進階功能層提供詳細資訊提取和結果匯出報告功能。詳細資訊提取包含轉錄元資料（建立時間、更新狀態、貢獻者資訊）和影片關聯資訊（基本影片資訊、頻道資訊、影片時長）。結果匯出支援多格式輸出（JSON、CSV、TXT、HTML），以及自定義報告樣版功能。這種分層設計確保了功能的清晰性和可擴展性，讓開發團隊能夠按照優先順序進行開發。
技術架構與實作策略
技術架構採用 Python 3.10+ 作為主要技術，搭配 yt-dlp、google-api-python-client 等核心套件，使用 Click 作為 CLI 框架，Pandas 進行資料處理。這種技術選型考慮了 YouTube 資料提取的實際需求和 Python 生態系的成熟度。架構設計遵循分層架構原則，包含核心服務層、模型層、CLI 命令層、檢測器層、匯出器層等模組。
設計模式的應用包括服務層模式（Service Layer Pattern）封裝業務邏輯、策略模式（Strategy Pattern）支援多種檢測策略、工廠模式（Factory Pattern）動態建立檢測器、觀察者模式（Observer Pattern）處理進度通知。資料儲存策略採用本地快取來避免重複 API 呼叫，使用 YAML 格式配置檔案，支援 JSON、CSV、HTML 格式的結果輸出。
CLI 介面設計與使用者體驗
CLI 介面設計非常完整，涵蓋基礎指令、進階指令、報告分析指令和維護指令四個類別。基礎指令支援單一影片轉錄檢測、快速模式檢測、指定語言檢測、播放清單批次檢測等常用功能。進階指令提供詳細檢測模式、頻道影片批次掃描、自定義輸出格式、快取管理、平行處理、篩選條件等進階功能。
特別值得注意的是進度顯示設計，包含視覺化的進度條、彩色狀態輸出、統計資訊即時更新等使用者體驗要素。像是批次檢測進度會顯示整體進度條、目前處理的影片、已檢測結果統計等資訊，讓使用者能夠清楚掌握處理狀況。這種細緻的使用者體驗設計體現了 PRD 對於實用性的重視。
錯誤處理與系統穩定性
錯誤處理機制設計非常全面，分為 YouTube API 錯誤處理、網路連線錯誤、資料處理錯誤、批次處理錯誤四個主要類別。YouTube API 錯誤處理包含自動配額耗盡警告、請求速率限制遵循、多重 API 金鑰輪替、智慧重試機制等。影片存取錯誤處理能夠識別私人影片、偵測地區限制、自動跳過已刪除影片、驗證無效 URL 格式。
網路連線錯誤處理提供可配置的逾時設定、自動重試機制、網路狀態偵測、離線模式支援。批次處理錯誤採用錯誤項目隔離處理策略，保留成功項目結果，詳細記錄失敗原因，並提供重試佇列管理。這種全面的錯誤處理設計確保了工具在各種異常情況下都能優雅地處理並提供有用的回饋資訊。
效能監控與最佳化
效能監控機制追蹤關鍵指標包括每分鐘檢測影片數、平均檢測時間、API 呼叫效率、快取命中率等。最佳化策略涵蓋批次處理最佳化，包含智慧批次大小調整、平行處理數量控制、API 呼叫最佳化、記憶體使用控制等面向。快取機制設計包含影片檢測結果快取（24 小時）、播放清單結構快取（1 小時）、頻道資訊快取（6 小時）、錯誤結果短期快取（30 分鐘）等不同層級的快取策略。
這種多層次的效能最佳化設計確保了工具在處理大量影片時能夠維持良好的效能表現，同時減少不必要的 API 呼叫和網路請求。快取機制的設計考慮了不同類型資料的更新頻率，採用適當的快取時間來平衡效能和資料新鮮度。
配置管理與環境適配
配置管理系統設計支援 YAML 配置檔案和環境變數兩種配置方式。主要配置檔案（deus-config.yaml）涵蓋 YouTube API 配置、檢測配置、批次處理配置、快取配置、輸出配置、日誌配置等完整的系統參數。每個配置區塊都有詳細的參數說明和預設值定義，讓使用者能夠根據實際需求進行調整。
環境變數配置支援 API 配置、檢測配置、效能配置、快取配置、日誌配置等關鍵參數的覆寫，讓系統能夠在不同部署環境中靈活適配。配置驗證機制確保配置資料的正確性和完整性，避免因配置錯誤導致的系統異常。這種雙重配置機制提供了靈活性和便利性的平衡。
測試策略與品質保證
測試策略涵蓋單元測試、整合測試、效能測試三個層面。單元測試專注於核心服務功能測試，包含 DeusTranscriptionDetectorService 功能測試、DeusYouTubeApiService API 整合測試、DeusBatchProcessorService 批次處理測試、配置載入和驗證測試等。整合測試覆蓋完整檢測工作流程測試、批次處理功能測試、錯誤處理機制測試、快取機制功能測試等。
效能測試包含大型批次檢測效能測試、API 配額使用效率測試、記憶體使用測試、快取效能測試等。這種全面的測試策略確保了產品品質和功能完整性，同時驗證了系統在各種使用場景下的穩定性和效能表現。
部署運維與安全考量
部署需求涵蓋本地安裝、Docker 部署、CI/CD 整合等多種部署方式。本地安裝支援 pip 安裝和虛擬環境設定，Docker 部署提供容器化部署選項，CI/CD 整合支援自動化測試和部署流水線。監控指標包含 API 使用監控（配額使用、請求成功率）、效能監控（檢測速度、記憶體使用）、錯誤監控（失敗率、錯誤類型分佈）等。
安全考量包含 API 金鑰安全和資料隱私兩個主要面向。API 金鑰安全採用環境變數儲存、配置檔案權限控制、金鑰輪替機制支援等措施。資料隱私保護確保不儲存影片內容，只記錄檢測元資料，並遵循使用者隱私保護原則。這種全面的安全設計確保了工具在實際使用中的安全性和合規性。
# Product Requirements Document (PRD) - Deus YouTube Transcription Detector
## 1. Project Overview
### 1.1 Project Name
**Deus YouTube Transcription Detector** - YouTube Video Transcription Availability Detection Tool
### 1.2 Project Objectives
Develop a lightweight YouTube video transcription detection tool specifically designed for quickly checking whether
YouTube videos provide official or user-uploaded transcriptions. The tool supports batch detection, multi-language
transcription identification, and detailed reporting capabilities.
### 1.3 Project Background
- **Market Need**: Researchers, content creators, and subtitle workers need to quickly identify which YouTube videos
have available transcriptions
- **Competitive Analysis**: Existing tools lack dedicated transcription detection features, with most requiring full
video downloads to check availability
- **Business Value**: Save manual checking time, improve subtitle workflow efficiency, support large-scale content
analysis
## 2. Functional Requirements
### 2.1 Core Features
#### 2.1.1 Transcription Availability Detection
- **Transcription Type Identification**:
- Auto-generated captions detection
- Manual uploaded captions detection
- Community contributed captions detection
- Transcription source type marking
- **Language Support Detection**:
- Available transcription language listing
- Primary language identification
- Multi-language transcription detection
- Standardized language code output
- **Transcription Quality Information**:
- Transcription completeness check
- Timeline availability confirmation
- Transcription length statistics
- Quality assessment metrics
#### 2.1.2 Batch Detection Processing
- **Multi-Video Detection**:
- URL list batch processing
- Complete playlist scanning
- Channel video batch detection
- CSV file input support
- **Result Aggregation**:
- Detection result statistical reports
- Available/unavailable transcription classification
- Language distribution statistics
- Detection success rate analysis
#### 2.1.3 Quick Query Mode
- **Real-time Detection**:
- Single URL quick detection
- Instant result display
- Simplified output mode
- Error status reporting
### 2.2 Advanced Features
#### 2.2.1 Detailed Information Extraction
- **Transcription Metadata**:
- Transcription creation time
- Transcription update status
- Transcription contributor information
- Transcription version tracking
- **Video Associated Information**:
- Basic video information
- Channel information
- Video duration
- Upload time
#### 2.2.2 Result Export and Reporting
- **Multi-format Output**:
- JSON structured output
- CSV table format export
- TXT simplified reports
- HTML visualization reports
- **Custom Report Templates**:
- Configurable output fields
- Report style customization
- Statistical chart generation
- Summary information generation
### 2.3 User Interface
#### 2.3.1 Command Line Interface (CLI)
- Concise parameter design
- Colored status output
- Progress bar display
- Detailed error reporting
#### 2.3.2 Configuration System
- YAML configuration file support
- Default template provision
- Environment variable override
- Configuration validation mechanism
## 3. Technical Requirements
### 3.1 Technology Stack
- **Primary Technology**: Python 3.10+
- **Core Packages**: yt-dlp, google-api-python-client
- **CLI Framework**: Click
- **Data Processing**: Pandas
### 3.2 Dependencies
```
yt-dlp>=2024.1.0 # YouTube data extraction
google-api-python-client>=2.100.0 # YouTube API client
click>=8.1.0 # Command line interface
rich>=13.7.0 # Enhanced output
pandas>=2.0.0 # Data processing
pydantic>=2.5.0 # Data validation
requests>=2.31.0 # HTTP requests
loguru>=0.7.0 # Logging management
PyYAML>=6.0 # YAML configuration
```
### 3.3 Architecture Design
#### 3.3.1 Module Structure
```
deus_youtube_transcription_detector/
├── src/
│ └── deus_youtube_transcription_detector/
│ ├── __init__.py
│ ├── __main__.py
│ ├── core/
│ │ ├── services/
│ │ │ ├── deus_transcription_detector_service.py
│ │ │ ├── deus_youtube_api_service.py
│ │ │ └── deus_batch_processor_service.py
│ │ ├── models/
│ │ │ ├── deus_video_model.py
│ │ │ ├── deus_transcription_info_model.py
│ │ │ └── deus_detection_result_model.py
│ │ └── repositories/
│ │ └── deus_result_repository.py
│ ├── cli/
│ │ ├── commands/
│ │ │ ├── deus_detect_commands.py
│ │ │ ├── deus_batch_commands.py
│ │ │ └── deus_report_commands.py
│ │ └── utils/
│ │ ├── deus_progress_display.py
│ │ ├── deus_output_formatter.py
│ │ └── deus_status_reporter.py
│ ├── detectors/
│ │ ├── deus_transcription_detector.py
│ │ ├── deus_language_detector.py
│ │ └── deus_quality_assessor.py
│ ├── exporters/
│ │ ├── deus_json_exporter.py
│ │ ├── deus_csv_exporter.py
│ │ ├── deus_html_exporter.py
│ │ └── deus_report_generator.py
│ ├── config/
│ │ ├── deus_settings.py
│ │ ├── deus_api_config.py
│ │ └── deus_logging_config.py
│ └── utils/
│ ├── deus_youtube_client.py
│ ├── deus_url_validator.py
│ ├── deus_cache_manager.py
│ └── deus_error_handler.py
```
#### 3.3.2 Design Patterns
- **Service Layer Pattern**: Business logic encapsulation in service layer
- **Strategy Pattern**: Multiple detection strategy support
- **Factory Pattern**: Dynamic detector creation
- **Observer Pattern**: Progress notification mechanism
### 3.4 Data Storage
- **Local Cache**: Detection result caching to avoid duplicate API calls
- **Configuration Files**: YAML format configuration files
- **Output Files**: JSON, CSV, HTML format results
## 4. CLI Command Design
### 4.1 Basic Commands
```bash
# Single video transcription detection
deus-transcription-detect --url="https://youtube.com/watch?v=VIDEO_ID"
# Quick mode detection
deus-transcription-detect --url="..." --quick --output="simple"
# Specify language detection
deus-transcription-detect --url="..." --languages="zh-TW,en" --detailed
# Playlist batch detection
deus-transcription-detect --playlist="https://youtube.com/playlist?list=PLAYLIST_ID"
# URL list batch processing
deus-transcription-detect --input-file="video_urls.txt" --output-format="csv"
```
### 4.2 Advanced Commands
```bash
# Detailed detection mode
deus-transcription-detect --url="..." --detailed --include-metadata --quality-check
# Channel video batch scanning
deus-transcription-detect --channel="CHANNEL_ID" --max-videos=100 --filter-recent="30d"
# Custom output format
deus-transcription-detect --input-file="..." --output-format="json" --output-file="results.json"
# Cache management
deus-transcription-detect --cache-mode="refresh" --cache-ttl="1h"
# Parallel processing
deus-transcription-detect --input-file="..." --parallel=5 --timeout=30
# Filter conditions
deus-transcription-detect --playlist="..." --filter-duration="min:300,max:3600" --filter-language="zh-TW"
```
### 4.3 Reporting and Analysis Commands
```bash
# Generate statistical reports
deus-transcription-detect --analyze --input-file="results.json" --report-type="summary"
# Comparative analysis
deus-transcription-detect --compare --file1="before.json" --file2="after.json"
# Export HTML reports
deus-transcription-detect --export-html --input="results.json" --template="detailed"
# Statistical summary
deus-transcription-detect --stats --input-dir="./results" --group-by="language,type"
```
### 4.4 Maintenance Commands
```bash
# Clear cache
deus-transcription-detect --clear-cache --older-than="7d"
# Verify API configuration
deus-transcription-detect --verify-api --test-quota
# Update configuration file
deus-transcription-detect --init-config --template="advanced"
# Diagnostic mode
deus-transcription-detect --diagnose --check-dependencies --test-connection
```
### 4.5 Progress Display Examples
```bash
# Single video detection
🔗 Connecting to YouTube API... ✅ Complete
📹 Retrieving video information... ✅ Complete
📝 Detecting transcription availability... ✅ Found 2 language transcriptions
📊 Quality assessment... ✅ Complete
# Batch detection progress
📋 Batch Detection: 50 videos
📊 Overall Progress: [██████████████████░░░░░░░░░░░░] 60% | 30/50 completed
🎯 Current: "Video Title" [███████████████████████░░░░░] 85% | Detecting transcriptions
✅ Has Transcription: 18 | ❌ No Transcription: 12 | ⏳ Pending: 20
# Detection result summary
📈 Detection Completion Statistics:
🎯 Total Videos: 50
✅ Has Transcription: 32 (64%)
❌ No Transcription: 18 (36%)
🌐 Language Distribution: zh-TW(25), en(18), ja(8), other(3)
📝 Transcription Types: Auto(28), Manual(4)
```
## 5. Error Handling and Recovery Mechanisms
### 5.1 YouTube API Error Handling
- **API Limit Handling**:
- Automatic quota exhaustion warning
- Request rate limit compliance
- Multiple API key rotation
- Intelligent retry mechanism
- **Video Access Errors**:
- Private video identification marking
- Region restriction detection logging
- Automatic skipping of deleted videos
- Invalid URL format validation
### 5.2 Network Connection Errors
- **Connection Timeout Handling**:
- Configurable timeout settings
- Automatic retry mechanism
- Network status detection
- Offline mode support
### 5.3 Data Processing Errors
- **Data Format Errors**:
- Input file format validation
- Automatic corrupt data repair
- Encoding issue handling
- Format conversion error handling
### 5.4 Batch Processing Errors
- **Partial Failure Handling**:
- Error item isolation processing
- Successful item result retention
- Detailed failure reason logging
- Retry queue management
## 6. Detection Result Persistence
### 6.1 Result Data Format
```json
{
"detection_id": "uuid-string",
"timestamp": "2025-08-03T10:00:00Z",
"video_info": {
"video_id": "YouTube_VIDEO_ID",
"title": "Video Title",
"channel": "Channel Name",
"duration": 1800,
"upload_date": "2025-07-15T14:30:00Z"
},
"transcription_status": {
"has_transcription": true,
"transcription_types": [
"auto_generated",
"manual"
],
"available_languages": [
{
"language_code": "zh-TW",
"language_name": "Traditional Chinese",
"type": "manual",
"quality_score": 0.95
},
{
"language_code": "en",
"language_name": "English",
"type": "auto_generated",
"quality_score": 0.87
}
],
"primary_language": "zh-TW",
"total_languages": 2
},
"detection_metadata": {
"detection_method": "api_v3",
"processing_time_ms": 1250,
"api_calls_used": 3,
"cache_hit": false,
"error_occurred": false
}
}
```
### 6.2 Caching Mechanism
- **Result Caching**:
- Video detection result cache (24 hours)
- Playlist structure cache (1 hour)
- Channel information cache (6 hours)
- Error result short-term cache (30 minutes)
## 7. Performance Monitoring and Optimization
### 7.1 Performance Metrics
- **Detection Performance**:
- Videos detected per minute
- Average detection time
- API call efficiency
- Cache hit rate
### 7.2 Optimization Strategies
- **Batch Processing Optimization**:
- Intelligent batch size adjustment
- Parallel processing count control
- API call optimization
- Memory usage control
## 8. Logging Management and Output Standards
### 8.1 Log Level Definitions
- **DEBUG**: Detailed API request information, cache operation details
- **INFO**: 🚀 Detection start, ✅ Detection complete, 📊 Statistical information
- **WARNING**: ⚠️ API quota approaching limit, ⚠️ Low detection quality
- **ERROR**: ❌ Individual video detection failure, ❌ Network connection issues
- **CRITICAL**: 💥 Invalid API key, 💥 Insufficient system resources
### 8.2 Log Format
```python
# Console output format
'%(asctime)s - %(name)s - %(levelname)s - %(message)s'
# Detection event logs
logger.info("🔍 Starting video detection: %(video_title)s")
logger.info("✅ Detection complete: Found %(lang_count)d language transcriptions")
logger.warning("⚠️ Video has no available transcription: %(video_id)s")
```
## 9. Configuration File Specifications
### 9.1 Main Configuration File (deus-config.yaml)
```yaml
# YouTube API configuration
youtube_api:
api_keys:
- "YOUR_YOUTUBE_API_KEY_1"
- "YOUR_YOUTUBE_API_KEY_2"
quota_limit_per_day: 10000
quota_warning_threshold: 0.8
request_timeout: 30
max_retries: 3
# Detection configuration
detection:
target_languages:
- "zh-TW"
- "en"
- "ja"
- "ko"
include_auto_generated: true
include_manual: true
include_community: true
quality_threshold: 0.7
# Batch processing configuration
batch_processing:
max_concurrent: 5
batch_size: 10
timeout_per_video: 15
retry_failed: true
max_retries: 2
# Cache configuration
cache:
enabled: true
cache_dir: "./cache"
default_ttl_hours: 24
max_cache_size_mb: 100
auto_cleanup: true
# Output configuration
output:
default_format: "json"
include_metadata: true
compress_output: false
date_format: "ISO"
# Logging configuration
logging:
level: "INFO"
file_enabled: true
file_path: "./logs/deus-transcription-detect.log"
file_rotation: "10 MB"
file_retention: 30
console_colors: true
```
### 9.2 Environment Variable Configuration
```bash
# API configuration
DEUS_YOUTUBE_API_KEY=your_api_key_here
DEUS_QUOTA_LIMIT=10000
# Detection configuration
DEUS_DETECT_LANGUAGES=zh-TW,en,ja
DEUS_INCLUDE_AUTO_GENERATED=true
DEUS_QUALITY_THRESHOLD=0.7
# Performance configuration
DEUS_MAX_CONCURRENT=5
DEUS_BATCH_SIZE=10
DEUS_TIMEOUT=15
# Cache configuration
DEUS_CACHE_ENABLED=true
DEUS_CACHE_TTL_HOURS=24
DEUS_CACHE_DIR=./cache
# Logging configuration
DEUS_LOG_LEVEL=INFO
DEUS_LOG_FILE=./logs/detection.log
```
## 10. Testing Requirements
### 10.1 Unit Testing
- DeusTranscriptionDetectorService functionality tests
- DeusYouTubeApiService API integration tests
- DeusBatchProcessorService batch processing tests
- Configuration loading and validation tests
### 10.2 Integration Testing
- Complete detection workflow tests
- Batch processing functionality tests
- Error handling mechanism tests
- Cache mechanism functionality tests
### 10.3 Performance Testing
- Large batch detection performance tests
- API quota usage efficiency tests
- Memory usage tests
- Cache performance tests
## 11. Deployment and Operations
### 11.1 Deployment Requirements
- **Local Installation**: pip installation support, virtual environment setup
- **Docker Deployment**: Containerized deployment options
- **CI/CD Integration**: Automated testing and deployment pipelines
### 11.2 Monitoring Metrics
- **API Usage Monitoring**: Quota usage, request success rates
- **Performance Monitoring**: Detection speed, memory usage
- **Error Monitoring**: Failure rates, error type distribution
## 12. Security Considerations
### 12.1 API Key Security
- Environment variable storage for API keys
- Configuration file permission control
- Key rotation mechanism support
### 12.2 Data Privacy
- No video content storage
- Only detection metadata logging
- User privacy protection
---
**Document Version**: v1.0
**Creation Date**: 2025-08-03
**Owner**: Development Team
**Reviewer**: Product Manager
