# Prompt library for AI-assisted coding

By Patrick, PK Solutions

Most weak results I see from coding agents come from weak prompts, not weak models. A prompt that works tends to have five parts:

- **Goal.** What should be true when the work is done, in one or two sentences.
- **Context.** The files, modules, error messages or tickets that matter. Point to them; don't make the agent guess.
- **Constraints.** What must not change: public APIs, dependencies, style rules, performance budgets, files that are off limits.
- **Acceptance criteria.** How you and the agent will know it's done: tests that pass, behaviour you can observe, commands that run clean.
- **A plan first.** For anything bigger than a one-line fix, I ask for a plan and review it before any code is written. It's the cheapest place to catch a wrong assumption.

The prompts below follow that pattern. Replace every `[PLACEHOLDER]` with something specific, delete the lines that don't apply, and add what the template is missing for your codebase. They're written to work in any coding agent or chat assistant. If your tool can't read files directly, paste the relevant code where the prompt refers to it.

## Understanding a codebase

### 1. Guided tour of a repository

Use it on your first day in an unfamiliar repo.

```text
I'm new to this repository. Give me a guided tour before I change anything.

1. Summarize what the project does and who uses it, based on the code and docs you can see.
2. List the main directories and what each one is responsible for.
3. Identify the entry points (where execution starts for the app, CLI, jobs or tests).
4. Name the key dependencies and what they are used for.
5. Point out anything unusual: custom build steps, code generation, non-standard conventions.

Only describe what you can verify in the code. Mark anything you are inferring as an assumption.
Do not modify any files.
```

### 2. Trace a request end to end

Use it when you need to understand how one feature actually flows through the system.

```text
Trace what happens when [USER ACTION OR REQUEST, e.g. "a user submits the checkout form"].

Start at [ENTRY POINT, e.g. the route, handler or UI component] and follow the flow through every layer until [END STATE, e.g. the data is persisted and a response is returned].

For each step, give:
- the file and function
- what it does with the data
- any side effects (database writes, network calls, events, cache updates)

Finish with a short list of places where this flow could fail and how each failure is handled today.
Do not modify any files.
```

### 3. Explain a confusing piece of code

Use it when a function or module doesn't make sense to you.

```text
Explain [FILE PATH, FUNCTION OR CLASS NAME] to me.

- What problem is it solving?
- Walk through the logic step by step, in plain language.
- Why might it have been written this way? Point to evidence in the code, comments or surrounding modules.
- What are the inputs, outputs and hidden dependencies (globals, environment variables, shared state)?
- What would break if I changed [SPECIFIC PART I'M CONSIDERING CHANGING]?

If something is genuinely unclear from the code alone, say so instead of guessing.
```

### 4. Map the impact of a change

Use it before touching code that many other parts might depend on.

```text
I'm planning to change [FUNCTION, TYPE, TABLE, API OR CONFIG] so that [DESCRIPTION OF CHANGE].

Find everything that depends on it:
- direct callers and imports
- indirect uses (reflection, string references, config files, serialized data, templates)
- tests that cover it
- external consumers you can see evidence of (public API, other services, scripts)

Group the results by risk: will definitely break, might break, safe.
Do not modify any files.
```

## Planning a change

### 5. Plan before code

Use it for any task that touches more than a couple of files.

```text
Goal: [WHAT SHOULD BE TRUE WHEN THIS IS DONE].

Context: [TICKET, LINKS, RELEVANT FILES OR MODULES].

Constraints:
- [e.g. no new dependencies]
- [e.g. keep the public API unchanged]
- [e.g. must work with the existing database schema]

Before writing any code, produce a plan:
1. The files you expect to create or change, and why.
2. The order of the changes.
3. How you will verify each step (tests, commands, manual checks).
4. Open questions or assumptions I should confirm.

Stop after the plan and wait for my approval.
```

### 6. Compare implementation options

Use it when there's more than one reasonable way to build something.

```text
I need to [PROBLEM TO SOLVE] in [PART OF THE CODEBASE].

Propose two or three different approaches. For each one:
- a short description
- what it changes in the existing code
- trade-offs: complexity, performance, testability, how easy it is to undo
- what would make it the wrong choice

Then recommend one approach for our situation, given these priorities: [e.g. ship quickly, minimize risk, long-term maintainability].
Do not write implementation code yet.
```

### 7. Break a feature into small steps

Use it to turn a large feature into reviewable, shippable pieces.

