Prompt Patterns¶

Prompts are how you steer an agent. A good prompt does not need to be long. It needs to be clear about the goal, context, constraints, and output.

Use these patterns throughout the course. Copy them, adapt them, and eventually turn your repeated favorites into slash commands.

The Basic Shape¶

Most strong prompts follow this structure:

Goal: What I want done.
Context: What you need to know.
Constraints: What not to do, what to preserve, or which mode to use.
Output: How I want the answer formatted.

Example:

Goal: Find why the login test fails.
Context: This is a small Node app. The failure started after the auth refactor.
Constraints: Stay in plan mode and do not edit files.
Output: Give me the likely root cause, file references, and a 5-step fix plan.

1. Explore Before Acting¶

Use when you are unsure what needs to change.

Inspect this repository in plan mode. Do not edit files. Explain the project structure, the likely test command, and the files I should understand first.

Why it works: it keeps the agent in the read/think part of the agent loop before any risky action.

2. Bug Investigation¶

Use when something is broken but the cause is unclear.

Investigate this bug in plan mode: [describe the bug]. Look for the smallest likely root cause. Return findings with file paths, evidence, and a proposed fix. Do not edit files yet.

Example:

Investigate this bug in plan mode: users can submit an empty todo item. Look for the smallest likely root cause. Return findings with file paths, evidence, and a proposed fix. Do not edit files yet.

3. Smallest Safe Change¶

Use when you are ready for build mode.

Make the smallest safe change to [goal]. Preserve existing style and behavior outside this issue. After editing, summarize the diff and tell me how to verify it.

Example:

Make the smallest safe change to prevent empty todo items from being submitted. Preserve existing style and behavior outside this issue. After editing, summarize the diff and tell me how to verify it.

4. Explain for a Beginner¶

Use when you need understanding, not edits.

Explain [file/concept/error] for a beginner. Use plain language. Define any terms I need. End with the next two things I should inspect or try.

Example:

Explain src/router.js for a beginner. Use plain language. Define any terms I need. End with the next two things I should inspect or try.

5. Review First, Summary Second¶

Use for code review, PR review, and diff review.

Review the current diff for bugs, regressions, missing tests, and unclear code. Findings first, ordered by severity, with file references. Do not edit files. If there are no findings, say that clearly and list any residual risks.

Why it works: it prevents the agent from giving a vague compliment before doing the review.

6. Ask for Evidence¶

Use when the agent sounds confident but you want proof.

Re-check your answer. Separate facts supported by files or command output from assumptions. For each fact, cite the file, line, or command result that supports it.

Example:

Re-check your answer about the test command. Separate facts supported by files or command output from assumptions. For each fact, cite the file, line, or command result that supports it.

7. Convert a Repeated Workflow into a Command¶

Use when you notice yourself typing the same prompt again.

Turn this repeated workflow into a custom OpenCode slash command: [paste workflow]. The command should be beginner-friendly, include clear constraints, and accept arguments where useful.

Example:

Turn this repeated workflow into a custom OpenCode slash command: review the current git diff for bugs, missing tests, and unclear naming. The command should be beginner-friendly, include clear constraints, and accept arguments where useful.

8. Create a Skill Brief¶

Use when the agent needs reusable knowledge, not just a one-time instruction.

Draft a skill for [topic]. Include a clear description that would help an agent know when to load it. Add a checklist, examples, and common mistakes. Keep it reusable across projects.

Example:

Draft a skill for writing release notes. Include a clear description that would help an agent know when to load it. Add a checklist, examples, and common mistakes. Keep it reusable across projects.

9. Design a Custom Agent¶

Use when you need a repeatable role with specific permissions.

Design a custom OpenCode agent for [job]. Recommend whether it should be primary or subagent, what tools it should be allowed to use, what it should be denied, and what instructions belong in its prompt. Explain the permission choices.

Example:

Design a custom OpenCode agent for security review. Recommend whether it should be primary or subagent, what tools it should be allowed to use, what it should be denied, and what instructions belong in its prompt. Explain the permission choices.

10. Multi-Agent Handoff¶

Use when one agent needs to delegate work to another.

Create a handoff contract for [subagent name]. Define its input, allowed scope, output format, and failure conditions. Make the output easy for a primary agent to act on.

Example:

Create a handoff contract for security-checker. Define its input, allowed scope, output format, and failure conditions. Make the output easy for a primary reviewer-orchestrator agent to act on.

11. Verification Plan¶

Use after edits or before accepting agent work.

Give me a verification plan for this change. Include the fastest useful check, the strongest check, and any manual review steps. Do not make more edits.

Example:

Give me a verification plan for the empty-todo fix. Include the fastest useful check, the strongest check, and any manual review steps. Do not make more edits.

12. Stop and Narrow Scope¶

Use when the agent is drifting, over-editing, or solving the wrong problem.

Pause. Do not edit more files. Summarize what changed so far, what remains uncertain, and the smallest next step. Wait for my approval before continuing.

This is a productive friction prompt. It slows the workflow down so you can regain control.

Prompt Ingredients¶

Good Goals¶

Strong goals are specific:

Find why the test fails.
Add validation for empty todo text.
Review this diff for production risks.
Draft a beginner explanation of this file.

Weak goals are vague:

Fix it.
Make this better.
Look at this.

Good Context¶

Useful context includes:

What changed recently.
What you already tried.
Which files or errors matter.
Whether the task is for learning, production, or review.
What level of explanation you need.

Good Constraints¶

Useful constraints include:

Stay in plan mode.
Do not edit files.
Only touch files in reference/.
Preserve existing behavior.
Do not install packages.
Ask before running destructive commands.

Good Output Requests¶

Useful output formats include:

Give me 5 bullets.
Findings first, ordered by severity.
Use a table with file, issue, risk, and fix.
End with verification steps.
Separate facts from assumptions.

Before and After Examples¶

Too Vague¶

Fix the tests.

Better:

Investigate why the tests fail. Start in plan mode and do not edit files. Identify the first failing test, the likely root cause, and the smallest fix. Cite the files involved.

Too Broad¶

Refactor this app.

Better:

Review this app for one small refactor that would improve readability without changing behavior. Stay in plan mode. Recommend only one change and explain how to verify it.

Missing Safety Boundary¶

Set up the project.

Better:

Inspect the setup instructions and tell me the commands needed to run this project. Do not install packages or change files yet. Flag any command that could modify my system.

When to Use Which Pattern¶

Situation	Pattern
New repo	Explore Before Acting
Broken behavior	Bug Investigation
Ready to edit	Smallest Safe Change
Confusing code	Explain for a Beginner
Reviewing changes	Review First, Summary Second
Agent may be guessing	Ask for Evidence
Repeated prompt	Convert into a Command
Reusable knowledge	Create a Skill Brief
Specialized role	Design a Custom Agent
Multi-agent workflow	Multi-Agent Handoff
After edits	Verification Plan
Agent drift	Stop and Narrow Scope

Final Rule¶

If the task is unclear, ask for understanding before action.

If the task is risky, use plan mode.

If the task repeats, turn it into a command, skill, or agent.