Recap — The Prompt-Engineering Primer for Code

# The Prompt-Engineering Primer for Code The single biggest controllable variable in AI-assisted coding quality is YOUR prompts. Better prompts → better code. Three principles. ## Principle 1: Specificity Vague: > "Make this faster." Specific: > "This function takes 2s on a 100K row dataframe. Profile and identify the bottleneck; optimize to under 500ms while keeping the same output. Likely candidates: the nested loop in process_row; the repeated pd.concat in merge_results." Difference: - Concrete metric (2s → 500ms). - Identifies the target (this function). - Suggests where to look (specific lines). - Specifies invariant (same output). AI now knows what to do AND what good looks like. ## Principle 2: Context Vague: > "Write a function to validate user input." With context: > "Add a validator for our User model (in src/models.py). Should validate email (RFC 5322 format), name (2-50 chars, no special chars), and age (13-120). Follows the existing validator style in src/validators.py (uses Pydantic v2 field_validators)." Difference: - Points to existing files. - References established patterns. - Specifies the validation library. - Defines exact rules. AI doesn't have to guess your conventions. ## Principle 3: Constraints Vague: > "Add a feature to log users in." With constraints: > "Add JWT-based login. Use the existing User model. Hash passwords with bcrypt. JWT expires in 15min. Refresh token expires in 30 days, stored in refresh_tokens table. Don't break existing tests. Add tests for happy path + invalid password + expired token + missing token." Difference: - Auth scheme specified (JWT, not sessions). - Library specified (bcrypt). - Token lifetimes given. - Test cases listed. - Backward compat mandated. AI builds within the lines you drew. ## The S-C-C template For non-trivial requests: ``` [Specificity] - What you want, concretely. - Definition of done. - Success metrics if applicable. [Context] - Relevant files / functions. - Existing patterns to follow. - Domain background if non-obvious. [Constraints] - What NOT to do. - Libraries / styles required. - Performance / compatibility requirements. - Test cases to cover. ``` Not every prompt needs all three. Trivial requests ("add a docstring to this function") need none. Big features need all. ## Examples by task type ### Generating new code Bad: > "Write a rate limiter." Better: > "Add a rate-limit middleware to our FastAPI app. Should use the sliding window counter algorithm. Limits: 100 req/min per IP for unauthenticated; 1000 req/min per user_id for authenticated. Store counters in Redis (already initialized in app.state.redis). Return 429 with X-RateLimit-* headers. Reference existing middleware in src/middleware.py for style." Specificity + context + constraints all present. ### Debugging Bad: > "Why doesn't this work?" Better: > "This function returns None when it should return the user dict. Input: user_id=42. Expected: {id:42, name:..., email:...}. Actual: None. The DB has the user (I verified directly). Walks through this function step by step; identify where None comes from." Bad debugging prompts: 'fix it' (AI fumbles). Good: 'here's the input, the expected, the actual; investigate'. ### Refactoring Bad: > "Clean this up." Better: > "Refactor this function to be more testable. Extract the database call into a separate function that can be mocked. Don't change the public signature or behavior. Add type hints. Keep all logging." Specifies what 'clean' means + invariants. ### Code review Bad: > "Is this good?" Better: > "Review this PR. Focus on: 1) error handling (we missed some cases recently); 2) test coverage (especially edge cases); 3) potential race conditions. Don't comment on style — we have ruff for that. Comment in [must-fix] / [suggest] / [nit] format." Tells the AI what to look at AND what NOT to comment on. ### Documentation Bad: > "Add docs." Better: > "Write a usage guide for this module aimed at someone integrating it for the first time. Include: 1-paragraph overview; setup steps; minimal example; common patterns; gotchas. Tone: technical but conversational. Length: ~500 lines markdown." ## Prompt iterations First prompt rarely perfect. The dance: 1. Initial prompt. 2. AI generates. 3. Review output. 4. Refine prompt: "Good, but the function should also handle None inputs. Also, use logging.info instead of print." 5. AI revises. 3-5 iterations is normal for non-trivial work. ## Anti-patterns ### Don't say "do your best" AI has no preference. Specify the result. ### Don't apologize in prompts "I know this is complex but if you could just..." wastes tokens. ### Don't be defensive "You probably can't do this but..." → AI takes the opt-out. ### Don't ask "should I do X?" if you know "Should I use Redis or Memcached for this cache?" If you know Redis, just say "use Redis". ### Don't repeat in chat what's in context AI sees the file. "The code is..." waste. ## Reference patterns Prov