Chapter 10: Key Takeaways

Specification-Driven Prompting -- Summary Card

1. Specifications eliminate ambiguity. The single most important reason to write specifications before prompting AI is that they remove the guesswork. Every assumption an AI has to make is an opportunity for error. A formal specification replaces assumptions with explicit requirements.

2. There are four levels of specification precision. From vague idea to rough description to detailed description to formal specification, each level produces increasingly predictable AI output. The investment in moving from Level 2 to Level 4 typically pays for itself in reduced iteration time.

3. Requirements documents translate directly into AI prompts. Functional requirements (what the system must do) and non-functional requirements (how well it must do it) both guide AI code generation. Non-functional requirements are particularly important because AI rarely infers performance, security, or reliability needs on its own.

4. User stories with acceptance criteria are highly effective prompts. The GIVEN/WHEN/THEN format maps naturally to test cases and eliminates ambiguity about expected behavior. Always include acceptance criteria; a user story without them is too vague for reliable AI code generation.

5. API-first development produces the most predictable results. OpenAPI and GraphQL SDL specifications are among the most effective prompt formats because they are structured, unambiguous, and extremely well-represented in AI training data. Writing the API spec first and having AI implement it consistently produces high-quality code.

6. Database schemas are foundational specifications. Errors in data modeling propagate to every component. Always specify your schema formally (SQL DDL, Pydantic models, or JSON Schema) before asking AI to generate data access code. Include constraints, indexes, and relationships.

7. Test-first prompting is the most precise specification method. Writing tests before implementation defines exact inputs, exact outputs, and exact edge cases. The AI has no room for misinterpretation, and you have an immediate way to verify the output. This is the closest to a guarantee of correctness you can get with AI.

8. Interface specifications promote modularity. Python Protocols, abstract base classes, and Design by Contract (preconditions, postconditions, invariants) define component boundaries clearly, leading to more modular and maintainable AI-generated code.

9. Configuration specifications prevent deployment surprises. Specifying environment-specific settings, distinguishing between hardcoded defaults and environment variables, and defining different configurations for development, testing, and production prevents a whole class of issues.

10. Reusable specification templates accelerate your workflow. Building a library of templates for common project types (microservices, CLI tools, CRUD applications) lets you quickly adapt proven structures to new projects instead of starting from scratch each time.

11. Not everything needs a formal specification. Utility functions, prototypes, and exploratory work are better served by conversational prompting. Apply the 80/20 rule: focus your specification effort on the 20% of code that contains 80% of the complexity.

12. Use incremental specification for real projects. Start with rough descriptions, identify the critical parts, formalize those, and progressively add formality as the system matures. You do not need a complete specification before writing any code.

13. Watch for signals. If AI keeps repeating the same mistakes, if generated components do not work together, or if you keep correcting data types, you need more specification. If you spend more time writing specs than the AI spends generating code, you may be over-specifying.

14. Multiple specification types work together. The most comprehensive approach combines a database schema (data layer), an API specification (interface layer), and a test suite (behavior layer). Together, these three cover the dimensions most prone to AI generation errors.

Quick Reference: When to Use Each Specification Type