mcpField
C
code-trace

code-trace

github.com/laststance開発150 回インストール4 日前に更新
リポジトリ

code-trace について

アプリケーションコードの実行経路を対話形式で追跡するスキルです。HTTP リクエストや関数呼び出しを段階的に説明し、分岐の選択や追跡状態の保存に対応します。外部依存は境界として扱います。

主な機能

  1. 01リクエストと関数の経路を追跡
  2. 02分岐を対話形式で探索
  3. 03ファイルと行番号を示して説明
  4. 04追跡状態の保存と再開
  5. 05外部依存の概要を提示

活用シーン

  1. 01HTTP リクエストから応答まで追跡
  2. 02関数の呼び出し元と呼び出し連鎖を把握
  3. 03中断したコード追跡を再開

MCP 対応

Serena MCP を使ってシンボルを検索し、追跡状態を記憶します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/laststance/skills --skill code-trace

インストール後、Claude Code で/code-traceを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
control-flow-types.md
explanation-style.md
framework-patterns.md
mermaid-templates.md
scripts/
detect-framework.sh
workflows/
trace-function.md
trace-request.md

詳細

Codex 互換性

Codex でこのスキルを実行する場合は、操作を行う前に Claude Code 専用のプリミティブを変換してください。AskUserQuestion は chat/request_user_input に、TodoWrite は update_plan に、Task／TaskCreate／TeamCreate／SendMessage は、利用可能かつ許可されている場合に spawn_agent／send_input／wait_agent に変換します。また、EnterPlanMode／ExitPlanMode は、簡潔なチャットでの計画と明示的な承認に置き換えます。 Read／Write／Edit／Bash／WebSearch／WebFetch は Codex のファイル／シェル／ウェブツールに対応付け、タスクが明示的に Claude Code を対象としていない限り、~/.claude/... のパスは ~/.agents/... または ~/.codex/... に対応付けます。

Cursor 互換性

Cursor Agent でこのスキルを実行する場合は、操作を行う前に Claude Code 専用のプリミティブを変換してください。AskUserQuestion は AskQuestion に、TodoWrite は Cursor の TodoWrite または同等のチェックリストに変換します。Task／TaskCreate／TeamCreate／SendMessage／マルチエージェントのフローは、許可されている場合に Cursor の Task（サブエージェント）、並列の Task、または run_in_background に置き換えます（TeamCreate／SendMessage に完全に一致する機能がない場合があります）。EnterPlanMode／ExitPlanMode は、プランモード（SwitchMode／CreatePlan）と明示的なユーザー承認に置き換えます。 Read／Write／Edit／StrReplace／Bash／web／search／MCP は、Cursor Composer または Agent の同等機能に対応付けます。mcp__server__tool 形式の MCP 名は通常、設定済みのサーバー識別子を使った call_mcp_tool に対応付けます。タスクが明示的に Claude Code を対象としていない限り、~/.claude/... は ~/.cursor/skills/、.cursor/skills/、.cursor/rules/ に対応付けます。

<essential_principles>

コードトレースの仕組み

このスキルは、コードベース内をデバッガーでステップ実行するように対話的にコードの実行経路をたどり、各ステップで詳しい説明を提供します。

原則 1：アプリケーションの境界

トレースするのはアプリケーションコードのみです。外部依存関係（node_modules、vendor/）については、次の対応にとどめます。

  • 何をするものかを要約する
  • 公式ドキュメントへのリンクを示す
  • 内部まで詳しくトレースしない

理由：外部ライブラリは 10 万行を超えることもあります。その内部までトレースすると、コンテキストを浪費し、実際のアプリケーションロジックが見えにくくなります。目的は、ライブラリの内部ではなく、あなたのコードを理解することです。

原則 2：対話的なナビゲーション

条件分岐ごとに、ユーザーが選択できるようにします。

コードパターン表示方法
if/else「経路 A：条件が真」対「経路 B：条件が偽」
switchケースごとに 1 つの選択肢
try/catch「成功経路」対「エラー経路」
async/await呼び出し先の関数をトレースする選択肢

理由：直線的なトレースでは重要な経路を見落とします。対話的なナビゲーションにより、ユーザーは関心のある経路を正確に調べられます。

原則 3：段階的な説明

各ステップには、次の内容を含めます。

  1. 場所：ファイル、行の範囲、関数名
  2. コード：省略せずにソース全体を示す
  3. 内容：コードが何をするかの簡潔な要約
  4. 理由：このステップがフローに存在する理由
  5. 次の処理：次に起こること（分岐がある場合は選択肢）

