monitoring-conventions
Alerts on symptoms, prevents alert fatigue, links runbooks, and separates health from readiness checks.
- Group
- Conventions
- Kind
- Read-only
- Loads when
- Editing infrastructure code, or adding metrics and alerts
When it runs
When infrastructure code is being edited or metrics and alerts are being added. Claude loads it on its own when the description matches the file or the task; it never writes anything itself. It matches:
- CDK
- Terraform
- serverless config
- CI workflows
- metrics
- alerts
The conventions
- Alert on symptoms. Error rate above 1%, p99 above 2 seconds, a growing queue. Do not page on causes such as CPU above 80% or memory use; causes belong on dashboards.
- Prevent alert fatigue. An alert that fires three times without action gets its threshold tuned or is removed. An ignored alert is worse than no alert.
- Every paging alert has a runbook. It says what to inspect, what to restart and whom to escalate to. No alert without a runbook.
- Health is not readiness.
/healthreports process liveness for load balancers;/readyreports dependency readiness for orchestration. A health check does not query the database. - Monitoring ships with the feature. A new metric or alert lands in the same change as the feature it observes, never in an unspecified later task.
Related
- deploy-checklist checks monitoring before a deploy.
- defensive-coding-conventions: defect classes that commonly ship past review.