Wiki.Quizz.vn

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

----

===== Overview =====

^  Step  ^  You do  ^  Model does  ^  Output file  ^
|  1  |  Write the request  |  —  |  ''raw_request.md''  |
|  2  |  Provide source files  |  Technical planning  |  ''plan.md''  |
|  3  |  Triage blockers  |  Structured audit  |  ''audit.md''  |
|  4  |  Review task list  |  Task decomposition  |  ''tasks/task-NN.md''  |
|  5  |  Run verifier, paste output  |  Implement one task  |  Modified source files  |

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

----

===== Step 1 — Write the raw request =====

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.

==== File: raw_request.md ====

<code markdown>
## 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]
</code>

==== Tips ====

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

----

===== Step 2 — Create the plan file =====

==== Prompt ====

<code>
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.
</code>

==== What to check in the output ====

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

==== Tips ====

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

----

===== Step 3 — Audit the plan =====

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

==== Prompt ====

<code>
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.
</code>

==== Severity definitions ====

^  Severity  ^  Meaning  ^  Action  ^
|  BLOCKER  |  Will cause incorrect behavior, data loss, security issue, or breaks the build  |  Fix before step 4  |
|  WARNING  |  Technical debt, suboptimal approach, or risk under specific conditions  |  Log in a tech-debt note; revisit later  |
|  NITPICK  |  Style, naming, minor improvements  |  Ignore or batch into a cleanup task  |

==== Tips ====

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

----

===== Step 4 — Split into tasks =====

==== Prompt ====

<code>
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
</code>

==== Task review checklist ====

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

==== Tips ====

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

----

===== Step 5 — Implement and verify =====

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

==== Prompt ====

<code>
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.
</code>

==== Verification loop ====

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

<code>
Test output:
[paste output here]

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

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

==== Tips ====

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

----

===== File structure reference =====

<code>
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
</code>

----

===== Common failure modes =====

^  Symptom  ^  Cause  ^  Fix  ^
|  Step 3 loops forever  |  No concrete definition of "ready"  |  Use the BLOCKER/READY gate; you decide when to proceed  |
|  Step 5 output is vague or generic  |  Model lost context from earlier steps  |  Always include ''plan.md'' in step 5 context  |
|  Tasks are too coarse to verify  |  Acceptance criteria are missing or subjective  |  Require test commands or observable behavior in every task  |
|  Model refactors unrelated code  |  No scope constraint in step 5 prompt  |  Add "do not touch code outside this task's scope" explicitly  |
|  Model marks task complete without real evidence  |  Self-verification loop  |  Run the test command yourself and paste output back  |
|  Plan contradicts codebase patterns  |  Model hallucinated conventions  |  Feed the actual relevant source files, not just descriptions  |

----

===== Quick reference — prompt inputs per step =====

^  Step  ^  Inputs to provide  ^
|  1  |  Your own knowledge  |
|  2  |  ''raw_request.md'' + relevant source files  |
|  3  |  ''raw_request.md'' + ''plan.md'' + relevant source files  |
|  4  |  ''raw_request.md'' + ''plan.md'' + ''audit.md'' + relevant source files  |
|  5  |  ''tasks/task-NN.md'' + ''plan.md'' + source files listed in the task  |