template-python 0.0.13 批判的レビューレポート

最新ノウハウ(2026年10月時点)に基づく修正事項と、新テンプレートの提案

1. エグゼクティブサマリー

1.1 総評

現行テンプレートは「SHA ピン留め」「uv --locked」「import-linter」「zizmor/actionlint」など良い素材を揃えている一方で、品質ゲートとしての正しさとサプライチェーン上の検証可能性に重大な欠陥があり、そのままプロダクションのひな形として配布するのは推奨できません。主な理由は次の 5 点です。

1. テストゲートが壊れている: ライブラリのロガーが propagate=False を設定しているため、pytest の caplog(root ロガーにハンドラを追加する方式)がログを受け取れず、tests/test_core.py の 3 テストは失敗します。同じ仕組みをオフラインで再現し、捕捉件数 0 件を確認しました(A-1)。
2. リリースが誤ったものを公開しうる: プレリリースタグ v1.2.3-rc.1 を push すると、安定版タグ 1.2.3 と latest が上書きされます(D-1)。テスト結果を待たずに公開し(D-2)、Docker Hub と GHCR を別々にビルドするため同一バージョンでもダイジェストが一致しません(D-3)。
3. 検証可能性(Provenance)が無い: Dockerfile は uv export --no-hashes → pip install でハッシュ検証を捨てています(C-1)。成果物の来歴証明(Artifact Attestations)、SBOM、イミュータブルリリースもありません(C-5)。
4. 「失敗を可視化する」という自らの原則に反している: Trivy は非ブロッキング、zizmor は --offline --min-severity high のため、オンライン監査と medium 以下の指摘(credential の残留、過剰権限など)を素通りさせます(C-2, C-3)。
5. GitHub プラットフォーム機能をほぼ使っていない: ルールセット、必須チェック、CodeQL、依存関係レビュー、シークレットスキャン、Environments、OIDC、Pages の Actions デプロイ、Copilot のリポジトリカスタマイズ(AGENTS.md、セットアップステップ、エージェント、スキル、フック)がありません(I-1, J-1 ほか)。

加えて、2026 年 10 月時点では Python 3.10 が EOL(2026-10-01)、Python 3.15 が GA(2026-10-09)、Actions ランナーから Node 20 が削除(2026-09-23)、MkDocs 1.x は保守停止・Material for MkDocs は保守モード(2027-05-05 まで)、ubuntu-latest が 26.04 へ移行開始(2026-10-19〜) という環境変化があり、テンプレートの前提そのものを更新する必要があります。

1.2 重大指摘(P0/P1 の上位 12 件)

1.3 観点別スコアカード

5 段階評価です(5 = プロダクション水準)。

2. レビューの範囲・方法・前提

2.1 対象

ワークフロー 6 本(test / docker / docker-release / ghcr-release / github-pages / azure-static-web-app)、dependabot.yaml、.pre-commit-config.yaml、.devcontainer/devcontainer.json、.vscode/extensions.json、Dockerfile、.dockerignore、compose.yml、Makefile、pyproject.toml、uv.lock、template_python/(4 モジュール)、scripts/template.py、tests/(3 モジュール)、docs/(4 ページ)、mkdocs.yml、notebooks/templates.ipynb、README.md、LICENSE、.gitignore、.env.template。

2.2 方法

• 精読: 全ファイルを 1 行ずつ確認しました。
• ロック解析: uv.lock を解析しました(144 パッケージ。うち 69 は notebook グループ専用で、Python バージョンによる分岐が 3 パッケージ)。
• 挙動の再現: サンドボックスにはネットワークがないため、pytest の caplog と同じ仕組み(root ロガーへのハンドラ追加)を標準ライブラリで再現し、現行の loggers.py / core.py で検証しました。
• 最新動向の調査: 2026-10-12 時点の一次情報を調べました(付録 B)。GitHub Actions は新旧テンプレートで使う 22 アクションについて、最新リリースとそのコミット SHA(40 桁)を照合しています。

2.3 重要度の定義

3. 修正が必要な事項の一覧

P0 が 3 件、P1 が 25 件、P2 が 36 件、P3 が 10 件、合計 74 件です。「対応先」は新テンプレート内のファイルです。詳細は第 4 章を参照してください。

A. テストと品質ゲート

B. CI 設計

C. サプライチェーン・セキュリティ

D. リリース / CD

E. コンテナ

F. Python パッケージとアプリ設計

G. 開発者体験

H. ドキュメント

I. GitHub ガバナンス

J. AI 駆動開発(GitHub Copilot)

4. 指摘事項の詳細

各項目は「現状 → 問題 → 修正方針 → 新テンプレートでの対応」の順に記載します。

4.A テストと品質ゲート

A-1 (P0) propagate=False で caplog が機能せず、テストが失敗する

現状

# template_python/loggers.py
logger.setLevel(log_level)
logger.propagate = False          # ← 親(root)へ伝播させない
if logger.handlers:
    return logger
handler = logging.StreamHandler()  # ← ライブラリが自前でハンドラを付ける

# tests/test_core.py
with caplog.at_level(logging.INFO, logger="template_python.core"):
    hello_world()
assert "Hello World" in caplog.text   # ← root に届かないので常に空

問題

