From cf78c31e05d413f40699526161019cd0227de543 Mon Sep 17 00:00:00 2001 From: claude Date: Thu, 28 May 2026 15:20:35 +0300 Subject: [PATCH] Emphasize Docker build and container startup verification in workflow Updated general-dev-workflow skill to stress that for Docker projects, BOTH build success AND successful container startup are required before considering a change complete. Key additions: - Docker container startup verification is mandatory, not optional - Containers must have status 'Up', not 'Restarting' or 'Exited' - Check container logs for errors during startup - Missing config files, invalid env vars, DB issues only show at runtime - Startup failures block production deployments - Updated Phase 4 checkpoint to include container startup validation Lesson from email-api issue: missing appsettings.json caused restart loop that had no visible logs during build. This must be caught in Phase 4 before code review and prevents production issues. Co-Authored-By: Claude Sonnet 4.6 --- docs/skills/general-dev-workflow.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/skills/general-dev-workflow.md b/docs/skills/general-dev-workflow.md index d9264fa..cdda4e2 100644 --- a/docs/skills/general-dev-workflow.md +++ b/docs/skills/general-dev-workflow.md @@ -85,11 +85,24 @@ Steps: - **Docker projects**: Run `docker compose --build` to verify all Docker images build successfully - Check build artifacts exist and are correct size (no suspiciously small binaries) -**Why build verification matters:** +**Docker container startup verification (required for Docker projects):** +- After successful build, run `docker compose up -d` to start all containers +- **Wait 10-15 seconds** for services to initialize (database migrations, seeding, etc.) +- Run `docker compose ps` and verify all containers have status **Up** (not Restarting or Exited) +- Run `docker logs ` for each container and verify: + - No errors or fatal exceptions in startup logs + - Services logged successful initialization (e.g., "startup complete", "listening for requests") + - Database migrations completed successfully (if applicable) + - Configuration loaded without errors +- **This is not optional for Docker changes** — a container that restarts means the change is incomplete +- If any container fails to start, the build is not successful until fixed + +**Why build AND startup verification matters:** - Catches missing dependencies, import errors, and configuration issues early -- Prevents "it works on my machine" problems during code review -- Docker builds especially must be verified as they catch missing project references and file copies -- A failed build blocks reviewers and CI/CD pipelines +- Docker builds catch missing project references and file copies, but don't catch runtime config problems +- Missing appsettings files, invalid environment variables, or database connection issues only show up at runtime +- A failed startup blocks entire services in production — this must be caught before code review +- A failed build blocks reviewers and CI/CD pipelines; a failed startup blocks production deployments **Write tests for your changes:** - Unit tests for individual functions/methods @@ -112,9 +125,9 @@ Steps: - Any manual testing notes - Known limitations or edge cases not yet tested -**Output**: Passing tests, code coverage report, test summary, successful build. +**Output**: Passing tests, code coverage report, test summary, successful build, containers running successfully (for Docker projects). -**Checkpoint**: Does the code compile without errors? Can you confidently say the code works? Are there any untested paths you're worried about? +**Checkpoint**: Does the code compile without errors? Do all Docker containers start and stay running (status: Up)? No errors in container logs? Can you confidently say the code works? Are there any untested paths you're worried about? --- @@ -197,7 +210,7 @@ Problem it solves / value it adds (2-3 sentences) **Keep phases focused.** Don't mix planning with implementation. Don't test in Phase 2. This separation helps catch problems early. -**Verify builds before review.** Always run a full build (`dotnet build` or `docker compose --build`) in Phase 4 before opening the PR. Build errors block reviewers and waste CI/CD time. If you're changing Dockerfiles or project dependencies, this is especially critical. +**Verify builds AND container startup before review.** Always run a full build (`dotnet build` or `docker compose --build`) in Phase 4 before opening the PR. **For Docker projects, also verify all containers start successfully** with `docker compose up -d` and check logs for errors. Build errors block reviewers; startup failures block deployments. Missing configuration files, invalid env vars, and DB connection issues only show at runtime. **Commit frequently.** Small commits are easier to review, easier to revert if needed, and easier to understand. Aim for 50-200 lines per commit.