Diagnosis starts with facts

Do not immediately change code to treat a startup problem. First record the operating system, shell, current directory, Git state, tool versions, exact command, and the first meaningful log lines.

The goal is to turn a vague symptom into a scenario another person can reproduce in a clean or explicitly described environment.

Minimal setup evidence
pwd
git status --short
./gradlew --version
node -v
docker --version
docker compose ps
docker compose logs backend --tail=40
grep -n "SPRING_PROFILES_ACTIVE" .env.example

Make the environment reproducible

  • Record runtime and build-tool versions.
  • Use lock files and wrappers when the project provides them.
  • Record the package manager, profile, ports, and standard start command.
  • Check that required Docker services are actually running.
  • Define a smoke signal: health endpoint, CLI output, or another observable result.
SourceQuestion
README.mdWhich commands, versions, ports, and variables are documented?
Package scripts or Gradle tasksWhich commands are actually available?
Dockerfile or ComposeWhich entrypoint, environment, and port does the container use?
CLAUDE.mdDo local rules match the actual configuration?

Git and the file system are the baseline

If the symptom looks like a permission problem, check access to the required files, directories, or Docker socket separately. Do not change permissions blindly.

  1. Confirm the working copy with pwd.
  2. Check for README, wrappers, lock files, Compose files, and .env.example.
  3. Run git status --short before investigating.
  4. Separate your local edits from the new symptom.
  5. Compare the start command with documentation and scripts.

Environment variables without secret leakage

.env.example should describe names and safe example values, not real keys. Pass Claude masked values or variable names when the value is not required for diagnosis.

Compare .env.example, README, Compose, and application code. An unknown required variable often explains a failure before business logic does.

Safe variable template
PAYMENT_PROVIDER_MODE=sandbox
PAYMENT_API_KEY=<set-locally-never-commit>

One hypothesis, one check, smallest change

  1. State the most likely cause and the evidence supporting it.
  2. Ask Claude for read-only analysis and verification commands.
  3. Test one hypothesis with one command or small change.
  4. If it is not confirmed, record that result and return to facts.
  5. After confirmation, make the smallest necessary fix and repeat the baseline.

Canonical lesson source · JavaRush

Open JavaRush material