AgentSkillsCN

communication-guidelines

明确提示与提案时的必备要素,确保沟通有据可依、清晰明了。

SKILL.md
--- frontmatter
name: communication-guidelines
description: 判断提示・提案時の必須要素を定義。根拠のある明確なコミュニケーションを実現。

Communication Guidelines Skill

目的

判断提示・提案時の必須要素を定義し、根拠のある明確なコミュニケーションを実現する。

使用タイミング

  • 実装方針を提案する時
  • 複数案を提示する時
  • 判断を求められた時
  • 設計の選択肢を説明する時
  • トレードオフを説明する時

判断提示の必須要素

テンプレート

markdown
## [提案内容]

[1-2文で提案の概要]

### 根拠

- [なぜその判断に至ったか]
- [どの情報源/スキルを参照したか]
- [前提条件は何か]

### メリット

- [利点1]: [具体的な説明]
- [利点2]: [具体的な説明]
- [利点3]: [具体的な説明]

### デメリット/リスク

- [欠点1]: [具体的な説明]
- [欠点2]: [具体的な説明]
- [リスク]: [発生可能性と影響度]

### 代替案

**案A: [名前]**
- 特徴: [簡潔な説明]
- 適用場面: [どういう時に有効か]

**案B: [名前]**
- 特徴: [簡潔な説明]
- 適用場面: [どういう時に有効か]

### 推奨

[推奨する案] を推奨します。

理由: [具体的な理由]

実践例

例1: 実装方針の提案

markdown
## キャッシュ戦略の提案

Redis を使用したキャッシュ層の導入を提案します。

### 根拠

- 現在のAPI応答時間: 平均2秒 (うちDB クエリ1.5秒)
- performance-optimization スキルを参照
- 目標: 応答時間を0.5秒以下に

### メリット

- 応答時間の大幅改善: 2秒 → 0.5秒 (75%削減)
- DB負荷の軽減: 読み取りクエリの90%をキャッシュで処理
- スケーラビリティ向上: 水平スケールが容易

### デメリット/リスク

- インフラコストの増加: Redis サーバーが必要
- キャッシュ整合性の管理: 無効化戦略が必要
- 運用の複雑化: キャッシュのモニタリング・デバッグ
- 学習コスト: チームがRedisに不慣れな場合

### 代替案

**案A: DBインデックスの最適化**
- 特徴: 既存インフラのみで対応
- 適用場面: コスト削減優先、改善率30-50%で十分

**案B: マテリアライズドビュー**
- 特徴: DB内で事前集計
- 適用場面: 集計クエリが主、更新頻度が低い

**案C: アプリケーションレベルキャッシュ**
- 特徴: メモリ内キャッシュ (例: Python の lru_cache)
- 適用場面: 単一サーバー、シンプルなキャッシュ

### 推奨

Redis を推奨します。

理由:
- 目標の0.5秒を達成可能
- 将来的なスケールに対応
- キャッシュ戦略の柔軟性が高い

例2: バグ修正アプローチ

markdown
## ログイン失敗バグの修正方針

セッション管理の初期化タイミングを修正する案を提案します。

### 根拠

- systematic-debugging スキルで4フェーズ分析済み
- 原因: セッションIDが生成前に参照される
- 再現率: 100% (ログイン直後のリダイレクト時)

### メリット

- 根本原因の解決: セッション生成を確実に
- 副作用なし: 既存の正常フローに影響なし
- 実装が単純: 5行の修正

### デメリット/リスク

- テストケース追加が必要: セッション初期化のテスト
- リグレッションテスト推奨: 既存のセッション機能全般

### 代替案

**案A: エラーハンドリング追加**
- 特徴: セッションIDなしでもエラーにしない
- 適用場面: 対症療法、根本解決ではない

**案B: リダイレクトを遅延**
- 特徴: セッション生成完了を待つ
- 適用場面: レイテンシの増加が許容される場合

### 推奨

セッション初期化タイミングの修正を推奨します。

理由:
- 根本原因を解決
- シンプルな修正
- パフォーマンス影響なし

コミュニケーションの原則

原則1: 根拠なき提案禁止

text
❌ 悪い例:
"Redisを使いましょう"

✅ 良い例:
"現在のDB クエリ時間が1.5秒なので、Redisキャッシュで
 0.5秒以下に改善できます (performance-optimization参照)"