• pytest の caplog は root ロガーにハンドラを追加して記録を集めます(pytest 公式ドキュメント「The caplog fixture adds a handler to the root logger」)。at_level(logger=...) はレベルを変えるだけです。非伝播ロガーにも対応する PR(logging: also capture logs from non-propagating loggers pytest-dev/pytest#14375)は 2026-09 時点で未マージであり、ロックされている pytest 9.1.1 には含まれていません。
• 同じ仕組みを標準ライブラリで再現すると、propagate = False、root 側の捕捉件数 0、"Hello World" in caplog.text → False になりました。test_hello_world_logs_message と parametrize された 2 ケースの計 3 件が失敗します。
• ノートブックの出力(2026-05-10)には root 経由の重複行が残っています。伝播を止める変更が後から入り、テストを壊した可能性が高いと考えられます。CI がこれを検出していないなら、ゲートが実際には実行されていないか、結果が見落とされています。

修正方針

• ライブラリは logging.getLogger(__name__) を使うだけにし、ハンドラ、伝播、レベルには一切触れません。
• ログの構成はアプリケーションの入口で 1 回だけ、冪等に行います。
• 「ライブラリのログが caplog に届くこと」を回帰テストで固定します。

新テンプレートでの対応

• src/template_python/logging_config.py:
  • configure_logging() は自分の名前付きハンドラだけを置き換え、caplog などのハンドラには触れません。
  • JSON Lines 出力に対応しています。
• tests/test_logging_config.py::test_library_records_reach_caplog(回帰テスト)。

A-2 (P1) テストが環境変数を汚染し、CWD に依存する

現状

test_settings.py は load_dotenv(dotenv_path=".env.template") を呼びます。これはプロセスの os.environ を書き換えるので、以降の全テストに PROJECT_NAME などが残ります。さらに、相対パスのため pytest を別ディレクトリから実行すると失敗します。アサーションの文言「Default project name should be 'template-python'」も誤りで、実際の既定値は default-project です。

問題

• テストの順序に依存する、再現しにくい不具合の温床になります。
• 開発者の .env や環境変数がテスト結果を変えてしまいます(非ハーメチック)。

修正方針・新テンプレート

• tests/conftest.py の autouse fixture で、TEMPLATE_PYTHON_* を削除し、tmp_path へ chdir し、テスト後に自前のハンドラを除去します。
• 設定のテストは monkeypatch.setenv と tmp_path / ".env" で行います。
• 優先順位(環境変数 > .env)、正規化、不正値、秘匿、不変性を個別に検証します(tests/test_config.py、7 件)。

A-3 (P1) CLI が無テストで、カバレッジ対象外

現状

--cov=template_python だけが計測対象で、scripts/template.py は計測もテストもされていません。そのため F-3(--verbose の不具合)や F-7(出力が無い)を検出できません。

修正方針・新テンプレート

CLI をパッケージ内(cli.py)に移し、typer.testing.CliRunner で E2E テストします。

• stdout/stderr の分離、--version、--verbose、不正入力時の終了コード 2、不正設定時の 78、--help が設定エラーの影響を受けないこと、秘匿表示を確認します。
• python -m template_python をサブプロセスで実行します。

A-4 (P2) 弱いアサーションと無意味な parametrize

hello_world() は値を返さず、5 レベルのログを出すだけです。テストは「Hello World という文字列がどこかにあるか」しか見ておらず、DEBUG/INFO の parametrize も結果を区別しません。未使用の setup_session fixture はデッドコードです。

新テンプレートでは、ドメインを純粋関数 build_greeting() にして入出力を検証します。不変条件(前後空白の除去、長さ制限)は Hypothesis のプロパティテストで確認します。

A-5 (P2) カバレッジ閾値なし・ブランチカバレッジ無効

[tool.coverage.report] は show_missing だけで、閾値もブランチ計測もありません。CI はカバレッジを報告も保存もしません。

新テンプレートの設定は次のとおりです。

• branch = true、fail_under = 90、exclude_also を設定します。
• 基準プラットフォーム(Ubuntu、3.14)でのみ計測し、Markdown 表を Job Summary に出力します。
• coverage.xml と junit.xml を artifact として保存します。

A-6 (P2) pytest 設定の不備

A-7 (P2) 型チェッカー 3 種の併用

現状

make lint は mypy strict、ty、pyrefly をすべて実行します。

問題

• 推論や診断の差異により、同じコードに 3 種の抑制コメント(# type: ignore、# ty: ignore、# pyrefly: ignore)が必要になります。
• 実行時間と更新コストが 3 倍になります。
• ty は 0.0.x(beta、診断の破壊的変更あり)で、ブロッキングゲートには不適です。

新テンプレート

• mypy 2.x strict + pydantic プラグインを唯一のブロッキングゲートにしました(ADR-0002)。
• エディタも同じ mypy(VS Code の mypy 拡張)を使い、Pylance の型検査はオフにして診断を一元化します。

A-8 (P2) Ruff のルール選択が最小限

現状

select = ["E","F","I","UP"] だけで、実際に以下を見逃しています。

• ロギングの f-string(G004)。
• subprocess、assert、秘密情報(S)。
• バグの温床(B)と pytest スタイル(PT)。

ignore = ["D203"] は D を選択していないため意味がありません。

新テンプレート

• 34 のルール群(A、ASYNC、B、BLE、C4、D(google)、DTZ、E、EM、F、FURB、G、I、ISC、LOG、N、PERF、PGH、PIE、PL、PT、PTH、RET、RSE、RUF、S、SIM、SLF、T10、T20、TID、TRY、UP、W)を明示的に選択しました。
• Ruff 0.16 で既定ルールが 59 から 413 に、0.17 で既定のターゲットが変わったため、明示選択でアップグレード時の揺れを防ぎます。

A-9 (P3) アーキテクチャ契約が弱い

現状

scripts(__init__.py の無い名前空間)→ template_python の 1 契約だけです。ライブラリ内部の層と外部フレームワークへの依存は無制約です。

新テンプレート

• layers 契約: cli → (config | logging_config) → domain。exhaustive = true で新規モジュールの層への分類を強制します。
• forbidden 契約: domain から typer、pydantic、pydantic_settings を禁止します(include_external_packages = true)。

4.B CI 設計

B-1 (P1) 二重起動・並行制御なし・マージキュー非対応

現状

test.yaml と docker.yaml は push(main / feature/** / copilot/**)と pull_request(main)の両方で起動します。

問題

• PR ブランチでは同じコミットに対して CI が 2 回走ります。
• concurrency が無いため、追加 push 時に古い実行がキャンセルされません。
• merge_group トリガーが無いので、マージキューを有効にすると必須チェックが永久に Pending になります。

新テンプレート

ci.yaml のトリガーは次のとおりです。

• pull_request(全ブランチ宛)
• push(main)
• merge_group
• workflow_dispatch
• workflow_call(リリースから再利用)

concurrency は PR の場合だけ進行中の実行をキャンセルします。

B-2 (P1) 必須チェックの集約ジョブが無い

行列ジョブ名(test (3.13) など)を必須チェックにすると、行列を変えるたびにブランチ保護が壊れます。新テンプレートは ci-success ジョブが全ジョブの結果を検査します(skipped は許容し、failure / cancelled は失敗)。ルールセットはこの 1 つだけを必須にします。

B-3 (P2) Python の二重セットアップ

setup-uv に python-version を渡したうえで actions/setup-python も実行しています(test / azure-static-web-app / github-pages)。新テンプレートは setup-uv だけを使い、Python は .python-version または行列値から uv が取得します。

B-4 (P2) 直列の巨大ジョブと重複実行

現状

make ci-test は format → mypy → import-linter → ruff → ty → pyrefly → actionlint → zizmor → pytest を 1 ジョブで直列に実行します。docs は test.yaml と github-pages.yaml で 2 回ビルドされ、ruff は hooks ジョブでも再実行されます。

新テンプレート

lint / workflows / test(行列)/ docs / package / container を並列ジョブに分けました。ステップ名で失敗箇所が分かり、Ruff は --output-format=github で PR に注釈を付けます。

B-5 (P2) 配布物を一度もビルドしない

wheel/sdist の破損(パッケージデータの欠落、エントリポイントの誤り)は利用者側で初めて発覚します。新テンプレートは package ジョブで uv build --no-sources を実行し、uv run --isolated --no-project --with dist/*.whl template-python --version でインストール済みの状態をスモークテストします。

B-6 (P2) Python 行列が時代遅れ

現状

3.10〜3.14 を対象にしています。3.10 は 2026-10-01 に EOL で、3.15.0 は 2026-10-09 に GA です。Windows/macOS の検証もありません。

新テンプレート

• Ubuntu で 3.12 / 3.13 / 3.14 / 3.15 をブロッキングで実行します(3.15 は pydantic 2.14 が対応済み)。
• Windows 2025 と macOS 26 で 3.14 を実行します。
• フリースレッドの 3.14t は早期警告用で、非ブロッキングです。
• テスト行列は --no-default-groups --group test で最小限の依存だけを入れ、新しい Python で開発ツールのホイール欠如に巻き込まれないようにしています。

B-7 (P2) ubuntu-latest の暗黙移行

GitHub は 2026-10-19〜11-19 に ubuntu-latest を 26.04 へ段階移行します。新テンプレートは ubuntu-24.04 / ubuntu-24.04-arm / windows-2025 / macos-26 を明示し、移行は計画的に行います。

B-8 (P2) uv バージョンが 6 か所に散在

devcontainer、ワークフロー 4 本、Dockerfile、README に 0.12.19 が書かれています。新テンプレートは pyproject.toml の [tool.uv] required-version = ">=0.13.0,<0.14" を唯一の定義とし、setup-uv はこれを自動で読みます。Dockerfile と devcontainer の uv イメージタグは Dependabot(docker)の更新対象です。

B-9 (P2) actionlint の取得と検証

現状

gh release download で取得したバイナリを、同じリリースの checksums.txt で照合しています。リリース自体が改ざんされた場合は検出できません。ローカルでは別途インストールが必要で、CI とバージョンがずれます。

新テンプレート

actionlint-py(1.7.12.x)を lint 依存グループに加え、uv.lock のハッシュで固定しました。ローカル(make workflows、pre-commit)と CI で同じバイナリを使います。

B-10 (P3) timeout と権限の粒度

github-pages.yaml にタイムアウトがありません。権限はワークフローレベルだけです。新テンプレートは全ジョブに timeout-minutes と permissions を明示し、ワークフローレベルは permissions: {} にしました。

4.C サプライチェーン・セキュリティ

C-1 (P0) ハッシュ検証を捨てたコンテナビルド

現状

RUN uv export --locked --format requirements-txt --no-dev --no-hashes ... --output-file requirements.txt
...
RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

問題

• uv.lock が持つ配布物ハッシュを --no-hashes で捨てています。インデックスやミラーの改ざん、依存関係混乱(dependency confusion)を検出できません。
• --upgrade の意図も不明確です。

新テンプレート

uv 公式 Docker ガイドの方式に従います。

• uv sync --locked --no-install-project --no-editable で依存だけの層をキャッシュし、続けてプロジェクトを非 editable でインストールします。uv はロックのハッシュを検証します。
• UV_COMPILE_BYTECODE=1、UV_LINK_MODE=copy、UV_NO_DEV=1、UV_PYTHON_DOWNLOADS=0 を設定します。
• BuildKit のキャッシュマウントとバインドマウントを使います。

C-2 (P1) zizmor がオフラインかつ high 以上のみ

現状

zizmor --offline --strict-collection --min-severity high . で実行しています。

問題

• オフラインでは impostor-commit(フォーク由来の偽 SHA)、ref-confusion、known-vulnerable-actions が無効です。
• medium 以下の artipacked(認証情報の残留)、excessive-permissions、cache-poisoning などを全て見逃します。実際に github-pages.yaml は contents: write のトークンを checkout に残しています(C-9)。

新テンプレート

• CI では GH_TOKEN を渡してオンライン監査を有効にし、--format=github --min-severity=low で実行します。
• .github/zizmor.yml で全 uses: にハッシュピンを要求します。
• pre-commit でもオフライン版を実行します。
• 全ワークフローをこの基準に合わせて設計しました(run: 内での ${{ }} 展開なし、リリース系ジョブのキャッシュ無効化など)。

C-3 (P1) Trivy が非ブロッキング

現状

aquasec/trivy:0.74.0 image ... は --exit-code が無いため、常に成功します。README は「review its findings before enabling a blocking severity threshold」と自ら認めており、アーキテクチャ文書の原則 8「Surface failures」と矛盾します。

問題

• 修正版があるのに放置された HIGH/CRITICAL の脆弱性を含むイメージを公開できてしまいます。
• Trivy は 2026-03-19 に、公式リリース v0.69.4、trivy-action の 76 タグ、setup-trivy の全タグが改ざんされるサプライチェーン侵害を受けました(GHSA-69fq-xp46-6x23 / CVE-2026-33634)。2026-03-22 には Docker Hub の 0.69.5 / 0.69.6 も改ざんされています。スキャナ自身の取得経路を固定する設計が必須です。

新テンプレート

• aquasecurity/trivy-action をコミット SHA で固定し(v0.36.0、侵害後のリリース)、スキャナ本体も version: v0.75.0 で明示しました。
• ignore-unfixed: true、severity: CRITICAL,HIGH、exit-code: "1" で、修正版がある重大脆弱性をブロックします。
• hadolint はバイナリを sha256 照合したうえで実行します。

C-4 (P1) 標準的なセキュリティ機能の欠落

C-5 (P1) 来歴証明・SBOM・イミュータブルリリースが無い

問題

利用者は「このイメージやホイールが、このリポジトリのこのワークフローでビルドされた」ことを検証できません。リリース後のタグ付け替えや資産の差し替えも可能です。

新テンプレート

• wheel/sdist とイメージに actions/attest v4 で SLSA build provenance を付与します。attest-build-provenance は v4 から actions/attest のラッパーになり、attest-sbom は非推奨です。
• イメージには BuildKit の provenance: mode=max と sbom: true も付けます(private リポジトリでは既定が min なので明示)。
• GitHub Release を gh release create で作成します(draft → 資産アップロード → 公開)。イミュータブルリリース(2025-10-28 GA)と互換で、設定スクリプトで有効化します。
• 検証手順(gh attestation verify、gh release verify / verify-asset)を SECURITY.md に記載しました。
• Free/Pro/Team の private リポジトリでは Attestations を使えないため、ATTESTATIONS 変数でガードし、失敗させずに運用できるようにしています。

C-6 (P1) 長期資格情報の広範な露出

現状

DOCKERHUB_TOKEN(PAT)と AZURE_STATIC_WEB_APPS_API_TOKEN(長期デプロイトークン)をリポジトリシークレットとして保持し、Environment による保護(承認、タグ限定)がありません。同一リポジトリの任意ブランチのワークフローから参照できます。

新テンプレート

• GHCR へは GITHUB_TOKEN で push します(長期資格情報なし)。
• Docker Hub は任意のミラーで、dockerhub Environment に限定したシークレットを使い、同一ダイジェストをコピーするだけです。
• Azure SWA は azure/login の OIDC で一時的にログインし、実行時にデプロイトークンを取得します。GitHub には保存しません。
• PyPI は Trusted Publishing(OIDC、pypi Environment は v* タグのみ)で、PEP 740 attestations が自動付与されます。

C-7 (P2) Dependabot の設定不足

現状

グループ化が無く、毎週エコシステムごとに個別 PR が大量に作られます。cooldown は uv だけで、Actions、Docker、pre-commit は公開直後の版を即座に提案します。devcontainers は対象外です。

新テンプレート

• uv、github-actions、docker(/ と /.devcontainer)、devcontainers、pre-commit(2026-03-10 対応)の全エコシステムに cooldown.default-days: 7 を設定しました。
• グループ化、ラベル、Conventional Commits 風の接頭辞を付けます。
• uv は groups.dependency-type 非対応のため、update-types でグループ化します。
• zizmor の dependabot-cooldown 監査にも適合します。

C-8 / C-9 (P2) 過剰権限と認証情報の残留

ghcr-release.yaml はワークフロー全体に packages: write を付与し、github-pages.yaml は contents: write で、checkout の persist-credentials も既定(true)のままです。新テンプレートはワークフローレベルを permissions: {} とし、ジョブ単位で最小権限を付与し、全 checkout で persist-credentials: false にしています。リポジトリ設定でも GITHUB_TOKEN の既定を read にします。

C-10 (P2) 第三者のアクセス解析 ID がテンプレートに残っている

mkdocs.yml の extra.analytics.property: G-0ZTKFXVQ5K は原作者の Google Analytics です。テンプレートから生成したすべてのドキュメントサイトの閲覧データが第三者に送られます。Cookie 同意やプライバシーポリシー上も問題です。新テンプレートには解析設定を含めません。

C-11 (P2) 設定全量のログ出力と秘匿化の欠如

logger.info(f"Settings from .env: {get_project_settings().model_dump_json(indent=2)}") は、将来 API キーなどを設定に追加した瞬間に秘密をログへ出力します。新テンプレートは秘密を SecretStr で受け、config コマンドは秘匿済み JSON だけを出力します(********** をテストで保証)。Typer は 0.23 からトレースバックにローカル変数を表示しないのが既定になったため、依存の下限を typer>=0.27 にしてこの挙動を担保しています。

4.D リリース / CD

D-1 (P0) プレリリースが安定版タグと latest を上書きする

現状

// docker-release.yaml / ghcr-release.yaml(Set Versions ステップ)
const tag = context.ref.substring(10)              // "v1.2.3-rc.1"
const no_v = tag.replace('v', '')                  // "1.2.3-rc.1"
const dash_index = no_v.lastIndexOf('-')
const no_dash = (dash_index > -1) ? no_v.substring(0, dash_index) : no_v   // "1.2.3"

tags: |
  ${{ secrets.DOCKERHUB_USERNAME }}/template-python:${{steps.set_version.outputs.no-dash}}  # :1.2.3
  ${{ secrets.DOCKERHUB_USERNAME }}/template-python:latest                                 # :latest

問題

RC/beta を試験公開しただけで、安定版 1.2.3 と latest が RC の中身に置き換わります。GHCR 側も type=semver,value=v<no-dash> と type=raw,value=latest を使っているので同じです。

新テンプレート

• バージョンを PEP 440(例: v1.3.0rc1)で統一します。
• docker/metadata-action を type=pep440,pattern={{version}} / {{major}}.{{minor}} と flavor: latest=auto で使います。プレリリースは {{version}} だけを生成し、latest を付けません。
• type=ref,event=tag(プレリリースにも latest を付ける)は使いません。
• GitHub Release もプレリリースとして作成します。

D-2 (P1) テストを経ずに公開する

タグ push を契機にした公開ワークフローに needs もゲートもありません。アーキテクチャ文書自身が「release workflows are delivery mechanisms, not substitutes for the test workflow」と書きながら、両者がつながっていません。新テンプレートの release.yaml は、verify(タグ = uv version --short)→ ci(ci.yaml を workflow_call で再利用)の成功後にだけビルドと公開を行います。

D-3 (P1) レジストリごとに別ビルドしている

問題

Docker Hub 向けと GHCR 向けを別ワークフローでビルドしています。タイムスタンプやベースイメージの更新により、同じ 1.2.3 でもダイジェストが異なるイメージが 2 つ存在することになります。来歴の検証やインシデント時の追跡ができません。

新テンプレート

1. amd64/arm64 をネイティブランナーでビルドし、ダイジェストだけで push します。
2. docker buildx imagetools create でマルチアーキのインデックスとタグを作成します。
3. インデックスのダイジェストに attestation を付与します。
4. Docker Hub は同じダイジェストをコピーするだけです(任意)。

D-4 (P1) バージョンの乖離と未使用のビルド引数

pyproject.toml は version = "0.0.1" のままですが、Git タグは v0.0.13 です。Dockerfile は ARG GIT_REVISION / GIT_TAG を宣言しているのに一切使っていません(ラベルにも環境変数にもならない)。新テンプレートは uv version --bump で版を管理し、タグとの一致をリリース時に強制します。OCI ラベル(source、revision、version、created)は metadata-action で付与します。

D-5 (P1) GitHub Release とリリースノートが無い

コンテナを push するだけで、変更点・成果物・検証手段が利用者に提供されません。新テンプレートは gh release create <tag> dist/* --verify-tag --generate-notes を実行し、イメージのダイジェストをノートに追記します。.github/release.yml のカテゴリ(Breaking / Features / Bug fixes / Security / Docs / Dependencies)で自動生成ノートを整理し、設定スクリプトがラベルを作成します。

D-6 (P2) エミュレーション前提のマルチアーキテクチャ

platforms: linux/amd64,linux/arm64 を指定していますが、setup-qemu-action がありません。GitHub ホストランナーの arm64 は 2026-01-29 から private リポジトリでも標準ランナーとして利用でき、エミュレーションより高速です。新テンプレートは ubuntu-24.04-arm でネイティブにビルドします。

D-7 (P2) 旧方式の Pages デプロイ

mkdocs gh-deploy --force は gh-pages ブランチへ force push する旧方式で、contents: write が必要です。並行制御も環境保護もありません。新テンプレートは actions/configure-pages → upload-pages-artifact → deploy-pages と github-pages 環境を使い、concurrency: pages を設定しています。Pages が有効なとき(has_pages)だけ実行するので、新規リポジトリで赤くなりません。

D-8 / D-9 (P2/P3) SWA ワークフローの不備と非 strict ビルド

単一値の matrix、Python の二重セットアップ、長期トークン(C-6)、strict でない docs ビルドがあります。新テンプレートは任意実行の docs-azure-swa.yaml(OIDC)と zensical build --strict に置き換えました。

4.E コンテナ

E-1 (P1) root 実行

USER 命令が無く、コンテナは root で動作します。新テンプレートでは次のようにしました。

• 数値 UID/GID 10001 の専用ユーザーで実行します(hadolint DL3066 にも適合)。
• venv は root 所有で、アプリから書き換えられません。
• compose では read_only、cap_drop: [ALL]、no-new-privileges を既定にしています。

E-2 (P1) コンテキスト全体の同梱と非インストール実行

COPY . . で docs、notebooks、Makefile、scripts などを同梱し、ソースツリーを作業ディレクトリから直接 import して実行しています。新テンプレートは builder ステージでプロジェクトを非 editable の wheel として venv にインストールし、ランタイムには /app/.venv だけをコピーします(ソースもツールも入りません)。

E-3 (P2) 流用された .dockerignore

• node_modules、bower_components、*.test.js など JavaScript 向けのパターンを含みます。
• .DS_Store # macOS-specific はインラインコメントが使えないため無効なパターンです。
• docker-compose.yml を除外していますが、実ファイルは compose.yml です。

新テンプレートは * で全除外し、必要なもの(pyproject.toml、uv.lock、README.md、LICENSE、src)だけを許可する方式にしました。Dockerfile 先頭の # check=error=true により、CopyIgnoredFile などの BuildKit ビルドチェック違反はビルドエラーになります。

E-4 (P2) 旧ベースイメージ

Debian 12 bookworm は 2026-07-11 に通常サポートを終え、LTS のみになっています。新テンプレートは python:3.14-slim-trixie(Debian 13)を使います。python:3.15-slim-trixie は 2026-10-12 時点で RC タグしか公開されていないため、コンテナの既定は 3.14 にしました。

ダイジェストの固定は推奨ですが、本成果物の作成環境では公開ダイジェストを検証できなかったため、タグで固定し Dependabot(docker)で更新する構成にしています。導入時に docker buildx imagetools inspect でダイジェストを付与する手順を 6 章に記載しました。

E-5 (P2) 危険な compose の例

command: ["python", "-m", "http.server", "8000"] は、/app(ソースコード)を 0.0.0.0:8000 で配信します。env_file: .env は必須扱いなので、.env の無い新規クローンでは起動に失敗します。container_name を固定しているためスケールもできません。新テンプレートの compose.yaml は CLI を実行するだけの最小例で、env_file は required: false です。

E-6 / E-7 (P3) OCI ラベルの欠如と GIT_TAG のバグ

org.opencontainers.image.source が無いと、GHCR のパッケージとリポジトリが自動で紐付きません。Makefile の sed -e s/v//g は v1.0.0-dev を 1.0.0-de に壊します。いずれも新テンプレートで解消しました。

4.F Python パッケージとアプリ設計

F-1 (P1) ライブラリがログ構成を所有している

get_logger() は呼び出しのたびにレベルを上書きし、StreamHandler を追加し、伝播を止めます。ライブラリとして組み込まれた場合、アプリケーション側の logging.config.dictConfig やログ基盤への転送(OpenTelemetry など)が効かず、出力の重複や欠落も起きます。Python 公式の Logging HOWTO が推奨するとおり、ライブラリはハンドラを構成しないことが原則です。

新テンプレートでは次のように分担します。

• ライブラリ: logging.getLogger(__name__) だけを使います。
• アプリ: cli.py から configure_logging(level, json_format=...) を 1 回呼びます。
  • テキストまたは JSON Lines で、出力先は stderr です。
  • extra= のフィールドと例外も JSON 化します。
  • 何度呼んでも安全です。

F-2 (P1) import 時の副作用

各モジュールが import 時に get_logger(__name__) を通じて get_project_settings() を呼び、lru_cache に保存します。設定は最初に import された時点の環境で固定されます。後から行う load_dotenv() や環境変数の変更は反映されず、テストの実行順にも依存します。

新テンプレートでは、Settings() は CLI のコマンド実行時(_runtime())にだけ生成されます。--help は不正な設定の影響を受けません。

F-3 (P1) --verbose が機能しない

コールバックは logging.basicConfig(level=DEBUG) と、__main__ ロガーのレベル変更しか行いません。template_python.core のロガーは import 時に INFO に固定されているため、ライブラリの DEBUG ログは出ません。さらに basicConfig が root にハンドラを追加するため、出力が二重になる状態も生じます(ノートブックの出力で両方を確認できます)。

新テンプレートでは、--verbose が root を DEBUG にします。test_verbose_flag_enables_debug_logs_on_stderr で保証しています。

F-4 (P1) .env が実環境変数を上書きする

load_dotenv(override=True) は、コンテナや Kubernetes の Secret などで実際に設定された環境変数を .env の値で上書きします。12-factor の優先順位が逆転し、作業ディレクトリに残った .env が本番設定を乗っ取る事故につながります。そもそも pydantic-settings が .env を読むので、python-dotenv の直接利用は不要です。

新テンプレートでは pydantic-settings の既定(環境変数 > .env)だけを使い、テスト(test_environment_variables_override_dotenv)で保証しています。

F-5 (P2) CLI を配布・インストールできない

flat layout で scripts/ はパッケージに含まれず、python scripts/template.py で起動するしかありません。新テンプレートは src layout にし、[project.scripts] template-python = "template_python.cli:app"、__main__.py(python -m template_python)、py.typed を備えます。

F-6 (P2) 弱い設定モデル

現状

• project_log_level: str は任意の文字列を受け入れ、不正値は logging の実行時例外になります。
• 接頭辞が無く、PROJECT_NAME のような汎用名は他ツールと衝突しやすいです。
• 秘密情報の型(SecretStr)がありません。
• python-dotenv を直接依存に持っています。

新テンプレート

• Literal 型(LOG_LEVEL / LOG_FORMAT / ENVIRONMENT)に大小文字の正規化を組み合わせました。
• TEMPLATE_PYTHON_ 接頭辞を付けます(初期化スクリプトで新名称に置換されます)。
• frozen=True、SecretStr、min_length を設定しました。

F-7 (P2) 出力と終了コードの設計

hello --name は name を使わず、stdout に何も出しません(ログだけ)。そのため、シェルスクリプトから結果を受け取れず、テストもできません。

新テンプレートでは次のように整理しました。

• 結果は stdout(typer.echo)、診断は stderr(ログ)に出します。
• 入力エラーは typer.BadParameter(終了コード 2)、設定エラーは 78(sysexits の EX_CONFIG)にします。
• ドメインの例外を CLI 層で変換します。

F-8〜F-11 (P2/P3) その他

• F-8: f-string のログは、レベルで捨てられる場合でも文字列を生成します。構造化もできません。新テンプレートは % 形式の引数と JSON フォーマッタを使います。
• F-9: build-system.requires = ["hatchling"] は無制約で、ビルドの再現性がありません。新テンプレートは uv_build>=0.13.0,<0.14 と PEP 639 の license = "MIT" / license-files を使い、classifiers と urls を追加しました。
• F-10: requires-python >=3.10 は EOL の版を含みます。新テンプレートは >=3.12 で、PEP 695 構文や typing.override を使えます。既定は 3.14 です。
• F-11: Docker の CMD ["python", "-m", "template_python.core"] はデモ用の __main__ ブロックです。新テンプレートは ENTRYPOINT ["template-python"] と CMD ["--help"] にしました。

4.G 開発者体験

G-1 (P1) devcontainer の dev- タグ

mcr.microsoft.com/devcontainers/python:dev-3.13-bookworm の dev- は、devcontainers/images の公式説明では main ブランチから生成される実験的な開発イメージで、インプレース更新されます。チームメンバーごとに環境が変わる恐れがあります。uv も毎回 pipx install しています。

新テンプレートの構成は次のとおりです。

• .devcontainer/Dockerfile: mcr.microsoft.com/devcontainers/python:3-3.14-trixie に、CI・本番と同じ ghcr.io/astral-sh/uv:0.13.0 から uv をコピーします。
• features: github-cli と docker-in-docker(コンテナ関連の make ターゲット用)を入れます。
• hostRequirements を指定します。
• updateContentCommand で依存を入れます(Codespaces の prebuild 対象)。
• postCreateCommand で git フックを入れます。

G-2 (P1) テンプレート固有名の散在と初期化手段の欠如

ks6088ts(Makefile の DOCKER_REPO_NAME、mkdocs、README のバッジ、LICENSE)と template-python / template_python が各所に埋め込まれており、置換手順もツールもありません。

新テンプレートでは 2 つの手段を用意しました。

• scripts/init_project.py(標準ライブラリのみ、PEP 723 メタデータ付き)が、配布名、パッケージ名、環境変数の接頭辞、オーナー、説明を一括置換し、パッケージディレクトリを改名し、uv.lock を削除します。名前の検証(キーワードや標準ライブラリとの衝突)とドライランも備え、テストがあります。
• initialize.yaml が、初回 push 時の uv.lock 生成と、任意の改名(workflow_dispatch の入力)を GitHub 上で自動化します。

G-3 (P2) docs 用の同期が開発環境を壊す

make install-deps-docs は uv sync --locked --no-dev --group docs です。uv sync は exact モードのため、dev グループ(prek を含む)を venv から削除します。その結果、インストール済みの git フックが実行ファイルを見失い、コミットが失敗します。新テンプレートは docs を uv run --only-group docs(inexact)で実行し、CI では専用ジョブに分けています。

G-4 (P2) フックと CI のバージョンのドリフト

ruff-pre-commit の rev: v0.16.9 と uv.lock の ruff は別々に更新されます。uv.lock の整合チェックはなく、exclude: "generated/.*|artifacts/.*" は存在しないディレクトリを指しています。

新テンプレートでは次のようにしました。

• 汎用フック(pre-commit-hooks。prek がネイティブ実行)はそのまま使います。
• ruff、actionlint、zizmor は language: system + uv run --frozen で uv.lock の版を使います。
• uv lock --check フックを追加しました。

G-5 (P2) エディタ設定の不一致

.vscode/extensions.json は pyrefly を、devcontainer は ruff と Copilot Chat を推奨しており、一致していません。Pylance と pyrefly の併用で診断も重複します。新テンプレートは両者を統一し(Ruff、mypy、Python、Copilot Chat、GitHub Actions、TOML)、保存時の整形と import 整理を設定しました。

G-6 (P3) ノートブックの実行結果をコミットしている

ANSI エスケープ、実行日時、相対パス(../scripts/template.py)に依存した出力がコミットされており、テストもされていません。新テンプレートでは削除しました。必要な場合は nbstripout 系のフックと一緒に追加してください。

4.H ドキュメント

H-1 (P1) ドキュメント基盤の保守終了

2026-10 時点の状況

新テンプレート

• Material チームの後継である Zensical を zensical.toml で採用しました(ADR-0003)。
  • mkdocs.yml 互換で、--strict を備えます。
  • 0.0.69 は alpha です。2026-11-05 から 0.1.0 系が安定版の位置付けになる予定で、バージョンは uv.lock で固定されます。
• Zensical はまだ i18n に対応していないため、英語(docs/)と日本語(docs/ja/)を 1 サイトの別ナビゲーションとして公開します。
• アーキテクチャ判断は ADR(docs/adr/)として記録します。

H-2〜H-4 (P2/P3)

現状の問題

• README には「Git hooks and deployment workflows are unchanged, and this does not add a pre-deployment gate.」のような PR 説明文の残骸があります。
• import-linter の説明が README、docs/index、architecture(英日)の計 4 か所に重複しています。
• 「structured logging」と書かれていますが、実装はテキストです。
• 原則「Surface failures」に反してスキャンが非ブロッキングです。
• site_url(ks6088ts-labs)と repo_url(ks6088ts)のオーナーが不一致です。

新テンプレート

ページの責務を分けました(Getting started / Development / Architecture / CI/CD / Security / Releasing / AI / Repository settings)。記述は実装と一致させ、URL はプレースホルダー(your-github-org)にして初期化スクリプトで置換します。

4.I GitHub ガバナンス

I-1 (P1) ルールセット・必須チェック・タグ保護が無い

GitHub のテンプレートリポジトリはファイルしか複製しないため、ブランチ保護などの設定はテンプレートに含められません。現行テンプレートには設定を再現する手段がなく、ゲートを迂回して main へ直接 push したり、任意のユーザーがリリースタグを作成したりできます。

新テンプレートは次の 3 つのルールセット JSON(UI からのインポートにも対応)を同梱し、scripts/configure_repository.py --apply で作成または更新します。

I-2 (P1) リポジトリ設定のコード化

configure_repository.py は既定でドライランです。各手順は独立しており、プランや可視性の制約で失敗した手順は警告として扱います。テスト付きで、主に次を設定します。

• Actions の既定トークンを read にし、Actions による PR 承認を禁止し、SHA ピン必須ポリシー(sha_pinning_required、2025-08 導入)を有効にします。
• squash のみでマージし、auto-merge を許可し、マージ後にブランチを削除します。
• Dependabot アラートとセキュリティ更新、シークレットスキャンとプッシュ保護、PVR、CodeQL default setup(extended)を有効にします。
• イミュータブルリリースを有効にします。
• Pages(Actions ソース)を有効にします。
• pypi Environment を作成し、v* タグからのみデプロイできるようにします。
• リリースノート用のラベルを作成します。

I-3 / I-4 (P2/P3) コミュニティ健全性ファイル

新テンプレートには次を同梱しました: SECURITY.md(非公開報告と検証手順)、CONTRIBUTING.md、CODE_OF_CONDUCT.md(Contributor Covenant 2.1 への参照)、Issue Forms(バグ報告と機能要望、ブランク Issue の無効化、セキュリティ報告への誘導)、PR テンプレート、CODEOWNERS。LICENSE はプレースホルダー化し、初期化スクリプトで置換します。

4.J AI 駆動開発(GitHub Copilot)

J-1 (P1) Copilot 用の構成が無い

test.yaml は copilot/** ブランチを CI 対象にしており、Copilot cloud agent(旧 coding agent。2026-04 に名称変更)の利用を想定しています。にもかかわらず、エージェント向けの指示も実行環境の定義もありません。エージェントは毎回、uv の導入方法や品質ゲートを推測することになり、規約違反の PR や CI の失敗を繰り返します。

新テンプレート(2026-10 時点の仕様に準拠)の構成は次のとおりです。

エージェント用のシークレットは「Settings → Secrets and variables → Agents」で管理します(2026-05-08 に copilot 環境から移行)。

J-2 (P2) ガードレールと再利用可能な手順

プロンプトファイル(.prompt.md)は VS Code で非推奨になったため、スキルで実装しています。

J-3 (P3) コードレビューの自動依頼

copilot_code_review ルール(review_on_push)を任意のルールセットとして同梱しました。設定スクリプトの --copilot-review オプションで適用できます。

GitHub Agentic Workflows(gh-aw、2026-06 からパブリックプレビュー)は、コンパイル済みの .lock.yml のコミットが必須です。そのため本テンプレートには同梱せず、導入手順(gh aw add githubnext/agentics/ci-doctor)だけをドキュメントに記載しています。