Plans in markdown

Chat and Plan mode are great for thinking. A markdown file in the repo is great for seeing the same breakdown at a glance: headings, ordered steps, and notes you can scroll without replaying a long thread.

Put the plan somewhere stable (for example docs/feature-name-plan.md or next to the code it describes). You and Claude both read the same file, so the plan stays the single place to answer “what are we doing, and in what order?”

Why markdown helps

• Structure: Sections and lists make dependencies obvious.
• Diffs: Changes to the plan show up in git like any other doc.
• Reuse: Paste a chunk into a prompt, or point the agent at the file path instead of re-explaining the whole goal.

Task lists and checkboxes

Most agents and editors understand GitHub-style task lists:

## Shipping search

- [ ] Add query param to the API
- [ ] Wire the UI to call it
- [ ] Empty and error states
- [ ] Quick smoke test in the README

As work completes, items flip to - [x]. That gives you a visual progress bar in plain text.

Working with Claude

Tell Claude explicitly to treat the file as the source of truth for the breakdown, and to mark items complete only after the work is done and briefly verified (tests, manual check, or whatever you agree on). For example:

• “Open docs/search-plan.md. Do the next unchecked item only. When it is done, check it off and stop.”
• “Implement steps 1–2 from the plan file, then update the checkboxes to match.”

That keeps each turn focused on one or a few boxes instead of re-loading the entire project story into context.

Example prompt

Open docs/search-plan.md. Do the next unchecked item only: add the query parameter to the API and return typed errors for invalid input. When finished, mark that line [x], leave other boxes alone, and list files you changed.

Picking up later

When context gets long or you start a new session, the plan file is cheap to load: what is checked is done, what is unchecked is next. Claude does not need the whole prior conversation to see how far you got, only the current code plus the plan. You can tighten prompts further with: “Only discuss and edit files related to the first unchecked checkbox.”

You can combine this with AGENTS.md or other team notes: the markdown plan is the checklist for this effort; longer-lived guidance can stay in agent instructions.