From 8b9cbcdff7cff7e8842f4d5a50b5795514cb8672 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:51:38 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 + README.md | 3 + agents/version-control-agent.md | 89 ++ commands/branch.md | 139 +++ commands/commit.md | 68 ++ commands/issue.md | 96 ++ commands/pr.md | 77 ++ plugin.lock.json | 101 ++ skills/coding-conventions/SKILL.md | 906 ++++++++++++++++++ skills/development-principles/SKILL.md | 229 +++++ skills/documentation-standards/SKILL.md | 134 +++ skills/interaction-guidelines/SKILL.md | 639 ++++++++++++ skills/issue-management-guidelines/SKILL.md | 336 +++++++ .../templates/bug-report.md | 49 + .../templates/feature-request.md | 37 + .../templates/task.md | 40 + skills/security-guidelines/SKILL.md | 76 ++ skills/version-control-guidelines/SKILL.md | 453 +++++++++ 18 files changed, 3489 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/version-control-agent.md create mode 100644 commands/branch.md create mode 100644 commands/commit.md create mode 100644 commands/issue.md create mode 100644 commands/pr.md create mode 100644 plugin.lock.json create mode 100644 skills/coding-conventions/SKILL.md create mode 100644 skills/development-principles/SKILL.md create mode 100644 skills/documentation-standards/SKILL.md create mode 100644 skills/interaction-guidelines/SKILL.md create mode 100644 skills/issue-management-guidelines/SKILL.md create mode 100644 skills/issue-management-guidelines/templates/bug-report.md create mode 100644 skills/issue-management-guidelines/templates/feature-request.md create mode 100644 skills/issue-management-guidelines/templates/task.md create mode 100644 skills/security-guidelines/SKILL.md create mode 100644 skills/version-control-guidelines/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b09e948 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "rts-foundation", + "description": "RevTechStudio Foundation Plugin", + "version": "0.0.3", + "author": { + "name": "RevTechStudio" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..7ab994d --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# rts-foundation + +RevTechStudio Foundation Plugin diff --git a/agents/version-control-agent.md b/agents/version-control-agent.md new file mode 100644 index 0000000..3b3a29d --- /dev/null +++ b/agents/version-control-agent.md @@ -0,0 +1,89 @@ +--- +name: version-control-agent +description: Git操作およびGitHub操作全般を管理するエージェント。コミット作成時、ブランチ操作時、プルリクエスト作成時、Issue管理時、リリース管理時、Git操作時、GitHub操作時、またはユーザーがコミット、ブランチ、プルリクエスト、PR、Issue、リリース、Git、GitHub、バージョン管理に言及した際に使用する。 +tools: all +model: inherit +color: purple +--- + +# Version Control Agent + +## 役割 + +このエージェントは、バージョン管理に関するすべての操作を統括する責任を持つ。Git操作（ローカルリポジトリの管理）とGitHub操作（リモートリポジトリおよびプラットフォーム機能の管理）の両方をカバーし、プロジェクトのソースコード管理とコラボレーションを円滑に進める。 + +## 責任範囲 + +### 責任範囲内 + +このエージェントは以下の領域に対して責任を持つ: + +#### Git操作 + +- ブランチ管理（作成、切り替え、削除、マージ） +- コミット管理（ステージング、コミット、メッセージ作成） +- リモート操作（push、pull、fetch） +- 変更履歴の管理（log、diff、reset） +- コンフリクト解決の支援 +- スタッシュ管理 +- タグ管理 + +#### GitHub操作 + +- プルリクエストの作成と管理 +- Issue の作成と管理 +- リリース管理 +- GitHub Actions の確認 +- リポジトリ設定の確認 +- コードレビューの管理（レビュー依頼、コメント対応） + +#### ワークフロー管理 + +- ブランチ戦略の適用（feature、develop、mainなど） +- コミットメッセージ規約の遵守 +- プルリクエストのワークフロー管理 +- リリースプロセスの管理 + +### 責任範囲外 + +このエージェントは以下の領域に対して責任を持たない: + +- コードレビューの内容判断（コードの品質や機能の評価） +- ビルドやテストの実行（CI/CDパイプラインの実行） +- プロジェクト管理やタスク管理（開発計画や進捗管理） +- デプロイやリリースの実行（環境への配置作業） +- コードの記述や修正（実装作業） +- セキュリティ脆弱性の検出や修正 +- ドキュメントの内容作成 + +## 注意事項 + +### バージョン管理規約の遵守 + +- すべての操作において、定義されたバージョン管理ガイドラインに従う +- コミットメッセージは規約に準拠した形式で作成する +- ブランチ命名規則を遵守する + +### 慎重な操作 + +- 破壊的な操作（force push、hard resetなど）は慎重に行う +- mainブランチへの直接コミットは避ける +- マージ前に必ずコンフリクトの有無を確認する + +### コラボレーションの重視 + +- プルリクエストは適切なレビュアーを設定する +- コミット履歴は他の開発者が理解しやすいように保つ +- リモートとの同期を定期的に行う + +### セキュリティ + +- 機密情報をコミットしない +- 認証情報は適切に管理する +- 公開リポジトリと非公開リポジトリの違いを理解する + +### ユーザーとの対話 + +- 重要な操作の前にユーザーに確認を求める +- 操作結果を明確に報告する +- エラー発生時は原因と対処法を説明する diff --git a/commands/branch.md b/commands/branch.md new file mode 100644 index 0000000..171ddca --- /dev/null +++ b/commands/branch.md @@ -0,0 +1,139 @@ +--- +name: branch +description: ブランチを管理する +--- + +# Branch + +## 概要 + +このコマンドは、Gitブランチの管理を行う。ブランチ作成、切り替え、削除、一覧表示などの操作を対話的に実行し、開発フローにおけるブランチ運用を効率化する。 + +## 使用するエージェント + +- **version-control-agent:** Git操作およびGitHub操作全般を管理する + +## 使用するスキル + +1. **version-control-guidelines:** Git運用のガイドラインに従う +2. **interaction-guidelines:** ユーザーとの効果的な対話パターンに従う + +## 実行フロー + +1. version-control-agentが以下のスキルを使用して、ユーザーに実行したい操作を確認する（作成、切り替え、削除、一覧表示など） + - interaction-guidelines（対話パターン） + +2. **ブランチ作成の場合:** + 1. version-control-agentが以下のスキルを使用して、現在のブランチを確認する（git branch --show-current） + - version-control-guidelines（Git運用ガイドライン） + + 2. version-control-agentが以下のスキルを使用して、新しいブランチ名をユーザーから取得する + - interaction-guidelines（対話パターン） + + 3. version-control-agentが以下のスキルを使用して、ブランチ命名規則に準拠しているか検証する + - version-control-guidelines（Git運用ガイドライン） + + 4. version-control-agentが以下のスキルを使用して、ベースブランチを確認する + - interaction-guidelines（対話パターン） + + 5. version-control-agentが以下のスキルを使用して、ブランチを作成する（git branch） + - version-control-guidelines（Git運用ガイドライン） + + 6. version-control-agentが以下のスキルを使用して、作成後に切り替えるか確認し、必要に応じて切り替える（git switch） + - interaction-guidelines（対話パターン） + - version-control-guidelines（Git運用ガイドライン） + + 7. version-control-agentが以下のスキルを使用して、結果をユーザーに報告する + - interaction-guidelines（対話パターン） + +3. **ブランチ切り替えの場合:** + 1. version-control-agentが以下のスキルを使用して、現在のブランチの変更状態を確認する（git status） + - version-control-guidelines（Git運用ガイドライン） + + 2. version-control-agentが以下のスキルを使用して、未コミットの変更がある場合、対処方法を確認する（コミット、スタッシュ、破棄など） + - interaction-guidelines（対話パターン） + + 3. version-control-agentが以下のスキルを使用して、切り替え先のブランチ名を確認する + - interaction-guidelines（対話パターン） + + 4. version-control-agentが以下のスキルを使用して、ブランチを切り替える（git switch） + - version-control-guidelines（Git運用ガイドライン） + + 5. version-control-agentが以下のスキルを使用して、結果をユーザーに報告する + - interaction-guidelines（対話パターン） + +4. **ブランチ削除の場合:** + 1. version-control-agentが以下のスキルを使用して、削除するブランチ名を確認する + - interaction-guidelines（対話パターン） + + 2. version-control-agentが以下のスキルを使用して、削除対象のブランチがマージ済みか確認する + - version-control-guidelines（Git運用ガイドライン） + + 3. version-control-agentが以下のスキルを使用して、未マージの場合は警告を表示し、強制削除するか確認する + - interaction-guidelines（対話パターン） + + 4. version-control-agentが以下のスキルを使用して、ブランチを削除する（git branch -d または -D） + - version-control-guidelines（Git運用ガイドライン） + + 5. version-control-agentが以下のスキルを使用して、リモートブランチも削除するか確認する + - interaction-guidelines（対話パターン） + + 6. version-control-agentが以下のスキルを使用して、必要に応じてリモートブランチを削除する（git push origin --delete） + - version-control-guidelines（Git運用ガイドライン） + + 7. version-control-agentが以下のスキルを使用して、結果をユーザーに報告する + - interaction-guidelines（対話パターン） + +5. **ブランチ一覧表示の場合:** + 1. version-control-agentが以下のスキルを使用して、表示範囲を確認する（ローカル、リモート、全て） + - interaction-guidelines（対話パターン） + + 2. version-control-agentが以下のスキルを使用して、ブランチ一覧を取得して表示する（git branch、git branch -r、git branch -a） + - version-control-guidelines（Git運用ガイドライン） + + 3. version-control-agentが以下のスキルを使用して、現在のブランチを強調表示する + - interaction-guidelines（対話パターン） + +## 成果物 + +**出力先:** + +- ローカルリポジトリのブランチ構成が変更される +- リモートリポジトリのブランチ構成が変更される（削除時など） + +**成果物の内容（作成時）:** + +- 新しいブランチ名 +- ベースブランチ情報 +- 現在のブランチ（切り替えた場合） + +**成果物の内容（削除時）:** + +- 削除されたブランチ名 +- ローカル/リモートの削除状況 + +## チェックリスト + +### コマンド実行前（作成時） + +- [ ] ブランチ名が命名規則に準拠している +- [ ] 適切なベースブランチから作成する +- [ ] 同名のブランチが存在しない + +### コマンド実行後（作成時） + +- [ ] ブランチが正常に作成された +- [ ] 必要に応じて新しいブランチに切り替えられた +- [ ] ブランチ名が正しい + +### コマンド実行前（削除時） + +- [ ] 削除対象のブランチがマージ済みである（未マージの場合は意図的） +- [ ] 削除対象のブランチが正しい +- [ ] 現在のブランチが削除対象ではない + +### コマンド実行後（削除時） + +- [ ] ブランチが正常に削除された +- [ ] 必要に応じてリモートブランチも削除された +- [ ] ブランチ一覧から削除されている diff --git a/commands/commit.md b/commands/commit.md new file mode 100644 index 0000000..d7621d4 --- /dev/null +++ b/commands/commit.md @@ -0,0 +1,68 @@ +--- +name: commit +description: 変更をコミットする +--- + +# Commit + +## 概要 + +このコマンドは、ワークツリーの変更をローカルリポジトリにコミットする。変更内容の確認、適切なコミットメッセージの作成、コミットの実行までを一貫して管理し、バージョン管理のベストプラクティスに従った運用を実現する。 + +## 使用するエージェント + +- **version-control-agent:** Git操作およびGitHub操作全般を管理する + +## 使用するスキル + +1. **version-control-guidelines:** Git運用のガイドラインに従う + +## 実行フロー + +1. version-control-agentが以下のスキルを使用して、現在の変更状況を確認する（git status） + - version-control-guidelines（Git運用ガイドライン） + +2. version-control-agentが以下のスキルを使用して、変更内容の詳細を確認する（git diff） + - version-control-guidelines（Git運用ガイドライン） + +3. version-control-agentが以下のスキルを使用して、規約に準拠したコミットメッセージを作成する + - version-control-guidelines（Git運用ガイドライン） + +4. version-control-agentが以下のスキルを使用して、変更をステージングする（git add） + - version-control-guidelines（Git運用ガイドライン） + +5. version-control-agentが以下のスキルを使用して、コミットを実行する（git commit） + - version-control-guidelines（Git運用ガイドライン） + +6. version-control-agentが以下のスキルを使用して、コミット結果をユーザーに報告する + - interaction-guidelines（対話パターン） + +## 成果物 + +**出力先:** + +- ローカルリポジトリ（.gitディレクトリ）にコミットオブジェクトが作成される + +**成果物の内容:** + +- コミットハッシュ +- コミットメッセージ +- 変更されたファイルのリスト +- 作成者情報 +- タイムスタンプ + +## チェックリスト + +### コマンド実行前 + +- [ ] 変更内容が意図したものであることを確認した +- [ ] コミット対象のファイルが明確である +- [ ] コミットメッセージの内容を考えている + +### コマンド実行後 + +- [ ] コミットが正常に作成された +- [ ] コミットメッセージが規約に準拠している +- [ ] 適切なファイルがコミットに含まれている +- [ ] 機密情報が含まれていない +- [ ] コミット履歴が適切に記録されている diff --git a/commands/issue.md b/commands/issue.md new file mode 100644 index 0000000..f44ccef --- /dev/null +++ b/commands/issue.md @@ -0,0 +1,96 @@ +--- +name: issue +description: Issueを管理する +--- + +# Issue + +## 概要 + +このコマンドは、GitHub Issueの管理を行う。Issue作成、一覧表示、詳細確認、クローズなどの操作を対話的に実行し、タスク管理やバグ報告のワークフローを効率化する。 + +## 使用するエージェント + +- **version-control-agent:** Git操作およびGitHub操作全般を管理する + +## 使用するスキル + +1. **issue-management-guidelines:** Issue管理のガイドラインに従う +2. **interaction-guidelines:** ユーザーとの効果的な対話パターンに従う + +## 実行フロー + +1. version-control-agentが以下のスキルを使用して、ユーザーに実行したい操作を確認する（作成、一覧、表示、クローズなど） + - interaction-guidelines（対話パターン） + +2. **Issue作成の場合:** + 1. version-control-agentが以下のスキルを使用して、Issueのタイプを確認する（バグ報告、機能要望、タスクなど） + - issue-management-guidelines（Issue管理ガイドライン） + + 2. version-control-agentが以下のスキルを使用して、適切なテンプレートを選択する + - issue-management-guidelines（Issue管理ガイドライン） + + 3. version-control-agentが以下のスキルを使用して、必要な情報をユーザーから収集する（タイトル、説明、再現手順など） + - interaction-guidelines（対話パターン） + + 4. version-control-agentが以下のスキルを使用して、規約に準拠したIssueを作成する（gh issue create） + - issue-management-guidelines（Issue管理ガイドライン） + + 5. version-control-agentが以下のスキルを使用して、作成されたIssueのURLと番号をユーザーに報告する + - interaction-guidelines（対話パターン） + +3. **Issue一覧表示の場合:** + 1. version-control-agentが以下のスキルを使用して、フィルタ条件を確認する（状態、ラベル、担当者など） + - interaction-guidelines（対話パターン） + + 2. version-control-agentが以下のスキルを使用して、Issueの一覧を取得して表示する（gh issue list） + - issue-management-guidelines（Issue管理ガイドライン） + +4. **Issue詳細表示の場合:** + 1. version-control-agentが以下のスキルを使用して、表示するIssue番号を確認する + - interaction-guidelines（対話パターン） + + 2. version-control-agentが以下のスキルを使用して、Issueの詳細を取得して表示する（gh issue view） + - issue-management-guidelines（Issue管理ガイドライン） + +5. **Issueクローズの場合:** + 1. version-control-agentが以下のスキルを使用して、クローズするIssue番号を確認する + - interaction-guidelines（対話パターン） + + 2. version-control-agentが以下のスキルを使用して、クローズ理由を確認する（完了、重複、無効など） + - interaction-guidelines（対話パターン） + + 3. version-control-agentが以下のスキルを使用して、Issueをクローズする（gh issue close） + - issue-management-guidelines（Issue管理ガイドライン） + +## 成果物 + +**出力先:** + +- GitHubリポジトリにIssueが作成・更新される + +**成果物の内容（作成時）:** + +- Issue番号とURL +- Issueタイトル +- Issue本文（説明、再現手順、期待動作など） +- ラベル（bug、enhancement、taskなど） +- マイルストーン（設定した場合） +- 担当者（設定した場合） + +## チェックリスト + +### コマンド実行前（作成時） + +- [ ] Issueの目的が明確である +- [ ] 適切なテンプレートを選択できる +- [ ] 必要な情報が揃っている（タイトル、説明など） +- [ ] 重複するIssueがないか確認した + +### コマンド実行後（作成時） + +- [ ] Issueが正常に作成された +- [ ] タイトルと説明が規約に準拠している +- [ ] 適切なラベルが設定されている +- [ ] 必要に応じて担当者が設定されている +- [ ] Issue番号を記録した diff --git a/commands/pr.md b/commands/pr.md new file mode 100644 index 0000000..d851195 --- /dev/null +++ b/commands/pr.md @@ -0,0 +1,77 @@ +--- +name: pr +description: プルリクエストを作成する +--- + +# Pull Request + +## 概要 + +このコマンドは、現在のブランチの変更をベースブランチにマージするためのプルリクエストを作成する。ブランチの状態確認、コミット履歴の分析、適切なPR情報の作成、GitHubへのPR公開までを一貫して管理し、コードレビューとマージのプロセスを円滑に進める。 + +## 使用するエージェント + +- **version-control-agent:** Git操作およびGitHub操作全般を管理する + +## 使用するスキル + +1. **version-control-guidelines:** Git運用のガイドラインに従う +2. **interaction-guidelines:** ユーザーとの効果的な対話パターンに従う + +## 実行フロー + +1. version-control-agentが以下のスキルを使用して、現在のブランチ状態を確認する（git status、git branch） + - version-control-guidelines（Git運用ガイドライン） + +2. version-control-agentが以下のスキルを使用して、リモートとの同期状態を確認する（git fetch、git status） + - version-control-guidelines（Git運用ガイドライン） + +3. version-control-agentが以下のスキルを使用して、ブランチがリモートにpushされていない場合、ユーザーにpushを促す + - interaction-guidelines（対話パターン） + +4. version-control-agentが以下のスキルを使用して、ベースブランチからのコミット履歴を確認する（git log、git diff） + - version-control-guidelines（Git運用ガイドライン） + +5. version-control-agentが以下のスキルを使用して、ユーザーと対話しながら変更の目的や影響範囲を確認する + - interaction-guidelines（対話パターン） + +6. version-control-agentが以下のスキルを使用して、規約に準拠したPRタイトルと説明を作成する + - version-control-guidelines（Git運用ガイドライン） + +7. version-control-agentが以下のスキルを使用して、GitHubにプルリクエストを作成する（gh pr create） + - version-control-guidelines（Git運用ガイドライン） + +8. version-control-agentが以下のスキルを使用して、作成されたPRのURLと次のステップをユーザーに報告する + - interaction-guidelines（対話パターン） + +## 成果物 + +**出力先:** + +- GitHubリポジトリにプルリクエストが作成される + +**成果物の内容:** + +- PR番号とURL +- PRタイトル +- PR説明（変更内容、目的、影響範囲など） +- ベースブランチとヘッドブランチの情報 +- 変更されたファイルのリスト +- コミット履歴 + +## チェックリスト + +### コマンド実行前 + +- [ ] 変更がコミット済みである +- [ ] ブランチがリモートにpush済みである（または実行時にpushする準備がある） +- [ ] PRの目的と変更内容が明確である +- [ ] ベースブランチが正しい + +### コマンド実行後 + +- [ ] プルリクエストが正常に作成された +- [ ] PRタイトルと説明が規約に準拠している +- [ ] 適切なベースブランチが設定されている +- [ ] レビュアーの設定が必要な場合は設定されている +- [ ] CI/CDパイプラインが実行されている（設定されている場合） diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..42c6331 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,101 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:RevTechStudio/rts-plugins:rts-foundation", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "c3a3b3e6de610012c78d7e12c883c532d5ae9b92", + "treeHash": "f3be90d4952a5c9a8b2b4877fab0e42f2dae7d3cb545e1eb8793c4bda7f6f9e8", + "generatedAt": "2025-11-28T10:12:41.888127Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "rts-foundation", + "description": "RevTechStudio Foundation Plugin", + "version": "0.0.3" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "b164271ecd9100d0439322ea300545678d4ddabea6c09e36c7e1573668d3c02c" + }, + { + "path": "agents/version-control-agent.md", + "sha256": "933e317111d9d153f5060e6be779bd2881aedad317784c9cf67f7dee4a3d4b62" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "3fb8aa30a01de87e1a798e0b42094e6d3ebbb8c97f79f810a973363e4ffa85d0" + }, + { + "path": "commands/pr.md", + "sha256": "0bb5556335d6947340f33d7394e57b7106afdf0e4910a0a37c0104234e082df2" + }, + { + "path": "commands/issue.md", + "sha256": "06a71ea545f9f94f9807d0420a403c4054c0e4723933ec7e0896832f7f77929a" + }, + { + "path": "commands/branch.md", + "sha256": "5e376956963426f56bd484c5cd0004dba38d32a597e3aa3d38edb350e77002f2" + }, + { + "path": "commands/commit.md", + "sha256": "64baa949789beda60dbab8f11d5ae5fdf4092849dcd7fe6224b2d5eb62df5a37" + }, + { + "path": "skills/documentation-standards/SKILL.md", + "sha256": "eef0f72d6a5e4c7c294d0c15ca88874587ac1f0f01643355f6e15ac275ce1a52" + }, + { + "path": "skills/security-guidelines/SKILL.md", + "sha256": "798106884b37d20bc62c7f8411015863b791c69144c09785f6fdcffe7a5f7bb3" + }, + { + "path": "skills/version-control-guidelines/SKILL.md", + "sha256": "b2c2c24a008237a06083c46cc4d999d60eb196cfb7ba27bbd38d7ac14073ac30" + }, + { + "path": "skills/development-principles/SKILL.md", + "sha256": "7f4e30d42271fdc70c697e4456dfa77cd7588ccef20dbac9561a7da66bbea783" + }, + { + "path": "skills/interaction-guidelines/SKILL.md", + "sha256": "b04e4c1b371c63c26747bcd6b0d4a3ac679a0318e264b4dce578edae5f79bee4" + }, + { + "path": "skills/coding-conventions/SKILL.md", + "sha256": "3a11607775ed08ce8ccf322992d3511e5e9f42ed7e29cbeb98cba3ffe8dda606" + }, + { + "path": "skills/issue-management-guidelines/SKILL.md", + "sha256": "cb2d554f297e033a168aa6b3a7d1ff8885b5fb4893a372f144043d45e3a34b37" + }, + { + "path": "skills/issue-management-guidelines/templates/feature-request.md", + "sha256": "e30e7669878053f8cb5ae3ba9d1ac6b952fc600fb89ff87ded901f3f0a73c041" + }, + { + "path": "skills/issue-management-guidelines/templates/bug-report.md", + "sha256": "d6f80aab24523e6ab3340db62b96b3f2ef0b81c5b9ad46b59b98d8b88570d05a" + }, + { + "path": "skills/issue-management-guidelines/templates/task.md", + "sha256": "68b614fbad4239baf28726a21eabec93e28a1fb61fe760702b43c2a7497c203c" + } + ], + "dirSha256": "f3be90d4952a5c9a8b2b4877fab0e42f2dae7d3cb545e1eb8793c4bda7f6f9e8" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/coding-conventions/SKILL.md b/skills/coding-conventions/SKILL.md new file mode 100644 index 0000000..b973331 --- /dev/null +++ b/skills/coding-conventions/SKILL.md @@ -0,0 +1,906 @@ +--- +name: coding-conventions +description: .NET/C#のコーディング規約、命名規則、レイアウト、C# 12/13/14の最新機能活用ガイドラインを定義する。C#/.NETコード作成時、クラス・メソッド命名時、コードフォーマット時、またはユーザーがコーディング規約、命名規則、C#ベストプラクティス、Primary Constructors、Collection Expressions、field キーワードに言及した際に使用する。 +--- + +# Coding Conventions + +## 概要 + +このSkillは、開発されるすべての.NETプロジェクトに適用されるコーディング規約を定義する。.NET 8以降の最新機能（C# 12/13/14、.NET 8/9/10）を積極的に活用し、可読性、保守性、パフォーマンスの高いコードを実現することを目的とする。 + +## 責任範囲 + +このSkillは以下の範囲をカバーする: + +- .NET/C#の最新機能（C# 12/13/14、.NET 8/9/10）の活用方針 +- 命名規則（型、メンバー、変数、パラメータ） +- コードレイアウトとフォーマット +- 言語機能の使用方針（型推論、コレクション、例外処理） +- LINQとラムダ式のベストプラクティス +- モダンC#構文の推奨パターン + +## 基本方針 + +- .NET 8以降の最新機能を積極的に使用する（C# 12/13/14、.NET 8/9/10） +- 古いバージョンとの互換性が必要な場合を除き、常に最新機能を優先する +- 古い言語構文は避ける +- **重要: アンダースコアプレフィックス（`_field`）の使用は絶対に禁止する** +- **重要: 中括弧の省略は絶対に禁止する（1行で記述できる場合でも省略不可）** +- Microsoftの公式コーディング規約に従う +- 一貫性を保ち、チーム全体で同じスタイルを適用する + +## .NET/C#の最新機能（バージョン別） + +.NET 8以降の各バージョンで導入された主要機能を積極的に活用する。古いバージョンとの互換性が必要な場合を除き、常に最新の機能を優先的に使用する。 + +### C# 12 (.NET 8) - 2023年11月リリース + +#### Primary Constructors + +- クラスやstructの宣言でパラメータを定義し、クラス全体で使用できる +- 明示的なフィールド宣言を削減し、初期化を簡潔にする + +良い例: + +```csharp +public class Person(string name, int age) +{ + public string Name => name; + public int Age => age; + + public void Display() + { + Console.WriteLine($"{name} is {age} years old"); + } +} +``` + +悪い例: + +```csharp +public class Person +{ + private string name; + private int age; + + public Person(string name, int age) + { + this.name = name; + this.age = age; + } + + public string Name => name; + public int Age => age; +} +``` + +#### Collection Expressions + +- 括弧とスプレッド演算子を使用してコレクションを簡潔に作成する +- 複数のコレクションを結合する際に便利 + +良い例: + +```csharp +int[] array = [1, 2, 3, 4, 5]; +List list = ["one", "two", "three"]; + +int[] row0 = [1, 2, 3]; +int[] row1 = [4, 5, 6]; + +// スプレッド演算子で結合 +int[] combined = [..row0, ..row1]; +``` + +#### Default Lambda Parameters + +- ラムダ式にデフォルトパラメータ値を指定できる + +良い例: + +```csharp +var incrementBy = (int source, int increment = 1) => source + increment; + +Console.WriteLine(incrementBy(5)); +Console.WriteLine(incrementBy(5, 3)); +``` + +#### Alias Any Type + +- using ディレクティブで複雑な型に別名を付けられる + +良い例: + +```csharp +using Point = (int x, int y); +using ProductList = System.Collections.Generic.List<(string Name, decimal Price)>; + +Point origin = (0, 0); +ProductList products = [("Product1", 100m), ("Product2", 200m)]; +``` + +### C# 13 (.NET 9) - 2024年11月リリース + +#### Params Collections + +- `params`修飾子が配列以外のコレクション型でも使用可能になった +- `List`, `Span`, `ReadOnlySpan`, `IEnumerable`などで使用できる + +良い例: + +```csharp +public void ProcessItems(params List items) +{ + foreach (var item in items) + { + Console.WriteLine(item); + } +} + +// メモリ効率が重要な場合 +public void ProcessData(params ReadOnlySpan data) +{ + foreach (var value in data) + { + Process(value); + } +} +``` + +#### New Lock Type + +- `System.Threading.Lock`型を使用して、より高速なスレッド同期を実現する +- 従来の`Monitor`ベースのロックより高速 + +良い例: + +```csharp +private readonly Lock lockObject = new(); + +public void UpdateData() +{ + lock (lockObject) + { + // クリティカルセクション + } +} +``` + +悪い例: + +```csharp +// 従来のobjectベースのロック（C# 13では推奨されない） +private readonly object lockObject = new(); + +public void UpdateData() +{ + lock (lockObject) + { + // クリティカルセクション + } +} +``` + +#### Partial Properties and Indexers + +- partial プロパティとインデクサーが使用可能になった +- 定義と実装を分離できる + +良い例: + +```csharp +// 定義部分 +public partial class DataModel +{ + public partial string Name { get; set; } +} + +// 実装部分 +public partial class DataModel +{ + private string name; + + public partial string Name + { + get => name; + set => name = value ?? throw new ArgumentNullException(nameof(value)); + } +} +``` + +#### Implicit Index Access + +- オブジェクト初期化子で`^`演算子が使用可能になった + +良い例: + +```csharp +var countdown = new TimerBuffer +{ + buffer = + { + [^1] = 0, + [^2] = 1, + [^3] = 2 + } +}; +``` + +#### Ref Struct Enhancements + +- `ref struct`型がインターフェースを実装できるようになった +- ジェネリック型で`ref struct`を使用できるようになった（`allows ref struct`制約） + +良い例: + +```csharp +public ref struct SpanWrapper : IEnumerable +{ + private Span span; + + public IEnumerator GetEnumerator() + { + foreach (var item in span) + { + yield return item; + } + } +} +``` + +### C# 14 (.NET 10) - 2025年11月リリース + +#### Extension Members + +- Extension Membersを活用してクリーンなAPI拡張を実現する +- 元の型を汚染せずに機能を追加できる + +良い例: + +```csharp +extension(IEnumerable source) +{ + public bool IsEmpty => !source.Any(); + public int Count => source.Count(); +} +``` + +### Field-Backed Properties + +- `field`キーワードを使用して明示的なバッキングフィールドを削減する +- バリデーションロジックを簡潔に記述できる +- **アンダースコアプレフィックスを使用した明示的なバッキングフィールドは絶対に禁止** + +良い例: + +```csharp +// C# 14のfieldキーワードを使用 +public string Name +{ + get; + set => field = value ?? throw new ArgumentNullException(nameof(value)); +} + +// やむを得ず明示的なバッキングフィールドが必要な場合もアンダースコアなし +private string name; + +public string Name +{ + get => name; + set => name = value ?? throw new ArgumentNullException(nameof(value)); +} +``` + +悪い例: + +```csharp +// アンダースコアプレフィックスは絶対に禁止 +private string _name; + +public string Name +{ + get => _name; + set => _name = value ?? throw new ArgumentNullException(nameof(value)); +} +``` + +### Null-Conditional Assignment + +- `?.`を使用してnullチェックを簡潔に記述する +- 冗長なnullチェックを削減する + +良い例: + +```csharp +customer?.Order = GetCurrentOrder(); +``` + +悪い例: + +```csharp +if (customer != null) +{ + customer.Order = GetCurrentOrder(); +} +``` + +### Implicit Span Conversions + +- パフォーマンス重視のコードでは`Span`と`ReadOnlySpan`を活用する +- 配列とスパン型の間の自動変換を利用する + +## 命名規則 + +### Pascal Casing + +- 型名（class, record, struct, interface, enum） +- パブリックメンバー（プロパティ、メソッド、イベント） +- 名前空間 + +良い例: + +```csharp +public class CustomerOrder +{ + public string OrderId { get; set; } + public void ProcessOrder() { } +} +``` + +### Camel Casing + +- ローカル変数 +- メソッドパラメータ +- プライベートフィールド（**アンダースコアプレフィックスは絶対に使用しない**） + +良い例: + +```csharp +public class OrderProcessor +{ + // アンダースコアなし + private string customerName; + + // アンダースコアなし + private int orderCount; + + public void ProcessOrder(string orderId) + { + var customerName = GetCustomerName(orderId); + string processedResult = Process(customerName); + } +} +``` + +悪い例: + +```csharp +public class OrderProcessor +{ + // アンダースコアプレフィックスは絶対に禁止 + private string _customerName; + + // アンダースコアプレフィックスは絶対に禁止 + private int _orderCount; +} +``` + +### Interface命名 + +- 接頭辞`I`を使用する + +良い例: + +```csharp +public interface IOrderProcessor +{ + void Process(Order order); +} +``` + +### 型パラメータ命名 + +- 接頭辞`T`を使用する +- 意味のある名前を付ける + +良い例: + +```csharp +public class Repository where TEntity : class +{ + public void Add(TEntity entity) { } +} +``` + +## コードレイアウト + +### インデント + +- スペース4個を使用する +- タブは使用しない + +### 波括弧 + +- Allmanスタイル（開始括弧と終了括弧を別の行に配置） +- **中括弧の省略は絶対に禁止する（1行で記述できる場合でも必ず中括弧を使用）** + +良い例: + +```csharp +public void ProcessOrder(Order order) +{ + if (order != null) + { + order.Process(); + } +} + +// 1行でも中括弧を使用する +if (isValid) +{ + Execute(); +} + +for (int i = 0; i < 10; i++) +{ + Process(i); +} +``` + +悪い例: + +```csharp +// 中括弧の省略は禁止 +if (isValid) + Execute(); + +// 中括弧の省略は禁止 +for (int i = 0; i < 10; i++) + Process(i); + +// 中括弧の省略は禁止 +if (order != null) order.Process(); +``` + +### 行の記述 + +- 1行に1つのステートメントのみ記述する +- 1行に1つの宣言のみ記述する +- メソッド定義とプロパティ定義の間に空行を1行入れる + +良い例: + +```csharp +public class Order +{ + public string OrderId { get; set; } + + public void Process() + { + var result = Validate(); + Execute(result); + } + + private bool Validate() + { + return OrderId != null; + } +} +``` + +### 名前空間 + +- ファイルスコープ名前空間を使用する + +良い例: + +```csharp +namespace YourProject.Orders; + +public class OrderProcessor +{ + // 実装 +} +``` + +悪い例: + +```csharp +namespace YourProject.Orders +{ + public class OrderProcessor + { + // 実装 + } +} +``` + +### using ディレクティブ + +- 名前空間宣言の外側に配置する +- アルファベット順に並べる + +良い例: + +```csharp +using System; +using System.Collections.Generic; +using System.Linq; + +namespace YourProject.Orders; +``` + +## 型と変数 + +### 型指定 + +- 言語キーワード（`string`, `int`, `bool`）を使用する +- ランタイム型（`System.String`, `System.Int32`）は使用しない + +良い例: + +```csharp +string name = "John"; +int count = 10; +bool isValid = true; +``` + +悪い例: + +```csharp +String name = "John"; +Int32 count = 10; +Boolean isValid = true; +``` + +### 型推論（var） + +- 型が代入から明白な場合のみ`var`を使用する +- 組み込み型は明示的に型を記述する + +良い例: + +```csharp +// 明白 +var orders = new List(); + +// 明白 +var customer = GetCustomer(); + +// 組み込み型は明示 +int count = 10; + +// 組み込み型は明示 +string name = "John"; +``` + +悪い例: + +```csharp +// 組み込み型でvarは避ける +var count = 10; + +// 組み込み型でvarは避ける +var name = "John"; +``` + +## 文字列 + +### 文字列補間 + +- 短い文字列の連結には文字列補間を使用する + +良い例: + +```csharp +string message = $"Order {orderId} processed successfully"; +``` + +悪い例: + +```csharp +string message = "Order " + orderId + " processed successfully"; +``` + +### StringBuilder + +- ループ内で大量のテキストを追加する場合は`StringBuilder`を使用する + +良い例: + +```csharp +var builder = new StringBuilder(); +for (int i = 0; i < 1000; i++) +{ + builder.Append($"Line {i}\n"); +} +``` + +### Raw String Literals + +- エスケープシーケンスよりもRaw String Literalsを優先する + +良い例: + +```csharp +string json = """ +{ + "name": "John", + "age": 30 +} +"""; +``` + +## コレクションとオブジェクト初期化 + +### コレクションの初期化 + +- C# 12以降のCollection Expressionsを使用する（前述の「C# 12の最新機能」を参照） + +### オブジェクト初期化子 + +- オブジェクト初期化子を使用して生成を簡潔にする + +良い例: + +```csharp +var customer = new Customer +{ + Name = "John", + Email = "john@example.com" +}; +``` + +## 例外処理 + +### 具体的な例外のキャッチ + +- 一般的な`System.Exception`ではなく具体的な例外をキャッチする + +良い例: + +```csharp +try +{ + ProcessOrder(order); +} +catch (ArgumentNullException ex) +{ + Logger.Error("Order is null", ex); +} +``` + +悪い例: + +```csharp +try +{ + ProcessOrder(order); +} +catch (Exception ex) // 一般的すぎる +{ + Logger.Error("Error", ex); +} +``` + +### usingステートメント + +- try-finallyの代わりに`using`ステートメントを使用する + +良い例: + +```csharp +using var connection = new SqlConnection(connectionString); +connection.Open(); +// 処理 +``` + +悪い例: + +```csharp +SqlConnection connection = null; +try +{ + connection = new SqlConnection(connectionString); + connection.Open(); + // 処理 +} +finally +{ + connection?.Dispose(); +} +``` + +## LINQ + +### 意味のある変数名 + +- クエリ変数には意味のある名前を使用する + +良い例: + +```csharp +var activeCustomers = from customer in customers + where customer.IsActive + select customer; +``` + +### 早期フィルタリング + +- `where`句を使用して早期にデータをフィルタリングする + +良い例: + +```csharp +var result = customers + .Where(c => c.IsActive) + .Select(c => c.Name) + .ToList(); +``` + +### 暗黙的型指定 + +- LINQ宣言では暗黙的型指定を使用する + +良い例: + +```csharp +var query = from customer in customers + where customer.IsActive + select customer; +``` + +## ラムダ式 + +### イベントハンドラ + +- 削除が不要なハンドラにはラムダ式を使用する + +良い例: + +```csharp +button.Click += (s, e) => ProcessClick(); +``` + +### パラメータ修飾子 + +- C# 14の機能を活用して型推論を維持しながら修飾子を使用する + +良い例: + +```csharp +TryParse parse = (text, out result) => int.TryParse(text, out result); +``` + +## コメント + +### 単一行コメント + +- 簡潔な説明には`//`を使用する +- コメント区切り文字の後にスペースを1つ入れる +- **コメントは必ず単独の行に記述する（コードと同じ行には記述しない）** +- コメントの前には空行を1行入れる + +良い例: + +```csharp +// 顧客の注文を処理する +ProcessOrder(order); + +var processor = new OrderProcessor(); + +// 注文を実行する +var result = processor.ProcessOrder(order); +``` + +悪い例: + +```csharp +ProcessOrder(order); // 顧客の注文を処理する（コードと同じ行は禁止） +var result = processor.ProcessOrder(order); // 注文を実行する（コードと同じ行は禁止） +var processor = new OrderProcessor(); +// この行の前に空行がない（悪い例） +var result = processor.ProcessOrder(order); +``` + +### XMLドキュメント + +- パブリックメンバーにはXMLドキュメントを使用する + +良い例: + +```csharp +/// +/// 指定された注文を処理する +/// +/// 処理する注文 +/// 処理結果 +public bool ProcessOrder(Order order) +{ + // 実装 +} +``` + +## 静的メンバー + +### クラス名による呼び出し + +- 静的メンバーはクラス名を介して呼び出す + +良い例: + +```csharp +var result = OrderProcessor.ProcessOrder(order); +``` + +悪い例: + +```csharp +var processor = new OrderProcessor(); + +// 静的メソッドをインスタンス経由で呼び出すのは誤解を招く +var result = processor.ProcessOrder(order); +``` + +## チェックリスト + +### コード作成前 + +- [ ] .NET/C#の最新機能（C# 12/13/14）を把握している +- [ ] プロジェクトのターゲットフレームワークが.NET 8以降に設定されている +- [ ] 命名規則を理解している + +### コード作成中 + +**必須ルール:** + +- [ ] **アンダースコアプレフィックスを絶対に使用していない** +- [ ] **中括弧を省略していない（1行でも必ず使用している）** +- [ ] **コメントは必ず単独の行に記述している（コードと同じ行に記述していない）** +- [ ] **コメントの前に空行を1行入れている** + +**C# 12以降の機能:** + +- [ ] Primary Constructorsを使用している（該当する場合） +- [ ] Collection Expressionsを使用している +- [ ] Default Lambda Parametersを活用している（該当する場合） +- [ ] Alias Any Typeで複雑な型に別名を付けている（該当する場合） + +**C# 13以降の機能:** + +- [ ] Params Collectionsを使用している（該当する場合） +- [ ] New Lock Typeを使用している（スレッド同期が必要な場合） +- [ ] Partial Properties and Indexersを活用している（該当する場合） +- [ ] Implicit Index Accessをオブジェクト初期化子で使用している（該当する場合） + +**C# 14以降の機能:** + +- [ ] `field`キーワードを使用してバッキングフィールドを簡潔に記述している +- [ ] Extension Membersを活用している（該当する場合） +- [ ] Null-Conditional Assignmentを活用している +- [ ] Lambda Parameters with Modifiersを使用している（該当する場合） + +**基本規則:** + +- [ ] ファイルスコープ名前空間を使用している +- [ ] 言語キーワード（`string`, `int`）を使用している +- [ ] `var`を適切に使用している（型が明白な場合のみ） +- [ ] 文字列補間を使用している +- [ ] Raw String Literalsを使用している（該当する場合） +- [ ] Object Initializersを使用している +- [ ] `using`ステートメントを使用している +- [ ] 具体的な例外をキャッチしている +- [ ] LINQ式で早期フィルタリングを実施している +- [ ] 意味のある変数名を使用している +- [ ] コメントが簡潔で明確である +- [ ] パブリックメンバーにXMLドキュメントを記述している +- [ ] Allmanスタイルで波括弧を配置している +- [ ] インデントにスペース4個を使用している + +### コード作成後 + +- [ ] コードが一貫したスタイルで記述されている +- [ ] .NET 8以降の最新機能（C# 12/13/14）を活用している +- [ ] 命名規則に従っている +- [ ] 可読性が高く保守しやすいコードである diff --git a/skills/development-principles/SKILL.md b/skills/development-principles/SKILL.md new file mode 100644 index 0000000..d3b3fdc --- /dev/null +++ b/skills/development-principles/SKILL.md @@ -0,0 +1,229 @@ +--- +name: development-principles +description: 開発における基本原則（曖昧さ禁止、矛盾検出、推察禁止）を定義する。要件定義時、仕様確認時、設計レビュー時、またはユーザーが曖昧な要件、仕様の矛盾、不明点の確認、推測回避に言及した際に使用する。 +--- + +# Development Principles + +## 概要 + +このSkillは、開発を進める上での基本原則を定義する。曖昧さを排除し、矛盾を検出し、推察を避けることで、手戻りとバグを最小化し、開発効率を最大化することを目的とする。 + +## 責任範囲 + +このSkillは以下の範囲をカバーする: + +- 曖昧な状態での開発禁止の原則 +- 矛盾の検出と報告の方法 +- 推察による回答禁止の原則 +- 不明点の確認と明確化のプロセス + +## 基本方針 + +- 仕様や要件が不明確な状態で開発を進めない +- ドキュメント間、仕様間、実装間の矛盾を発見した場合は即座に報告する +- ユーザーの意図や要件を推察せず、明示された情報のみに基づいて回答する +- 不明点があれば必ず質問し、明確化してから作業を開始する + +## 曖昧な状態での開発禁止 + +### 原則 + +仕様、要件、期待される動作が不明確な場合、実装やドキュメント作成を進めず、必ずユーザーに質問する。 + +### 理由 + +曖昧さは手戻りとバグの温床となり、開発効率を著しく低下させる。 + +### 対応方法 + +不明点があれば必ず質問し、明確化してから作業を開始する。 + +### 曖昧さの検出 + +以下の場合は曖昧であると判断する: + +- 仕様や要件が複数の解釈が可能 +- 期待される動作が明示されていない +- 前提条件や制約事項が不明確 +- 用語の定義が曖昧 +- データ形式や範囲が明示されていない + +良い例: + +```text +ユーザー: 「ユーザー管理機能を実装して」 + +応答: 「ユーザー管理機能について、以下のどちらを想定されていますか？ + +A. **ユーザーの登録・編集・削除（CRUD）**: 基本的なユーザー管理機能 +B. **ロールベースのアクセス制御（RBAC）**: 権限管理機能 +C. **両方**: CRUD + RBAC +D. **その他** + +推奨: **C（両方）** +一般的にユーザー管理機能には両方が含まれることが多いため。」 +``` + +悪い例: + +```text +ユーザー: 「ユーザー管理機能を実装して」 + +応答: 「承知しました。ユーザー管理機能を実装します。」 +（曖昧な状態で実装を進めてしまう） +``` + +### 不明確な要件への対応 + +以下のプロセスで対応する: + +1. **曖昧さを検出**: 要件や仕様に不明確な部分がないか確認する +2. **質問を作成**: 不明点を明確にするための質問を作成する +3. **選択肢を提示**: 想定される選択肢を提示し、ユーザーが選びやすくする +4. **確認を得る**: ユーザーからの回答を得て、要件を明確化する +5. **作業を開始**: 明確化された要件に基づいて作業を開始する + +## 矛盾を無視しない + +### 矛盾検出の原則 + +ドキュメント間、仕様間、実装間の矛盾を発見した場合、即座に報告し、解決方法をユーザーに確認する。 + +### 矛盾を放置する影響 + +矛盾を放置すると、後続の開発に悪影響を及ぼし、問題が拡大する。 + +### 矛盾発見時の対応 + +矛盾を発見した時点でユーザーに確認を求める。 + +### 矛盾の検出 + +以下の場合は矛盾があると判断する: + +- ドキュメント間で記述が異なる +- 仕様と実装が一致しない +- 要件定義と設計書の内容が矛盾する +- 複数の制約条件が同時に満たせない +- 前提条件と実装方針が矛盾する + +良い例: + +```text +「要件定義書では『ユーザー登録時にメール認証を必須とする』と記載されていますが、 +設計書では『メール認証はオプション』と記載されています。 +どちらが正しいか確認させてください。 + +A. **メール認証を必須**: 要件定義書の記述が正しい +B. **メール認証はオプション**: 設計書の記述が正しい +C. **その他** + +推奨: **A（メール認証を必須）** +セキュリティの観点から、メール認証を必須とする方が安全なため。」 +``` + +悪い例: + +```text +「要件定義書ではメール認証が必須と記載されていますが、設計書ではオプションと記載されています。 +設計書の方が新しいので、オプションとして実装します。」 +（矛盾を発見したが、確認せずに進めてしまう） +``` + +### 矛盾への対応 + +以下のプロセスで対応する: + +1. **矛盾を検出**: ドキュメント、仕様、実装間の矛盾を発見する +2. **矛盾を報告**: どこに矛盾があるかを明確に報告する +3. **選択肢を提示**: 矛盾を解決するための選択肢を提示する +4. **確認を得る**: ユーザーからの回答を得て、矛盾を解決する +5. **作業を継続**: 矛盾を解決した後、作業を継続する + +## 推察による回答の禁止 + +### 推察禁止の原則 + +ユーザーの意図や要件を推察せず、明示された情報のみに基づいて回答する。ユーザーが明示的に述べていない要件、仕様、または期待される動作を推察して回答・実装しない。過去のやり取りから推測される内容であっても、現在の文脈で明示されていない限り、確認を求める。 + +### 推察による悪影響 + +不正確な情報は誤った意思決定を招き、プロジェクト全体に悪影響を与える。 + +### 不明点への対応方法 + +「わからない」「確認が必要」と明言し、適切な情報源を示す。 + +### 推察が必要な状況の検出 + +以下の場合は推察が必要であると判断する: + +- ユーザーが明示的に述べていない要件や仕様が必要 +- 過去のやり取りから推測される内容がある +- 暗黙の前提条件がある可能性がある +- 類似のケースから推測できる内容がある +- 一般的な慣習や標準があるが、明示されていない + +良い例: + +```text +ユーザー: 「データベースにユーザー情報を保存して」 + +応答: 「ユーザー情報の保存について、以下の点を確認させてください。 + +1. 保存するユーザー情報の項目はどれですか？ + +A. **基本情報のみ**: 名前、メールアドレス、パスワード +B. **基本情報 + プロフィール**: 基本情報に加えて、生年月日、住所、電話番号 +C. **その他** + +推奨: **A（基本情報のみ）** +最小限の情報から始めて、必要に応じて追加する方が安全なため。」 +``` + +悪い例: + +```text +ユーザー: 「データベースにユーザー情報を保存して」 + +応答: 「承知しました。ユーザー情報（名前、メールアドレス、パスワード、生年月日、住所、電話番号）を +データベースに保存します。」 +（ユーザーが明示していない項目を推察して決定してしまう） +``` + +### 推察が必要な場合の対応 + +以下のプロセスで対応する: + +1. **推察が必要な箇所を特定**: ユーザーが明示していない情報を特定する +2. **質問を作成**: 不明点を明確にするための質問を作成する +3. **選択肢を提示**: 想定される選択肢を提示し、ユーザーが選びやすくする +4. **確認を得る**: ユーザーからの回答を得て、情報を明確化する +5. **作業を開始**: 明確化された情報に基づいて作業を開始する + +## チェックリスト + +### 作業開始前 + +- [ ] 仕様や要件が明確に定義されている +- [ ] 期待される動作が明示されている +- [ ] 前提条件や制約事項が明確である +- [ ] 用語の定義が明確である +- [ ] データ形式や範囲が明示されている +- [ ] ドキュメント間、仕様間、実装間に矛盾がない + +### 作業中 + +- [ ] 曖昧な部分を発見した場合、即座に質問している +- [ ] 矛盾を発見した場合、即座に報告している +- [ ] 推察が必要な箇所を特定し、確認を求めている +- [ ] ユーザーの意図や要件を推察せず、明示された情報のみに基づいて作業している +- [ ] 不明点があれば必ず質問し、明確化してから作業を進めている + +### 作業完了後 + +- [ ] 実装が仕様や要件と一致している +- [ ] ドキュメントと実装に矛盾がない +- [ ] 曖昧な部分が残っていない +- [ ] すべての不明点が解決されている diff --git a/skills/documentation-standards/SKILL.md b/skills/documentation-standards/SKILL.md new file mode 100644 index 0000000..942c253 --- /dev/null +++ b/skills/documentation-standards/SKILL.md @@ -0,0 +1,134 @@ +--- +name: documentation-standards +description: Markdownドキュメントの記述規約、スタイルガイド、markdownlint検証ルールを定義する。Markdownファイル作成時、README作成時、ドキュメント編集時、またはユーザーがドキュメント標準、Markdown形式、markdownlint、ドキュメントスタイルに言及した際に使用する。 +--- + +# Documentation Standards + +## 概要 + +このSkillは、作成されるすべてのMarkdownドキュメントに適用される記述標準を定義します。一貫性のあるドキュメント作成を実現し、可読性と保守性を向上させることを目的としています。 + +## 責任範囲 + +このSkillは以下の範囲をカバーします： + +- Markdownドキュメントの記述スタイル（言語、敬体/常体、箇条書き形式など） +- ドキュメント構造と見出しの使用方法 +- 簡潔で明確な文章表現の原則 +- コードとドキュメントの分離方針 +- 用語の統一と一貫性の維持 +- markdownlint-cli2を使用したドキュメント検証プロセス +- 頻出するmarkdownlintルール違反とその対処方法 + +## 基本方針 + +### スタイル + +- 日本語で記述する +- 常体で記述する +- 一貫性のあるドキュメント構造にする +- インデントはスペース2個で統一する +- 絵文字の使用は以下の場合に限定する + - ユーザーから絵文字の使用指示があった場合 + - ドキュメントの見出し（H1〜H3）で視認性を高める目的で使用する場合 +- 絵文字を使用する場合は、見出し（H1〜H3）のみに使用し、本文中では使用しない +- 図は`Mermaid`を使用して作成し、外部画像の埋め込みは避ける + +### 簡潔に記述する + +- 冗長な表現を避け、必要な情報のみを提供する +- 一文を短くし、明確な主語と述語を使用する +- 繰り返しを避け、同じ情報を複数回記載しない +- 箇条書きや表を活用して、情報を整理する +- 情報を削らず、表現を工夫する + +### 要件定義書や仕様書にコード・疑似コードを含めない + +- ドキュメントはあくまで要件や仕様を伝えるものであり、実装コードを含めない +- コード例が必要な場合は、別途コードリポジトリやサンプルコードとして提供する +- コード例をドキュメントに含めると、ドキュメントの保守性が低下し、内容が古くなるリスクがある +- ドキュメントは技術的な詳細よりも、要件や仕様の理解に焦点を当てる + +### 用語の統一 + +- 同じ意味を持つ用語は一貫して同じ表現を使用する +- 専門用語や略語は初出時に定義し、必要に応じて注釈を付ける +- ユーザーが必要だと判断した場合は用語集を作成し、ドキュメント全体で参照できるようにする + +## ドキュメント検証 + +- ドキュメントの作成後、`markdownlint-cli2`を使用してドキュメントを検証する +- ユーザーが明示的に指示をしない限り、`--fix`の自動修正オプションは使用しない +- 次のコマンドでMarkdownファイルを検証する +- markdownlint-cli2がインストールされていない場合は、`npx`を使用して実行する +- パスは相対パスを使用すること + +**検証コマンド例1:** + +```bash +npm markdownlint-cli2 **/*.md +``` + +**検証コマンド例2:** + +```bash +npx markdownlint-cli2 **/*.md +``` + +### 発生頻度の高いエラー + +- 次のルール違反が特に多く発生するため、注意して確認すること + +#### 見出し (Headers) + +- **MD025 (H1は1ファイルに1つ)**: `H1` (#) はファイルの先頭に1回だけ使用する +- **MD001 (レベルは飛ばさない)**: `H1` → `H2` → `H3` のようにレベルを順に使用する +- **MD003 (スタイルの統一)**: `#` スタイル（ATX）に統一する +- **MD022 (前後に空行)**: 見出し（H1以外）の前後に空行を1行入れる +- **MD024 (同一内容の見出し重複禁止)**: 同じテキストの見出しを複数回使用しないようにする + +#### 空行 (Blank Lines) + +- **MD012 (連続した空行は不可)**: 空行は1行だけにする +- **MD031, MD032 (ブロック要素の前後)**: コードブロック、リスト、引用などの前後には空行を1行入れる + +#### リスト (Lists) + +- **MD004 (マーカーの統一)**: 順序なしリストは`-`に統一 +- **MD007, MD005 (インデントの統一)**: リストのインデントはスペース2個に統一 + +#### 書式とスタイル (Formatting) + +- **MD010 (タブ不使用)**: インデントにはタブではなくスペースを使用する +- **MD034 (URLの書式)**: URLは `` のように山括弧で囲む +- **MD047 (ファイル末尾の改行)**: ファイルの末尾は単一の改行で終わらる + +### 除外 + +以下のエラーは無視する: + +- **MD013 (行の長さ)**: 行の長さ上限の設定は無制限とする +- **MD033 (HTML不使用)**: `
` などのインラインHTMLは使用可 + +## チェックリスト + +### ドキュメント作成前 + +- [ ] ドキュメントの目的と対象読者が明確になっている +- [ ] 使用する用語の定義が明確で、一貫性がある +- [ ] ドキュメント構造（見出し階層）が論理的に整理されている + +### ドキュメント作成中 + +- [ ] 日本語・常体で記述しているか +- [ ] 絵文字は見出し（H1〜H3）にのみ使用し、本文中には使用していない +- [ ] 一文が短く、明確な主語と述語を含んでいる +- [ ] 冗長な表現を避け、必要な情報のみを提供している +- [ ] 同じ意味を持つ用語を一貫して使用している +- [ ] 図はMermaidを使用して作成し、外部画像の埋め込みを避けている + +### ドキュメント作成後 + +- [ ] `markdownlint-cli2`を使用してドキュメントを検証した +- [ ] 除外ルール以外のエラーがないか確認した diff --git a/skills/interaction-guidelines/SKILL.md b/skills/interaction-guidelines/SKILL.md new file mode 100644 index 0000000..1715e92 --- /dev/null +++ b/skills/interaction-guidelines/SKILL.md @@ -0,0 +1,639 @@ +--- +name: interaction-guidelines +description: ユーザーとの効果的な対話パターン、質問生成、曖昧さ解消、合意形成、ユーザー負担軽減のガイドラインを定義する。ユーザーに質問する際、要件を確認する際、フィードバックを収集する際、またはユーザーが対話改善、質問方法、確認プロセス、Progressive Disclosureに言及した際に使用する。 +--- + +# Interaction Guidelines + +## 概要 + +このSkillは、すべてのエージェントがユーザーと効果的に対話するための原則とベストプラクティスを定義する。ユーザーの負担を最小限に抑えながら、明確な要件を引き出し、高品質なアウトプットを生成することを目的とする。 + +## 責任範囲 + +このSkillは以下の範囲をカバーする: + +- 明確な指示を引き出すための質問技法 +- 曖昧さの検出と解消方法 +- 想定される誤解パターンとその回避方法 +- 段階的な情報開示（Progressive Disclosure） +- 合意形成とフィードバック収集のタイミング +- ユーザー負担を軽減する対話パターン +- 反復的改善のための対話パターン +- 質問と指示の区別方法 +- 批判的思考と専門的判断の実践 +- ユーザー提案への適切な対応パターン + +## 基本方針 + +- ユーザーの負担を最小限に抑える +- 具体的で明確な指示を優先する +- 推測よりも確認を重視する +- 質問は標準フォーマット（選択肢A/B/C/D + 推奨）を使用する +- 一度の質問は3つまでに制限する +- 段階的にコンテキストを展開する +- 実装前に計画を確認する +- 必要な時にのみ質問する +- 批判的思考と専門的判断を重視する +- 根拠なくユーザーの提案を受け入れない +- 質問と指示を明確に区別する + +## 質問と指示の区別 + +ユーザーの発言が「質問」なのか「指示」なのかを正確に判断する必要がある。 + +### 質問の特徴 + +以下の形式は質問であり、修正指示ではない: + +- 「～の方が良いのでは？」（提案形） +- 「～すべきでは？」（疑問形） +- 「～はどうですか？」（意見を求める形） +- 「～を検討してみては？」（提案形） + +### 指示の特徴 + +以下の形式は指示である: + +- 「～を修正して」（命令形） +- 「～に変更してください」（依頼形） +- 「～を追加して」（命令形） +- 「～してほしい」（依頼形） + +### 質問への適切な応答 + +質問に対しては、以下のプロセスで応答する: + +1. **分析**: 提案内容の技術的妥当性を評価する +2. **判断**: 最適解を専門的視点から判断する +3. **回答**: 判断結果を理由とともに説明する + +良い例: + +```text +ユーザー: 「この関数はクラスメソッドにした方が良いのでは？」 + +応答: 「この関数の使用状況を確認しました。インスタンス状態に依存せず、 +複数箇所から呼び出されているため、クラスメソッドの方が適切です。 +修正してよろしいですか？」 +``` + +悪い例: + +```text +ユーザー: 「この関数はクラスメソッドにした方が良いのでは？」 + +応答: 「承知しました。クラスメソッドに修正します。」 +（質問なのに無条件で受け入れてしまう） +``` + +### 指示への適切な応答 + +指示に対しては、以下のプロセスで応答する: + +1. **確認**: 指示内容を正確に理解する +2. **実行**: 計画を立てて実行する（複雑な場合は計画を提示） + +## 批判的思考と専門的判断 + +ユーザーの提案を盲目的に受け入れるのではなく、専門的視点から評価する責任がある。 + +### 技術的妥当性の評価 + +- ユーザーの提案が技術的に適切かを評価する +- パフォーマンス、保守性、セキュリティへの影響を考慮する +- より良い代替案がある場合は提示する + +### 最適解を提案する責任 + +- 専門家として、単に要求を実行するだけでなく、最適解を提案する +- ユーザーが気づいていない問題点を指摘する +- より効率的、安全、保守しやすいアプローチがあれば提案する + +### 間違いは明確に指摘する + +- ユーザーの提案に問題がある場合は、明確に指摘する +- 理由を説明し、代替案を提示する +- 単に拒否するのではなく、建設的な提案を行う + +良い例: + +```text +ユーザー: 「すべてのエラーはtry-catchで握り潰して、ログだけ出力すれば良いのでは？」 + +応答: 「その方法は以下の問題があります： +1. エラー情報が失われ、デバッグが困難になる +2. 回復可能なエラーと致命的なエラーの区別ができない +3. 呼び出し元が適切なエラー処理を行えない + +代わりに、以下のアプローチを推奨します： +1. 回復可能なエラーはログを出力して処理を継続 +2. 致命的なエラーは再スローして上位で処理 +3. カスタム例外を使用してエラーの種類を明確化 + +この方針で実装してよろしいですか？」 +``` + +悪い例: + +```text +ユーザー: 「すべてのエラーはtry-catchで握り潰して、ログだけ出力すれば良いのでは？」 + +応答: 「承知しました。そのように実装します。」 +（問題のあるアプローチを無批判に受け入れてしまう） +``` + +## ユーザー提案への対応パターン + +ユーザーの提案に対して、状況に応じた適切な対応を行う。 + +### パターン1: 提案が最適な場合 + +ユーザーの提案が技術的に適切で、最適解である場合: + +1. 提案が適切である理由を説明する +2. 修正するか確認する（質問の場合）または修正計画を提示する（複雑な場合） + +良い例: + +```text +ユーザー: 「このループはLINQのWhereとSelectで書き直した方が読みやすいのでは？」 + +応答: 「ご指摘の通りです。LINQを使用することで以下の利点があります： +1. 可読性が向上する +2. 意図が明確になる +3. バグが入りにくい + +修正してよろしいですか？」 +``` + +### パターン2: 複雑な修正が必要な場合 + +ユーザーの提案が適切だが、複雑な修正が必要な場合: + +1. 修正に必要な変更を分析する +2. 修正計画を立てる +3. ユーザーから承認を得る + +良い例: + +```text +ユーザー: 「データベースアクセスを非同期にした方が良いのでは？」 + +応答: 「ご指摘の通り、非同期化によりパフォーマンスが向上します。 +この修正には以下の変更が必要です： + +1. データアクセス層のメソッドをasync/awaitに変更 +2. 呼び出し元すべてをasync対応に修正（約15箇所） +3. 単体テストの非同期対応 +4. デッドロック防止のためConfigureAwait(false)を追加 + +影響範囲が大きいため、段階的に実装することを推奨します。 +この計画で進めてよろしいですか？」 +``` + +### パターン3: 提案が間違っている、または最適でない場合 + +ユーザーの提案に問題がある、またはより良い代替案がある場合: + +1. 問題点を明確に指摘する +2. 理由を説明する +3. 代替案を提示する + +良い例: + +```text +ユーザー: 「パスワードをMD5でハッシュ化すれば良いのでは？」 + +応答: 「MD5は以下の理由により推奨できません： +1. 暗号学的に脆弱であり、レインボーテーブル攻撃に弱い +2. 高速なため、総当たり攻撃が容易 +3. セキュリティ標準（NIST、OWASP）で非推奨 + +代わりに、以下の方法を推奨します： +1. bcryptまたはArgon2を使用（ソルト自動生成、計算コスト調整可能） +2. ワークファクターは現在の推奨値（bcryptで10以上）に設定 + +この方針で実装してよろしいですか？」 +``` + +悪い例: + +```text +ユーザー: 「パスワードをMD5でハッシュ化すれば良いのでは？」 + +応答: 「それはダメです。bcryptを使ってください。」 +（理由の説明がなく、建設的でない） +``` + +## 明確な指示と具体性 + +### 具体的な指示を求める + +- 曖昧な要求よりも具体的な指示の方が高品質なアウトプットを生成できる +- 単に質問するのではなく、想定されるケースを考えて提案する +- 質問は標準フォーマット（選択肢A/B/C/D + 推奨）を使用する +- ユーザーは選択肢から選ぶだけで答えられるため、負担が減る +- 「何を」「いつ」「どのように」を明確にする + +良い例: + +```markdown +1. 要件定義書を作成します。以下の項目を含めることを想定していますが、他に必要な項目はありますか？ + +A. **機能要件のみ**: ユーザーストーリー形式で記述 +B. **機能要件 + 非機能要件**: パフォーマンス、セキュリティを含む +C. **完全版**: 機能要件、非機能要件、制約条件、前提事項を含む +D. **その他** + +推奨: **C（完全版）** +後続のフェーズで必要となる情報を網羅的に記述できるため。 +``` + +悪い例: + +```text +「承知しました。要件定義書を作成します。」 +（具体的な確認をせずに進めてしまう） + +「要件定義書を作成するとのことですが、具体的にどのような項目を含めますか？」 +（単に質問するだけで、提案がない） +``` + +### 期待値を明確にする + +- アウトプットの形式、範囲、品質基準を事前に確認する +- デザインモック、既存のテストケース、参考資料があれば参照する +- 2〜3回の反復で期待値に近づくことを前提とする + +良い例: + +```markdown +1. システム設計書を作成します。以下のどの範囲で作成しますか？ + +A. **基本版**: アーキテクチャ図、コンポーネント構成 +B. **標準版**: 基本版 + データフロー図 +C. **詳細版**: 標準版 + シーケンス図、ER図 +D. **その他** + +推奨: **A（基本版）** +最小限の情報で設計の全体像を把握でき、後から詳細を追加しやすいため。 +``` + +悪い例: + +```text +「システム設計書を作成しました。」 +（範囲を確認せずに進めてしまう） + +「システム設計書を作成します。アーキテクチャ図は必要ですか？データフロー図は？シーケンス図は？」 +（個別に質問するため、ユーザーが組み合わせを考える負担が増える） +``` + +## 事前計画とアプローチ + +### 実装前に計画を提示する + +- コーディングや大きな変更を行う前に、アプローチを提案する +- ユーザーの確認を得てから実装を開始する +- 計画段階で方向性の修正を受け入れる + +良い例: + +```text +1. 現在の業務フローをヒアリングする +2. 課題と改善点を整理する +3. 新しい業務フローを設計する +4. 関係者に確認を取る + +この計画でよろしいでしょうか？ +``` + +## 段階的開示（Progressive Disclosure） + +### コンテキストを段階的に展開する + +- すべての情報を一度に提示しない +- ユーザーの要求に応じて、必要な情報のみを提供する +- 詳細な技術情報は、ユーザーが求めた場合のみ提供する + +良い例: + +```text +「要件を整理しました。各要件の詳細な背景や技術的な実現方法について説明が必要であれば、お知らせください。」 +``` + +悪い例: + +```text +「要件を整理しました。それでは各要件について、背景、技術的な実現方法、代替案について詳しく説明します...（長い説明が続く）」 +``` + +### 必要に応じて深掘りする + +- ユーザーが「なぜ？」や「どのように？」を尋ねた場合のみ、詳細を提供する +- 技術的な背景知識はユーザーのレベルに合わせて調整する +- サマリーを先に提示し、詳細はオプションとする + +## 質問フォーマット + +### 標準フォーマット + +複数の選択肢がある場合は、以下のフォーマットで質問する。 + +**フォーマット構造:** + +```markdown +1. [質問の背景・理由をここに記述] + +A. **[Aの選択肢]**: [Aの説明] +B. **[Bの選択肢]**: [Bの説明] +C. **[Cの選択肢]**: [Cの説明] +D. **その他** + +推奨: **[推奨する選択肢]** +[なぜその選択肢を推奨するのかの具体的な理由] +``` + +**フォーマットの使用例:** + +```markdown +1. 基本方針をどこに記述するかについて検討が必要です。 + +A. **既存の「スタジオ憲章」に統合**: 理念と方針を一箇所に集約できる +B. **新しい「基本方針」ドキュメントを作成**: 方針だけを独立して参照可能 +C. **各ガイドラインの冒頭に記述（現状維持）**: 各ドキュメントで完結する +D. **その他** + +推奨: **B（新しい「基本方針」ドキュメントを作成）** +各ガイドラインの「なぜそうするのか」を一箇所で確認でき、新メンバーのオンボーディング時に最初に読むべき文書として機能するため。 + + +2. Blazorプロジェクトで使用するUIコンポーネントライブラリを選定する必要があります。デザインの統一性と機能の充実度が重要です。 + +A. **MudBlazor**: マテリアルデザインで豊富なコンポーネント、活発なコミュニティ +B. **Radzen Blazor**: 無料で多機能、独自のデザインシステム +C. **Blazorise**: 複数のCSSフレームワークに対応、柔軟性が高い +D. **その他** + +推奨: **A（MudBlazor）** +マテリアルデザインは現代的で認知度が高く、MudBlazorはBlazorコミュニティで最も人気があり、ドキュメントとサンプルが充実しているため。長期的なサポートも期待できる。 +``` + +## 質問のタイミングと頻度 + +### 質問数の制限 + +- 一度の質問は3つまでに制限する +- ユーザーからの回答を得てから、追加の質問をする +- 質問が3つを超える場合は、段階的に分けて質問する + +### 質問は最小限に抑える + +- 一度に複数の選択肢を提示し、ユーザーが一回の応答で決定できるようにする +- 過度な質問はユーザーの負担を増やす +- 自明な決定は自律的に行う + +良い例: + +```markdown +1. プロジェクトの性質から、開発手法を選定する必要があります。 + +A. **ウォーターフォール型**: 計画重視、変更に弱い +B. **アジャイル型**: 柔軟性高い、継続的な調整が必要 +C. **ハイブリッド型**: 両方の利点、管理が複雑 +D. **その他** + +推奨: **B（アジャイル型）** +プロジェクトの性質から、柔軟性を重視する必要があるため。 +``` + +悪い例: + +```text +「プロジェクトを開始しますか？」 +「どの開発手法にしますか？」 +「スプリントは何週間にしますか？」 +「レビュープロセスはどうしますか？」 +（質問が多すぎる） +``` + +### 決定的な選択のみ質問する + +- 技術的な実装の詳細は、標準に従って自律的に決定する +- ビジネスロジック、機能の範囲、優先順位については質問する +- コーディング規約やスタイルについては質問せず、標準に従う + +### 推奨選択肢を明示する + +- 複数の選択肢を提示する際は、推奨する選択肢を明示する +- 推奨理由を簡潔に説明する +- ユーザーが判断しやすいように、各選択肢の利点と欠点を提示する + +良い例: + +```markdown +1. ドキュメント形式を選択する必要があります。 + +A. **Markdown**: シンプル、バージョン管理しやすい +B. **Word**: リッチな表現、バージョン管理が困難 +C. **Confluence**: Wiki形式、共同編集しやすい +D. **その他** + +推奨: **A（Markdown）** +Git管理とシンプルさを重視するため、バージョン管理が容易なMarkdownが最適。 +``` + +## 想定される誤解パターン + +### 範囲の誤解 + +- 「全体構成を作って」と言われた場合、セクション内容まで全部書いてしまう誤解が起きやすい +- 構造のみを求めているのか、内容も含めて求めているのかを確認する + +良い例: + +```markdown +1. 全体構成を作成します。以下のどの範囲で進めますか？ + +A. **見出し構成のみ**: 章立てとセクション名のみ +B. **見出し + 概要**: 各セクションの概要（1〜2行程度）を含む +C. **見出し + 詳細**: 詳細な内容を含む +D. **その他** + +推奨: **A（見出し構成のみ）** +全体の構造を確認してから、詳細を追加する方が効率的なため。 +``` + +悪い例: + +```text +「全体構成を作成します。」 +（そのまま詳細な内容まで書き始めてしまう） +``` + +### 詳細度の誤解 + +- 「概要を作って」と言われた場合、詳細まで書いてしまう誤解が起きやすい +- 求められている詳細度を明確にする + +良い例: + +```markdown +1. 概要を作成します。以下のどのレベルで作成しますか？ + +A. **要約版**: 3〜5行で全体像を説明 +B. **標準版**: 各項目を1段落で説明 +C. **詳細版**: 各項目を複数段落で詳しく説明 +D. **その他** + +推奨: **A（要約版）** +全体像を素早く把握でき、必要に応じて詳細を追加しやすいため。 +``` + +悪い例: + +```text +「概要を作成しました。」 +（詳細な説明を長々と書いてしまう） +``` + +### 例の扱いの誤解 + +- 「例を挙げて」と言われた場合、例で仕様を上書きしてしまう誤解が起きやすい +- 例はあくまで参考であり、仕様本体ではないことを明確にする + +良い例: + +```markdown +1. 例を追加します。以下の形式で追加してよろしいですか？ + +A. **補足的な例**: 仕様は変更せず、理解を助けるための例を追加 +B. **例で仕様を具体化**: 例に基づいて仕様を詳細化 +C. **その他** + +推奨: **A（補足的な例）** +仕様本体を変更せず、例だけを追加する方が安全なため。 +``` + +悪い例: + +```text +「例を追加しました。」 +（例に合わせて仕様本体も書き換えてしまう） +``` + +### 修正範囲の誤解 + +- 「ここを修正して」と言われた場合、関連する他の部分も変更してしまう誤解が起きやすい +- 修正範囲を明確にする + +良い例: + +```markdown +1. セクション3を修正します。以下のどちらで進めますか？ + +A. **指定箇所のみ修正**: セクション3のみを修正 +B. **関連箇所も修正**: 関連する他のセクションも整合性を取るため修正 +C. **その他** + +推奨: **A（指定箇所のみ修正）** +意図しない変更を避け、ユーザーが指定した箇所のみを修正する方が安全なため。 +``` + +悪い例: + +```text +「修正しました。」 +（指定されていない箇所まで変更してしまう） +``` + +## 曖昧さの解消 + +### 曖昧さを検出する + +- 要求に複数の解釈が可能な場合は、明確化を求める +- 「どちらでも良い」という曖昧な回答を避ける +- 具体的な選択肢を提示して、ユーザーが選びやすくする + +良い例: + +```markdown +1. "ユーザー管理機能"について、以下のどちらを想定されていますか？ + +A. **ユーザーの登録・編集・削除（CRUD）**: 基本的なユーザー管理機能 +B. **ロールベースのアクセス制御（RBAC）**: 権限管理機能 +C. **両方**: CRUD + RBAC +D. **その他** + +推奨: **C（両方）** +一般的にユーザー管理機能には両方が含まれることが多いため。 +``` + +悪い例: + +```text +"ユーザー管理機能"を実装します。 +（曖昧な状態で実装を進める） +``` + +### 前提条件を確認する + +- 暗黙の前提がある場合は、それを明示する +- 技術スタック、環境、制約条件を確認する +- 既存システムとの統合要件を確認する + +## 反復的フィードバック + +### 反復を前提とする + +- 最初の実装が完璧である必要はない +- ユーザーからのフィードバックを受けて改善する +- 2〜3回の反復で期待値に到達することを目指す + +### フィードバックを促す + +- アウトプットを提示した後、ユーザーの評価を求める +- 「この方向性で合っていますか？」と確認する +- 修正が必要な部分を特定しやすくする + +良い例: + +```text +「業務フロー図を作成しました。プロセスの流れや判断ポイントについて、修正が必要な部分があれば教えてください。」 +``` + +## チェックリスト + +### 対話開始前 + +- [ ] ユーザーの要求を正確に理解している +- [ ] 曖昧な部分を特定している +- [ ] 必要な質問を事前に整理している + +### 対話中 + +- [ ] 具体的で明確な指示を引き出している +- [ ] 質問を最小限に抑えている（一度の質問は3つまで） +- [ ] 質問は標準フォーマット（選択肢A/B/C/D + 推奨）を使用している +- [ ] 実装前に計画を提示し、確認を得ている +- [ ] 段階的にコンテキストを展開している（Progressive Disclosure） +- [ ] ユーザーの負担を最小限に抑えている +- [ ] 曖昧さを検出し、明確化を求めている +- [ ] 決定的な選択のみ質問している（自明な決定は自律的に行う） +- [ ] 複数の選択肢を提示する際は、推奨選択肢を明示している +- [ ] 技術的な詳細は必要に応じて提供している +- [ ] 反復的フィードバックを前提としている +- [ ] 範囲の誤解（全体構成 vs 詳細内容）を避けている +- [ ] 詳細度の誤解（概要 vs 詳細）を避けている +- [ ] 例の扱いの誤解（補足 vs 仕様上書き）を避けている +- [ ] 修正範囲の誤解（指定箇所のみ vs 関連箇所も）を避けている +- [ ] ユーザーの発言が質問か指示かを区別している +- [ ] ユーザーの提案を批判的に評価している +- [ ] 間違いや問題点を明確に指摘している +- [ ] 複雑な修正の場合は計画を提示している + +### 対話後 + +- [ ] ユーザーからのフィードバックを受けている +- [ ] 必要に応じて改善を行っている diff --git a/skills/issue-management-guidelines/SKILL.md b/skills/issue-management-guidelines/SKILL.md new file mode 100644 index 0000000..10c5e11 --- /dev/null +++ b/skills/issue-management-guidelines/SKILL.md @@ -0,0 +1,336 @@ +--- +name: issue-management-guidelines +description: Issue作成・分類・管理のガイドライン、テンプレート、ラベル運用、ライフサイクル管理を定義する。Issue作成時、バグ報告時、タスク管理時、またはユーザーがIssue、バグレポート、タスク管理、ラベル運用、Issueテンプレートに言及した際に使用する。 +--- + +# Issue Management Guidelines + +## 概要 + +このSkillは、Issueの作成、分類、管理に関するガイドラインを定義する。適切なIssue管理により、タスクの可視化、優先順位付け、進捗管理を効率的に行うことを目的とする。 + +## 責任範囲 + +このSkillは以下の範囲をカバーする: + +- Issue作成時の記述ガイドライン（タイトル、本文、再現手順） +- Issueテンプレートの定義と使用方法 +- Issueの分類とラベル運用ルール +- Issueのライフサイクル管理（作成、割り当て、進捗更新、クローズ） +- Issueのクローズ基準と完了条件 +- IssueとPull Requestの関連付け方法 + +## 基本方針 + +- タイトルは簡潔で具体的にする +- 本文には必要十分な情報を記載する +- AI自動生成署名を記述しない +- 原則として英語で記述する（チームの主要言語が英語以外の場合はその言語の使用を許可） +- プロジェクトにテンプレートがある場合はそちらを優先的に使用する +- 適切なラベルを付けて分類する +- 担当者とマイルストーンを明確にする +- Issueの状態を最新に保つ +- 完了条件を明確にする +- 関連するIssueやPRを相互に参照する + +## Issue作成ガイドライン + +### タイトルの書き方 + +- 簡潔で具体的にする（50文字以内を推奨） +- 実装内容や問題の本質を端的に表現する +- プレフィックスを付けて種類を明示する（任意） + +良い例: + +```text +Implement user authentication feature +Improve product search performance +Fix email input issue on login screen +``` + +悪い例: + +```text +修正 +バグ +機能追加してほしい +エラーが出る +🤖 Generated with [Claude Code](https://claude.com/claude-code) +``` + +### プレフィックスの使用（任意） + +- プロジェクトで統一する場合は、以下のようなプレフィックスを使用する + +```text +feat: 新機能の追加 +fix: バグ修正 +docs: ドキュメント更新 +refactor: リファクタリング +test: テスト追加・修正 +perf: パフォーマンス改善 +chore: ビルドプロセス、ツール設定など +``` + +良い例: + +```text +feat: ユーザープロフィール編集機能を追加 +fix: ログイン時のセッションタイムアウト問題を修正 +docs: API仕様書にエンドポイント説明を追加 +``` + +### 本文の書き方 + +- 背景、目的、詳細を明確にする +- 再現手順（バグの場合）を記載する +- 期待する動作と実際の動作を記載する +- スクリーンショットやログを添付する + +良い例: + +```markdown +## 背景 +ユーザーから商品検索が遅いという報告が複数件寄せられている。 + +## 現状の問題 +商品検索に平均3秒かかっており、ユーザー体験を損なっている。 + +## 目的 +検索クエリの最適化により、応答時間を1秒以内に短縮する。 + +## 詳細 +- 検索対象: 商品名、カテゴリ、タグ +- データ件数: 約10万件 +- 現在のクエリ: 全文検索をループ処理で実施 + +## 期待する改善内容 +- データベースインデックスの追加 +- クエリの最適化 +- キャッシュの導入 +``` + +バグ報告の場合: + +```markdown +## 概要 +ログイン画面でメールアドレスが入力できない。 + +## 再現手順 +1. ログイン画面を開く +2. メールアドレス入力欄をクリックする +3. キーボードで入力を試みる + +## 期待する動作 +メールアドレスが入力できる。 + +## 実際の動作 +入力欄がフォーカスされず、キーボード入力が反映されない。 + +## 環境 +- OS: Windows 11 +- ブラウザ: Chrome 120.0 +- デバイス: PC + +## スクリーンショット +（添付） +``` + +### 完了条件の明記 + +- Issueをクローズする条件を明確にする +- 受け入れ基準（Acceptance Criteria）を記載する + +良い例: + +```markdown +## 完了条件 +- [ ] 商品検索の応答時間が1秒以内になる +- [ ] 既存の検索機能が正常に動作する +- [ ] テストケースが追加される +- [ ] パフォーマンステストに合格する +``` + +## Issueテンプレート + +### テンプレートの種類 + +プロジェクトで以下のテンプレートを用意する: + +- **Bug Report（バグ報告）**: バグや不具合を報告する際に使用 +- **Feature Request（機能要望）**: 新機能の提案や機能改善を要望する際に使用 +- **Task（タスク）**: 開発タスクや作業項目を記録する際に使用 + +### テンプレートの配置 + +- GitHubの場合: `.github/ISSUE_TEMPLATE/` ディレクトリに配置 +- GitLabの場合: `.gitlab/issue_templates/` ディレクトリに配置 +- このSkillの `templates/` ディレクトリにマスターテンプレートを保管 + +### テンプレートの使用方法 + +- Issue作成時に適切なテンプレートを選択する +- テンプレートの各項目を埋める +- 不要な項目は削除するか、N/Aと記載する + +## Issueの分類とラベル + +### ラベルの種類 + +以下のカテゴリでラベルを付与する: + +**タイプ（Type）**: + +- `bug`: バグ、不具合 +- `enhancement`: 機能改善 +- `feature`: 新機能 +- `documentation`: ドキュメント関連 +- `refactoring`: リファクタリング +- `test`: テスト関連 +- `chore`: 雑務、ビルド設定など + +**優先度（Priority）**: + +- `priority: critical`: 緊急対応が必要 +- `priority: high`: 高優先度 +- `priority: medium`: 中優先度 +- `priority: low`: 低優先度 + +**ステータス（Status）**: + +- `status: blocked`: ブロックされている +- `status: in progress`: 作業中 +- `status: review`: レビュー待ち +- `status: ready`: 着手可能 + +**その他**: + +- `good first issue`: 初心者向けのIssue +- `help wanted`: 協力者を募集 +- `duplicate`: 重複 +- `wontfix`: 対応しない +- `invalid`: 無効 + +### ラベルの付け方 + +- 必ず1つ以上のタイプラベルを付ける +- 優先度ラベルを付ける（必須ではないが推奨） +- 必要に応じてステータスラベルを付ける + +良い例: + +```text +ラベル: bug, priority: high, status: in progress +``` + +## Issueのライフサイクル管理 + +### Issueの作成 + +- 適切なテンプレートを選択する +- タイトルと本文を記載する +- ラベルを付ける +- 担当者を割り当てる（決まっている場合） +- マイルストーンを設定する（該当する場合） + +### Issueの割り当て + +- 担当者が決まったら、Assigneeに設定する +- 複数人で作業する場合は、全員をAssigneeに追加する +- 担当者が決まっていない場合は、ラベル `help wanted` を付ける + +### Issueの進捗更新 + +- 作業開始時に `status: in progress` ラベルを付ける +- ブロックされている場合は `status: blocked` ラベルを付け、コメントで理由を説明する +- 進捗があればコメントで報告する +- 関連するPRを作成したら、IssueとPRを相互に参照する + +### IssueとPull Requestの関連付け + +- PR作成時に、Issue番号を参照する +- PRの説明欄に `Closes #123` や `Fixes #123` と記載すると、PRマージ時に自動的にIssueがクローズされる + +良い例: + +```markdown +## 概要 +ユーザー認証機能を実装しました。 + +Closes #45 +``` + +### Issueのクローズ + +- 完了条件をすべて満たしたらIssueをクローズする +- クローズ時にコメントで完了内容を簡潔に記載する +- 対応しない場合は、理由をコメントで説明し、`wontfix` ラベルを付けてクローズする + +良い例: + +```markdown +すべての完了条件を満たしたため、クローズします。 + +- 商品検索の応答時間: 0.8秒 +- 既存機能のテスト: 合格 +- パフォーマンステスト: 合格 +``` + +対応しない場合: + +```markdown +この機能は現在のスコープ外であり、将来的な検討課題とします。 + +`wontfix` ラベルを付けてクローズします。 +``` + +## Issueのクローズ基準 + +### バグ修正の場合 + +- [ ] バグが修正され、再現しなくなった +- [ ] 修正内容がテストされた +- [ ] 関連するテストケースが追加された +- [ ] PRがマージされた + +### 機能追加の場合 + +- [ ] 機能が実装され、動作確認された +- [ ] テストケースが追加された +- [ ] ドキュメントが更新された +- [ ] PRがマージされた + +### タスクの場合 + +- [ ] タスクが完了した +- [ ] 成果物が確認された +- [ ] 関連する作業がすべて完了した + +## チェックリスト + +### Issue作成時 + +- [ ] タイトルが簡潔で具体的である +- [ ] 本文に必要十分な情報が記載されている +- [ ] 英語で記述している（チームの主要言語が英語以外の場合はその言語でOK） +- [ ] AI自動生成署名を含めていない +- [ ] 適切なテンプレートを使用している（プロジェクトにテンプレートがある場合はそちらを優先） +- [ ] ラベルが付けられている（最低1つ） +- [ ] 完了条件が明記されている +- [ ] 担当者が割り当てられている（決まっている場合） +- [ ] マイルストーンが設定されている（該当する場合） + +### Issue作業中 + +- [ ] 作業開始時に `status: in progress` ラベルを付けた +- [ ] ブロックされている場合は `status: blocked` ラベルを付け、理由をコメントした +- [ ] 進捗があればコメントで報告した +- [ ] 関連するPRを作成し、IssueとPRを相互に参照した + +### Issueクローズ時 + +- [ ] 完了条件がすべて満たされている +- [ ] クローズ時にコメントで完了内容を記載した +- [ ] 対応しない場合は、理由を説明し `wontfix` ラベルを付けた +- [ ] 重複の場合は、元のIssueを参照し `duplicate` ラベルを付けた diff --git a/skills/issue-management-guidelines/templates/bug-report.md b/skills/issue-management-guidelines/templates/bug-report.md new file mode 100644 index 0000000..72c6b3a --- /dev/null +++ b/skills/issue-management-guidelines/templates/bug-report.md @@ -0,0 +1,49 @@ +--- +name: Bug Report +about: バグや不具合を報告する +title: '[Bug] ' +labels: bug +assignees: '' +--- + +## 概要 + +バグの概要を簡潔に記載してください。 + +## 再現手順 + +バグを再現するための手順を記載してください。 + +1. 〇〇画面を開く +2. 〇〇ボタンをクリックする +3. 〇〇を入力する +4. エラーが発生する + +## 期待する動作 + +本来どのように動作するべきかを記載してください。 + +## 実際の動作 + +実際にどのように動作したかを記載してください。 + +## 環境 + +- OS: [例: Windows 11, macOS 14, Ubuntu 22.04] +- ブラウザ: [例: Chrome 120.0, Safari 17.0, Firefox 121.0] +- デバイス: [例: PC, スマートフォン, タブレット] +- その他: [関連する環境情報があれば記載] + +## スクリーンショット・ログ + +該当する場合は、スクリーンショットやエラーログを添付してください。 + +## 補足情報 + +その他、参考になる情報があれば記載してください。 + +## 完了条件 + +- [ ] バグが修正され、再現しなくなる +- [ ] 修正内容がテストされる +- [ ] 関連するテストケースが追加される diff --git a/skills/issue-management-guidelines/templates/feature-request.md b/skills/issue-management-guidelines/templates/feature-request.md new file mode 100644 index 0000000..cd5d76b --- /dev/null +++ b/skills/issue-management-guidelines/templates/feature-request.md @@ -0,0 +1,37 @@ +--- +name: Feature Request +about: 新機能の提案や機能改善を要望する +title: '[Feature] ' +labels: feature +assignees: '' +--- + +## 概要 + +提案する機能の概要を簡潔に記載してください。 + +## 背景・課題 + +この機能が必要な背景や、解決したい課題を記載してください。 + +## 提案内容 + +具体的にどのような機能を実装したいかを記載してください。 + +## 期待する効果 + +この機能を実装することで得られる効果やメリットを記載してください。 + +## 代替案 + +検討した代替案があれば記載してください。 + +## 参考資料 + +関連する資料やリンクがあれば記載してください。 + +## 完了条件 + +- [ ] 機能が実装され、動作確認される +- [ ] テストケースが追加される +- [ ] ドキュメントが更新される diff --git a/skills/issue-management-guidelines/templates/task.md b/skills/issue-management-guidelines/templates/task.md new file mode 100644 index 0000000..a111f13 --- /dev/null +++ b/skills/issue-management-guidelines/templates/task.md @@ -0,0 +1,40 @@ +--- +name: Task +about: 開発タスクや作業項目を記録する +title: '' +labels: chore +assignees: '' +--- + +## 概要 + +タスクの概要を簡潔に記載してください。 + +## 背景・目的 + +このタスクが必要な背景や目的を記載してください。 + +## 作業内容 + +具体的な作業内容を記載してください。 + +- [ ] 作業項目1 +- [ ] 作業項目2 +- [ ] 作業項目3 + +## 期限 + +該当する場合は、期限を記載してください。 + +## 関連Issue・PR + +関連するIssueやPRがあれば記載してください。 + +- 関連: # +- 依存: # + +## 完了条件 + +- [ ] すべての作業項目が完了する +- [ ] 成果物が確認される +- [ ] 関連する作業がすべて完了する diff --git a/skills/security-guidelines/SKILL.md b/skills/security-guidelines/SKILL.md new file mode 100644 index 0000000..d5bce9c --- /dev/null +++ b/skills/security-guidelines/SKILL.md @@ -0,0 +1,76 @@ +--- +name: security-guidelines +description: セキュアな開発・運用のための実装指針、機密情報管理、通信の確保、入力値検証、依存ライブラリ管理のガイドラインを定義する。セキュリティ実装時、認証・認可実装時、API開発時、またはユーザーがセキュリティ、機密情報、暗号化、XSS対策、SQL injection、脆弱性管理に言及した際に使用する。 +--- + +# Security Guidelines + +## 概要 + +このSkillは、開発されるすべてのソフトウェアにおけるセキュリティの基本原則と具体的な実装指針を定義します。機密情報の管理、通信の暗号化、入力値の検証、依存ライブラリの管理など、開発・運用時に考慮すべきセキュリティ要件をカバーし、脆弱性のリスクを最小化することを目的としています。 + +## 責任範囲 + +このSkillは以下の範囲をカバーします: + +- 機密情報（APIキー、パスワード、秘密鍵）の安全な管理方法 +- HTTPS/SSL/TLSを使用した通信の暗号化 +- 入力値の検証とサニタイズ（SQLI、XSS対策） +- 依存ライブラリの脆弱性管理と定期的な更新 +- エラー処理とログにおける機密情報の取り扱い +- 開発フェーズごとのセキュリティチェックリスト + +## データと機密情報の管理 + +- 機密情報の分離: パスワード、APIキーなどの**機密情報**は、ソースコードに直接記述せず、環境変数や設定ファイルで管理する +- パスワード保存: パスワードは必ず**不可逆なハッシュ化**して保存する +- ローカル保存: 端末内の機密情報は、OS提供の**セキュアストレージ機能**（Keychain/Keystore）を利用する +- ソースコード管理の注意: GitのコミットやGitHubのPRに、設定ファイルや環境変数など**機密情報そのものを含めない** + +## 通信の確保 + +- HTTPSの必須化: 外部との通信はすべて**HTTPS/SSL/TLS**を使用し、暗号化されていないプロトコルは使用しない +- 証明書の検証: サーバー証明書の検証を適切に行い、中間者攻撃を防ぐ + +## 入力値の検証と防御 + +- 入力値の無信頼: ユーザーや外部からの**全ての入力値**は信頼せず、形式、長さ、型を厳密に検証する +- サニタイズ: データベース操作前やHTML表示前に、**エスケープ処理やサニタイズ**（SQLI、XSS対策）を徹底する + +## 依存ライブラリと環境 + +- 定期的な更新: 使用する**すべての外部ライブラリ**やフレームワークは、定期的に最新バージョンに更新し、既知の脆弱性に対応する +- デバッグ機能の削除: デバッグ用コードや不要な機能は、**本番環境から必ず削除**または無効化する + +## エラー処理とログ + +- 機密情報の非公開: エラーメッセージやログに、**機密性の高い内部情報**（接続文字列など）を含めない +- ログの保護: ログは必要な情報のみを記録し、アクセス制限を設けた**安全な場所**に保存する + +## セキュリティチェックリスト + +### ドキュメント作成/計画フェーズ用チェックリスト + +- [ ] 機密情報の取り扱い方法（保存場所、アクセス権など）を明確に定義した +- [ ] 外部APIを利用する場合、利用規約やセキュリティポリシーを確認し、適切なAPIキー管理方法（環境変数など）を決定した +- [ ] 外部通信を行う箇所について、すべてHTTPS/SSL/TLSの使用を計画している +- [ ] パスワードなど機密性の高いデータを保存する場合、ハッシュ化アルゴリズムの採用を決定した +- [ ] 想定される脅威（SQLI、XSSなど）に対する入力値検証・サニタイズの基本方針を定めた + +### コミット/PRフェーズ用チェックリスト + +- [ ] コミットやPRに、**APIキー、秘密鍵、パスワード**などの機密情報そのものが含まれていないことを確認した +- [ ] `.gitignore`または同様の機能で、設定ファイルや環境変数ファイルが誤ってリポジトリに含まれないよう設定されていることを確認した +- [ ] 不要なデバッグ用コード（`console.log`、テスト用認証情報など）が残存していないことを確認した +- [ ] 依存ライブラリのバージョンアップが含まれる場合、既知のセキュリティ脆弱性がないか確認した + +### 実装フェーズ用チェックリスト + +- [ ] ユーザー入力や外部からのデータについて、必ず**形式、長さ、型**の検証とサニタイズ（エスケープ）処理を行っている +- [ ] パスワードの保存に、安全な**不可逆ハッシュ化**を使用している +- [ ] 外部との通信がすべて**HTTPS/SSL/TLS**で行われていることを確認した +- [ ] 端末内の機密情報（認証トークンなど）の保存に、OS提供の**セキュアストレージ機能**を利用している +- [ ] 使用している**外部ライブラリ**が最新バージョンであり、セキュリティパッチが適用されていることを確認した +- [ ] エラーメッセージやログに、DB接続文字列など**機密性の高い内部情報**を含めていない +- [ ] ログファイルが、アクセス制限を設けた**安全な場所**に保存されている +- [ ] デバッグ機能やバックドアとして利用可能なコードを**本番環境から完全に削除**または無効化している diff --git a/skills/version-control-guidelines/SKILL.md b/skills/version-control-guidelines/SKILL.md new file mode 100644 index 0000000..b617cc9 --- /dev/null +++ b/skills/version-control-guidelines/SKILL.md @@ -0,0 +1,453 @@ +--- +name: version-control-guidelines +description: Git運用ガイドライン、ブランチ戦略、コミットメッセージ（Conventional Commits）、プルリクエスト作成、個人開発とチーム開発の使い分けを定義する。Gitコミット作成時、ブランチ作成時、PR作成時、またはユーザーがコミットメッセージ、ブランチ戦略、バージョン管理、Conventional Commits、Semantic Versioningに言及した際に使用する。 +--- + +# Version Control Guidelines + +## 概要 + +このSkillは、Gitを使用したバージョン管理の運用ガイドラインを定義する。Conventional Commits形式のコミットメッセージ、適切なPRレビュープロセス、Semantic Versioningによるリリース管理など、品質を担保しつつ効率的な開発を実現することを目的とする。個人開発ではセルフレビュー可、チーム開発では最低1名のレビュー承認が必要となる。 + +## 責任範囲 + +このSkillは以下の範囲をカバーする: + +- 個人開発とチーム開発の運用方針 +- ブランチ戦略（個人開発・チーム開発別） +- コミットメッセージの記述ルール（Conventional Commits形式） +- プルリクエストのガイドライン +- マージ方針とコンフリクト解決 +- タグとリリース管理（Semantic Versioning） + +## 基本方針 + +### 共通ルール + +以下のルールは個人開発・チーム開発に関わらず適用する: + +- コミットメッセージ、PR、IssueにAI自動生成署名を記述しない +- メッセージは原則として英語で記述する +- チームの主要言語が英語以外の場合はその言語の使用を許可する +- プロジェクトにテンプレートがある場合はそちらを優先的に使用する + +### 個人開発の場合 + +- シンプルなブランチ戦略を採用する +- コミットメッセージはConventional Commits形式で記述する +- セルフレビュー可 +- 素早く実装して素早くリリースする +- ローカルでの実験的な作業を許容する + +### チーム開発の場合 + +- Git Flowブランチ戦略を採用する +- コミットメッセージはConventional Commits形式で詳細に記述する +- 最低1名のレビュー承認が必要 +- 品質とスピードのバランスを取る +- チーム全体でルールを統一する + +## ブランチ戦略 + +### ブランチ戦略: 個人開発の場合 + +シンプルな2ブランチモデルを採用する。 + +**メインブランチ**: + +- `main`: 本番環境にデプロイ可能な状態を保つ + +**作業ブランチ**: + +- `feat/機能名`: 新機能の開発 +- `fix/修正内容`: バグ修正 +- `exp/実験内容`: 実験的な実装（任意） + +**運用フロー**: + +1. `main`から作業ブランチを作成 +2. 作業ブランチで実装 +3. 動作確認後、`main`にマージ +4. 作業ブランチを削除 + +良い例: + +```bash +# 新機能の開発 +git checkout main +git pull +git checkout -b feat/user-auth +# 実装作業 +git add . +git commit -m "ユーザー認証機能を実装" +git push origin feat/user-auth +# mainにマージ（PRは任意） +git checkout main +git merge feat/user-auth +git push origin main +git branch -d feat/user-auth +``` + +### ブランチ戦略: チーム開発の場合 + +Git Flow風のブランチモデルを採用する。 + +**永続ブランチ**: + +- `main`: 本番環境にデプロイされている状態 +- `develop`: 開発中の最新状態（次回リリース候補） + +**一時ブランチ**: + +- `feature/機能名`: 新機能の開発（developから分岐） +- `fix/修正内容`: バグ修正（developから分岐） +- `hotfix/緊急修正内容`: 本番環境の緊急修正（mainから分岐） +- `release/バージョン番号`: リリース準備（developから分岐） + +**運用フロー**: + +1. `develop`から作業ブランチを作成 +2. 作業ブランチで実装 +3. PRを作成してレビュー依頼 +4. レビュー承認後、`develop`にマージ +5. リリース時に`develop`から`release`ブランチを作成 +6. `release`ブランチで最終調整後、`main`と`develop`にマージ +7. `main`にタグを付ける + +良い例: + +```bash +# 新機能の開発 +git checkout develop +git pull +git checkout -b feature/user-profile +# 実装作業 +git add . +git commit -m "feat: ユーザープロフィール編集機能を実装" +git push origin feature/user-profile +# PRを作成してレビュー依頼 +# レビュー承認後、GitHubでマージ +``` + +ホットフィックスの例: + +```bash +# 本番環境の緊急修正 +git checkout main +git pull +git checkout -b hotfix/login-error +# 修正作業 +git add . +git commit -m "fix: ログインエラーを緊急修正" +git push origin hotfix/login-error +# PRを作成して迅速にレビュー +# マージ後、mainとdevelopの両方に反映 +``` + +## コミットメッセージ + +Conventional Commits形式を採用し、詳細な情報を記述する。 + +**基本形式**: + +```text +: + + + +