claude-collaboration

Claude Code のコラボレーションにおけるベストプラクティス

このスキルでは、チーム環境で Claude Code を効果的に使用し、スキルを通じて共有知識を管理し、AI 支援開発の価値を最大限に高めるためのガイダンスを提供します。

基本原則

1. スキルは成長し続けるドキュメントです - 学びに応じて進化します
2. 知識を明示的に記録します - Claude がスキルを自動更新することはありません
3. すべてのスキルは $CLAUDE_METADATA に置きます - プロジェクト内にローカルのスキルやコマンドは置きません
4. チーム内で知識を共有します - 一元管理されたリポジトリによって一貫性を保てます
5. スキルをバージョン管理します - 変更と改善を追跡できます
6. 更新は慎重に行います - 学んだことすべてを記録する必要はありません

重要：ローカルのスキルやコマンドは置かない

すべてのスキルとコマンドは、個々のプロジェクトディレクトリではなく、必ず $CLAUDE_METADATA リポジトリに置いてください。

次のようにしてはいけません：

# Creating local skill in project
echo "---" > .claude/skills/my-local-skill/SKILL.md

必ず次のようにしてください：

# Create skill in central repo
mkdir -p $CLAUDE_METADATA/skills/project-name
echo "---" > $CLAUDE_METADATA/skills/project-name/SKILL.md

# Then symlink to project
ln -s $CLAUDE_METADATA/skills/project-name .claude/skills/project-name

一元管理が必須である理由：

• バージョン管理：すべてのスキルを1つの git リポジトリで追跡できます
• チームでの共有：全員が同じ知識を使用できます
• 一貫性：プロジェクト間で差異が生じません
• 保守：一度更新すれば、すべてに適用されます
• 見つけやすさ：チーム全員が利用可能なスキルを確認できます

プロジェクト固有のスキルも、中央リポジトリ内の $CLAUDE_METADATA/skills/project-name/ に置きます。

---

スキルの仕組みを理解する

セッション中に起こること

セッション開始時：

• Claude は、現在のディレクトリにあるすべての .claude/skills/ ファイルを読み込みます
• スキルは、セッションのコンテキストとガイドラインを提供します
• スキルの知識が Claude の作業コンテキストに「読み込まれ」ます

セッション中：

• Claude は会話から学習します（一時的な、コンテキスト内での学習です）
• 発見された解決策が適用されるのは、この会話だけです
• 明示的に更新しない限り、スキルは変更されません

セッション終了時：

• 一時的な学習内容はすべて失われます
• スキルはセッション開始時とまったく同じ状態で維持されます
• 次のセッションは新たに始まり、スキルを再度読み込みます

これが意味すること

• スキルはセッションをまたいで保持されます - ディスク上のファイルだからです
• セッション中の学習内容は保持されません - 会話のコンテキスト内にのみ存在します
• スキルは明示的に更新する必要があります - Claude が自動で更新することはありません

---

スキルを更新するタイミング

次の場合は必ずスキルを更新します：

1. 解決策がわかっている問題が繰り返し発生した場合

   • 「このエラーが何度も発生するので、解決方法をここに記載します」
   • トラブルシューティングのセクションに追加します

2. 新しいベストプラクティスが見つかった場合

   • 「--quiet を使うとトークンを85%節約できるので、デフォルトで使用します」
   • 最適化ガイドラインに追加します

3. 標準化が必要な一般的なワークフローがある場合

   • 「チームでは常に Y の前に X を実行します」
   • 標準的な手順に追加します

4. 有効な設定パターンが見つかった場合

   • 「この cron ジョブの設定が、私たちの HPC では最も効果的です」
   • 推奨設定として追加します

5. 重要なアーキテクチャ上の決定があった場合

   • 「グローバルスキルにシンボリックリンクを使うことにしました。その理由は……」
   • 将来参照できるよう、根拠を記録します

次の場合はスキルを更新しません：

1. 一度限りの問題 - 特定の実行や環境に固有のものです
2. 実験的なアプローチ - 有効性が確認されるまで待ちます
3. ユーザー固有の好み - チームのデフォルトにすべき場合を除きます
4. 自明な情報 - すでに別の場所で十分に文書化されています
5. 一時的な回避策 - 恒久化する価値はありません

例：更新するタイミング

シナリオ 1：新しいエラーパターンを発見

Session: "WF8 fails when Hi-C files are missing R2 reads"
Action: ADD to troubleshooting - this will happen again
Rationale: Common issue with known solution

シナリオ 2：一度限りの設定問題

Session: "My personal laptop has Python 3.7, need 3.8"
Action: DON'T ADD to skill - personal environment issue
Rationale: Not relevant to others, not a recurring pattern

シナリオ 3：トークンの最適化を発見

Session: "Using --quiet mode saves 15K to 2K tokens!"
Action: ADD to token efficiency skill
Rationale: Valuable for entire team, significant impact

---

スキルを更新する方法

方法 1：明示的に依頼する（推奨）

User: "We just solved the issue with workflow timeouts in HPC environments.
       Add this to the VGP skill under troubleshooting."

Claude: [Reads current skill, adds new troubleshooting entry, saves file]

方法 2：Claude に更新案を提案してもらう

User: "Based on our work today, what should we add to the VGP skill?"
Claude: [Reviews conversation, suggests additions]
User: "Yes, add those three things."
Claude: [Updates skill file]

