feat: Claude Code向けCLAUDE.mdとskillsを生成

.claude/skills/adr-management/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: adr-management
+description: 設計判断（アーキテクチャ、運用ルール、依存方針など）の採否を ADR として記録・更新し、変更理由を追跡可能にするためのPlaybook。方針の新規決定、方針変更、既存判断の置換が発生したときに使う。
+---
+
+<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
+<!-- source: docs/ai/canonical/playbooks/adr-management.md + scripts/sync_ai_context.py -->
+
+# ADR管理
+
+設計判断を文章化し、後から採否理由を追跡できる状態を維持する。
+
+## 実行手順
+
+1. 判断対象を明確化する。
+- 対象となる方針（例: アーキテクチャ、ツール選定、運用ルール）を 1 つに絞る。
+- 影響範囲（コード、CI、運用、ドキュメント）を整理する。
+
+2. 既存 ADR を確認する。
+- `docs/adr/README.md` の一覧を確認し、重複や置換関係がないかを調べる。
+- 既存判断を置換する場合は、旧ADRのステータスを `置換済み(superseded)` に更新する。
+
+3. ADR を作成または更新する。
+- 新規作成時は `docs/ai/playbook-assets/adr-management/references/_adr-template.md` を使用する。
+- 保存先は `docs/adr/`、ファイル名は `NNNN-short-title.md`（4桁連番 + kebab-case）を使う。
+- 本文には「文脈」「決定」「代替案」「影響」「フォローアップ」を必ず記載する。
+
+4. 関連ドキュメントを同期する。
+- 方針変更が `AGENTS.md` / Playbook / README / CI 設定へ影響する場合は同一タスクで更新する。
+- 変更理由が追跡できるように、関連ファイルから ADR への参照を追加する。
+
+5. レビュー観点を明示する。
+- トレードオフが比較可能か。
+- 非採用案の却下理由が具体的か。
+- 追加コスト（移行、教育、運用）を説明しているか。
+
+6. 結果を報告する。
+- 追加/更新した ADR ファイル。
+- 置換した ADR（ある場合）。
+- 同時に更新した実装・ドキュメントファイル。
+
+## 運用ルール
+
+- 重要な設計判断は、口頭・チャットだけで完結させず ADR に残す。
+- 1ADR に複数の無関係な判断を混在させない。
+- ステータスは `提案(proposed)` / `承認済み(accepted)` / `却下(rejected)` / `置換済み(superseded)` を使用する。
+- 置換関係がある場合は、新旧 ADR の双方に相互リンクを張る。
+
+## 参照ファイル
+
+- ADRテンプレート: `docs/ai/playbook-assets/adr-management/references/_adr-template.md`
+- ADR一覧: `docs/adr/README.md`

.claude/skills/api-spec-sync/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: api-spec-sync
+description: REST/HTTP APIの定義書（index + 1エンドポイント1ファイル）を新規作成・更新し、実装差分と常時同期させるためのPlaybook。API実装の追加・変更・削除、認証仕様変更、エラー形式変更、入出力スキーマ変更が発生したときに使う。
+---
+
+<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
+<!-- source: docs/ai/canonical/playbooks/api-spec-sync.md + scripts/sync_ai_context.py -->
+
+# API定義書同期
+
+API実装の変更とAPIドキュメント更新を同一タスクで完結させる。
+
+## 実行手順
+
+1. 実装差分から影響エンドポイントを特定する。
+- ルーター・ハンドラー・コントローラー・DTO/Schema・OpenAPI定義の差分を確認する。
+- 追加/変更/削除をエンドポイント単位に整理する。
+
+2. 一覧ドキュメントを更新する。
+- `docs/ai/playbook-assets/api-spec-sync/references/_index_template.md` を読み、`index.md` の共通仕様とエンドポイント一覧を更新する。
+- 新規エンドポイント追加時は、必ず一覧リンクを追加する。
+- 廃止エンドポイントは一覧から削除し、必要に応じて「非推奨 / 廃止」に移す。
+
+3. エンドポイント詳細ドキュメントを更新する。
+- `docs/ai/playbook-assets/api-spec-sync/references/_endpoint_template.md` を読み、対象エンドポイントの詳細ファイルを作成/更新する。
+- 命名は `<resource>-<method>.md` を基本とし、必要ならプロジェクト規約に合わせる。
+- 1エンドポイント1ファイルを厳守する。
+
+4. 実装と仕様を突合する。
+- HTTPメソッド、パス、認証、パラメータ、リクエスト/レスポンススキーマ、ステータスコード、エラーを確認する。
+- 実装で確認できない項目は推測しない。`TODO(要実装確認)` として明示する。
+
+5. 同期ゲートを通す。
+- `docs/ai/playbook-assets/api-spec-sync/references/sync-checklist.md` のチェックを上から順に実施する。
+- 必要なら `python3 scripts/playbooks/api-spec-sync/check_api_docs_sync.py --docs-root <APIドキュメントルート>` を実行する。
+- API実装が変わっているのにドキュメント差分がない場合、タスク完了にしない。
+
+6. 変更結果を報告する。
+- 更新した一覧ファイルと詳細ファイルを明示する。
+- 実装側の関連ファイルと未解決TODOを明示する。
+
+## 厳守ルール
+
+- API実装変更とAPIドキュメント更新を分離しない。
+- 共通仕様（認証、エラーフォーマット、ベースURL）変更時は `index.md` を必ず更新する。
+- エンドポイント仕様変更時は該当詳細ファイルを必ず更新する。
+- 差分が大きい場合でも、最小限の追記で済ませず仕様全体の整合を優先する。
+
+## 参照ファイル
+
+- 一覧テンプレート: `docs/ai/playbook-assets/api-spec-sync/references/_index_template.md`
+- 詳細テンプレート: `docs/ai/playbook-assets/api-spec-sync/references/_endpoint_template.md`
+- 同期チェック: `docs/ai/playbook-assets/api-spec-sync/references/sync-checklist.md`
+- 同期漏れ簡易検知スクリプト: `scripts/playbooks/api-spec-sync/check_api_docs_sync.py`

