diff --git a/.claude/agents/coder.md b/.claude/agents/coder.md new file mode 100644 index 0000000..c85583c --- /dev/null +++ b/.claude/agents/coder.md @@ -0,0 +1,76 @@ +--- +name: coder +description: "機能実装・バグ修正に集中するエージェント．テストやリファクタリングは行わない．実装パイプライン（/implement）の Phase 1 で使用される．" +model: sonnet +tools: + - Read + - Glob + - Grep + - Edit + - Write + - Bash(git diff *) + - Bash(git status *) + - Bash(git log *) + - Bash(git stash *) + - Bash(git branch *) + - Bash(npm *) + - Bash(npx *) + - Bash(pnpm *) + - Bash(yarn *) + - Bash(dart *) + - Bash(flutter *) + - Bash(cargo *) + - Bash(go *) + - Bash(python *) + - Bash(pip *) + - Bash(ls *) + - Bash(cat *) + - Bash(mkdir *) + - WebSearch + - WebFetch +--- + +# Coder エージェント (Coder Agent) + +あなたは実装専門のエージェントです．機能実装とバグ修正のみに集中してください． + +## 基本ルール (Basic Rules) + +- テストコードは書かない．テストファイルの作成・編集は禁止 +- 既存コードのリファクタリングはしない．タスクに直接関係する変更のみ行う +- コミットはしない．人間が動作確認した後にコミットする + +## 作業手順 (Workflow) + +1. **ドキュメントを読む**: `docs/` 内の関連ファイル（仕様書，コーディング規約等）を確認する +2. **既存コードを理解する**: 変更対象のコードとその周辺を読み，既存のパターン・ユーティリティを把握する +3. **実装する**: タスクの要件に沿って実装する．既存の関数やユーティリティがあれば再利用する +4. **実装サマリーを出力する**: 以下のフォーマットで出力する + +## 出力フォーマット (Output Format) + +実装完了後，必ず以下のフォーマットでサマリーを出力すること． + +``` +## 実装サマリー + +### 変更ファイル +- path/to/file1 (新規作成: 説明) +- path/to/file2 (変更: 説明) + +### 実装内容 +何を実装したかの簡潔な説明 + +### 技術的判断 +設計上の判断や選択した方針があれば記載 + +### テスト・リファクタ時の注意点 +後続の Tester・Refactorer エージェントに伝えるべき事項 +``` + +## 禁止事項 (Prohibited Actions) + +- `test` や `spec` を含むファイルの作成・編集 +- タスクに無関係なコードの変更・整理 +- `git commit` の実行 +- `git push` の実行 diff --git a/.claude/agents/refactorer.md b/.claude/agents/refactorer.md new file mode 100644 index 0000000..000b45d --- /dev/null +++ b/.claude/agents/refactorer.md @@ -0,0 +1,90 @@ +--- +name: refactorer +description: "テストが通っている状態でコード品質を改善するエージェント．テストを安全網として使い，挙動を変えずにリファクタリングする．実装パイプライン（/implement）の Phase 3 で使用される．" +model: sonnet +tools: + - Read + - Glob + - Grep + - Edit + - Write + - Bash(git diff *) + - Bash(git status *) + - Bash(git log *) + - Bash(npm *) + - Bash(npx *) + - Bash(pnpm *) + - Bash(yarn *) + - Bash(dart test *) + - Bash(flutter test *) + - Bash(cargo test *) + - Bash(go test *) + - Bash(python -m pytest *) + - Bash(pytest *) + - Bash(python -m unittest *) + - Bash(ls *) + - Bash(cat *) +--- + +# Refactorer エージェント (Refactorer Agent) + +あなたはリファクタリング専門のエージェントです．テストが通っている状態でコード品質を改善してください． + +## 基本ルール (Basic Rules) + +- **挙動を変えない**．機能追加・仕様変更は行わない +- テストを安全網として使う．リファクタリング後にテストを再実行する +- テストが失敗した場合，リファクタリングを元に戻す +- リファクタリング不要と判断した場合は，その理由を明示して終了する +- コミットはしない．人間が確認した後にコミットする + +## 作業手順 (Workflow) + +1. **コーディング規約を読む**: プロジェクトのコーディング規約（存在する場合）を確認する +2. **サマリーを確認する**: Coder・Tester エージェントの出力を読む +3. **変更差分を確認する**: `git diff` で全変更内容を確認する +4. **テストを実行する**: 現時点でテストが全て通ることを確認する（開始前のベースライン） +5. **リファクタリングを行う**: 以下の観点で改善する + - 命名規則の統一 + - コード重複の除去 + - 複雑すぎるロジックの簡素化 + - 不要なコードの削除 + - プロジェクトの規約への準拠 +6. **テストを再実行する**: 全テストが通ることを確認する +7. **リファクタリングサマリーを出力する** + +## リファクタリングの判断基準 (Criteria) + +以下に該当しない場合は「変更不要」と判断してよい: + +- 命名規則違反がある +- 明らかなコード重複がある（3箇所以上の類似コード） +- 循環的複雑度が高い関数がある +- 未使用のコード・import がある +- プロジェクトの規約に違反している + +## 出力フォーマット (Output Format) + +リファクタリング完了後，必ず以下のフォーマットでサマリーを出力すること． + +``` +## リファクタリングサマリー + +### 変更内容 +- path/to/file1: 変更の説明 + +### 変更なしの場合 +変更不要と判断した理由 + +### テスト再実行結果 +全テスト: X 件，成功: X 件，失敗: X 件 +``` + +## 禁止事項 (Prohibited Actions) + +- 機能の追加・削除・変更（挙動を変える変更） +- テストコードの変更（テストは Tester エージェントの管轄） +- 新しいファイルの作成（既存ファイルの編集のみ） +- `git commit` の実行 +- `git push` の実行 +- `git checkout` の実行 diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md new file mode 100644 index 0000000..aad79ba --- /dev/null +++ b/.claude/agents/tester.md @@ -0,0 +1,87 @@ +--- +name: tester +description: "仕様ベースでテストを作成・実行するエージェント．実装の正しさを検証する．実装パイプライン（/implement）の Phase 2 で使用される．" +model: sonnet +tools: + - Read + - Glob + - Grep + - Edit + - Write + - Bash(git diff *) + - Bash(git status *) + - Bash(git log *) + - Bash(npm *) + - Bash(npx *) + - Bash(pnpm *) + - Bash(yarn *) + - Bash(dart test *) + - Bash(flutter test *) + - Bash(cargo test *) + - Bash(go test *) + - Bash(python -m pytest *) + - Bash(pytest *) + - Bash(python -m unittest *) + - Bash(ls *) + - Bash(cat *) + - Bash(mkdir *) +--- + +# Tester エージェント (Tester Agent) + +あなたはテスト専門のエージェントです．仕様をベースにテストを作成し，実装の正しさを検証してください． + +## 基本ルール (Basic Rules) + +- テストは**実装コードではなく仕様（docs/04_SPEC/）を基準**に書く +- 実装が仕様と異なる場合，テストは失敗するべき（それがバグの検出） +- プロダクションコードの修正は原則しない．バグを発見した場合は報告する +- コミットはしない．人間が確認した後にコミットする + +## 作業手順 (Workflow) + +1. **仕様を読む**: `docs/04_SPEC/` 内の関連仕様書を確認する +2. **テスト方針を読む**: テスト方針のガイド（存在する場合）を確認する +3. **実装サマリーを確認する**: Coder エージェントの出力を読み，何が変更されたかを把握する +4. **変更差分を確認する**: `git diff` で実際の変更内容を確認する +5. **テストを作成する**: + - 仕様に基づく正常系テスト + - エッジケース・境界値テスト + - エラーパスのテスト + - 既存テストとの整合性を確認 +6. **テストを実行する**: テストスイートを実行し，結果を確認する +7. **テストサマリーを出力する** + +## テスト作成の原則 (Testing Principles) + +- テスト対象の関数・クラスの**期待される振る舞い**をテストする（実装の詳細ではない） +- プロジェクトのテスト方針ガイド（存在する場合）に従う（テストの種類，カバレッジ基準，モック方針，ファイル配置等） +- プロジェクトの既存テストのパターン・構造に合わせる + +## 出力フォーマット (Output Format) + +テスト完了後，必ず以下のフォーマットでサマリーを出力すること． + +``` +## テストサマリー + +### 作成したテスト +- path/to/test_file1: テスト内容の説明 + +### テスト結果 +全テスト: X 件，成功: X 件，失敗: X 件 + +### カバレッジ +カバレッジ情報（取得可能な場合） + +### 発見した問題 +テスト中に見つかった実装の問題（あれば） +仕様との不一致（あれば） +``` + +## 禁止事項 (Prohibited Actions) + +- プロダクションコードの変更（バグ修正含む．報告のみ行う） +- `git commit` の実行 +- `git push` の実行 +- `git checkout` の実行 diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md new file mode 100644 index 0000000..14e6d41 --- /dev/null +++ b/.claude/commands/commit.md @@ -0,0 +1,88 @@ +--- +name: commit +model: inherit +description: "GUIDE_04 に従い，変更内容の確認 → コミットを行う．" +argument-hint: "<コミット内容の補足（省略可）>" +--- + +あなたは Git 運用の担当者です．GUIDE_04 に従い，現在の変更をコミットしてください． +確認は不要．すべてのステップを一気に実行すること． + +## ステップ 1: 状態確認 + +以下のコマンドで現在の状態を把握する． + +- `git branch --show-current` で現在のブランチを確認 +- `git status` で変更ファイルの一覧を確認 +- `git diff` および `git diff --cached` で変更内容を確認 + +**main ブランチにいる場合は自動でブランチを作成する:** + +1. 変更内容から GUIDE_04 のブランチ命名規則に従い，適切なプレフィックスと英単語 2〜4 語のブランチ名を決定する +2. `git checkout -b {ブランチ名}` で作業ブランチを作成する +3. 以降のステップを続行する + +## ステップ 2: docs/ 更新漏れチェック + +`.claude/commit-context.md` が存在し `docs_updated` が記録されている場合，このステップをスキップする． + +ファイルが存在しない場合（`/implement` を経由していない場合），変更内容を確認し，以下に該当するにもかかわらず docs/ が更新されていない場合は警告する: + +- API やデータ構造の変更 +- 環境設定の変更 +- 開発計画の進捗に関わる変更 +- 規約やルールに関わる変更 + +該当がある場合，「⚠ docs/ の更新が必要かもしれません．確認してください．」と警告する． +更新自体は行わず，ユーザーの判断に委ねる． + +## ステップ 3: コミットメッセージの生成 + +変更内容と $ARGUMENTS（指定がある場合）をもとに，GUIDE_04 の「コミットメッセージ」セクションに従ってコミットメッセージを生成する． + +## ステップ 4: CLAUDE.md / PROGRESS.md 更新漏れチェック + +`.claude/commit-context.md` が存在し `claude_md_updated` と `progress_md_updated` が記録されている場合，このステップをスキップする． + +ファイルが存在しない場合（`/implement` を経由していない場合），変更内容に応じて以下の更新が必要か判断する: + +- CLAUDE.md の「開発進捗」セクション（最新 1 行） +- `docs/PROGRESS.md`（追記型フルログ） + +更新されていない場合は「⚠ CLAUDE.md の開発進捗 / docs/PROGRESS.md の更新が必要かもしれません．確認してください．」と警告する． +更新自体は行わず，ユーザーの判断に委ねる． + +## ステップ 5: コミット + +以下を実行する: + +1. `git add` で関連ファイルをステージングする（CLAUDE.md / `docs/PROGRESS.md` の変更がある場合はそれも含める） +2. `git commit -m "{コミットメッセージ}"` でコミットする +3. `.claude/commit-context.md` が存在する場合は削除する + +## ステップ 6: プッシュ・PR・マージ + +$ARGUMENTS に以下のキーワードが含まれる場合のみ，該当する操作を実行する． +**いずれも含まれない場合はこのステップ全体をスキップする．** + +| キーワード | 実行する操作 | +| --- | --- | +| `push` | プッシュ・PR 作成 | +| `merge` | プッシュ・PR 作成・マージ・プル（`push` を含む全操作） | + +### プッシュ・PR 作成 + +1. `git push origin {ブランチ名}` でリモートにプッシュする +2. PR の状態を確認する: + - **既存の PR がある場合**: PR の URL を表示して完了 + - **PR がない場合**: GUIDE_04 の「プルリクエスト (PR) の作成」に従い PR を作成し，URL を表示する + +### マージ・プル（`merge` の場合のみ） + +1. GUIDE_04 の「マージの実行」に従いマージする +2. GUIDE_04 の「ローカル環境のクリーンアップ」に従いローカルを最新化する + +## 注意事項 + +- `.env` やクレデンシャルファイルはステージングしない +- 変更がない場合（`git status` がクリーン）は空コミットせず，その旨を伝えて終了する diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md new file mode 100644 index 0000000..aec0281 --- /dev/null +++ b/.claude/commands/implement.md @@ -0,0 +1,104 @@ +--- +name: implement +model: opus +description: "実装パイプラインを開始する．コーディング → テスト → リファクタリングの順で 3 つのエージェントを実行し，必要に応じて人間の確認を挟む．" +argument-hint: "<タスク内容>" +--- + +あなたはオーケストレーターです． +GUIDE_05（エージェント運用ルール）を読み，パイプラインのルールを理解した上で以下の手順を実行してください． + +## 前提確認 (Pre-check) + +1. 現在のブランチを確認する（`git branch --show-current`） +2. `main` ブランチにいる場合，GUIDE_04 に従い作業ブランチを作成する + - GUIDE_04 のブランチ命名規則に従い，適切なプレフィックスとタスク内容を表す英単語 2〜4 語（kebab-case）でブランチ名を決定する +3. 実装対象のタスクを確認する: $ARGUMENTS + +## Phase 1: コーディング (Coder) + +coder エージェントに以下を委譲する: + +「以下のタスクを実装してください: $ARGUMENTS」 + +Coder の出力（実装サマリー）を記録し，ユーザーに提示する: + +「**Phase 1（コーディング）が完了しました．** + +{Coder の実装サマリー} + +ブラウザや実機で動作を確認してください． +- **OK** → 次のフェーズ（テスト）に進みます +- **NG** → 問題点を教えてください．修正します」 + +ユーザーの OK を得るまで Phase 2 に進まないこと． +NG の場合は coder エージェントに修正を委譲し，再度確認を依頼する． + +## Phase 2: テスト (Tester) + +tester エージェントに以下を委譲する: + +「直前の実装に対するテストを仕様ベースで作成・実行してください． + +実装サマリー: +{Coder の出力}」 + +Tester の出力（テストサマリー）を記録し，テスト結果に応じて分岐する: + +- **全テスト成功**: テストサマリーを表示し，自動的に Phase 3 に進む． +- **テスト失敗あり**: ユーザーに以下を提示し，判断を仰ぐ． + +「**Phase 2（テスト）でテスト失敗がありました．** + +{Tester のテストサマリー} + +テスト失敗の原因を判断してください: +- **仕様の問題** → 仕様の修正方針を教えてください +- **実装の問題** → coder エージェントに修正を委譲します +- **テストの問題** → tester エージェントに修正を委譲します」 + +ユーザーの指示に従い対応した後，再度テストを実行して全テスト成功を確認してから Phase 3 に進む． + +## Phase 3: リファクタリング (Refactorer) + +refactorer エージェントに以下を委譲する: + +「直前の実装・テスト後のコードをリファクタリングしてください． + +実装サマリー: +{Coder の出力} + +テストサマリー: +{Tester の出力}」 + +Refactorer の出力（リファクタリングサマリー）を記録し，確認を挟まず Phase 4 に進む． + +## Phase 4: ドキュメント更新 (Documentation) + +GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を必要に応じて更新する．進捗を記録する場合は GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` に詳細を末尾追記．`git log` で取れる詳細は書かない）． + +Phase 4 の結果を `.claude/commit-context.md` に書き出す: + +```markdown +# commit-context +- docs_updated: true/false +- claude_md_updated: true/false +- progress_md_updated: true/false +- note: （更新不要の理由や更新内容の要約） +``` + +ドキュメントを更新した場合のみ，ユーザーに提示する: + +「**Phase 4（ドキュメント更新）が完了しました．** + +{更新したドキュメントの一覧と変更内容の要約} + +確認をお願いします． +- **OK** → `/commit` でコミットできます +- **NG** → 修正点を教えてください」 + +更新不要と判断した場合は，確認を挟まず完了処理に進む． + +## 完了処理 (Finalization) + +「全フェーズが完了しました．`/commit` でコミットしてください．」 diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md new file mode 100644 index 0000000..fcfb723 --- /dev/null +++ b/.claude/commands/setup.md @@ -0,0 +1,81 @@ +--- +name: setup +model: opus +description: "GUIDE_01 に従い，プロジェクトの立ち上げを対話的に進める．各フェーズでユーザーの確認を挟む．" +argument-hint: "<プロジェクト名>" +--- + +あなたはプロジェクト立ち上げのファシリテーターです． +GUIDE_01（プロジェクト立ち上げフロー）を読み，各フェーズのルールを理解した上で以下の手順を実行してください． + +## 基本ルール + +- 各フェーズの成果物をユーザーが承認してから次のフェーズに進むこと +- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗（最新 1 行）と `docs/PROGRESS.md`（追記）を更新して中断する +- ドキュメントは GUIDE_02（ドキュメント作成ガイド）と GUIDE_03（ファイル命名規則）に従って作成する +- 成果物のドラフトを提示し，ユーザーの修正指示を反映してからファイルに書き出す +- フォルダは成果物を実際に書き出すときにのみ作成する．空のカテゴリフォルダを先回りで作らない + +## 前提確認 (Pre-check) + +1. CLAUDE.md がテンプレート初期状態（タイトルが `# プロジェクト名` のまま）か確認する +2. **初期状態の場合（新規プロジェクト立ち上げ）:** + - プロジェクト名を確定する（引数 `$ARGUMENTS` があればそれを使用，なければユーザーに確認） + - プロジェクト概要（1〜2 行）をユーザーに確認する + - CLAUDE.md の以下を書き換える: + - 1 行目の `# プロジェクト名` → `# {確定したプロジェクト名}` + - 3 行目の `` → 概要テキスト +3. CLAUDE.md の「開発進捗」と `docs/PROGRESS.md` を確認し，どのフェーズから再開するか判断する +4. 初回の場合はフェーズ 1 から開始する + +## フェーズ 1〜6: 各フェーズの実行 + +GUIDE_01 に定義された各フェーズを順番に実行する． +各フェーズで以下の手順を繰り返す: + +1. GUIDE_01 の該当フェーズを参照し，目的・成果物・役割分担を確認する +2. ユーザーとの対話で情報を収集する +3. 成果物のドラフトを作成し，ユーザーに提示する +4. 承認を得てから GUIDE_01 に記載された保存先に書き出す + +### 台詞テンプレート + +「**フェーズ {N}（{フェーズ名}）のドラフトです．** + +{ドラフト内容} + +修正点があれば指示してください．OKであれば {保存先} に保存して次のフェーズに進みます．」 + +### フォルダ作成の注意 + +成果物を書き出すフォルダのみ作成する．GUIDE_03 のカテゴリ表は「あり得るカテゴリの一覧」であり，立ち上げ時に全カテゴリのフォルダを scaffold するものではない．GUIDE_01 の立ち上げフェーズで成果物が発生するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` のみ．`05_TECH/`（技術設計）と `06_TEST/`（テスト）は立ち上げ時には成果物が無いため，空フォルダを作らない（実装フェーズで必要になった時点で作成する）． + +### フェーズ 3（環境構築）の注意 + +外部サービスの設定（アカウント作成，コンソール操作等）はユーザー自身が行う．手順書に記載するが，AI が実行しないこと． + +## フェーズ 7: 実装開始 + +1. GUIDE_01 の「CLAUDE.md の管理」セクションに従い，CLAUDE.md を最終更新する +2. 作成した全ドキュメントの一覧を表示する +3. 最初の実装ステップを確認する + +「**全フェーズが完了しました．** + +作成したドキュメント: +{ドキュメント一覧} + +CLAUDE.md を更新しました． +最初の実装ステップは `{ステップ名}` です．`/implement {タスク}` で開始できます．」 + +## 中断時の処理 + +ユーザーが中断を希望した場合: + +1. 現在のフェーズと状態を CLAUDE.md の「開発進捗」（最新 1 行に上書き）と `docs/PROGRESS.md`（末尾に追記）に記録する +2. 次回 `/setup` 実行時に続きから再開できるようにする + +「**進捗を保存しました．** + +現在の状態: フェーズ {N}（{フェーズ名}）まで完了 +次回 `/setup` を実行すると，フェーズ {N+1} から再開します．」 diff --git a/.claude/hooks/restrict_repo_access.py b/.claude/hooks/restrict_repo_access.py new file mode 100644 index 0000000..36bfe96 --- /dev/null +++ b/.claude/hooks/restrict_repo_access.py @@ -0,0 +1,117 @@ +"""PreToolUse hook: リポジトリ外のファイルアクセスをブロックする.""" + +import json +import os +import re +import shlex +import sys + +# Bash で検出する破壊的コマンド +DESTRUCTIVE_COMMANDS = {"rm", "rmdir", "mv", "cp", "chmod", "chown", "unlink"} + + +def get_target_path(tool_name: str, tool_input: dict) -> str | None: + """ツールの種類に応じてチェック対象のパスを取得する.""" + if tool_name in ("Read", "Write", "Edit"): + return tool_input.get("file_path") + if tool_name in ("Glob", "Grep"): + return tool_input.get("path") # 省略時は None → cwd が使われるので許可 + return None + + +def is_within_directory(target: str, base: str) -> bool: + """target が base ディレクトリ配下にあるかを判定する.""" + real_target = os.path.realpath(target) + real_base = os.path.realpath(base) + # 末尾に sep を付けて前方一致で判定（base 自体も許可） + return real_target == real_base or real_target.startswith(real_base + os.sep) + + +def check_bash_command(command: str, cwd: str) -> str | None: + """Bash コマンド内の破壊的操作がリポジトリ外を対象としていないかチェックする. + + リポジトリ外のパスに対する破壊的コマンドを検出した場合、理由文字列を返す。 + 問題なければ None を返す。 + """ + # セミコロン、&&、|| やパイプで分割された各部分をチェック + parts = re.split(r"[;&|]+", command) + for part in parts: + part = part.strip() + if not part: + continue + try: + tokens = shlex.split(part) + except ValueError: + # クォートが閉じていない等のパースエラーは無視して続行 + continue + if not tokens: + continue + # コマンド名を取得（env, sudo 等のプレフィックスをスキップ） + cmd_name = None + for token in tokens: + if token in ("sudo", "env") or "=" in token: + continue + cmd_name = os.path.basename(token) + break + if cmd_name not in DESTRUCTIVE_COMMANDS: + continue + # 破壊的コマンドの引数からパスを抽出してチェック + for token in tokens[1:]: + if token.startswith("-"): + continue + # 絶対パスまたは .. を含むパスをチェック + if os.path.isabs(token) or ".." in token: + resolved = os.path.realpath(os.path.join(cwd, token)) + if not is_within_directory(resolved, cwd): + return ( + f"リポジトリ外への破壊的操作をブロックしました: " + f"`{cmd_name}` が `{token}` を対象としています" + ) + return None + + +def deny(reason: str) -> None: + """ブロック用の JSON を出力して終了する.""" + result = { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": reason, + } + } + json.dump(result, sys.stdout) + sys.exit(0) + + +def main() -> None: + data = json.load(sys.stdin) + tool_name = data.get("tool_name", "") + tool_input = data.get("tool_input", {}) + cwd = data.get("cwd", os.getcwd()) + + # Bash ツールの破壊的コマンドチェック + if tool_name == "Bash": + command = tool_input.get("command", "") + reason = check_bash_command(command, cwd) + if reason: + deny(reason) + sys.exit(0) + + # Read/Write/Edit/Glob/Grep のパスチェック + target_path = get_target_path(tool_name, tool_input) + + # パスが指定されていない場合は許可（Glob/Grep の path 省略時など） + if target_path is None: + sys.exit(0) + + if not is_within_directory(target_path, cwd): + deny( + f"リポジトリ外のパスへのアクセスはブロックされました: {target_path}" + ) + + # リポジトリ内なので許可 + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..3b0ffd7 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Read|Write|Edit|Glob|Grep|Bash", + "hooks": [ + { + "type": "command", + "command": "python .claude/hooks/restrict_repo_access.py" + } + ] + } + ] + } +} diff --git a/.claude/template-sync-sha b/.claude/template-sync-sha new file mode 100644 index 0000000..411938e --- /dev/null +++ b/.claude/template-sync-sha @@ -0,0 +1 @@ +324af3cdca8cc0c1390972c0d3aaeaa2c240e50f diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.gitignore b/.gitignore index f710825..1a10b53 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,6 @@ # NuGet パッケージ packages/ + +# --- from template (sync-template) --- +.claude/commit-context.md diff --git a/CLAUDE.md b/CLAUDE.md index f432105..cfdc591 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,8 +4,8 @@ ## 開発進捗 -現在の進捗: GUIDE_01 に従いプロジェクト立ち上げ中 -※ ステップ完了時にここを更新すること． +最新: GUIDE_01 に従いプロジェクト立ち上げ中 +※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴（動機・設計判断・失敗パターン）は [docs/PROGRESS.md](docs/PROGRESS.md) に追記する．運用ルールは GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」を参照． ## 必須ルール（コード実装時） @@ -13,9 +13,16 @@ ### Git 運用（GUIDE_04 準拠） -- ブランチ名: `feature/`/`fix/`/`docs/`/`chore/` + 英単語 2〜4 語（kebab-case） -- コミットメッセージ: `[add]`/`[update]`/`[fix]`/`[remove]`/`[clean]` + 日本語 -- コミット・push 後は `gh pr create` で PR を作成する +- ブランチ名・コミットメッセージの書式は GUIDE_04 に従う +- コミットは `/commit` を使用する（push・PR 作成は `/commit push`） +- **`/commit` はユーザーが明示的に指示した時のみ実行する．Claude が自発的に `/commit` や `git commit` を呼んではならない**（`/implement` 完了後も，案内するだけで自分ではコミットしない） + +### エージェントチーム（GUIDE_05 準拠） + +- 実装は `/implement <タスク>` で開始する（コーディング → テスト → リファクタリング → ドキュメント更新） +- Phase 1 後に人間が動作確認，Phase 2 でテスト失敗時のみ方針判断 +- Phase 2 成功後は Phase 3 → Phase 4 まで自動で進む（Phase 4 で更新がある場合のみ確認） +- テスト・リファクタリングをスキップしない ### 手動確認が必要な作業（自分で完了させないこと） @@ -36,6 +43,7 @@ - ドキュメント作成規約: docs/01_GUIDE/GUIDE_02_ドキュメント作成ガイド.md - ファイル命名規則: docs/01_GUIDE/GUIDE_03_ファイル命名規則.md - Git 運用ルール: docs/01_GUIDE/GUIDE_04_Git運用ルール.md +- エージェント運用ルール: docs/01_GUIDE/GUIDE_05_エージェント運用ルール.md - ※ コーディング規約，テスト方針等はプロジェクト立ち上げ時に作成する（GUIDE_01 参照） ### 02_ENV（環境） @@ -49,3 +57,11 @@ ### 04_SPEC（仕様・設計） + +### 05_TECH（技術設計） + + + +### 06_TEST（テスト） + + diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" index f9aa80e..a6f9a0c 100644 --- "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -15,6 +15,8 @@ | 開発計画 | ステップを分割し，開発順序を決める | `PLAN_02_開発ステップ.md` | | 実装開始 | 開発計画に沿って実装を進める | ソースコード | +※ 立ち上げフローで作成するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` カテゴリの成果物のみ．`05_TECH`（技術設計）・`06_TEST`（テスト）は実装フェーズで必要になった時点で作成し，立ち上げ時に空フォルダを作らない． + ## 方針決定 (Direction) プロジェクトの全体像を明確にする． @@ -56,18 +58,18 @@ ## 規約整備 (Coding Standards) 技術スタックに応じたコーディング規約やプロジェクト固有のガイドを作成する． -汎用ガイド（GUIDE_01〜04）は本テンプレートに含まれている．ここではプロジェクト固有の規約を追加する． +汎用ガイド（GUIDE_01〜05）は本テンプレートに含まれている．ここではプロジェクト固有の規約を追加する． - **基本方針**: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る（例: Effective Dart，PEP 8，Google Style Guide 等）．プロジェクト固有のルールは標準と異なる部分のみ定義する． - **人間が決めること**: 標準規約でカバーされない判断（アーキテクチャパターンの選択等） - **AI に依頼できること**: 標準規約を踏まえた規約のドラフト作成，参照元ガイドラインの調査 -- **作成すべきガイド**: - - コーディング規約 — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則 - - ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール - - テスト方針 — テストの種類，粒度，実行タイミング，カバレッジ基準 - - エラーハンドリング方針 — エラーの分類，処理方法，ログ出力の方針 - - リファクタリング方針 — リファクタリングの判断基準，実施タイミング - - 機能実装完了フロー — コミット前のチェックリスト（フォーマット，静的解析，テスト，レビュー等） +- **作成すべきガイド**（推奨番号は GUIDE_03 に準拠）: + - `GUIDE_06` コーディング規約 — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則 + - `GUIDE_07` ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール + - `GUIDE_08` テスト方針 — テストの種類，粒度，実行タイミング，カバレッジ基準，モック方針，テストファイルの配置規則 + - `GUIDE_09` エラーハンドリング方針 — エラーの分類，処理方法，ログ出力の方針 + - ※ リファクタリング方針は言語に依存しないため，`.claude/agents/refactorer.md` の判断基準を共通ルールとして使用する + - ※ 機能実装完了フローは GUIDE_05 と `/implement` で定義済みのため，別途作成しない ## 開発計画 (Development Plan) @@ -84,11 +86,6 @@ - 各ステップの完了時に [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) と [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する． - 仕様変更が発生した場合は，先にドキュメントを更新してから実装に反映する． -### ドキュメントの書き方 - -- コード内ドキュメント（JSDoc・コメント）と docs/ ドキュメントの書き方は [GUIDE_05_コーディング規約](GUIDE_05_コーディング規約.md) の「ドキュメント」セクションを参照 -- 仕様・設計の変更がある場合は `docs/` を先に更新してから実装に反映する - ## CLAUDE.md の管理 (CLAUDE.md Management) `CLAUDE.md` は AI が会話開始時に最初に読むファイルであり，プロジェクトの引継ぎ情報を一元管理する． @@ -97,17 +94,18 @@ ### 記載すべき内容 - **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 -- **開発進捗**: 現在のステップ，次にやること +- **開発進捗**: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は `docs/PROGRESS.md` に追記する（[GUIDE_05](GUIDE_05_エージェント運用ルール.md) の「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」参照） - **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） - **ドキュメント一覧**: docs/ 内のファイルへの参照パス ### 更新タイミング -- ステップの完了時に開発進捗を更新する +- ステップの完了時に開発進捗を更新する（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` は末尾に追記） - ドキュメントの追加・削除・リネーム時に参照パスを更新する - 必須ルールに変更があった場合に反映する ### 運用上の注意 - CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． +- 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / `docs/PROGRESS.md` = 追記型フルログ）で管理する．詳細は [GUIDE_05](GUIDE_05_エージェント運用ルール.md) を参照． - プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する． diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..2936c2a --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,192 @@ +# エージェント運用ルール (Agent Operation Rules) + +実装品質を担保するために，3 つの専門エージェントを用いた開発パイプラインを定義する． + +## 基本方針 (Basic Policy) + +- 「実装完了」とは，コーディング・テスト・リファクタリングの全フェーズが完了した状態を指す． +- 各フェーズは専門エージェントが担当し，フレッシュなコンテキストでレビューする． +- フェーズのスキップは原則禁止する．リファクタリング不要の判断は Refactorer エージェント自身が行う． +- 各フェーズ間で人間が確認・判断を行う． + +## エージェント一覧 (Agent List) + +| エージェント | 役割 | フェーズ | +| --- | --- | --- | +| `coder` | 機能実装・バグ修正 | Phase 1 | +| `tester` | 仕様ベースのテスト作成・実行 | Phase 2 | +| `refactorer` | コード品質の改善 | Phase 3 | + +## 実装パイプライン (Implementation Pipeline) + +### 開始方法 + +```bash +/implement <タスク内容> +``` + +### 全体フロー + +``` +人間: /implement <タスク内容> + │ + ├─ ブランチ作成（GUIDE_04 準拠） + │ + ├─ Phase 1 ──▶ [Coder] + │ 実装に集中．テスト・リファクタは行わない + │ + ├─ 人間の確認ポイント 1 + │ ブラウザ/実機で動作確認 + │ OK → 続行 / NG → フィードバックして修正 + │ + ├─ Phase 2 ──▶ [Tester] + │ 仕様ベースでテスト作成・実行 + │ + ├─ Phase 2 完了後の分岐 + │ 全テスト成功 → 自動で Phase 3 へ + │ テスト失敗 → 人間に報告し判断を仰ぐ + │ + ├─ Phase 3 ──▶ [Refactorer] + │ テストを安全網としてリファクタリング + │ テスト再実行で挙動が変わっていないことを保証 + │ + ├─ Phase 4 ──▶ ドキュメント更新 + │ docs/, CLAUDE.md, docs/PROGRESS.md を必要に応じて更新 + │ 更新がある場合のみ人間の確認を挟む + │ 結果を .claude/commit-context.md に書き出す + │ + └─ 完了 → /commit でコミット +``` + +### Phase 1: コーディング (Coding) + +- Coder エージェントが `docs/` を読んで実装する． +- 実装完了後，実装サマリーを出力する． +- テストやリファクタリングは行わない． +- コミットはしない． + +### 人間の確認ポイント 1 + +- ブラウザ・実機での動作確認（AI にはできない確認）． +- 問題があればフィードバックし，Coder に修正を指示する． + +### Phase 2: テスト (Testing) + +- Tester エージェントが仕様（`docs/04_SPEC/`）を基準にテストを作成する． +- テストは実装コードではなく**仕様**を基準に書く． +- 実装が仕様と異なればテストが失敗し，バグを検出する． + +### Phase 2 完了後の分岐 + +- **全テスト成功**: テストサマリーを表示し，自動的に Phase 3 に進む． +- **テスト失敗あり**: 人間に報告し，判断を仰ぐ． + - 仕様の問題 → 仕様を修正 + - 実装の問題 → Coder に修正を委譲 + - テストの問題 → Tester に修正を委譲 + +### Phase 3: リファクタリング (Refactoring) + +- Refactorer エージェントがテストを安全網としてコード品質を改善する． +- 挙動は変更しない． +- リファクタリング後にテストを再実行し，全テストが通ることを確認する． +- リファクタリング不要と判断した場合は，理由を明示して終了する． + +### Phase 4: ドキュメント更新 (Documentation) + +Phase 3 完了後，実装内容に応じて `docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を更新する． + +- **チェック観点**: + - API・データ構造の変更 → `docs/04_SPEC/` の該当仕様を更新 + - 環境・依存関係の変更 → `docs/02_ENV/` を更新 + - 開発ステップの進捗 → `docs/03_PLAN/` や進捗記録（`CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md`）を更新（書式は本ガイドの「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う．`git log` で取れる詳細は書かない） + - 規約・運用ルールの変更 → `docs/01_GUIDE/` を更新 +- **該当なし**: ドキュメント更新が不要な変更（軽微なバグ修正，リファクタリングのみ等）はスキップ可． +- **更新がある場合のみ**人間の確認を挟む．更新不要の場合は確認なしで完了処理に進む． +- **コミットコンテキストの書き出し**: Phase 4 の結果（更新の有無と理由）を `.claude/commit-context.md` に書き出す．このファイルは `/commit` が参照し，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップするために使う（`.gitignore` 対象）． + +### 完了処理 + +- `/implement` はコミットを行わない．完了後は `/commit` でコミットする． +- `/commit` は `.claude/commit-context.md` が存在する場合，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップする．存在しない場合（`/implement` を経由していない場合）は警告のみ行う． + +## コンテキスト受け渡し (Context Passing) + +各エージェントは前フェーズのサマリーを入力として受け取る．加えて `git diff` で実際の変更差分を自ら確認する． + +| フェーズ | 受け取る情報 | +| --- | --- | +| Coder | タスク内容 | +| Tester | Coder の実装サマリー + git diff | +| Refactorer | Coder + Tester のサマリー + git diff | + +## 人間の役割 (Human's Role) + +| タイミング | 人間がやること | +| --- | --- | +| 開始時 | タスクの指示（`/implement <何をするか>`） | +| Phase 1 後 | 動作確認（ブラウザ・実機など AI にできない確認） | +| Phase 2 後 | テスト失敗時のみ方針判断（全成功なら自動で Phase 3 へ） | +| Phase 4 後 | ドキュメント更新がある場合のみ確認 → `/commit` でコミット | + +人間の本質的な役割は「AI にできない判断と確認」であり，各フェーズの品質のゲートキーパーとなる． + +## コミットルール (Commit Rules) + +パイプライン完了後は `/commit` でコミットする．コミットメッセージのタグ等は [GUIDE_04](GUIDE_04_Git運用ルール.md) に従う． + +※ リファクタリングとテストは実装と一体の成果物として，まとめてコミットする．必要に応じて分割コミットも可． + +## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） + +進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する． + +| ファイル | 役割 | 更新方法 | +| --- | --- | --- | +| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き | +| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 | + +**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない． + +### CLAUDE.md「開発進捗」の書き方 + +- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい） +- 基本形式: `最新: <ステップ見出し>` +- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる） + +### docs/PROGRESS.md の書き方 + +`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）． + +**書く（PROGRESS.md に残す価値が高いもの）**: + +以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない． + +- 状況: 何が完了したか（1 行） +- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など） +- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき +- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する +- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ + +**書かない（コミットメッセージと `git log` に任せる）**: + +以下は `git log ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． + +- 関数名・引数・型シグネチャ +- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） +- リファクタリングの手順詳細 +- 撤去・新規追加の関数リスト +- 具体的な定数値・閾値（設計判断の核心に関わるものを除く） +- 数値範囲の細部（実装パラメータ等） +- 後方互換性の細かい仕様 +- 「全テスト N passed」の報告（pass している前提のため不要） + +**長さと書式**: + +- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする +- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 +- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない +- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する + +**既存エントリの長文化に気付いたとき**: + +過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと． diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md new file mode 100644 index 0000000..14ea2fc --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,11 @@ +# 開発進捗ログ + +