Prompt Engineering for Code

How you phrase a prompt directly affects the quality of the output. This page covers practical techniques for code-related tasks, plus the workspace instruction files that let you front-load context once for the whole repo.

Principles of Effective Prompts

Be specific and concrete. Include the language, framework, relevant types/interfaces, and surrounding context — not just "write me a function."
State constraints explicitly. "Don't change the public API" or "keep the existing test structure" are things the AI won't infer on its own.
Specify the output format. Do you want code only, code with explanation, code with tests, or a refactored diff? Say so.
Use few-shot examples. Paste a snippet of your codebase's style and the model will match it far better than it would from style descriptions alone.
Ask for reasoning on complex tasks. "Explain your approach before writing the code" produces more careful output and lets you catch a wrong direction early.

Prompt Patterns for Common Tasks

Generating New Code

Include: the language and framework, any relevant types or interfaces, what module or file this belongs in, and what you've already got. The richer the context, the less the model invents.

Example prompt structure:

Prompt: generating a new hook
I'm working in a React 18 + TypeScript project using React Query and Zod.

I need a custom hook called `useUserProfile` that:
- Fetches `/api/users/:id` using React Query
- Validates the response with this Zod schema: [paste schema]
- Returns `{ data, isLoading, error }` — typed strictly, no `any`

Don't add error boundary logic; we handle that at the page level.
Here's how another similar hook looks in this codebase: [paste example]

Refactoring

Include the full function or module to be changed.
State what to change and what to leave alone.
Specify invariants: "preserve the return type," "don't add new dependencies," "keep the existing tests passing."

Debugging

Include the full error message and stack trace.
Paste the relevant code.
Describe what you've already tried.
Ask for step-by-step reasoning before the fix: this catches cases where the model would jump to the wrong conclusion.

Code Review and Explanation

Ask for specific feedback dimensions: correctness, performance, security, readability.
"What edge cases is this missing?" is a more productive prompt than "review this."
"Explain this code as if I'm new to this codebase" works better than "what does this do?"

Workspace Instruction Files

note

These files give the AI persistent context about your project without pasting it into every prompt. Set them up once per repo, and every prompt benefits.

GitHub Copilot — `.github/copilot-instructions.md`

Copilot reads this file and incorporates it as system-level context for all Copilot Chat interactions in the workspace.

What to include: tech stack and versions, coding conventions, folder structure, preferred patterns, patterns to avoid.

.github/copilot-instructions.md
# Copilot Instructions

## Stack
- React 18, TypeScript 5, Vite
- React Query for data fetching, Zod for validation
- Tailwind CSS + shadcn/ui for styling

## Conventions
- All components use named exports (no default exports)
- Use React Query for all server state; avoid `useState` for async data
- Validate all API responses with Zod schemas before use
- Prefer `const` arrow functions for components

## Do Not
- Add `any` types — use `unknown` and narrow instead
- Install new dependencies without discussing in a PR
- Use `useEffect` for data fetching — use React Query instead

Reference: GitHub Copilot custom instructions

Cursor — `.cursorrules`

Cursor reads .cursorrules at the repo root as a standing system prompt for all Cursor Chat and Composer interactions.

.cursorrules
You are an expert TypeScript and React developer.

This project uses React 18, TypeScript 5, React Query, Zod, Tailwind CSS, and shadcn/ui.

Always:
- Use named exports for components
- Type everything strictly — no `any`
- Use React Query for server state
- Validate API responses with Zod

Never:
- Add new npm packages without noting it
- Use useEffect for data fetching
- Generate default exports for components

Cursor is also moving toward a .cursor/rules/ folder for modular, file-glob-scoped rules. See the Cursor documentation for the latest on this.

Claude Code — `CLAUDE.md`

Claude Code reads CLAUDE.md at the project root when starting a session. It's the most important context file for agentic Claude workflows.

Recommended content: project description, tech stack, key architecture decisions, how to run the dev server and tests, common commands.

CLAUDE.md
# Project: My App

A React + Node.js web application for [brief description].

## Stack
- Frontend: React 18, TypeScript 5, Vite, React Query, Tailwind CSS, shadcn/ui
- Backend: Node.js 20, Express, Prisma, PostgreSQL
- Testing: Vitest (unit), Playwright (E2E)

## Running the project
- `npm run dev` — start the dev server (frontend on :5173, backend on :3000)
- `npm test` — run unit tests
- `npm run test:e2e` — run Playwright tests

## Key conventions
- Named exports everywhere
- All API responses validated with Zod
- No `any` types
- Feature folders: `src/features/<name>/{components,hooks,api,types}.ts`

Reference: Claude Code memory docs

AGENTS.md — Tool-Agnostic Convention

AGENTS.md is a tool-agnostic convention for providing instructions to AI coding agents. Instead of maintaining separate files for each tool, you write one AGENTS.md that supporting agents can read — though not all tools support it yet (unsupported tools will simply ignore the file).

