bp-python

Stars0

Forks0

UpdatedJuly 2, 2026 at 12:36

Python ベストプラクティス(eval/ 専用、Python 3.14 + uv + Pyrefly + Ruff)。モデル A/B・プロンプト評価スクリプトの規約と再現性の作法。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

Kaikei-e

Kaikei-e/moka-1

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	bp-python
description	Python ベストプラクティス(eval/ 専用、Python 3.14 + uv + Pyrefly + Ruff)。モデル A/B・プロンプト評価スクリプトの規約と再現性の作法。

Python Best Practices (eval/ のみ)

moka-1 の Python は eval/ の評価スクリプトに限定(ADR-0001)。本体機能(フィード取得・API・エージェントループ)を Python で書き始めたら設計違反 — その場で指摘して止まること。eval/ の役割は tenets §9 の類のタスク: モデル A/B、プロンプト比較、速度実測、品質採点。

ツールチェーン

uv で完結: uv add / uv run / uv lock。pip・手動 venv・conda 禁止。uv.lock はコミットする
単発スクリプトは PEP 723 インライン依存が便利:
```
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx", "pydantic>=2"]
# ///
```
uv run script.py だけで動く。共有基盤(採点・レポート生成)が育ったら通常の pyproject.toml パッケージに昇格
Pyrefly 必須: uv run pyrefly check . 通過必須。mypy / pyright は使わない(v1.0 安定版・Ruff 系より高速、ADR 済みの選定)
Ruff が一次ソース: uv run ruff format . + uv run ruff check .。ルールは E,W,F,B,UP,SIM,N,I,ANN,S,PTH,C4,ASYNC,TRY,RUF を select。手動スタイル議論禁止

コード規約

型ヒント必須: 使い捨てスクリプトでも関数は完全アノテーション。Any は境界最小限。Python 3.14 なので list[str] / X | None / PEP 695 type エイリアスを使う(typing.List / Optional は書かない)
例外は具体的に: 裸の except: / except Exception: 禁止。raise EvalError("scoring failed") from err で原因チェーン保持
Pydantic v2 で LLM 出力を受ける: llama.cpp の json_schema 出力は Model.model_validate_json() でパース。生 dict を引き回さない。スキーマは Pydantic モデルから model_json_schema() で生成してリクエストに渡す(スキーマと検証の一元化)
HTTP は httpx: llama.cpp server(localhost)へは httpx.Client を使い回す。タイムアウトは生成長に合わせ明示(timeout=httpx.Timeout(300, connect=5))。並列プローブは asyncio + httpx.AsyncClient、ただし -np スロット数を超える同時リクエストを投げない
資源管理は context manager: with / async with。裸 open() 禁止、パスは pathlib.Path

評価の作法(このスキルの本体)

</think> 除去を忘れない: LFM2.5 系は reasoning-only(tenets §9)。除去前のテキストで品質採点や長さ測定をすると測定が壊れる。CoT 長・CoT 込みレイテンシは別の測定項目として記録する
結果は自己記述的な JSONL: 1 行 = 1 試行。必ず含める: モデル名・量子化・llama.cpp バージョン・サンプリングパラメータ(temperature/top_k/repetition_penalty)・プロンプトの SHA-256・入力 ID・seed・レイテンシ(prefill/decode 分離)・出力。「後から何の実験だったか分かる」ことが正義
seed 固定 + 複数試行: 単発比較で結論しない。同一条件 n≥3、モデル間比較は同一入力セットで対にする(paired comparison)
速度測定は分離して報告: pp(プレフィル)と tg(デコード)を分ける(tenets §9 の形式に合わせる)。ウォームアップ 1 回を捨てる
品質採点に LLM を使う場合: 採点者モデルは被評価モデルと別系統にする(自己採点バイアス)。採点プロンプトも結果 JSONL にハッシュで記録
結論は draft / ADR に還流: eval/ の結果で意思決定したら、moka-adr-writer で ADR 化する。スクリプトと結果 JSONL のパスを ADR から参照

実行環境

ホスト上で直接実行: eval/ はコンテナ化しない(コンテナ数上限 5 に含めない)。llama.cpp server へは http://localhost:<port>
compose の llm を占有しない配慮: 長時間ベンチ中は moka-core の濃縮が遅れる(同一 iGPU)。実測系は明示的に「ベンチ中」であることをユーザーに伝えてから回す

参照

docs/tenets/moka-tenets.md — 本スキルの「tenets §N」参照はこの文書の節番号

More from this repository

same repository

bp-rust-wasm

Kaikei-e/moka-1

Rust ベストプラクティス(Plecto WASM フィルタ向け、Edition 2024)。plecto:filter WIT コントラクトを実装する WASM Component Model フィルタの規約とツールチェーン。

2026-07-210

grill-with-docs

Kaikei-e/moka-1

