From e6a5d1e9f7898f2d94a0345b2b8fc98c03f08d99 Mon Sep 17 00:00:00 2001 From: "kuroeda.makoto" Date: Mon, 2 Feb 2026 11:20:45 +0900 Subject: [PATCH 1/2] chore: add .tool-versions to .gitignore Co-Authored-By: Claude Sonnet 4.5 --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 082fc2b..460ea17 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,6 @@ dist/ # Others tmp/ + +# Version management +.tool-versions From e6fef17b3145e1deaccdb3c696202c12a7d88c47 Mon Sep 17 00:00:00 2001 From: "kuroeda.makoto" Date: Wed, 25 Feb 2026 15:40:37 +0900 Subject: [PATCH 2/2] feat: version 1.2.0 - add kairo-loop, new debug commands, skills, and update help.md Co-Authored-By: Claude Sonnet 4.6 --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 5 +- MANUAL.md | 19 +- claude_docker/hooks/docker-auto-wrapper.sh | 139 ++++ claude_docker/settings.json | 102 +++ claude_docker/settings.local.json | 11 + commands/auto-debug.md | 201 +++++- commands/build-fix.md | 116 +++ commands/env-fix.md | 132 ++++ commands/flaky-fix.md | 126 ++++ commands/help.md | 220 ++++++ commands/kairo-implement.md | 669 ------------------ commands/kairo-loop.md | 24 + commands/orchestrate.md | 381 ++++++++++ commands/tdd-green.md | 38 +- commands/tdd-red.md | 77 +- commands/tdd-refactor.md | 38 +- commands/tdd-tasknote.md | 18 +- commands/tdd-testcases.md | 53 +- commands/tdd-verify-complete.md | 97 ++- commands/timeout-fix.md | 144 ++++ skills/kairo-implement/SKILL.md | 128 ++++ .../kairo-implement/kairo-direct-process.md | 65 ++ skills/kairo-implement/kairo-tdd-process.md | 158 +++++ 24 files changed, 2097 insertions(+), 868 deletions(-) create mode 100755 claude_docker/hooks/docker-auto-wrapper.sh create mode 100644 claude_docker/settings.json create mode 100644 claude_docker/settings.local.json create mode 100644 commands/build-fix.md create mode 100644 commands/env-fix.md create mode 100644 commands/flaky-fix.md create mode 100644 commands/help.md delete mode 100644 commands/kairo-implement.md create mode 100644 commands/kairo-loop.md create mode 100644 commands/orchestrate.md create mode 100644 commands/timeout-fix.md create mode 100644 skills/kairo-implement/SKILL.md create mode 100644 skills/kairo-implement/kairo-direct-process.md create mode 100644 skills/kairo-implement/kairo-tdd-process.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 72abc27..0e27d57 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,14 +7,14 @@ }, "metadata": { "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", - "version": "1.1.1" + "version": "1.2.0" }, "plugins": [ { "name": "tsumiki", "source": "./", "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", - "version": "1.1.1", + "version": "1.2.0", "author": { "name": "makoto kuroeda", "email": "kuroeda.makoto@classmethod.jp" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 25a14b1..3635b96 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "tsumiki", - "version": "1.1.1", + "version": "1.2.0", "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", "author": { "name": "makoto kuroeda", @@ -10,5 +10,6 @@ "repository": "https://github.com/classmethod/tsumiki", "license": "MIT", "keywords": ["ai-development", "sdd", "tdd"], - "commands": "./commands/" + "commands": "./commands/", + "skills": "./skills/" } diff --git a/MANUAL.md b/MANUAL.md index 70491a9..fb82b2f 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -32,6 +32,19 @@ docs/rule/kairo/requirements/ # kairo-requirements専用ルール これらのディレクトリ内の `.md` ファイルは、コマンド実行時にコンテキストとして自動読み込みされます。 +#### --permission-mode　　bypassPermissions の利用 + +可能な限り隔離された環境を用意する方法について *サンプル* を公開しました +利用についてはマニュアル https://code.claude.com/docs/en/permissions#permission-modes を必ず参照してください +claude code をホストのsandbox環境下で利用し、ファイルの変更など一部のコマンド以外全てを docker内で実行する *サンプル* を用意しています +claude_docker/ ディレクトリを参考に構築してください（pluginとしては扱わないようにしてます） +仕組みは、hooksを利用してtool実行のうち許可されてないものは全てdocker上で動作するコマンドを書き換えています + +テスト済みの動作環境は、Mac/RancherDesktop(docker)/go です +※これはtsumikiの長時間実行の試験をする目的で作成されました。実プロジェクトでの適用についてはそれぞれのプロジェクトで判断・変更してください + +改善方法についてのPRをお待ちしてます + ### TDDコマンド TASK作成時に `TDD` と判定している場合で個別にTDDプロセスを実行したい場合は、以下のコマンドを順次実行できます： @@ -152,7 +165,11 @@ Kairoは以下を生成します： # 特定のタスクのみ実装 /tsumiki:kairo-implement タスクファイル名　TASK番号 -# "TASK-101を実装してください" + +# タスク範囲を指定して実装 タスクディレクトリ名　開始TASK番号 終了TASK番号 +/tsumiki:kairo-loop +（実行中にcompactが発動しても安定して「長時間処理」が可能です + ``` Kairoは各タスクに対して内部的にTDDコマンドを使用して以下のプロセスを実行します： diff --git a/claude_docker/hooks/docker-auto-wrapper.sh b/claude_docker/hooks/docker-auto-wrapper.sh new file mode 100755 index 0000000..e12e6d9 --- /dev/null +++ b/claude_docker/hooks/docker-auto-wrapper.sh @@ -0,0 +1,139 @@ +#!/bin/bash +# docker-auto-wrapper.sh +# Claude CodeのPreToolUseフック：ほぼすべてのBashコマンドをDockerコンテナ内で自動実行 + +set -e + +# ログディレクトリの作成 +LOG_DIR="/tmp/claude" +mkdir -p "$LOG_DIR" 2>/dev/null || true + +# デバッグログ用環境変数（DOCKER_HOOK_DEBUG=1 で有効化） +debug_log() { + local msg="$*" + if [[ "${DOCKER_HOOK_DEBUG:-0}" == "1" ]]; then + echo "[DEBUG] $msg" >&2 + # デバッグモード時のみファイルにも出力 + echo "[$(date '+%Y-%m-%d %H:%M:%S')] $msg" >> "$LOG_DIR/hook-debug.log" 2>/dev/null || true + fi +} + +# 標準入力からJSONを読み取る +INPUT=$(cat) +debug_log "Input received" + +# デバッグモード時のみ実際の入力を保存 +if [[ "${DOCKER_HOOK_DEBUG:-0}" == "1" ]]; then + echo "$INPUT" > "$LOG_DIR/hook-input-last.json" 2>/dev/null || true +fi + +# コマンドを抽出 +COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) +if [[ $? -ne 0 ]]; then + debug_log "ERROR: Failed to parse JSON with jq" + exit 0 +fi +debug_log "Command: $COMMAND" + +# コマンドが空の場合はそのまま実行 +if [ -z "$COMMAND" ]; then + debug_log "Empty command, skipping" + exit 0 +fi + +# コマンドの最初の単語を抽出（複数のパターンに対応） +# パイプ、リダイレクト、コマンド置換を考慮して抽出 +# 重要: 複数行コマンドの場合は最初の行の最初の単語のみを取得 +CMD_NAME=$(echo "$COMMAND" | head -1 | sed 's/|.*//' | sed 's/>.*//' | sed 's/<.*//' | sed 's/;.*//' | sed 's/&&.*//' | awk '{print $1}' | tr -d ' \t') + +# パス情報を削除（例: "/usr/local/bin/go" → "go"） +CMD_BASE=$(basename "$CMD_NAME" 2>/dev/null || echo "$CMD_NAME") +debug_log "CMD_NAME after extraction: [$CMD_NAME]" +debug_log "CMD_BASE after basename: [$CMD_BASE]" +debug_log "Extracted command base: $CMD_BASE" + +# 最優先: Git/Docker関連コマンドは必ずホストで実行 +# Sandbox無効時でも確実に除外するため、最初にチェック +CRITICAL_HOST_COMMANDS=("git" "docker" "docker-compose") +debug_log "Checking CRITICAL_HOST_COMMANDS for: [$CMD_BASE]" +for critical_cmd in "${CRITICAL_HOST_COMMANDS[@]}"; do + debug_log " Comparing: [$CMD_BASE] == [$critical_cmd]" + if [[ "$CMD_BASE" == "$critical_cmd" ]]; then + debug_log " MATCH! Critical host command detected: $CMD_BASE - running on host" + exit 0 + fi +done +debug_log "No critical command match found" + +# ホストで実行すべきコマンドのホワイトリスト +# これらのコマンドはDockerコンテナ内で実行しても意味がない、または実行できない +HOST_ONLY_COMMANDS=( + "cd" # シェル組み込みコマンド + "pushd" # シェル組み込みコマンド + "popd" # シェル組み込みコマンド + "export" # 環境変数設定 + "source" # スクリプト読み込み + "." # source のエイリアス + "alias" # エイリアス定義 + "unalias" # エイリアス解除 + "hash" # コマンドハッシュテーブル + "type" # コマンドタイプ確認 + "which" # コマンドパス確認（場合により） + "date" # 日時取得（ホストの日時を使用） +) + +# ホワイトリストに含まれているかチェック +for host_cmd in "${HOST_ONLY_COMMANDS[@]}"; do + if [[ "$CMD_BASE" == "$host_cmd" ]]; then + debug_log "Host-only command detected: $CMD_BASE - running on host" + exit 0 + fi +done + +# それ以外のすべてのコマンドをDockerコンテナ内で実行 +debug_log "Wrapping command for Docker execution" + +# プロジェクトルートを確定（スクリプトの 2 階層上 = .claude/hooks/ の親の親） +PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)" +COMPOSE_FILE="$PROJECT_DIR/docker-compose.yml" +CONTAINER_NAME="go-app" + +# コンテナ状態を確認（失敗時は空文字になる） +CONTAINER_STATUS=$(docker inspect --format '{{.State.Status}}' "$CONTAINER_NAME" 2>/dev/null) || true +debug_log "Container status: [$CONTAINER_STATUS]" + +if [[ "$CONTAINER_STATUS" == "running" ]]; then + # 起動中のコンテナで実行（高速） + WRAPPED_COMMAND="docker-compose -f \"$COMPOSE_FILE\" exec -T app sh -c $(printf '%q' "$COMMAND")" + debug_log "using exec (container running)" +else + # コンテナを自動起動（db の healthcheck 完了まで待機、60 秒タイムアウト） + docker-compose -f "$COMPOSE_FILE" up -d --wait --wait-timeout 60 app >&2 && UP_OK=true || UP_OK=false + + if [[ "$UP_OK" == "true" ]]; then + WRAPPED_COMMAND="docker-compose -f \"$COMPOSE_FILE\" exec -T app sh -c $(printf '%q' "$COMMAND")" + debug_log "using exec (container started)" + else + # 起動失敗時は従来の run --rm にフォールバック + WRAPPED_COMMAND="docker-compose -f \"$COMPOSE_FILE\" run --rm -T app sh -c $(printf '%q' "$COMMAND")" + debug_log "using run --rm (fallback)" + fi +fi +debug_log "Wrapped command: $WRAPPED_COMMAND" + +# JSONを出力して、コマンドを変更 +jq -n \ + --arg cmd "$WRAPPED_COMMAND" \ + '{ + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "updatedInput": { + "command": $cmd + }, + "permissionDecisionReason": "Automatically wrapped to run in Docker container" + } + }' + +debug_log "Hook completed successfully" +exit 0 diff --git a/claude_docker/settings.json b/claude_docker/settings.json new file mode 100644 index 0000000..77d7702 --- /dev/null +++ b/claude_docker/settings.json @@ -0,0 +1,102 @@ +{ + "sandbox": { + "enabled": true, + "autoAllowBashIfSandboxed": true, + "excludedCommands": ["docker", "docker-compose", "git"], + "allowUnsandboxedCommands": true, + "filesystem": { + "write": { + "allowOnly": [ + "/tmp/claude", + "/private/tmp/claude", + "/private/tmp/zsh*" + ] + } + }, + "network": { + "allowedDomains": [ + "proxy.golang.org", + "*.pkg.go.dev", + "github.com", + "*.docker.io", + "*.dockerhub.com", + "registry.hub.docker.com" + ], + "allowUnixSockets": [ + "/var/run/docker.sock", + "~/.rd/docker.sock" + ], + "allowLocalBinding": true + } + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/docker-auto-wrapper.sh", + "timeout": 90 + } + ] + } + ] + }, + "permissions": { + "deny": [ + "Bash(git push --force*)", + "Bash(git push -f *)", + "Bash(git push * -f*)", + "Bash(git push *--force*)", + "Bash(git reset --hard*)", + "Bash(git branch -D*)", + "Bash(git push * --delete*)", + "Bash(git push --delete*)", + "Bash(git clean -f*)", + "Bash(git checkout .)", + "Bash(git restore .)", + "Bash(git push *)", + "Bash(git commit --amend*)", + "Bash(git rebase*)", + "Bash(git merge*)", + "Bash(git stash drop*)", + "Bash(git tag -d*)", + "Bash(docker-compose down -v*)", + "Bash(docker-compose down *-v*)", + "Bash(docker-compose down*--volumes*)", + "Bash(docker system prune*)", + "Bash(docker volume rm*)", + "Bash(docker volume prune*)", + "Bash(docker rm -f *)", + "Bash(docker container prune*)", + "Bash(docker image prune -a*)", + "Bash(docker rmi *-f*)", + "Bash(docker network prune*)", + "Bash(docker-compose kill*)", + "Bash(docker stop *)", + "Bash(docker kill *)", + "Bash(rm *go.mod*)", + "Bash(rm *go.sum*)", + "Bash(rm *docker-compose.yml*)", + "Bash(rm *Dockerfile*)", + "Bash(rm *.claude/settings.json*)", + "Bash(rm *.claude/hooks/*)", + "Bash(rm *CLAUDE.md*)", + "Bash(rm -rf .git*)", + "Bash(find * -delete*)", + "Bash(find * -exec rm*)", + "Bash(*| sh)", + "Bash(*| bash)", + "Bash(*| sh *)", + "Bash(*| bash *)", + "Edit(.env)", + "Write(.env)", + "Edit(go.mod)", + "Edit(go.sum)", + "Edit(docker-compose.yml)", + "Edit(.claude/settings.json)", + "Write(.claude/settings.json)" + ] + } +} diff --git a/claude_docker/settings.local.json b/claude_docker/settings.local.json new file mode 100644 index 0000000..4f7647c --- /dev/null +++ b/claude_docker/settings.local.json @@ -0,0 +1,11 @@ +{ + "sandbox": { + "network": { + "allowUnixSockets": [ + "/var/run/docker.sock", + "/Users/USER_NAME/.rd/docker.sock" + ] + }, + "filesystem": {} + } +} diff --git a/commands/auto-debug.md b/commands/auto-debug.md index 71b67de..08bc271 100644 --- a/commands/auto-debug.md +++ b/commands/auto-debug.md @@ -1,5 +1,7 @@ --- description: テストエラーを解消するための自動デバッグプロセス。全テストケースの確認からエラー原因の調査、修正まで段階的に実行し、テストケースの成功率向上を目指します。 +allowed-tools: Read, Glob, Grep, Task, Edit, Write, TodoWrite +argument-hint: "[テストファイルパス（省略可）]" --- テストエラーを解消して。 @@ -7,15 +9,51 @@ description: テストエラーを解消するための自動デバッグプロ ## step1: 失敗テストの特定 -1. **全テストケースの確認** +1. **グローバルラウンドカウンタの初期化** + - `global_round: 0` — step3→step2の外側ループ回数 + - `max_global_round: 3` — 最大ラウンド数 + +2. **テストコマンドの決定** + - tasknote（`./docs/implements/**/note.md`）に `test_command` フィールドがあればそこから読み取り + - tasknoteにない場合、以下の順序で情報を収集して決定: + - **a. プロジェクトドキュメントの確認**（存在するもののみ読み取り）: + - `CLAUDE.md` — テスト実行方法、開発ルール、プロジェクト固有の指示 + - `README.md` — プロジェクトのセットアップ手順、テスト実行方法 + - `AGENTS.md` — エージェント向けの開発ルール、テスト関連の指示 + - これらにテスト実行コマンドの記載があればそれを優先採用 + - **b. プロジェクト設定ファイルから自動検出**（a で確定しなかった場合）: + - `playwright.config.ts` / `playwright.config.js` が存在 → `npx playwright test` + - `pytest.ini` / `pyproject.toml`（`[tool.pytest]`セクションあり）が存在 → `pytest` + - `package.json` の `scripts.test` が定義されている → `npm test` + - `Makefile` に `test` ターゲットがある → `make test` + - いずれにも該当しない → `npm test`（フォールバック） + - 検出結果を tasknote に記録（tasknoteが存在する場合） + - 以降の全ステップで検出したコマンドを `{{test_command}}` として使用 + +3. **全テストケースの確認（簡潔モード）** ```bash - npm test -- --verbose 2>&1 | tee test-results.log + timeout 300 {{test_command}} 2>&1 ``` - - 失敗しているテストのみをリスト化 - - 各テストの失敗内容を記録 + - **--verboseは使用しない**（成功テストの詳細出力はトークンの無駄） + - 失敗しているテストファイル名のみをリスト化 - テストファイルごとにグループ化 - -2. **失敗テストをTODOに登録** + - **タイムアウト発生時**: /tsumiki:timeout-fix コマンドを subagent（general-purpose）で実行 + - timeout-fix 成功 → テスト再実行 + - timeout-fix 失敗（テスト分離成功） → 分離されたテストをレポートに記載し、残りのテストで続行 + - timeout-fix 失敗（分離も不能） → タイムアウトとしてレポート（step5）に報告し終了 + +4. **ビルドエラーの判定** + - テスト出力を解析し、以下のパターンを検知: + - コンパイルエラー（SyntaxError, TypeError at compile time, Cannot find module 等） + - TypeScript型エラー（TS2xxx系エラー） + - 依存パッケージ未解決（Module not found, Cannot resolve 等） + - **ビルドエラーの場合**: + - /tsumiki:build-fix コマンドを subagent（general-purpose）で実行（test_command と error_output を渡す） + - build-fix 成功 → テスト再実行して step1-3 の結果確認に戻る + - build-fix 失敗 → ビルドエラーとして最終レポート（step5）に報告し終了 + - **テストエラーの場合**: 通常通りstep2へ進む + +5. **失敗テストをTODOに登録** - TodoWrite ツールで各失敗テストをTODO項目として登録 - 優先度を設定（重要度: 高/中/低） - メタデータに以下を含める: @@ -30,44 +68,80 @@ description: テストエラーを解消するための自動デバッグプロ 1. **リトライカウンタの初期化** - 各テストファイルのリトライ回数を0に設定 - 保留テストリストを初期化（空のリスト） + - 修正履歴リストを初期化（空のリスト） -2. **該当テストファイルのみを実行して詳細確認** +2. **該当テストファイルのみを実行して詳細確認**（ここでのみ--verbose使用） ```bash - npm test -- <失敗したテストファイル> --verbose + timeout 120 {{test_command}} -- <失敗したテストファイル> --verbose ``` + - 失敗テストの詳細なエラーメッセージ・スタックトレースを取得 + - **タイムアウト発生時**: /tsumiki:timeout-fix コマンドを subagent で実行（test_file を指定） + - 成功 → テスト再実行 + - 失敗 → レポートに記載して次のテストファイルへ -3. **エラー原因の分析** - - Task tool (subagent_type: Explore, thoroughness: quick) を使用 - - エラーメッセージから原因を特定 - - 修正方針を決定 - -4. **修正実装** +3. **flaky test の検知** + - テストが失敗した場合、**即座に同じテストを1回だけ再実行** + ```bash + {{test_command}} -- <失敗したテストファイル> --verbose + ``` + - 2回目に成功した場合: **flaky test と判定** + - /tsumiki:flaky-fix コマンドを subagent（general-purpose）で実行（test_file と error_output を渡す） + - flaky-fix 成功（3回連続成功） → 安定化済みとして通常フローに復帰（修正済みテストとして次のテストファイルへ） + - flaky-fix 失敗 → 従来通り flaky test として記録し、修正対象から除外。次のテストファイルへ + - 2回目も失敗した場合: 安定した失敗と判断し、次の分析ステップへ + +4. **エラー原因の構造化分析** + - Task tool (subagent_type: Explore, thoroughness: **medium**) を使用 + - **以下のエラー分類フレームワークに従って分析**: + - 🔧 **コードバグ**: 実装コードのロジックエラー、型ミス、計算ミス等 + - 🧪 **テストバグの疑い**: テストの期待値が仕様と不整合、テストのセットアップ不備等 + - ⚙️ **設定・環境問題**: パス設定ミス、環境変数不足、設定ファイル不備等 + - 📦 **依存関係問題**: パッケージバージョン不整合、未インストール等 + - 分類結果と修正方針を決定 + - **リトライ2回目以降**: 修正履歴（前回の修正内容・失敗原因）を分析プロンプトに含める + +5. **テストバグの疑い判定** + - エラー分類で「🧪 テストバグの疑い」と判定された場合: + - 保留リストに追加（保留理由: 「テスト自体のバグの可能性」） + - 詳細な根拠を記録（どの部分がなぜテストバグと疑われるか） + - **このテストファイルの修正は行わず、次のテストファイルへ進む** + +6. **環境・依存関係問題の委譲** + - エラー分類で「⚙️ 設定・環境問題」または「📦 依存関係問題」と判定された場合: + - /tsumiki:env-fix コマンドを subagent（general-purpose）で実行（test_command, test_file, error_output, error_classification を渡す） + - env-fix 成功 → テストを再実行し、成功すれば次のテストファイルへ + - env-fix 失敗 → 保留リストに追加（保留理由: env-fix の結果レポートを含める）。次のテストファイルへ + +7. **修正実装**（エラー分類が「🔧 コードバグ」の場合） - をTask ツールで直接実行して修正 - - パラメータとしてエラーの原因と該当テストファイルを渡す + - パラメータとしてエラーの原因、該当テストファイル、**エラー分類結果**を渡す -5. **該当テストファイルのみを再実行** +8. **該当テストファイルのみを再実行** ```bash - npm test -- <修正したテストファイル> + {{test_command}} -- <修正したテストファイル> ``` -6. **リトライ判定** - - ✅ 成功: 次のテストファイルへ +9. **リトライ判定** + - ✅ 成功: **修正履歴に「成功」を記録**し、次のテストファイルへ - ❌ 失敗かつリトライ回数 < 3: - リトライ回数を+1 - - step2の3に戻って再分析 + - **修正履歴に「失敗: [エラー内容] / 試みた修正: [修正内容]」を記録** + - step2の4に戻って再分析（修正履歴を引き継ぐ） - ❌ 失敗かつリトライ回数 >= 3: - このテストは保留リストに追加 - 保留理由を記録（例: "3回の修正試行後も解消できず"） + - **修正履歴全体を保留理由に含める** - 次のテストファイルへ進む ## step3: 全テスト実行による確認 **全ての失敗テストの修正試行が完了した後**: -1. **全テスト実行** +1. **全テスト実行（簡潔モード）** ```bash - npm test -- --verbose + {{test_command}} 2>&1 ``` + - **--verboseは使用しない**（全テストの通過確認のみが目的） 2. **結果確認** - 新たに失敗したテストがないか確認 @@ -75,14 +149,28 @@ description: テストエラーを解消するための自動デバッグプロ - 保留テストの状態を確認 3. **追加修正が必要な場合** - - 新規失敗テスト: step2に戻って対応（リトライ回数0から開始） + - **グローバルラウンドカウンタをチェック**: + - global_round < max_global_round（3）の場合: + - global_round を +1 + - 新規失敗テスト: step2に戻って対応（リトライ回数0から開始） + - global_round >= max_global_round（3）の場合: + - **新規失敗テストはすべて保留リストに追加** + - 保留理由: 「グローバルラウンド上限（3回）到達。カスケード障害の可能性」 + - step4へ進む - 保留テストの再試行: ユーザーに確認後、step2に戻って対応 ## step4: リファクタリング -**全テストが通った後**: +**全テストが通った後（または保留テストのみ残っている場合）**: + +1. をTask ツールで直接実行してリファクタリングを実施 -- をTask ツールで直接実行してリファクタリングを実施 +2. **リファクタリング後の全テスト再検証** + ```bash + {{test_command}} 2>&1 + ``` + - リファクタリングによる回帰がないか確認 + - 新たな失敗が発生した場合: リファクタリングによる問題としてレポートに記録（step2には戻らない。リファクタリング起因の問題は手動対応を推奨） ## step5: 最終レポート @@ -92,30 +180,82 @@ description: テストエラーを解消するための自動デバッグプロ # テストエラー解消レポート ## 結果サマリー +- テストコマンド: {{test_command}} - 修正前の失敗テスト数: XX個 - 修正後の失敗テスト数: XX個 - 解消したテスト数: XX個 -- 保留したテスト数: XX個（3回の修正試行後も解消できず） +- 保留したテスト数: XX個 +- flaky test数: XX個（安定化成功: XX個 / 未解消: XX個） +- テストバグの疑い: XX個 +- 環境依存問題: XX個（自動修正: XX個 / 未解消: XX個） +- タイムアウト: XX個（改善: XX個 / 分離: XX個 / 未解消: XX個） +- グローバルラウンド実行回数: X/3 - テスト成功率: XX% +## ビルドエラー（テスト実行前に検出） +（ビルドエラーがあった場合のみ記載） +- エラー種別: [コンパイルエラー / 型エラー / 依存パッケージ未解決] +- build-fix 結果: [成功（自動修正済み） / 失敗] +- エラー内容: [エラーの詳細] +- 推奨対応: [手動での修正が必要な理由と方針] + ## 修正内容 1. test/user.test.js + - エラー分類: 🔧 コードバグ - エラー原因: データベース接続エラー - 修正内容: 接続プールの初期化を修正 - 実行時間: 15秒 → 2秒 - リトライ回数: 1回 2. test/file.test.js + - エラー分類: ⚙️ 設定・環境問題 - エラー原因: ファイルパスの不一致 - 修正内容: パス解決ロジックを修正 - 実行時間: 8秒 → 0.5秒 - リトライ回数: 0回 +## flaky test（不安定なテスト） +（flaky testがあった場合のみ記載） +1. test/unstable.test.js + - 1回目: 失敗 / 2回目: 成功 + - flaky-fix 結果: [安定化成功 / 安定化失敗] + - 修正内容: [安定化のために行った修正]（成功時のみ） + - 推奨対応: [手動での安定化が必要な理由]（失敗時のみ） + +## タイムアウト +（タイムアウトが発生した場合のみ記載） +1. test/slow.test.js + - タイムアウト秒数: XX秒 + - timeout-fix 結果: [改善成功 / 分離成功 / 改善失敗] + - 修正/分離内容: [実施した対応] + - 個別実行方法: [分離された場合の実行コマンド] + +## 環境依存問題 +（環境依存問題があった場合のみ記載） +1. test/env-dependent.test.js + - 問題種別: [依存パッケージ / 環境変数 / 設定ファイル / 外部サービス] + - env-fix 結果: [成功 / 失敗] + - 修正内容: [実施した修正]（成功時のみ） + - 推奨対応: [手動対応が必要な内容]（失敗時のみ） + +## テストバグの疑い（要手動確認） +（テストバグの疑いがあった場合のみ記載） +1. test/suspicious.test.js + - 疑い理由: [テストの期待値が仕様と不整合 等] + - 根拠: [具体的な不整合箇所] + - 推奨対応: テストコードの仕様確認と修正を検討してください + ## 保留テスト（要手動確認） 1. test/complex.test.js - 保留理由: 3回の修正試行後も解消できず + - 修正履歴: [各試行の修正内容と失敗原因] - 最終エラー: [エラーメッセージ] - 推奨対応: [手動での詳細調査が必要な理由] + +## リファクタリング後の回帰 +（リファクタリング後に新たな失敗が発生した場合のみ記載） +- 失敗テスト: [テストファイル名] +- 推奨対応: リファクタリングによる問題のため手動対応を推奨 ``` ## step6: テスト実行時間のチェック @@ -139,6 +279,15 @@ NEVER: テストのスキップ NEVER: 既存テストケースの削除 MUST: 各テストファイルの修正は最大3回まで（無限ループ防止） MUST: 3回試行後も解消できないテストは保留リストに追加 +MUST: step3→step2の外側ループは最大3ラウンドまで（カスケード障害防止） +MUST: テストコマンドは自動検出結果（{{test_command}}）を使用する（npm test固定にしない） +MUST: テスト実行時はtimeoutを明示指定する（全体: 300秒、個別: 120秒） +MUST: ビルドエラー検出時はまず /tsumiki:build-fix に委譲し、失敗時のみレポート +MUST: flaky test検出時はまず /tsumiki:flaky-fix に委譲し、失敗時のみ除外・レポート +MUST: 環境・依存関係問題はまず /tsumiki:env-fix に委譲し、失敗時のみ保留・レポート +MUST: タイムアウト発生時はまず /tsumiki:timeout-fix に委譲し、失敗時のみ分離またはレポート +MUST: テストバグの疑いがある場合は修正せずユーザに報告 +MUST: リトライ時は前回の修正履歴を分析に含める（同じ修正の繰り返し防止） # info diff --git a/commands/build-fix.md b/commands/build-fix.md new file mode 100644 index 0000000..7887c12 --- /dev/null +++ b/commands/build-fix.md @@ -0,0 +1,116 @@ +--- +description: ビルドエラー（コンパイルエラー、型エラー、依存パッケージ未解決）を自動的に分析・修正します。auto-debugから委譲される他、ユーザが直接呼び出すことも可能です。 +allowed-tools: Read, Glob, Grep, Task, Edit, Write +argument-hint: "[エラー内容（省略可）]" +--- +ビルドエラーを解消して。 + +# context + +``` +test_command: {{test_command}} (テスト実行コマンド。未指定の場合は npm test) +error_output: {{error_output}} (ビルドエラーの出力内容) +max_retry: 3 (最大リトライ回数) +retry_count: 0 (現在のリトライ回数) +``` + +# step + +## step0: プロジェクトコンテキストの確認 + +以下のファイルが存在する場合は読み取り、テスト実行方法や開発ルールを把握する: +- `CLAUDE.md` — テスト実行方法、プロジェクト固有の指示 +- `README.md` — セットアップ手順、ビルド方法 +- `AGENTS.md` — エージェント向けの開発ルール + +test_command が未指定の場合は、これらの情報から適切なテストコマンドを決定する。 + +## step1: ビルドエラーの分析 + +1. **エラー出力の取得** + - error_output が提供されている場合はそれを使用 + - 提供されていない場合は以下を実行: + ```bash + {{test_command}} 2>&1 + ``` + +2. **エラー種別の特定** + - Task tool (subagent_type: Explore, thoroughness: **medium**) を使用 + - 以下のエラー分類に従って分析: + - **構文エラー**: SyntaxError, Unexpected token 等 + - **型エラー**: TS2xxx系エラー, TypeError at compile time 等 + - **依存パッケージ未解決**: Cannot find module, Module not found, Cannot resolve 等 + - **設定ファイル不備**: 設定ファイルの構文エラー, 未定義のプロパティ参照 等 + - エラー箇所（ファイル名、行番号）を特定 + - 修正方針を決定 + +## step2: 自動修正の試行 + +エラー種別に応じた修正を実施: + +1. **依存パッケージ未解決の場合** + - `package.json` / `requirements.txt` 等を確認 + - 不足パッケージを特定 + ```bash + npm install {{missing_package}} + ``` + - または `npm ci`（lockfileとの不整合の場合） + +2. **import文エラーの場合** + - 正しいモジュールパスを探索（Explore quick） + - import文を修正（Edit tool） + +3. **型エラーの場合** + - 型定義ファイルの不足: `npm install -D @types/{{package}}` + - 型注釈の誤り: コード修正（Edit tool） + - tsconfig.json の設定不備: 設定修正 + +4. **構文エラーの場合** + - エラー箇所のコードを読み取り（Read tool） + - 構文エラーを修正（Edit tool） + +5. **設定ファイル不備の場合** + - 設定ファイルの構文チェック + - 不足プロパティの追加、誤記の修正 + +## step3: ビルド再実行による確認 + +1. **テスト（ビルド）を再実行** + ```bash + {{test_command}} 2>&1 + ``` + +2. **結果判定** + - **ビルド成功（テスト実行段階まで到達）**: 修正完了。修正内容を報告して終了 + - **別のビルドエラーが発生**: retry_count < max_retry なら step1 に戻る + - **同じビルドエラーが継続**: retry_count < max_retry なら別のアプローチで step2 を再試行 + - **retry_count >= max_retry**: 修正不能としてレポートを出力して終了 + +## step4: 結果レポート + +```markdown +# build-fix 結果レポート + +## 結果: [成功 / 部分成功 / 失敗] + +## 修正内容 +（修正した場合のみ） +- エラー種別: [構文エラー / 型エラー / 依存パッケージ / 設定不備] +- 修正ファイル: [ファイルパス] +- 修正内容: [具体的な変更内容] +- リトライ回数: X/3 + +## 未解決のエラー +（修正できなかった場合のみ） +- エラー内容: [エラーメッセージ] +- 試行した修正: [各試行の内容] +- 推奨対応: [手動での修正が必要な理由と方針] +``` + +# rule + +NEVER: ソースコードのロジック変更（ビルドを通すための最小限の修正のみ） +NEVER: テストコードの削除やスキップ +MUST: 修正はビルドエラーの解消に直接関係するもののみ +MUST: 依存パッケージの追加時はバージョンを明示 +MUST: 各リトライで前回と異なるアプローチを試みる diff --git a/commands/env-fix.md b/commands/env-fix.md new file mode 100644 index 0000000..930661a --- /dev/null +++ b/commands/env-fix.md @@ -0,0 +1,132 @@ +--- +description: テスト実行に必要な環境依存問題（パッケージ不足、環境変数未設定、設定ファイル不備、外部サービス未起動）を自動的に分析・修正します。auto-debugから委譲される他、ユーザが直接呼び出すことも可能です。 +allowed-tools: Read, Glob, Grep, Task, Edit, Write +argument-hint: "[テストファイルパス（省略可）]" +--- +環境依存問題を解消して。 + +# context + +``` +test_command: {{test_command}} (テスト実行コマンド。未指定の場合は npm test) +test_file: {{test_file}} (対象テストファイル。未指定の場合は全テスト) +error_output: {{error_output}} (エラー出力内容) +error_classification: {{error_classification}} (エラー分類。⚙️設定・環境問題 / 📦依存関係問題) +max_retry: 2 (最大リトライ回数) +``` + +# step + +## step0: プロジェクトコンテキストの確認 + +以下のファイルが存在する場合は読み取り、テスト実行方法や環境要件を把握する: +- `CLAUDE.md` — テスト実行方法、環境設定の指示 +- `README.md` — セットアップ手順、必要な環境変数、外部サービス要件 +- `AGENTS.md` — エージェント向けの開発ルール、環境関連の注意事項 + +test_command が未指定の場合は、これらの情報から適切なテストコマンドを決定する。 + +## step1: 環境問題の分析 + +1. **エラー出力の確認** + - error_output が提供されている場合はそれを分析 + - 提供されていない場合はテストを実行してエラーを取得 + +2. **原因分析**（Task tool, subagent_type: Explore, thoroughness: **medium**） + - 以下の環境問題パターンに沿って分析: + - **依存パッケージ不足/不整合**: package.json と node_modules の不一致、lockfile の不整合 + - **環境変数未設定**: 必要な環境変数が未定義、.env ファイルの不備 + - **設定ファイル不備**: 設定ファイルの不足、パス設定の誤り + - **外部サービス未起動**: DB、Redis、メッセージキュー等の未起動 + - **Node.js/ランタイムバージョン不整合**: .nvmrc / .node-version との不一致 + - 修正可能な問題と手動対応が必要な問題を分類 + +## step2: 自動修正の試行 + +問題種別に応じた修正を実施: + +1. **依存パッケージ不足/不整合の場合** + ```bash + # lockfileとの同期 + npm ci + ``` + - `npm ci` が失敗した場合: + ```bash + rm -rf node_modules && npm install + ``` + - Python の場合: + ```bash + pip install -r requirements.txt + ``` + +2. **環境変数未設定の場合** + - `.env.example` / `.env.sample` / `.env.template` が存在するか確認 + - 存在する場合: `.env.test` または `.env` にコピー + - 存在しない場合: エラーメッセージから必要な環境変数を特定し、テスト用デフォルト値で `.env.test` を生成 + - 注意: 機密情報（APIキー等）はプレースホルダで記載し、レポートで手動設定を推奨 + +3. **設定ファイル不備の場合** + - テンプレートや既存設定からの生成 + - パス設定の修正（相対パス/絶対パスの変換） + - 不足プロパティの追加 + +4. **外部サービス未起動の場合** + - `docker-compose.yml` / `compose.yml` が存在するか確認 + - 存在する場合: + ```bash + docker compose up -d + ``` + - 存在しない場合: 手動起動が必要としてレポート + +5. **ランタイムバージョン不整合の場合** + - `.nvmrc` / `.node-version` の内容を報告 + - 自動修正は行わず、レポートで推奨バージョンを記載 + +## step3: テスト再実行による確認 + +1. **テストを再実行** + ```bash + {{test_command}} 2>&1 + ``` + - test_file が指定されている場合: + ```bash + {{test_command}} -- {{test_file}} 2>&1 + ``` + +2. **結果判定** + - **成功**: 修正完了。step4へ + - **同じ環境エラーが継続**: retry_count < max_retry → 別のアプローチで step2 を再試行 + - **別の問題が発生**: 環境問題が解消されたか確認し、新たな問題は報告 + - **retry_count >= max_retry**: 修正不能としてレポート + +## step4: 結果レポート + +```markdown +# env-fix 結果レポート + +## 結果: [成功 / 部分成功 / 失敗] + +## 検出された問題 +- 問題種別: [依存パッケージ / 環境変数 / 設定ファイル / 外部サービス / ランタイムバージョン] +- 詳細: [具体的な問題内容] + +## 自動修正内容 +（修正した場合のみ） +- 実行したコマンド: [コマンド一覧] +- 修正したファイル: [ファイル一覧] +- リトライ回数: X/2 + +## 手動対応が必要な項目 +（自動修正できなかった場合のみ） +- 問題: [問題内容] +- 推奨対応: [具体的な手順] +``` + +# rule + +NEVER: 機密情報（APIキー、パスワード等）をハードコードする +NEVER: 本番環境の設定を変更する +NEVER: グローバルなパッケージインストール（npm install -g） +MUST: 環境変数の値にプレースホルダが含まれる場合はレポートで明記 +MUST: docker compose 実行前にDockerが起動しているか確認 +MUST: パッケージインストール後はlockfileの変更をレポート diff --git a/commands/flaky-fix.md b/commands/flaky-fix.md new file mode 100644 index 0000000..8e0f7dc --- /dev/null +++ b/commands/flaky-fix.md @@ -0,0 +1,126 @@ +--- +description: 不安定なテスト（flaky test）の原因を分析し、テストの安定化を試みます。auto-debugから委譲される他、ユーザが直接呼び出すことも可能です。 +allowed-tools: Read, Glob, Grep, Task, Edit, Write +argument-hint: "[テストファイルパス]" +--- +flaky testを安定化して。 + +# context + +``` +test_command: {{test_command}} (テスト実行コマンド。未指定の場合は npm test) +test_file: {{test_file}} (対象テストファイル) +error_output: {{error_output}} (失敗時のエラー出力) +max_retry: 2 (修正の最大リトライ回数) +stability_runs: 3 (安定性確認の実行回数) +``` + +# step + +## step0: プロジェクトコンテキストの確認 + +以下のファイルが存在する場合は読み取り、テスト実行方法や開発ルールを把握する: +- `CLAUDE.md` — テスト実行方法、プロジェクト固有の指示 +- `README.md` — テストフレームワーク、セットアップ手順 +- `AGENTS.md` — エージェント向けの開発ルール + +test_command が未指定の場合は、これらの情報から適切なテストコマンドを決定する。 + +## step1: flaky原因の分析 + +1. **テストファイルと関連コードの読み取り** + - 対象テストファイルを Read tool で読み取り + - テスト対象の実装ファイルを特定 + +2. **原因分析**（Task tool, subagent_type: Explore, thoroughness: **medium**） + - 以下のflaky原因パターンに沿って分析: + - **タイミング依存**: 非同期処理のawait不足、setTimeout依存、競合状態 + - **共有状態**: グローバル変数、DB状態、ファイルシステム状態のテスト間汚染 + - **外部サービス依存**: API呼び出し、ネットワーク通信、外部DB + - **ランダム性**: Math.random, Date.now, UUID生成等の非決定的処理 + - **順序依存**: テスト実行順序に依存する暗黙の前提 + - **リソース制限**: メモリ不足、ファイルディスクリプタ枯渇、ポート競合 + - 最も可能性の高い原因を特定し、修正方針を決定 + +## step2: テストコードの修正 + +原因に応じた修正を実施（general-purpose subagent）: + +1. **タイミング依存の場合** + - 不足しているawaitの追加 + - setTimeout → 適切なイベント待機に変更 + - waitFor / waitForExpect パターンの導入 + - テスト用のタイムアウト値を十分に確保 + +2. **共有状態の場合** + - beforeEach/afterEachでの状態初期化・クリーンアップ追加 + - テスト専用のデータ生成（ユニークなID/名前） + - テスト間の依存関係の排除 + +3. **外部サービス依存の場合** + - テスト用モック/スタブの導入 + - MSW (Mock Service Worker) 等のHTTPモックの設定 + - テスト用のインメモリDB切り替え + +4. **ランダム性の場合** + - Math.random → seed付き乱数生成に変更 + - Date.now → jest.useFakeTimers() / vi.useFakeTimers() + - テスト用の固定値モック + +5. **順序依存の場合** + - 各テストの独立性を確保 + - 暗黙の前提条件を明示的なsetupに変換 + +6. **リソース制限の場合** + - afterEachでのリソース解放追加 + - 接続プールの適切な管理 + +## step3: 安定性確認 + +1. **修正後のテストを複数回実行** + ```bash + # stability_runs 回連続実行 + {{test_command}} -- {{test_file}} + {{test_command}} -- {{test_file}} + {{test_command}} -- {{test_file}} + ``` + +2. **結果判定** + - **全回成功**: 安定化成功。step4へ + - **1回でも失敗**: + - retry_count < max_retry → 別のアプローチで step1 に戻る + - retry_count >= max_retry → 安定化不能としてレポート + +## step4: 結果レポート + +```markdown +# flaky-fix 結果レポート + +## 結果: [安定化成功 / 安定化失敗] + +## 対象テスト +- ファイル: {{test_file}} + +## flaky原因 +- 原因分類: [タイミング依存 / 共有状態 / 外部依存 / ランダム性 / 順序依存 / リソース制限] +- 詳細: [具体的な原因] + +## 修正内容 +（修正した場合のみ） +- 修正ファイル: [ファイルパス] +- 修正内容: [具体的な変更内容] +- 安定性確認: X回連続成功 + +## 未解決 +（安定化できなかった場合のみ） +- 試行した修正: [各試行の内容] +- 推奨対応: [手動での安定化が必要な理由と方針] +``` + +# rule + +NEVER: テストの削除やスキップによる「安定化」 +NEVER: テストの期待値を緩くする（assertionの弱化） +MUST: テストの意図（何を検証するか）を変えない +MUST: 安定性確認は最低3回連続成功 +MUST: 修正はテストコード側を優先（実装コードの変更は最小限） diff --git a/commands/help.md b/commands/help.md new file mode 100644 index 0000000..c0f3382 --- /dev/null +++ b/commands/help.md @@ -0,0 +1,220 @@ +--- +description: tsumikiの利用可能なコマンド一覧表示、個別コマンドの詳細ヘルプ、困りごとからの最適コマンド検索を行います。 +allowed-tools: Read, Glob, Grep +argument-hint: "[コマンド名 or 困りごとテキスト（省略可）]" +--- +tsumikiのヘルプを表示して。 + +# context + +``` +args: {{args}} (引数。空=一覧表示、コマンド名=詳細、それ以外=困りごと検索) +``` + +# step + +## step1: モード判定 + +引数の内容に基づいて実行モードを判定する: + +1. **引数なし** → **Mode A: カテゴリ別一覧表示**（step2へ） +2. **引数が以下のコマンド名に一致** → **Mode B: コマンド詳細表示**（step3へ） + - 一致判定対象のコマンド名リスト: + - kairo-requirements, kairo-design, kairo-tasks, kairo-loop, kairo-implement + - tdd-requirements, tdd-testcases, tdd-red, tdd-green, tdd-refactor, tdd-verify-complete + - auto-debug, build-fix, flaky-fix, env-fix, timeout-fix + - init-tech-stack, direct-setup, direct-verify + - orchestrate, help + - rev-requirements, rev-design, rev-specs, rev-tasks + - dcs:bug-analysis, dcs:edgecase-analysis, dcs:feature-rubber-duck, dcs:impact-analysis, dcs:incremental-dev, dcs:performance-analysis, dcs:sequence-diagram-analysis, dcs:state-transition-analysis, dcs:test-performance-analysis + - `/tsumiki:` プレフィックス付き（例: `/tsumiki:auto-debug`）や `/` プレフィックス付き（例: `/auto-debug`）でも一致とみなす +3. **上記に一致しない** → **Mode C: 困りごと検索**（step4へ） + +## step2: Mode A — カテゴリ別一覧表示 + +以下の内容をそのまま表示する: + +``` +# tsumiki コマンド一覧 + +## Kairo開発（要件定義〜実装の一気通貫開発） + +| コマンド | 説明 | +|---------|------| +| /tsumiki:kairo-requirements | 要件の概要からEARS記法を使用した詳細な要件定義書を作成 | +| /tsumiki:kairo-design | 承認された要件定義書に基づいて技術設計文書を生成 | +| /tsumiki:kairo-tasks | 設計文書に基づいて実装タスクを1日単位で分割・フェーズ管理 | +| /tsumiki:kairo-loop | 指定したTASK範囲のkairo実装を開始から終了まで順番に自動実行 | +| /tsumiki:kairo-implement | 分割されたタスクを順番に、またはユーザが指定したタスクをTDDで実装 | + +## TDD開発（テスト駆動開発の各フェーズ） + +| コマンド | 説明 | +|---------|------| +| /tsumiki:tdd-requirements | TDD開発の要件整理。機能要件を明確化 | +| /tsumiki:tdd-testcases | 要件に基づいた包括的なテストケースの洗い出し | +| /tsumiki:tdd-red | Redフェーズ: 失敗するテストケースを作成 | +| /tsumiki:tdd-green | Greenフェーズ: テストを通す実装を行う | +| /tsumiki:tdd-refactor | Refactorフェーズ: コード品質の改善 | +| /tsumiki:tdd-verify-complete | すべてのテストケースの実装完了を検証 | + +## デバッグ・修正 + +| コマンド | 説明 | +|---------|------| +| /tsumiki:auto-debug | テストエラーの自動デバッグ。全テスト確認→原因調査→修正まで一括実行 | +| /tsumiki:build-fix | ビルドエラー（コンパイル・型・依存パッケージ）を自動分析・修正 | +| /tsumiki:flaky-fix | 不安定なテスト（flaky test）の原因分析と安定化 | +| /tsumiki:env-fix | 環境依存問題（パッケージ不足・環境変数・設定不備）を自動修正 | +| /tsumiki:timeout-fix | テスト実行のタイムアウト問題を分析し高速化または分離 | + +## セットアップ + +| コマンド | 説明 | +|---------|------| +| /tsumiki:init-tech-stack | プロジェクト初期設定として技術スタックを選定 | +| /tsumiki:direct-setup | DIRECTタスクの設定作業（環境構築・設定ファイル・依存関係） | +| /tsumiki:direct-verify | DIRECTタスクの動作確認とテスト | + +## リバースエンジニアリング（既存コードからドキュメント逆生成） + +| コマンド | 説明 | +|---------|------| +| /tsumiki:rev-tasks | 既存コードベースを分析しタスク一覧として整理 | +| /tsumiki:rev-design | 既存コードベースから技術設計文書を逆生成 | +| /tsumiki:rev-specs | 既存コードベースからテストケースと仕様書を逆生成 | +| /tsumiki:rev-requirements | 既存コードベースから要件定義書を逆生成 | + +## DCS分析（Deep Code Survey） + +| コマンド | 説明 | +|---------|------| +| /tsumiki:dcs:bug-analysis | バグの原因を特定するための詳細分析を実施 | +| /tsumiki:dcs:edgecase-analysis | エッジケース・エラー状態を包括的に分析し洗い出す | +| /tsumiki:dcs:feature-rubber-duck | アイデアを整理して実現可能なPRDを作成 | +| /tsumiki:dcs:impact-analysis | 変更対象の影響範囲分析を実施 | +| /tsumiki:dcs:incremental-dev | 増分開発の計画を立案 | +| /tsumiki:dcs:performance-analysis | 性能問題の原因を調査 | +| /tsumiki:dcs:sequence-diagram-analysis | 機能のシーケンス図をmermaid形式で作成 | +| /tsumiki:dcs:state-transition-analysis | データの状態遷移フローを包括的に分析 | +| /tsumiki:dcs:test-performance-analysis | テスト実行速度を分析しリファクタリング提案を行う | + +## その他 + +| コマンド | 説明 | +|---------|------| +| /tsumiki:orchestrate | 複雑な依頼を自動分析しエージェントチームで実行・検証・再試行 | + +--- + +**使い方:** +- `/tsumiki:help <コマンド名>` — コマンドの詳細ヘルプを表示（例: `/tsumiki:help auto-debug`） +- `/tsumiki:help <困りごと>` — 困りごとに対応するコマンドを検索（例: `/tsumiki:help テストが失敗する`） +``` + +表示したら終了。 + +## step3: Mode B — コマンド詳細表示 + +1. **コマンドファイルの読み取り** + - `commands/{{コマンド名}}.md` を Read tool で読み取る + +2. **以下の情報を抽出して表示** + +``` +# /tsumiki:{{コマンド名}} + +## 概要 +{{frontmatter の description}} + +## 使い方 +/tsumiki:{{コマンド名}} {{frontmatter の argument-hint}} + +## 処理ステップ +（コマンドファイル内の `## step` セクションを要約。各ステップのタイトルと1行説明を箇条書き） + +## 注意事項 +（コマンドファイル内の `# rule` セクションの NEVER / MUST ルールを箇条書き） +``` + +3. 表示したら終了。 + +## step4: Mode C — 困りごと検索 + +### step4-1: 定型マッピングによる検索 + +入力テキストに以下のキーワードが含まれるかチェックする。**複数一致する場合はすべて表示**する: + +| キーワード | 推奨コマンド | 説明 | +|-----------|-------------|------| +| テスト失敗, テストエラー, デバッグ, テストが落ちる, テスト修正 | /tsumiki:auto-debug | テストエラーの自動デバッグ | +| ビルドエラー, コンパイルエラー, 型エラー, ビルドが通らない, TypeScriptエラー | /tsumiki:build-fix | ビルドエラーの自動修正 | +| テスト不安定, flaky, たまに落ちる, ランダムに失敗, 不安定なテスト | /tsumiki:flaky-fix | flakyテストの安定化 | +| タイムアウト, テストが遅い, 時間がかかる, timeout | /tsumiki:timeout-fix | タイムアウト問題の改善・テスト分離 | +| 環境エラー, パッケージ不足, 環境変数, npm ci, モジュール不足, Cannot find module | /tsumiki:env-fix | 環境依存問題の自動修正 | +| TDD, テスト駆動, テストから書きたい, テストファースト | /tsumiki:tdd-requirements | TDD開発の要件整理から開始 | +| 要件定義, 要件整理, 仕様を決めたい | /tsumiki:kairo-requirements | EARS記法による要件定義書作成 | +| 設計, アーキテクチャ, 技術設計 | /tsumiki:kairo-design | 技術設計文書の生成 | +| タスク分割, 実装計画, スケジュール | /tsumiki:kairo-tasks | タスクの分割とフェーズ管理 | +| 実装したい, コードを書きたい, 機能追加, 一気通貫 | /tsumiki:kairo-loop | TASK範囲のkairo実装を自動実行 | +| タスク実装, TDD実装, kairo実装, タスクを実装したい | /tsumiki:kairo-implement | 分割されたタスクをTDDで順番に実装 | +| 技術スタック, プロジェクト初期設定, 初期化 | /tsumiki:init-tech-stack | 技術スタックの選定 | +| 複雑なタスク, 自動化, 一括実行, 複数ステップ | /tsumiki:orchestrate | エージェントチームによる自動実行 | +| 設定作業, 環境構築, セットアップ | /tsumiki:direct-setup | DIRECT設定作業の実行 | +| 動作確認, 設定検証 | /tsumiki:direct-verify | DIRECTタスクの動作確認 | +| リバースエンジニアリング, 既存コード分析, ドキュメント逆生成, タスク抽出 | /tsumiki:rev-tasks | 既存コードからタスク一覧を整理 | +| 既存コード設計, 設計書逆生成, アーキテクチャ抽出 | /tsumiki:rev-design | 既存コードから技術設計文書を逆生成 | +| 仕様逆生成, テストケース抽出, 仕様書生成 | /tsumiki:rev-specs | 既存コードからテストケース・仕様書を逆生成 | +| 要件逆生成, 要件抽出, EARS逆生成 | /tsumiki:rev-requirements | 既存コードから要件定義書を逆生成 | +| バグ分析, バグ調査, 原因特定 | /tsumiki:dcs:bug-analysis | バグの原因を詳細分析 | +| エッジケース, 異常系, エラー状態, 境界値 | /tsumiki:dcs:edgecase-analysis | エッジケース・エラー状態の包括分析 | +| 仕様の壁打ち, アイデア整理, 要件を相談, PRD作成 | /tsumiki:dcs:feature-rubber-duck | アイデアを整理してPRDを作成 | +| 影響範囲, 影響分析, 変更影響, リスク評価 | /tsumiki:dcs:impact-analysis | 変更対象の影響範囲分析 | +| 増分開発, 段階的実装, インクリメンタル | /tsumiki:dcs:incremental-dev | 増分開発の計画立案 | +| 性能問題, パフォーマンス, レスポンス遅い, 速度改善 | /tsumiki:dcs:performance-analysis | 性能問題の原因調査 | +| シーケンス図, 処理フロー, mermaid, フロー図 | /tsumiki:dcs:sequence-diagram-analysis | シーケンス図をmermaid形式で作成 | +| 状態遷移, ステート, ステータス管理, ライフサイクル | /tsumiki:dcs:state-transition-analysis | データの状態遷移フロー分析 | +| テスト速度分析, テスト遅い原因, テスト計測 | /tsumiki:dcs:test-performance-analysis | テスト実行速度の分析とリファクタリング提案 | + +### step4-2: 結果の表示 + +**一致あり の場合:** + +``` +# 「{{入力テキスト}}」に対応するコマンド + +{{一致したコマンドごとに:}} +## /tsumiki:{{コマンド名}} +{{説明}} + +--- +`/tsumiki:help {{コマンド名}}` で詳細を確認できます。 +``` + +**一致なし の場合（AI推論フォールバック）:** + +全対象コマンドの description を参照し、入力テキストの困りごとに最も適したコマンドを推論する: + +1. 全対象コマンド（33件）の description とステップ概要を把握 +2. 入力テキストの意図を分析 +3. 関連度の高いコマンドを最大3件まで推薦 +4. 「該当するコマンドが見つかりませんでした」の場合もありうる + +``` +# 「{{入力テキスト}}」に関連するコマンド（AI推論） + +{{推薦コマンドごとに:}} +## /tsumiki:{{コマンド名}} +{{description}} +推薦理由: {{なぜこのコマンドが関連するか}} + +--- +`/tsumiki:help {{コマンド名}}` で詳細を確認できます。 +``` + +# rule + +NEVER: コマンドの description を改変して表示する +MUST: Mode B でコマンドファイルを読み取る際は Read tool を使用する +MUST: Mode C の定型マッピングで一致がない場合のみ AI推論を使用する +MUST: AI推論の結果には「AI推論」であることを明示する diff --git a/commands/kairo-implement.md b/commands/kairo-implement.md deleted file mode 100644 index ea94235..0000000 --- a/commands/kairo-implement.md +++ /dev/null @@ -1,669 +0,0 @@ ---- -description: 分割されたタスクを順番に、またはユーザが指定したタスクを実装します。既存のTDDコマンドを活用して品質の高い実装を行います。 -allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, AskUserQuestion, TaskList, TaskGet, TaskUpdate -allowed-skills: tsumiki:tdd-tasknote, tsumiki:tdd-requirements, tsumiki:tdd-testcases, tsumiki:tdd-red, tsumiki:tdd-green, tsumiki:tdd-refactor, tsumiki:tdd-verify-complete, tsumiki:direct-setup, tsumiki:direct-verify -argument-hint: "[要件名（省略可）] [TASK-ID (TASK-00001)] [--hil]" ---- -あなたは実装担当者です。残タスクを調べて 指定されたコマンドを駆使して実装をしてください - -# kairo-implement - -## 目的 - -分割されたタスクを順番に、またはユーザが指定したタスクを実装する。既存のTDDコマンドを活用して品質の高い実装を行う。 - -## オプション - -- `--hil` (Human-in-the-Loop): テストケース作成後にユーザーの確認を求め、承認後にtdd-red以降のフェーズを実行する -- `--model [defaultModel]` タスク内で利用する最優先のデフォルトのモデルを指定する。設定がない場合はauto(それぞれのデフォルトを優先) sonnet/opusなどの指定が可能 -- `--think-model [thinkModelName]`: requirements/testcasesのモデル名を指定。デフォルトは opus -- `--tdd-model [tddModelName]`: red/green/refactor/verify-complete のモデル名を指定。デフォルトはsonnet -- `--note-model [noteModelName]`: tasknote のモデル名を指定。デフォルトはhaiku - -## 前提条件 - -- `docs/tasks/{要件名}-tasks.md` にタスク一覧が存在する -- ユーザがタスクの実装を承認している -- 既存のTDDコマンドが利用可能である -- 実装用のワークスペースが設定されている -- task_id は　`TASK-{4桁の数字}` (例 TASK-0001 ) である -- thinkTaskName を コマンド選択ルール で設定する。 thinkModelName , defaultModel, `opus` -- tddTaskName を コマンド選択ルール で設定する。 tddModelName , defaultModel, `sonnet` -- noteTaskName を コマンド選択ルール で設定する。 noteModelName , defaultModel, `haiku` - -## コマンド選択ルール - -### パラメータ -- selectModel -- defaultModel -- commandDefaultModel - -### ルール - -selectModel は　(selectModel == null && defaultModel != null) の場合、 defaultModel -selectModel は　(selectModel == null && defaultModel == null) の場合、 commandDefaultModel - -この時点で selectModel が null の場合は sonnetにする - -selectModelに -- `sonnet` が指定されている場合は `sonnet` を返す -- `opus` が指定されている場合は `opus` を返す -- `haiku` が指定されている場合は `haiku` を返す - -## 実行内容 - -**【信頼性レベル指示】**: -各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： - -- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 -- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 -- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 - -0. **Claude Codeタスクシステムの確認** - - TaskList ツールで未完了のタスク（pending/in_progress）を確認 - - タスクのsubjectが "TASK-" で始まるものを抽出 - - 各タスクについて： - - TaskGet でタスクの詳細情報を取得 - - metadata から以下を取得： - - `requirement_name`: 要件名 - - `task_file`: タスクファイルパス（例: docs/tasks/db-migration-tool/TASK-0001.md） - - `phase`: フェーズ情報 - - `task_type`: タスクタイプ（TDD/DIRECT） - - 引数の優先順位： - - **引数で要件名が指定されている場合**: 引数の要件名を使用 - - **引数で要件名が省略されている場合**: Claude Codeタスクのmetadataから要件名を取得 - - **TASK-IDの決定**: - - 引数でTASK-IDが指定されている場合: 引数のTASK-IDを使用 - - 引数でTASK-IDが省略されている場合: - - blockedByが空（依存タスクがない）かつstatus=pendingの最初のタスクを選択 - - 選択したタスクのsubjectからTASK-IDを抽出（例: "TASK-0001: タスク名" → TASK-0001） - - 選択したClaude CodeタスクのIDを記録（後でステータス更新に使用） - -1. **追加ルールの読み込み** - - `docs/spec/{要件名}/note.md` が存在する場合は読み込み - -2. **プロジェクト文書の読み込み** - - - **タスク関連文書の読み込み**: - - `docs/tasks/{要件名}/overview.md` or `docs/tasks/{要件名}-overview.md` - タスク全体概要 - - `docs/tasks/{要件名}/TASK-{task_id}.md` or `docs/tasks/{要件名}-tasks.md` - 対象タスクファイル - - 依存タスクのファイルも読み込み、実装の順序と関連性を理解 - - Claude Codeタスクのmetadataにtask_fileがある場合はそのパスを優先使用 - -3. **タスクの選択と実行開始** - - 選択されたタスクの詳細を表示 - - Claude Codeタスクが選択されている場合: - - TaskUpdate でステータスを 'in_progress' に更新 - - 更新内容を表示: "📌 Claude Codeタスク #{task_id} を実行中に設定しました" - - 読み込んだ技術スタック定義に基づいて実装方針を決定 - -4. **依存関係の確認** - - Claude CodeタスクのblockedByフィールドを確認 - - 依存タスクが完了しているか確認（status=completed） - - 未完了の依存タスクがある場合は警告 - - Task tool (subagent_type: Explore, thoroughness: quick) を使用して依存タスクファイルの状態も確認 - -5. **実装ディレクトリの準備** - - 現在のワークスペースで作業を行う - - 必要に応じてディレクトリ構造を確認 - -6. **実装タイプの判定** - - タスクの性質を分析（コード実装 vs 準備作業） - - 実装方式を決定（TDD vs 直接作業） - - Claude Codeタスクのmetadata.task_typeも参考にする - -7. **実装プロセスの実行** - - ### A. **TDDプロセス**（コード実装タスク用） - - a. **コンテキスト準備** - `@Task tool (subagent_type: general-purpose, model: {{noteTaskName}}) /tsumiki:tdd-tasknote` - ``` - Task実行: TDDコンテキスト準備フェーズ - 目的: タスクノートを生成し、開発に必要なコンテキスト情報を収集する - 収集内容: - - 技術スタック（使用技術・フレームワーク・アーキテクチャパターン） - - 開発ルール（コーディング規約・型チェック・テスト要件） - - 関連実装（既存の実装パターン・参考コード） - - 設計文書（データモデル・ディレクトリ構造） - - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） - コマンド: /tsumiki:tdd-tasknote {要件名} {TASK-ID} - 実行方式: 個別Task実行 - 出力ファイル: docs/implements/{要件名}/{TASK-ID}/note.md - ``` - - b. **要件定義** - `@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-requirements` - ``` - Task実行: TDD要件定義フェーズ - 目的: タスクの詳細要件を記述し、受け入れ基準を明確化する - 前提条件: タスクノート（note.md）が存在すること - コマンド: /tsumiki:tdd-requirements {要件名} {TASK-ID} - 実行方式: 個別Task実行 - ``` - - c. **テストケース作成** - `@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-testcases` - ``` - Task実行: TDDテストケース作成フェーズ - 目的: 単体テストケースを作成し、エッジケースを考慮する - コマンド: /tsumiki:tdd-testcases - 実行方式: 個別Task実行 - ``` - - c-1. **ユーザー確認** (--hilオプション指定時のみ) - ``` - テストケース確認フェーズ: - - 作成されたテストケース一覧を表示 - - テストケースの妥当性をユーザーに確認 - - ユーザーからのフィードバックを受け取る - - 必要に応じてテストケースを修正 - - 承認後、d. tdd-red以降のフェーズを実行 - - 確認内容: - - テストケースが要件を満たしているか - - エッジケース・エラーケースが十分か - - テストケースの数と粒度が適切か - - 追加・修正が必要なテストケースはないか - ``` - - d. **テスト実装** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-red` - ``` - Task実行: TDDレッドフェーズ - 目的: 失敗するテストを実装し、テストが失敗することを確認する - コマンド: /tsumiki:tdd-red - 実行方式: 個別Task実行 - ``` - - e. **最小実装** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-green` - ``` - Task実行: TDDグリーンフェーズ - 目的: テストが通る最小限の実装を行い、過度な実装を避ける - コマンド: /tsumiki:tdd-green - 実行方式: 個別Task実行 - ``` - - f. **リファクタリング** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-refactor` - ``` - Task実行: TDDリファクタリングフェーズ - 目的: コードの品質向上と保守性の改善を行う - コマンド: /tsumiki:tdd-refactor - 実行方式: 個別Task実行 - ``` - - g. **品質確認** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-verify-complete` - ``` - Task実行: TDD品質確認フェーズ - 目的: 実装の完成度とテストケースの充足度を確認する - 確認項目: - - すべてのテストケースが実装されているか - - すべてのテストケースが成功しているか - - テストカバレッジが要求水準を満たしているか - - エッジケースがすべてカバーされているか - - 判定基準: - - テストケースが不足している場合: d(tdd-red)から繰り返す - - テストケースは十分だが実装が不足している場合: e(tdd-green)から繰り返す - - 実装・テストともに十分な場合: 次のステップ（h. タスク完了処理）へ - - コマンド: /tsumiki:tdd-verify-complete - 実行方式: 個別Task実行 - ``` - - h. **タスク完了処理** - ``` - 品質確認が成功した後の処理: - - タスクファイルの完了チェックボックスを更新 - - Claude Codeタスクシステムの更新: - - TaskUpdate でステータスを 'completed' に更新 - - 更新結果を表示: "✅ Claude Codeタスク #{task_id} を完了に設定しました" - - 実装サマリーの作成 - - 次のタスクの提案（依存関係が解消された次のタスク） - ``` - - ### B. **直接作業プロセス**（準備作業タスク用） - - a. **準備作業の実行** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-setup` - ``` - Task実行: 直接作業実行フェーズ - 目的: ディレクトリ作成、設定ファイル作成、依存関係のインストール、環境設定を行う - 作業内容: - - ディレクトリ作成 - - 設定ファイル作成 - - 依存関係のインストール - - 環境設定 - 実行方式: 個別Task実行 - ``` - - b. **作業結果の確認** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-verify` - ``` - Task実行: 直接作業確認フェーズ - 目的: 作業完了の検証と成果物確認を行う - 作業内容: - - 作業完了の検証 - - 期待された成果物の確認 - - 次のタスクへの準備状況確認 - 実行方式: 個別Task実行 - ``` - - c. **タスク完了処理** - ``` - 作業確認が成功した後の処理: - - タスクファイルの完了チェックボックスを更新 - - Claude Codeタスクシステムの更新: - - TaskUpdate でステータスを 'completed' に更新 - - 更新結果を表示: "✅ Claude Codeタスク #{task_id} を完了に設定しました" - - 実装サマリーの作成 - - 次のタスクの提案（依存関係が解消された次のタスク） - ``` - -7. **全体の完了確認** - - タスクのステータスを更新（タスクファイルのチェックボックスにチェックを入れる） - - Claude Codeタスクシステムの更新: - - TaskUpdate でステータスを 'completed' に更新 - - 依存関係が解消された次のタスクを TaskList で確認 - - 実装結果をドキュメント化 - - 次のタスクを提案（Claude Codeタスクの依存関係を考慮） - -## 実行フロー - -```mermaid -flowchart TD - A0[0. Claude Codeタスク確認] --> A0_1{タスク存在?} - A0_1 -->|Yes| A0_2[要件名・TASK-ID取得] - A0_1 -->|No| A0_3[引数から取得] - A0_2 --> A0_4[TaskUpdate: in_progress] - A0_3 --> A - A0_4 --> A[1. 追加ルール読み込み] - A --> A1[2. プロジェクト文書読み込み] - A1 --> A2[要件定義書・設計文書] - A2 --> B[3. タスク選択確認] - B --> D{4. 依存関係OK?} - D -->|No| E[警告表示] - D -->|Yes| F[5. ディレクトリ準備] - F --> G{6. タスクタイプ判定} - - G -->|コード実装| H[TDDプロセス] - G -->|準備作業| M[直接作業プロセス] - - H --> H0[a. tdd-tasknote] - H0 --> H1[b. tdd-requirements] - H1 --> H2[c. tdd-testcases] - H2 --> H2_1{--hil指定?} - H2_1 -->|Yes| H2_2[c-1. ユーザー確認] - H2_1 -->|No| H3[d. tdd-red] - H2_2 --> H2_3{承認?} - H2_3 -->|修正必要| H2[c. tdd-testcases] - H2_3 -->|承認| H3 - H3 --> H4[e. tdd-green] - H4 --> H5[f. tdd-refactor] - H5 --> H6[g. tdd-verify-complete] - - H6 --> H7{品質判定} - H7 -->|テストケース不足| H3 - H7 -->|実装不足| H4 - H7 -->|OK| H8[h. タスク完了処理] - - M --> M1[a. direct-setup] - M1 --> M2[b. direct-verify] - M2 --> M3[c. タスク完了処理] - - H8 --> H9[TaskUpdate: completed] - M3 --> M4[TaskUpdate: completed] - - H9 --> I{8. 他のタスク?} - M4 --> I - I -->|Yes| A0 - I -->|No| J[全タスク完了] -``` - -## コマンド実行例 - -```bash -# 全タスクを順番に実装 -$ /tsumiki:kairo-implement {要件名} - -# 特定のタスクを実装 -$ /tsumiki:kairo-implement {要件名} TASK-0001 - -# Human-in-the-Loopモードで実装（テストケース作成後に確認） -$ /tsumiki:kairo-implement {要件名} TASK-0001 --hil - -# Human-in-the-Loopモードで全タスクを実装 -$ /tsumiki:kairo-implement {要件名} --hil - -# Claude Codeタスクシステムと連携（引数省略） -# - 未完了のClaude Codeタスクから自動的に要件名とTASK-IDを取得 -# - タスク開始時にステータスを in_progress に更新 -# - タスク完了時にステータスを completed に更新 -$ /tsumiki:kairo-implement - -# Claude Codeタスクシステムと連携（要件名のみ指定） -# - 指定した要件名のClaude Codeタスクから最初の未完了タスクを選択 -$ /tsumiki:kairo-implement {要件名} -``` - -## 実装タイプ判定基準 - -### TDDプロセス（コード実装タスク） - -以下の条件に当てはまるタスク： - -- 新しいコンポーネント、サービス、フック等の実装 -- 既存コードの機能追加・修正 -- ビジネスロジックの実装 -- API実装 - -**例**: TaskService実装、UIコンポーネント作成、状態管理実装 - -### 直接作業プロセス（準備作業タスク） - -以下の条件に当てはまるタスク： - -- プロジェクト初期化・環境構築 -- ディレクトリ構造作成 -- 設定ファイル作成・更新 -- 依存関係のインストール -- ツール設定・設定 - -**例**: プロジェクト初期化、データベース設定、開発環境設定 - -## 個別Task実行アプローチ - -### Task実行の方針 - -各実装ステップを個別のTaskとして実行することで、以下のメリットが得られます： - -1. **独立性**: 各ステップが独立して実行され、エラー発生時の切り分けが容易 -2. **再実行性**: 特定のステップのみ再実行が可能 -3. **並列性**: 依存関係のないステップは並列実行可能 -4. **追跡性**: 各ステップの実行状況と結果が明確に記録される - -### Task実行パターン - -```bash -# TDDプロセスの場合 -@Task tool (subagent_type: general-purpose, model: {{noteTaskName}}) /tsumiki:tdd-tasknote {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-requirements {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-testcases {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-red {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-green {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-refactor {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-verify-complete {要件名} {TASK-ID} - -# 直接作業プロセスの場合 -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-setup {要件名} {TASK-ID} -@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-verify {要件名} {TASK-ID} -``` - -## 実装時の注意事項 - -### 全般 - -1. **Claude Codeタスクシステム連携** - - 実行開始時に TaskList で未完了タスクを確認 - - タスク開始時に TaskUpdate でステータスを 'in_progress' に更新 - - タスク完了時に TaskUpdate でステータスを 'completed' に更新 - - metadata から要件名、タスクファイルパス、タイプを取得 - - 引数が省略された場合は Claude Codeタスクの情報を使用 - - 依存関係（blockedBy）を考慮して次のタスクを提案 - -2. **プロジェクト文書の活用** - - 要件定義書（EARS記法）を常に参照し、実装の根拠を明確にする - - 設計文書に記載されたアーキテクチャ、データフロー、API仕様に従う - - タスクファイルの「関連文書」セクションから必要な文書を確認 - - 信頼性レベル（🔵🟡🔴）を参考に、推測が必要な箇所を特定 - -3. **ファイル構造の理解** - - `docs/spec/{要件名}/` - 要件定義書 - - `docs/design/{要件名}/` - 設計文書 - - `docs/tasks/{要件名}/` - タスク管理 - - 各タスクファイルには依存関係と関連文書へのリンクが含まれる - -### TDDプロセス用 - -4. **--hilオプション使用時の注意** - - テストケース作成後、必ずユーザーの確認を待つ - - ユーザーが承認するまでtdd-red以降のフェーズを実行しない - - 修正指示があった場合は、tdd-testcasesフェーズから再実行 - - AskUserQuestion ツールを使用してユーザーの選択を取得 - -5. **テストファースト** - - 必ずテストを先に書く - - テストが失敗することを確認してから実装 - -6. **インクリメンタルな実装** - - 一度に全てを実装しない - - 小さなステップで進める - -7. **品質確認の徹底** - - 各ステップで品質を確認 - - 技術的負債を作らない - - **テストケース充足度の確認**: - - すべての要件に対してテストケースが存在するか - - エッジケース、エラーケース、境界値テストが含まれているか - - テストカバレッジが基準を満たしているか（目安: 80%以上） - - **実装完成度の確認**: - - すべてのテストケースが成功しているか - - 要件定義書・設計文書に記載された仕様を満たしているか - - コード品質（可読性、保守性）が基準を満たしているか - -8. **品質確認後の対応** - - テストケース不足の場合: - - d. tdd-red に戻り、不足しているテストケースを追加 - - e. tdd-green で実装を追加 - - f. tdd-refactor でリファクタリング - - g. tdd-verify-complete で再確認 - - 実装不足の場合（テストケースは十分）: - - e. tdd-green に戻り、失敗しているテストを通す実装を追加 - - f. tdd-refactor でリファクタリング - - g. tdd-verify-complete で再確認 - -9. **Human-in-the-Loop実行フロー** - - --hilオプション指定時: - 1. c. tdd-testcases でテストケースを作成 - 2. c-1. 作成されたテストケースの一覧と分析結果を表示 - 3. AskUserQuestionツールでユーザーの選択を取得: - - 「承認」: d. tdd-red以降のフェーズを続行 - - 「修正」: ユーザーの指示に基づいてテストケースを修正後、c-1に戻る - - 「キャンセル」: 実装を中断し、現在の状態を保存 - 4. 承認後、通常のTDDプロセスを続行 - -### 直接作業プロセス用 - -10. **作業の段階的実行** - - 依存関係を考慮した順序で実行 - - 各ステップの完了を確認 - -11. **設定の検証** - - 作成した設定ファイルの動作確認 - - 環境の正常性チェック - -12. **ドキュメントの更新** - - 実装と同時にドキュメントも更新 - - 他の開発者が理解できるように - -## 出力フォーマット - -### タスク開始時（TDDプロセス） - -``` -🚀 タスク {{task_id}}: {{task_name}} の実装を開始します - -📋 タスク詳細: -- 要件: REQ-101, REQ-102 -- 依存: {{依存タスクID}} ✅ -- 推定時間: 4時間 -- 実装タイプ: TDDプロセス -- Claude Codeタスク: #{{claude_task_id}} (in_progress) - -🔄 TDDプロセスを開始します... -``` - -### タスク開始時（直接作業プロセス） - -``` -🚀 タスク {{task_id}}: {{task_name}} の実装を開始します - -📋 タスク詳細: -- 要件: REQ-402, REQ-006 -- 依存: {{依存タスクID}} ✅ -- 推定時間: 3時間 -- 実装タイプ: 直接作業プロセス -- Claude Codeタスク: #{{claude_task_id}} (in_progress) - -🔧 準備作業を開始します... -``` - -### 各ステップ完了時（TDD） - -``` -✅ Task 1/8: @task /tsumiki:tdd-tasknote 完了 - ファイル: docs/implements/{要件名}/{{task_id}}/note.md - Task実行結果: タスクノート作成完了 - -✅ Task 2/8: @task /tsumiki:tdd-requirements 完了 - ファイル: docs/implements/{要件名}/{{task_id}}/{要件名}-requirements.md - Task実行結果: 要件定義書作成完了 - -🏃 Task 3/8: @task /tsumiki:tdd-testcases 実行中... - Task実行: TDDテストケース作成フェーズを開始 - -... - -✅ Task 7/8: @task /tsumiki:tdd-verify-complete 完了 - 品質確認結果: - - テストケース充足度: 95% (26/27件実装済み) - - テストケース成功率: 92% (24/26件成功) - - テストカバレッジ: 88% - - 判定: テストケース不足あり & 実装不足あり - → Task 4/8 (tdd-red) から再実行します - -🏃 Task 4/8: @task /tsumiki:tdd-red 実行中... - 不足しているテストケースを追加します -``` - -### ユーザー確認時（--hilオプション指定時） - -``` -✅ Task 3/8: @task /tsumiki:tdd-testcases 完了 - ファイル: docs/implements/{要件名}/{{task_id}}/testcases.md - -📋 作成されたテストケース (27個): - -【正常系テストケース】 -1. ✓ 有効なタスクIDでタスクが正常に作成できる -2. ✓ 必須フィールドが全て設定された状態でタスクが作成できる -3. ✓ オプションフィールドを省略してもタスクが作成できる -... - -【異常系テストケース】 -15. ✓ 無効なタスクID形式でエラーが返される -16. ✓ 必須フィールド不足でバリデーションエラーが返される -17. ✓ 重複するタスクIDでエラーが返される -... - -【境界値テストケース】 -24. ✓ タスク名の最小文字数(1文字)で作成できる -25. ✓ タスク名の最大文字数(200文字)で作成できる -... - -🔍 テストケースレビューポイント: -- 要件カバレッジ: 100% (全要件に対応) -- エッジケースカバレッジ: 85% (主要なエッジケースをカバー) -- エラーケースカバレッジ: 90% (主要なエラーパターンをカバー) - -⏸️ このテストケースで実装を進めてよろしいですか? - -選択肢: -1. [承認] テストケースを承認してtdd-red以降を実行 -2. [修正] テストケースの修正・追加を指示 -3. [キャンセル] 実装を中断 - -あなたの選択: _ -``` - -### 各ステップ完了時（直接作業） - -``` -✅ Task 1/2: @task /tsumiki:direct-setup 完了 - 作成ファイル: 8個、設定更新: 3個 - Task実行結果: 準備作業実行完了 - -🏃 Task 2/2: @task /tsumiki:direct-verify 実行中... - Task実行: 直接作業確認フェーズを開始 -``` - -### タスク完了時（TDD） - -``` -🎉 タスク {{task_id}} が完了しました！ - -✅ タスクファイルのチェックボックスを更新しました - - [ ] **タスク完了** → [x] **タスク完了** - -✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました - - Status: in_progress → completed - -📊 実装サマリー: -- 実装タイプ: TDDプロセス (個別Task実行) -- 実行Taskステップ: 8個 (全て成功) -- 品質確認の繰り返し: 2回 (初回: テストケース不足検出 → 追加実装 → 2回目: 成功) -- 作成ファイル: 13個 (タスクノート含む) -- テストケース: 27個 (全て成功) -- テストカバレッジ: 95% -- 要件充足度: 100% -- 所要時間: 4時間15分 - -📝 次の推奨タスク: -- {{次のタスクID}}: {{次のタスク名}} (Claude Codeタスク: #{{次のclaude_task_id}}) -- {{関連タスクID}}: {{関連タスク名}}（依存関係あり） - -続けて実装しますか？ (y/n) -``` - -### タスク完了時（直接作業） - -``` -🎉 タスク {{task_id}} が完了しました！ - -✅ タスクファイルのチェックボックスを更新しました - - [ ] **タスク完了** → [x] **タスク完了** - -✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました - - Status: in_progress → completed - -📊 実装サマリー: -- 実装タイプ: 直接作業プロセス (個別Task実行) -- 実行Taskステップ: 2個 (全て成功) -- 作成ファイル: 8個 -- 設定更新: 3個 -- 環境確認: 正常 -- 所要時間: 2時間30分 - -📝 次の推奨タスク: -- {{次のタスクID}}: {{次のタスク名}} (Claude Codeタスク: #{{次のclaude_task_id}}) -- {{関連タスクID}}: {{関連タスク名}}（依存関係あり） - -続けて実装しますか？ (y/n) -``` - -## エラーハンドリング - -- **Claude Codeタスク関連**: - - タスクが見つからない: 引数から要件名とTASK-IDを取得して続行 - - タスクステータス更新失敗: 警告を表示するが処理は続行 - - metadataが不完全: 引数またはタスクファイルから情報を補完 -- **依存関係**: - - 依存タスク未完了: 警告を表示し、確認を求める - - blockedByに未完了タスクがある: 依存タスクの一覧を表示 -- **実装エラー**: - - テスト失敗: 詳細なエラー情報を表示 - - ファイル競合: バックアップを作成してから上書き - -## 実行後の確認 - -- 実装したファイルの一覧を表示 -- テスト結果のサマリーを表示 -- Claude Codeタスクのステータス更新確認 -- 残りのタスクと進捗率を表示（Claude Codeタスクシステムの情報を含む） -- 次のタスクの提案を表示（依存関係が解消されたタスクを優先） -- TaskList で全体の進捗を確認 diff --git a/commands/kairo-loop.md b/commands/kairo-loop.md new file mode 100644 index 0000000..aafc565 --- /dev/null +++ b/commands/kairo-loop.md @@ -0,0 +1,24 @@ +--- +description: 指定したTASK範囲のkairo実装を開始から終了まで順番に自動実行し、品質確認・戻り処理・デバッグを含むループ処理を行います。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, AskUserQuestion, TaskList, TaskGet, TaskUpdate +argument-hint: "[要件名] [開始TASK-ID (TASK-00001)] [終了TASK-ID (TASK-00002)] " +--- + +- $1 がない場合、「引数に要件名・開始TASK-ID・終了TASK-IDを指定してください（例: /kairo-loop ユーザー認証システム TASK-00001 TASK-00005）」と言って終了する +- $2 がない場合、「引数に開始TASK-IDを指定してください（例: TASK-00001）」と言って終了する +- $3 がない場合、「引数に終了TASK-IDを指定してください（例: TASK-00005）」と言って終了する + +$0 の $1 から順番に実行してください。 $2 まで完了したら一旦終了して。 +以下の作業を実施してください +- /tsumiki:kairo-implement を理解して、skillの内容に正確に従ってください +- 実施する内容を全てtodoに詳細に記録してください。 +- 品質確認の段階で戻る処理をするときは以下の手順を組み込んでください + - 品質の確認処理 + - 戻り先決定ルールを品質確認後の戻る処理内に含めてください + - 戻り先からのステップをそれぞれtodoに追加(例:step-e追加の場合は、step-e,step-f,step-g,品質確認を追加する) + - 追加したtodoの依存関係を設定 + - 戻り先として追加したtaskに遷移する +- 最後のチェックボックスを入れる作業も含めて忘れずにtodoに追加してください +- todoには必ず依存関係を設定してください +- todoに記録が終わったら順番に実施してください +- 全ての TASK の完了が終わったら `/tsumiki:auto-debug` を実行する diff --git a/commands/orchestrate.md b/commands/orchestrate.md new file mode 100644 index 0000000..28c6be7 --- /dev/null +++ b/commands/orchestrate.md @@ -0,0 +1,381 @@ +--- +description: 複雑な依頼を自動分析し、適切なエージェントチームで実行・検証・再試行を行う高度な自動化コマンド +allowed-tools: Read, Glob, Grep, Task, TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion +argument-hint: "実施したい依頼内容(例: ログイン機能のテストを追加してバグを修正)" +--- + +このコマンドは、ユーザからの複雑な依頼を自動的に分析し、必要な作業をステップに分割し、適切なエージェントチームを編成して実行します。各ステップの成功条件を自動判定し、失敗時は原因を分析して最大5回まで自動再試行を行います。 + +# context + +``` +user_request: {{args}} (ユーザからの依頼内容) +team_name: orchestrate-{{timestamp}} (チーム名) +max_retry_per_step: 5 (1ステップあたりの最大再試行回数) +steps: [] (実行ステップのリスト) +current_step_index: 0 (現在実行中のステップ番号) +``` + +# steps + +## step1: 依頼内容の分析とプランニング + +ユーザの依頼内容を詳細に分析し、以下を決定する: + +1. **作業の洗い出し**: 依頼を達成するために必要な具体的な作業をリストアップ +2. **ステップ分割の判定**: + - シンプルな依頼(1つの明確な作業): 1ステップで実行 + - 中規模の依頼(2-3の関連作業): 2-3ステップに分割 + - 大規模な依頼(4つ以上の作業): 論理的なまとまりでステップに分割 +3. **各ステップの定義**: + - ステップ名: 何をするステップか + - 作業内容: 具体的に何を実行するか + - 成功条件: どうなれば成功か(自動判定可能な条件) + - 推奨エージェント: どのエージェントタイプが適切か + +**ステップ分割ルール**に従って分析を行い、結果を構造化してメモする。 + +## step2: チームとタスクリストの準備 + +1. **チーム作成**: + - `TeamCreate` でオーケストレーションチームを作成 + - チーム名: `orchestrate-{現在時刻のタイムスタンプ}` + +2. **タスク作成**: + - step1で定義した各ステップに対して `TaskCreate` でタスクを作成 + - subject: ステップ名 + - description: 作業内容 + 成功条件 + - activeForm: 実行中の表示メッセージ + +3. **依存関係の設定**: + - 前のステップに依存する場合は `TaskUpdate` で blockedBy を設定 + +## step3: ステップの順次実行 + +各ステップを順番に実行する(並列実行は行わない): + +1. **タスクの取得**: `TaskGet` で次の実行対象タスクを取得 +2. **タスクを進行中に更新**: `TaskUpdate` で status を `in_progress` に +3. **エージェント選定**: **エージェント選定ルール**に従って最適なエージェントタイプを選択 +4. **エージェント起動**: `Task` ツールで選定したエージェントを起動し、作業を依頼 + - prompt: 作業内容を明確に指示 + 成功条件を伝える + - team_name: 作成したチーム名 + - name: わかりやすいエージェント名(例: `step1-explorer`, `step2-implementer`) +5. **実行待機**: エージェントからの完了報告を待つ + +## step4: 結果の検証と判定 + +エージェントの実行結果を検証する: + +1. **成功条件の確認**: **成功条件判定ルール**に従って判定 + - エージェントの報告内容を確認 + - 必要に応じてファイルの状態、テスト結果等を確認 + +2. **判定結果の処理**: + - **成功の場合**: + - `TaskUpdate` で status を `completed` に更新 + - step3に戻り次のステップを実行(全ステップ完了ならstep5へ) + - **失敗の場合**: + - 再試行カウンタをチェック + - 最大再試行回数未満なら step5(再試行)へ + - 最大再試行回数到達なら step6(エスカレーション)へ + +## step5: 失敗時の原因分析と再試行 + +**再試行ルール**に従って再試行を実施: + +1. **原因分析**: + - エージェントの実行結果とエラーログを分析 + - 何が原因で成功条件を満たせなかったかを特定 + - 改善方法を検討(例: 指示の明確化、別のエージェントタイプの選択、前提条件の修正) + +2. **改善策の適用**: + - エージェントへの指示を改善 + - 必要に応じてエージェントタイプを変更 + - 前提条件が不足していれば追加の準備作業を実施 + +3. **再実行**: + - 改善した内容で `Task` ツールを再実行 + - 再試行カウンタをインクリメント + +4. **step4に戻って再検証** + +## step6: 最大再試行到達時のエスカレーション + +5回の再試行でも成功しなかった場合: + +1. **状況の整理**: + - 失敗したステップの内容 + - 試行した方法と結果 + - エラーの詳細 + +2. **ユーザへの報告**: + - 現在の状況を簡潔に報告 + - `AskUserQuestion` で次のアクションを確認: + - 「このステップをスキップして次へ進む」 + - 「手動で介入して修正する(一時中断)」 + - 「全体を中止する」 + +3. **ユーザの選択に従って処理**: + - スキップ: タスクを `completed` にして次のステップへ(step3) + - 手動介入: orchestrate を一時停止し、ユーザの作業完了後に再開 + - 中止: step7(クリーンアップ)へ + +## step7: 完了報告とクリーンアップ + +全ステップが完了したら: + +1. **完了報告**: + - 実行した全ステップの概要 + - 各ステップの結果(成功/スキップ/失敗) + - 再試行が発生したステップとその回数 + - 最終的な成果物や変更内容 + +2. **チームのシャットダウン**: + - 各エージェントに `SendMessage` で shutdown_request を送信 + - エージェントからの shutdown_response を待つ + +3. **クリーンアップ**: + - `TeamDelete` でチームを削除 + - タスクリストも自動削除される + +# rule + +## エージェント選定ルール + +作業内容に応じて最適なエージェントタイプを選択する: + +### general-purpose エージェント +- **用途**: 汎用的な実装作業、複雑な多段階タスク +- **適用例**: + - コードの実装・修正 + - テストコードの作成 + - バグ修正 + - 機能追加 + - 複数ファイルにまたがる変更 + +### Explore エージェント +- **用途**: コードベースの調査・分析 +- **適用例**: + - 既存コードの理解 + - バグの原因調査 + - パターンの検索 + - アーキテクチャの把握 + - 依存関係の分析 + +### Plan エージェント +- **用途**: 実装計画の立案 +- **適用例**: + - 大規模な実装の設計 + - アーキテクチャ決定 + - リファクタリング計画 + - マイグレーション計画 + +### Bash エージェント +- **用途**: コマンドライン操作、git操作、外部ツール実行 +- **適用例**: + - テストの実行 + - ビルドの実行 + - git操作(ブランチ作成、コミット等) + - パッケージのインストール + - 環境設定 + +### 選定の優先順位 +1. 調査が必要 → Explore +2. 計画が必要 → Plan +3. コマンド実行のみ → Bash +4. コード実装 → general-purpose +5. 迷ったら → general-purpose + +## 成功条件判定ルール + +各ステップの成功条件を自動判定する基準: + +### ファイル操作系 +- ファイルが作成/更新された +- 想定される内容が含まれている +- 構文エラーがない + +### テスト系 +- テストが実行された +- テストがパスした +- カバレッジが適切 + +### 調査系 +- 必要な情報が得られた +- 原因が特定された +- 次のステップに必要な情報が揃った + +### 実装系 +- コードが書かれた +- エラーなくビルド/実行できる +- 要求仕様を満たしている + +### 判定方法 +1. エージェントの報告内容を確認 +2. 必要に応じて `Read` でファイルを確認 +3. 必要に応じて `Bash` でテストやビルドを実行 +4. 成功条件に照らして合格/不合格を判断 + +**注意**: 完璧を求めすぎない。80%の品質で次に進めるなら進む。 + +## 再試行ルール + +失敗時の再試行は以下の方針で行う: + +### 1回目の失敗 +- **原因**: 指示が不明瞭、情報不足の可能性 +- **対策**: + - 指示をより具体的に修正 + - 必要な前提情報を追加 + - 成功条件を明確化 + +### 2回目の失敗 +- **原因**: エージェントタイプが不適切の可能性 +- **対策**: + - 別のエージェントタイプを試す + - 作業を細分化して複数エージェントに分割 + +### 3回目の失敗 +- **原因**: 前提条件が満たされていない可能性 +- **対策**: + - 依存する作業が完了しているか確認 + - 必要なファイルや設定が存在するか確認 + - 不足があれば準備作業を追加実行 + +### 4回目の失敗 +- **原因**: アプローチ自体が間違っている可能性 +- **対策**: + - 根本的に異なるアプローチを検討 + - Explore エージェントで再調査 + - Plan エージェントで計画を見直し + +### 5回目の失敗 +- **原因**: 自動化が困難なタスクの可能性 +- **対策**: + - 最後の試行として、最も確実と思われる方法を実行 + - それでも失敗したら step6 でユーザにエスカレーション + +### 再試行の間隔 +- 即座に再試行(待機時間なし) +- ただし、同じエラーを繰り返さないように改善策を適用してから実行 + +## ステップ分割ルール + +依頼内容に応じて適切にステップを分割する: + +### シンプルな依頼(1ステップ) +- 単一の明確な作業 +- 例: 「特定のバグを修正」「テストを1つ追加」「ファイルを整形」 + +### 中規模の依頼(2-3ステップ) +- 関連する複数の作業 +- 例: 「機能を追加してテストを書く」 + - Step1: 機能実装 + - Step2: テスト作成 + +### 大規模な依頼(4ステップ以上) +- 複雑で多段階の作業 +- 例: 「ログイン機能のテストを追加してバグを修正」 + - Step1: 既存コードの調査(Explore) + - Step2: バグの原因特定と修正(general-purpose) + - Step3: テストコード作成(general-purpose) + - Step4: テスト実行と検証(Bash) + +### 分割の基準 +- **依存関係**: 前の作業の結果が次の作業に必要な場合は別ステップに +- **作業の性質**: 調査→計画→実装→検証のように性質が異なる場合は別ステップに +- **検証ポイント**: 途中で検証したい場合は別ステップに +- **エージェントタイプ**: 異なるエージェントが適切な場合は別ステップに + +### 分割しすぎない +- 過度な分割は管理コストが増える +- 密接に関連する作業は1ステップにまとめる +- 目安: 1ステップ = 5-30分で完了する作業量 + +# info + +## エージェントタイプ一覧 + + +利用可能なエージェントタイプとその特徴: + +**general-purpose** +- フルアクセス: Read, Write, Edit, Glob, Grep, Bash, Task など全ツール +- 汎用的な実装・修正作業に最適 +- 迷ったらこれを選択 + +**Explore** +- 読み取り専用: Glob, Grep, Read, WebFetch, WebSearch +- コードベースの調査・分析専用 +- ファイル編集不可 + +**Plan** +- 読み取り専用: Glob, Grep, Read, WebFetch, WebSearch +- 実装計画の立案専用 +- ファイル編集不可 + +**Bash** +- コマンド実行専用: Bash のみ +- git操作、テスト実行、ビルドなど +- ファイル編集は専用ツールでは不可(sedなどは使える) + + +## 成功条件の例 + + +各種作業タイプにおける成功条件の具体例: + +**コード実装** +- 指定された機能が実装されている +- 構文エラーがない +- 既存のコードスタイルに従っている + +**バグ修正** +- 報告されたバグが再現しない +- 関連するテストがパスする +- 副作用が発生していない + +**テスト作成** +- テストケースが作成されている +- テストが実行できる +- テストがパスする(新規実装の場合) + +**調査作業** +- 調査対象の情報が得られた +- 原因や場所が特定された +- 次のステップに必要な情報が文書化された + +**リファクタリング** +- コードが改善されている +- 既存のテストがすべてパスする +- 機能に変更がない + +**ドキュメント作成** +- 必要な情報が記載されている +- 形式が適切(markdown等) +- 誤字脱字がない + + +## 進捗報告のタイミング + + +ユーザへの報告は最小限に抑える: + +**報告するタイミング**: +1. orchestrate 開始時: 分析結果とステップ数を報告 +2. エラー発生時: 重大なエラーや再試行の状況 +3. エスカレーション時: 最大再試行到達でユーザ判断が必要な時 +4. 完了時: 全体の結果サマリー + +**報告しないこと**: +- 各ステップの開始・完了(内部で処理) +- エージェントとのやり取り(自動処理) +- 成功した再試行(問題なく進んだので報告不要) +- タスクリストの更新(裏側の処理) + +**報告の形式**: +- 簡潔に(3-5文程度) +- 重要な情報のみ +- 次に何が起こるかを明示 + diff --git a/commands/tdd-green.md b/commands/tdd-green.md index 74a8b38..b5cf22c 100644 --- a/commands/tdd-green.md +++ b/commands/tdd-green.md @@ -28,33 +28,17 @@ Greenフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature 開発コンテキストの準備を実行する： -1. **既存の実装ドキュメントの確認** - - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 - - 特に以下のファイルを優先的に読み込み： - - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） - - `{feature_name}-requirements.md` - 要件定義 - - `{feature_name}-testcases.md` - テストケース定義 - - `{feature_name}-red-phase.md` - Redフェーズのテスト記録 - - `{feature_name}-green-phase.md` - 既存のGreenフェーズ記録 - - `{feature_name}-memo.md` - 開発履歴メモ - - その他の関連MDファイル - - これらのファイルから既存の実装状況、設計判断、注意事項を把握 - -2. **追加ルールの読み込み** - - `AGENTS.md` ファイルが存在する場合は読み込み - - `./docs/rule` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用して実装関連情報を探索** - - 既存の類似機能やユーティリティ関数を探索 - - 実装パターンやアーキテクチャガイドラインを特定 - - 依存関係やインポートパスを確認 - -4. **関連する外部ファイルを直接読み込み** - - 関連する設計文書やタスクファイルも必要に応じて読み込み - - プロジェクト全体の設計文書、アーキテクチャ文書など +1. **タスクノートの読み込み（唯一のコンテキストソース）** + - `./docs/implements/{要件名}/{{task_id}}/note.md` を読み込み + - 存在しない場合: @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` を実行して生成 + - note.mdには技術スタック、開発ルール、関連実装、設計文書、テスト関連情報、注意事項が集約済み + +2. **直前フェーズの出力を読み込み** + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md` - Redフェーズのテスト記録 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md` - 既存のGreenフェーズ記録（存在する場合） + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 開発履歴メモ（存在する場合） 読み込み完了後、step3 を実行する diff --git a/commands/tdd-red.md b/commands/tdd-red.md index ddacbd1..29bce71 100644 --- a/commands/tdd-red.md +++ b/commands/tdd-red.md @@ -30,46 +30,16 @@ Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_n 開発コンテキストの準備を実行する： -**1. 既存の実装ドキュメントの確認** -- `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 -- 特に以下のファイルを優先的に読み込み： - - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） - - `{feature_name}-requirements.md` - 要件定義 - - `{feature_name}-testcases.md` - テストケース定義 - - `{feature_name}-red-phase.md` - 既存のRedフェーズ記録 - - `{feature_name}-memo.md` - 開発履歴メモ - - その他の関連MDファイル -- これらのファイルから既存の実装状況、設計判断、注意事項を把握 - -**2. 追加ルールの読み込み** -- `AGENTS.md` ファイルが存在する場合は読み込み -- `./docs/rule` ディレクトリが存在する場合は読み込み -- `./docs/rule/tdd` ディレクトリが存在する場合は読み込み -- `./docs/rule/tdd/red` ディレクトリが存在する場合は読み込み -- 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -**3. 技術スタック定義の読み込み** -- `./docs/tech-stack.md` が存在する場合は読み込み -- 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み -- どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 - -**4. タスクノートの読み込み** -- `./docs/implements/{要件名}/{{task_id}}/note.md` が既存ドキュメント確認でまだ読み込まれていない場合 -- 存在しない場合: - - @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` コマンドを実行してノートを生成 - - 生成されたノートファイルを読み込み -- ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる - -**5. Task tool (subagent_type: Explore, thoroughness: quick) を使用してテスト実装関連情報を探索** -- 読み込んだ技術スタック定義に基づいてテストフレームワークを特定 -- **UIタスクの場合**: E2Eテストフレームワーク（Playwright等）の設定とサンプルを優先的に確認 -- 既存のテストファイルやテスト関数を探索 -- テストセットアップやモックの使用パターンを特定 -- **E2Eテスト設定確認**: playwright.config.js、cypress.config.js等の設定ファイルを確認 - -**6. 関連する外部ファイルを直接読み込み** -- 関連する設計文書やタスクファイルも必要に応じて読み込み -- プロジェクト全体の設計文書、アーキテクチャ文書など +**1. タスクノートの読み込み（唯一のコンテキストソース）** +- `./docs/implements/{要件名}/{{task_id}}/note.md` を読み込み +- 存在しない場合: @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` を実行して生成 +- note.mdには技術スタック、開発ルール、関連実装、設計文書、テスト関連情報、注意事項が集約済み + +**2. 直前フェーズの出力を読み込み** +- `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義 +- `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義 +- `./docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md` - 既存のRedフェーズ記録（存在する場合） +- `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 開発履歴メモ（存在する場合） 読み込み完了後、step3 を実行する @@ -81,7 +51,11 @@ Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_n - 対象テストケース名が指定されている場合は、そのテストケースのみ実装 - 指定がない場合は、未実装のテストケースから10個以上を選択して実装 - Write ツールを使用してテストファイルに保存 - - Bash ツールを使用してテストを実行し、失敗することを確認 + - Bash ツールを使用して**新規作成したテストファイルのみ**を実行し、失敗することを確認 + - Jest: `npm test -- <作成したテストファイル>` + - Playwright: `npx playwright test <作成したテストファイル>` + - pytest: `pytest <作成したテストファイル>` + - 全テスト実行は不要（verify-completeフェーズで実施） - 作成したテストコードについて、品質判定基準に基づいて以下を評価： - テスト実行: 実行可能で失敗することを確認済み @@ -90,7 +64,23 @@ Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_n - 実装方針: 明確 - 信頼性レベル（🔵🟡🔴の分布） -- 品質判定結果をユーザーに表示する +- 品質判定結果に応じた処理: + - **✅ 高品質**: そのまま step4 へ + - **⚠️ 要改善**: 自動修正ループを実施 + 1. 要改善の指摘内容（どの項目が不足/不適切か）を特定 + 2. Task tool (subagent_type: general-purpose) で指摘内容を渡してテストコードを修正させる + 3. 修正後のテストコードを Write tool で上書き保存 + 4. Bash tool で修正後のテストファイルを再実行し、失敗することを再確認 + 5. 再度品質判定基準に基づいて評価 + 6. 高品質になれば step4 へ + 7. まだ要改善の場合: もう1回だけ修正を試みる（最大2回まで） + 8. 2回修正しても要改善のまま → 警告をtasknoteの注意事項に追記し、step4 へ + - **⚠️ テストが成功してしまった場合**（Redフェーズなのに失敗しない）: + 1. テストの期待値やアサーションを見直すsubagent（general-purpose）を起動 + 2. 「まだ実装されていない機能をテストする」という原則に基づいて修正 + 3. 修正後に再実行し、失敗することを確認 + 4. 最大2回まで修正を試みる + 5. 2回修正しても成功してしまう → AskUserQuestion でユーザに確認 - step4 を実行する ## step4: ドキュメント更新 @@ -673,5 +663,6 @@ describe('{{feature_name}} アクセシビリティテスト', () => { 4. **実装後の期待**: テストが通るために必要な実装の概要 必ず Write ツールを使用して、{{出力ファイル名}} にテストコードを保存してください。 -その後、Bash ツールを使用してテストを実行し、失敗することを確認してください。 +その後、Bash ツールを使用して**新規作成したテストファイルのみ**を実行し、失敗することを確認してください。 +全テスト実行は不要です（verify-completeフェーズで最終確認を行います）。 diff --git a/commands/tdd-refactor.md b/commands/tdd-refactor.md index ee7d7f1..6c1dcd6 100644 --- a/commands/tdd-refactor.md +++ b/commands/tdd-refactor.md @@ -28,33 +28,17 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat 開発コンテキストの準備を実行する: -1. **既存の実装ドキュメントの確認** - - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 - - 特に以下のファイルを優先的に読み込み： - - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） - - `{feature_name}-requirements.md` - 要件定義 - - `{feature_name}-testcases.md` - テストケース定義 - - `{feature_name}-green-phase.md` - Greenフェーズの実装記録 - - `{feature_name}-refactor-phase.md` - 既存のRefactorフェーズ記録 - - `{feature_name}-memo.md` - 開発履歴メモ - - その他の関連MDファイル - - これらのファイルから既存の実装状況、設計判断、注意事項を把握 - -2. **追加ルールの読み込み** - - `AGENTS.md` ファイルが存在する場合は読み込み - - `./docs/rule` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用してリファクタリング関連情報を探索** - - 既存のコードスタイルやベストプラクティスを探索 - - プロジェクト全体のアーキテクチャパターンを特定 - - 再利用可能なユーティリティ関数やコンポーネントを確認 - -4. **関連する外部ファイルを直接読み込み** - - 関連する設計文書やタスクファイルも必要に応じて読み込み - - プロジェクト全体の設計文書、アーキテクチャ文書など +1. **タスクノートの読み込み（唯一のコンテキストソース）** + - `./docs/implements/{要件名}/{{task_id}}/note.md` を読み込み + - 存在しない場合: @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` を実行して生成 + - note.mdには技術スタック、開発ルール、関連実装、設計文書、テスト関連情報、注意事項が集約済み + +2. **直前フェーズの出力を読み込み** + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md` - Greenフェーズの実装記録 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md` - 既存のRefactorフェーズ記録（存在する場合） + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 開発履歴メモ（存在する場合） 読み込み完了後、step3 を実行する diff --git a/commands/tdd-tasknote.md b/commands/tdd-tasknote.md index 76fa8a7..a2e0396 100644 --- a/commands/tdd-tasknote.md +++ b/commands/tdd-tasknote.md @@ -22,8 +22,8 @@ noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" **追加ルールの読み込み** - `AGENTS.md` ファイルが存在する場合は読み込み - `./docs/rule` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は、サブディレクトリを含む全ファイルを読み込み + - `./docs/rule/tdd/red/`, `./docs/rule/tdd/green/`, `./docs/rule/tdd/refactor/`, `./docs/rule/tdd/testcases/`, `./docs/rule/tdd/verify-complete/` など全て対象 - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 **Task tool (subagent_type: Explore, thoroughness: quick) を使用して実装関連情報を探索** @@ -34,6 +34,11 @@ noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" - 既存の類似機能やユーティリティ関数を探索 - 実装パターンやアーキテクチャガイドラインを特定 - 依存関係やインポートパスを確認 + - **テスト関連情報の探索**（後続フェーズで再探索不要にするため）: + - テストフレームワークの設定ファイル（jest.config.js, playwright.config.js等） + - 既存のテストファイルのパターンとディレクトリ構成 + - テストユーティリティやモック設定 + - E2Eテスト設定（UIタスクの場合） **関連ファイルを直接読み込み** - `./docs/implements/{要件名}/{{task_id}}/*.md` - taskに関係する全てのファイルを読み込み @@ -96,7 +101,14 @@ noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" - データモデル - 参照元: [相対ファイルパス一覧] -### 5. 注意事項 +### 5. テスト関連情報 +- テストフレームワーク・設定ファイルのパス +- 既存テストのディレクトリ構成・命名パターン +- テストユーティリティ・モック設定 +- E2Eテスト設定（該当する場合） +- 参照元: [相対ファイルパス一覧] + +### 6. 注意事項 - 技術的制約 - セキュリティ・パフォーマンス要件 - 参照元: [相対ファイルパス] diff --git a/commands/tdd-testcases.md b/commands/tdd-testcases.md index 4c44cad..6cb5fa0 100644 --- a/commands/tdd-testcases.md +++ b/commands/tdd-testcases.md @@ -28,38 +28,15 @@ TDD開発のテストケース洗い出しを実施し、要件定義書を参 ## step2 - 開発コンテキストの準備を実行する： - **既存の実装ドキュメントの確認** - - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 - - 特に以下のファイルを優先的に読み込み： - - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） - - `{feature_name}-requirements.md` - 既存の要件定義 - - `{feature_name}-testcases.md` - 既存のテストケース - - `{feature_name}-memo.md` - 開発履歴メモ - - その他の関連MDファイル - - これらのファイルから既存の実装状況、設計判断、注意事項を把握 - - **タスクノートの読み込み** - - `./docs/implements/{要件名}/{{task_id}}/note.md` が存在しない場合: - - @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` コマンドを実行してノートを生成 - - 生成されたノートファイルを読み込み - - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる - - **追加ルールの読み込み** - - `./docs/rule` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd/testcases` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - - **Task tool (subagent_type: Explore, thoroughness: quick) を使用してテスト関連情報を探索** - - 既存のテストパターンやテストケースを探索 - - 類似機能のテスト方法やモック戦略を特定 - - テストフレームワークの使用方法を確認 - - **関連ファイルを直接読み込み** - - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - 既存のテストケースを確認 - - 関連する設計文書やタスクファイルも必要に応じて読み込み + + **1. タスクノートの読み込み（唯一のコンテキストソース）** + - `./docs/implements/{要件名}/{{task_id}}/note.md` を読み込み + - 存在しない場合: @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` を実行して生成 + - note.mdには技術スタック、開発ルール、関連実装、設計文書、テスト関連情報、注意事項が集約済み + + **2. 直前フェーズの出力を読み込み** + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - 既存のテストケース（存在する場合） - 読み込み完了後、step3 を実行する @@ -77,7 +54,17 @@ TDD開発のテストケース洗い出しを実施し、要件定義書を参 - 実装可能性: 現在の技術スタックで実現可能 - 信頼性レベル（🔵🟡🔴の分布） -- 品質判定結果をユーザーに表示する +- 品質判定結果に応じた処理: + - **✅ 高品質**: そのまま step4 へ + - **⚠️ 要改善**: 自動修正ループを実施 + 1. 要改善の指摘内容（どの項目が不足/不適切か）を特定 + 2. Task tool (subagent_type: general-purpose) で指摘内容を渡してテストケースを修正させる + 3. 修正後のテストケースを Write tool で上書き保存 + 4. 再度品質判定基準に基づいて評価 + 5. 高品質になれば step4 へ + 6. まだ要改善の場合: もう1回だけ修正を試みる（最大2回まで） + 7. 2回修正しても要改善のまま → 警告をtasknoteの注意事項に追記し、step4 へ + - **❌ 不適切**: AskUserQuestion でユーザに確認（「修正して再試行」/「このまま進む」/「中止」） - step4 を実行する ## step4 diff --git a/commands/tdd-verify-complete.md b/commands/tdd-verify-complete.md index 9f940a4..5cc60eb 100644 --- a/commands/tdd-verify-complete.md +++ b/commands/tdd-verify-complete.md @@ -27,30 +27,18 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat 検証コンテキストの準備を実行する： -1. **既存の実装ドキュメントの確認** - - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 - - 特に以下のファイルを優先的に読み込み： - - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） - - `{feature_name}-requirements.md` - 要件定義 - - `{feature_name}-testcases.md` - テストケース定義 - - `{feature_name}-refactor-phase.md` - Refactorフェーズの結果 - - `{feature_name}-memo.md` - 開発履歴メモ - - その他の関連MDファイル - - これらのファイルから既存の実装状況、設計判断、注意事項を把握 - -2. **追加ルールの読み込み** - - `AGENTS.md` ファイルが存在する場合は読み込み - - `./docs/rule` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `./docs/rule/tdd/verify-complete` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用して検証関連情報を探索** - - 完了予定のテストケースや機能を探索 - - 既存のテストカバレッジや品質基準を確認 - - 実装完了タスクのマーキングパターンを特定 - -4. **元タスクファイルを直接読み込み** +1. **タスクノートの読み込み（唯一のコンテキストソース）** + - `./docs/implements/{要件名}/{{task_id}}/note.md` を読み込み + - 存在しない場合: @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` を実行して生成 + - note.mdには技術スタック、開発ルール、関連実装、設計文書、テスト関連情報、注意事項が集約済み + +2. **直前フェーズの出力を読み込み** + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md` - Refactorフェーズの結果 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 開発履歴メモ（存在する場合） + +3. **元タスクファイルを直接読み込み** - `docs/tasks/{taskfile}.md` - タスクの完了状態を確認 - プロジェクト全体のタスク進捗を把握 @@ -59,7 +47,11 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat ## step3: 既存テストのグリーン状態確認 - **必須**: @task で全ての既存テストが成功していることを確認 -- **テスト失敗がある場合**: memoファイルに記載し、後の工程で修正対応することを記録 +- **テスト結果のスコープ分類**: + - テストケースファイル（{feature_name}-testcases.md）に記載されたテストファイルを「スコープ内」とする + - それ以外の失敗テストは「スコープ外」として分類 +- **スコープ内テスト失敗がある場合**: 要改善として記録（後のstep7で差し戻し判定に使用） +- **スコープ外テスト失敗がある場合**: memoファイルに記録し、auto-debug対応を推奨として記録 - **この工程では修正禁止**: テスト失敗を発見してもここでは修正しない - **テスト実行時間の確認**: - 総実行時間が30秒以上の場合は記録 @@ -78,7 +70,7 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat 2. `/tsumiki:test-optimization-patterns` でパターンを確認 3. 次のTDDサイクルで段階的に改善 ``` -- テスト状態を記録し、step4 に進む +- テスト状態（スコープ内/スコープ外それぞれ）を記録し、step4 に進む ## step4: 実装状況の分析 @@ -126,14 +118,16 @@ step7 を実行する - 品質判定結果をTODO内容に記録 - **完全実装済み判定**: 以下の条件を満たす場合は 完全実装済み とする - - 既存テスト状態: すべてグリーン + - 今回のタスクのテスト状態: すべてグリーン（スコープ内テストが全パス） - 要件網羅率: 100%（全要件項目実装・テスト済み） - - テスト成功率: 100% + - テスト成功率: 100%（スコープ内のみ） - 未実装重要要件: 0個 -- **完全実装済みの場合**: の形式で出力し、次のステップを提案 +- **完全実装済みの場合**: + - スコープ外テスト失敗なし → の形式で出力し、次のステップを提案 + - スコープ外テスト失敗あり → の形式で出力し、auto-debug対応を推奨 -- **実装不足がある場合**: の形式で出力し、状況を報告 +- **実装不足がある場合（スコープ内テストに失敗あり）**: の形式で出力し、状況を報告 # rules @@ -173,15 +167,23 @@ step7 を実行する ## 品質判定基準 ``` -✅ 高品質（要件充実度完全達成）: -- 既存テスト状態: すべてグリーン +✅ 高品質（完全達成）: +- 今回のタスクのテスト: すべてグリーン +- スコープ外テスト: すべてグリーン - 要件網羅率: 100%（要件定義書の全項目に対する完全な実装・テスト） - テスト成功率: 100% - 未実装重要要件: 0個 - 要件充実度: 要件定義に対する完全な充実度を達成 -⚠️ 要改善（要件充実度不足）: -- 既存テスト状態: 失敗テストあり または +✅ タスク完了（スコープ外問題あり）: +- 今回のタスクのテスト: すべてグリーン +- スコープ外テスト: 失敗あり（auto-debug対応推奨） +- 要件網羅率: 100% +- 今回のタスクの要件充実度は完全達成 +- スコープ外の問題は別途 /tsumiki:auto-debug で対応 + +⚠️ 要改善（タスク未完了）: +- 今回のタスクのテスト: 失敗あり - 要件網羅率: 100%未満（要件定義書の項目に対する実装・テスト不足） - 重要な要件項目が未実装・未テスト - 要件充実度: 要件定義に対する充実度が不十分 @@ -359,8 +361,33 @@ step7 を実行する 次のお勧めステップ: `/tsumiki:tdd-cycle` で次のTDDサイクルを開始します。 + +✅ **テストケース完全性検証: 合格（スコープ外問題あり）** + +📊 今回のタスク要件充実度: +- 対象要件項目: [数]個 +- 実装・テスト済み: [数]個 / 未実装: [数]個 +- 要件網羅率: 100% +- 要件充実度: 完全達成 + +📊 全体のテスト状況: +- 全テストケース総数: [数]個 +- 成功: [数]個 / 失敗: [数]個 +- 全体テスト成功率: [数]% + +⚠️ **スコープ外テスト失敗を検出**: +- [失敗テストファイル1]: [失敗内容の概要] +- [失敗テストファイル2]: [失敗内容の概要] + +📝 スコープ外の失敗はmemoファイルに記録済みです。 +🔧 **推奨対応**: `/tsumiki:auto-debug` を実行してスコープ外の失敗テストを修正してください。 + +🚀 今回のタスクの要件は完全に達成されています。 +自動で次のTDDサイクルに進みます。 + + -⚠️ **テストケース実装不足を検出** +⚠️ **テストケース実装不足を検出（スコープ内テストに失敗あり）** 📊 今回のタスク要件充実度: - 対象要件項目: [数]個 diff --git a/commands/timeout-fix.md b/commands/timeout-fix.md new file mode 100644 index 0000000..7d43a32 --- /dev/null +++ b/commands/timeout-fix.md @@ -0,0 +1,144 @@ +--- +description: テスト実行のタイムアウト問題を分析し、テストの高速化または適切な分離を行います。auto-debugから委譲される他、ユーザが直接呼び出すことも可能です。 +allowed-tools: Read, Glob, Grep, Task, Edit, Write +argument-hint: "[テストファイルパス]" +--- +テストのタイムアウト問題を解消して。 + +# context + +``` +test_command: {{test_command}} (テスト実行コマンド。未指定の場合は npm test) +test_file: {{test_file}} (タイムアウトしたテストファイル。未指定の場合は全テスト) +timeout_seconds: {{timeout_seconds}} (タイムアウトした秒数) +max_retry: 2 (修正の最大リトライ回数) +execution_timeout: 120 (テスト再実行時のタイムアウト秒数) +``` + +# step + +## step0: プロジェクトコンテキストの確認 + +以下のファイルが存在する場合は読み取り、テスト実行方法や性能要件を把握する: +- `CLAUDE.md` — テスト実行方法、タイムアウト設定、プロジェクト固有の指示 +- `README.md` — テスト実行環境、パフォーマンス要件 +- `AGENTS.md` — エージェント向けの開発ルール + +test_command が未指定の場合は、これらの情報から適切なテストコマンドを決定する。 + +## step1: タイムアウト原因の分析 + +1. **テストファイルと関連コードの読み取り** + - 対象テストファイルを Read tool で読み取り + - テスト対象の実装ファイルを特定 + +2. **原因分析**（Task tool, subagent_type: Explore, thoroughness: **medium**） + - 以下のタイムアウト原因パターンに沿って分析: + - **非効率な処理**: N+1クエリ、不要なループ、大量データの逐次処理 + - **外部API呼び出しのハング**: タイムアウト未設定のHTTPリクエスト、未応答のサービス + - **デッドロック/無限ループ**: Promise未解決、イベントループブロック、再帰の終了条件欠如 + - **大量テストデータ**: 不必要に大きなテストデータセット + - **テストのセットアップ過重**: beforeAll/beforeEachでの重い初期化処理 + - **リソースリーク**: 未クローズの接続、ストリーム、ファイルハンドル + - 最も可能性の高い原因を特定し、修正方針を決定 + +## step2: 修正の試行 + +原因に応じた修正を実施（general-purpose subagent）: + +1. **非効率な処理の場合** + - テスト対象コードの最適化（テスト範囲内で可能な場合） + - テスト側でのデータ量削減 + - バッチ処理への変更 + +2. **外部API呼び出しのハングの場合** + - テストでのモック導入（実際のAPI呼び出しを回避） + - テスト対象コードにタイムアウト設定が不足している場合はレポートに記載 + - テスト用のAbortController / タイムアウト設定追加 + +3. **デッドロック/無限ループの場合** + - テストコード内のPromise解決パターンを修正 + - 無限ループの終了条件修正 + - テスト用のタイムアウトガード追加 + +4. **大量テストデータの場合** + - テストデータセットの削減（本質を損なわない範囲で） + - テストファクトリの最適化 + +5. **テストのセットアップ過重の場合** + - 不要な初期化の削除 + - 共有セットアップの最適化（beforeAllへの移動等） + +6. **リソースリークの場合** + - afterAll/afterEachでの適切なクリーンアップ追加 + - 接続のクローズ処理追加 + +## step3: 再実行による確認 + +1. **修正後のテストを実行**（明示的タイムアウト設定） + ```bash + timeout {{execution_timeout}} {{test_command}} -- {{test_file}} 2>&1 + ``` + +2. **結果判定** + - **タイムアウトせず成功**: 修正完了。step5（レポート）へ + - **タイムアウトせず失敗**: テストエラーは別問題。タイムアウト改善は成功としてレポート + - **再度タイムアウト**: retry_count < max_retry → 別のアプローチで step1 に戻る + - **retry_count >= max_retry**: step4（テスト分離）へ + +## step4: テストの分離 + +修正でタイムアウトを解消できなかった場合、テストを通常実行から分離: + +1. **分離方法の決定** + - Jest: `describe.skip` + 専用設定ファイルでの実行（`jest.config.slow.js`） + - Playwright: タグ付け（`@slow`）+ フィルター実行 + - pytest: `@pytest.mark.slow` マーカー付与 + +2. **分離の実施** + - テストに適切なマーカー/タグを付与 + - 通常のテスト実行から除外される設定を確認 + - 分離されたテストの個別実行方法を記録 + +3. **通常テストの実行確認** + ```bash + {{test_command}} 2>&1 + ``` + - 分離されたテストが除外されていることを確認 + +## step5: 結果レポート + +```markdown +# timeout-fix 結果レポート + +## 結果: [改善成功 / 分離成功 / 改善失敗] + +## 対象テスト +- ファイル: {{test_file}} +- 元のタイムアウト: {{timeout_seconds}}秒 + +## タイムアウト原因 +- 原因分類: [非効率処理 / 外部APIハング / デッドロック / 大量データ / セットアップ過重 / リソースリーク] +- 詳細: [具体的な原因] + +## 修正内容 +（改善成功の場合） +- 修正ファイル: [ファイルパス] +- 修正内容: [具体的な変更内容] +- 改善後の実行時間: X秒 + +## テスト分離 +（分離の場合） +- 分離方法: [skip + 専用設定 / タグ付け / マーカー] +- 個別実行方法: [実行コマンド] +- 推奨対応: [根本的な改善のための方針] +``` + +# rule + +NEVER: テストの削除（分離はOKだが削除はNG） +NEVER: テストの期待値を変更してタイムアウトを回避 +NEVER: 実装コードの本質的なロジック変更（テスト通過のための最適化は除く） +MUST: 分離されたテストの個別実行方法を必ずレポートに記載 +MUST: テスト分離時はスキップ理由をコメントとして記載 +MUST: 各リトライで前回と異なるアプローチを試みる diff --git a/skills/kairo-implement/SKILL.md b/skills/kairo-implement/SKILL.md new file mode 100644 index 0000000..0e4a992 --- /dev/null +++ b/skills/kairo-implement/SKILL.md @@ -0,0 +1,128 @@ +--- +description: 分割されたタスクを順番に、またはユーザが指定したタスクを実装します。既存のTDDコマンドを活用して品質の高い実装を行います。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, AskUserQuestion, TaskList, TaskGet, TaskUpdate +allowed-skills: tsumiki:tdd-tasknote, tsumiki:tdd-requirements, tsumiki:tdd-testcases, tsumiki:tdd-red, tsumiki:tdd-green, tsumiki:tdd-refactor, tsumiki:tdd-verify-complete, tsumiki:direct-setup, tsumiki:direct-verify +argument-hint: "[要件名（省略可）] [TASK-ID (TASK-00001)] [--hil]" +--- +あなたは実装担当者です。残タスクを調べて、指定されたコマンドを駆使して実装をしてください + +# context + +要件名={{requirement_name}}（引数または Claude Codeタスクから取得） +TASK-ID={{task_id}}（引数または Claude Codeタスクから取得） +hilモード={{hil}}（--hil オプション指定時は true） +defaultModel={{defaultModel}}（--model オプション） +thinkModelName={{thinkModelName}}（--think-model オプション。デフォルト: opus） +tddModelName={{tddModelName}}（--tdd-model オプション。デフォルト: sonnet） +noteModelName={{noteModelName}}（--note-model オプション。デフォルト: haiku） + +コマンド選択ルール: +- thinkTaskName: thinkModelName が指定されていれば thinkModelName / defaultModel が指定されていれば defaultModel / それ以外は opus +- tddTaskName: tddModelName が指定されていれば tddModelName / defaultModel が指定されていれば defaultModel / それ以外は sonnet +- noteTaskName: noteModelName が指定されていれば noteModelName / defaultModel が指定されていれば defaultModel / それ以外は haiku + +# step + +- context の内容をまとめてユーザに宣言する +- step0 を実行する + +## step0: Claude Codeタスクシステムの確認 + +- TaskList で未完了のタスク（pending/in_progress）を確認する +- subject が "TASK-" で始まるタスクを抽出し、各タスクを TaskGet で詳細を取得する +- metadata から requirement_name / task_file / phase / task_type を取得する +- 引数の優先順位: + - 要件名が引数で指定されている場合: 引数の要件名を使用 + - 引数省略の場合: Claude Codeタスクの metadata から取得 + - TASK-ID が引数で指定されている場合: 引数の TASK-ID を使用 + - 引数省略の場合: blockedBy が空かつ status=pending の最初のタスクを選択 +- 選択した Claude Codeタスクの ID を claude_task_id として記録する + +step1 を実行する + +## step1: 追加ルールの読み込み + +- `docs/spec/{要件名}/note.md` が存在する場合は Read ツールで読み込む + +step2 を実行する + +## step2: プロジェクト文書の読み込み + +以下のファイルを Read ツールで読み込む（存在するものを優先）: +- `docs/tasks/{要件名}/overview.md` または `docs/tasks/{要件名}-overview.md` +- `docs/tasks/{要件名}/TASK-{task_id}.md` または `docs/tasks/{要件名}-tasks.md` +- Claude Codeタスクの metadata に task_file がある場合はそのパスを優先使用 +- 依存タスクのファイルも読み込み、実装の順序と関連性を理解する + +step3 を実行する + +## step3: タスクの選択と実行開始 + +- 選択されたタスクの詳細を表示する +- TaskUpdate でステータスを 'in_progress' に更新する +- "📌 Claude Codeタスク #{{claude_task_id}} を実行中に設定しました" を表示する + +step4 を実行する + +## step4: 依存関係の確認 + +- Claude CodeタスクのblockedByフィールドを確認する +- 依存タスクが完了しているか確認する（status=completed） +- 未完了の依存タスクがある場合は警告を表示してユーザーに確認する + +step5 を実行する + +## step5: 実装ディレクトリの準備 + +- 現在のワークスペースで必要に応じてディレクトリ構造を確認する + +step6 を実行する + +## step6: 実装タイプの判定 + +タスクの性質を分析して実装方式を決定する: +- Claude Codeタスクの metadata.task_type を参照する +- **TDD**: 新しいコンポーネント・サービス・フック等の実装、ビジネスロジック、API実装 +- **DIRECT**: プロジェクト初期化、ディレクトリ作成、設定ファイル作成、依存関係インストール + +step7 を実行する + +## step7: 実装プロセスの実行 + +実装タイプに応じてプロセスファイルを Read ツールで読み込み、その step に従って実行する: + +- **TDDの場合**: `skills/kairo-implement/kairo-tdd-process.md` を Read で読み込む。context に以下を設定した上でファイルの step に従って実行する: + - thinkTaskName / tddTaskName / noteTaskName（コマンド選択ルールで解決済みの値） + - 要件名 / TASK-ID / hilモード / claude_task_id + +- **DIRECTの場合**: `skills/kairo-implement/kairo-direct-process.md` を Read で読み込む。context に以下を設定した上でファイルの step に従って実行する: + - tddTaskName（コマンド選択ルールで解決済みの値） + - 要件名 / TASK-ID / claude_task_id + +step8 を実行する + +## step8: 全体の完了確認 + +- TaskList で全体の進捗を確認する +- 依存関係が解消された次のタスクを提案する +- 続けて次のタスクを実装するか確認する + +# rules + +## エラーハンドリング + +- **Claude Codeタスク関連**: + - タスクが見つからない: 引数から要件名とTASK-IDを取得して続行 + - タスクステータス更新失敗: 警告を表示するが処理は続行 + - metadata が不完全: 引数またはタスクファイルから情報を補完 +- **依存関係**: + - 依存タスク未完了: 警告を表示し、AskUserQuestion でユーザーに確認 + - blockedBy に未完了タスクがある: 依存タスクの一覧を表示 +- **実装エラー**: + - テスト失敗: 詳細なエラー情報を表示 + - ファイル競合: バックアップを作成してから上書き + +MUST: タスク開始時に TaskUpdate でステータスを 'in_progress' に更新すること +MUST: タスク完了時に TaskUpdate でステータスを 'completed' に更新すること +MUST: 引数が省略された場合は Claude Codeタスクの情報を使用すること +NEVER: 依存タスクが未完了のまま確認なしで実装を進めないこと diff --git a/skills/kairo-implement/kairo-direct-process.md b/skills/kairo-implement/kairo-direct-process.md new file mode 100644 index 0000000..8f8fc9d --- /dev/null +++ b/skills/kairo-implement/kairo-direct-process.md @@ -0,0 +1,65 @@ +直接作業プロセスを実行します。direct-setup → direct-verify の順に各フェーズを個別Taskで実行します。 + +# context + +tddTaskName={{tddTaskName}} +要件名={{requirement_name}} +TASK-ID={{task_id}} +claude_task_id={{claude_task_id}} + +# step + +- context の内容を確認する +- step-a を実行する + +## step-a: 準備作業の実行 (direct-setup) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-setup {{要件名}} {{TASK-ID}} +``` + +完了したら step-b を実行する + +## step-b: 作業結果の確認 (direct-verify) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-verify {{要件名}} {{TASK-ID}} +``` + +完了したら step-c を実行する + +## step-c: タスク完了処理 + +- `docs/tasks/{要件名}/overview.md` の完了チェックボックスを更新する: + - `[ ] **タスク完了**` → `[x] **タスク完了**` +- TaskUpdate でステータスを 'completed' に更新する +- 実装サマリーを以下の形式で表示する: + +``` +🎉 タスク {{TASK-ID}} が完了しました！ + +✅ タスクファイルのチェックボックスを更新しました +✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました + +📊 実装サマリー: +- 実装タイプ: 直接作業プロセス (個別Task実行) +- 実行Taskステップ: 2個 (全て成功) +- 作成ファイル: N個 +- 設定更新: N個 +- 環境確認: 正常 + +📝 次の推奨タスク: +- {{次のタスクID}}: {{次のタスク名}} +``` + +- 依存関係が解消された次のタスクを TaskList で確認して提案する + +# rules + +MUST: 各フェーズは必ず個別 Task として実行すること +MUST: step-b で検証エラーが発生した場合、詳細をユーザーに報告して対応を確認すること +NEVER: 作業確認が完了しないまま完了処理を実行しないこと diff --git a/skills/kairo-implement/kairo-tdd-process.md b/skills/kairo-implement/kairo-tdd-process.md new file mode 100644 index 0000000..2c74646 --- /dev/null +++ b/skills/kairo-implement/kairo-tdd-process.md @@ -0,0 +1,158 @@ +TDDプロセスを実行します。tasknote → requirements → testcases → red → green → refactor → verify-complete の順に各フェーズを個別Taskで実行します。 + +# context + +thinkTaskName={{thinkTaskName}} +tddTaskName={{tddTaskName}} +noteTaskName={{noteTaskName}} +要件名={{requirement_name}} +TASK-ID={{task_id}} +hilモード={{hil}} +claude_task_id={{claude_task_id}} + +# step + +- context の内容を確認する +- step-a を実行する + +## step-a: コンテキスト準備 + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{noteTaskName}}) /tsumiki:tdd-tasknote {{要件名}} {{TASK-ID}} +``` + +完了したら step-b を実行する + +## step-b: 要件定義 + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-requirements {{要件名}} {{TASK-ID}} +``` + +完了したら step-c を実行する + +## step-c: テストケース作成 + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-testcases {{要件名}} {{TASK-ID}} +``` + +完了後: +- hilモード=true の場合: step-c1 を実行する +- hilモード=false の場合: step-d を実行する + +## step-c1: ユーザー確認（hilモード時のみ） + +作成されたテストケース一覧を以下の形式で表示する: + +``` +📋 作成されたテストケース (N個): + +【正常系テストケース】 +... + +【異常系テストケース】 +... + +【境界値テストケース】 +... + +🔍 テストケースレビューポイント: +- 要件カバレッジ: N% +- エッジケースカバレッジ: N% +- エラーケースカバレッジ: N% + +⏸️ このテストケースで実装を進めてよろしいですか? +``` + +AskUserQuestion ツールでユーザーの選択を取得する: +- **承認**: step-d を実行する +- **修正**: ユーザーの指示に基づいてテストケースを修正後、step-c1 に戻る +- **キャンセル**: 実装を中断し、現在の状態を保存して終了 + +## step-d: テスト実装 (tdd-red) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-red {{要件名}} {{TASK-ID}} +``` + +完了したら step-e を実行する + +## step-e: 最小実装 (tdd-green) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-green {{要件名}} {{TASK-ID}} +``` + +完了したら step-f を実行する + +## step-f: リファクタリング (tdd-refactor) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-refactor {{要件名}} {{TASK-ID}} +``` + +完了したら step-g を実行する + +## step-g: 品質確認 (tdd-verify-complete) + +以下の Task を実行する: + +``` +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-verify-complete {{要件名}} {{TASK-ID}} +``` + +判定結果に応じた処理: +- **テストケース不足**: 不足内容を明示した上で step-d（tdd-red）に戻り、テストケースを追加 +- **実装不足（テストケースは十分）**: 失敗テストを明示した上で step-e（tdd-green）に戻り、実装を追加 +- **スコープ外のみ失敗**: step-h へ進む + ユーザーに `/tsumiki:auto-debug` 推奨を通知 +- **OK**: step-h へ進む + +## step-h: タスク完了処理 + +- `docs/tasks/{要件名}/overview.md` の完了チェックボックスを更新する: + - `[ ] **タスク完了**` → `[x] **タスク完了**` +- TaskUpdate でステータスを 'completed' に更新する +- 実装サマリーを以下の形式で表示する: + +``` +🎉 タスク {{TASK-ID}} が完了しました！ + +✅ タスクファイルのチェックボックスを更新しました +✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました + +📊 実装サマリー: +- 実装タイプ: TDDプロセス (個別Task実行) +- 実行Taskステップ: N個 (全て成功) +- 品質確認の繰り返し: N回 +- 作成ファイル: N個 +- テストケース: N個 (全て成功) +- テストカバレッジ: N% +- 要件充足度: N% + +📝 次の推奨タスク: +- {{次のタスクID}}: {{次のタスク名}} +``` + +- 依存関係が解消された次のタスクを TaskList で確認して提案する + +# rules + +MUST: 各フェーズは必ず個別 Task として実行すること +MUST: --hil 指定時は step-c 完了後に必ず step-c1 を実行し、ユーザーの承認を待つこと +MUST: --hil 指定時はユーザーが承認するまで step-d 以降を実行しないこと +MUST: step-g でテストケース不足と判定された場合、不足内容を明示して step-d に戻ること +MUST: step-g で実装不足と判定された場合、失敗テストを明示して step-e に戻ること +NEVER: 品質確認で問題が見つかった場合、警告なしで次に進まないこと