Writing & changing code

Refactor this file. Constraints:
- Behaviour must not change. If you think a behaviour is a bug, flag it,
  don't silently fix it.
- No new dependencies.
- Keep the same public function/export names so my other files still work.
- Show me the full new file, then a short list of what you changed and why.

<paste file>

Review this code the way a sceptical senior dev would. Look for:
1. Things that will break with real user input (empty, huge, weird characters).
2. Anything secret that shouldn't be in the file (API keys, tokens, passwords).
3. Anything that talks to a database or the network without error handling.
4. Copy-pasted blocks that should be one function.

For each finding: the line, why it matters, and the smallest fix.
Rank by "would actually bite me" — skip style nitpicks.

<paste file>

You rewrote more than I asked. Undo that.

Go back to my original file and change ONLY: <the one thing>
Everything else stays byte-for-byte identical.
Show me a diff, not the whole file.

Feature: <describe it>

Before writing the implementation, write the tests. I want:
- The happy path.
- Two realistic ways a user breaks it.
- One edge case I probably haven't thought of.

Use <testing framework, or "the simplest thing that runs with no setup">.
Show me the tests and stop. I will read them and tell you if they
describe the thing I actually asked for.

Working code is attached. It currently does <what works today> and I
need that to keep working exactly as it does now.

Add: <the new feature>

Rules:
- Show me a diff or the changed sections only, not the whole file.
- Do not rename or restructure anything you were not asked to change.
- If the new feature genuinely requires changing existing behaviour,
  stop and tell me what and why before you write it.

Here is one function: <paste>

It works. I don't want new behaviour — I want it easier to read.

- Same inputs, same outputs, same side effects.
- Tell me first, in two lines, what makes it hard to read.
- Then the rewrite.
- Then list anything the rewrite changed that I should test.

Do not touch anything outside this function.

Here is my code: <paste>

Don't change any logic. Just tell me which names are wrong, and what
they should be. For each one, one line on why.

Look for: names that lie about what the thing holds, names that need a
comment to be understood, single letters outside short loops, and
functions whose name says less than they do.

This file has grown to <n> lines and I've lost the thread: <paste>

Propose a split. For each new file: the name, what moves into it, and
what it exports. Show me the plan as a list — no code yet.

Prefer the fewest files that fix the problem. If you think it should
stay as one file, say that instead and tell me why.

I have <current stack> and I want to get to <target>. Here's the code:
<paste or describe>

Do NOT rewrite it all at once. Give me a migration plan where the app
works after every step:
- What moves first, and why that piece.
- How the old and new parts talk to each other during the transition.
- The point of no return, and what I should verify before it.
- What I could keep on the old stack forever without shame.

Then we do step one, and only step one.

This project has types switched on loosely. I want strict, eventually.

- Turn on one compiler flag at a time. Tell me the order, easiest first.
- For the flag we're doing now, show me the errors it will produce and
  fix them in batches by kind, not file by file.
- Where a real fix needs restructuring, say so and leave a marked
  escape hatch rather than pretending with `any`.

Do not add `any` to make an error go away without telling me.

Here's my project: <paste files or the file list plus key files>

Find what isn't used:
- Functions never called.
- Imports never referenced.
- Variables assigned and never read.
- Files nothing imports.
- Config options nothing reads.
- Entire features I appear to have abandoned halfway.

For each: how confident are you it's genuinely unused, given you can
only see what I've pasted? Flag anything that might be called
dynamically or from a file you haven't seen.

Rank by how safe it is to delete.

Here's my code: <paste>

Find near-duplicates — blocks doing the same job with small
variations. This happens when I ask for similar things in separate
conversations.

For each cluster:
- What they have in common and how they differ.
- Whether they should genuinely be one function, or whether the
  differences mean they should stay separate.
- If they should merge, show me the merged version and every call site
  that changes.

Be honest when the answer is "leave them alone". Two similar functions
are often better than one with four flags.

Review this as if you'd just joined the project and have to maintain
it: <paste>

Answer in this order:
1. What does this do? If you can't tell in 30 seconds, say what's
   in the way.
2. What would surprise you here — anything doing something other than
   what its name suggests?
3. What breaks with unexpected input: empty, null, enormous, the
   wrong type, hostile?
4. What's not handled — errors swallowed, cases ignored?
5. What would you have to ask the author about?

Then: the three changes with the best ratio of improvement to risk.

This code has no types: <paste>

Add them incrementally:
- Start with the boundaries — function inputs and outputs, and the
  shape of anything coming from an API or a database.
- Types that describe reality, including nullable fields and the
  shape of an error response. Don't pretend everything is always
  present.
- Where the real type is genuinely dynamic, say so explicitly rather
  than using a permissive escape hatch quietly.

List every place you had to widen a type or use an escape hatch, and
why. Those are the places my code is doing something I should look at.

