CarryCtx コアスキル

CarryCtx は、AIコーディングエージェントにファーストクラスのプロジェクト状態とコンテキストの連続性を提供します。タスク管理、細粒度の進捗追跡、チェックポイントスナップショットの作成、ASTコード依存関係グラフの維持、stdio MCPサーバーの実行、ワークフロープリセットの適用、セッション再起動やGit作業ツリー間でのコンテキストのシームレスな保持を実現します。

適用タイミング

以下の場合に CarryCtx コマンドを使用します:

新しいタスクやセッションの開始時: エージェントIDを登録し、セッションを開始、コンテキストを復元します (carryctx resume)。
プロジェクトタスクの管理時: タスクの作成、割り当て、開始、完了、ブロック、キャンセルを行います (carryctx task ...)。
細粒度の進捗追跡時: 構造化された todo、block、risk、note アイテムを記録します。
状態の保存/チェックポイント作成時: セッション終了やフォーカス切り替えの前に、現在の作業進捗、gitステータス、残作業をキャプチャします。
コードグラフの探索時: ASTモジュール依存関係をスキャンし (carryctx graph scan)、Mermaid/DOT/ASCIIダイアグラムをエクスポートします (carryctx graph export)。
AIエージェントツール統合（MCP）: Model Context Protocol stdioサーバー経由でプロジェクトコンテキストをCursor/Windsurf/AGYに公開します (carryctx mcp)。
ワークフローの標準化（プリセット）: プロジェクトワークフローの設計図、コーディングルール、エージェントペルソナを一覧表示、検査、適用します (carryctx preset ...)。
並列タスク作業時: 専用のGit作業ツリーでタスクを作成し分離します (carryctx worktree ...)。
ヘルス状態の診断時: carryctx doctor を実行して、孤立したタスク、欠落しているフック、データベースの問題を検出します。
古いデータの削除時: carryctx project prune を使用して完了タスクをクリーンアップし、データベースを軽量に保ちます。
エージェント分析時: carryctx stats を使用してエージェントセッション時間、タスクメトリクスを監査し、Markdown/CSVレポートをエクスポートします。
コンテンツによる過去の作業検索時: carryctx search "<query>" を使用して、タスク、進捗アイテム、チェックポイント、決定をキーワードで検索します。SQLを手書きしたりコミットメッセージをgrepする必要はありません。

前提条件

CarryCtx CLIをインストールします (cargo install carryctx またはビルド済みバイナリ)。
プロジェクトリポジトリでCarryCtxを初期化します: carryctx init。

クイックリファレンス

