# Claude for Development

> Give Claude the context a senior engineer would want.

Repo facts, intent, constraints, and a verification path. Phrases for pairing, planning, debugging, refactoring, and reviewing without thrash.

Source: https://www.juanmnl.com/notes/claude-for-development.html

## Frame the Ask

Underspecified requests get plausible-but-wrong code. State these and you'll get code that fits your repo.

### Goal & acceptance criteria

What "done" looks like. Concrete criteria let Claude self-check instead of guessing scope.

Prompt: Goal: add pagination to the users API. Done when it returns page, limit, total and has tests.

### Stack & versions

Language, framework, and versions. Prevents APIs from the wrong era or ecosystem.

Prompt: Stack: TypeScript, React 19, Next.js app router, Tailwind v4.

### Conventions

Point at how the codebase already does things so new code matches, not fights, the patterns.

Prompt: Follow the existing pattern in /services, match its error handling and naming.

### Constraints

No new deps, must stay backward-compatible, performance budget, security rules.

Prompt: Constraints: no new dependencies, keep the public API stable.

### Scope boundary

Say what NOT to touch. Stops well-meaning refactors that balloon the diff.

Prompt: Only change the auth module. Don't refactor anything else.

### Vague → precise


## Working Modes

Lead with the verb that matches the help you want.

### Implement / build

Write new code to a spec. Strongest with acceptance criteria and conventions attached.

Prompt: Implement a debounced search hook with a 300ms delay and cancellation.

### Plan first

Ask for an approach before code on anything non-trivial. Cheaper to correct a plan than a diff.

Prompt: Plan the approach first, list the steps and files before writing code.

### Refactor

Improve structure without changing behavior. Name the goal: readability, performance, testability.

Prompt: Refactor this for readability, behavior must stay identical.

### Debug

Find and fix a defect. Give the symptom, the trace, and how to reproduce.

Prompt: Debug this, here's the error, the input, and expected output.

### Review

Evaluate a diff or file for bugs, security, and style. Ask for severity-ranked findings.

Prompt: Review this PR for bugs and security issues, ranked by severity.

### Explain

Understand existing code. Great for onboarding to an unfamiliar repo.

Prompt: Explain what this function does and why it's written this way.

### Optimize

Improve a measurable metric, name it (latency, memory, bundle size) and the target.

Prompt: Optimize this query, it's the N+1 hot path; cut DB round-trips.

### Test

Generate tests for behavior, edge cases, and regressions. Name the framework.

Prompt: Write tests (Vitest) covering empty, single, and overflow cases.


## Give Context

The single biggest lever for code quality. Claude reasons over what you show it, show the right things.

### Paste the error verbatim

Full stack trace, not a paraphrase. The exact line and message carry most of the signal.

Prompt: Here's the full stack trace and the failing line: [paste].

### Share the relevant files

Give the actual code that matters, plus its callers. Don't make Claude guess interfaces.

Prompt: Here's the handler and the service it calls, both files.

### Repo structure

A directory tree orients Claude on where things live and where new code belongs.

Prompt: Project layout: src/api, src/db, src/components, put new endpoints in api.

### Reproduction steps

Exact input → expected vs actual output. Turns "it's broken" into a solvable problem.

Prompt: Repro: POST this body → expect 201, get 500.

### Point Claude at the repo

When it has file access, let it read the code itself instead of you pasting everything.

Prompt: Read the auth module and tell me how sessions are stored.

### A CLAUDE.md / conventions doc

A persistent file of project rules (commands, style, gotchas) Claude loads every session.

Prompt: Follow CLAUDE.md, run pnpm test before claiming done.


## Code Vocabulary

Precise engineering terms collapse a paragraph into a word Claude already understands.

### Extract / inline

Pull code into its own function/module (extract) or fold it back (inline).

Prompt: Extract the validation into a pure function.

### Pure function

No side effects, same input → same output. Ask for these where you want testability.

Prompt: Make this a pure function, no I/O inside.

### Idempotent

Running it twice has the same effect as once. Key for retries and APIs.

Prompt: Make the endpoint idempotent with a request key.

### DRY / single source of truth

Remove duplication; one canonical definition. Use when copy-paste has crept in.

Prompt: This logic is duplicated 3 times, DRY it up.

### Edge cases

The boundary inputs: empty, null, huge, concurrent, malformed. Always ask for them.

Prompt: Handle the edge cases: empty array, null, and duplicates.

### Race condition

A bug from unpredictable ordering of concurrent ops. Name it when timing is suspect.

Prompt: Could this be a race condition? Two requests hit it at once.

### Type-safe / strict

No any, exhaustive checks, narrowed types. Ask for it explicitly.

Prompt: Make it type-safe, no any, handle every case.

### Backward compatible

Existing callers keep working. Critical when touching shared APIs.

Prompt: Keep it backward compatible, don't break current consumers.

### Abstraction / interface

A clean boundary hiding implementation. Ask Claude to define one before coupling things.

Prompt: Define an interface so we can swap the provider later.


## Agentic Workflow

When Claude can run commands and edit files, these moves keep it on the rails.

### "Plan, then execute"

Have Claude propose a plan you approve before it starts changing files.

Prompt: Show me the plan first, wait for my OK, then implement.

### "Work in small steps"

Incremental changes you can review beat one giant diff you can't.

Prompt: Do it in small, reviewable steps, pause between each.

### "Run the tests"

Tell Claude to verify its own work by running the suite before declaring done.

Prompt: Run the tests and don't stop until they pass.

### "Write a failing test first"

TDD, capture the bug or spec as a red test, then make it green.

Prompt: Write a failing test that reproduces the bug, then fix it.

### "Don't touch X"

Fence off files or areas so the agent stays scoped.

Prompt: Don't modify the migrations or the config.

### "Use a subagent"

Delegate parallel or exploratory work (searching, verifying) to a separate agent.

Prompt: Use a subagent to find every call site before changing the signature.


## Review & Quality

Name the lens and Claude reviews like a specialist instead of skimming.

### Correctness

Does it actually do the thing for all inputs, including the nasty ones?

Prompt: Check correctness on edge and error paths.

### Security

Injection, authz, secrets, unsafe input. Ask for an explicit security pass.

Prompt: Do a security review: injection, authz, exposed secrets.

### Performance

Hot paths, N+1 queries, unnecessary allocations, big-O.

Prompt: Flag any performance issues, N+1s, needless loops.

### Readability

Naming, structure, comments where the "why" isn't obvious.

Prompt: Would a new teammate understand this? Improve readability.

### Test coverage

What's untested, especially branches and failure modes.

Prompt: What's not covered by tests here?

### Maintainability

Coupling, hidden state, things that'll bite in six months.

Prompt: What will be hard to maintain about this later?


## Debugging

A structured ask gets a root cause, not a shot in the dark.

### "Find the root cause"

Ask for the underlying cause, not just a patch that hides the symptom.

Prompt: Find the root cause, don't just silence the error.

### "Add logging / instrument"

When the cause is unclear, have Claude add targeted logs to narrow it down.

Prompt: Add logging around the suspect path so we can see the state.

### "Form hypotheses"

Ask for ranked possible causes before fixing, keeps debugging systematic.

Prompt: List the top 3 likely causes, most probable first.

### "Bisect it"

Narrow down when it broke (commits) or where (binary search the code path).

Prompt: Bisect, what changed between the working and broken versions?

### "Minimal repro"

Reduce to the smallest case that still fails, often reveals the cause itself.

Prompt: Build a minimal reproduction of the failure.

### "Regression test"

After a fix, lock it in with a test so the bug can't return.

Prompt: Add a regression test so this never comes back.