Writing Prompts Like GitHub Issues

A practical prompt structure for turning vague AI requests into scoped, reviewable development work.

Most bad AI coding sessions start before the model answers.

They start with a request that has no edges:

Make the newsletter better.

The model can respond to that. It can inspect files, suggest copy, change styles, refactor a component, add validation, or invent a feature nobody asked for. The problem is not that the tool is lazy. The problem is that the work was never shaped.

If you want useful AI development output, write prompts like GitHub issues.

A good prompt is a work order

A GitHub issue does not need to be long. It needs to make the work reviewable.

At minimum, include:

  • the goal
  • the current behavior
  • the desired behavior
  • constraints
  • relevant files
  • acceptance criteria
  • verification commands

That structure gives the AI enough room to help without giving it permission to redesign the whole system.

The base template

Use this as the starting point:

Goal:
<What should change?>

Context:
<Why does this change matter? What should the agent know before editing?>

Relevant files:
- <path>
- <path>

Constraints:
- <What must not change?>
- <What dependencies or patterns should be avoided?>
- <What existing conventions should be followed?>

Acceptance criteria:
- <Observable result>
- <Observable result>

Verification:
- <command>
- <manual check>

Output:
Before editing, summarize the plan.
After editing, summarize the diff, tests run, and remaining risks.

This is not ceremony. It is leverage.

Context beats cleverness

Developers often try to make prompts clever. That is less useful than making them specific.

Bad:

Act as a senior engineer and improve this code.

Better:

Inspect app/api/newsletter/route.ts and app/components/NewsletterForm.tsx.
Improve validation and error handling for newsletter signup.
Keep the public API response shape unchanged.
Do not add dependencies.
Run npm run build.

The second prompt gives the agent work it can actually do.

Name the negative space

One of the most useful parts of a prompt is what the AI should not touch.

For example:

Do not redesign the form.
Do not change the database schema.
Do not modify unrelated CSS.
Do not change the contact form route.

That negative space matters because AI coding tools are good at finding adjacent problems. Sometimes that is helpful. Sometimes it turns a 20-minute fix into a review headache.

Scope is kindness to the reviewer.

Ask for inspection before implementation

When the AI starts by editing, it is guessing from the prompt. When it starts by inspecting, it can learn the local system.

Use language like:

First inspect the relevant files and summarize the current pattern.
Then propose a short plan.
Wait for approval before making broad changes.

For small, low-risk tasks, approval may not be necessary. For shared modules, migrations, auth, billing, deployment, or infrastructure, that pause is worth it.

Require proof, not confidence

AI tools are very good at sounding finished.

Do not ask, "Is this correct?" Ask for proof:

Run the test suite or the closest available check.
Report the exact command and result.
If a check cannot be run, explain why.
List any behavior that still needs manual verification.

That turns the final answer into a review artifact.

The useful output is not just "done." It is:

  • changed files
  • behavior changed
  • tests run
  • tests not run
  • risks
  • follow-up work

Prompts should produce durable reasoning

The prompt should also ask the AI to preserve the why.

For example:

After implementation, write a short reasoning summary suitable for a PR description.
Include assumptions, rejected options, and tradeoffs.

This matters because the chat will not be where future maintainers look first. They will look at the PR, the commit, the docs, the ADR, or the code.

If the reasoning is valuable, move it there.

A full example

Goal:
Add a newsletter issue preview page for Markdown files under content/newsletter.

Context:
The site already renders journal articles from content/journal using gray-matter and ReactMarkdown. Follow that pattern where practical.

Relevant files:
- app/late-night-development/lib/articles.ts
- app/late-night-development/[slug]/page.tsx
- app/components/ArticleBody.tsx
- app/globals.css

Constraints:
- Do not change existing journal article behavior.
- Keep newsletter issues unpublished unless their front matter says otherwise.
- Do not add a new Markdown renderer.

Acceptance criteria:
- /newsletter/container-series-launch renders.
- The page uses the issue title, preview, hero image, and CTAs from front matter.
- Draft-only production notes do not render.

Verification:
- Run npm run build.
- Confirm the route appears in build output.

Output:
Summarize the plan before editing.
After editing, summarize changed files, checks run, and any remaining risks.

That prompt is longer than "make a newsletter page." It is also far less expensive to review.

The prompt is part of the engineering system

Teams should save their best prompts.

Not every chat needs to become documentation, but repeated work should become a template:

  • bug fix prompt
  • small feature prompt
  • refactor prompt
  • test generation prompt
  • PR review prompt
  • reasoning capture prompt

Those templates make AI usage less personal and more operational. The team stops relying on whoever happens to be good at prompting and starts building a shared development system.

That is the real move.

Do not prompt like you are asking for magic. Prompt like you are opening a pull request before the code exists.

Common mistakes

  • Opening with a request that has no edges ("make the newsletter better") and letting the model choose the scope.
  • Writing "act as a senior engineer" instead of naming the files, the constraint, and the check to run.
  • Leaving out the negative space, so the agent fixes adjacent problems and turns a 20-minute change into a review headache.
  • Asking "is this correct?" instead of requiring the exact command run and its result.
  • Letting each developer reinvent prompts privately instead of saving the good ones as shared templates.

Practical checklist

  • The prompt states goal, current behavior, desired behavior, constraints, relevant files, acceptance criteria, and verification.
  • What the AI must not touch is written down explicitly.
  • The agent is told to inspect and summarize the current pattern before proposing changes.
  • The prompt asks for proof—commands and results—not a confidence statement.
  • The prompt requests a reasoning summary suitable for a pull request description.
  • Acceptance criteria are observable results, not intentions.
  • Repeated work has a saved template: bug fix, small feature, refactor, test generation, review, reasoning capture.

Previous: ChatGPT, Codex, and Claude: Choosing the Right Surface for the Work

Next: Reasoning Is a Company Asset, Not Chat Debris. The next part covers preserving decisions, assumptions, rejected options, and risks so the team's thinking survives past the chat window.