impl-standards

実装標準

一貫性があり、保守しやすいコードを確保するため、実装時には以下の標準を適用してください。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が誤っている、パラメーターがずれている、または回避策が必要だった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合のみ更新してください。

このスキルを使用するタイミング

• /itp:go のフェーズ 1 で
• 新しい本番コードを書くとき
• ユーザーが「エラー処理」、「定数」、「マジックナンバー」、「進捗ログ」、「SSoT」、「依存性注入」、「設定シングルトン」に言及したとき
• リリース前にコード品質を確認するとき

クイックリファレンス

標準	ルール
エラー	発生させて伝播する。フォールバック／デフォルト値／再試行／無言の処理は禁止
定数	マジックナンバーを、意味が明確でバージョンに依存しない動的定数に抽象化する
SSoT/DI	設定シングルトン → デフォルト値を None にする → リゾルバー → エントリーポイントでの検証
依存関係	独自コードより OSS ライブラリを優先する。後方互換性は不要
進捗	1 分を超える処理：15～60 秒ごとに状況をログに記録する
ログ	logs/{adr-id}-YYYYMMDD_HHMMSS.log（nohup）
メタデータ	任意：サービス検出用の catalog-info.yaml

---

エラー処理

基本ルール：発生させて伝播する。フォールバック／デフォルト値／再試行／無言の処理は禁止

# ✅ Correct - raise with context
def fetch_data(url: str) -> dict:
    response = requests.get(url)
    if response.status_code != 200:
        raise APIError(f"Failed to fetch {url}: {response.status_code}")
    return response.json()

# ❌ Wrong - silent catch
try:
    result = fetch_data()
except Exception:
    pass  # Error hidden

詳細なパターンについては、エラー処理リファレンスを参照してください。

---

定数の管理

基本ルール：マジックナンバーを意味が明確な定数に抽象化する

# ✅ Correct - named constant
DEFAULT_API_TIMEOUT_SECONDS = 30
response = requests.get(url, timeout=DEFAULT_API_TIMEOUT_SECONDS)

# ❌ Wrong - magic number
response = requests.get(url, timeout=30)

パターンについては、定数管理リファレンスを参照してください。

---

進捗ログ

1 分を超える処理では、15～60 秒ごとに状況をログに記録してください。

import logging
from datetime import datetime

logger = logging.getLogger(__name__)

def long_operation(items: list) -> None:
    total = len(items)
    last_log = datetime.now()

    for i, item in enumerate(items):
        process(item)

        # Log every 30 seconds
        if (datetime.now() - last_log).seconds >= 30:
            logger.info(f"Progress: {i+1}/{total} ({100*(i+1)//total}%)")
            last_log = datetime.now()

    logger.info(f"Completed: {total} items processed")

---

ログファイルの規約

ログの保存先：logs/{adr-id}-YYYYMMDD_HHMMSS.log

# Running with nohup
nohup python script.py > logs/2025-12-01-my-feature-20251201_143022.log 2>&1 &

---

---

データ処理

基本ルール：データフレームの操作には、Pandas より Polars を優先してください。

シナリオ	推奨事項
新しいデータパイプライン	Polars を使用する（30 倍高速、遅延評価）
ML の特徴量エンジニアリング	Polars → Arrow → NumPy（ゼロコピー）
MLflow のログ記録	Pandas でも可（例外のコメントを追加）
レガシーコードの修正	既存のライブラリを維持する

例外の仕組み：ファイルの先頭に追加します。

# polars-exception: MLflow requires Pandas DataFrames
import pandas as pd

判断ツリーとベンチマークについては、ml-data-pipeline-architectureを参照してください。

---

関連スキル

スキル	目的
adr-code-traceability	コードに ADR 参照を追加する
code-hardcode-audit	リリース前にハードコードされた値を検出する
ml-data-pipeline-architecture	Polars／Arrow の効率的なパターン

---

リファレンスドキュメント

• エラー処理 - 発生させて伝播するパターン
• 定数の管理 - マジックナンバーの抽象化
• SSoT／依存性注入 - 設定シングルトン → デフォルト値を None にする → リゾルバーチェーン

---

トラブルシューティング

問題	原因	解決策
何も通知されずに失敗する	bare except ブロック	特定の例外を捕捉し、ログに記録するか再送出します
コード内のマジックナンバー	定数が定義されていない	意味が分かる名前の定数に置き換え、背景も示します
エラーが握りつぶされる	except: pass パターン	続行する前にエラーをログに記録するか再送出します
実行時の型エラー	検証が不足している	境界で入力を検証します
設定が読み込まれない	パスがハードコードされている	デフォルト値を設定した環境変数を使用します

実行後の振り返り

このスキルの実行が完了したら、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった指示またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルをそれに合わせて更新します。
3. 回避策が必要でしたか？ — 即興で対処した場合（異なるフラグや追加の手順など）は、次回同じ回避策が不要になるように、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。