アクション	コマンド	目的
エージェント設定	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	エージェントIDを登録
現在のエージェント	`carryctx agent current`	アクティブなエージェントIDを表示
セッション開始	`carryctx session start`	追跡対象の作業セッションを開始
コンテキスト復元	`carryctx resume`	現在のタスク、進捗、次のアクションを取得
タスク作成	`carryctx task create --title "..." [--depends-on CTX-0001]`	新しいタスクを定義
タスク割り当て	`carryctx task claim CTX-0001`	タスクを現在のエージェントに割り当て
タスク編集	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	タスクのタイトル、優先度、説明を更新
タスク開始	`carryctx task start CTX-0001`	タスクを進行中としてマーク
進捗追跡	`carryctx progress <todo	block
チェックポイント	`carryctx checkpoint --done "..." --remaining "..."`	意味的にリッチな状態スナップショットを保存
コードグラフスキャン	`carryctx graph scan`	AST依存関係をSQLiteグラフに抽出
グラフエクスポート	`carryctx graph export --type <mermaid	dot
MCP Stdioサーバー	`carryctx mcp`	6つのエージェントツールを備えたMCP stdioサーバーを起動
プリセット適用	`carryctx preset apply <preset_name>`	ワークフローSOP、ルール、ペルソナを注入
作業ツリー	`carryctx worktree create CTX-0001`	タスク用に分離されたgit作業ツリーを作成
セッション終了	`carryctx session end`	チェックポイント付きでセッションを安全に終了
診断	`carryctx doctor`	プロジェクトの健全性を診断
フックインストール	`carryctx hooks install`	gitコミットごとに自動チェックポイント
データ削除	`carryctx project prune --older-than 30`	古い完了タスクをクリーンアップ
エージェント統計	`carryctx stats [--markdown] [--output file.csv]`	メトリクスを表示し、パフォーマンスレポートをエクスポート
決定	`carryctx decision add --title "..." --task CTX-0001`	アーキテクチャ上の決定を記録
引き継ぎ	`carryctx handoff create --target <agent> --task CTX-0001`	エージェント間で作業を転送
セッション一時停止	`carryctx session pause`	アクティブセッションのタイマーを一時停止
セッション再開	`carryctx session resume`	一時停止したセッションを再開
検索	`carryctx search "" [--type task	progress

出力動作（0.5.2以降）

テキスト出力（デフォルトの --format text）は コンパクト設計: エンティティコマンドはレコードごとに1行の短い行を出力します（Task created: CTX-0321、agent current は名前のみ、リストは display_id、ステータス、切り詰められたタイトル/サマリー）。これによりエージェントのコンテキストを小さく保ちます。完全なレコードが必要な場合:

--verbose（グローバルフラグ）または .carryctx/config.toml の [output] verbose = true で、完全な整形済みレコードを復元します。
--fields display_id,status,summary（グローバルフラグ）またはコマンドごとの [output.fields] テーブルで、テキストとJSONのレコードを許可リストに制限します。
--format json は常に完全なエンベロープを返します。

JSON出力は変更されておらず、マシン間のコントラクトとして機能します: すべての成功はstdoutに単一のエンベロープ、すべてのエラーはstderrに単一のエンベロープとして出力されます。

標準エージェントワークフロー

1. セッション初期化とコンテキスト復元

対話の開始時やエージェント再起動後:

# まだ設定されていない場合はIDを登録
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# セッションを開始し、現在のコンテキストをロード
carryctx session start
carryctx resume

セッションの一時停止と再開:

carryctx session pause    # アクティブセッションを一時停止（タイマー停止）
carryctx session resume   # 一時停止したセッションを再開
carryctx session end      # オプションのチェックポイント付きでセッション終了
carryctx session abandon  # チェックポイントなしでセッション終了

2. コード依存関係分析（グラフサブシステム）

コードを変更したりモジュールをリファクタリングする前:

# 1. コードベースのAST依存関係をスキャン
carryctx graph scan

# 2. 特定のモジュールを中心としたサブグラフをエクスポート
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. モジュールレベルのコンパクトなASCIIアーキテクチャ概要をエクスポート
carryctx graph export --type ascii --compact

3. ワークフロープリセットとルール注入

標準業務手順やコーディングガイドラインを注入:

# 利用可能なワークフロープリセットを一覧表示
carryctx preset list

# 標準バグ修正ワークフロープリセットを現在のプロジェクトに適用
carryctx preset apply workflows/bugfix

4. タスクライフサイクル

# オープンタスクを一覧表示
carryctx task list --status ready

# タスクを割り当てて開始
carryctx task claim CTX-0001
carryctx task start CTX-0001

# 検証後、タスクを完了としてマーク
carryctx task complete CTX-0001

5. 細粒度の進捗追跡

作業が進むにつれて、構造化された進捗アイテムを記録:

carryctx progress todo "認証ミドルウェアの単体テストを書く"
carryctx progress todo "JWTトークン検証を実装"
carryctx progress block "APIエンドポイント仕様の確認待ち"
carryctx progress risk "上流依存関係の破壊的変更"
carryctx progress note "トークン検索の最適化にLRUキャッシュを使用"
# todoを完了としてマーク:
carryctx progress complete PX-0001

6. チェックポイントの作成

セッション終了前、タスク切り替え前、または作業引き継ぎ前に状態を保存:

carryctx checkpoint \
  --done "バックエンド認証エンドポイントを完了" \
  --remaining "フロントエンドログインフォームの統合" \
  --blocker "なし"

7. 作業ツリーの並列性

独立したタスクを同時に進める場合:

carryctx worktree create CTX-0002
# CTX-0002にリンクされた分離された作業ツリーディレクトリに切り替え

7a. 決定と引き継ぎの記録

アーキテクチャ上の決定を記録し、エージェント間で作業を引き継ぎ:

# タスクに関連付けてアーキテクチャ上の決定（ADR）を記録
carryctx decision add --title "ストレージにSQLiteを使用" --task CTX-0001

# 決定を一覧表示または検索
carryctx decision list
carryctx decision search --keyword SQLite

# 決定を新しいもので置き換えられたものとしてマーク
carryctx decision supersede DEC-0001 --by DEC-0002

# 別のエージェントに作業を引き継ぐためのハンドオフを作成
carryctx handoff create --target <agent-ulid> --summary "APIを実装" --task CTX-0001

# ハンドオフを受け入れる、拒否する、閉じる
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "担当外"
carryctx handoff close HO-0001

7b. プロジェクト履歴の全文検索

どのブランチやタスクが触れたかを覚えておく必要なく、コンテンツで過去の作業を見つけます。タスクのタイトル/説明、進捗アイテム、チェックポイントノート、決定を関連性でランク付けして検索:

# すべてを検索
carryctx search "markdown worker protocol"

# 1つのエンティティ種別に絞り込む
carryctx search "retry backoff" --type checkpoint

# 所有タスクのステータスまたは所有者エージェントで絞り込む
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

各ヒットには、所有タスクの表示ID、ステータス、および（既知の場合）作業が行われたブランチが含まれます。関連する作業を開始する前にこれを使用して、既に解決済みの問題の重複を避け、引き継ぎ前に受け取りエージェントに過去の選択を説明する正確なチェックポイントや決定を指し示します。

8. セッション終了とレポート

# 作業セッションを終了
carryctx session end

# PR説明やドキュメント用にプロジェクト統計レポートをエクスポート
carryctx stats --markdown --output /tmp/project_stats.md

9. Model Context Protocol (MCP) 統合

CarryCtxをCursor/Windsurf/AGYに直接フック:

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

公開されるMCPツール:

carryctx_graph_explorer: プロジェクトコンテキストグラフのクエリ、スキャン、エクスポート
carryctx_context_manager: 永続コンテキスト、チェックポイント、状態スナップショットの管理
carryctx_task_manager: プロジェクトタスク、依存関係、優先度の管理
carryctx_progress_tracker: タスク進捗、ノート、ブロッカーの管理
carryctx_decision_logger: アーキテクチャ上の決定レコードの記録と検索
carryctx_project_admin: プロジェクトデータベース、統計、コールドストレージアーカイブ、設定の管理

10. デバッグとトラブルシューティング

構造化されたデバッグログを有効にして問題を診断:

# CarryCtx操作のデバッグログを表示
RUST_LOG=carryctx=debug carryctx task list          # コマンド結果の前にデバッグ出力を確認

# エラーのみ表示
RUST_LOG=error carryctx status

# 診断の実行
carryctx doctor             # プロジェクトの健全性をチェック
carryctx doctor --json      # 機械可読な診断出力

コーディングエージェントのベストプラクティス

開始時は常に carryctx resume を実行: エージェントを現在のタスクと進捗に即座に再指向します。
大規模リファクタリングの前にコードグラフをスキャン: carryctx graph scan で上流依存関係の破損を防止します。
タスクを明示的に割り当てる: 複数のエージェントが同じリポジトリで作業する際の重複実行を防止します。
構造化された進捗アイテムを使用する: 実行手順中に todo、done、block を最新の状態に保ちます。
停止前にチェックポイントを作成: 制御を譲る前や複雑なマルチステップ作業を完了する前に、常にチェックポイントを作成します。
初回使用時またはアップグレード後に carryctx doctor を実行: 実行時エラーが発生する前に設定のギャップを明らかにします。

CarryCtx スキル