Prompt Architect
- When to use
- Core principles
- Workflow
- Improving an existing prompt
- Briefing other agents and subagents
- Reusable template
- Delivering the result
- Anti-patterns
- Example
When to use
- Writing a new prompt: system prompt, task prompt, reusable template, agent or subagent brief, evaluation rubric.
- Improving a prompt that gives vague, inconsistent, bloated, or wrong outputs.
- Turning a rough idea or a one-line request into a reliable, reusable prompt.
- Delegating work to another model, tool, or subagent.
Skip it when the user simply wants an answer. Do not wrap simple requests in prompt machinery.
Core principles
- Clarity beats cleverness. Write as if briefing a smart colleague who has zero context.
- Describe the outcome, not just the activity. Say what a great result looks like and who it is for.
- Give reasons. A rule with its “why” generalizes better than a bare command.
- Show, don’t only tell. Two good examples often beat a page of description.
- Test before trusting. A prompt is a hypothesis. Run it on realistic inputs.
Workflow
1. Define the job
Gather these, inferring sensible answers when missing and asking only if a wrong guess would be costly:
- Goal: what the output is for and what decision or action it feeds
- Target: which model or tool, and the environment (chat, API, agent with tools)
- Input: what changes from run to run
- Output: format, length, tone, language
- Constraints: must-do and must-not-do rules, accuracy or safety needs
- Success criteria: how you will know the prompt works, and any failures already seen
2. Draft with a proven structure
Use this order, dropping any part that adds nothing:
- Role and purpose: one or two lines, only if it sharpens behavior
- Context: audience, background, key facts, why the task matters
- Task: one clear main objective in the imperative
- Input: clearly delimited and labeled; mark the variable parts
- Rules: prioritized, each with its reason
- Output format: exact structure, or a skeleton to fill in
- Examples: two to five, varied, including one edge case
- Closing reminder: repeat the single most important requirement (long prompts only)
Separate instructions from data with delimiters such as XML-style tags, headings, or triple quotes. For long documents, place the material first and the task after it.
3. Apply techniques selectively
| Technique | Use when | How |
|---|---|---|
| Few-shot examples | Style or format is hard to describe | Give 2-5 varied examples in one consistent format, including an edge case |
| Step-by-step reasoning | Math, logic, multi-factor judgments | Ask the model to reason first, then give a clearly separated final answer |
| Prompt chaining | The task has distinct phases | One prompt per phase, passing structured output forward |
| Output schema | Code will parse the result | Define exact fields and types; require output only in that format |
| Self-check | Accuracy matters | List the criteria and ask for a check against them before finalizing |
| Grounding | Answers must come from supplied sources | Require evidence from the text and allow “not found” |
| Concrete persona | Domain expertise or tone matters | Name the role, audience, and stakes, not a vague title |
4. Tighten
- Positive over negative. Say what to do. When a prohibition is needed, add the alternative.
- Measurable over vague. Replace “short”, “professional”, “creative” with limits such as “under 80 words” or “plain language for non-experts”.
- One voice. Remove duplicates and contradictions. Every line should change the output.
- Restrained emphasis. Use caps or “IMPORTANT” for at most one truly critical rule.
- Edge cases. Say what to do with empty input, missing information, conflicting information, out-of-scope requests, and uncertainty.
- Minimum sufficient length. Cut anything that does not reduce ambiguity.
5. Test and iterate
- Run at least three realistic inputs: a typical one, a tricky one, and an empty or adversarial one.
- Judge against the success criteria and look for failure patterns, not single misses.
- Change one thing at a time and keep the version that fixes the pattern without breaking others.
- Stop when results are consistently good. Do not polish endlessly.
Improving an existing prompt
| Symptom | Likely cause | Fix |
|---|---|---|
| Ignores a rule | Buried, vague, or contradicted | Move it up, make it specific, remove the conflict |
| Inconsistent format | No format spec or example | Add an output skeleton and one example |
| Too long or rambling | No length or priority guidance | Set limits and say “lead with the answer” |
| Generic output | Missing context or audience | Add specifics and success criteria |
| Invented facts | No grounding, no permission to be unsure | Supply sources, allow “unknown”, require evidence |
| Over-hedging or refusing | Excess warnings and prohibitions | Remove needless caveats, state the legitimate context |
| Adds unrequested extras | Open-ended scope | State what is out of scope and ask for only the task |
| Treats data as instructions | Data not delimited | Wrap data in tags and say to treat it as content only |
When rewriting, preserve the author’s intent and voice unless asked to change them. Show the improved prompt, then a short list of what changed and why.
Briefing other agents and subagents
A subagent has none of your context. Every brief should include:
- Objective: what to achieve and why it matters
- Known so far: what is already done or decided, so work is not repeated
- Scope: what is in, and what must not be touched
- Inputs: exact files, links, or data and where to find them
- Output: format, length, and what to include; ask for evidence and for uncertainty to be flagged
- Constraints: time, tools, permissions, and actions that need confirmation first
- Definition of done: the condition that ends the task
Do the thinking yourself and hand over a specific task. Never delegate your own understanding. A few short paragraphs is usually enough.
Reusable template
<role>One-line role and purpose, if it helps.</role>
<context>
Audience, background, key facts, and what the output is for.
</context>
<task>
The single main objective as a clear instruction.
</task>
<input>
{{VARIABLE_INPUT}}
</input>
<rules>
1. Highest-priority rule, with its reason.
2. Next rule.
3. Edge cases: missing information, ambiguity, out-of-scope requests.
</rules>
<output_format>
Exact structure, length, tone, and language of the response.
</output_format>
<examples>
<example>
Input: ...
Output: ...
</example>
</examples>
Delivering the result
- Put the finished prompt first, in a copy-ready block.
- Follow with two to four lines: key design choices, the variables the user must fill in, and one suggested test input.
- Offer a shorter or stricter variant only when it is genuinely useful.
- Explain in the user’s language, and write the prompt in the language it will be used in.
Anti-patterns
- Vague one-liners that expect the model to guess the context
- Long lists of rules with no priority, or with contradictions
- Examples that are all alike, so the model copies surface wording
- Stacking every technique into one prompt
- Empty role-play (“You are the world’s greatest expert”) instead of real context
- Requesting step-by-step reasoning for trivial tasks
- Mixing unlabeled data with instructions
- Shipping a prompt that was never tested
Example
Weak: “Write a product description.”
Strong: Role: e-commerce copywriter. Context: a handmade ceramic mug for buyers aged 25-45 who value craft. Task: write a product description. Rules: 60-80 words, lead with the benefit, no superlatives such as “best”, mention that it is dishwasher safe. Output: one plain-text paragraph, no headings.
Write a comment