diff --git a/.claude/commands/code-review.md b/.claude/commands/development/code-review.md similarity index 100% rename from .claude/commands/code-review.md rename to .claude/commands/development/code-review.md diff --git a/.claude/commands/debug-help.md b/.claude/commands/development/debug-help.md similarity index 100% rename from .claude/commands/debug-help.md rename to .claude/commands/development/debug-help.md diff --git a/.claude/commands/refactor.md b/.claude/commands/development/refactor.md similarity index 100% rename from .claude/commands/refactor.md rename to .claude/commands/development/refactor.md diff --git a/.claude/commands/docs-gen.md b/.claude/commands/documentation/docs-gen.md similarity index 100% rename from .claude/commands/docs-gen.md rename to .claude/commands/documentation/docs-gen.md diff --git a/.claude/commands/setup-project.md b/.claude/commands/project-management/setup-project.md similarity index 100% rename from .claude/commands/setup-project.md rename to .claude/commands/project-management/setup-project.md diff --git a/.claude/commands/test-gen.md b/.claude/commands/testing/test-gen.md similarity index 100% rename from .claude/commands/test-gen.md rename to .claude/commands/testing/test-gen.md diff --git a/.serena/.gitignore b/.serena/.gitignore new file mode 100644 index 0000000..14d86ad --- /dev/null +++ b/.serena/.gitignore @@ -0,0 +1 @@ +/cache diff --git a/.serena/project.yml b/.serena/project.yml new file mode 100644 index 0000000..5000ed8 --- /dev/null +++ b/.serena/project.yml @@ -0,0 +1,67 @@ +# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby) +# * For C, use cpp +# * For JavaScript, use typescript +# Special requirements: +# * csharp: Requires the presence of a .sln file in the project folder. +language: bash + +# whether to use the project's gitignore file to ignore files +# Added on 2025-04-07 +ignore_all_files_in_gitignore: true +# list of additional paths to ignore +# same syntax as gitignore, so you can use * and ** +# Was previously called `ignored_dirs`, please update your config if you are using that. +# Added (renamed) on 2025-04-07 +ignored_paths: [] + +# whether the project is in read-only mode +# If set to true, all editing tools will be disabled and attempts to use them will result in an error +# Added on 2025-04-18 +read_only: false + +# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details. +# Below is the complete list of tools for convenience. +# To make sure you have the latest list of tools, and to view their descriptions, +# execute `uv run scripts/print_tool_overview.py`. +# +# * `activate_project`: Activates a project by name. +# * `check_onboarding_performed`: Checks whether project onboarding was already performed. +# * `create_text_file`: Creates/overwrites a file in the project directory. +# * `delete_lines`: Deletes a range of lines within a file. +# * `delete_memory`: Deletes a memory from Serena's project-specific memory store. +# * `execute_shell_command`: Executes a shell command. +# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced. +# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). +# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). +# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. +# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. +# * `initial_instructions`: Gets the initial instructions for the current project. +# Should only be used in settings where the system prompt cannot be set, +# e.g. in clients you have no control over, like Claude Desktop. +# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. +# * `insert_at_line`: Inserts content at a given line in a file. +# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. +# * `list_dir`: Lists files and directories in the given directory (optionally with recursion). +# * `list_memories`: Lists memories in Serena's project-specific memory store. +# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). +# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). +# * `read_file`: Reads a file within the project directory. +# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. +# * `remove_project`: Removes a project from the Serena configuration. +# * `replace_lines`: Replaces a range of lines within a file with new content. +# * `replace_symbol_body`: Replaces the full definition of a symbol. +# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. +# * `search_for_pattern`: Performs a search for a pattern in the project. +# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. +# * `switch_modes`: Activates modes by providing a list of their names +# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. +# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. +# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. +# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. +excluded_tools: [] + +# initial prompt for the project. It will always be given to the LLM upon activating the project +# (contrary to the memories, which are loaded on demand). +initial_prompt: "" + +project_name: "SmartPhoneAutoDevelopSetup" diff --git a/CLAUDE.md b/CLAUDE.md index a8dbaa4..1e04a60 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,12 +6,20 @@ ## 開発ルール - **共通ルール**: 変数命名、コードスタイル、コメントの書き方はプロジェクト内で統一する。 -- **テスト駆動開発（TDD）** を基本とする。 +- **Spec Kit + TDD統合開発**: 仕様駆動開発とテスト駆動開発を組み合わせた開発フローを採用する。 - **Issue Driven 開発**: すべての開発はIssueから開始し、Issueに紐づけて進める。 - **MCPツールの使用必須**: 開発作業は基本的にMCPのツールを使用する。 - **Formatter/Linter実行**: コード整形や静的解析はClaude CodeのHooksから自動実行すること。 +- **プロジェクト憲法遵守**: 開発原則の一貫した適用と品質ゲートの確実な実行。 - **CLAUDE.mdの改善**: 開発を始める際には、READMEやIssueを参照して、そのプロジェクト用にCLAUDE.mdを必要に応じて改善する。 +### Spec Kit + TDD 開発フロー +1. **仕様作成** (`/specify`) - 自然言語から正式仕様を作成 +2. **計画立案** (`/plan`) - 技術選定と実装計画 +3. **タスク生成** (`/tasks`) - TDD準拠のタスクリスト作成 +4. **TDD実装** (`/implement`) - Red-Green-Refactorサイクル +5. **品質確認** (`/code-review`, `/constitution`) - 品質とプロジェクト憲法への準拠確認 + ## 構成 - `.github/workflows/claude.yml` : Claude Codeを動作させるワークフロー - `README.md` : プロジェクト概要と開発ガイド @@ -19,8 +27,13 @@ - `.claude/commands/` : カスタムスラッシュコマンド定義 - `.claude/agents/` : 専門サブエージェント定義 - `.claude/hooks/` : コード検証・整形スクリプト +- `.specify/` : Spec Kit設定・テンプレート・実行スクリプト + +### ドキュメント - `docs/COMMANDS.md` : スラッシュコマンド詳細ガイド - `docs/AGENTS.md` : サブエージェント詳細ガイド +- `docs/SPEC_KIT_TDD_WORKFLOW.md` : Spec Kit + TDD統合ワークフロー +- `docs/GITHUB_ACTIONS_SETUP.md` : GitHub Actions設定ガイド ## 設定・制約 - 依存ライブラリの追加は最小限にとどめる。 @@ -28,7 +41,20 @@ ## カスタムスラッシュコマンド 以下のスラッシュコマンドが利用可能です： + +### プロジェクト管理 - `/setup-project` - プロジェクトの初期セットアップ + +### Spec Kit統合コマンド（仕様駆動開発） +- `/specify` - 自然言語から仕様作成 +- `/plan` - 仕様から実装計画作成 +- `/clarify` - 仕様の対話的明確化 +- `/tasks` - TDD準拠のタスクリスト生成 +- `/implement` - TDDサイクルでの実装 +- `/analyze` - 既存仕様の分析 +- `/constitution` - プロジェクト憲法管理 + +### 開発支援 - `/code-review` - コード品質分析とレビュー - `/debug-help` - デバッグ支援とエラー分析 - `/refactor` - コードリファクタリングと改善 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 1601178..2857770 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -4,7 +4,189 @@ ## 利用可能なサブエージェント -再編集 +### `rust-expert` - Rust開発専門家 + +**専門分野**: +- Rustの所有権システムとライフタイム管理 +- パフォーマンス最適化とメモリ効率 +- 非同期プログラミング（async/await、tokio） +- システムプログラミング・WebAssembly開発 +- Cargoエコシステム + +**実行可能タスク**: +- Rustプロジェクトの設計・実装 +- 所有権エラーの解決 +- パフォーマンス分析とボトルネック解決 +- クレート選定と統合 +- テストコード作成（unit、integration、doc tests） +- Clippyワーニング修正 +- Unsafe Rustコードレビュー + +**使用例**: +```bash +@claude rust-expert: 所有権エラーを修正してください +@claude rust-expert: tokioを使った非同期処理を実装 +@claude rust-expert: パフォーマンス最適化を行ってください +``` + +**開発ツール**: +- cargo（build、test、clippy、fmt） +- rustdoc、cargo-audit、cargo-tarpaulin +- flamegraph（プロファイリング） + +--- + +### `web-developer` - Web開発専門家 + +**専門分野**: +- フロントエンド開発（React、Vue、Angular等） +- バックエンドAPI設計・実装 +- レスポンシブデザイン・UI/UX +- Web パフォーマンス最適化 +- SEO・アクセシビリティ + +**実行可能タスク**: +- SPAアプリケーション開発 +- REST/GraphQL API設計 +- レスポンシブWebデザイン +- PWA（Progressive Web App）開発 +- Webパフォーマンス分析・改善 +- Cross-browserテスト + +**使用例**: +```bash +@claude web-developer: レスポンシブデザインを実装してください +@claude web-developer: REST APIを設計・実装 +@claude web-developer: PWA化してください +``` + +**技術スタック**: +- Frontend: React/Vue/Angular、TypeScript +- Backend: Node.js、Express、FastAPI +- Database: PostgreSQL、MongoDB +- Tools: Webpack、Vite、ESLint + +--- + +### `mobile-developer` - モバイルアプリ開発専門家 + +**専門分野**: +- iOS開発（Swift、UIKit、SwiftUI） +- Android開発（Kotlin、Jetpack Compose） +- クロスプラットフォーム（React Native、Flutter） +- モバイル設計パターン・アーキテクチャ +- アプリストア最適化 + +**実行可能タスク**: +- ネイティブモバイルアプリ開発 +- クロスプラットフォームアプリ開発 +- モバイル特化UI/UX実装 +- プッシュ通知・バックグラウンド処理 +- アプリ最適化・パフォーマンス改善 +- アプリストア申請準備 + +**使用例**: +```bash +@claude mobile-developer: iOS アプリのUIを実装してください +@claude mobile-developer: プッシュ通知機能を追加 +@claude mobile-developer: Flutter でクロスプラットフォームアプリを作成 +``` + +--- + +### `devops-engineer` - DevOpsとインフラ専門家 + +**専門分野**: +- CI/CDパイプライン設計・構築 +- コンテナ化（Docker、Kubernetes） +- クラウドインフラ（AWS、GCP、Azure） +- Infrastructure as Code（Terraform、CloudFormation） +- 監視・ログ管理システム + +**実行可能タスク**: +- GitHub Actions/GitLab CI設定 +- Docker化・Kubernetes設定 +- クラウドインフラ設計・構築 +- 監視・アラート設定 +- セキュリティ設定・脆弱性対応 +- デプロイメント自動化 + +**使用例**: +```bash +@claude devops-engineer: CI/CDパイプラインを設定してください +@claude devops-engineer: Kubernetesにデプロイできるよう設定 +@claude devops-engineer: 監視システムを構築 +``` + +**インフラツール**: +- Container: Docker、Kubernetes +- Cloud: AWS、GCP、Azure +- IaC: Terraform、Ansible +- Monitoring: Prometheus、Grafana + +--- + +### `data-scientist` - データサイエンスと機械学習専門家 + +**専門分野**: +- 機械学習モデル設計・実装 +- データ分析・可視化 +- 統計解析・予測モデリング +- MLOps・モデルデプロイメント +- ビッグデータ処理 + +**実行可能タスク**: +- 機械学習パイプライン構築 +- データクリーニング・前処理 +- 特徴量エンジニアリング +- モデル評価・検証 +- データ可視化・レポート作成 +- A/Bテスト設計・分析 + +**使用例**: +```bash +@claude data-scientist: 予測モデルを構築してください +@claude data-scientist: データ分析とレポート作成 +@claude data-scientist: MLOpsパイプラインを設定 +``` + +**技術スタック**: +- Python: pandas、scikit-learn、PyTorch、TensorFlow +- R: tidyverse、ggplot2、caret +- Big Data: Spark、Hadoop +- Visualization: matplotlib、seaborn、plotly + +--- + +### `security-expert` - セキュリティと脆弱性専門家 + +**専門分野**: +- セキュリティ監査・脆弱性評価 +- ペネトレーションテスト +- セキュアコーディング +- 暗号化・認証システム +- コンプライアンス対応 + +**実行可能タスク**: +- セキュリティ監査・脆弱性スキャン +- セキュアなアーキテクチャ設計 +- 認証・認可システム実装 +- 暗号化機能実装 +- セキュリティテスト実行 +- コンプライアンス準拠確認 + +**使用例**: +```bash +@claude security-expert: 脆弱性を検査してください +@claude security-expert: 認証システムをセキュアに実装 +@claude security-expert: OWASP準拠のセキュリティテスト実行 +``` + +**セキュリティツール**: +- SAST: SonarQube、CodeQL +- DAST: OWASP ZAP、Burp Suite +- 依存関係: Snyk、npm audit +- Container: Trivy、Clair ## 使用時のベストプラクティス diff --git a/docs/CLAUDE_GITHUB_ACTIONS_SPECS.md b/docs/CLAUDE_GITHUB_ACTIONS_SPECS.md new file mode 100644 index 0000000..7617657 --- /dev/null +++ b/docs/CLAUDE_GITHUB_ACTIONS_SPECS.md @@ -0,0 +1,383 @@ +# Claude Code GitHub Actions 仕様書 + +## 概要 +このドキュメントは、仕様駆動開発（Spec Kit）およびテスト駆動開発（TDD）のための Claude Code と GitHub Actions の統合仕様を定義します。 + +## 1. 基本ワークフロー構成 + +### 1.1 ファイル構成 +``` +.github/workflows/ +├── claude-spec-driven.yml # 仕様駆動開発ワークフロー +├── claude-tdd.yml # テスト駆動開発ワークフロー +├── claude-code-review.yml # コードレビューワークフロー +└── claude-integration.yml # 統合ワークフロー +``` + +## 2. 仕様駆動開発ワークフロー + +### 2.1 トリガー条件 +```yaml +name: Spec-Driven Development with Claude Code + +on: + issues: + types: [opened, labeled] + issue_comment: + types: [created] + pull_request: + types: [opened, synchronize] + +# ラベルベースのトリガー +- label: 'spec:new' # 新規仕様作成 +- label: 'spec:update' # 仕様更新 +- label: 'spec:review' # 仕様レビュー +``` + +### 2.2 ワークフロー手順 +```yaml +jobs: + spec-driven-development: + runs-on: ubuntu-latest + if: contains(github.event.issue.labels.*.name, 'spec:') || contains(github.event.comment.body, '@claude /specify') + + steps: + # 1. 環境準備 + - name: Checkout code + uses: actions/checkout@v4 + + # 2. Spec Kit準備 + - name: Setup Spec Kit + run: | + # .specify/ ディレクトリの確認・作成 + mkdir -p .specify/{templates,specs,outputs} + + # 3. Claude Code実行 + - name: Run Claude Code - Specification Phase + uses: anthropics/claude-code-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + claude-api-key: ${{ secrets.CLAUDE_API_KEY }} + commands: | + # 仕様作成フロー + /specify ${{ github.event.issue.title }} + /clarify + /plan + /analyze + + # 4. 仕様書生成・保存 + - name: Save Specifications + run: | + # .specify/specs/ に仕様書を保存 + # タイムスタンプ付きでバックアップ + + # 5. Issue/PRにフィードバック + - name: Update Issue/PR + uses: actions/github-script@v7 + with: + script: | + // 仕様作成結果をIssue/PRにコメント + // 生成された仕様書へのリンク提供 +``` + +### 2.3 コマンド仕様 +```yaml +# 利用可能なSpec Kitコマンド +commands: + - /specify # 自然言語から仕様作成 + - /clarify # 仕様の対話的明確化 + - /plan # 仕様から実装計画作成 + - /analyze # 既存仕様の分析 + - /tasks # TDD準拠のタスクリスト生成 +``` + +## 3. テスト駆動開発ワークフロー + +### 3.1 トリガー条件 +```yaml +name: Test-Driven Development with Claude Code + +on: + pull_request: + types: [opened, synchronize] + issue_comment: + types: [created] + +# TDD特有のトリガー +- comment: '@claude /implement' +- comment: '@claude /test-gen' +- label: 'tdd:red' # Red フェーズ（失敗テスト作成） +- label: 'tdd:green' # Green フェーズ（最小実装） +- label: 'tdd:refactor' # Refactor フェーズ（リファクタリング） +``` + +### 3.2 TDDサイクル実装 +```yaml +jobs: + tdd-cycle: + runs-on: ubuntu-latest + strategy: + matrix: + phase: [red, green, refactor] + + steps: + # Red Phase - 失敗テスト作成 + - name: TDD Red Phase + if: matrix.phase == 'red' + uses: anthropics/claude-code-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + claude-api-key: ${{ secrets.CLAUDE_API_KEY }} + commands: | + /test-gen --failing --spec-based + # 仕様書に基づく失敗テスト生成 + + # Green Phase - 最小実装 + - name: TDD Green Phase + if: matrix.phase == 'green' + uses: anthropics/claude-code-action@v1 + with: + commands: | + /implement --minimal --test-driven + # テストを通す最小限の実装 + + # Refactor Phase - リファクタリング + - name: TDD Refactor Phase + if: matrix.phase == 'refactor' + uses: anthropics/claude-code-action@v1 + with: + commands: | + /refactor --maintain-tests --improve-design + # テストを維持しながら設計改善 + + # テスト実行・検証 + - name: Run Tests + run: | + # プロジェクトに応じたテストコマンド + npm test || cargo test || python -m pytest + + # カバレッジ測定 + - name: Test Coverage + uses: codecov/codecov-action@v3 +``` + +### 3.3 自動フィードバックループ +```yaml + # TDDサイクル自動化 + - name: TDD Feedback Loop + run: | + # Red → Green → Refactor の自動サイクル + if [[ "${{ matrix.phase }}" == "red" ]]; then + # テストが失敗することを確認 + ! npm test && echo "RED_PHASE_SUCCESS=true" >> $GITHUB_ENV + elif [[ "${{ matrix.phase }}" == "green" ]]; then + # テストが成功することを確認 + npm test && echo "GREEN_PHASE_SUCCESS=true" >> $GITHUB_ENV + elif [[ "${{ matrix.phase }}" == "refactor" ]]; then + # リファクタリング後もテストが成功 + npm test && echo "REFACTOR_PHASE_SUCCESS=true" >> $GITHUB_ENV + fi +``` + +## 4. 統合ワークフロー + +### 4.1 Spec Kit + TDD統合 +```yaml +name: Integrated Spec-Driven TDD + +on: + issues: + types: [opened] + pull_request: + types: [opened, synchronize] + +jobs: + integrated-development: + runs-on: ubuntu-latest + + steps: + # フェーズ1: 仕様作成 + - name: Specification Phase + uses: anthropics/claude-code-action@v1 + with: + commands: | + /specify ${{ github.event.issue.title }} + /clarify + /plan + + # フェーズ2: タスク分解 + - name: Task Generation Phase + uses: anthropics/claude-code-action@v1 + with: + commands: | + /tasks --tdd-ready --priority-sorted + + # フェーズ3: TDDサイクル実行 + - name: TDD Implementation Phase + uses: anthropics/claude-code-action@v1 + with: + commands: | + /implement --tdd-cycle --spec-compliant + + # フェーズ4: 品質チェック + - name: Quality Assurance Phase + uses: anthropics/claude-code-action@v1 + with: + commands: | + /code-review --comprehensive + /constitution --compliance-check +``` + +## 5. 環境設定仕様 + +### 5.1 必須シークレット +```yaml +secrets: + CLAUDE_API_KEY: # Claude API キー（必須） + GITHUB_TOKEN: # GitHub アクセストークン（自動設定） + CODECOV_TOKEN: # コードカバレッジ（オプション） +``` + +### 5.2 権限設定 +```yaml +permissions: + contents: write # ファイル読み書き + pull-requests: write # PR操作 + issues: write # Issue操作 + actions: read # ワークフロー状態参照 + statuses: write # ステータス更新 +``` + +### 5.3 環境変数 +```yaml +env: + SPEC_KIT_VERSION: "latest" + TDD_FRAMEWORK: "auto-detect" # jest, pytest, cargo-test など + CLAUDE_MODEL: "claude-3-sonnet-20240229" + WORKFLOW_MODE: "integrated" # spec-only, tdd-only, integrated +``` + +## 6. カスタマイゼーション仕様 + +### 6.1 プロジェクト固有設定 +```yaml +# .claude/settings.json での設定 +{ + "spec_kit": { + "template_dir": ".specify/templates", + "output_dir": ".specify/outputs", + "auto_clarify": true, + "spec_format": "markdown" + }, + "tdd": { + "test_framework": "auto", + "coverage_threshold": 80, + "red_green_refactor": true, + "parallel_tests": true + }, + "integration": { + "spec_to_tasks": true, + "auto_implement": false, + "quality_gates": ["lint", "test", "coverage"] + } +} +``` + +### 6.2 フック設定 +```yaml +# .claude/hooks/ での実行フック +hooks: + pre_specify: "hooks/pre-spec.sh" # 仕様作成前処理 + post_specify: "hooks/post-spec.sh" # 仕様作成後処理 + pre_implement: "hooks/pre-impl.sh" # 実装前処理 + post_implement: "hooks/post-impl.sh" # 実装後処理 + pre_test: "hooks/pre-test.sh" # テスト前処理 + post_test: "hooks/post-test.sh" # テスト後処理 +``` + +## 7. モニタリング・ログ仕様 + +### 7.1 実行ログ +```yaml +# 各フェーズの実行ログ記録 +logging: + spec_phase: ".specify/logs/spec-{timestamp}.log" + tdd_phase: ".specify/logs/tdd-{timestamp}.log" + integration: ".specify/logs/integration-{timestamp}.log" + +# 構造化ログ出力 +log_format: "json" +log_level: "info" +``` + +### 7.2 メトリクス収集 +```yaml +metrics: + spec_completion_time: "仕様作成時間" + tdd_cycle_duration: "TDDサイクル時間" + test_coverage: "テストカバレッジ" + code_quality_score: "コード品質スコア" + spec_compliance: "仕様準拠率" +``` + +## 8. エラーハンドリング仕様 + +### 8.1 エラー分類 +```yaml +error_types: + spec_creation_failed: "仕様作成失敗" + test_generation_failed: "テスト生成失敗" + implementation_failed: "実装失敗" + quality_check_failed: "品質チェック失敗" +``` + +### 8.2 自動リカバリ +```yaml +recovery_strategies: + retry_with_clarification: "明確化を伴う再実行" + fallback_to_manual: "手動フォールバック" + partial_completion: "部分完了モード" +``` + +## 9. セキュリティ考慮事項 + +### 9.1 機密情報保護 +- API キーの適切な管理 +- 生成コードの機密情報スキャン +- 権限の最小化原則 + +### 9.2 脆弱性チェック +```yaml +security_checks: + dependency_scan: "依存関係脆弱性スキャン" + code_scan: "生成コード脆弱性スキャン" + secret_scan: "機密情報漏洩チェック" +``` + +## 10. 実装例 + +### 10.1 最小構成ワークフロー +```yaml +# .github/workflows/claude-minimal.yml +name: Claude Code Minimal Integration + +on: + issues: + types: [opened] + issue_comment: + types: [created] + +jobs: + claude-development: + if: contains(github.event.comment.body, '@claude') || github.event_name == 'issues' + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: anthropics/claude-code-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + claude-api-key: ${{ secrets.CLAUDE_API_KEY }} +``` + +この仕様書に基づいて、プロジェクトの要件に応じてワークフローをカスタマイズして実装してください。 \ No newline at end of file diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 38e02b9..0292b2e 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -2,9 +2,203 @@ このファイルは、Claude Codeで利用可能なカスタムスラッシュコマンドの詳細な使用方法を説明します。 +## コマンドディレクトリ構成 + +カスタムスラッシュコマンドは以下のディレクトリ構成で管理されています： + +``` +.claude/commands/ +├── spec-kit/ # 仕様駆動開発コマンド +│ ├── specify.md # 仕様作成 +│ ├── clarify.md # 仕様明確化 +│ ├── plan.md # 実装計画作成 +│ ├── tasks.md # タスクリスト生成 +│ ├── implement.md # TDD実装 +│ ├── analyze.md # 仕様解析 +│ └── constitution.md # プロジェクト憲法管理 +├── project-management/ # プロジェクト管理 +│ └── setup-project.md # プロジェクト初期セットアップ +├── development/ # 開発支援 +│ ├── code-review.md # コード品質分析 +│ ├── refactor.md # リファクタリング +│ └── debug-help.md # デバッグ支援 +├── testing/ # テスト関連 +│ └── test-gen.md # テストコード生成 +└── documentation/ # ドキュメント + └── docs-gen.md # ドキュメント生成 +``` + +## GitHub Actions統合 + +これらのコマンドはGitHub Actionsと統合して自動実行が可能です。詳細な仕様については、[CLAUDE_GITHUB_ACTIONS_SPECS.md](./CLAUDE_GITHUB_ACTIONS_SPECS.md)を参照してください。 + ## 利用可能なコマンド -再編集中 +### プロジェクト管理コマンド + +#### `/setup-project` - プロジェクト初期セットアップ +**概要**: 新規プロジェクトの初期セットアップを自動実行 +**使用例**: +```bash +@claude /setup-project +``` +**実行内容**: +- プロジェクト構造の分析・作成 +- 設定ファイルの確認・生成 +- 依存関係の解決 +- 開発環境の初期化 +- CI/CD設定の確認 + +**対象環境**: Rust、Node.js、Python、Go、Java/Kotlin等 + +--- + +### Spec Kit統合コマンド（仕様駆動開発） + +#### `/specify` - 仕様作成 +**概要**: 自然言語の機能説明から正式な仕様を作成 +**使用例**: +```bash +@claude /specify ユーザー登録機能を実装したい。メールとパスワードで登録し、重複チェックも行う +``` +**出力**: +- 専用ブランチ作成 +- 仕様ファイル（`.specify/specs/[###-feature]/spec.md`） +- 機能要求・受入条件の明確化 + +#### `/plan` - 実装計画作成 +**概要**: 仕様から具体的な実装計画を生成 +**使用例**: +```bash +@claude /plan +``` +**前提条件**: 仕様ファイル（`/specify`の実行後） +**出力**: +- `plan.md` - 全体設計・技術選定 +- `research.md` - 技術調査結果 +- `data-model.md` - データモデル設計 +- `contracts/` - API契約定義 +- `quickstart.md` - 検証手順 + +#### `/clarify` - 仕様明確化 +**概要**: 仕様の曖昧な点を対話的に明確化 +**使用例**: +```bash +@claude /clarify パスワード要件とメール認証の必要性について +``` +**機能**: インタラクティブな質疑応答で仕様を改善 + +#### `/tasks` - タスク生成 +**概要**: 実装計画からTDD準拠のタスクリストを生成 +**使用例**: +```bash +@claude /tasks +``` +**前提条件**: 実装計画（`/plan`の実行後） +**出力**: +- TDD順序のタスクリスト +- 並列実行可能タスクのマーク `[P]` +- 依存関係の明確化 +- 具体的ファイルパス指定 + +#### `/implement` - TDD実装 +**概要**: TDDサイクルに従った機能実装 +**使用例**: +```bash +@claude /implement +``` +**前提条件**: タスクリスト（`/tasks`の実行後） +**実装サイクル**: +1. Red: テスト作成（失敗） +2. Green: 最小限実装 +3. Refactor: コード改善 + +#### `/analyze` - 仕様解析 +**概要**: 既存仕様の分析と評価 +**使用例**: +```bash +@claude /analyze spec.md +``` +**機能**: 仕様の完全性・一貫性チェック + +#### `/constitution` - プロジェクト憲法管理 +**概要**: 開発原則の作成・更新と準拠確認 +**使用例**: +```bash +@claude /constitution +``` +**機能**: +- プロジェクト憲法の作成・更新 +- 開発原則への準拠チェック +- テンプレート同期 + +--- + +### 開発支援コマンド + +#### `/code-review` - コード品質分析 +**概要**: コードの品質分析とレビュー実行 +**使用例**: +```bash +@claude /code-review src/main.rs +@claude /code-review src/ +``` +**分析項目**: +- バグ・セキュリティ問題 +- パフォーマンス問題 +- 可読性・保守性 +- ベストプラクティス準拠 + +#### `/debug-help` - デバッグ支援 +**概要**: エラー分析とデバッグ支援 +**使用例**: +```bash +@claude /debug-help テストが失敗している +@claude /debug-help --error-log error.log +``` +**機能**: +- エラー原因分析 +- 修正方法提案 +- ログ解析 +- デバッグ戦略提案 + +#### `/refactor` - リファクタリング +**概要**: コードのリファクタリングと改善 +**使用例**: +```bash +@claude /refactor src/services/ +@claude /refactor --extract-function complex_method +``` +**実行内容**: +- コード構造改善 +- 重複除去 +- 設計パターン適用 +- パフォーマンス最適化 + +#### `/test-gen` - テストコード生成 +**概要**: 自動テストコード生成 +**使用例**: +```bash +@claude /test-gen --unit --integration +@claude /test-gen src/models/user.rs +``` +**テスト種類**: +- 単体テスト（unit） +- 統合テスト（integration） +- 契約テスト（contract） + +#### `/docs-gen` - ドキュメント生成 +**概要**: 自動ドキュメント生成 +**使用例**: +```bash +@claude /docs-gen +@claude /docs-gen --api --readme +``` +**生成内容**: +- API仕様書 +- README更新 +- コード仕様書 +- ユーザーガイド ## 使用時の注意点 diff --git a/docs/GITHUB_ACTIONS_SETUP.md b/docs/GITHUB_ACTIONS_SETUP.md new file mode 100644 index 0000000..a0cc09e --- /dev/null +++ b/docs/GITHUB_ACTIONS_SETUP.md @@ -0,0 +1,244 @@ +# GitHub Actions設定ガイド + +このドキュメントでは、Claude CodeをGitHub Actionsで実行するための設定について説明します。 + +## 現在の設定概要 + +### ワークフローファイル +- **メインワークフロー**: `.github/workflows/claude.yml` +- **コードレビューワークフロー**: `.github/workflows/claude-code-review.yml` + +### トリガー条件 +Claude Codeは以下の条件でトリガーされます： + +```yaml +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] +``` + +**実行条件**: +- Issue/PRコメントに `@claude` が含まれる +- Issueのタイトルまたは本文に `@claude` が含まれる +- PRレビューに `@claude` が含まれる + +### 権限設定 +Claude Codeには以下の権限が付与されています： + +```yaml +permissions: + contents: write # コード・ファイルアクセス + pull-requests: write # PR操作 + issues: write # Issue操作 + actions: read # ワークフロー状態閲覧 + statuses: write # コミット・PRステータス設定 + repository-projects: write # プロジェクトボード操作 + id-token: write # OIDC認証 +``` + +### 必要なシークレット + +以下のシークレットを設定する必要があります： + +1. **`CLAUDE_CODE_OAUTH_TOKEN`** + - Claude Code OAuthトークン + - Claude Code WebUIで生成 + +2. **`ANTHROPIC_API_KEY`** + - Anthropic APIキー + - Anthropic Consoleで取得 + +### 設定ファイル + +#### `.claude/settings.json` +Claude Codeの基本設定： + +```json +{ + "allowedTools": ["*"], + "customCommands": { + "enabled": true, + "directory": ".claude/commands" + }, + "agents": { + "enabled": true, + "directory": ".claude/agents" + }, + "hooks": { + "enabled": true, + "directory": ".claude/hooks" + } +} +``` + +## ワークフローの動作 + +### 1. 環境セットアップ +```yaml +- name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + +- name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + +- name: Install uv CLI + uses: astral-sh/setup-uv@v4 +``` + +### 2. Git設定 +```yaml +- name: Setup Git configuration + run: | + git config --global user.name "Claude Code" + git config --global user.email "claude-code@anthropic.com" + git config --global init.defaultBranch main +``` + +### 3. PR情報取得（PRの場合） +```yaml +- name: Get PR info (only if PR) + if: ${{ github.event.issue.pull_request }} + run: | + if ! gh pr view ${{ github.event.issue.number }} --json number,title,body,baseRefName,headRefName > pr_info.json; then + echo "Failed to get PR info, creating empty file" + echo '{}' > pr_info.json + fi +``` + +### 4. Claude Code実行 +```yaml +- name: Run Claude Code + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + settings: ".claude/settings.json" + track_progress: true + branch_prefix: develop/claude/ + use_sticky_comment: true +``` + +## ブランチ戦略 + +### ブランチ命名規則 +``` +develop/claude/issue-{issue-number}-{timestamp} +``` + +例：`develop/claude/issue-5-20250926-1255` + +### マージ戦略 +1. Issueから自動ブランチ作成 +2. 機能実装・テスト +3. PR作成（mainブランチへ） +4. レビュー・マージ + +## カスタマイズ可能な設定 + +### 1. ブランチプレフィックス +```yaml +branch_prefix: develop/claude/ +``` + +### 2. プログレス追跡 +```yaml +track_progress: true +``` + +### 3. スティッキーコメント +```yaml +use_sticky_comment: true +``` + +### 4. プロンプトカスタマイズ +```yaml +prompt: | + # Claude Code Prompt Template + ## GitHub コンテキスト + リポジトリ: ${{ github.repository }} + 実行ユーザー: ${{ github.actor }} + + [カスタムプロンプト内容] +``` + +## トラブルシューティング + +### よくある問題 + +#### 1. 権限エラー +**症状**: `Permission denied` エラー +**解決**: +- シークレット設定の確認 +- リポジトリ権限の確認 +- workflows/の権限確認 + +#### 2. ワークフロー実行されない +**症状**: `@claude` コメント後に実行されない +**解決**: +- トリガー条件の確認 +- イベントタイプの確認 +- ワークフローファイル構文チェック + +#### 3. Claude Codeタイムアウト +**症状**: ワークフロー途中で停止 +**解決**: +- タスクの分割 +- タイムアウト時間調整 +- リソース使用量確認 + +### デバッグ方法 + +1. **ワークフローログ確認** + - GitHub Actions画面でログ詳細確認 + +2. **設定ファイル検証** + ```bash + # settings.jsonの構文確認 + cat .claude/settings.json | jq . + ``` + +3. **権限テスト** + ```bash + # GitHub CLIでの権限確認 + gh auth status + gh repo view --json permissions + ``` + +## ベストプラクティス + +### 1. セキュリティ +- シークレットの定期更新 +- 最小権限の原則 +- 監査ログの確認 + +### 2. パフォーマンス +- キャッシュ活用 +- 並列処理の最適化 +- 不要なステップの削除 + +### 3. 保守性 +- ワークフローの文書化 +- 設定の標準化 +- 定期的な依存関係更新 + +## まとめ + +GitHub Actions設定により以下が実現されます： + +- ✅ **自動化**: Issue/PRでの自動Claude Code実行 +- ✅ **セキュリティ**: 適切な権限管理とシークレット保護 +- ✅ **効率性**: ブランチ戦略とプログレス追跡 +- ✅ **カスタマイズ**: プロジェクト固有の設定対応 +- ✅ **可視性**: 実行ログとステータス追跡 + +この設定により、Spec Kit + TDD統合開発フローが GitHub Actions上で確実に動作します。 \ No newline at end of file diff --git a/docs/SPEC_KIT_TDD_WORKFLOW.md b/docs/SPEC_KIT_TDD_WORKFLOW.md new file mode 100644 index 0000000..d08bc93 --- /dev/null +++ b/docs/SPEC_KIT_TDD_WORKFLOW.md @@ -0,0 +1,200 @@ +# Spec Kit + TDD 統合ワークフロー + +本ドキュメントでは、仕様駆動開発（Spec Kit）とテスト駆動開発（TDD）を組み合わせた開発フローについて説明します。このワークフローにより、確実なVibe-Codingを実現できます。 + +## 概要 + +Spec Kit + TDD ワークフローは以下の原則に基づいています： + +1. **仕様ファースト**: 機能実装前に明確な仕様を作成 +2. **テストファースト**: 実装前にテストコードを作成 +3. **段階的実装**: 仕様 → テスト → 実装 → 検証のサイクル +4. **プロジェクト憲法遵守**: 開発原則の一貫した適用 + +## ワークフローの全体像 + +```mermaid +graph TD + A[機能要求] --> B[/specify: 仕様作成] + B --> C[/clarify: 仕様明確化] + C --> D[/plan: 実装計画] + D --> E[/tasks: タスク生成] + E --> F[/implement: TDD実装] + F --> G[検証・テスト] + G --> H{品質OK?} + H -->|Yes| I[機能完了] + H -->|No| J[/debug-help: デバッグ] + J --> F +``` + +## フェーズ詳細 + +### フェーズ 0: 仕様作成（Specification） + +#### `/specify` コマンド +自然言語の機能説明から正式な仕様を作成します。 + +```bash +@claude /specify ユーザー登録機能を追加したい。メールアドレスとパスワードで登録でき、重複チェックも行う +``` + +**出力例:** +- ブランチ作成: `005-user-registration` +- 仕様ファイル: `.specify/specs/005-user-registration/spec.md` + +#### `/clarify` コマンド +仕様の曖昧な点を対話的に明確化します。 + +```bash +@claude /clarify パスワードの複雑性要件は？メール認証は必要？ +``` + +### フェーズ 1: 実装計画（Planning） + +#### `/plan` コマンド +仕様から具体的な実装計画を作成します。 + +```bash +@claude /plan +``` + +**生成される成果物:** +- `plan.md` - 全体設計と技術選定 +- `research.md` - 技術調査結果 +- `data-model.md` - データモデル設計 +- `contracts/` - API契約定義 +- `quickstart.md` - 検証手順 + +### フェーズ 2: タスク生成（Task Generation） + +#### `/tasks` コマンド +実装計画からTDD準拠のタスクリストを生成します。 + +```bash +@claude /tasks +``` + +**生成されるタスクの特徴:** +- テスト優先順序（TDD準拠） +- 並列実行可能タスクのマーク `[P]` +- 依存関係の明確化 +- ファイルパス指定による具体性 + +### フェーズ 3: 実装（Implementation） + +#### `/implement` コマンド +TDDサイクルに従った実装を実行します。 + +```bash +@claude /implement +``` + +**TDDサイクル:** +1. **Red**: テストを書く（失敗する） +2. **Green**: テストを通す最小限の実装 +3. **Refactor**: コード改善 + +### フェーズ 4: 検証・デバッグ + +#### `/debug-help` コマンド +実装時のエラー解析とデバッグ支援。 + +```bash +@claude /debug-help テストが失敗している +``` + +#### `/code-review` コマンド +コード品質の分析とレビュー。 + +```bash +@claude /code-review src/models/user.rs +``` + +## プロジェクト憲法との統合 + +### 憲法チェック +各フェーズで `/constitution` コマンドにより開発原則への準拠を確認： + +```bash +@claude /constitution +``` + +### 主要原則 +1. **ライブラリファースト**: 機能をライブラリとして設計 +2. **CLIインターフェース**: すべての機能にCLI提供 +3. **テストファースト**: TDD厳格遵守 +4. **統合テスト**: 契約テストとサービス間通信テスト +5. **観測可能性**: ログ・メトリクス・トレーシング + +## 専門エージェントとの連携 + +### 言語・技術別エージェント +特定の技術領域では専門エージェントを活用： + +```bash +@claude rust-expert: 所有権エラーを修正してください +@claude web-developer: レスポンシブデザインを実装してください +@claude security-expert: 脆弱性を検査してください +``` + +### エージェント選択指針 +- **rust-expert**: Rust特有の問題（所有権、async等） +- **web-developer**: フロントエンド・Web API開発 +- **mobile-developer**: モバイルアプリ開発 +- **devops-engineer**: CI/CD・インフラ設定 +- **data-scientist**: データ分析・機械学習 +- **security-expert**: セキュリティ監査・脆弱性対応 + +## ベストプラクティス + +### 1. 仕様品質の確保 +- 機能要求は具体的に記述 +- 受入条件を明確化 +- エッジケースも考慮 + +### 2. テスト戦略 +- 契約テスト（API仕様テスト） +- 統合テスト（ユーザーシナリオテスト） +- 単体テスト（ロジック検証） + +### 3. 段階的実装 +- 最小機能から開始 +- 段階的機能追加 +- 継続的品質確認 + +### 4. 品質ゲート +- 各フェーズでの憲法チェック +- コードレビューの実行 +- 自動化テストの通過 + +## トラブルシューティング + +### よくある問題と解決策 + +#### 1. 仕様が曖昧 +**問題**: `[NEEDS CLARIFICATION]` マーカーが残る +**解決**: `/clarify` コマンドで対話的明確化 + +#### 2. テストが複雑すぎる +**問題**: テスト作成が困難 +**解決**: 仕様を単純化、段階的実装 + +#### 3. 実装が憲法違反 +**問題**: 複雑性が増しすぎる +**解決**: 設計の見直し、原則回帰 + +#### 4. 依存関係エラー +**問題**: タスク実行順序の問題 +**解決**: 依存関係の再確認、並列実行の見直し + +## まとめ + +Spec Kit + TDD ワークフローは以下を実現します： + +- ✅ **品質確保**: 仕様とテストによる品質担保 +- ✅ **開発効率**: 段階的・体系的な開発プロセス +- ✅ **保守性**: 明確な仕様とテストによる保守容易性 +- ✅ **拡張性**: モジュラー設計による機能拡張 +- ✅ **一貫性**: プロジェクト憲法による開発原則統一 + +このワークフローにより、確実で効率的なVibe-Codingが可能になります。 \ No newline at end of file diff --git a/pr_info.json b/pr_info.json new file mode 100644 index 0000000..4ffbf9e --- /dev/null +++ b/pr_info.json @@ -0,0 +1 @@ +{"baseRefName":"main","body":"- Spec Kit + TDD統合開発フローの詳細ドキュメント作成\r\n- カスタムスラッシュコマンド詳細ガイド更新\r\n- 専門サブエージェント詳細ガイド更新\r\n- GitHub Actions設定ガイド作成\r\n- CLAUDE.md更新でSpec Kit統合開発フロー追加\r\n\r\n🤖 Generated with [Claude Code](https://claude.ai/code)","headRefName":"develop/claude/issue-5-20250926-1255","number":6,"title":"docs: Spec Kit + TDD統合ワークフロー文書化とClaude Code構成整理"}