Developer Prompt Pipeline

A structured 5-step prompting workflow for software developers using AI assistants (Claude, GPT-4, etc.) to go from raw feature request to verified implementation.

Core principle: Replace subjective model-judged gates with concrete artifacts and real tool output. Every step produces a file. Every file is checkable.

Key discipline: What you do between steps matters as much as the prompts themselves. Do not hand triage or task-review decisions to the model.

You write this file yourself. Do not ask the model to produce it. This is your contract with yourself and the model for all subsequent steps.

## Feature / Bug / Task
[One sentence summary]
 
## Context
- What part of the codebase does this touch?
- Why is this needed? (user problem or business reason)
- Any related tickets, PRs, or prior decisions?
 
## Requirements
- [Requirement 1 — use "must", "should", "must not"]
- [Requirement 2]
- ...
 
## Out of scope
- [What explicitly NOT to do]
 
## Constraints
- Stack: [e.g. Node 20, React 18, Postgres 15]
- Conventions: [e.g. use repository pattern, no raw SQL, tests with Vitest]
- Must not break: [e.g. existing auth flow, public API contracts]
- Prefer: [e.g. small focused functions, no new dependencies without justification]
 
## Success criteria
- [ ] [Observable, testable outcome 1]
- [ ] [Observable, testable outcome 2]

• The Constraints section is the most important part. The more specific it is, the fewer loops you hit in step 3.
• Use “must”, “should”, “must not” language in Requirements — it forces you to think about priority.
• Success criteria should be observable and testable by a human or a test runner, not just “feature works”.

You are a senior engineer doing technical planning.

Read the following:
- `raw_request.md` — the feature/bug request
- The relevant source files listed below

Source files:
[list file paths]

Produce a `plan.md` file with these sections:

## Summary
One paragraph: what are we building and why.

## Current state
How the relevant code works today. Be specific — reference actual files, functions, and data flows.

## Proposed approach
Step-by-step technical approach. For each step explain the "why", not just the "what".

## Files to change
| File | Change type | Reason |
|------|-------------|--------|

## Files to create
| File | Purpose |

## Risks and unknowns
- [anything that could go wrong or needs a decision before implementing]

## Decisions made
- [any design decisions made here and the reasoning]

Be concise. Avoid generic advice. Reference specific files and function names from the actual codebase.

• Does “Current state” reference actual function names from your code, not generic descriptions?
• Does “Proposed approach” explain why each step is taken?
• Is the “Decisions made” section populated? If empty, the model skipped reasoning — prompt again with: “For each decision in the approach, explain what alternatives were considered and why you chose this one.”

• Always feed this prompt the minimal set of source files relevant to the task. Feeding the entire codebase produces vague plans.
• The Decisions made section is critical — it carries reasoning forward into steps 4 and 5, preventing the model from re-inventing or contradicting decisions mid-implementation.

This replaces the open-ended “is it best practice?” gate with a structured, triaged list of concerns.

You are a senior engineer doing a pre-implementation code review.

Read:
- `raw_request.md`
- `plan.md`
- The relevant source files listed below

Source files:
[list file paths]

Produce an `audit.md` file. For each concern use this format:

---
**[BLOCKER | WARNING | NITPICK]** — [short title]
- File/area: [where]
- Issue: [what is wrong or risky]
- Suggestion: [concrete fix]
---

Check for:
- Does the plan contradict existing patterns in the codebase?
- Are there missing edge cases or error paths?
- Will this break any existing behavior or API contracts?
- Are there security, performance, or scalability concerns?
- Does anything in the plan conflict with the constraints in raw_request.md?
- Are there simpler alternatives the plan overlooks?

End with a verdict:
## Verdict
READY | NEEDS CHANGES

If NEEDS CHANGES, list only the BLOCKERs that must be resolved before proceeding.
Do NOT suggest changes for WARNINGs or NITPICKs — those can be addressed later.