.claude/skills/git-commit/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: git-commit
+description: Gitの変更を安全にコミットするためのPlaybook。`git status` と `git diff` で差分を確認し、変更内容に合うプレフィックスを選んで日本語コミットメッセージ規約を満たしたうえで `git commit` を実行する必要があるときに使う。コミット実行依頼、コミットメッセージ作成依頼、コミット直前の最終確認で適用する。
+---
+
+<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
+<!-- source: docs/ai/canonical/playbooks/git-commit.md + scripts/sync_ai_context.py -->
+
+# Gitコミット実行
+
+重要: すべてのコミットメッセージは日本語で記述する。
+
+## 実行手順
+
+1. ワークツリーと差分を確認する。
+- `git status --short`
+- `git diff --`
+- `git diff --staged --`
+
+2. 変更意図ごとにコミット単位を整理する。
+- 無関係な変更が混在する場合はコミットを分割する。
+- コミット対象が空なら停止して理由を報告する。
+
+3. 必要なファイルのみをステージする。
+- 個別指定を優先する: `git add <path>`
+- 追加後に再確認する: `git status --short`
+
+4. プレフィックスを選択する。
+- `feat`: 新機能の追加
+- `fix`: バグ修正
+- `docs`: ドキュメントのみの変更
+- `style`: 動作に影響しない変更（フォーマットなど）
+- `refactor`: 機能追加やバグ修正を伴わない構造変更
+- `perf`: パフォーマンス改善
+- `test`: テストの追加または修正
+- `chore`: ビルド、補助ツール、依存関係などの変更
+
+5. コミットメッセージを作成し、規約チェックを通す。
+- 形式: `prefix: メッセージ`
+- 全体文字数: 50文字以内（prefixを含む）
+- 文体: 現在形（辞書形）または体言止め
+- 末尾: 句点（。）を付けない
+- 言語: プレフィックス後の本文は日本語のみ
+
+6. 文字数を機械的に確認する。
+- `msg='feat: ユーザー認証機能を追加'`
+- `printf %s \"$msg\" | wc -m`
+- 50を超える場合は短く書き直して再計測する。
+
+7. コミットを実行する。
+- `git commit -m \"$msg\"`
+- 実行後に `git show --stat --oneline -1` で内容を確認する。
+
+8. 結果を報告する。
+- コミットハッシュ、件名、変更ファイルを簡潔に共有する。
+- 未ステージ変更が残る場合は明示する。
+
+## メッセージ例
+
+- 良い例: `feat: ユーザー認証機能を追加`
+- 悪い例: `feat: Add user authentication`

