# Stop rewriting your whole plan: shard it instead

> Source: <https://dev.to/haoli/stop-rewriting-your-whole-plan-shard-it-instead-goc>
> Published: 2026-10-02 09:56:02+00:00

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**.

A monolith plan has two failure modes:

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

**Shard.** Feed it the monolith:

```
plan-shard shard plan.md -o shards/
```

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: []
---
```

**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"
```

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`.

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.

`--feedback` is exact string replacement, not semantic editing. It won't reword surrounding prose or chase cross-shard references for you.`PLAN_XXX` mentions, not a real graph.

```
pip install plan-shard
```

Source: [https://github.com/hahahahahahahahah6/plan-shard](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.