This works but it's hard to follow: <paste>

Simplify it. Behaviour must be identical.

Look for:
- Nesting that could be flattened with early returns.
- Conditions that could be named instead of inlined.
- Steps that happen in a confusing order.
- Flags and parameters that change what the function fundamentally is
  — those usually want to be two functions.

Tell me first, in two lines, what specifically makes it hard to
follow. Then the rewrite. Don't make it shorter at the cost of
clarity — I'd rather have more lines that read in order.

Audit the error handling in this: <paste>

Find:
- Empty catch blocks, and catches that only log then continue as if
  nothing happened.
- Errors caught too broadly, hiding ones I'd want to know about.
- Promises with no rejection handling.
- Failures that leave things half-done — a record created but not
  linked, a file written but not registered.
- Errors shown to users with internal detail in them.

For each: what actually happens today, what should happen, and whether
this failure should be retried, reported, or shown to the user.

Here's my code: <paste>

Two passes:

1. Delete comments that just restate what the next line does. List
   what you removed.

2. Add comments only where something can't be inferred from the code:
   a non-obvious constraint, why the obvious approach doesn't work
   here, a workaround for an external bug, a magic number's origin,
   an ordering that matters.

If you don't know why something is the way it is, ask me rather than
inventing a reason. A wrong "why" comment is worse than none.

I can't easily test this: <paste>

Tell me what makes it hard to test — usually it's doing several things
at once, or reaching out to the world in the middle of its logic.

Then restructure it so the logic can be tested without the network,
the clock, the filesystem or the database. Keep the behaviour
identical.

Show me:
- The separated version.
- One test that would have been impossible before.
- What's still untestable and why that's acceptable.

This project was built across many separate conversations and the
style has drifted: <paste several files>

Find the inconsistencies:
- Naming — camelCase here, snake_case there, different words for the
  same concept.
- Error handling done three different ways.
- Async handled with promises in one place and callbacks in another.
- Different patterns for the same kind of operation.

For each: pick one convention, say why, and list every place that
needs changing. Don't change anything yet — I want the list first.

I use <package> for <what I use it for>. Here's how: <paste the usage>

Honestly: could I replace this with my own code?
- How much of the library am I actually using?
- What would the replacement look like — show me it.
- What edge cases does the library handle that I'd get wrong?
- Is it doing something genuinely hard, or something that's just
  tedious to type?

If keeping it is the right call, say so. I'm not looking to
reimplement date parsing.

This uses callbacks and I'd like promises and async/await: <paste>

Convert it, keeping behaviour identical:
- Errors that arrived as a first callback argument become rejections.
- Preserve the ordering. If operations ran sequentially, they must
  stay sequential — don't parallelise them as a "bonus".
- Anything that ran in parallel by accident, flag it rather than
  quietly changing it.
- Add the error handling the callback version was missing.

List every behavioural difference between the two versions, including
subtle ones around ordering and error timing.

I'm building <one sentence> with <stack>, deployed to <host>. Here's the
project as it stands: <paste the file list and one representative file>

Write a short conventions file for AI tools to read at the start of every
session, such as CLAUDE.md. Include:
- How to run it locally and how to deploy it to this host.
- The stack's conventions this project actually follows, taken from the
  code rather than from general advice.
- What's deliberately unusual here, and why.
- What must never happen: files not to edit, commands not to run.

Under 60 lines. Only things that can't be worked out from the code.

My project uses <stack> and deploys to <host>. It has no linter or
formatter yet.

Set up the standard ones for this stack:
- Which tools, and why those.
- The smallest configuration that's useful. Defaults where possible.
- One command to format and one to check.
- Whether anything needs to change on the host, or whether this stays on
  my machine only.

Then tell me how to apply the formatter once, as its own commit, so it
doesn't clutter every later diff.

My project is <one sentence>, built with <stack> and hosted on <host>.
It has no tests.

Set up the test tool people normally use with this stack:
- Installation, and the single command that runs everything.
- One real test of the thing I'd most hate to break: <describe it>.
- How to run a single test on its own.
- Whether tests need a database, and how to keep them away from the
  real one.

Tests run on my machine or in CI, never on the live host.

My project runs <stack> on <host>. I want to move to <new version>.

Plan the upgrade:
- What changed between my version and the new one that affects code like
  mine. Point at the patterns to search for.
- How to test locally on the new version before touching the host.
- How to switch the version on this host, and how to switch back.
- Dependencies that need updating first.

Give me a checklist in order, with a way back at every step.

This code runs on <stack> and is deployed to <host>:
<paste>

Review it as an experienced developer in this stack would:
- Where does it ignore the stack's own conventions or built-in features?
- Where does it reinvent something the standard library already does?
- Anything that works locally but behaves differently on this host.

For each, show the idiomatic version. Don't change behaviour, and skip
pure style preferences.