```text
Break this feature into a sequence of small, independently reviewable changes:

[FEATURE DESCRIPTION]

Rules:
- Each step should leave the codebase working, with tests passing.
- Each step should be small enough to review in one sitting.
- Put risky or uncertain work early so we learn fast.
- Note which steps could sit behind a feature flag.

For each step, give a one-line title, what changes, and how to verify it.
```

### 8. Surface hidden requirements

Use it when a ticket feels too simple to be true.

```text
Here is the task I've been given:

[TICKET OR REQUIREMENT TEXT]

Before we plan anything, act as a skeptical senior engineer. Based on this codebase, list:
- questions I should ask the requester
- edge cases the ticket doesn't mention
- existing behaviour this could conflict with
- non-functional concerns (permissions, performance, logging, localization, accessibility, data migration)

Keep it to the items that actually apply here, not a generic checklist.
```

## Implementing features

### 9. Implement from an approved plan

Use it right after you've reviewed and approved a plan.

```text
The plan above is approved. Implement step [N]: [STEP TITLE].

- Follow the existing patterns in [SIMILAR FILE OR MODULE].
- Only change the files the plan lists. If you need to touch anything else, stop and tell me why first.
- Add or update tests for the new behaviour.
- Run [TEST COMMAND] and [LINT/TYPECHECK COMMAND] and fix anything that fails.

When you're done, summarize what changed and anything that differs from the plan.
```

### 10. Build a feature by matching an existing one

Use it when the codebase already has something very similar to what you need.

```text
Build [NEW FEATURE] by following the same structure as [EXISTING FEATURE, with file paths].

Match its:
- file layout and naming
- error handling
- validation approach
- test style

Differences from the existing feature:
- [DIFFERENCE 1]
- [DIFFERENCE 2]

Show me the list of files you plan to create or change before writing them.
```

### 11. Add an API endpoint

Use it for a new route, handler or RPC method.

```text
Add a [HTTP METHOD] endpoint at [PATH] that [WHAT IT DOES].

Request: [FIELDS, TYPES, WHICH ARE REQUIRED]
Response: [SHAPE ON SUCCESS]
Errors: [EXPECTED ERROR CASES AND STATUS CODES]
Auth: [WHO IS ALLOWED TO CALL IT]

Follow the conventions of [EXISTING ENDPOINT FILE] for routing, validation, error format and logging.
Add tests covering success, validation failure, unauthorized access and [OTHER CASE].
Do not change existing endpoints.
```

### 12. Build a UI component

Use it for a new front-end component that has to fit an existing design system.

```text
Create a [COMPONENT NAME] component in [DIRECTORY].

It should:
- [BEHAVIOUR 1]
- [BEHAVIOUR 2]
- handle loading, empty and error states

Constraints:
- Use the existing components and styles from [DESIGN SYSTEM OR FOLDER]. Do not add new styling libraries.
- It must be keyboard accessible and have proper labels for screen readers.
- Follow the prop and file conventions of [SIMILAR EXISTING COMPONENT].

Add tests for the main interactions, using the same testing approach as the rest of the project.
```

## Writing tests

### 13. Tests for existing code

Use it to add coverage to code that has none.

```text
Write tests for [FILE OR FUNCTION].

First, list the behaviours you think should be tested: normal cases, edge cases and error cases. Wait for me to confirm the list.

Then write the tests:
- Use [TEST FRAMEWORK] and follow the style in [EXISTING TEST FILE].
- Test behaviour through the public interface, not implementation details.
- Mock only external boundaries (network, filesystem, time, third-party services).
- Do not change the code under test. If something is hard to test, tell me why instead.
```

### 14. Test-first for a new behaviour

Use it when you want the agent to work red, then green.

```text
I want to add this behaviour: [DESCRIPTION].

Work test-first:
1. Write a failing test that describes the behaviour. Run it and show me that it fails for the right reason.
2. Write the minimum code to make it pass.
3. Run the full test suite for [MODULE] to confirm nothing else broke.
4. Suggest any refactoring, but don't apply it without asking.

Repeat for each of these cases: [CASE 1], [CASE 2], [CASE 3].
```

### 15. Find gaps in an existing test suite

Use it when tests exist but you don't trust them.

```text
Review the tests for [MODULE] in [TEST FILE(S)] against the code in [SOURCE FILE(S)].

Tell me:
- which behaviours and branches have no test
- tests that would still pass if the code were broken (weak assertions, over-mocking)
- tests that are brittle because they depend on implementation details
- missing edge cases: empty inputs, boundaries, invalid data, concurrency, time zones

Rank the gaps by risk and propose the five tests I should add first. Do not write them yet.
```

### 16. Stabilize a flaky test

Use it when a test passes and fails without any code change.