.claude/skills/python-project-bootstrap/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: python-project-bootstrap
+description: 新しい Python プロジェクトの初期セットアップを標準化するPlaybook。AGENTS.md と docs/product を対話で確定し、Hexagonal Architecture 前提のディレクトリ、SOLID/DRY ガイド、API/タスク設計ドキュメント、`.env.development`/`.env.production` と dotenvx 暗号化運用を整備するときに使う。CI は必須工程とし、品質ゲート設定は必ず `python-uv-ci-setup` を呼び出して完了させる依頼で適用する。
+---
+
+<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
+<!-- source: docs/ai/canonical/playbooks/python-project-bootstrap.md + scripts/sync_ai_context.py -->
+
+# Pythonプロジェクト初期構築
+
+このPlaybookは、Python 新規プロジェクトの「最初に揃えるべき構造と運用ドキュメント」を再利用可能な手順で作る。
+
+## 実行ルール
+
+- AGENTS.md の不明点がある状態で雛形を確定しない。必ず対話で埋める。
+- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を空欄のまま放置しない。初期化時に必ずユーザーと擦り合わせる。
+- 質問は 1〜3 問ずつ行い、回答を反映して次の質問へ進む。
+- CI 設定は必須。必ず `python-uv-ci-setup` を使って完了させる。
+- 既存ファイルがある場合は破壊的上書きを避け、差分統合を優先する。
+- AGENTS.md は常時有効ルールのみを記載し、長い手順やコマンドは Playbook 側へ集約する。
+- 原則として新規作成は Playbook 同梱のテンプレートリポジトリから開始する。
+- 空リポジトリから開始する場合のみ、グローバル `python-project-bootstrap` を初回1回だけ使う。
+- 初回生成直後に手順正本を `<repo>/docs/ai/canonical/playbooks/` へ配置し、以後は repo ローカルを正本とする。
+
+## 実行フロー
+
+1. 前提を確認する。
+- ルートディレクトリと Git 管理状態を確認する。
+- 既存の `AGENTS.md` と `docs/task-designs` の有無を確認する。
+- 既存プロジェクトで `docs/tasks` を使っている場合のみ、後方互換として既存パス命名を尊重する。
+- 空リポジトリの場合は「初回のみグローバル bootstrap」を適用し、完了後に repo ローカル Playbook 運用へ移行する。
+
+2. AGENTS.md 情報を対話で確定する。
+- `docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md` の必須項目から埋める。
+- `docs/ai/playbook-assets/python-project-bootstrap/references/agents-playbooks-boundary.md` を基準に、AGENTS と Playbooks の責務境界を固定する。
+- 未確定項目は既定値を勝手に固定せず、ユーザー確認を優先する。
+- 既定値を使う場合は「既定値を採用した」と明示してから確定する。
+
+3. 初期構成を生成する。
+- `scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py` を実行して、ディレクトリと初期ドキュメントを生成する。
+- 例:
+  - `python3 scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py --target <project-root> --project-name <name> --package-name <package_name> --description "<description>"`
+- 必要に応じて `--task-design-dir docs/task-designs`（既定）や `--force` を使う。
+- 生成後に手順正本を `<repo>/docs/ai/canonical/playbooks/` に配置してコミットし、以後の実行基盤を repo ローカルへ固定する。
+
+4. プロダクト方針（docs/product）を対話で初期確定する。
+- `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md` を使い、1〜3問ずつ擦り合わせる。
+- 最低限、次を埋める。
+  - `docs/product/vision.md`: 対象ユーザー、解く課題、成功状態
+  - `docs/product/goals.md`: ユーザー到達状態ゴールと到達判定
+  - `docs/product/milestones.md`: 到達ステップ
+  - `docs/product/progress.md`: やるべきこと一覧ベースの現在地
+- 不確定項目が残る場合は、`仮置き` と明記して次の確認タイミングを残す。
+
+5. 生成内容をレビューする。
+- `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md` を基準に、`adapters/application/domain/ports` の責務分離を確認する。
+- `docs/rules/solid/README.md` と `docs/rules/code_architecture/README.md` の導線が AGENTS.md から参照できることを確認する。
+- `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` を基準に `.env.*` の運用記載が整合しているか確認する。
+- `docs/product/*.md` が生成され、対話で確定した内容が反映されていることを確認する。
+
+6. CI を必須で設定する。
+- 生成直後に必ず `python-uv-ci-setup` を呼び出して、`uv` ベースの品質ゲートと GitHub Actions を整備する。
+- 本Playbook内で CI 設定を再実装しない（DRY を維持）。
+
+7. 検証する。
+- 生成ファイル一覧を確認する。
+- `AGENTS.md` の必須セクションが埋まっていることを確認する。
+- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` が初期記入されていることを確認する。
+- `.env.development` / `.env.production` の整合を確認する。
+- CI 設定完了後に `uv run pre-commit install` が実行可能な状態であることを確認する。
+
+8. 結果を報告する。
+- 作成・更新したファイル
+- 対話で確定した項目
+- `docs/product` で合意した内容（Vision/Goal/Milestone/Progress）
+- CI 設定の実行結果
+- 残課題（手動で埋めるべき値や鍵など）
+- Playbook 配置先（repo 配下 / 個人グローバル）と採用理由
+
+## 参照ファイル
+
+- AGENTS.md ヒアリング項目: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md`
+- AGENTS と Playbooks の責務境界: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-playbooks-boundary.md`
+- docs/product 擦り合わせ質問: `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md`
+- Hexagonal 構成と責務: `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md`
+- `.env.*` と dotenvx 暗号化運用: `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md`

.claude/skills/python-uv-ci-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: python-uv-ci-setup
+description: uv を使う Python プロジェクトで、format/lint/静的型チェック/テスト/docstring ルールをローカルと GitHub Actions で一貫運用するためのセットアップPlaybook。`pyproject.toml` の `[dependency-groups]`、`.pre-commit-config.yaml`、`.github/workflows/ci.yml` を新規作成または更新し、`uv run pre-commit install` まで完了させる依頼で使う。
+---
+
+<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
+<!-- source: docs/ai/canonical/playbooks/python-uv-ci-setup.md + scripts/sync_ai_context.py -->
+
+# Python uv CIセットアップ
+
+このPlaybookでは、`uv + ruff + mypy + pytest + pre-commit + GitHub Actions` を最小差分で導入し、ローカルとCIの品質ゲートをそろえる。
+
+## 実行フロー
+
+1. 前提を確認する。
+- ルートに `pyproject.toml` があるか確認する。なければ `uv init` を提案する。
+- `uv --version` と `python --version` を確認する。
+- Git管理下か確認する。未初期化なら `git init` を実行してから進む。
+
+2. 既存設定を監査する。
+- `pyproject.toml` の `[dependency-groups]`、`[tool.ruff]`、`[tool.mypy]`、`[tool.pytest.*]` を確認する。
+- `.pre-commit-config.yaml` と `.github/workflows/*.yml` を確認する。
+- 既存設定がある場合は上書きせず、重複を避けて統合する。
+
+3. `pyproject.toml` を `uv` 前提で整備する。
+- 開発依存を `dependency-groups.dev` に集約する。
+- 最低限の開発依存をそろえる: `ruff`, `mypy`, `pytest`, `pre-commit`。
+- ルールは `docs/ai/playbook-assets/python-uv-ci-setup/references/templates.md` の `pyproject.toml` テンプレートを基準にし、既存プロジェクトに合わせて微調整する。
+
+4. pre-commit を設定する。
+- `.pre-commit-config.yaml` を作成または更新する。
+- `uv-pre-commit` の `uv-lock` を入れてロックファイル整合を強制する。
+- `uv run` 経由で `ruff format --check`、`ruff check`、`mypy` を実行する。
+- `pytest` は既定で `pre-push` に配置して開発体験を維持する。全コミットで必須にしたい場合は `stages` を `pre-commit` に変更する。
+
+5. GitHub Actions を設定する。
+- `.github/workflows/ci.yml` を作成または更新する。
+- `actions/setup-python` と `astral-sh/setup-uv` を使い、`uv sync --locked --dev` の後に同等チェックを実行する。
+- キャッシュは `setup-uv` の `enable-cache: true` を基本にする。
+
+6. ローカルセットアップを完了する。
+- `uv lock`
+- `uv sync --locked --dev`
+- `uv run pre-commit install --hook-type pre-commit --hook-type pre-push`
+- `uv run pre-commit run --all-files`
+
+7. 最終検証を実行する。
+- `uv run ruff format --check .`
+- `uv run ruff check .`
+- `uv run mypy .`
+- `uv run pytest -q`
+
+8. 結果を報告する。
+- 追加・更新したファイル
+- 実行コマンドと結果
+- 残課題（既存コード由来のlint/type/test失敗など）
+
+## 運用ルール
+
+- 型チェックは `mypy` に固定し、`ty` は使わない。
+- docstring は Google style を採用し、短文 1 行のみの記述を避ける。
+- docstring の先頭では「何をする処理か」「どの条件で使うか」を日本語で具体的に説明する。
+- 引数がある処理は `Args`、戻り値がある処理は `Returns`、例外を送出しうる処理は `Raises` を記載する。
+- `pydocstyle` の `convention = "google"` を有効化し、必要に応じて日本語運用に不要なルールのみ最小限で除外する。
+- `project.requires-python` を定義し、Ruff のバージョン推論と整合させる。
+- CI とローカルで実行コマンドを一致させる。
+
+## 参照ファイル
+
+- 設定方針と採用理由: `docs/ai/playbook-assets/python-uv-ci-setup/references/tooling-best-practices.md`
+- そのまま適用できる雛形: `docs/ai/playbook-assets/python-uv-ci-setup/references/templates.md`