cawplan-coding-insights

CawPlan コーディングインサイト

初期設定

cawplan skill check

ワークフロー

ユーザーの依頼内容に応じて、関連するビューを並行して取得します。1 日分の場合は --date、期間を指定する場合は --from／--to を使用します。

ユーザーがプロンプトを指定しない場合、または /cawplan-coding-insights のみを実行した場合は、今日の現在のユーザーのレポートをデフォルトとして使用します。

today="$(date +%F)"
cawplan session my-sessions --date "$today"
cawplan session user-human-inputs --date "$today"

このデフォルトの出力を使用して、今日のユーザー自身のセッション、コスト、トークン、変更されたファイル、および人間による入力のハイライトを要約します。

---

ワークスペースの概要

合計コスト、トークン、アクティブメンバー：

cawplan session overview --from <YYYY-MM-DD> --to <YYYY-MM-DD>

日次推移（コストとトークンの経時変化）：

cawplan session trend --from <YYYY-MM-DD> --to <YYYY-MM-DD>

利用可能なレポート日（日時選択用）：

cawplan session dates

---

コストの内訳項目（ワークスペース全体）

メンバー別：

cawplan session by-member --from <YYYY-MM-DD> --to <YYYY-MM-DD>

AI モデル別（Claude Opus、Sonnet、Haiku など）：

cawplan session by-model --from <YYYY-MM-DD> --to <YYYY-MM-DD>

モデル＋トークン種別別（入力／出力／キャッシュ）：

cawplan session by-model-dimension --from <YYYY-MM-DD> --to <YYYY-MM-DD>

AI コーディングエージェント別（Claude Code、Cursor、Codex など）：

cawplan session by-agent --from <YYYY-MM-DD> --to <YYYY-MM-DD>

git プロジェクト／リポジトリ別：

cawplan session by-project --from <YYYY-MM-DD> --to <YYYY-MM-DD>

CawPlan 製品別（製品とリポジトリのマッピングが必要）：

cawplan session by-product --from <YYYY-MM-DD> --to <YYYY-MM-DD>

すべての内訳コマンドは、ページネーション用の --page-num と --page-size に対応しています。

---

メンバービュー

データのあるすべてのメンバーを一覧表示：

cawplan session members

1 人のメンバーの詳細：

cawplan session member-detail --member <git-username>

個人セッションの詳細表示（概要＋セッション一覧）：

# First resolve your user_id if needed
cawplan users query --email <your-email>

cawplan session my-sessions --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

個人のプロンプト品質の概要：

cawplan session user-human-inputs --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

---

製品の対象判定（coding-insights コントロール）

cawplan products list が返す各製品には、controls 配列（例：["dashboard", "version-plans", "issues-suggestions", "knowledge", "test-suites", "coding-insights"]）があり、その製品で有効な機能を示します。controls に "coding-insights" が含まれる製品にのみコーディングセッションデータがあります。それ以外の製品はすべてこのスキルの対象外として扱い、それらに対して product-* セッションエンドポイントを呼び出してはいけません。

• 単一の製品を特定する場合（cawplan products list --search "<name>"）：空白をトリミングした後、大文字と小文字を区別しない完全一致のアクセシブル名、一意な短縮形／トークン接頭辞との一致、またはユーザーが明示的に確認した候補を受け入れます。指定された製品が見つからない場合、または候補が曖昧な場合は、候補を一覧表示して、どの製品を指しているのかユーザーに確認します。一意でない最も近い名前で代用してはいけません。その後、一致した製品の controls を確認してからクエリを実行します。coding-insights が含まれていない場合は、この製品ではコーディングインサイトが有効になっていないことをユーザーに伝え、product-overview／product-trend などを呼び出さずに終了します。
• チーム名簿または集計を作成する場合（cawplan products list --product_line_id <id>。以下のチーム提出状況のギャップとチームコストの集計で使用）：members.rds を統合したりコストを合計したりする前に、controls に coding-insights がない製品を除外します。その製品の R&D メンバーに「未提出」のフラグを立てたり、コスト合計に含めたりしないでください。そもそもその製品にはセッションデータが存在しません。除外が暗黙にならないよう、除外した製品とその理由を明示します。

---

製品スコープのビュー

製品の unique_id が必要です。最初にそれを特定し、上記のルールに従って coding-insights コントロールがあることを確認します。

cawplan products list --search "<product name>"

製品コストの概要：

cawplan session product-overview --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

製品の日次推移：

cawplan session product-trend --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

製品のメンバー別内訳：

cawplan session product-by-member --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

製品のモデル別内訳：

cawplan session product-by-model --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

製品のプロンプト品質の概要：

cawplan session product-human-inputs --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

---

人間による入力（プロンプト品質）の分析

ワークスペースのプロンプト概要（カテゴリ、トピック、品質）：

cawplan session human-input-summary --from <YYYY-MM-DD> --to <YYYY-MM-DD>

プロンプト品質スコアの分布：

cawplan session human-input-quality --from <YYYY-MM-DD> --to <YYYY-MM-DD>

