AgentSkillsCN

suggest-improve

从多角度全面审视整个代码库，从技术难题、架构设计、UI/UX优化，以及产品方向等多个维度出发，提出符合产品理念的改进建议，并以GitHub Issue的形式提交。

SKILL.md
--- frontmatter
name: suggest-improve
description: コードベース全体を多角的にレビューし、技術的課題・アーキテクチャ・UI/UX・プロダクト方向性の観点からプロダクト哲学に沿った改善を提案し、GitHub Issueとして起票する
disable-model-invocation: true

改善提案スキル

このスキルは、コードベース全体を多角的にレビューし、プロダクト哲学に沿った改善提案をGitHub Issueとして起票するワークフローです。

以下のステップを必ず順番通りに実行してください。

ステップ1: 4つの観点から並行してコードベースを分析する

Taskツール（subagent_type=Explore）を使って、以下の**4つのエージェントを同時に（1つのメッセージで）**起動してください。各エージェントにはCLAUDE.mdの内容（特にプロダクト哲学・5つのコア原則）を踏まえた分析を指示してください。

エージェント1: 技術的課題の分析

以下のプロンプトでExploreエージェントを起動してください:

このプロジェクトのコードベース全体を調査し、細かな技術的課題を見つけてください。 以下の観点で分析してください:

  • •パフォーマンスのボトルネック（不要な再レンダリング、非効率なクエリ、メモリリークの可能性など）
  • •エラーハンドリングの不備（未処理のPromise rejection、不適切なtry-catch、エッジケースの未対応など）
  • •型安全性の問題（any型の使用、型アサーションの乱用、不十分な型定義など）
  • •セキュリティ上の懸念（入力値のバリデーション不足、SQLインジェクションの可能性など）
  • •コードの重複や非効率なパターン
  • •依存関係の問題（古いバージョン、不要な依存、脆弱性など）

各課題について以下の形式で報告してください:

  • •課題: 何が問題か
  • •場所: ファイルパスと行番号
  • •影響: どのような悪影響があるか
  • •改善案: 具体的にどう修正すべきか
  • •優先度: 高/中/低

エージェント2: アーキテクチャの分析

以下のプロンプトでExploreエージェントを起動してください:

このプロジェクトのコードベース全体を調査し、アーキテクチャレベルの課題を見つけてください。 以下の観点で分析してください:

  • •ディレクトリ構造とモジュール分割の適切さ
  • •関心の分離（ビジネスロジック、データアクセス、UIの混在など）
  • •データフロー設計（状態管理、props drilling、不必要な複雑さなど）
  • •API設計の一貫性と拡張性
  • •WebSocket/Yjs同期アーキテクチャの堅牢性
  • •テスト戦略（E2Eのみでユニットテストがない点を含む）
  • •エラー回復とレジリエンス（WebSocket切断時の動作など）
  • •スケーラビリティの考慮

各課題について以下の形式で報告してください:

  • •課題: 何が問題か
  • •現状: 現在のアーキテクチャの説明
  • •影響: メンテナンス性やスケーラビリティへの悪影響
  • •改善案: 具体的なアーキテクチャ変更の提案
  • •優先度: 高/中/低

エージェント3: UI/UXの分析

以下のプロンプトでExploreエージェントを起動してください:

このプロジェクトのコードベース全体を調査し、UI/UXの課題を見つけてください。 CLAUDE.mdに記載されたプロダクト哲学（特に「ノイズの排除」「即座に始められる」「ミニマリズム」「ストレスなく使える」）を基準に分析してください。 以下の観点で分析してください:

  • •ユーザーの思考を中断させる要素はないか
  • •開いた瞬間から書き始められるか（初回体験の最適化）
  • •操作のレスポンス速度（体感的な遅延がないか）
  • •エラー時のユーザー体験（ネットワーク切断、同期失敗時など）
  • •アクセシビリティ（キーボードナビゲーション、スクリーンリーダー対応など）
  • •モバイル対応の状況
  • •CSSやスタイリングの一貫性
  • •不要なUI要素や過剰な視覚的ノイズ

各課題について以下の形式で報告してください:

  • •課題: 何が問題か
  • •場所: 関連するコンポーネントやファイル
  • •ユーザー影響: どのようにユーザー体験を損なうか
  • •改善案: 具体的なUI/UX改善の提案
  • •関連するコア原則: 5つのコア原則のどれに該当するか

エージェント4: プロダクト方向性の分析

以下のプロンプトでExploreエージェントを起動してください:

このプロジェクトのコードベース全体とCLAUDE.mdのプロダクト哲学を調査し、プロダクトの方向性に関する提案を行ってください。 プロダクトビジョン「悩むから考えるへ」と5つのコア原則を深く理解した上で分析してください。 以下の観点で提案してください:

  • •現状の機能でプロダクト哲学に十分合致していない部分はないか
  • •プロダクト哲学に沿った新機能の提案（ただし「あったら便利かも」ではなく「これがないと価値が損なわれる」レベルのもの）
  • •現状機能の変更提案（より哲学に沿った形への改善）
  • •ユーザーが「悩む」から「考える」への変化を体験するために不足しているもの
  • •共同編集体験をより自然にするための提案

注意: CLAUDE.mdの「やってはいけないこと」を必ず確認し、機能の肥大化やカスタマイズの追加にならないよう注意してください。

各提案について以下の形式で報告してください:

  • •提案: 何を提案するか
  • •理由: なぜプロダクト哲学に沿っているか
  • •関連するコア原則: どの原則に基づくか
  • •想定される効果: ユーザー体験にどのような改善をもたらすか
  • •実装の概要: 技術的にどう実現するか

