Skip to content

commandBackend and APIs

Add Health Check

Adds liveness and readiness endpoints that test real dependencies with short timeouts, so orchestrators restart the right things.

npx workspacetemplates add add-health-check --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/add-health-check.md14 lines · 1.3 KBFile
---
description: Adds liveness and readiness endpoints that test real dependencies with short timeouts, so orchestrators restart the right things.
argument-hint: "[dependencies to check, optional]"
---

Add health endpoints to this service. Dependencies to include: $ARGUMENTS (detect them from config if empty).

1. Read the app entry point, config and client setup to list real dependencies: database, cache, queue, object storage, upstream APIs.
2. Add `GET /livez`: returns 200 with no dependency calls. It only proves the process responds.
3. Add `GET /readyz`: runs one cheap check per required dependency in parallel (for example `SELECT 1`, a cache PING), each with a 1 to 2 second timeout. Return 200 when all pass, otherwise 503 with JSON like {"status":"degraded","failed":["database"]}.
4. Mark optional dependencies as non-fatal so a flaky analytics API does not take the service out of rotation.
5. Never include secrets, hostnames, stack traces or version numbers in the body. Skip auth on these routes but do not expose them publicly if the platform supports an internal port.
6. Reuse existing connections; do not open a new pool per probe.
7. Add tests for all-healthy and one-dependency-down, then run them. Show the probe snippet for the deploy config and ask before editing it.

What it does

A health route that always returns 200 hides outages, and one that calls every dependency on each probe can cause them. This command adds two separate checks: one that says the process is alive, and one that says it can do work.

Each dependency check has a hard timeout and runs a cheap query. The response names what failed without leaking connection strings or versions.

Example

you › /add-health-check database and redis

agent › Added /livez (static 200) and /readyz (Postgres SELECT 1, Redis PING, 1.5s timeout each, run in parallel).
Down redis returns 503 {"status":"degraded","failed":["redis"]}. 3 tests pass.
Suggested probe: readiness path /readyz, period 10s, failureThreshold 3.

Questions

Why two endpoints?
Liveness restarts a stuck process, readiness only removes it from traffic. Mixing them makes a database blip restart every instance.
Could the checks slow the service down?
They are cheap queries on shared connections with short timeouts, and they run in parallel.
  • Add Caching

    CommandBackend and APIs

    Free
  • Add Endpoint

    CommandBackend and APIs

    Free
  • Add Pagination

    CommandBackend and APIs

    Free
  • Add Rate Limit

    CommandBackend and APIs

    Free