Add code review instructions and release checklist prompts

2026-07-21 02:06:50 +00:00 · 2026-05-31 10:59:28 +08:00
parent f10ab4e7b3
commit aa575390d2
3 changed files with 197 additions and 0 deletions
@@ -0,0 +1,83 @@
 ---
 description: "Use when the user asks for a code review, PR review, regression scan, or quality review of backend changes in this repository."
 ---
 # Code Review Instruction
 ## Review Objective
 Find defects and risks before merge. Prioritize behavior, correctness, reliability, and operational safety over style preferences.
 ## Output Contract
 Return review results in this order:
 1. Findings ordered by severity (critical, high, medium, low)
 2. Open questions or assumptions
 3. Brief change summary
 If no actionable findings exist, explicitly say no findings and list residual risks or test gaps.
 ## Finding Format
 For each finding include:
 - Severity
 - Impact
 - Evidence with file reference
 - Why it matters
 - Suggested fix direction
 ## Repository-Specific Review Focus
 ### API Behavior and Compatibility
 - Verify route behavior under app/api/routes is compatible with existing endpoint contracts.
 - Check query alias compatibility for upstream params such as BusStopCode, ServiceNo, Date, and $skip.
 - Flag any accidental payload transformation if endpoint should proxy upstream JSON directly.
 ### Upstream and Error Handling
 - Confirm upstream failures are mapped consistently and safely.
 - Ensure no secrets or sensitive payload content is leaked in error bodies.
 - Validate timeout and retry assumptions for DataMall calls.
 ### Cache Safety
 - For cache-related changes, verify key stability, TTL appropriateness, and stale-data risk.
 - Confirm degraded behavior is safe when Valkey is unavailable.
 - Check that cache logic is centralized in app/services/cache.py patterns.
 ### Configuration and Secrets
 - Confirm required env vars are documented in .env.example.
 - Confirm .env is not staged or committed.
 - Verify new settings are wired through app/core/config.py.
 ### Runtime and Deployment
 - Validate Docker and compose changes maintain health endpoint behavior.
 - Ensure Makefile targets still reflect actual workflows.
 - Check operational regressions for Podman or Docker detection logic.
 ### Tests and Validation
 - Require at least compile-level validation for touched Python files.
 - Flag missing automated tests for behavior changes.
 - For major logic changes, request route-level or service-level tests.
 ## High-Risk Patterns To Flag Immediately
 - Breaking endpoint contract changes without documentation updates
 - Silent exception swallowing in request or cache paths
 - Hardcoded secrets or keys
 - Unbounded cache growth patterns
 - Changes that bypass centralized client or cache abstractions
 ## Helpful References
 - Architecture and commands: AGENTS.md
 - Runtime and usage: README.md
 - Entry wiring: app/main.py
 - Upstream client: app/services/lta_client.py
 - Cache layer: app/services/cache.py
@@ -0,0 +1,53 @@
 ---
 mode: ask
 description: "Use when preparing a release for this backend project to run a consistent release checklist covering build, runtime, config safety, and documentation updates."
 ---
 # Release Checklist
 Run a full release readiness pass for this repository.
 ## Inputs
 - Release version or tag
 - Scope of changes
 - Target environment (local, staging, production)
 If any input is missing, ask concise follow-up questions before proceeding.
 ## Checklist Workflow
 1. Review changed files and summarize release scope.
 2. Validate project health:
   - Run make sync if dependency files changed.
   - Run make compile.
 3. Validate container workflow:
   - Run make compose-up when Podman or Docker is available.
   - Verify the health endpoint returns success.
   - Run make compose-ps and confirm services are healthy.
 4. Validate configuration safety:
   - Ensure .env is not staged or committed.
   - Ensure .env.example includes any new required variables.
 5. Validate docs and instructions:
   - Update README.md if commands, routes, or behavior changed.
   - Update AGENTS.md if conventions or operational workflows changed.
 6. Produce a release report with:
   - Pass and fail checklist items
   - Risks or follow-ups
   - Suggested next actions before tagging
 ## Output Format
 Return results in this order:
 1. Findings by severity, with file references where relevant
 2. Open questions and assumptions
 3. Release readiness verdict: ready, conditionally ready, or not ready
 4. Recommended next actions
 ## Project-Specific Notes
 - Primary commands are managed through Makefile and uv.
 - Backend routes live under app/api/routes.
 - Runtime depends on DATAMALL_API_KEY from .env.
 - Valkey cache is expected in compose-based runs.
@@ -0,0 +1,61 @@
 ---
 name: backend-testing
 description: "Use when adding, fixing, or reviewing backend tests for this FastAPI project, including route tests, service tests, cache behavior, and upstream error handling."
 ---
 # Backend Testing Skill
 Use this skill to design and implement robust tests for the backend API.
 ## Project Context
 - App framework: FastAPI
 - Python environment: uv
 - API routes: [app/api/routes/bus.py](app/api/routes/bus.py)
 - Upstream client: [app/services/lta_client.py](app/services/lta_client.py)
 - Cache layer: [app/services/cache.py](app/services/cache.py)
 - App wiring and lifespan: [app/main.py](app/main.py)
 ## Testing Goals
 1. Verify endpoint behavior, input validation, and response shape.
 2. Verify upstream failures are mapped to expected HTTP errors.
 3. Verify cache-assisted behavior does not break correctness.
 4. Keep tests deterministic with no real external API calls.
 ## Workflow
 1. Identify the change surface and affected endpoints or services.
 2. Add or update tests under a test layout that mirrors app modules.
 3. Mock external dependencies:
   - Mock DataMall calls from [app/services/lta_client.py](app/services/lta_client.py).
   - Stub cache interactions from [app/services/cache.py](app/services/cache.py).
 4. Cover at least these scenarios per endpoint:
   - Success response
   - Input validation failure
   - Upstream failure mapping
 5. Run checks and tests with uv.
 6. Keep tests readable with clear arrange, act, assert sections.
 ## Preferred Patterns
 - Use pytest-style tests and fixtures.
 - Use FastAPI test clients for route-level coverage.
 - Keep one behavior assertion focus per test.
 - Use explicit test data, not random values.
 - Name tests with behavior intent, for example: test_bus_arrival_returns_upstream_payload.
 ## Commands
 - Sync dependencies: make sync
 - Compile check: make compile
 - Run tests: uv run pytest
 If pytest is not installed yet, add it to project dependencies before creating tests.
 ## Quality Gate Before Finish
 1. New or changed behavior has corresponding tests.
 2. Tests do not call live DataMall services.
 3. Error handling and validation paths are covered.
 4. Existing compile check still passes.