ステップ2: 提案内容をグルーピングし、妥当性を検証する

ステップ1で4つのエージェントから返ってきた提案を分析し、以下を行ってください:

  1. •類似する提案をグルーピングする。異なる観点から同じ領域の問題が指摘されている場合はまとめる。
  2. •グルーピングした**各グループにつき1つのTaskエージェント（subagent_type=Explore）を起動し、以下を検討させる。全グループのエージェントを同時に（1つのメッセージで）**起動してください。

各検討エージェントへのプロンプト:

以下の改善提案群について検討してください。

【提案群の内容をここに記載】

以下の2つの観点で評価してください:

1. プロダクト哲学との整合性

CLAUDE.mdの以下の基準で判断してください:

  • •それがなくても目的は達成できないか？ → 達成できるなら、追加しない
  • •説明なしで使い方がわかるか？ → わからないなら、設計を見直す
  • •ユーザーの思考を中断させないか？ → 中断させるなら、やり方を変える
  • •「あったら便利かも」ではなく本当に必要か？

2. トレードオフとデメリットの分析

  • •実施することで失われるものはないか（シンプルさ、パフォーマンス、メンテナンス性など）
  • •実装コストに見合う効果があるか
  • •他の機能や設計に悪影響を及ぼさないか
  • •ユーザーの学習コストが増えないか

判定

各提案について以下のいずれかの判定を下してください:

  • •実施推奨: プロダクト哲学に沿っており、デメリットを上回るメリットがある
  • •条件付き実施: 特定の条件や修正を加えれば実施すべき
  • •見送り: プロダクト哲学に沿わない、またはデメリットがメリットを上回る

ステップ3: 検討結果を集約し、実施計画をまとめる

ステップ2の検討結果を集約し、「実施推奨」と「条件付き実施」の判定を受けた提案のみを対象に、具体的な実施計画をまとめてください。

以下の形式で整理してください:

実施計画

各項目について:

  • •タイトル: 改善内容の簡潔なタイトル
  • •概要: 何をなぜ行うか
  • •カテゴリ: 技術改善 / アーキテクチャ / UI/UX / プロダクト
  • •優先度: 高 / 中 / 低
  • •影響範囲: 変更が及ぶファイルやコンポーネント
  • •条件付きの場合: どのような条件や修正が必要か

ステップ4: 作業を細かな単位に分割する

ステップ3の実施計画を、GitHub Issueとして起票できる粒度の作業単位に分割してください。

各作業単位は以下を満たすようにしてください:

  • •1つのプルリクエストで完結できる規模
  • •他の作業との依存関係が明確
  • •受け入れ条件が具体的

各作業単位について以下の形式で整理してください:

  • •Issueタイトル: 簡潔で分かりやすいタイトル
  • •説明: 何をなぜ行うかの詳細
  • •受け入れ条件: 完了と判断するための具体的な条件（チェックリスト形式）
  • •関連ファイル: 変更対象のファイル一覧
  • •依存関係: 先に完了すべき他の作業があれば記載
  • •ラベル: enhancement / bug / refactor / performance / accessibility など

ステップ5: ADRおよび既存GitHub Issueとの重複確認

5-a: ADR（Architecture Decision Records）の確認

まず、docs/adr/ ディレクトリ内のすべてのADRファイルを読み、過去に検討済み・却下済みの提案がないか確認してください。ADRには、過去に意図的に「実装しない」と判断された機能や設計が記録されています。

ステップ4の各作業単位について、ADRで既に却下・見送りが決定されている内容と重複する場合は、その作業単位を除外してください。

5-b: 既存GitHub Issueとの重複確認

Bashツールで gh issue list --state open --limit 100 を実行し、既存のIssueを確認してください。 ステップ4で作成した各作業単位について、既存Issueと内容が重複していないか確認してください。

重複の判断基準:

  • •同じファイルの同じ問題を指摘している
  • •同じ機能改善を提案している
  • •実装すると既存Issueが不要になる
  • •ADRで既に却下された内容と同じ、または類似している

ステップ6: GitHub Issueの作成・更新

ステップ5の結果に基づき、以下を実行してください:

重複するIssueがある場合

Bashツールで gh issue comment <issue-number> --body "..." を使って、既存Issueに追加情報をコメントしてください。コメントには以下を含めてください:

  • •このレビューで発見された追加情報
  • •より具体的な改善案や影響範囲の情報
  • •関連する他のIssueへの参照

重複するIssueがない場合

Bashツールで gh issue create を使って新しいIssueを作成してください。以下の形式を使用してください:

bash
gh issue create --title "Issueタイトル" --body "$(cat <<'EOF'
## 概要

[何をなぜ行うかの説明]

## 背景

[この改善が必要な理由と、プロダクト哲学との関連]

## 受け入れ条件

- [ ] 条件1
- [ ] 条件2
- [ ] 条件3

## 関連ファイル

- `ファイルパス1`
- `ファイルパス2`

## 依存関係

[先に完了すべきIssueがあれば記載。なければ「なし」]

## 備考

[その他の参考情報]
EOF
)" --label "ラベル"

注意: Issueは1つずつ順番に作成してください。作成後は番号を記録し、依存関係のあるIssueには相互参照を含めてください。

最終出力

すべてのステップが完了したら、以下のサマリーを出力してください:

レビューサマリー

  • •分析で発見された課題の総数
  • •検討の結果実施推奨となった項目数
  • •作成したIssueの一覧（番号とタイトル）
  • •既存Issueにコメントした一覧（番号とタイトル）
  • •特に優先度の高い項目のハイライト