Recap — From Spec → Scaffold → Fill → Polish

# From Spec → Scaffold → Fill → Polish Effective AI code generation is rarely one prompt. It's a sequence: specify, scaffold, fill in details, polish. Each phase has different prompts and different review criteria. ## Phase 1: Specify Before AI generates anything, get the spec right. What you decide: - What the feature does (inputs, outputs, behavior). - What constraints apply (perf, libraries, style). - What "done" looks like (tests pass; manual verification; etc.). Write this down (or talk through with AI): > "We're adding a notifications service. POST /notifications enqueues a notification (recipient, type, payload). A worker processes the queue and sends via email/SMS based on type. We need: durable queue (Redis), retry on transient failures, dedup by idempotency_key. Use existing User model, FastAPI, ARQ." Treat this as a spec. AI now has clear targets. When the spec is unclear, generated code will be too. Spec → quality. ## Phase 2: Scaffold Get the structure: files, classes, signatures, types. NOT implementations yet. Prompt: > "Scaffold the notifications service: > - src/notifications/models.py: Notification table. > - src/notifications/schemas.py: Pydantic for request/response. > - src/notifications/router.py: FastAPI endpoint. > - src/notifications/worker.py: ARQ task. > > Just signatures, type hints, and TODO comments. No implementations yet." AI generates the structure. You review: - Right files? - Right signatures? - Match conventions? If something's off, fix it BEFORE filling in. Easier to refactor a skeleton than a fully-implemented module. ## Phase 3: Fill Now implement file by file (or chunk by chunk). Prompt: > "Now implement src/notifications/router.py. The POST endpoint should validate the request, generate an idempotency key if not provided, enqueue to ARQ, return the queued notification ID. Handle the case where the user doesn't exist (404)." AI generates the implementation. You review: - Does it match the scaffold? - Edge cases handled? - Style matches codebase? Iterate per file or per logical chunk. ## Phase 4: Polish After core implementation: - Add tests. - Add logging. - Add docstrings. - Handle edge cases AI missed. - Make sure linter / type checker / tests pass. Prompt: > "Now add tests for the notifications router. Cover: happy path; missing recipient; invalid type; duplicate idempotency_key. Use the test patterns in tests/test_users.py." Tests are often a good final phase because they verify the implementation. ## The whole flow in one example ### Specify > "Add a feature: bulk-tag posts. Endpoint POST /posts/bulk-tag accepts a list of post_ids and a list of tags. Adds the tags to all those posts. Must be transactional (all or nothing). Tags that don't exist are created. Returns the count of posts tagged. Only the post owner can tag their own posts; admin can tag any." ### Scaffold > "Scaffold this: schemas (request, response), router endpoint, business logic in a service module. Use the existing patterns." (AI generates 3 files with signatures.) ### Fill > "Implement the router. Use Depends for current_user and DB. Call into the service." > "Implement the service. Make it transactional. Reuse existing get_or_create_tag if it exists." (AI implements; you review each.) ### Polish > "Add tests. Cover: owner tagging own posts; admin tagging others; non-owner trying to tag others (403); empty list of posts." > "Add a docstring to the service function explaining the transactional behavior." (AI adds; you accept or refine.) Total time: 20-40 minutes for a non-trivial feature. ## When to merge phases For tiny features (one file, "Add a /health/db endpoint that returns 200 if DB query succeeds, 503 otherwise. Add a simple test." For medium features: scaffold + fill + polish. For large features: explicit specify + scaffold + multiple fill + polish. ## Pattern: scaffold from data model up Often best to start from the data model: 1. **Spec** the entities and relationships. 2. **Scaffold the schema/migration** (SQLAlchemy + Alembic). 3. **Scaffold Pydantic models** based on DB. 4. **Scaffold service functions** (CRUD basics). 5. **Scaffold endpoints**. 6. **Implement** each layer. 7. **Tests** at each layer. Top-down or bottom-up; consistency matters. ## Pattern: scaffold from API contract Alternative: start from the public interface. 1. **Spec the endpoint contract** (URL, method, request, response). 2. **Scaffold the router** with empty handlers. 3. **Backfill** schemas, service, data layer. 4. **Implement** inward. 5. **Tests**. Outside-in design. Useful when API design is fixed first. ## When generation feels wrong Signs you should stop and rethink: - AI generates a lot of code you don't understand. - Implementation doesn't match your spec — but it's hard to articulate why. - You're rejecting more than accepting. - AI keeps proposing structures that feel off. Solutions: - Go back to spec; what changed?