原則2: メリットだけでなくデメリットも

text
❌ 悪い例:
"この方法は速いです"

✅ 良い例:
"この方法は速いですが (メリット)、
 メモリを多く使います (デメリット)"

原則3: 単一解の押し付け禁止

text
❌ 悪い例:
"この方法でやります"

✅ 良い例:
"案A (速度優先) と案B (メモリ優先) があります。
 現在の要件では案Aを推奨しますが、どちらが良いですか?"

原則4: ユーザーの質問を無視しない

text
❌ 悪い例:
ユーザー: "なぜエラーが出る?"
Claude: "では実装を進めます"

✅ 良い例:
ユーザー: "なぜエラーが出る?"
Claude: "エラーの原因は○○です。理由は△△だからです"

原則5: 不明点は先に確認

text
❌ 悪い例:
"たぶん○○だと思うので、実装します"

✅ 良い例:
"○○の仕様が不明です。
 案1は△△を前提、案2は□□を前提としています。
 どちらが正しいですか?"

質問への対応

質問の優先順位

text
1. ユーザーの質問 (最優先)
2. 提案内容の説明
3. 実装の詳細

質問への回答形式

markdown
## [質問の内容]

### 回答

[明確な回答を1-2文で]

### 理由

[なぜそうなのか]

### 補足

[必要に応じて追加情報]

例: 質問への対応

markdown
質問: "なぜRedisが必要なの? DBじゃダメ?"

## Redisが必要な理由

### 回答

DBだけでは目標の0.5秒応答を達成できないためです。

### 理由

- 現在のDBクエリ時間: 1.5秒
- インデックス最適化後の予測: 1.0秒 (まだ遅い)
- Redisキャッシュ使用時: 0.05秒 (目標達成)

### 補足

もし目標が1秒以下で良ければ、DBインデックス最適化だけで
十分です (コスト削減可能)。どちらが良いですか?

トークン効率化

冗長な表現を避ける

text
❌ 悪い例:
"この方法にはいくつかのメリットがあります。
 まず1つ目のメリットは速度が向上することです。
 2つ目のメリットはメモリ使用量が少ないことです。
 3つ目のメリットは実装が簡単なことです。"

✅ 良い例:
"メリット:
 - 速度向上
 - メモリ効率
 - 実装が簡単"

前置き・後置きを削る

text
❌ 悪い例:
"それでは、ご質問にお答えさせていただきます。
 まず最初に..."

✅ 良い例:
"回答: ○○です"

スキルへの参照で詳細省略

text
❌ 悪い例:
"TDDとは、まずテストを書いて、それから実装して、
 最後にリファクタリングする開発手法で..."

✅ 良い例:
"TDDで実装します (test-driven-development 参照)"

チェックリスト

提案前の確認

text
□ 根拠を明示したか?
□ メリットとデメリット両方を書いたか?
□ 代替案を2-3個示したか?
□ 推奨する案とその理由を明確にしたか?
□ ユーザーの質問に答えたか?
□ 不明点を先に確認したか?
□ 冗長な表現を削ったか?

よくある間違い

間違い1: 「できません」で終わる

text
❌ 悪い例:
"それはできません"

✅ 良い例:
"それは制約Xのため困難ですが、代替案として:
 案A: ○○する (制約Xを回避)
 案B: △△する (要件を緩和)
 どちらが良いですか?"

間違い2: 技術用語の羅列

text
❌ 悪い例:
"Redisのpub/sub機能とlua scriptingを活用し、
 distributed lockingでconsistencyを..."

✅ 良い例:
"Redisで以下を実現:
 - メッセージ配信
 - 排他制御
 - データ整合性"

間違い3: 長すぎる説明

text
❌ 悪い例:
500行の詳細説明

✅ 良い例:
"概要: [50行]
 詳細: 該当スキル参照"

関連スキル

  • brainstorming-design - 複数案の発散
  • pattern-thinking - 思考パターン
  • consultation - 相談準備
  • auto-consultation - 自己対話

まとめ

良いコミュニケーションの3原則

  1. 根拠を示す
  2. メリデメ両方を示す
  3. 代替案を示す

避けるべきこと

  1. 根拠なき提案
  2. 単一解の押し付け
  3. ユーザーの質問無視
  4. 冗長な説明