Place AGENTS.md at the repo root for global instructions. Additional AGENTS.md files in subdirectories scope instructions to that directory — similar to how .gitignore works hierarchically.

The content is essentially the same as what you'd put in CLAUDE.md: project overview, tech stack, commands, conventions, and constraints.

AGENTS.md
# Project: My App

## Overview
A React + Node.js web application for [brief description].

## Stack
- Frontend: React 18, TypeScript 5, Vite, React Query, Tailwind CSS
- Backend: Node.js 20, Express, Prisma, PostgreSQL
- Testing: Vitest (unit), Playwright (E2E)

## Commands
- `npm run dev` — start dev server
- `npm test` — run unit tests
- `npm run lint` — lint and type-check

## Conventions
- Named exports for all components (no default exports)
- Validate all API responses with Zod schemas
- No `any` types — use `unknown` and narrow
- Feature folders: `src/features/<name>/{components,hooks,api,types}.ts`

## Do Not
- Add new dependencies without discussing in a PR
- Use `useEffect` for data fetching — use React Query
- Commit generated files or build artifacts

Tool	Reads `AGENTS.md`?	Notes
Claude Code	✅	Reads alongside `CLAUDE.md`
OpenAI Codex	✅	Primary instruction file
GitHub Copilot	❌	Uses `.github/copilot-instructions.md`
Cursor	❌	Uses `.cursorrules` / `.cursor/rules/`

tip

When to use AGENTS.md:

Multi-tool teams — use AGENTS.md as a single source of truth that all supported agents read.
Single-tool teams — a vendor-specific file (CLAUDE.md, .cursorrules) may be simpler.
Hybrid — use AGENTS.md for shared conventions, plus vendor-specific files for tool-unique features.

Reference: AGENTS.md convention

For a tool-agnostic convention with varying tool support, see AGENTS.md above. Copilot also supports scoped instruction files (*.instructions.md) and reusable prompt templates (*.prompt.md) for more granular control. See Copilot Customization Files for full details.

VS Code Copilot Techniques

@workspace — semantic search across all open workspace files. Use it to ask questions about your codebase: @workspace how is authentication handled?
@terminal — include terminal output (errors, build failures) as context for a fix.
#file / #selection — explicitly scope context to a specific file or highlighted code block.
#problems — include current diagnostics (errors and warnings) from the Problems panel as context.
#fetch — fetch a URL and include the response content as context. Useful for referencing live documentation or API specs.
Slash commands:
- /explain — explain a piece of code in plain language
- /fix — fix a bug or error in selected code
- /tests — generate unit tests for selected code
- /doc — generate a documentation comment for selected code

tip

@workspace /explain on an unfamiliar module is one of the highest-value quick wins when onboarding to a new codebase.

Model Selection

Copilot Chat supports multiple language models. Click the model name in the chat panel header to switch — different models suit different tasks.

Model	Best for
GPT-4.1	Fast general-purpose coding, good default
Claude Sonnet 4	Long reasoning chains, architectural decisions, large refactors
o4-mini	Complex logic where step-by-step reasoning helps, math-heavy code
Gemini 2.5 Pro	Large context windows, analyzing many files at once

Model availability depends on your Copilot subscription tier. The model picker shows only models available to you.

note

Model selection affects chat and agent mode only — inline completions (ghost text) use a separate, fast model that isn't user-configurable.

Vision & Image Context

Copilot Chat accepts image attachments when using a vision-capable model (GPT-4o, Claude Sonnet, Gemini). Drag and drop or paste an image directly into the chat input.

Use cases:

UI mockup → code — paste a wireframe or Figma screenshot and ask Copilot to implement it
Bug reproduction — attach a screenshot of broken UI with the question "why does this render wrong?"
Diagram interpretation — paste an architecture diagram and ask Copilot to scaffold the described structure

tip

Combine image context with #file references for best results: paste a mockup and reference your design system components so Copilot uses your existing component library rather than inventing new markup.

Next Edit Suggestions (NES)

Next Edit Suggestions predict your next logical edit after you make a change — not just completions at the cursor, but related changes elsewhere in the file. A ghost-text suggestion appears at the predicted location; press Tab to accept.

Example: rename a parameter in a function signature → NES suggests updating all usages of that parameter in the function body.

Enable or disable via:

.vscode/settings.json
{
    "github.copilot.nextEditSuggestions.enabled": true
}

note

NES is different from inline completions. Inline completions suggest code at your cursor position. NES suggests edits at other locations in the file based on the edit you just made.

Customizing Copilot Outputs

