prompt-engineer-claude-code

gistfile1.txt

---
name: prompt-engineer-claude-code
description: >
  Diagnoses and improves prompts directed at Claude Code and coding agents.
  Use when the user wants to pass an instruction to Claude Code or any coding
  AI agent and the prompt is incomplete, disorganized, or not producing the
  expected result. Also use when the user says "help me improve this prompt",
  "how do I tell Claude Code to...", "I want the agent to do X", or pastes
  an informal prose prompt and asks to structure it better. Applies to
  debugging, new features, refactors, architecture decisions, and
  DevOps/infra tasks described in natural language.
---

# Prompt Engineer — Claude Code

Framework for diagnosing and rewriting prompts directed at Claude Code
and coding agents. The goal is to reduce the agent's search space:
a precise prompt produces actionable code, a vague one produces
clarifying questions or generic solutions.

---

## Step 1 — Identify the prompt type

Identify which category the prompt belongs to before rewriting it:

| Type | Signals | Most common antipattern |
|------|---------|------------------------|
| **Debugging** | "there's an error", "it's not working", "status 500" | Mixes symptoms with hypotheses |
| **New feature** | "add", "create", "I need it to..." | Doesn't specify current vs expected behavior |
| **Refactor** | "improve", "clean up", "restructure" | Doesn't define what's wrong or the expected result |
| **Architecture** | "how do I structure", "what pattern should I use" | Doesn't provide stack context or constraints |
| **DevOps/Infra** | "deploy", "pipeline", "configure" | Doesn't specify the target environment |

---

## Step 2 — Diagnosis checklist

Review what the original prompt is missing:

**Technical context**
- [ ] Is the stack mentioned? (framework, runtime, version)
- [ ] Is there anything non-standard the agent can't infer?
- [ ] Are concrete paths, files, or component names referenced?

**The problem**
- [ ] Are symptoms separated from hypotheses?
- [ ] Are there concrete reproduction scenarios?
- [ ] Is it mentioned what was already tried and didn't work?

**The question**
- [ ] Is there an explicit, scoped question at the end?
- [ ] Is the expected output specified? (analysis? code? both?)
- [ ] Are paths the agent should NOT explore ruled out?

---

## Step 3 — Templates by type

### Debugging

```markdown
## Context
[Relevant tech stack. Anything non-standard in your setup.]

## Observed symptom
[What exactly fails. Endpoint, error message, log output.]
[When it occurs — concrete reproduction scenarios.]
[Frequency: 100% reproducible or intermittent?]

## What you already ruled out
[Hypotheses you already tried that didn't solve the problem.]
[This prevents the agent from repeating what you already did.]

## Current hypothesis
[Your best theory about the cause. The agent can confirm
or dismiss it — but needs to know your starting point.]

## Question
[One scoped question: confirm hypothesis / propose solution
/ list probable causes ordered by likelihood.]

## Expected output
[Analysis? Code change with explanation? Step-by-step list?]
```

### New feature

```markdown
## Context
[What exists today. Affected component/module with path.]
[Stack and patterns already used in the project.]

## Current behavior
[What the system does today in the area being modified.]

## Expected behavior
[What it should do after. State before and after
user/system interaction.]

## Business rules
[Concrete conditions: "only when X", "maximum N", "if Y then Z".]

## Technical constraints
[Dependencies that can't change, required patterns,
compatibility with other modules.]

## Expected output
[Full code? Just the interface/types? Proposal first for review?]
```

### Refactor

```markdown
## Context
[File/module to refactor with path.]
[Why the problem exists: tech debt, changed requirements, etc.]

## Concrete problem
[What's wrong today: coupling, duplication, naming, performance.]
[Metric if applicable: "this function is 300 lines", "called N times".]

## Expected result
[How it should look after. If there's a reference pattern
in the codebase, name it.]

## Constraints
[What must NOT change: public API, observable behavior, existing tests.]

## Expected output
[Proposal first for review? Code directly? Phased approach?]
```

### Architecture

```markdown
## Context
[Full current stack. What already exists and won't change.]
[Current and projected scale if relevant.]

## Decision to make
[What is being designed. One clear sentence.]

## Options considered
[What you already evaluated, with why you ruled them out
or why they're still candidates.]

## Hard constraints
[What can't change: existing infra, team, budget, timeline.]

## Scoped question
[Recommend one option? Compare trade-offs? Design the solution?]
```

---

## Cross-cutting rules

These apply to all prompt types:

**1. Separate observation from hypothesis**
They are different things. The observation is a fact; the hypothesis
is an interpretation. If mixed, the agent validates the hypothesis
instead of questioning it.

**2. Give exact reproduction scenarios**
"sometimes fails" → "fails when the token has been inactive for
more than 15 min and the user navigates between apps". Precision
gives the agent surface area to reason about.

**3. Name what was already ruled out**
Without this the agent will suggest exactly what was already tried.
This is the most underrated field in any technical prompt.

**4. End with an explicit, scoped question**
Not "what do we do?" but one of these forms:
- "What is the most likely cause given this context?"
- "Give me the 3 hypotheses ordered by probability with how to validate each"
- "Propose the solution assuming hypothesis X is correct"

**5. Specify the expected output**
Analysis? Code? Proposal first for review? If not stated,
the agent chooses — and rarely chooses what's needed at that moment.

**6. References always explicit**
"like we have it today", "the usual component", "remember that..."
don't work — the agent has no memory between sessions.
Always reference by path, function name, or file name.

---

## Signs of a well-formed prompt

- The agent can start working without asking anything
- No ambiguity about what's wrong and what should remain correct
- Expected output is defined
- What was already tried is documented
- References are concrete paths or names, not pronouns

## Signs of a prompt that needs work

- Mixes symptoms, hypotheses, and questions in the same paragraph
- Uses "remember that...", "as always", "the thing from before"
- Ends with "what do we do?" or "I think that's the issue"
- Doesn't mention the stack or assumes the agent already knows it
- Doesn't say what type of output is expected