/ ディレクトリ / プレイグラウンド / planning-with-files
● コミュニティ OthmanAdi ⚡ 即起動

planning-with-files

作者 OthmanAdi · OthmanAdi/planning-with-files

Claudeにディスクベースのマークダウンファイル(task_plan.md、findings.md、progress.md)を永続メモリとして使用させ、コンテキストリセット時の状態消失を防ぎます。

Manus AIの3ファイルプランニングパターンを実装するClaude Codeスキルです。インストールすると、Claudeはマルチステップ作業の開始前にtask_plan.mdを自動作成し、発見事項をfindings.mdに記録し、セッション全体を通じてprogress.mdを更新します。ベンチマークでは、マルチステップタスクにおいて未使用時の6.7%に対し96.7%のパス率を達成しています。3ステップ以上または多数のツールコールを伴う作業に最適です。

なぜ使うのか

主な機能

ライブデモ

実際の動作

planning-with-files-skill.replay ▶ 準備完了
0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "planning-with-files-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json
{
  "context_servers": {
    "planning-with-files-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/OthmanAdi/planning-with-files",
          "~/.claude/skills/planning-with-files"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add planning-with-files-skill -- git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方: planning-with-files

数日にわたるリファクタリングを状態を失わずに実行する

👤 Claude Codeでマイグレーションや大規模リファクタリングを行うエンジニア ⏱ ~30 min intermediate

使うタイミング: モノリスの分割、フレームワークのマイグレーション、または複数セッションにまたがる作業を行う場合に使用します。

前提条件
  • スキルを~/.claude/skills/planning-with-filesにクローン済み — git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files
フロー
  1. スキルを明示的に指定して作業を開始する
    We're migrating the auth module from JWT to session cookies. Use the planning-with-files skill to map this out before you start.✓ コピーしました
    → Claudeがコードに触れる前にフェーズ分けされたtask_plan.mdを作成する
  2. Claudeに作業を続行させ、日をまたいで中断・再開する
    Pick up where we left off — read progress.md and continue.✓ コピーしました
    → Claudeがプランを再読み込みし、次のフェーズを正確に把握している
  3. findings.mdで想定外の発見を確認する
    Summarize findings.md — anything that changed the original plan?✓ コピーしました
    → 記録がなければ失われていたであろう発見事項のリスト

結果: コンテキストリセットを乗り越え、実際にレビュー可能な監査証跡を伴うリファクタリング。

注意点
  • 些細な1行の編集にもスキルが呼び出され、オーバーヘッドが発生する — Claudeに「skip planning-with-files, this is a one-shot fix」と伝える
組み合わせ: filesystem · git

永続的な調査ドキュメントを使ってリサーチ調査を実施する

👤 Claudeを使って複数ソースからのリサーチを行うすべてのユーザー ⏱ ~45 min beginner

使うタイミング: Claudeに多数のソースから情報を収集・統合させる場合に使用します。

フロー
  1. リサーチの問いから始める
    Research how modern rate-limiters handle burst traffic. Use planning-with-files — I want findings.md to build up over the session.✓ コピーしました
    → Claudeが検索しながらfindings.mdを段階的に書き込む
  2. 最後に統合レポートを依頼する
    Now synthesize findings.md into a 1-page brief.✓ コピーしました
    → ハルシネーションではなく、永続ノートに基づいたブリーフ

結果: 再利用可能な調査ドキュメントと、それに裏付けられたブリーフ。

注意点
  • findings.mdがノイズで膨らむ — フェーズの区切りでシグナルのみに絞るようClaudeに指示する
組み合わせ: firecrawl · fetch

組み合わせ

他のMCPと組み合わせて10倍の力を

planning-with-files-skill + filesystem

スキルがマークダウンファイルを書き込み、filesystem MCPによりClaudeが同一セッション内でコードも編集可能

Use planning-with-files to plan, then apply the fixes to the repo via filesystem.✓ コピーしました
planning-with-files-skill + git

フェーズの区切りでprogress.mdとfindings.mdをコミットし、マシン間で永続的な記録を残す

End of phase — commit the 3 planning files with a message summarizing what's done.✓ コピーしました

ツール

このMCPが提供する機能

ツール入力呼び出すタイミングコスト
create_plan task description 3ステップ以上のタスクの開始時 0 — local file write
log_finding discovery text リサーチで記録すべき発見があるたび 0
update_progress step completed 重要なツールコールまたはフェーズの完了後 0
resume_session none 同じ作業ディレクトリでのフォローアップセッションの開始時 0

コストと制限

運用コスト

APIクォータ
なし
呼び出しあたりのトークン
少量 — 3ファイルの再読み込みでトークンを消費しますが、通常それぞれ2k未満です
金額
無料 — スキルは純粋なプロンプトとフックスクリプトで構成されています
ヒント
長期プロジェクトで際限なく肥大化しないよう、Claudeに定期的にprogress.mdをトリムさせてください。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管: 認証情報は不要 — スキルは純粋なプロンプトとローカルファイル操作のみです
データ送信先: なし — すべての状態は作業ディレクトリ内のディスクに保持されます

トラブルシューティング

よくあるエラーと対処法

Claudeがスキルを無視してtask_plan.mdを作成しない

プロンプトでスキル名を明示的に指定してください:「use the planning-with-files skill」。クローンが~/.claude/skills/planning-with-filesに正しく配置されていることを確認してください。

確認: ls ~/.claude/skills/planning-with-files/SKILL.md
ツールコール間でフックが発火しない(Hooks not firing)

SKILL.mdのフロントマターが正しいか確認してください。クローンが不完全だった場合は再インストールしてください。

確認: head ~/.claude/skills/planning-with-files/SKILL.md
3つのファイルが誤ってgitにコミットされる

task_plan.md、findings.md、progress.mdを.gitignoreに追加してください。

確認: git check-ignore task_plan.md

代替案

planning-with-files 他との比較

代替案代わりに使う場面トレードオフ
skillforgeプランニングだけでなく、他のスキルを生成するスキルが必要な場合目的が異なる — skillforgeはスキルを構築し、planning-with-filesはタスクを実行する
Native TodoWrite tool軽量なコンテキスト内TODOで十分で、クロスセッションの永続性が不要な場合無料だがコンテキストリセット時に消失する

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る