DEV Community

hao li
hao li

Posted on

Stop rewriting your whole plan: shard it instead

#python #claudecode #ai #productivity

Claude Code's Plan Mode is great at producing thorough plans. It's also great at producing monolithic ones — thirty pages of markdown where changing one bullet means the model rewrites the entire document. If you've ever caught yourself manually splitting a plan into PLAN_1.md, PLAN_2.md files just to keep edits contained, you're not alone. That's the exact workflow I automated with plan-shard.

The pain

A monolith plan has two failure modes:

  1. Feedback is all-or-nothing. You spot a wrong detail in step 4 of 12. The fix requires regenerating (or at least re-emitting) the whole plan, which risks the model "helpfully" rewriting the 11 steps that were fine.
  2. No resume point. Plans are executed top to bottom, but there's no machine-readable notion of "I'm done through step 3, resume at step 4" — so every session starts with re-reading everything.

What plan-shard does

It's a zero-dependency Python CLI with two core moves:

Shard. Feed it the monolith:

plan-shard shard plan.md -o shards/
Enter fullscreen mode Exit fullscreen mode

You get PLAN_001.md … PLAN_00N.md plus a PLAN_INDEX.md. Every shard carries frontmatter with its dependency order and resume index:

---
shard: 3
total: 6
title: "Step 1: Add the Redis client"
source: plan.md
depends_on: [2, 4]
resume_index: 3
status: pending
revisions: []
---
Enter fullscreen mode Exit fullscreen mode

Targeted feedback. Fix one shard without touching the rest:

plan-shard feedback shards/PLAN_003.md \
  --old "app/cache.py" --new "app/caching.py" \
  --note "rename module"
Enter fullscreen mode Exit fullscreen mode

Only that file changes — every other shard stays byte-identical, and the edit is logged in the shard's revisions list. Then track execution with plan-shard done / plan-shard resume.

How the slicing works

The heuristic is deliberately simple: every ## heading starts a new shard (configurable with --level 3). Text before the first heading becomes shard 1; dependencies default to sequential order plus any literal PLAN_XXX references found in a shard's body. No LLM, no API calls, runs offline in milliseconds.

Honest limitations

  • Slicing is heuristic. Plans without consistent headings slice badly; a heading-free plan becomes one shard.
  • --feedback is exact string replacement, not semantic editing. It won't reword surrounding prose or chase cross-shard references for you.
  • Dependency detection is shallow — sequential order plus PLAN_XXX mentions, not a real graph.

Try it 

pip install plan-shard
Enter fullscreen mode Exit fullscreen mode

Source: https://github.com/hahahahahahahahah6/plan-shard (MIT). 24 tests, stdlib only. If your plans keep getting rewritten wholesale, give your feedback a smaller blast radius.

Top comments (0)