方法 3：セッション終了時に要約する

User: "Summarize today's learnings and update the relevant skills."
Claude: [Creates summary, updates multiple skills if needed]

方法 4：定期的に見直す

User: "We've been working on VGP for a month.
       Review our conversation history and suggest skill improvements."
Claude: [Analyzes patterns, suggests updates]

---

スキルの整理パターン

パターン 1：プロジェクト固有のスキル（中央リポジトリ内）

用途： プロジェクト固有の知識（VGP のワークフロー、Galaxy API）

場所： $CLAUDE_METADATA/skills/project-name/（プロジェクトディレクトリ内ではありません）

$CLAUDE_METADATA/
└── skills/
    ├── my-project/              # Project-specific skill
    │   └── SKILL.md
    └── another-project/
        └── SKILL.md

my-project/
└── .claude/
    └── skills/
        └── my-project -> $CLAUDE_METADATA/skills/my-project  # Symlink only!

パターン 2：一般的なスキル（プロジェクト横断）

用途： 一般的な開発プラクティス、ツールに依存しない最適化、チーム全体の標準

場所： $CLAUDE_METADATA/skills/

パターン 3：プロジェクトへのスキルのシンボリックリンク

これが標準パターンです。すべてのプロジェクトでシンボリックリンクを使用し、例外はありません。

# In each project
cd /path/to/project
mkdir -p .claude/skills .claude/commands

# Symlink skills from central repo
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
ln -s $CLAUDE_METADATA/skills/my-project .claude/skills/my-project

# Symlink commands from central repo
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

重要なルール： プロジェクトに含めるのはシンボリックリンクのみです。スキルやコマンドのファイルそのものを配置してはいけません。

パターン 4：補足ドキュメントを含むスキル

skills/skill-name/
├── SKILL.md              # Core concepts and quick reference
├── reference.md          # Detailed technical documentation
├── troubleshooting.md    # Common issues and solutions
├── examples/             # Code examples
└── templates/            # Template files

次の場合に使用します：

• SKILL.md が長くなりすぎている（500 行超）
• 詳細なリファレンス資料がある
• 情報に複数のカテゴリがある（ガイド、トラブルシューティング、例）

ベストプラクティス：

• SKILL.md は 500 行未満に保つ
• 詳細なガイドは補足ファイルに移す
• SKILL.md の末尾で補足ファイルを参照する
• 内容がわかるファイル名を使用する（tips.md ではなく troubleshooting.md）

---

クイックリファレンス

毎日のワークフロー

1. Start session -> Claude reads skills
2. Work on task -> Learn new patterns
3. End session -> "What should we add to skills?"
4. Claude suggests -> You approve/modify
5. Git commit -> Share with team

毎週のメンテナンス

1. Review week's commits
2. Identify patterns across sessions
3. Consolidate related updates
4. Remove outdated info
5. Share changelog with team

毎月のレビュー

1. Audit all skills for conflicts
2. Measure token savings
3. Collect team feedback
4. Major refactoring if needed
5. Update skill documentation

---

まとめ

主な原則：

1. スキルは永続的で、セッションは一時的です
2. スキルは明示的に更新します。Claude が自動更新することはありません
3. すべてのスキルを $CLAUDE_METADATA に配置します。ローカルのスキルやコマンドは一切作成しません
4. 中央リポジトリで git を使用してスキルをバージョン管理します
5. チームでスキルを共有します。一元管理により一貫性が保たれます
6. 定期的にレビューすることで、スキルの価値を保ちます

重要なアーキテクチャルール：

• プロジェクトディレクトリにスキルやコマンドを直接作成してはいけません
• 必ず $CLAUDE_METADATA に作成し、プロジェクトにシンボリックリンクを設定します

プロジェクト固有のスキルも中央リポジトリに配置する必要があります。これにより、次のことが実現します。

• 唯一の信頼できる情報源：重複や不整合が発生しません
• バージョン管理：すべてのスキルを 1 つの git リポジトリで追跡できます
• チームでの共有：全員がすべてのスキルを見つけて利用できます
• 簡単なメンテナンス：一度更新すれば、どこでも反映されます

覚えておいてください： Claude は強力なアシスタントですが、その力を一貫性のある、共有可能で、永続的なものにするのがスキルです。一元管理されたアーキテクチャにより、チームのナレッジを整理し、見つけやすく、メンテナンスしやすい状態に保てます。スキルに投資すれば、チーム全体に大きな利益をもたらします。

---

補足ドキュメント

このスキルには、同じディレクトリに詳細なリファレンスドキュメントが含まれています。

• centralized-repository.md - スキル用の中央リポジトリのセットアップ、移行パターン、チームのワークフロー、ディレクトリ構造の例
• version-control-and-sharing.md - スキルのための Git セットアップ、チームのコラボレーションワークフロー、スキルを共有する 4 つの方法（Git リポジトリ、ネットワークドライブ、コピー方式、ZIP アーカイブ）
• maintenance-and-effectiveness.md - スキルのメンテナンスに関するベストプラクティス、有効性の測定、追跡する指標、解決策とあわせたよくある落とし穴
• advanced-patterns.md - 階層型、条件付き、役割ベースのスキルパターンと、セッション中断時のドキュメント（再開用ドキュメントのテンプレート）

これらのファイルでは、上記の基本概念を補完する詳細な技術情報を提供しています。