python3-add-feature

<feature_description>$ARGUMENTS</feature_description>

Python 機能追加ワークフロー

モデルは、発見、計画、実装、検証の各フェーズを通じて機能開発をガイドします。

引数

<feature_description/>

手順

1. 引数から機能リクエストを理解する
2. プロジェクトのコンテキストを把握する（構成、パターン、既存コード）
3. 実装を計画する（作成・変更するファイル、依存関係）
4. TDD に従ってテストを実施しながら実装する
5. 品質を検証する（リンティング、型、カバレッジ）

---

フェーズ 1：発見

プロジェクトのコンテキストを収集する

CHECK:
- [ ] pyproject.toml exists and has project configuration
- [ ] src/ or packages/ directory structure
- [ ] tests/ directory with existing test patterns
- [ ] Linting and type-check configuration (ruff; ty and/or mypy per project — see `standards-for-python-development`)
- [ ] Existing patterns for similar features

統合ポイントを特定する

機能を組み込む場所を決定します。

• この機能を担当するモジュール／パッケージはどれですか？
• どの既存クラス／関数と連携しますか？
• 新たに作成する必要があるファイルは何ですか？

---

フェーズ 2：計画

機能仕様

明確な仕様を作成します。

## Feature: [Name]

**Purpose**: [One sentence describing what this enables]

**User Story**: As a [user type], I want [capability] so that [benefit].

**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

**Files to Create/Modify**:
- `src/module/new_feature.py` - Main implementation
- `tests/test_new_feature.py` - Test suite
- `src/module/__init__.py` - Export new functionality

**Dependencies**:
- Internal: [existing modules to import]
- External: [new packages if any]

MoSCoW による優先順位付け

<moscow_framework>

すべての要件を MoSCoW に基づいて分類します。

優先度	意味	基準
P0（必須）	v1 に不可欠	これがなければ機能が成り立たない
P1（あるべき）	重要で、対応を約束する項目	価値は高いが、なくても v1 は動作する
P2（あるとよい）	時間があれば望ましい項目	あれば便利な改善
対象外	明示的に延期	今回のリリースの対象外

優先順位の確認：すべてが P0 なら、P0 はありません。優先順位を見直してください。

例：

### Requirements by Priority

**P0 (Must Have)**:
- [ ] Parse CSV input with header detection
- [ ] Output formatted report to stdout
- [ ] Handle malformed rows with error message

**P1 (Should Have)**:
- [ ] Support custom delimiter (--delimiter)
- [ ] Progress indicator for large files

**P2 (Could Have)**:
- [ ] JSON output format option
- [ ] Column filtering

**Won't Have (This Release)**:
- Excel format support (separate feature)
- Database export (requires new dependency)

</moscow_framework>

受け入れ基準の形式

<acceptance_criteria_patterns>

テスト可能な受け入れ基準には、次の形式のいずれか 1 つを使用します。

形式 1：Given／When／Then（BDD）

Given [precondition]
When [user action]
Then [expected outcome]

例：

Given a CSV file with 1000 rows
When the user runs `parse report.csv`
Then the output shows all rows within 2 seconds
And no memory warnings are logged

形式 2：具体的なチェックリスト

- [ ] Command `parse --help` shows usage with examples
- [ ] Empty file input returns exit code 1 with message "Empty file"
- [ ] Unicode characters in data are preserved in output
- [ ] Ctrl+C during processing exits cleanly (no stack trace)

避けるべきアンチパターン：

アンチパターン	問題点	改善例
「高速であるべき」	測定できない	「10K 行を <2s で処理する」
「エラーを適切に処理する」	曖昧	「無効な入力に対し、説明的なメッセージと終了コード 1 を返す」
「ユーザーフレンドリーな出力」	主観的	「ヘッダー付きの Rich テーブル形式で出力する」

</acceptance_criteria_patterns>

インターフェースを先に設計する

実装前にパブリック API を定義します。

# Define function signatures and docstrings
def new_feature(input_data: InputType, *, option: str = "default") -> ResultType:
    """Process input data with new feature capability.

    Args:
        input_data: The data to process
        option: Configuration option

    Returns:
        Processed result

    Raises:
        ValidationError: If input_data is invalid
    """
    ...

---

フェーズ 3：テスト駆動実装

先にテストを書く

import pytest
from pytest_mock import MockerFixture


class TestNewFeature:
    """Tests for new_feature functionality."""

    def test_basic_operation(self) -> None:
        """Test basic feature operation with valid input."""
        # Arrange
        input_data = create_valid_input()

        # Act
        result = new_feature(input_data)

        # Assert
        assert result.status == "success"

    def test_handles_invalid_input(self) -> None:
        """Test feature raises error for invalid input."""
        with pytest.raises(ValidationError, match="Invalid input"):
            new_feature(invalid_input)

    def test_option_affects_behavior(self) -> None:
        """Test that option parameter changes processing."""
        result_default = new_feature(data, option="default")
        result_custom = new_feature(data, option="custom")

        assert result_default != result_custom

テストに通るよう実装する