明確にするため、思考マーカー（🤔🎯⚡📊💡🔐）を使用します。

原則 4：状態の永続化

トレースの状態は Serena Memory に保存され、次のことが可能になります。

  • 中断したトレースの再開
  • 以前の判断地点への巻き戻し
  • 完了したトレースの将来の参照用保存 </essential_principles>
## 何をトレースしますか？
  1. リクエストフローをトレースする - HTTP リクエストの受信からレスポンスまでを追跡します
  2. 関数呼び出しをトレースする - 特定の関数をコードベース内で追跡します
  3. 前回のトレースを再開する - 中断したところから続けます

追加のコンテキストを提供してください：

  • リクエストのトレースの場合：どのエンドポイントですか？（例：「POST /api/users」）
  • 関数のトレースの場合：どの関数ですか？（例：「validateUser」または「src/utils/auth.ts:checkToken」）

続行する前に応答を待ちます。

| 応答 | ワークフロー | |----------|----------| | 1、「request」、「HTTP」、「route」、「API」、「endpoint」、「POST」、「GET」 | `workflows/trace-request.md` | | 2、「function」、「call」、特定の関数名 | `workflows/trace-function.md` | | 3、「resume」、「continue」、「previous」 | `trace_session_*` の Serena メモリを読み込みます |

ワークフローを開始する前に

  1. フレームワークを検出する：scripts/detect-framework.sh を実行して、以下を特定します：

    • Express、Next.js（App/Pages）、Fastify、Hono、NestJS、Koa、または汎用

  2. フレームワークのパターンを読み込む：検出されたフレームワークの references/framework-patterns.md のセクションを読みます

  3. Serena を準備する：以下のために Serena MCP が利用可能であることを確認します：

    • find_symbol() - 関数やハンドラーを検索します
    • find_referencing_symbols() - 呼び出し元を検索します
    • get_symbols_overview() - モジュール構造を把握します
    • write_memory() / read_memory() - 状態を保持します

意図とフレームワークを特定したら、適切なワークフローを読み、その手順に従ってください。

<reference_index>

リファレンス

すべて references/ 内にあります：

ファイル内容
framework-patterns.mdExpress、Next.js、Fastify などのエントリーポイントの検出とリクエストフロー
control-flow-types.mdif/switch/try/ループを対話型の選択肢として提示する方法
explanation-style.md思考マーカー、ステップ形式、要約形式
mermaid-templates.mdトレースの path_history から Mermaid.js フローチャートを生成

</reference_index>

<workflows_index>

ワークフロー

すべて workflows/ 内にあります：

ワークフロー目的
trace-request.mdHTTP リクエストをエントリーからレスポンスまでトレースします
trace-function.md特定の関数の呼び出しチェーンをトレースします

</workflows_index>

<scripts_index>

スクリプト

スクリプト目的
detect-framework.shpackage.json からプロジェクトのフレームワークを自動検出します

使用方法：

./scripts/detect-framework.sh /path/to/project
# Output: express | nextjs-app | nextjs-pages | fastify | hono | nestjs | koa | generic

</scripts_index>

<success_criteria> コードトレースの成功条件：

  • エントリーポイントが正しく特定され、説明されている
  • フレームワークが検出され、適切なパターンが適用されている
  • 少なくとも1つの分岐点が対話型の選択肢として提示されている
  • 外部依存関係が要約されている（詳細にはトレースしない）
  • ユーザーが終端まで進んだ、または停止を選択した
  • 経路履歴が ASCII フローチャート形式で表示されている
  • トレースが完了した場合、Mermaid フローチャートを出力オプションとして提示している
  • 重要な知見が収集され、表示されている
  • ユーザーが保存を選択した場合、トレースの状態を再開に利用できる

</success_criteria>

## 範囲

行うこと：

  • アプリケーションコードをソース全体を表示しながらトレースします
  • 思考マーカーを使って各ステップを説明します
  • 条件分岐を対話型の選択肢として提示します
  • 境界部分で外部依存関係を要約します
  • 再開できるよう、トレースの状態を保持します

行わないこと：

  • node_modules や外部ライブラリの詳細なトレース
  • コードの実行または起動（読み取り専用の分析）
  • ソースファイルの変更
  • 実行時の値についての仮定（すべての分岐を提示します）

コメント

Markdown 対応