製品別のプロンプト数と品質：

cawplan session human-input-by-product --from <YYYY-MM-DD> --to <YYYY-MM-DD>

フィルター付きのページ分割されたプロンプト一覧：

cawplan session human-inputs \
  --from <YYYY-MM-DD> --to <YYYY-MM-DD> \
  [--member <name>] \
  [--product <name>] \
  [--category <name>] \
  [--topic <name>] \
  [--q <search text>] \
  [--needs-review] \
  [--limit 25] [--offset 0]

---

セッション会話の詳細表示

cawplan session conversation --entry-id <entry_id>

---

チームの未提出状況（「未提出者は誰か」）

ここでの「チーム」とは、CawPlan の 製品ライン（cawplan product-lines ... — CLI の init プロンプトでは文字どおり「Select CawPlan Team」と表示されます）を指します。「コーディングコミット」とは、アップロードされた AI の日次セッションレポート（cawplan-coding-commit）を指し、git コミットではありません。

名簿はチームの製品から直接取得できるため、ユーザーごとの逆引きは不要です。products list --product_line_id は各製品の members オブジェクトをすでに返しており、members.rds[]（その製品に設定された研究開発／開発メンバー）が、コーディングレポートの提出を期待されるメンバーです。

1. チーム名を product_line_id に解決します（cawplan-product-report のチームワークフローと同様に、ページングして名前で照合します）。

   cawplan product-lines list --page_size 100
   

   空白をトリミングした後の大文字・小文字を区別しない完全一致、一意な短縮形／トークンのプレフィックス一致、または一覧にある候補についてのユーザーによる明示的な確認を必須とします。複数の名前が一致する場合は、ユーザーにどれかを確認します。一意に一致する名前がない場合は、最も近い候補を推測するのではなく、候補を一覧表示してどのチームを指すのか尋ねます。

2. チームの製品を解決し、同じ応答から名簿を作成します。

   cawplan products list --product_line_id <product_line_id>
   

   まず、controls に coding-insights が含まれていない製品を除外します（上記の「製品の適格性」を参照）。除外した製品名を示します。次に、残った製品全体から members.rds[].user_id（表示用の first_name／last_name を含む）を集約したものを名簿とします。残った製品の rds リストが空の場合は、そのことを明示します。その製品でも実際のコーディング活動はあり得ますが、このワークフローでは照合対象となる名簿がないため、未提出が検出されず、見落とされることになります。

3. このスキルの他の箇所と同じ方法で対象日を解決します（today="$(date +%F)"、またはユーザーが指定した正確な日付／期間を使用します。「today」という文字列をそのまま渡してはいけません）。その期間に実際に提出した人を特定します。セッションデータが存在するのは、誰かが cawplan-coding-commit のアップロードフローを実行した場合だけです（この CLI には受動的／自動的な収集機能はありません）。したがって、ここに user_id があれば、その人は単に「アクティブだった」のではなく、提出したことを意味します。

   cawplan session product-sessions --product-id <pid> --date <date>
   # or --from/--to for a range
   

   手順 2 の各製品について一度ずつ実行します。各セッションレコードには user_id が直接含まれているため、結合は不要です。すべての結果の user_id を集約し、これを「提出済み」セットとします。名簿に含まれない user_id が提出済みセットにあれば、それを黙って除外せず、設定された RD 担当ではないメンバーが貢献しているという補足情報として記録します。

4. 差分：名簿（手順 2）から提出済み（手順 3）を差し引くと、その期間の未提出者がわかります。名前を付けて報告します。

---

チームのコスト集計

session のコストコマンドには product_line_id パラメーターがなく、--product-id だけがあります。自分で集計します。

1. 「チームの未提出状況」の手順 1〜2 と同様に、チームを product_line_id とその製品に解決します。先に coding-insights コントロールのない製品を除外します。
2. 残った製品ごとに、次を実行します。

   cawplan session product-overview --product-id <pid> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
   cawplan session product-by-model --product-id <pid> --from <YYYY-MM-DD> --to <YYYY-MM-DD>   # only if the user asked for a model breakdown
   

3. 製品全体のコスト／トークンを合計します。モデル別の内訳は、ユーザーが製品ごとの表示を求めていない限り、製品ごとの表ではなく、同じモデル名の値を製品間で合計します。モデル別の合計が product-overview の合計と一致しない場合（たとえば、モデル別エンドポイントが分類しないモデルの項目がある場合）は、どちらかを黙って選ばず、両方の数値を報告します。常に一致するとは限りません。

チーム内の製品ごとに 1〜2 回の呼び出しが必要です。チームの製品数が異常に多い場合は件数を伝えますが、通常は安価です（ワークスペースのユーザー数ではなく、製品数によって決まります）。

コスト／差分の異常検知（「高コスト、差分が少ない」）

アップロードされたレポートには、コストとともにセッションごとの files_changed／files_added／files_deleted が含まれています。これにより、コストと変更量のバランスが取れていないセッションを検出できます。

