From aa1cd7d69bb63069c6d2bf569896a3df800182be Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:55:48 +0900 Subject: [PATCH 01/20] feat(skills): add spec-kit-workflow Skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 7つのspec-kitコマンドを統合したSkillを作成 - Specify, Clarify, Plan, Tasks, Implement, Analyze, Constitutionの全ワークフローを提供 - .specify/ディレクトリとの連携方法を明記 - TDDワークフローとの統合を説明 --- .claude/skills/spec-kit-workflow/SKILL.md | 449 ++++++++++++++++++++++ 1 file changed, 449 insertions(+) create mode 100644 .claude/skills/spec-kit-workflow/SKILL.md diff --git a/.claude/skills/spec-kit-workflow/SKILL.md b/.claude/skills/spec-kit-workflow/SKILL.md new file mode 100644 index 0000000..87d1c32 --- /dev/null +++ b/.claude/skills/spec-kit-workflow/SKILL.md @@ -0,0 +1,449 @@ +--- +name: spec-kit-workflow +description: Guide for specification-driven development workflow using Spec Kit. Use when creating specifications, planning implementations, generating tasks, or managing project constitution. Integrates with .specify/ directory for template-based development. +--- + +# Spec Kit Workflow + +このスキルは、Spec Kit を使用した仕様駆動開発のワークフローをガイドします。 + +## 概要 + +Spec Kitは、自然言語から正式仕様を作成し、実装計画、タスク生成、TDD実装までを体系的に進めるフレームワークです。 + +## ワークフロー + +``` +仕様駆動開発フロー: +- [ ] 1. Specify - 仕様作成 +- [ ] 2. Clarify - 仕様明確化 +- [ ] 3. Plan - 実装計画 +- [ ] 4. Tasks - タスク生成 +- [ ] 5. Implement - TDD実装 +- [ ] 6. Analyze - 品質分析 +- [ ] 7. Constitution - プロジェクト憲法管理 +``` + +## 1. Specify - 仕様作成 + +### 目的 +自然言語の機能説明から正式な仕様ドキュメントを作成します。 + +### 実行手順 + +1. **ブランチとファイルの初期化** + ```bash + .specify/scripts/bash/create-new-feature.sh --json "機能説明" + ``` + + 出力されるJSON: + - `BRANCH_NAME`: 新しいfeatureブランチ名 + - `SPEC_FILE`: 仕様ファイルのパス + +2. **テンプレートの読み込み** + ```bash + # 仕様テンプレートを確認 + cat .specify/templates/spec-template.md + ``` + +3. **仕様の作成** + - テンプレート構造に従って仕様を記述 + - 必須セクション: + - Overview/Context + - Functional Requirements + - Non-Functional Requirements + - User Stories + - Acceptance Criteria + +4. **完了報告** + - ブランチ名 + - 仕様ファイルパス + - 次のフェーズへの準備完了 + +## 2. Clarify - 仕様明確化 + +### 目的 +仕様の曖昧な部分を対話的に明確化し、実装前のリスクを削減します。 + +### 実行手順 + +1. **前提条件の確認** + ```bash + .specify/scripts/bash/check-prerequisites.sh --json --paths-only + ``` + +2. **曖昧性スキャン** + 以下のカテゴリで仕様を分析: + - 機能スコープと動作 + - ドメインとデータモデル + - インタラクションとUXフロー + - 非機能要件 + - 統合と外部依存 + - エッジケースと障害処理 + - 制約とトレードオフ + - 用語の一貫性 + +3. **質問の生成と対話** + - 最大5つの優先度の高い質問を生成 + - 1つずつ順番に質問 + - 回答を即座に仕様に統合 + +4. **仕様の更新** + - `## Clarifications`セクションを追加 + - `### Session YYYY-MM-DD`で日付ごとに記録 + - 各回答を適切なセクションに反映 + +### 質問形式 + +**多肢選択式**: +| Option | Description | +|--------|-------------| +| A | オプションAの説明 | +| B | オプションBの説明 | + +**短答式**: +Format: Short answer (≤5 words) + +## 3. Plan - 実装計画 + +### 目的 +仕様から具体的な実装計画を生成します。 + +### 実行手順 + +1. **セットアップ** + ```bash + .specify/scripts/bash/setup-plan.sh --json + ``` + +2. **仕様の分析** + - 機能要件とユーザーストーリー + - 機能的・非機能的要件 + - 成功基準と受入基準 + - 技術的制約と依存関係 + +3. **憲法の確認** + ```bash + cat .specify/memory/constitution.md + ``` + +4. **計画テンプレートの実行** + ```bash + cat .specify/templates/plan-template.md + ``` + + 生成される成果物: + - **Phase 0**: `research.md` - 技術調査 + - **Phase 1**: `data-model.md`, `contracts/`, `quickstart.md` + - **Phase 2**: `tasks.md` - タスクリスト + +5. **進捗追跡** + - 各フェーズの完了を確認 + - すべての成果物が生成されたことを検証 + +## 4. Tasks - タスク生成 + +### 目的 +設計成果物からTDD準拠のタスクリストを生成します。 + +### 実行手順 + +1. **前提条件の確認** + ```bash + .specify/scripts/bash/check-prerequisites.sh --json + ``` + +2. **設計ドキュメントの読み込み** + - `plan.md`: 技術スタックとライブラリ + - `data-model.md`: エンティティ（存在する場合） + - `contracts/`: APIエンドポイント（存在する場合） + - `research.md`: 技術的決定（存在する場合） + - `quickstart.md`: テストシナリオ（存在する場合） + +3. **タスクの生成** + テンプレート: `.specify/templates/tasks-template.md` + + タスクカテゴリ: + - **Setup**: プロジェクト初期化、依存関係、リント + - **Test [P]**: コントラクトごと、統合シナリオごと + - **Core**: エンティティ、サービス、CLIコマンド、エンドポイント + - **Integration**: DB接続、ミドルウェア、ログ + - **Polish [P]**: ユニットテスト、パフォーマンス、ドキュメント + +4. **タスク生成ルール** + - 各コントラクトファイル → コントラクトテストタスク `[P]` + - 各エンティティ → モデル作成タスク `[P]` + - 各エンドポイント → 実装タスク（共有ファイルの場合は非並列） + - 各ユーザーストーリー → 統合テスト `[P]` + - 異なるファイル = 並列可能 `[P]` + - 同じファイル = 順次（`[P]`なし） + +5. **依存関係の順序** + 1. Setup → すべての前に + 2. Tests → 実装の前（TDD） + 3. Models → サービスの前 + 4. Services → エンドポイントの前 + 5. Core → 統合の前 + 6. すべて → Polishの前 + +## 5. Implement - TDD実装 + +### 目的 +タスクリストに従ってTDDサイクルで実装を進めます。 + +### 実行手順 + +1. **前提条件の確認** + ```bash + .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ``` + +2. **実装コンテキストの読み込み** + - **必須**: `tasks.md` - 完全なタスクリストと実行計画 + - **必須**: `plan.md` - 技術スタック、アーキテクチャ、ファイル構造 + - **存在する場合**: `data-model.md`, `contracts/`, `research.md`, `quickstart.md` + +3. **タスク構造の解析** + - タスクフェーズ: Setup, Tests, Core, Integration, Polish + - タスク依存関係: 順次 vs 並列実行ルール + - タスク詳細: ID、説明、ファイルパス、並列マーカー `[P]` + +4. **実装の実行** + - **フェーズごとの実行**: 各フェーズを完了してから次へ + - **依存関係の尊重**: 順次タスクは順番に、並列タスク `[P]`は同時実行可能 + - **TDDアプローチ**: テストタスクを対応する実装タスクの前に実行 + - **ファイルベースの調整**: 同じファイルに影響するタスクは順次実行 + - **検証チェックポイント**: 各フェーズ完了を確認してから進行 + +5. **実装実行ルール** + - **Setup first**: プロジェクト構造、依存関係、設定の初期化 + - **Tests before code**: コントラクト、エンティティ、統合シナリオのテストを書く + - **Core development**: モデル、サービス、CLIコマンド、エンドポイントの実装 + - **Integration work**: DB接続、ミドルウェア、ログ、外部サービス + - **Polish and validation**: ユニットテスト、パフォーマンス最適化、ドキュメント + +6. **進捗追跡** + - 各完了タスク後に進捗を報告 + - 非並列タスクが失敗した場合は実行を停止 + - 並列タスク `[P]`の場合、成功したタスクは継続、失敗したものを報告 + - **重要**: 完了したタスクは`tasks.md`で`[X]`としてマーク + +## 6. Analyze - 品質分析 + +### 目的 +実装前に成果物間の一貫性と品質を分析します。 + +### 実行手順 + +1. **前提条件の確認** + ```bash + .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ``` + +2. **成果物の読み込み** + - `spec.md`: 仕様 + - `plan.md`: 実装計画 + - `tasks.md`: タスクリスト + - `.specify/memory/constitution.md`: プロジェクト憲法 + +3. **検出パス** + + **A. 重複検出**: + - ほぼ重複する要件を特定 + + **B. 曖昧性検出**: + - 測定可能な基準がない曖昧な形容詞 + - 未解決のプレースホルダー（TODO、???など） + + **C. 不十分な仕様**: + - 測定可能な結果がない要件 + - 受入基準が欠けているユーザーストーリー + + **D. 憲法との整合性**: + - MUST原則に違反する要件や計画要素 + - 憲法で義務付けられたセクションや品質ゲートの欠落 + + **E. カバレッジギャップ**: + - タスクが関連付けられていない要件 + - 要件/ストーリーにマッピングされていないタスク + + **F. 不整合**: + - 用語の不一致 + - データエンティティの不一致 + - タスク順序の矛盾 + +4. **重要度の割り当て** + - **CRITICAL**: 憲法のMUST違反、コア仕様の欠落 + - **HIGH**: 重複または矛盾する要件、曖昧なセキュリティ/パフォーマンス属性 + - **MEDIUM**: 用語の不一致、非機能タスクカバレッジの欠落 + - **LOW**: スタイル/文言の改善、軽微な冗長性 + +5. **レポート生成** + + | ID | Category | Severity | Location(s) | Summary | Recommendation | + |----|----------|----------|-------------|---------|----------------| + + 追加セクション: + - カバレッジサマリーテーブル + - 憲法整合性の問題 + - マッピングされていないタスク + - メトリクス + +6. **次のアクション** + - CRITICALな問題がある場合: 実装前に解決を推奨 + - LOW/MEDIUMのみの場合: 進行可能、改善提案を提供 + +**重要**: このコマンドは読み取り専用です。ファイルを変更しません。 + +## 7. Constitution - プロジェクト憲法管理 + +### 目的 +プロジェクトの開発原則と品質基準を定義・管理します。 + +### 実行手順 + +1. **憲法テンプレートの読み込み** + ```bash + cat .specify/memory/constitution.md + ``` + +2. **プレースホルダーの特定** + - `[PROJECT_NAME]` + - `[PRINCIPLE_1_NAME]` + - など、すべての`[ALL_CAPS_IDENTIFIER]`形式のトークン + +3. **値の収集** + - ユーザー入力から値を取得 + - 既存のリポジトリコンテキストから推論 + - ガバナンス日付の設定 + +4. **バージョニング** + - **MAJOR**: 後方互換性のない原則の削除または再定義 + - **MINOR**: 新しい原則/セクションの追加 + - **PATCH**: 明確化、文言修正、タイポ修正 + +5. **一貫性の伝播** + 以下のファイルとの整合性を確認: + - `.specify/templates/plan-template.md` + - `.specify/templates/spec-template.md` + - `.specify/templates/tasks-template.md` + - コマンドファイル + - ランタイムガイダンスドキュメント + +6. **同期影響レポート** + - バージョン変更 + - 変更された原則のリスト + - 追加/削除されたセクション + - 更新が必要なテンプレート + +7. **検証** + - 説明されていないブラケットトークンがないこと + - バージョン行がレポートと一致 + - 日付がISO形式（YYYY-MM-DD） + - 原則が宣言的、テスト可能、曖昧でない + +## .specify/ディレクトリとの連携 + +### ディレクトリ構造 + +``` +.specify/ +├── scripts/ +│ └── bash/ +│ ├── create-new-feature.sh +│ ├── setup-plan.sh +│ └── check-prerequisites.sh +├── templates/ +│ ├── spec-template.md +│ ├── plan-template.md +│ └── tasks-template.md +└── memory/ + └── constitution.md +``` + +### スクリプトの使用 + +すべてのスクリプトは`--json`オプションでJSON出力をサポートします: + +```bash +# 機能ブランチの作成 +.specify/scripts/bash/create-new-feature.sh --json "機能説明" + +# 計画のセットアップ +.specify/scripts/bash/setup-plan.sh --json + +# 前提条件の確認 +.specify/scripts/bash/check-prerequisites.sh --json +.specify/scripts/bash/check-prerequisites.sh --json --paths-only +.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks +``` + +## TDD統合 + +Spec Kit WorkflowはTDDと統合されています。 + +### TDDとの連携 + +1. **Tasks生成時**: テストタスクを実装タスクの前に配置 +2. **Implement時**: Red-Green-Refactorサイクルに従う +3. **カバレッジ**: 非機能要件にテストカバレッジを含める + +### 関連Skill + +- **tdd-basics**: [tdd-basics](../tdd-basics/SKILL.md) - TDDの基本概念 +- **testing-typescript**: [testing-typescript](../testing-typescript/SKILL.md) - TypeScriptテスト +- **testing-rust**: [testing-rust](../testing-rust/SKILL.md) - Rustテスト + +## ベストプラクティス + +### 1. 段階的な進行 + +各フェーズを完了してから次に進みます。スキップしないでください。 + +### 2. Clarifyの重要性 + +実装前に仕様を明確化することで、後戻りのリスクを大幅に削減できます。 + +### 3. 憲法の遵守 + +プロジェクト憲法は非交渉です。すべての決定は憲法に従う必要があります。 + +### 4. 並列実行の活用 + +タスクに`[P]`マーカーがある場合、並列実行で効率を向上できます。 + +### 5. 進捗の追跡 + +`tasks.md`で完了したタスクを`[X]`としてマークし、進捗を可視化します。 + +## トラブルシューティング + +### スクリプトが見つからない + +```bash +# .specify/ディレクトリが存在するか確認 +ls -la .specify/ + +# スクリプトに実行権限があるか確認 +chmod +x .specify/scripts/bash/*.sh +``` + +### JSON解析エラー + +```bash +# --jsonオプションを使用しているか確認 +.specify/scripts/bash/check-prerequisites.sh --json +``` + +### テンプレートが見つからない + +```bash +# テンプレートディレクトリを確認 +ls -la .specify/templates/ +``` + +## 参考リソース + +- [Spec Kit Documentation](.specify/) +- [Project Constitution](.specify/memory/constitution.md) +- [TDD Basics](../tdd-basics/SKILL.md) From 0e67d2804fe2f1376cb0bde3527e35d84df55ff4 Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:55:52 +0900 Subject: [PATCH 02/20] feat(skills): add code-review-workflow Skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 体系的なコードレビュープロセスを提供 - レビュー観点チェックリスト（品質、セキュリティ、パフォーマンス、テスト、ドキュメント） - レビューコメントのベストプラクティス - 自動化ツールの活用方法 - 言語別のレビューポイント --- .claude/skills/code-review-workflow/SKILL.md | 235 +++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 .claude/skills/code-review-workflow/SKILL.md diff --git a/.claude/skills/code-review-workflow/SKILL.md b/.claude/skills/code-review-workflow/SKILL.md new file mode 100644 index 0000000..c81d5a6 --- /dev/null +++ b/.claude/skills/code-review-workflow/SKILL.md @@ -0,0 +1,235 @@ +--- +name: code-review-workflow +description: Guide for systematic code review process. Use when reviewing code, checking quality, or providing feedback on pull requests. Covers security, performance, testing, and best practices. +--- + +# Code Review Workflow + +このスキルは、体系的なコードレビュープロセスをガイドします。 + +## レビュー観点チェックリスト + +### 1. コード品質 + +**可読性と保守性**: +- [ ] 変数名・関数名が意図を明確に表現しているか +- [ ] コードの構造が論理的で理解しやすいか +- [ ] 複雑な処理に適切なコメントがあるか +- [ ] マジックナンバーが定数化されているか + +**設計原則**: +- [ ] DRY原則（Don't Repeat Yourself）が守られているか +- [ ] SOLID原則が適用されているか +- [ ] 単一責任の原則に従っているか +- [ ] 適切な抽象化レベルか + +**命名規則**: +- [ ] プロジェクトの命名規則に従っているか +- [ ] 一貫した命名スタイルか +- [ ] 略語の使用が適切か + +### 2. セキュリティ + +**入力検証**: +- [ ] すべてのユーザー入力が検証されているか +- [ ] サニタイゼーション処理が適切か +- [ ] 型チェックが行われているか + +**認証・認可**: +- [ ] 認証が適切に実装されているか +- [ ] 認可チェックが漏れていないか +- [ ] セッション管理が安全か + +**一般的な脆弱性対策**: +- [ ] SQLインジェクション対策 +- [ ] XSS（クロスサイトスクリプティング）対策 +- [ ] CSRF（クロスサイトリクエストフォージェリ）対策 +- [ ] パストラバーサル対策 +- [ ] 機密情報のハードコーディングがないか + +### 3. パフォーマンス + +**計算量**: +- [ ] アルゴリズムの計算量が適切か（O(n), O(n log n)等） +- [ ] 不要なループのネストがないか +- [ ] 早期リターンが活用されているか + +**メモリ使用**: +- [ ] メモリリークの可能性がないか +- [ ] 大きなデータ構造の扱いが適切か +- [ ] 不要なオブジェクト生成がないか + +**データベース**: +- [ ] N+1問題が発生していないか +- [ ] インデックスが適切に使用されているか +- [ ] クエリが最適化されているか + +**キャッシュ**: +- [ ] キャッシュが適切に活用されているか +- [ ] キャッシュの無効化戦略が適切か + +### 4. テスト + +**テストカバレッジ**: +- [ ] 新規コードに対するテストがあるか +- [ ] カバレッジが目標値を満たしているか（80%以上推奨） +- [ ] 重要なビジネスロジックがテストされているか + +**テストの質**: +- [ ] エッジケースがテストされているか +- [ ] 異常系のテストがあるか +- [ ] テストが独立しているか（他のテストに依存していないか） +- [ ] テストが決定的か（実行するたびに同じ結果になるか） + +**テストの種類**: +- [ ] 単体テスト（Unit Tests） +- [ ] 統合テスト（Integration Tests） +- [ ] E2Eテスト（End-to-End Tests） + +### 5. エラーハンドリング + +**エラー処理**: +- [ ] すべてのエラーケースが処理されているか +- [ ] エラーメッセージが適切か +- [ ] エラーログが記録されているか +- [ ] ユーザーフレンドリーなエラーメッセージか + +**例外処理**: +- [ ] 例外が適切にキャッチされているか +- [ ] リソースのクリーンアップが行われているか +- [ ] 例外の再スローが適切か + +### 6. ドキュメント + +**コードコメント**: +- [ ] 複雑なロジックにコメントがあるか +- [ ] WHYを説明するコメントか（WHATではなく） +- [ ] TODOコメントが適切に管理されているか + +**API ドキュメント**: +- [ ] 公開APIにドキュメントがあるか +- [ ] パラメータと戻り値が説明されているか +- [ ] 使用例があるか + +**プロジェクトドキュメント**: +- [ ] READMEが更新されているか +- [ ] CHANGELOGが更新されているか +- [ ] 破壊的変更が文書化されているか + +## レビューコメントのベストプラクティス + +### 建設的なフィードバック + +**良い例**: +``` +この部分は O(n²) の計算量になっています。 +ハッシュマップを使うことで O(n) に改善できます。 + +例: +const map = new Map(); +for (const item of items) { + map.set(item.id, item); +} +``` + +**悪い例**: +``` +このコードは遅い。 +``` + +### 質問形式の活用 + +**良い例**: +``` +この処理は非同期で実行する必要がありますか？ +同期処理でも問題ない場合、シンプルにできそうです。 +``` + +### 肯定的なフィードバック + +良いコードには積極的にポジティブなコメントを: +``` +このエラーハンドリングは非常に丁寧で、ユーザーにとって +分かりやすいメッセージになっていますね！ +``` + +## 自動化ツールの活用 + +### 静的解析ツール + +**TypeScript/JavaScript**: +- ESLint: コードスタイルと潜在的なバグの検出 +- Prettier: コードフォーマット +- TypeScript: 型チェック + +**Rust**: +- clippy: Rustのリンター +- rustfmt: コードフォーマッター +- cargo check: 型チェック + +### セキュリティスキャン + +- **npm audit**: npm パッケージの脆弱性チェック +- **cargo audit**: Rust クレートの脆弱性チェック +- **Snyk**: 依存関係の脆弱性スキャン + +### テストカバレッジ + +- **Jest**: JavaScript/TypeScriptのカバレッジ +- **cargo-llvm-cov**: Rustのカバレッジ + +## 言語別のレビューポイント + +### TypeScript/JavaScript + +**型安全性**: +- [ ] `any`型の使用が最小限か +- [ ] 型アサーションが適切か +- [ ] null/undefinedチェックが適切か + +**非同期処理**: +- [ ] Promise/async-awaitが適切に使用されているか +- [ ] エラーハンドリングが適切か +- [ ] 並列処理が適切に実装されているか + +### Rust + +**所有権とライフタイム**: +- [ ] 所有権の移動が適切か +- [ ] ライフタイムが適切に指定されているか +- [ ] 借用チェッカーのエラーを回避するための不適切な回避策がないか + +**エラーハンドリング**: +- [ ] `Result`型が適切に使用されているか +- [ ] `unwrap()`の使用が適切か（本番コードでは避けるべき） +- [ ] `?`演算子が活用されているか + +## 関連Skill + +- **tdd-basics**: [tdd-basics](../tdd-basics/SKILL.md) - テストファーストの開発 +- **testing-typescript**: [testing-typescript](../testing-typescript/SKILL.md) - TypeScriptテスト +- **testing-rust**: [testing-rust](../testing-rust/SKILL.md) - Rustテスト +- **ci-cd-setup**: [ci-cd-setup](../ci-cd-setup/SKILL.md) - 自動化されたレビュー + +## トラブルシューティング + +### レビューに時間がかかりすぎる + +**解決策**: +1. チェックリストを使用して効率化 +2. 自動化ツールで機械的なチェックを削減 +3. 重要度の高い部分に集中 + +### レビューコメントが多すぎる + +**解決策**: +1. 最も重要な問題に絞る +2. スタイルの問題は自動フォーマッターに任せる +3. 教育的なコメントは別途ドキュメント化 + +### 意見の相違 + +**解決策**: +1. プロジェクトの憲法やガイドラインを参照 +2. データやベンチマークで判断 +3. チーム全体で議論 From 650b512608498f120fc8d4cc8a485aff1ad80208 Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:55:57 +0900 Subject: [PATCH 03/20] feat(skills): add debugging-workflow Skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 効率的なデバッグプロセスを提供 - 7ステップのデバッグフロー（再現、情報収集、仮説立案、検証、修正、テスト、ドキュメント化） - デバッグテクニック（ラバーダック、バイナリサーチ、プリントデバッグ） - 言語別のデバッグツール紹介 --- .claude/skills/debugging-workflow/SKILL.md | 341 +++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 .claude/skills/debugging-workflow/SKILL.md diff --git a/.claude/skills/debugging-workflow/SKILL.md b/.claude/skills/debugging-workflow/SKILL.md new file mode 100644 index 0000000..daa4718 --- /dev/null +++ b/.claude/skills/debugging-workflow/SKILL.md @@ -0,0 +1,341 @@ +--- +name: debugging-workflow +description: Guide for efficient debugging process. Use when investigating bugs, analyzing errors, or troubleshooting issues. Covers systematic problem-solving approaches and debugging techniques. +--- + +# Debugging Workflow + +このスキルは、効率的なデバッグプロセスをガイドします。 + +## デバッグの基本ステップ + +``` +デバッグフロー: +- [ ] 1. 問題の再現 +- [ ] 2. 情報の収集 +- [ ] 3. 仮説の立案 +- [ ] 4. 仮説の検証 +- [ ] 5. 修正の実装 +- [ ] 6. テストの作成 +- [ ] 7. ドキュメント化 +``` + +## 1. 問題の再現 + +### 再現手順の確立 + +**最小限の再現手順を特定**: +- [ ] 問題を引き起こす最小限の操作を特定 +- [ ] 不要なステップを削除 +- [ ] 再現率を確認（100%再現が理想） + +**環境条件の記録**: +- [ ] OS・ブラウザ・デバイス +- [ ] ソフトウェアバージョン +- [ ] 環境変数 +- [ ] ネットワーク状態 + +**入力データの保存**: +- [ ] テストデータを保存 +- [ ] エッジケースを特定 +- [ ] 境界値を確認 + +**期待される動作の明確化**: +- [ ] 正しい動作を定義 +- [ ] 現在の動作との差分を明確化 + +## 2. 情報の収集 + +### ログ分析 + +**エラーメッセージの収集**: +```bash +# アプリケーションログ +tail -f /var/log/app.log + +# システムログ +journalctl -u service-name -f + +# ブラウザコンソール +F12 → Console タブ +``` + +**スタックトレースの分析**: +- [ ] エラーが発生した場所を特定 +- [ ] 呼び出し元を追跡 +- [ ] 関連するコードを確認 + +**ログレベルの調整**: +```typescript +// ログレベルを DEBUG に変更 +logger.setLevel('DEBUG'); + +// 詳細なログを出力 +logger.debug('Variable value:', variable); +``` + +### デバッグツールの使用 + +**ブレークポイント**: +- [ ] 問題が発生する前にブレークポイントを設定 +- [ ] 変数の値を確認 +- [ ] ステップ実行で処理を追跡 + +**ウォッチ式**: +- [ ] 重要な変数をウォッチ +- [ ] 条件付きブレークポイントを使用 + +## 3. 仮説の立案 + +### 原因の推定 + +**一般的な原因**: +- [ ] ロジックエラー +- [ ] 型の不一致 +- [ ] null/undefined参照 +- [ ] 非同期処理のタイミング +- [ ] リソースリーク +- [ ] 競合状態（Race Condition） + +**仮説の優先順位付け**: +1. **最も可能性が高い原因**から検証 +2. **影響範囲が大きい原因**を優先 +3. **検証が容易な仮説**から試す + +## 4. 仮説の検証 + +### 二分探索法 + +問題が発生する範囲を半分ずつ絞り込む: + +``` +1. コードの中間地点にログを追加 +2. 問題が前半か後半かを特定 +3. 該当する範囲を再度二分 +4. 問題箇所を特定するまで繰り返す +``` + +### 分離テスト + +**最小限のテストケース作成**: +```typescript +// 問題を再現する最小限のコード +test('reproduce bug', () => { + const result = problematicFunction(input); + expect(result).toBe(expected); +}); +``` + +### デバッガーの活用 + +**TypeScript/JavaScript**: +```typescript +// Node.js デバッガー +node --inspect-brk app.js + +// Chrome DevTools +debugger; // この行で停止 +``` + +**Rust**: +```bash +# lldb を使用 +rust-lldb target/debug/app + +# gdb を使用 +rust-gdb target/debug/app +``` + +## 5. 修正の実装 + +### 修正の原則 + +**最小限の変更**: +- [ ] 問題を解決する最小限の変更 +- [ ] 副作用を最小化 +- [ ] 既存の動作を壊さない + +**防御的プログラミング**: +```typescript +// 入力検証を追加 +function processData(data: Data | null) { + if (!data) { + logger.warn('Data is null'); + return defaultValue; + } + + // 処理 +} +``` + +**エラーハンドリングの改善**: +```typescript +try { + await riskyOperation(); +} catch (error) { + logger.error('Operation failed:', error); + // 適切なフォールバック処理 + return fallbackValue; +} +``` + +## 6. テストの作成 + +### 回帰テストの作成 + +**バグを再現するテスト**: +```typescript +test('should handle null input', () => { + // このテストは修正前は失敗する + const result = processData(null); + expect(result).toBe(defaultValue); +}); +``` + +**エッジケースのテスト**: +- [ ] 境界値のテスト +- [ ] 異常系のテスト +- [ ] 並行処理のテスト + +## 7. ドキュメント化 + +### バグレポートの更新 + +**修正内容の記録**: +```markdown +## 原因 +非同期処理の完了を待たずに次の処理に進んでいた + +## 修正内容 +await を追加して非同期処理の完了を待つように変更 + +## テスト +- 単体テストを追加 +- 手動テストで動作確認 +``` + +### コードコメントの追加 + +```typescript +// Bug fix: #123 - null チェックを追加 +// 以前は null の場合にエラーが発生していた +if (data === null) { + return defaultValue; +} +``` + +## デバッグテクニック + +### ラバーダック デバッグ + +問題を誰か（またはラバーダック）に説明することで解決策が見つかることがある: + +1. 問題を声に出して説明 +2. コードの動作を1行ずつ説明 +3. 説明中に矛盾や誤りに気づく + +### バイナリサーチ + +Gitの履歴から問題が発生したコミットを特定: + +```bash +# バイナリサーチ開始 +git bisect start + +# 現在のコミットは問題あり +git bisect bad + +# 過去の正常なコミット +git bisect good + +# 自動的に中間のコミットに移動 +# テストして good/bad を報告 +git bisect good # または git bisect bad + +# 問題のコミットを特定 +git bisect reset +``` + +### プリントデバッグ + +シンプルだが効果的: + +```typescript +console.log('DEBUG: variable =', variable); +console.log('DEBUG: entering function'); +console.log('DEBUG: condition =', condition); +``` + +**注意**: 本番環境にデバッグログを残さない + +## 言語別のデバッグツール + +### TypeScript/JavaScript + +**ブラウザ DevTools**: +- Chrome DevTools +- Firefox Developer Tools +- Safari Web Inspector + +**Node.js デバッガー**: +```bash +# 組み込みデバッガー +node inspect app.js + +# Chrome DevTools +node --inspect app.js +``` + +**VS Code デバッガー**: +`.vscode/launch.json` を設定 + +### Rust + +**デバッガー**: +- lldb (macOS/Linux) +- gdb (Linux) +- Visual Studio Debugger (Windows) + +**デバッグビルド**: +```bash +# デバッグ情報付きでビルド +cargo build + +# リリースビルドでもデバッグ情報を含める +cargo build --release --config profile.release.debug=true +``` + +## トラブルシューティング + +### 再現できない問題 + +**対処法**: +1. より多くの情報を収集（ログ、環境情報） +2. 統計的アプローチ（複数回試行） +3. 本番環境のログを詳細化 + +### 複雑すぎる問題 + +**対処法**: +1. 問題を小さな部分に分割 +2. 各部分を個別にテスト +3. チームメンバーに相談 + +### パフォーマンス問題 + +**対処法**: +1. プロファイラーを使用 +2. ボトルネックを特定 +3. ベンチマークで効果を測定 + +## 関連Skill + +- **testing-typescript**: [testing-typescript](../testing-typescript/SKILL.md) - デバッグテストの作成 +- **testing-rust**: [testing-rust](../testing-rust/SKILL.md) - Rustデバッグテスト +- **code-review-workflow**: [code-review-workflow](../code-review-workflow/SKILL.md) - バグの早期発見 + +## 参考リソース + +- [Chrome DevTools](https://developer.chrome.com/docs/devtools/) +- [Node.js Debugging Guide](https://nodejs.org/en/docs/guides/debugging-getting-started/) +- [Rust Debugging](https://doc.rust-lang.org/book/ch09-00-error-handling.html) From 7d8c7183aee557a07c8b2e99bc10180067232ec6 Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:56:01 +0900 Subject: [PATCH 04/20] feat(skills): add refactoring-workflow Skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 安全で効果的なリファクタリングプロセスを提供 - テストファーストリファクタリングの原則 - コードスメルの特定（長いメソッド、重複コード、大きなクラス等） - リファクタリングパターン（メソッド抽出、変数抽出等） - 小さなステップでの安全な変更手順 --- .claude/skills/refactoring-workflow/SKILL.md | 462 +++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 .claude/skills/refactoring-workflow/SKILL.md diff --git a/.claude/skills/refactoring-workflow/SKILL.md b/.claude/skills/refactoring-workflow/SKILL.md new file mode 100644 index 0000000..5d7dd3b --- /dev/null +++ b/.claude/skills/refactoring-workflow/SKILL.md @@ -0,0 +1,462 @@ +--- +name: refactoring-workflow +description: Guide for safe and effective refactoring. Use when improving code structure, reducing technical debt, or applying design patterns. Covers test-first refactoring and incremental improvements. +--- + +# Refactoring Workflow + +このスキルは、安全で効果的なリファクタリングプロセスをガイドします。 + +## リファクタリングの原則 + +### テストファーストリファクタリング + +``` +リファクタリングフロー: +- [ ] 1. テストを書く（または既存テストを確認） +- [ ] 2. テストが通ることを確認（Green） +- [ ] 3. リファクタリングを実行 +- [ ] 4. テストが通ることを確認（Green維持） +- [ ] 5. コミット +``` + +**重要**: テストなしでリファクタリングしない + +### 小さなステップで進める + +- [ ] 1つの変更を小さく保つ +- [ ] 各ステップでテストを実行 +- [ ] 頻繁にコミット + +## コードスメルの特定 + +### 1. 長いメソッド + +**問題**: +- 理解が困難 +- テストが難しい +- 再利用性が低い + +**リファクタリング**: メソッド抽出 + +```typescript +// Before +function processOrder(order: Order) { + // 検証（20行） + // 計算（30行） + // 保存（15行） + // 通知（10行） +} + +// After +function processOrder(order: Order) { + validateOrder(order); + const total = calculateTotal(order); + saveOrder(order, total); + notifyCustomer(order); +} +``` + +### 2. 重複コード + +**問題**: +- メンテナンスコストが高い +- バグが複数箇所に存在する可能性 + +**リファクタリング**: 共通処理の抽出 + +```typescript +// Before +function processUserOrder(user: User, order: Order) { + if (!user.isActive) throw new Error('Inactive user'); + if (!user.hasPermission('order')) throw new Error('No permission'); + // 処理 +} + +function processAdminOrder(admin: Admin, order: Order) { + if (!admin.isActive) throw new Error('Inactive user'); + if (!admin.hasPermission('order')) throw new Error('No permission'); + // 処理 +} + +// After +function validateUser(user: User | Admin) { + if (!user.isActive) throw new Error('Inactive user'); + if (!user.hasPermission('order')) throw new Error('No permission'); +} + +function processUserOrder(user: User, order: Order) { + validateUser(user); + // 処理 +} +``` + +### 3. 大きなクラス + +**問題**: +- 単一責任の原則違反 +- 理解が困難 +- 変更の影響範囲が広い + +**リファクタリング**: クラスの分割 + +```typescript +// Before +class User { + // ユーザー情報 + // 認証ロジック + // 権限管理 + // 通知設定 + // メール送信 +} + +// After +class User { + // ユーザー情報のみ +} + +class UserAuthenticator { + // 認証ロジック +} + +class UserPermissions { + // 権限管理 +} + +class UserNotifier { + // 通知設定とメール送信 +} +``` + +### 4. 長いパラメータリスト + +**問題**: +- 関数呼び出しが複雑 +- 引数の順序を間違えやすい + +**リファクタリング**: パラメータオブジェクトの導入 + +```typescript +// Before +function createUser( + name: string, + email: string, + age: number, + address: string, + phone: string, + role: string +) { + // 処理 +} + +// After +interface UserParams { + name: string; + email: string; + age: number; + address: string; + phone: string; + role: string; +} + +function createUser(params: UserParams) { + // 処理 +} +``` + +### 5. 複雑な条件式 + +**問題**: +- 可読性が低い +- バグが混入しやすい + +**リファクタリング**: 条件の分解と命名 + +```typescript +// Before +if (user.age >= 18 && user.hasLicense && !user.isSuspended && user.balance > 0) { + // 処理 +} + +// After +const isAdult = user.age >= 18; +const hasValidLicense = user.hasLicense && !user.isSuspended; +const hasBalance = user.balance > 0; + +if (isAdult && hasValidLicense && hasBalance) { + // 処理 +} + +// さらに良い +function canDrive(user: User): boolean { + return user.age >= 18 + && user.hasLicense + && !user.isSuspended + && user.balance > 0; +} + +if (canDrive(user)) { + // 処理 +} +``` + +## リファクタリングパターン + +### 1. メソッド抽出（Extract Method） + +長いメソッドを小さなメソッドに分割: + +```typescript +// Before +function generateReport(data: Data[]) { + let html = ''; + html += '