1. テストを実行します。失敗するはずです（レッド）。
2. テストに通る最小限のコードを実装します（グリーン）。
3. 品質向上のためにリファクタリングします（リファクタ）。
4. 各テストケースについて繰り返します。

実装チェックリスト

- [ ] All functions have complete type hints
- [ ] Docstrings follow Google style
- [ ] Error handling uses specific exceptions
- [ ] No hardcoded values (use constants or config)
- [ ] Follows existing project patterns

---

フェーズ 4：統合

モジュールのエクスポートを更新する

# src/module/__init__.py
from .new_feature import new_feature, ResultType

__all__ = [
    "new_feature",
    "ResultType",
    # ... existing exports
]

CLI に追加する（該当する場合）

@app.command()
def feature_command(input_file: Annotated[Path, typer.Argument(help="Input file")]) -> None:
    """Run new feature on input file."""
    result = new_feature(load_data(input_file))
    console.print(f"Result: {result}")

---

フェーズ 5：検証

品質チェックを実行する

# Linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type checking — match hooks/CI (ty vs mypy); do not use mypy only because [tool.mypy] exists
uv run ty check src/ tests/
# If hooks/CI run mypy:
# uv run mypy src/ tests/

# Tests with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

カバレッジポリシー

カバレッジは、実行された動作を示す証拠であり、達成すべき割合の目標ではありません。

• 変更した動作、パブリックコントラクト、境界条件、エラー処理、および変更に関係する再現済みの回帰をテストします。
• 単体テストではユーザーから見える契約を確認できない場合は、統合テストまたは動作テストを追加します。
• 変更したブランチのうちカバーされていないものを確認し、重大なリスクにあたるか判断します。
• リポジトリに既存のカバレッジゲートがある場合はそれに従います。プロジェクトに存在しない場合は、恣意的な割合を設定しないでください。
• 行カバレッジを増やすことだけを目的に、価値の低いテストを追加しないでください。

成功指標

<success_metrics_framework>

実装前に、測定可能な成功基準を定義します。

先行指標（数日〜数週間で確認可能）：

指標	目標	測定方法
テスト合格率	100%	pytest --tb=short
型カバレッジ	100%	ty check またはプロジェクトの mypy コマンド
変更された動作	関連するコントラクトとリスクの高いパスを検証	対象を絞ったテスト ＋ カバレッジの確認
コマンドの起動時間	<500ms	time uv run <cmd> --help

遅行指標（数週間〜数か月で確認可能）：

指標	目標	測定方法
ユーザーの利用状況	N 人／週	利用ログまたはフィードバック
エラー率	呼び出しの <1%	エラーログ
サポートチケット	ベースラインから減少	イシュートラッカー

CLI 機能の場合：

# Performance baseline
hyperfine 'uv run <command> <args>' --warmup 3

# Memory usage
/usr/bin/time -v uv run <command> <args> 2>&1 | grep "Maximum resident"

評価期間：指標を評価するタイミングを指定します（例：「マージの1週間後」「100回の呼び出し後」）。

</success_metrics_framework>

ドキュメント

関連ドキュメントを更新します。

• ユーザー向け機能の場合は README.md
• 公開インターフェースの場合は API ドキュメント
• 機能の説明を CHANGELOG.md に追加

---

ワークフローの例

依頼：「レポートモジュールに CSV エクスポート機能を追加する」

調査

Project structure:
- src/reports/generator.py - existing report generation
- src/reports/formats/ - existing format handlers
- tests/reports/ - existing report tests

Pattern: Format handlers inherit from BaseFormatter

計画

## Feature: CSV Export

**Purpose**: Export reports in CSV format

**Files**:
- `src/reports/formats/csv_formatter.py` - CSV implementation
- `tests/reports/formats/test_csv_formatter.py` - Tests

**Interface**:
class CsvFormatter(BaseFormatter):
    def format(self, report: Report) -> str: ...

実装

1. CsvFormatter のテストを作成する
2. CsvFormatter クラスを実装する
3. フォーマットファクトリーに登録する
4. CLI オプション --format csv を追加する
5. 検証チェックを実行する

---

品質基準

共有プラグイン標準に照らして機能を検証する際は、/python-engineering:standards-for-python-development の標準を読み込み、それに従ってください。以下を確認します。

1. 型安全性：すべてのコードがプロジェクトの型チェッカーを通過すること — hooks/CI に合わせて ty と mypy を使い分けます。リポジトリで ty を実行している場合は uv run ty check を使用します。mypy が実際に実行されている場合に限り uv run mypy を使用します（[tool.mypy] が存在するだけでは使用しません）。
2. リンティング：ruff のエラーや警告がないこと
3. テスト：変更された動作と関連する回帰／境界パスをカバーすること。既存のプロジェクトのカバレッジ基準がある場合は、それに従います。
4. パターン：既存のプロジェクト規約に従うこと
5. ドキュメント：すべての公開インターフェースに docstring があること

---

参考資料

• pytest ドキュメント
• pytest-mock
• Google Python スタイルガイド