• You — not the model — decide what to fix. Read the audit, triage BLOCKERs yourself, update plan.md, then re-run step 3 only for the changed sections.
• This kills the infinite loop. The old “if no, return to step 3” pattern loops forever because the model has no stable definition of “ready”. The BLOCKER/READY gate gives it one.
• If the audit produces only WARNINGs and NITPICKs, the verdict should be READY. Proceed.

You are a senior engineer breaking a plan into implementation tasks.

Read:
- `raw_request.md`
- `plan.md`
- `audit.md`
- The relevant source files listed below

Source files:
[list file paths]

Create one file per task in the `tasks/` folder named `task-01.md`, `task-02.md`, etc.

Each task file must follow this exact structure:

## Goal
One sentence. What does completing this task accomplish?

## Context
Why this task exists and how it fits into the overall plan.

## Files to touch
- `path/to/file.ts` — what to do

## Implementation steps
Numbered, specific steps. Reference real function names, types, and patterns from the codebase.

## Acceptance criteria
- [ ] [Concrete, verifiable outcome — prefer test commands or observable behavior]
- [ ] [e.g. `npm test src/auth` passes]
- [ ] [e.g. POST /api/login returns 401 with invalid credentials]

## Dependencies
- Depends on: [task-XX or "none"]
- Must complete before: [task-XX or "none"]

Rules for task splitting:
- Each task must be independently verifiable
- No task should touch more than 3–4 files
- Order tasks so each one builds on a stable foundation
- Prefer: data layer → business logic → API → UI

Before running step 5, review the generated tasks yourself:

• [ ] Each task has at least one acceptance criterion that can be verified by a test command or observable behavior
• [ ] No task touches more than 3–4 files
• [ ] Tasks are ordered so each one has a stable foundation (no task depends on something not yet implemented)
• [ ] Trivially small tasks (1–2 line changes) are merged into adjacent tasks
• [ ] Tasks that touch too many files are split further

• You are the tech lead here. The model's task split is a first draft, not a final plan.
• Prefer the ordering: data/schema layer → business logic → API/service layer → UI/presentation.
• Acceptance criteria that say “code looks correct” are not criteria. Require a test command, a curl output, a log line, or a UI behavior.

Run this prompt once per task file. Do not batch multiple tasks into one prompt.

You are a senior engineer implementing a single task.

Read:
- `tasks/task-01.md` — the task to implement (change number each time)
- `plan.md` — for overall context and decisions already made
- The source files listed in the task

Implement exactly what the task describes. Do not implement anything outside this task's scope.

Rules:
- Follow existing code patterns in the files you touch
- Do not introduce new dependencies without flagging it
- Do not refactor code outside the task scope
- Leave a short inline comment when making a non-obvious choice

After implementing, self-check against the acceptance criteria:
## Verification
- [ ] [paste each criterion from the task]
For each criterion: state whether it passes and how you verified it.

If any criterion cannot be verified by you (e.g. requires running tests), output the exact command to run:
```
[test command]
```

Do not mark the task complete until all blockers are resolved.

For criteria that need real test output, run the command yourself and paste the result back with this follow-up prompt:

Test output:
[paste output here]

Are all acceptance criteria in task-01.md met? If not, what needs to change?

This gives the model real evidence to verify against instead of self-assessing.

• Always include plan.md in the context, not just the task file. It prevents the model from drifting or contradicting earlier decisions.
• “Do not implement anything outside this task's scope” is important — without it, the model will eagerly refactor surrounding code or pre-implement the next task.
• One task per prompt. Batching tasks in one prompt leads to entangled changes that are hard to review and harder to roll back.

project/
├── raw_request.md          ← Step 1: you write this
├── plan.md                 ← Step 2: model output, you review
├── audit.md                ← Step 3: model output, you triage
├── tasks/
│   ├── task-01.md          ← Step 4: model output, you review
│   ├── task-02.md
│   └── task-03.md
└── [your source files]     ← Step 5: model modifies these