Report

'; + html += ''; + for (const item of data) { + html += ''; + html += ``; + html += ``; + html += ''; + } + html += '
${item.name}${item.value}
'; + html += ''; + return html; +} + +// After +function generateReport(data: Data[]): string { + return wrapInHtml( + generateHeader() + generateTable(data) + ); +} + +function generateHeader(): string { + return '

Report

'; +} + +function generateTable(data: Data[]): string { + const rows = data.map(generateRow).join(''); + return `${rows}
`; +} + +function generateRow(item: Data): string { + return `${item.name}${item.value}`; +} + +function wrapInHtml(content: string): string { + return `${content}`; +} +``` + +### 2. 変数の抽出（Extract Variable） + +複雑な式を変数に抽出: + +```typescript +// Before +if (platform.toUpperCase().indexOf('MAC') > -1 && + browser.toUpperCase().indexOf('IE') > -1 && + wasInitialized() && resize > 0) { + // 処理 +} + +// After +const isMacOS = platform.toUpperCase().indexOf('MAC') > -1; +const isIE = browser.toUpperCase().indexOf('IE') > -1; +const wasResized = wasInitialized() && resize > 0; + +if (isMacOS && isIE && wasResized) { + // 処理 +} +``` + +### 3. 関数のインライン化（Inline Function） + +不要な間接化を削除: + +```typescript +// Before +function getRating(driver: Driver): number { + return moreThanFiveLateDeliveries(driver) ? 2 : 1; +} + +function moreThanFiveLateDeliveries(driver: Driver): boolean { + return driver.numberOfLateDeliveries > 5; +} + +// After +function getRating(driver: Driver): number { + return driver.numberOfLateDeliveries > 5 ? 2 : 1; +} +``` + +### 4. 条件記述の分解（Decompose Conditional） + +複雑な条件を関数に抽出: + +```typescript +// Before +if (date.before(SUMMER_START) || date.after(SUMMER_END)) { + charge = quantity * winterRate + winterServiceCharge; +} else { + charge = quantity * summerRate; +} + +// After +if (isWinter(date)) { + charge = winterCharge(quantity); +} else { + charge = summerCharge(quantity); +} + +function isWinter(date: Date): boolean { + return date.before(SUMMER_START) || date.after(SUMMER_END); +} + +function winterCharge(quantity: number): number { + return quantity * winterRate + winterServiceCharge; +} + +function summerCharge(quantity: number): number { + return quantity * summerRate; +} +``` + +## 安全なリファクタリング手順 + +### 1. 準備 + +**テストの確認**: +- [ ] 既存のテストが存在するか +- [ ] テストカバレッジが十分か +- [ ] すべてのテストが通るか + +**変更範囲の特定**: +- [ ] 影響を受けるコードを特定 +- [ ] 依存関係を確認 + +### 2. 実行 + +**小さなステップで**: +1. 1つの変更を実施 +2. テストを実行 +3. テストが通ることを確認 +4. コミット +5. 次の変更へ + +**自動化ツールの活用**: +- IDEのリファクタリング機能 +- 自動フォーマッター +- 静的解析ツール + +### 3. 検証 + +**テストの実行**: +```bash +# すべてのテストを実行 +npm test + +# カバレッジを確認 +npm run test:coverage +``` + +**手動確認**: +- [ ] 主要な機能が動作するか +- [ ] パフォーマンスが劣化していないか + +### 4. レビュー + +**セルフレビュー**: +- [ ] 変更が意図通りか +- [ ] 新しいコードスメルが発生していないか +- [ ] ドキュメントが更新されているか + +**チームレビュー**: +- [ ] PRを作成 +- [ ] レビューを依頼 +- [ ] フィードバックを反映 + +## リファクタリングのタイミング + +### ボーイスカウトルール + +**「来た時よりも美しく」** + +コードを触るたびに少しずつ改善: +- バグ修正時に周辺コードをリファクタリング +- 機能追加時に既存コードを整理 +- コードレビュー時に改善提案 + +### 計画的リファクタリング + +**技術的負債の返済**: +- [ ] 定期的なリファクタリング時間を確保 +- [ ] 優先度の高い負債から対処 +- [ ] チーム全体で取り組む + +## 言語別のリファクタリング + +### TypeScript/JavaScript + +**型の活用**: +```typescript +// Before +function process(data: any) { + // 処理 +} + +// After +interface ProcessData { + id: number; + name: string; +} + +function process(data: ProcessData) { + // 処理 +} +``` + +### Rust + +**所有権の最適化**: +```rust +// Before +fn process(data: Vec) -> Vec { + // data の所有権を奪う + data +} + +// After +fn process(data: &[String]) -> Vec { + // 借用を使用 + data.to_vec() +} +``` + +## トラブルシューティング + +### テストが壊れた + +**対処法**: +1. 前回のコミットに戻る（`git reset --hard HEAD~1`） +2. より小さなステップで再試行 +3. テストを先に修正 + +### パフォーマンスが劣化した + +**対処法**: +1. ベンチマークで計測 +2. プロファイラーでボトルネックを特定 +3. 必要に応じて最適化 + +## 関連Skill + +- **tdd-basics**: [tdd-basics](../tdd-basics/SKILL.md) - テストファーストリファクタリング +- **code-review-workflow**: [code-review-workflow](../code-review-workflow/SKILL.md) - リファクタリングのレビュー +- **testing-typescript**: [testing-typescript](../testing-typescript/SKILL.md) - TypeScriptテスト +- **testing-rust**: [testing-rust](../testing-rust/SKILL.md) - Rustテスト + +## 参考リソース + +- [Refactoring by Martin Fowler](https://refactoring.com/) +- [Code Smells](https://refactoring.guru/refactoring/smells) From c29a9a788840a71c0256d7200218975ab7d1ca3c Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:56:04 +0900 Subject: [PATCH 05/20] feat(skills): add documentation-maintenance Skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 継続的なドキュメントメンテナンスのガイド - ドキュメントの種類（README、API、CHANGELOG、CONTRIBUTING、ADR） - ドキュメント作成のベストプラクティス - コードコメントのベストプラクティス - ドキュメント生成ツールと自動化 --- .../skills/documentation-maintenance/SKILL.md | 479 ++++++++++++++++++ 1 file changed, 479 insertions(+) create mode 100644 .claude/skills/documentation-maintenance/SKILL.md diff --git a/.claude/skills/documentation-maintenance/SKILL.md b/.claude/skills/documentation-maintenance/SKILL.md new file mode 100644 index 0000000..4ef4514 --- /dev/null +++ b/.claude/skills/documentation-maintenance/SKILL.md @@ -0,0 +1,479 @@ +--- +name: documentation-maintenance +description: Guide for continuous documentation maintenance. Use when creating or updating documentation, writing API docs, maintaining README files, or ensuring documentation quality. +--- + +# Documentation Maintenance + +このスキルは、継続的なドキュメントメンテナンスをガイドします。 + +## ドキュメントの種類 + +### 1. README.md + +**必須セクション**: +- [ ] プロジェクト概要 +- [ ] インストール手順 +- [ ] 使用方法 +- [ ] 設定方法 +- [ ] コントリビューションガイド +- [ ] ライセンス + +**テンプレート**: +```markdown +# Project Name + +Brief description of what this project does. + +## Features + +- Feature 1 +- Feature 2 +- Feature 3 + +## Installation + +\`\`\`bash +npm install project-name +\`\`\` + +## Usage + +\`\`\`typescript +import { function } from 'project-name'; + +function(); +\`\`\` + +## Configuration + +\`\`\`typescript +const config = { + option1: 'value1', + option2: 'value2' +}; +\`\`\` + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) + +## License + +MIT +``` + +### 2. API ドキュメント + +**TypeScript/JavaScript**: +```typescript +/** + * Processes user data and returns a summary. + * + * @param user - The user object to process + * @param options - Optional processing options + * @returns A summary of the user data + * @throws {ValidationError} If user data is invalid + * + * @example + * ```typescript + * const summary = processUser(user, { detailed: true }); + * console.log(summary); + * ``` + */ +export function processUser( + user: User, + options?: ProcessOptions +): UserSummary { + // 実装 +} +``` + +**Rust**: +```rust +/// Processes user data and returns a summary. +/// +/// # Arguments +/// +/// * `user` - The user object to process +/// * `options` - Optional processing options +/// +/// # Returns +/// +/// A summary of the user data +/// +/// # Errors +/// +/// Returns `ValidationError` if user data is invalid +/// +/// # Examples +/// +/// ``` +/// let summary = process_user(&user, Some(options)); +/// println!("{:?}", summary); +/// ``` +pub fn process_user( + user: &User, + options: Option +) -> Result { + // 実装 +} +``` + +### 3. CHANGELOG.md + +**フォーマット**: +```markdown +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/), +and this project adheres to [Semantic Versioning](https://semver.org/). + +## [Unreleased] + +### Added +- New feature description + +### Changed +- Changed feature description + +### Fixed +- Bug fix description + +## [1.0.0] - 2024-01-01 + +### Added +- Initial release +``` + +### 4. CONTRIBUTING.md + +**必須セクション**: +- [ ] 開発環境のセットアップ +- [ ] コーディング規約 +- [ ] コミットメッセージ規約 +- [ ] PR作成ガイド +- [ ] テスト実行方法 + +### 5. アーキテクチャドキュメント + +**ADR (Architecture Decision Records)**: +```markdown +# ADR-001: Use TypeScript for Backend + +## Status +Accepted + +## Context +We need to choose a language for our backend services. + +## Decision +We will use TypeScript for backend development. + +## Consequences +### Positive +- Type safety +- Better IDE support +- Shared code with frontend + +### Negative +- Compilation step required +- Learning curve for team +``` + +## ドキュメント作成のベストプラクティス + +### 1. 明確で簡潔に + +**良い例**: +```markdown +## Installation + +Install the package using npm: + +\`\`\`bash +npm install my-package +\`\`\` +``` + +**悪い例**: +```markdown +## How to Install This Package + +First, you need to have npm installed on your system. +Then, open your terminal and navigate to your project directory. +After that, you can install the package by running the following command... +``` + +### 2. コード例を含める + +すべての主要な機能にコード例を提供: + +```markdown +## Usage + +### Basic Example + +\`\`\`typescript +import { createUser } from 'my-package'; + +const user = createUser({ + name: 'John Doe', + email: 'john@example.com' +}); +\`\`\` + +### Advanced Example + +\`\`\`typescript +const user = createUser({ + name: 'John Doe', + email: 'john@example.com', + options: { + sendWelcomeEmail: true, + role: 'admin' + } +}); +\`\`\` +``` + +### 3. 最新の状態を保つ + +**ドキュメント更新のタイミング**: +- [ ] 新機能追加時 +- [ ] API変更時 +- [ ] バグ修正時（重要な場合） +- [ ] 設定変更時 + +### 4. スクリーンショットを活用 + +UIの説明にはスクリーンショットを含める: + +```markdown +## Dashboard + +The main dashboard shows your project overview: + +![Dashboard Screenshot](./docs/images/dashboard.png) +``` + +## コードコメントのベストプラクティス + +### WHYを説明する + +**良い例**: +```typescript +// ユーザーのセッションタイムアウトを30分に設定 +// 短すぎるとユーザー体験が悪化し、長すぎるとセキュリティリスクが高まる +const SESSION_TIMEOUT = 30 * 60 * 1000; +``` + +**悪い例**: +```typescript +// タイムアウトを設定 +const SESSION_TIMEOUT = 30 * 60 * 1000; +``` + +### 複雑なロジックを説明する + +```typescript +// Fisher-Yates アルゴリズムを使用した配列のシャッフル +// O(n) の時間計算量で、すべての順列が等確率で生成される +function shuffle(array: T[]): T[] { + const result = [...array]; + for (let i = result.length - 1; i > 0; i--) { + const j = Math.floor(Math.random() * (i + 1)); + [result[i], result[j]] = [result[j], result[i]]; + } + return result; +} +``` + +### TODOコメントの管理 + +```typescript +// TODO(username): Implement caching for better performance +// Issue: #123 +// Deadline: 2024-12-31 +function fetchData() { + // 実装 +} +``` + +## ドキュメント生成ツール + +### TypeScript/JavaScript + +**TypeDoc**: +```bash +# インストール +npm install --save-dev typedoc + +# ドキュメント生成 +npx typedoc src/index.ts +``` + +**JSDoc**: +```bash +# インストール +npm install --save-dev jsdoc + +# ドキュメント生成 +npx jsdoc src +``` + +### Rust + +**cargo doc**: +```bash +# ドキュメント生成 +cargo doc + +# ブラウザで開く +cargo doc --open + +# プライベート項目も含める +cargo doc --document-private-items +``` + +## ドキュメントの品質チェック + +### チェックリスト + +**README.md**: +- [ ] プロジェクト概要が明確か +- [ ] インストール手順が正確か +- [ ] 使用例が動作するか +- [ ] リンクが切れていないか +- [ ] スクリーンショットが最新か + +**API ドキュメント**: +- [ ] すべての公開APIに説明があるか +- [ ] パラメータが説明されているか +- [ ] 戻り値が説明されているか +- [ ] エラーケースが説明されているか +- [ ] 使用例があるか + +**CHANGELOG.md**: +- [ ] 最新バージョンが記載されているか +- [ ] 破壊的変更が明記されているか +- [ ] リリース日が記載されているか + +## ドキュメントの多言語対応 + +### ディレクトリ構造 + +``` +docs/ +├── en/ +│ ├── README.md +│ ├── API.md +│ └── CONTRIBUTING.md +├── ja/ +│ ├── README.md +│ ├── API.md +│ └── CONTRIBUTING.md +└── zh/ + ├── README.md + ├── API.md + └── CONTRIBUTING.md +``` + +### 言語切り替えリンク + +```markdown +# Project Name + +[English](./en/README.md) | [日本語](./ja/README.md) | [中文](./zh/README.md) +``` + +## ドキュメントレビュー + +### レビューポイント + +- [ ] 技術的な正確性 +- [ ] 文法とスペル +- [ ] 一貫性（用語、スタイル） +- [ ] 完全性（必要な情報がすべて含まれているか） +- [ ] 可読性 + +### ツールの活用 + +**スペルチェック**: +```bash +# cspell を使用 +npm install -g cspell +cspell "**/*.md" +``` + +**リンクチェック**: +```bash +# markdown-link-check を使用 +npm install -g markdown-link-check +markdown-link-check README.md +``` + +## ドキュメントの自動化 + +### CI/CDでのドキュメント生成 + +**GitHub Actions**: +```yaml +name: Generate Docs + +on: + push: + branches: [main] + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install dependencies + run: npm ci + + - name: Generate docs + run: npm run docs + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs +``` + +## トラブルシューティング + +### ドキュメントが古くなっている + +**対処法**: +1. ドキュメント更新をPRの必須項目にする +2. 定期的なドキュメントレビューを実施 +3. 自動化ツールで検出 + +### ドキュメントが見つからない + +**対処法**: +1. README.mdに目次を追加 +2. ドキュメントの構造を整理 +3. 検索機能を追加 + +## 関連Skill + +- **spec-kit-workflow**: [spec-kit-workflow](../spec-kit-workflow/SKILL.md) - 仕様ドキュメント +- **code-review-workflow**: [code-review-workflow](../code-review-workflow/SKILL.md) - ドキュメントレビュー + +## 参考リソース + +- [Keep a Changelog](https://keepachangelog.com/) +- [Semantic Versioning](https://semver.org/) +- [Write the Docs](https://www.writethedocs.org/) From f918a600d83ef090e99bb9b023d1d3f0a301c146 Mon Sep 17 00:00:00 2001 From: UtakataKyosui Date: Mon, 12 Jan 2026 13:56:28 +0900 Subject: [PATCH 06/20] refactor: remove .claude/commands directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - コマンドディレクトリを削除 - スマートフォン/GitHub ActionsのCronから起動するため不要 - すべての機能はAgent Skillsに移行済み --- .claude/commands/development/code-review.md | 23 --- .claude/commands/development/debug-help.md | 24 --- .claude/commands/development/refactor.md | 25 --- .claude/commands/documentation/docs-gen.md | 25 --- .../project-management/setup-project.md | 22 --- .claude/commands/spec-kit/analyze.md | 101 ----------- .claude/commands/spec-kit/clarify.md | 158 ------------------ .claude/commands/spec-kit/constitution.md | 73 -------- .claude/commands/spec-kit/implement.md | 56 ------- .claude/commands/spec-kit/plan.md | 43 ----- .claude/commands/spec-kit/specify.md | 21 --- .claude/commands/spec-kit/tasks.md | 62 ------- .claude/commands/testing/test-gen.md | 24 --- 13 files changed, 657 deletions(-) delete mode 100644 .claude/commands/development/code-review.md delete mode 100644 .claude/commands/development/debug-help.md delete mode 100644 .claude/commands/development/refactor.md delete mode 100644 .claude/commands/documentation/docs-gen.md delete mode 100644 .claude/commands/project-management/setup-project.md delete mode 100644 .claude/commands/spec-kit/analyze.md delete mode 100644 .claude/commands/spec-kit/clarify.md delete mode 100644 .claude/commands/spec-kit/constitution.md delete mode 100644 .claude/commands/spec-kit/implement.md delete mode 100644 .claude/commands/spec-kit/plan.md delete mode 100644 .claude/commands/spec-kit/specify.md delete mode 100644 .claude/commands/spec-kit/tasks.md delete mode 100644 .claude/commands/testing/test-gen.md diff --git a/.claude/commands/development/code-review.md b/.claude/commands/development/code-review.md deleted file mode 100644 index 8f3c00b..0000000 --- a/.claude/commands/development/code-review.md +++ /dev/null @@ -1,23 +0,0 @@ -# /code-review - -コードレビューを実行し、品質向上のための提案を行います。 - -## 実行内容 -1. コード品質の分析 -2. セキュリティ脆弱性のチェック -3. パフォーマンス改善点の指摘 -4. ベストプラクティスの適用確認 -5. テストカバレッジの評価 -6. ドキュメントの完全性チェック - -## 使用例 -- `/code-review` - 変更されたファイルをレビュー -- `/code-review --full` - プロジェクト全体をレビュー -- `/code-review src/main.rs` - 特定ファイルをレビュー - -## レビュー観点 -- コード品質（可読性、保守性） -- セキュリティ（脆弱性、認証・認可） -- パフォーマンス（計算量、メモリ使用量） -- テスト（カバレッジ、エッジケース） -- ドキュメント（コメント、README） \ No newline at end of file diff --git a/.claude/commands/development/debug-help.md b/.claude/commands/development/debug-help.md deleted file mode 100644 index 57828ca..0000000 --- a/.claude/commands/development/debug-help.md +++ /dev/null @@ -1,24 +0,0 @@ -# /debug-help - -デバッグ支援を行い、問題の特定と解決策を提供します。 - -## 実行内容 -1. エラーメッセージの解析 -2. ログの分析と問題箇所の特定 -3. 再現手順の確認 -4. 原因の推定と修正案の提示 -5. テストケースの作成支援 -6. デバッグ手法の提案 - -## 使用例 -- `/debug-help` - 現在のエラー状況を分析 -- `/debug-help "error message"` - 特定のエラーメッセージを分析 -- `/debug-help --logs` - ログファイルから問題を特定 - -## 対応する問題タイプ -- コンパイル/ビルドエラー -- 実行時エラー・例外 -- パフォーマンス問題 -- メモリリーク -- データ破損・不整合 -- ネットワーク・通信エラー \ No newline at end of file diff --git a/.claude/commands/development/refactor.md b/.claude/commands/development/refactor.md deleted file mode 100644 index c984e3b..0000000 --- a/.claude/commands/development/refactor.md +++ /dev/null @@ -1,25 +0,0 @@ -# /refactor - -コードリファクタリングを実行し、保守性と可読性を向上させます。 - -## 実行内容 -1. コード重複の除去 -2. 関数・クラス設計の改善 -3. 命名規則の統一 -4. デザインパターンの適用 -5. 依存関係の整理 -6. パフォーマンス最適化 - -## 使用例 -- `/refactor` - 選択中のコードをリファクタリング -- `/refactor --extract-function` - 関数抽出リファクタリング -- `/refactor --rename-variables` - 変数名の統一・改善 - -## リファクタリング手法 -- Extract Method/Function -- Extract Class/Module -- Rename Variable/Function/Class -- Move Method/Field -- Replace Magic Numbers with Constants -- Eliminate Code Duplication -- Simplify Conditional Expressions \ No newline at end of file diff --git a/.claude/commands/documentation/docs-gen.md b/.claude/commands/documentation/docs-gen.md deleted file mode 100644 index aff3da8..0000000 --- a/.claude/commands/documentation/docs-gen.md +++ /dev/null @@ -1,25 +0,0 @@ -# /docs-gen - -ドキュメントの自動生成と既存ドキュメントの改善を行います。 - -## 実行内容 -1. API ドキュメントの生成 -2. README ファイルの作成・更新 -3. インラインコメントの追加 -4. 使用例・サンプルコードの作成 -5. 設計ドキュメントの生成 -6. 多言語対応ドキュメント - -## 使用例 -- `/docs-gen` - 選択中のコードのドキュメントを生成 -- `/docs-gen --api` - API ドキュメントを生成 -- `/docs-gen --readme` - README ファイルを更新 - -## 生成するドキュメント -- README.md -- API Reference -- Code Comments -- Usage Examples -- Architecture Documents -- Development Guide -- User Manual \ No newline at end of file diff --git a/.claude/commands/project-management/setup-project.md b/.claude/commands/project-management/setup-project.md deleted file mode 100644 index 79b2f86..0000000 --- a/.claude/commands/project-management/setup-project.md +++ /dev/null @@ -1,22 +0,0 @@ -# /setup-project - -新規プロジェクトの初期セットアップを行います。 - -## 実行内容 -1. プロジェクト構造の分析 -2. 必要な設定ファイルの確認・作成 -3. 依存関係の解決 -4. 開発環境の初期化 -5. 基本的なCI/CD設定の確認 - -## 使用例 -- `/setup-project` - 現在のディレクトリでプロジェクトセットアップを実行 -- 言語やフレームワークを自動検出してセットアップを行う - -## 対象言語・フレームワーク -- Rust (Cargo.toml) -- Node.js (package.json) -- Python (pyproject.toml, requirements.txt) -- Go (go.mod) -- Java/Kotlin (build.gradle, pom.xml) -- その他の一般的なプロジェクト構成 \ No newline at end of file diff --git a/.claude/commands/spec-kit/analyze.md b/.claude/commands/spec-kit/analyze.md deleted file mode 100644 index f4c1a7b..0000000 --- a/.claude/commands/spec-kit/analyze.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. ---- - -The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). - -User input: - -$ARGUMENTS - -Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`. - -STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). - -Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`. - -Execution steps: - -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: - - SPEC = FEATURE_DIR/spec.md - - PLAN = FEATURE_DIR/plan.md - - TASKS = FEATURE_DIR/tasks.md - Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). - -2. Load artifacts: - - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). - - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints. - - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths. - - Load constitution `.specify/memory/constitution.md` for principle validation. - -3. Build internal semantic models: - - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`). - - User story/action inventory. - - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases). - - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements. - -4. Detection passes: - A. Duplication detection: - - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation. - B. Ambiguity detection: - - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria. - - Flag unresolved placeholders (TODO, TKTK, ???, , etc.). - C. Underspecification: - - Requirements with verbs but missing object or measurable outcome. - - User stories missing acceptance criteria alignment. - - Tasks referencing files or components not defined in spec/plan. - D. Constitution alignment: - - Any requirement or plan element conflicting with a MUST principle. - - Missing mandated sections or quality gates from constitution. - E. Coverage gaps: - - Requirements with zero associated tasks. - - Tasks with no mapped requirement/story. - - Non-functional requirements not reflected in tasks (e.g., performance, security). - F. Inconsistency: - - Terminology drift (same concept named differently across files). - - Data entities referenced in plan but absent in spec (or vice versa). - - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note). - - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework). - -5. Severity assignment heuristic: - - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality. - - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion. - - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case. - - LOW: Style/wording improvements, minor redundancy not affecting execution order. - -6. Produce a Markdown report (no file writes) with sections: - - ### Specification Analysis Report - | ID | Category | Severity | Location(s) | Summary | Recommendation | - |----|----------|----------|-------------|---------|----------------| - | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | - (Add one row per finding; generate stable IDs prefixed by category initial.) - - Additional subsections: - - Coverage Summary Table: - | Requirement Key | Has Task? | Task IDs | Notes | - - Constitution Alignment Issues (if any) - - Unmapped Tasks (if any) - - Metrics: - * Total Requirements - * Total Tasks - * Coverage % (requirements with >=1 task) - * Ambiguity Count - * Duplication Count - * Critical Issues Count - -7. At end of report, output a concise Next Actions block: - - If CRITICAL issues exist: Recommend resolving before `/implement`. - - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions. - - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'". - -8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) - -Behavior rules: -- NEVER modify files. -- NEVER hallucinate missing sections—if absent, report them. -- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts. -- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note. -- If zero issues found, emit a success report with coverage statistics and proceed recommendation. - -Context: $ARGUMENTS diff --git a/.claude/commands/spec-kit/clarify.md b/.claude/commands/spec-kit/clarify.md deleted file mode 100644 index 26ff530..0000000 --- a/.claude/commands/spec-kit/clarify.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. ---- - -The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). - -User input: - -$ARGUMENTS - -Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. - -Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. - -Execution steps: - -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: - - `FEATURE_DIR` - - `FEATURE_SPEC` - - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) - - If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment. - -2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). - - Functional Scope & Behavior: - - Core user goals & success criteria - - Explicit out-of-scope declarations - - User roles / personas differentiation - - Domain & Data Model: - - Entities, attributes, relationships - - Identity & uniqueness rules - - Lifecycle/state transitions - - Data volume / scale assumptions - - Interaction & UX Flow: - - Critical user journeys / sequences - - Error/empty/loading states - - Accessibility or localization notes - - Non-Functional Quality Attributes: - - Performance (latency, throughput targets) - - Scalability (horizontal/vertical, limits) - - Reliability & availability (uptime, recovery expectations) - - Observability (logging, metrics, tracing signals) - - Security & privacy (authN/Z, data protection, threat assumptions) - - Compliance / regulatory constraints (if any) - - Integration & External Dependencies: - - External services/APIs and failure modes - - Data import/export formats - - Protocol/versioning assumptions - - Edge Cases & Failure Handling: - - Negative scenarios - - Rate limiting / throttling - - Conflict resolution (e.g., concurrent edits) - - Constraints & Tradeoffs: - - Technical constraints (language, storage, hosting) - - Explicit tradeoffs or rejected alternatives - - Terminology & Consistency: - - Canonical glossary terms - - Avoided synonyms / deprecated terms - - Completion Signals: - - Acceptance criteria testability - - Measurable Definition of Done style indicators - - Misc / Placeholders: - - TODO markers / unresolved decisions - - Ambiguous adjectives ("robust", "intuitive") lacking quantification - - For each category with Partial or Missing status, add a candidate question opportunity unless: - - Clarification would not materially change implementation or validation strategy - - Information is better deferred to planning phase (note internally) - -3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - - Maximum of 5 total questions across the whole session. - - Each question must be answerable with EITHER: - * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR - * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). - - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. - - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. - - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). - - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. - - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. - -4. Sequential questioning loop (interactive): - - Present EXACTLY ONE question at a time. - - For multiple‑choice questions render options as a Markdown table: - - | Option | Description | - |--------|-------------| - | A |