diff --git a/.claude/skills/adr-management/SKILL.md b/.claude/skills/adr-management/SKILL.md new file mode 100644 index 0000000..4d187f3 --- /dev/null +++ b/.claude/skills/adr-management/SKILL.md @@ -0,0 +1,52 @@ +--- +name: adr-management +description: 設計判断（アーキテクチャ、運用ルール、依存方針など）の採否を ADR として記録・更新し、変更理由を追跡可能にするためのPlaybook。方針の新規決定、方針変更、既存判断の置換が発生したときに使う。 +--- + + + + +# 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` diff --git a/.claude/skills/api-spec-sync/SKILL.md b/.claude/skills/api-spec-sync/SKILL.md new file mode 100644 index 0000000..151d114 --- /dev/null +++ b/.claude/skills/api-spec-sync/SKILL.md @@ -0,0 +1,54 @@ +--- +name: api-spec-sync +description: REST/HTTP APIの定義書（index + 1エンドポイント1ファイル）を新規作成・更新し、実装差分と常時同期させるためのPlaybook。API実装の追加・変更・削除、認証仕様変更、エラー形式変更、入出力スキーマ変更が発生したときに使う。 +--- + + + + +# 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` を読み、対象エンドポイントの詳細ファイルを作成/更新する。 +- 命名は `-.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実装が変わっているのにドキュメント差分がない場合、タスク完了にしない。 + +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` diff --git a/.claude/skills/git-commit/SKILL.md b/.claude/skills/git-commit/SKILL.md new file mode 100644 index 0000000..e8f2e39 --- /dev/null +++ b/.claude/skills/git-commit/SKILL.md @@ -0,0 +1,61 @@ +--- +name: git-commit +description: Gitの変更を安全にコミットするためのPlaybook。`git status` と `git diff` で差分を確認し、変更内容に合うプレフィックスを選んで日本語コミットメッセージ規約を満たしたうえで `git commit` を実行する必要があるときに使う。コミット実行依頼、コミットメッセージ作成依頼、コミット直前の最終確認で適用する。 +--- + + + + +# Gitコミット実行 + +重要: すべてのコミットメッセージは日本語で記述する。 + +## 実行手順 + +1. ワークツリーと差分を確認する。 +- `git status --short` +- `git diff --` +- `git diff --staged --` + +2. 変更意図ごとにコミット単位を整理する。 +- 無関係な変更が混在する場合はコミットを分割する。 +- コミット対象が空なら停止して理由を報告する。 + +3. 必要なファイルのみをステージする。 +- 個別指定を優先する: `git add ` +- 追加後に再確認する: `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` diff --git a/.claude/skills/python-project-bootstrap/SKILL.md b/.claude/skills/python-project-bootstrap/SKILL.md new file mode 100644 index 0000000..590e971 --- /dev/null +++ b/.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` を呼び出して完了させる依頼で適用する。 +--- + + + + +# 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回だけ使う。 +- 初回生成直後に手順正本を `/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-name --package-name --description ""` +- 必要に応じて `--task-design-dir docs/task-designs`（既定）や `--force` を使う。 +- 生成後に手順正本を `/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` diff --git a/.claude/skills/python-uv-ci-setup/SKILL.md b/.claude/skills/python-uv-ci-setup/SKILL.md new file mode 100644 index 0000000..d78a48a --- /dev/null +++ b/.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` まで完了させる依頼で使う。 +--- + + + + +# 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` diff --git a/.claude/skills/task-design-gate/SKILL.md b/.claude/skills/task-design-gate/SKILL.md new file mode 100644 index 0000000..7763db0 --- /dev/null +++ b/.claude/skills/task-design-gate/SKILL.md @@ -0,0 +1,45 @@ +--- +name: task-design-gate +description: 実装前にタスク設計書を作成し、スコープ・前提・リスクをそろえたうえでユーザー承認を取得するためのPlaybook。実装・リファクタ・移行・デバッグなど、ファイル変更を伴う依頼で事前計画が必要なときに使う。 +--- + + + + +# タスク設計ゲート + +実装ファイルを編集する前に、必ず次の手順を実行する。 + +1. 依頼内容を 1 文で言い換える。 +2. 関連コードと制約を調査する。 +3. `docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md` を読み、テンプレートを埋める。 +4. 設計書を提示し、ユーザーに明示的な承認を求める。 +5. 承認が出るまで、実装ファイルの編集を開始しない。 +6. 承認NGまたは修正依頼があれば、設計書を更新して再確認する。 + +## ゲートルール + +- 承認前に実装ファイルを編集しない。 +- 承認前に許可されるのは、読み取り中心の調査コマンドのみとする。 +- 永続化する計画メモの作成・更新は、ユーザーが明示的に求めた場合のみ許可する。 +- `10. オープン事項 / 要確認` に未解消項目がある場合、ステータスを `保留(blocked)` にし、実装を開始しない。 +- 承認後は合意済みスコープ内でのみ実装し、スコープ逸脱が発生したら即時に再合意を取る。 + +## 出力ルール + +- `docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md` の見出し順を厳守して Markdown で出力する。 +- タスク設計書のメタデータには、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 +- 各セクションはリポジトリ固有の具体内容で記載し、一般論を避ける。 +- ファイルは必ず明示的なパスで列挙する。 +- 少なくとも 1 つ以上のリスクと検証手順を含める。 +- 保存先はリポジトリ配下の `docs/task-designs/` に固定する。 +- `docs/task-designs/` が存在しない場合は作成してから保存する。 +- 新規設計書のファイル名は `YYYYMMDDHHMMSS_{task-name}.md` とし、`YYYYMMDDHHMMSS` は初版作成日時（JST）を使う。 +- `task-name` は英小文字の kebab-case を使う。 +- 更新時はファイル名を変更せず、本文の `最終更新` のみ更新する。 +- 作成時刻が不明な既存ドキュメントは `YYYYMMDD000000_{task-name}.md` を使う。 +- `README.md` と `_task-design-template.md` は命名プレフィックス規則の例外とする。 + +## ハイブリッド運用（任意） + +この運用をプロジェクト全体に常時適用したい依頼があれば、`docs/ai/playbook-assets/task-design-gate/references/agents-md-snippet.md` を参照し、`AGENTS.md` への追記を提案する。 diff --git a/.cursor/rules/10-task-routing.mdc b/.cursor/rules/10-task-routing.mdc index 3c8d72c..53fbcf8 100644 --- a/.cursor/rules/10-task-routing.mdc +++ b/.cursor/rules/10-task-routing.mdc @@ -21,5 +21,6 @@ alwaysApply: true - AGENTS.md には「いつどの Playbook を使うか」を書き、実行時はリンク先ドキュメントを参照する。 - 詳細手順の正本は `docs/ai/canonical/playbooks/*.md` に集約し、`scripts/sync_ai_context.py` で `docs/ai/playbooks/*.md` へ配布する。 +- Claude Code へは同じスクリプトで `CLAUDE.md`（`@AGENTS.md` を取り込む 1 行）と `.claude/skills//SKILL.md` を配布する。 - 参照資料は `docs/ai/playbook-assets/`、補助スクリプトは `scripts/playbooks/` に集約する。 - 同じ手順を AGENTS.md と Playbook に重複記載しない。 diff --git a/.github/workflows/ai-context-sync.yml b/.github/workflows/ai-context-sync.yml index aa41018..d2dacde 100644 --- a/.github/workflows/ai-context-sync.yml +++ b/.github/workflows/ai-context-sync.yml @@ -10,6 +10,8 @@ on: - "scripts/sync_ai_context.py" - "AGENTS.md" - ".cursor/rules/**" + - "CLAUDE.md" + - ".claude/skills/**" push: branches: [main] paths: @@ -20,6 +22,8 @@ on: - "scripts/sync_ai_context.py" - "AGENTS.md" - ".cursor/rules/**" + - "CLAUDE.md" + - ".claude/skills/**" jobs: check-sync: diff --git a/AGENTS.md b/AGENTS.md index 0c79ad5..190e500 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,7 @@ - AGENTS.md には「いつどの Playbook を使うか」を書き、実行時はリンク先ドキュメントを参照する。 - 詳細手順の正本は `docs/ai/canonical/playbooks/*.md` に集約し、`scripts/sync_ai_context.py` で `docs/ai/playbooks/*.md` へ配布する。 +- Claude Code へは同じスクリプトで `CLAUDE.md`（`@AGENTS.md` を取り込む 1 行）と `.claude/skills//SKILL.md` を配布する。 - 参照資料は `docs/ai/playbook-assets/`、補助スクリプトは `scripts/playbooks/` に集約する。 - 同じ手順を AGENTS.md と Playbook に重複記載しない。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7d8188f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ + + + +@AGENTS.md diff --git a/README.md b/README.md index 6ba0743..b8c77a7 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# codex-cursor-python-template +# python-project-template -Codex と Cursor を併用する Python プロジェクト向けのテンプレート。 +Codex / Cursor / Claude Code を併用する Python プロジェクト向けのテンプレート。 ## 目的 - AI 向け運用ルールの二重管理を防ぐ。 -- `AGENTS.md`（Codex）と `.cursor/rules/*.mdc`（Cursor）を同じ正本から生成する。 +- `AGENTS.md`（Codex）、`.cursor/rules/*.mdc`（Cursor）、`CLAUDE.md` と `.claude/skills/*/SKILL.md`（Claude Code）を同じ正本から生成する。 - 手順本文を `docs/ai/canonical/playbooks/` に集約し、実行時は `docs/ai/playbooks/*.md` を参照する。 - 参照資料と補助スクリプトを repo 同梱で管理し、チーム再現性を確保する。 @@ -15,6 +15,8 @@ Codex と Cursor を併用する Python プロジェクト向けのテンプレ . ├── AGENTS.md # 自動生成 ├── .cursor/rules/*.mdc # 自動生成 +├── CLAUDE.md # 自動生成（@AGENTS.md を取り込む 1 行） +├── .claude/skills/*/SKILL.md # 自動生成（Playbook を Claude Code のスキルとして配布） ├── docs/ai/canonical/*.md # 正本（手動編集） ├── docs/ai/canonical/playbooks/*.md # Playbook手順の正本（手動編集） ├── docs/ai/playbooks/*.md # 自動生成（実行時の参照先） @@ -38,7 +40,7 @@ Codex と Cursor を併用する Python プロジェクト向けのテンプレ ## 更新方針 - ルール本文は `docs/ai/canonical/` と `docs/ai/canonical/playbooks/` だけを編集する。 -- `docs/ai/playbooks/*.md`、`AGENTS.md`、`.cursor/rules/*.mdc` は自動生成物として直接編集しない。 +- `docs/ai/playbooks/*.md`、`AGENTS.md`、`.cursor/rules/*.mdc`、`CLAUDE.md`、`.claude/skills/*/SKILL.md` は自動生成物として直接編集しない。 - Playbook の参照資料は `docs/ai/playbook-assets/`、補助スクリプトは `scripts/playbooks/` を正本とする。 ## プロダクト方針と進捗管理 @@ -128,8 +130,11 @@ python3 scripts/sync_ai_context.py --check - 理由: OS/Git 設定差（例: `core.symlinks`）でチーム運用が不安定になりうるため。 - 必要な場合のみローカル実験として利用し、チーム標準は同期スクリプト方式を維持する。 -## Codex + Cursor 併用ポリシー +## Codex + Cursor + Claude Code 併用ポリシー -- 実行導線は `AGENTS.md` と `.cursor/rules/*.mdc` に統一する。 +- 実行導線は `AGENTS.md`、`.cursor/rules/*.mdc`、`CLAUDE.md` に統一する。 +- Claude Code は `AGENTS.md` を読まないため、`CLAUDE.md` は `@AGENTS.md` の 1 行で同じ規約を取り込む。Claude 固有の指示を足したい場合も `CLAUDE.md` を直接編集せず、正本に書いて再生成する。 +- Playbook は `.claude/skills//SKILL.md` として配布され、`/task-design-gate` のように呼べるほか、依頼内容に応じて Claude が自動で選ぶ。 +- Playbook 内のパスはリポジトリルート基準なので、Claude Code はリポジトリルートで起動する。 - 詳細手順は `docs/ai/playbooks/*.md` を共通参照先にする。 - 正本更新後は必ず `sync_ai_context.py` で再生成し、`--check` を通す。 diff --git a/docs/ai/canonical/task-routing.md b/docs/ai/canonical/task-routing.md index 8ff89c8..0b6644b 100644 --- a/docs/ai/canonical/task-routing.md +++ b/docs/ai/canonical/task-routing.md @@ -13,5 +13,6 @@ - AGENTS.md には「いつどの Playbook を使うか」を書き、実行時はリンク先ドキュメントを参照する。 - 詳細手順の正本は `docs/ai/canonical/playbooks/*.md` に集約し、`scripts/sync_ai_context.py` で `docs/ai/playbooks/*.md` へ配布する。 +- Claude Code へは同じスクリプトで `CLAUDE.md`（`@AGENTS.md` を取り込む 1 行）と `.claude/skills//SKILL.md` を配布する。 - 参照資料は `docs/ai/playbook-assets/`、補助スクリプトは `scripts/playbooks/` に集約する。 - 同じ手順を AGENTS.md と Playbook に重複記載しない。 diff --git a/scripts/sync_ai_context.py b/scripts/sync_ai_context.py index 94e5b02..dd00179 100755 --- a/scripts/sync_ai_context.py +++ b/scripts/sync_ai_context.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""canonical から AGENTS.md / Cursor rules / Playbooks を生成・検証する。""" +"""canonical から AGENTS.md / CLAUDE.md / Cursor rules / Claude Code skills / Playbooks を生成・検証する。""" from __future__ import annotations @@ -15,6 +15,7 @@ OUTPUT_FILES = { "agents": Path("AGENTS.md"), + "claude": Path("CLAUDE.md"), "cursor_global": Path(".cursor/rules/00-global.mdc"), "cursor_routing": Path(".cursor/rules/10-task-routing.mdc"), "cursor_playbooks": Path(".cursor/rules/20-playbooks.mdc"), @@ -22,6 +23,7 @@ PLAYBOOK_CANONICAL_DIR = Path("docs/ai/canonical/playbooks") PLAYBOOK_OUTPUT_DIR = Path("docs/ai/playbooks") +SKILL_OUTPUT_DIR = Path(".claude/skills") AUTO_GENERATED_NOTICE = "\n" FRONTMATTER_PATTERN = re.compile(r"\A---\n.*?\n---\n?", re.DOTALL) @@ -144,6 +146,18 @@ def build_agents(canonical: dict[str, str]) -> str: ) +def build_claude() -> str: + """CLAUDE.md の内容を生成する。 + + Claude Code は AGENTS.md を自動では読まないため、公式が推奨する + ``@AGENTS.md`` インポート 1 行で同じ規約を読ませる。 + + Returns: + 自動生成ヘッダと ``@AGENTS.md`` だけからなる CLAUDE.md 本文。 + """ + return auto_header("AGENTS.md") + "\n@AGENTS.md\n" + + def build_cursor_rule(description: str, body: str, source: str) -> str: """Cursor rule (.mdc) の内容を生成する。""" return ( @@ -196,6 +210,7 @@ def build_outputs( outputs: dict[Path, str] = { OUTPUT_FILES["agents"]: build_agents(canonical), + OUTPUT_FILES["claude"]: build_claude(), OUTPUT_FILES["cursor_global"]: build_cursor_rule( "プロジェクト共通ポリシーと標準", cursor_global, @@ -214,7 +229,11 @@ def build_outputs( } for playbook_name, markdown in playbooks.items(): source = f"docs/ai/canonical/playbooks/{playbook_name}.md" - outputs[PLAYBOOK_OUTPUT_DIR / f"{playbook_name}.md"] = with_auto_header(markdown, source) + generated = with_auto_header(markdown, source) + outputs[PLAYBOOK_OUTPUT_DIR / f"{playbook_name}.md"] = generated + # canonical playbook の frontmatter は name/description の SKILL.md 形式なので、 + # Claude Code のスキルとしてそのまま配布する（ディレクトリ名 = /コマンド名）。 + outputs[SKILL_OUTPUT_DIR / playbook_name / "SKILL.md"] = generated return outputs