Grilling session that challenges your plan against moka-1's documented design decisions (tenets, ADRs) and domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against the project's language and documented decisions, or says 「設計を詰めて」「用語を固めて」「ドキュメントと突き合わせて」.

2026-07-030

clean-architecture

Kaikei-e/moka-1

クリーンアーキテクチャの依存ルールを moka-1 のミニマリズム制約下で適用する指針。レイヤ分割・interface 設計・依存方向の判断基準と、過剰抽象化を避けるガードレールを提供する。

2026-07-030

web-research

Kaikei-e/moka-1

Web調査の方法論。一次ソース(RFC・公式仕様・公式ドキュメント・原論文・ソースコード)を最優先し、検索クエリの多角化・横断的検証(lateral reading)・独立ソースでの三角測量を経て、出典付きで報告する手順。

2026-07-030

docker-compose

Kaikei-e/moka-1

moka-1 スタックの Docker Compose 操作と compose.yaml の書き方。ワンキック起動・開発ループ・ヘルスチェック・開発機(iGPU/Vulkan)固有設定・トラブルシュート。

2026-07-020

bp-go

Kaikei-e/moka-1

Go ベストプラクティス(moka-core 向け、Go 1.26+)。常駐エージェントループ・LLM クライアント・フィード取得を含む moka-core の実装規約。

2026-07-020

Python Best Practices (eval/ のみ)

ツールチェーン

uv で完結: uv add / uv run / uv lock。pip・手動 venv・conda 禁止。uv.lock はコミットする

単発スクリプトは PEP 723 インライン依存が便利:

# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx", "pydantic>=2"]
# ///

uv run script.py だけで動く。共有基盤(採点・レポート生成)が育ったら通常の pyproject.toml パッケージに昇格

Pyrefly 必須: uv run pyrefly check . 通過必須。mypy / pyright は使わない(v1.0 安定版・Ruff 系より高速、ADR 済みの選定)

Ruff が一次ソース: uv run ruff format . + uv run ruff check .。ルールは E,W,F,B,UP,SIM,N,I,ANN,S,PTH,C4,ASYNC,TRY,RUF を select。手動スタイル議論禁止

コード規約

型ヒント必須: 使い捨てスクリプトでも関数は完全アノテーション。Any は境界最小限。Python 3.14 なので list[str] / X | None / PEP 695 type エイリアスを使う(typing.List / Optional は書かない)

例外は具体的に: 裸の except: / except Exception: 禁止。raise EvalError("scoring failed") from err で原因チェーン保持

Pydantic v2 で LLM 出力を受ける: llama.cpp の json_schema 出力は Model.model_validate_json() でパース。生 dict を引き回さない。スキーマは Pydantic モデルから model_json_schema() で生成してリクエストに渡す(スキーマと検証の一元化)

HTTP は httpx: llama.cpp server(localhost)へは httpx.Client を使い回す。タイムアウトは生成長に合わせ明示(timeout=httpx.Timeout(300, connect=5))。並列プローブは asyncio + httpx.AsyncClient、ただし -np スロット数を超える同時リクエストを投げない

資源管理は context manager: with / async with。裸 open() 禁止、パスは pathlib.Path

評価の作法(このスキルの本体)

</think> 除去を忘れない: LFM2.5 系は reasoning-only(tenets §9)。除去前のテキストで品質採点や長さ測定をすると測定が壊れる。CoT 長・CoT 込みレイテンシは別の測定項目として記録する

結果は自己記述的な JSONL: 1 行 = 1 試行。必ず含める: モデル名・量子化・llama.cpp バージョン・サンプリングパラメータ(temperature/top_k/repetition_penalty)・プロンプトの SHA-256・入力 ID・seed・レイテンシ(prefill/decode 分離)・出力。「後から何の実験だったか分かる」ことが正義

seed 固定 + 複数試行: 単発比較で結論しない。同一条件 n≥3、モデル間比較は同一入力セットで対にする(paired comparison)

速度測定は分離して報告: pp(プレフィル)と tg(デコード)を分ける(tenets §9 の形式に合わせる)。ウォームアップ 1 回を捨てる

品質採点に LLM を使う場合: 採点者モデルは被評価モデルと別系統にする(自己採点バイアス)。採点プロンプトも結果 JSONL にハッシュで記録

結論は draft / ADR に還流: eval/ の結果で意思決定したら、moka-adr-writer で ADR 化する。スクリプトと結果 JSONL のパスを ADR から参照

実行環境

ホスト上で直接実行: eval/ はコンテナ化しない(コンテナ数上限 5 に含めない)。llama.cpp server へは http://localhost:<port>

compose の llm を占有しない配慮: 長時間ベンチ中は moka-core の濃縮が遅れる(同一 iGPU)。実測系は明示的に「ベンチ中」であることをユーザーに伝えてから回す

参照

docs/tenets/moka-tenets.md — 本スキルの「tenets §N」参照はこの文書の節番号