```text
This test is flaky: [TEST NAME AND FILE].

Symptoms: [HOW IT FAILS, HOW OFTEN, WHERE (locally, CI, both)].
Failure output: [PASTE ERROR]

Investigate likely causes, such as timing and async waits, shared state between tests, test order, real clocks or random values, network calls, and environment differences.

Explain the most likely root cause with evidence from the code, then propose a fix that makes the test deterministic. Do not add retries or longer timeouts as the fix unless you can explain why that's actually correct.
```

## Debugging

### 17. Diagnose from an error

Use it when you have a stack trace or error message and not much else.

```text
I'm getting this error:

[PASTE FULL ERROR AND STACK TRACE]

It happens when [STEPS TO REPRODUCE]. Expected: [EXPECTED BEHAVIOUR].
Environment: [e.g. local dev / staging / production, versions if relevant].

Before proposing a fix:
1. Explain what the error means.
2. List the likely causes, ranked, with the evidence for each in the code.
3. Tell me what to check or log to confirm which cause it is.

Don't change any code until we've confirmed the root cause.
```

### 18. Reproduce before fixing

Use it for bug reports that are vague or hard to trigger.

```text
Bug report: [PASTE REPORT]

Your first job is to reproduce it, not fix it.
- Write the smallest possible failing test or script that shows the bug.
- If you can't reproduce it, tell me what information is missing and what you tried.

Once we have a reliable reproduction, propose a fix, apply it, and show that the reproduction now passes along with the existing tests.
```

### 19. Hypothesis-driven debugging

Use it when you're stuck and the obvious fixes haven't worked.

```text
I'm stuck on this bug: [DESCRIPTION].

What I've already tried:
- [ATTEMPT 1 AND RESULT]
- [ATTEMPT 2 AND RESULT]

Work through it systematically:
1. List at least three hypotheses that fit all the evidence, including what I've already ruled out.
2. For each, describe a quick experiment that would confirm or eliminate it.
3. Tell me which experiment to run first and why.

After I share results, update the hypotheses. Don't jump to a fix until one hypothesis is confirmed.
```

### 20. Find the change that caused a regression

Use it when something used to work and now doesn't.

```text
[FEATURE OR BEHAVIOUR] worked on [KNOWN GOOD VERSION, COMMIT OR DATE] and is broken on [CURRENT VERSION].

Here are the changes between the two: [PASTE GIT LOG, DIFF SUMMARY OR LIST OF PULL REQUESTS]

1. Identify which changes could plausibly affect this behaviour, and explain why.
2. Rank them by likelihood.
3. If the list is long, give me the exact commands to bisect it.

Once we find the cause, propose the smallest fix that restores the old behaviour without reverting unrelated work.
```

## Refactoring

### 21. Behaviour-preserving refactor

Use it to clean up code without changing what it does.

```text
Refactor [FILE OR FUNCTION] to [GOAL, e.g. "reduce nesting and split it into smaller functions"].

Rules:
- Behaviour must stay exactly the same. No new features, no bug fixes mixed in. List any bugs you notice separately.
- Keep the public interface unchanged: [FUNCTION SIGNATURES, EXPORTS, API].
- Make sure tests cover the current behaviour first. If they don't, add characterization tests before refactoring.
- Run [TEST COMMAND] after each step.

Show me the plan first, then work in small steps.
```

### 22. Split a large file or class

Use it when a single file has grown into several responsibilities.

```text
[FILE PATH] has grown to [SIZE] and mixes several responsibilities.

1. List the distinct responsibilities you can see and which functions belong to each.
2. Propose a new structure: which modules to create, what goes where, and how they depend on each other. Avoid circular dependencies.
3. Plan the move in steps that keep the code working after each one.

Keep existing imports working (re-export if needed) unless I approve changing them. Wait for my approval before moving any code.
```

### 23. Remove duplication

Use it when the same logic appears in several places.

```text
The logic for [WHAT IS DUPLICATED] appears in several places, including [FILE 1], [FILE 2], [FILE 3].

1. Find every copy, including slightly different variants.
2. Compare them and list the real differences. Some may be intentional.
3. Propose a single shared implementation that handles the legitimate differences without piling on flags.
4. Show how each call site would change.

Do not merge copies whose differences you can't explain. Flag them for me instead.
```

### 24. Improve names and readability

Use it for a low-risk pass on code that's hard to read.

