Current Vs Desired — Claude Code Guide

Three parts of a task description

`Goal` shows the direction, but it does not explain the gap between the current and target states. For that, record `Current behavior` and `Desired behavior` separately.

Describe the current state using observable facts without premature conclusions about the cause. The desired state should be something that can be checked after implementation.

Facts about current behavior

For a bugfix, record the entry point, reproduction steps, actual result, environment, workaround, and impact. For a feature, describe the limitation the user faces and how the problem is currently worked around.

On /login, enter a correct email and an incorrect password.
After submit, the page becomes blank.
No error message is shown.
The problem reproduces locally and on staging.

Desired behavior must be observable

• the user remains on the login page after an incorrect password;
• the form does not disappear or clear unnecessarily;
• an understandable message appears below the password field;
• successful authorization works as it did before.

Evidence versus hypothesis

Facts-first workflow

1. Write down Goal, Current behavior, and Desired behavior.
2. Mark hypotheses that still need to be checked separately.
3. Gather logs, reproduction steps, and other evidence.
4. Ask Claude to separate facts from assumptions before editing code.
5. Check the code, schema, handlers, API, and events.
6. Only after confirming the causes, move to planning and edits.
7. Check each Desired behavior item separately.

## Hypotheses to verify
- The cause may be in backend validation.
- Check it in the code first, then make changes.