Several Copilot outputs — commit messages, generated tests, and code reviews — can be customized with instruction settings in your VS Code settings.json (or your workspace's .vscode/settings.json). Each setting controls a different output type.

Commit Messages

Copilot can generate commit messages for you — click the sparkle icon in the Source Control panel and it drafts a message from your staged changes. Control the format and style with commitMessageGeneration.instructions:

.vscode/settings.json
{
    "github.copilot.chat.commitMessageGeneration.instructions": [
        {
            "text": "Generate commit messages following this format:\n\nSubject line: `YOURPROJECT-xxxx <gitmoji> Short meaningful description`\n- Start with the Jira issue number in YOURPROJECT-xxxx format (infer from branch name if possible)\n- Follow with a relevant gitmoji (e.g. ✨ new feature, 🐛 bugfix, ♻️ refactor, 🎨 style, 🔧 config, ✅ tests, 📝 docs, 🔥 removal, ⬆️ dependency upgrade, 🚀 performance)\n- Keep the subject under 72 characters, imperative mood (Add, Fix, Update)\n\nBody (optional, keep brief):\n- Only if the change isn't obvious from the subject\n- Max 2-3 short bullet points with gitmojis\n- Focus on WHY, not WHAT"
        }
    ]
}

The example above combines Jira issue prefixes, gitmoji, and imperative-mood subjects, but you can adapt the text value to match whatever commit convention your team uses — Conventional Commits, plain prefixes, or anything else.

Test Generation

The same pattern works for test output. When you use /tests or ask Copilot to generate tests, it follows testGeneration.instructions:

.vscode/settings.json
{
    "github.copilot.chat.testGeneration.instructions": [
        {
            "text": "Use Vitest (describe, it, expect). Prefer userEvent over fireEvent for React Testing Library. Follow the Arrange-Act-Assert pattern. Name test files <module>.test.ts."
        }
    ]
}

Code Review

When you select code and use Copilot's review feature, reviewSelection.instructions controls how it analyzes and reports issues:

.vscode/settings.json
{
    "github.copilot.chat.reviewSelection.instructions": [
        {
            "text": "Focus on: type safety, error handling, missing edge cases, and security. Flag any use of `any` type. Note if error boundaries or fallback states are missing."
        }
    ]
}

tip

All four instruction settings (codeGeneration, testGeneration, reviewSelection, commitMessageGeneration) accept the same format: an array of { "text": "..." } or { "file": "path/to/file.md" } objects. The file variant lets you point to a Markdown file in the repo — useful when the instructions are long or shared across developers.

For the full list of Copilot customization options, see the VS Code Copilot customization docs.

tip

The text value must be a single JSON string, so use \n for line breaks. Compose the instructions in a plain text editor first, then convert to a single line with escaped newlines.

Cursor-Specific Techniques

@codebase — full semantic search across the entire indexed repo; more powerful than @workspace for large codebases.
Composer — multi-file editing mode. Describe a cross-cutting change and Cursor drafts diffs across all affected files simultaneously.
.cursorrules — see Workspace Instruction Files above.

Resources

VS Code Copilot documentation — official reference for all Copilot features
GitHub Copilot Chat prompting tips — official prompting guidance
Cursor documentation — official Cursor feature reference
Anthropic Prompt Engineering Guide — model-agnostic prompting principles
Burke Holland's YouTube channel — Burke is a Senior Developer Advocate at Microsoft for VS Code and Copilot; browse his channel for practical prompting and Copilot technique videos
VS Code YouTube channel — search "Copilot" for feature deep dives and demos
VS Code Copilot Customization — the official multi-page guide to all Copilot customization options in VS Code
awesome-copilot — Instructions — a curated library of real-world .instructions.md files from the community. Browse for examples to adapt when writing your own workspace instruction files.

Principles of Effective Prompts​

Prompt Patterns for Common Tasks​

Generating New Code​

Refactoring​

Debugging​

Code Review and Explanation​

Workspace Instruction Files​

GitHub Copilot — .github/copilot-instructions.md​

Cursor — .cursorrules​

Claude Code — CLAUDE.md​

AGENTS.md — Tool-Agnostic Convention​

VS Code Copilot Techniques​

Model Selection​

Vision & Image Context​

Next Edit Suggestions (NES)​

Customizing Copilot Outputs​

Commit Messages​

Test Generation​

Code Review​

Cursor-Specific Techniques​

Resources​

Principles of Effective Prompts

Prompt Patterns for Common Tasks

Generating New Code

Refactoring

Debugging

Code Review and Explanation

Workspace Instruction Files

GitHub Copilot — `.github/copilot-instructions.md`

Cursor — `.cursorrules`

Claude Code — `CLAUDE.md`

AGENTS.md — Tool-Agnostic Convention

VS Code Copilot Techniques

Model Selection

Vision & Image Context

Next Edit Suggestions (NES)

Customizing Copilot Outputs

Commit Messages

Test Generation

Code Review

Cursor-Specific Techniques

Resources