```text
Improve the readability of [FILE OR FUNCTION] without changing behaviour.

Focus on:
- clearer names for variables, functions and types
- replacing magic numbers and strings with named constants
- simplifying conditionals
- removing dead code and stale comments
- adding a short comment only where the "why" isn't obvious

Keep public names unchanged unless I approve. Show the changes as a diff with a one-line reason for each non-trivial change.
```

## Code review

### 25. Review a diff before I open a pull request

Use it as a first review pass on your own work.

```text
Review this change before I open a pull request.

Purpose of the change: [WHAT IT'S SUPPOSED TO DO]
Diff: [PASTE DIFF, OR "the uncommitted changes in this repo", OR "this branch compared to main"]

Check for:
- bugs and logic errors
- edge cases that aren't handled
- missing or weak tests
- inconsistencies with the patterns used elsewhere in the codebase
- anything that doesn't match the stated purpose

Group findings as: must fix, should fix, nitpick. For each, point to the exact location and explain why. Don't rewrite the code; just review it.
```

### 26. Review someone else's pull request

Use it to prepare for reviewing a teammate's work.

```text
Help me review this pull request.

Description from the author: [PASTE PR DESCRIPTION]
Diff: [PASTE DIFF OR POINT TO BRANCH]

1. Summarize what the change does in plain language.
2. Check whether the implementation matches the description.
3. List the questions I should ask the author.
4. Flag risks: correctness, security, performance, backward compatibility, missing tests.

Keep the tone of any suggested comments constructive and specific. I'll decide what to post.
```

### 27. Check a change against team standards

Use it when your team has written conventions and you want them applied consistently.

```text
Here are our team's coding standards:

[PASTE STANDARDS OR POINT TO THE FILE]

Review [DIFF OR FILES] against them. For each violation, give the rule, the location and a suggested fix.

Only report real violations of the written standards. Don't add your own style preferences, and say so if the standards don't cover something you think matters.
```

## Documentation

### 28. Write a README for a module

Use it when a module has no documentation, or the documentation is out of date.

```text
Write a README for [MODULE OR DIRECTORY].

Include:
- what it does and when to use it
- how to set it up and run it locally
- the main public functions or endpoints, with a short example each
- configuration options and environment variables
- known limitations

Base everything on the actual code. If something is unclear, add a TODO for me rather than guessing. Keep it concise; developers should be able to scan it in two minutes.
```

### 29. Document a function or API

Use it for inline documentation that matches the project's style.

```text
Add documentation comments to the public functions in [FILE].

- Follow the existing doc comment style in [EXAMPLE FILE, or the language's standard format].
- For each function: what it does, parameters, return value, errors it can raise, and a short example if the usage isn't obvious.
- Don't restate what the code already says clearly. Focus on intent, constraints and gotchas.
- Don't change any code.
```

### 30. Record an architecture decision

Use it to capture the reasoning behind a technical choice while it's still fresh.

```text
Write an architecture decision record (ADR) for this decision:

Decision: [WHAT WE DECIDED]
Context: [THE PROBLEM AND CONSTRAINTS]
Options we considered: [OPTION A, OPTION B, OPTION C]
Why we chose it: [REASONS]

Use these sections: Title, Status, Context, Decision, Alternatives considered, Consequences (positive and negative).
Keep it under one page. Where I haven't given you a reason, leave a clear placeholder instead of inventing one.
```

## Performance

### 31. Find a performance bottleneck

Use it when something is slow and you don't yet know why.

```text
[OPERATION, PAGE OR ENDPOINT] is slow. It takes about [CURRENT TIME] and should take under [TARGET].

Relevant code: [FILES OR ENTRY POINT]
Profiling or timing data, if any: [PASTE]

1. Read the code path and list likely bottlenecks: repeated work, N+1 queries, blocking I/O, large allocations, missing indexes, unnecessary re-renders.
2. For each, explain how to measure whether it's actually the problem.
3. Don't optimize anything yet. Tell me what to measure first.
```

### 32. Optimize with a measurable target

Use it once you know where the time goes.

```text
The bottleneck is [SPECIFIC CODE AND WHAT MAKES IT SLOW], confirmed by [MEASUREMENT].

Optimize it with these constraints:
- Behaviour and output must stay identical. Existing tests must pass.
- Target: [e.g. under 200 ms for 10,000 records].
- Prefer the simplest change that reaches the target. Explain any trade-off in readability or memory.

Before and after, give me the exact command or benchmark to run so I can verify the improvement myself.
```

### 33. Review database queries

Use it when data access might be the slow part.

