swe-devops-standards

地理空間 SWE および DevOps 標準

目的: 地理空間作業の一環として作成されるコードは、ユーザーの実際の環境で動作し、ピアレベルのエンジニアリング品質を満たすべきです。これらのルールは、コードまたはリポジトリの成果物が対象範囲に含まれる場合にのみ適用してください。

1. 環境の現実（最大のエラー源）

• デフォルトはスクリプト優先: ユーザーが明示的にノートブック内にいる場合を除き、%matplotlib inline、!pip install、display() は使用しないでください。すべてのファイルは、if __name__ == "__main__": ブロックの背後で python script.py によってターミナルから実行されます。（# %% のようなセルマーカーは追加としてなら問題ありません — スクリプトはそれらがなくても動作する必要があります。）
• クロスプラットフォームのパス: 常に pathlib.Path を使用してください。文字列連結や / または \\ のハードコードは決してしないでください。シェルコマンドを提示する前に、ユーザーの OS を尋ねるか検出してください。Windows では CMD/PowerShell 構文を、それ以外では POSIX 構文を提示してください — 混在させないでください（export と set、venv/bin/activate と venv\Scripts\activate）。
• エンコーディング: すべてのテキストファイルを開く際に encoding="utf-8" を明示してください — Windows は依然としてレガシーコードページをデフォルトとしており、非 ASCII コンテンツはサイレントに破損します。
• モダン Python（3.11+）: X | None ユニオン、type エイリアス、コードを明確にする場合は構造的パターンマッチングを使用してください。機能がそれを必要とする場合は、最小バージョンを明記してください。

2. コード品質のデフォルト

要求されていない場合でも、生成されるすべての関数/モジュールに適用されます:

def compute_share(values: list[float], total: float) -> list[float]:
    """Return each value's share of the total.

    Args:
        values: Values to compute shares for.
        total: Denominator; must be non-zero.

    Returns:
        Shares in the same order as values.

    Raises:
        ValueError: If total is zero.
    """
    if total == 0:
        raise ValueError("total must be non-zero — share is undefined.")
    return [v / total for v in values]

• すべてのシグネチャに型ヒント。複雑な型には dataclass/TypeAlias を使用してください。
• Google スタイルの docstring。自明な関数には 1 行で十分です。
• 裸の except: は決して使用しないでください。特定の例外を捕捉し、処理するか、raise ... from e で再送出してください。サイレントな pass は 1 週間のデバッグを要します。
• ユーザー向けの CLI 出力を除き、print よりも logging（レベル付き、フォーマット済み）を使用してください。
• 重要な箇所ではアルゴリズムの計算量を注記してください（「これは O(n log n) で、n>10⁶ でも安全」） — 特にネストされたループや pandas の apply の周辺で。
• マジックナンバー → 名前付きのモジュールレベル定数にしてください。

3. テストと検証

• 実際のロジックを含むすべての関数に対して、少なくとも pytest のスケルトンを提供してください:

# test_compute.py — run: python -m pytest -q
import pytest
from compute import compute_share

def test_basic() -> None:
    assert compute_share([1, 1], 2) == [0.5, 0.5]

def test_zero_total_raises() -> None:
    with pytest.raises(ValueError):
        compute_share([1.0], 0)

• 数値コード: エッジケースをテストしてください — 空の入力、NaN、負の値、単一要素。
• 実行環境が存在する場合は、生成したコードを自分で実行してください。そうでない場合は、明示的に「未実行」とマークしてください — サイレントな仮定はしないでください。

4. 依存関係と再現性

• 新規プロジェクト → 仮想環境 + 固定された requirements.txt（package==version）。決して「最新版をインストール」しないでください。
• ランダム性をシードし、シードを設定に含めてください（詳細は ml-experiment-standards を参照）。
• 関連する場合は環境差異のリスク（BLAS、CUDA、ロケール）を注記してください。

5. Git の実践

• Conventional Commits: feat(scope): ...、fix: ...、refactor: ...。本文では なぜ を説明してください — diff はすでに 何を を示しています。
• 意味のある単位でコミットしてください。500 行の単一コミットに対しては警告してください。
• デフォルトの .gitignore: venv/、__pycache__/、*.pyc、大きなデータファイル（DVC/LFS を提案）、IDE フォルダー。

6. 自動化 / DevOps

• CI: テスト + リント（ruff）のための最小限の GitHub Actions。ジョブを Windows でも実行する必要がある場合は、OS ランナーの違いを注記してください。
• Docker: python:3.12-slim から始め、サイズやキャッシュがより多くを要求するまではシンプルなシングルステージにしてください。イメージサイズとビルドキャッシュへの影響を注記してください。
• モニタリング: 長時間稼働するサービス/パイプラインは、最低 3 つのシグナルを備えてください: 構造化ログ、障害アラート、基本的なメトリクス（所要時間、量）。ML サービスはドリフトチェックを追加してください（ml-experiment-standards を参照）。
• スケジュールされたジョブ: ユーザーのプラットフォームに合わせてください — POSIX では cron、Windows ではタスク スケジューラ（schtasks）。

7. コードレビューモード

この順序でレビューし、重要度別に所見を報告してください: 正確性（エッジケース、サイレント障害）→ セキュリティ（インジェクション、シークレット、パストラバーサル）→ パフォーマンス（N+1、不要なコピー、O(n²)）→ 可読性。すべての所見には、修正案をコードとして添付してください — 決して「これは良くない」だけで終わらせないでください。

実行契約

• ワークフロー: 地理空間コードの契約を明確化し、環境を再現し、正確性とデータ不変条件を検査し、最小限の安全な変更を実装し、テストし、パッケージ化し、運用とロールバックを文書化します。
• 意思決定ルール: このスキルは地理空間ソフトウェアとパイプラインのデリバリーに適用し、一般的な非空間のコーディングには適用しません。CI、コンテナ、オブザーバビリティは実際のデプロイリスクに応じてスケールさせます。
• 検証プロトコル: フォーカステストとリグレッションテストを実行し、設定されている場合は lint と型チェックを実行し、CRS／nodata／ジオメトリのエッジケースを検証し、クリーンインストールを確認し、CI 成果物をレビューします。
• 失敗モード: サイレントなデータ損失、非決定性、可変の隠れた状態、バージョン固定されていない重要な依存関係、シークレット、プラットフォームの前提、ロールバックの欠如、未処理の空間エッジケースについてはリリースをブロックします。
• 成果物: レビュー済みのコード、テスト、再現可能な環境とロックデータ、CI 設定、運用ノート、リスク順にランク付けされた所見、オブザーバビリティ計画、ロールバック手順。
• ソースの最新性: パッケージング、CI、テスト、サプライチェーンに関するガイダンスを適用する前に、信頼できるソースのレジストリを参照してください。