1. リクエストから対象範囲を特定します。
   • メンバー1人 → そのメンバーの user_id を解決します（メンバービューと同じ方法です。自分の場合は auth status、他のメンバーの場合は users query --email／--keyword を使います）。次に cawplan session my-sessions --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD> を実行します。session member-detail --member <git-username> ではなく、こちらを使います。実環境で確認したところ、member-detail のセッションごとのレコードには tokens はありますが、cost フィールドがまったくありません。そのため、このランキングのコスト側を評価できません。一方、my-sessions のレコードには cost と files_changed の両方があります。
   • プロダクト1つ → まず上記のプロダクト適格性に従って解決します（controls に coding-insights が含まれていない場合はスキップします）。次に cawplan session product-sessions --product-id <id> を実行します（期間を指定するには --from／--to を追加します）。実環境で確認したところ、このレコードには cost と files_changed の両方が含まれています。
   • ワークスペース全体 → cawplan session members を実行し、メンバーごとに my-sessions --user-id <id> を実行します（上記のメンバーの場合と同じ理由で、member-detail は使いません）。この方法は実際にワークスペースのメンバー数に応じて呼び出し回数が増えます。ユーザーごとのループではなく、products list からロスターを直接読み取る Team Submission Gap とは異なります。呼び出し回数をユーザーに伝え、約30回を超える呼び出しを実行する前に、明示的な許可を得てください。
2. 固定のコストや差分のしきい値（例：「コスト > $50」）を作らないでください。組織の通常の範囲はわかりません。代わりに、取得したセッションをコストの降順と files_changed の昇順で順位付けし、両方の方向で同時に突出しているセッションを提示します。結果が少ない場合（おおよそ10件未満）は、厳密な四分位のしきい値を無理に適用しないでください。わずかな差で明らかな外れ値を機械的に除外する可能性があるためです。順位付けを目安として突出したセッションを示し、数値も併記します。また、該当セッションが厳密な四分位の基準にわずかに届かない場合は、その旨を記載します。フラグ付けは取得したデータセット内での相対評価であり、絶対的なしきい値ではないことを明記し、ユーザー自身が判断できるよう、実際のコストと files_changed の数値を示してください。
3. files_changed が0のセッションを、確認せずに自動的に疑わしいと判断しないでください。計画、調査、レビューのみなど、正当な非コーディングセッションでも、コストが発生し、差分がない場合があります。異常としてフラグ付けするだけでなく、数値とともにセッションの session_name やプロジェクトがどのようなものかも示してください。

---

コスト増加の検出（メンバー）

1. メンバーを特定します（このスキルの他のメンバー別ビューと同じ方法です）。
2. 長さが同じで、期間が重ならない2つの期間を選びます。ユーザーが指定しない場合は、「直近30日」と「その前の30日」をデフォルトとします。ユーザーが明示的に指定しない限り、遡る期間は最大3か月までにします。

   cawplan session user-trend --user-id <user_id> --from <period1_start> --to <period1_end>
   cawplan session user-trend --user-id <user_id> --from <period2_start> --to <period2_end>
   

3. 2つの期間のコストの増減率を計算します。曖昧な「大幅な増加」ではなく、実際の数値（例：「前の期間比で +340%、$42 → $185」）を報告します。「増加」に該当するかどうかについて、独自の判断基準は適用しません。数値を示し、注目に値するかどうかはユーザーに判断してもらいます。前の期間のコストが $0 の場合、増減率は定義できません。割合を計算したりゼロで除算したりせず、「$0 → $X、この期間に新たな利用あり」のように前後の実額を報告してください。

---

日付範囲のルール

• 「先週」→ --from <last Monday> --to <last Sunday>
• 「今月」→ --from <first of month> --to <today>
• 「今日」／「昨日」→ --date <YYYY-MM-DD> を使います。
• プロンプトが指定されていない場合は、今日の現在のユーザーのレポートをデフォルトとします。
• プロンプトで指標が指定されているものの、日付が省略されている場合は、文面からより広い期間を意図していると判断できない限り、今日をデフォルトとします。
• cawplan session dates を使って、実際にデータが存在する日付を確認します。

出力

依頼内容に応じて、回答を次のように構成してください。

• 概要：合計コスト（$）、合計トークン数、期間中のアクティブなメンバー数。
• 推移：依頼された日数が2日を超える場合、日ごとのコスト表を表示します。
• 上位メンバー：コスト上位5名とトークン数。
• モデル／エージェント別：コスト順に並べ、合計に占める割合を表示します。
• 製品／プロジェクト別：セッション数とコストを一覧表示します。
• プロンプト品質：人間の入力データを取得した場合、カテゴリ別の内訳と品質スコアの分布を表示します。
• 主な所見：注目すべき傾向を1～3件（コストが高い日、最大の貢献者、特異なモデル支出など）。

注記

• by-product を使用するには、製品とリポジトリのマッピングを設定する必要があります（cawplan session product-repos）。
• product-* コマンドには、製品名ではなく unique_id が必要です。

参考資料

• references/CAWPLAN_OPEN_API.md