Michael Okafor

Plan a feature as commit-sized steps before an agent codes it

Have a coding agent plan before coding: assumptions, commit-sized steps with tests, a de-risking order, open questions and what's out of scope.

At a glance

Best for: Developers handing a multi-day feature to Claude Code, Codex or Cursor who want reviewable steps instead of one giant diff.
Tested on: Claude · Opus 5.5
You fill in: featurecontextconstraints
You get: PLAN.md: CSV contact import Assumptions The CSV is UTF-8 with a header row. We'll detect and reject other encodings instead of guessing. Email is… (full result below)

Prompt

Before writing any code, produce an implementation plan for this feature.

Feature: {{feature}}
Codebase context: {{context}}
Constraints: {{constraints}}

Format:

1. Assumptions: numbered, things you're taking as given. I'll correct them.

1. Steps: each one is a single commit that leaves the app working and deployable. For each step give the goal, files touched, the test that proves it works, and a rough size. No step over about 150 changed lines.

1. Order: why this order, and which risk each early step retires.

1. Open questions: at most 5, and only ones whose answers change the design.

1. Out of scope: what you will deliberately not build.

Do not write implementation code in the plan. If you can write files, save it as PLAN.md; otherwise print it. Then wait for my review before starting step 1.

Fill in

{{feature}}: The feature, in a few sentencese.g. Let users import contacts from a CSV (up to 50k rows) with column mapping and a preview
{{context}}: Stack and the relevant parts of the codebasee.g. Rails 8, Postgres, Solid Queue, Hotwire; Contact model with email unique per account
{{constraints}}: Hard requirements and things you won't accepte.g. Must not block web requests; never overwrite existing contacts silently; behind a feature flag

Example input

feature: Let users import contacts from a CSV file (up to 50,000 rows), map CSV columns to contact fields, preview the first rows, then run the import and see a summary of created, updated and skipped rows.
context: Rails 8, Postgres, Solid Queue for background jobs, Hotwire/Turbo for UI, Active Storage configured with S3. Contact model: account_id, email (unique per account), name, phone, company, tags (array).
constraints: Must not block web requests. Existing contacts must never be overwritten silently. Ship behind a Flipper feature flag.

2.3k0

Generated Outputs (1)

3 hours ago

Claude

Opus 5.5

3 hours ago

Generated Output

PLAN.md: CSV contact import

1. Assumptions

1. The CSV is UTF-8 with a header row. We'll detect and reject other encodings instead of guessing.

1. Email is the match key. Rows whose email exists in the account are skipped by default. Updating is an explicit opt-in per import.

1. Rows without a valid email are skipped and reported, not fatal.

1. One import at a time per account.

1. Tags come from a single column, comma-separated.

2. Steps
| # | Commit | Files | Proven by | Size |
|---|---|---|---|---|
| 1 | ContactImport model and migration (status, mapping JSON, counts, error report) + Flipper flag | model, migration, flipper initializer | model spec for state transitions | ~80 |
| 2 | Upload via Active Storage; parse header and first 20 rows | controller, form, CsvPreview service | service spec with fixture CSVs (BOM, quoted commas, empty lines) | ~120 |
| 3 | Column-mapping UI with preview (Turbo frame), saved to the import | views, Stimulus controller | system spec: upload, map, preview renders | ~150 |
| 4 | ContactImportJob: stream rows, validate, batch insert_all of 1,000 rows, skip existing | job, ContactRowBuilder | job spec with a 5k-row fixture; counts match | ~140 |
| 5 | "Update existing" opt-in using upsert_all with a fixed column list | job, form checkbox | spec: without opt-in nothing is changed, with it the mapped fields update | ~60 |
| 6 | Progress and summary page, downloadable CSV of skipped rows with reasons | views, controller | system spec for summary counts | ~100 |
| 7 | Limits: 50k rows and 20 MB, one running import per account | model validation, job guard | specs for each limit | ~50 |

3. Order
The parsing in step 2 is the riskiest part, because real CSVs are messy, so it comes before any UI polish. Step 4 proves the job handles volume without blocking requests before we build the summary page. Overwriting (step 5) is isolated in its own commit so it can be reviewed, or dropped, on its own. Everything sits behind the flag from step 1, so each commit is deployable.

4. Open questions

1. Should skipped duplicates be merged in any way (for example, adding new tags), or left completely untouched?

1. Can non-admin users import?

1. Should imported contacts trigger existing automations, such as welcome emails? That could send 50,000 emails.

5. Out of scope
Excel files, Google Sheets import, custom fields, undoing an import, and deduplicating by phone number.

Waiting for your review before starting step 1.

Why it works

"Each step is a single commit that leaves the app working" is the key constraint. It gives you review points and a clean way to stop halfway if things go wrong. The 150-line cap stops the agent hiding the hard part in one huge step. Asking which risk each early step retires puts messy CSV parsing before the UI. The assumptions list turns silent decisions ("existing contacts are skipped") into things you can veto. The open questions surfaced the 50,000-welcome-emails risk before any code existed.

When not to use it

Don't use it for small or exploratory tasks, where you learn more by building a quick spike and throwing it away. Plans also drift: if step 2 reveals that the assumptions were wrong, ask for an updated plan rather than letting the agent improvise against a stale one. Many agent tools have a built-in plan mode, and this prompt works inside it as the format.

Comments (0)

No comments yet. Be the first to share your thoughts!