```text
Review the database queries in [FILES, REPOSITORY LAYER OR ORM MODELS] for performance problems.

Database: [ENGINE AND VERSION]
Approximate table sizes: [e.g. orders: 5M rows, users: 200k rows]
Schema and indexes: [PASTE OR POINT TO MIGRATIONS]

Look for N+1 patterns, missing or unused indexes, full table scans, over-fetching columns or rows, and queries inside loops.

For each issue, show the query, explain the problem, and propose a fix. If you suggest an index, tell me how to check it with the query plan before adding it.
```

## Security review

### 34. Security review of a change

Use it before merging anything that touches input handling, auth or data access.

```text
Do a security review of [DIFF, FILES OR FEATURE].

Check for:
- injection (SQL, command, template, path traversal)
- missing or incorrect authentication and authorization checks
- unsafe handling of user input and output encoding
- secrets or credentials in code, logs or error messages
- insecure defaults and overly broad permissions
- sensitive data exposed in responses or logs

For each finding: location, what an attacker could do, severity (high, medium, low), and a concrete fix. Only report issues you can point to in the code, and say how confident you are in each one.
```

### 35. Audit an authorization flow

Use it to check who can actually do what.

```text
Audit authorization for [FEATURE OR RESOURCE, e.g. "editing invoices"].

Roles in the system: [LIST ROLES]
Expected rules: [WHO SHOULD BE ABLE TO DO WHAT]

1. Find every code path that reads or changes this resource (UI, API, background jobs, admin tools).
2. For each path, show where access is checked, or state that it isn't.
3. Compare the actual checks with the expected rules and list every mismatch.
4. Point out any place where the check relies on data the client controls.

Do not modify code. Give me the findings as a table.
```

### 36. Review dependencies and configuration

Use it for a periodic check of what your project pulls in and how it's configured.

```text
Review the dependency manifest [e.g. package.json, requirements.txt, go.mod] and the configuration in [CONFIG FILES].

Flag:
- dependencies that look unused, duplicated or abandoned
- very broad version ranges
- debug settings, permissive CORS, disabled security headers or verbose error output that could reach production
- secrets committed to the repository

For anything version-specific (known vulnerabilities, end-of-life dates), don't rely on memory. Tell me which command or tool to run to check it.
```

## Migrations and upgrades

### 37. Plan a dependency or framework upgrade

Use it before upgrading anything with breaking changes.

```text
I want to upgrade [LIBRARY OR FRAMEWORK] from [CURRENT VERSION] to [TARGET VERSION].

Here are the official migration notes or changelog: [PASTE OR SUMMARIZE]

1. Find every place in this codebase affected by the breaking changes listed.
2. Estimate the size of each change (trivial, moderate, significant).
3. Propose an upgrade order that keeps the app working, including any intermediate versions.
4. List what to test manually after the upgrade.

Only rely on the migration notes I've given you for version-specific changes. If you need information I haven't provided, ask for it.
```

### 38. Write a safe database migration

Use it for schema changes on a database that's already in production.

```text
I need to change the schema: [DESCRIPTION, e.g. "split the name column into first_name and last_name"].

Database: [ENGINE AND VERSION]
Migration tool: [TOOL]
Table size: [APPROXIMATE ROW COUNT]
Constraints: [e.g. no downtime, the old app version must keep working during the deploy]

Write the migration so that:
- it can run while the app is live (expand, then migrate data, then contract, if needed)
- it has a working rollback
- the data backfill runs in batches if the table is large

Explain the deploy order: which migration steps go before, during and after the code change.
```

### 39. Migrate a pattern across the codebase

Use it for large, repetitive changes, such as moving from one API or library to another.

```text
Migrate all uses of [OLD PATTERN OR API] to [NEW PATTERN OR API].

Example of the change:
Before: [CODE SAMPLE]
After: [CODE SAMPLE]

1. Find every occurrence and give me the count, grouped by directory.
2. Identify the cases that don't fit the simple before/after example and explain why.
3. Migrate the simple cases first, one directory at a time, running [TEST COMMAND] after each batch.
4. Leave the unusual cases for me to review, with a note on each.
```

### 40. Port code to another language or framework

Use it when rewriting a module rather than upgrading it.

```text
Port [FILE OR MODULE] from [SOURCE LANGUAGE OR FRAMEWORK] to [TARGET LANGUAGE OR FRAMEWORK].

- Preserve behaviour exactly, including error cases and edge cases.
- Write idiomatic [TARGET] code rather than a line-by-line translation.
- Follow the conventions in [EXISTING TARGET-LANGUAGE CODE IN THIS REPO].
- Port or write tests that prove the new version behaves the same as the old one.

Before writing code, list anything that doesn't translate directly (library features, concurrency model, type differences) and how you plan to handle each.
```