Best Practices
Proven strategies for AI specifications
Best Practices for AI Specifications
Proven strategies to create specifications that AI builders implement flawlessly
The AI Communication Framework
AI builders think differently than human developers. They excel at following explicit instructions but struggle with implied context. This framework ensures your specifications translate perfectly into working code.
Context is King
Technical Stack Context
Always specify your complete technical environment:
Tech Stack: - Framework: Next.js 14 with App Router - UI: shadcn/ui with Tailwind CSS - Database: PostgreSQL with Prisma ORM - Auth: NextAuth.js with Google OAuth - State: React Context + useReducer - Testing: Jest + React Testing Library - Deployment: Vercel
This context helps AI choose appropriate patterns and libraries.
Business Logic Context
Explain the business rules and constraints:
Business Rules: - Users can only edit their own posts - Free tier limited to 5 projects - Email verification required for publishing - Soft delete with 30-day recovery - GDPR compliance for EU users
AI needs explicit business logic to implement proper validation and flows.
The Specification Pyramid
Implementation Details
Code examples, API schemas, component props
Technical Requirements
Architecture, patterns, integrations, constraints
Functional Requirements
Features, user stories, acceptance criteria, workflows
Business Context
Purpose, goals, users, constraints, success metrics
Start broad with business context, then get increasingly specific toward implementation details
Error Prevention Strategies
Define All States
AI needs explicit guidance for every possible state:
- • Loading states: Show spinners for operations over 300ms
- • Empty states: Friendly messages with action prompts
- • Error states: User-friendly messages with retry options
- • Success states: Confirmation with next step guidance
- • Offline states: Graceful degradation or caching
Specify Validation Rules
Include comprehensive validation specifications:
Email validation: - Required field - Valid email format - Maximum 255 characters - Check for disposable email domains - Real-time validation on blur - Show "Email already exists" if duplicate
Data Flow Documentation
Example: User Registration Flow
- User enters email and password on /signup form
- Client validates input (email format, password strength)
- POST /api/auth/signup with { email, password }
- Server checks if email exists, hashes password
- Creates user record with emailVerified: false
- Sends verification email via email service
- Returns success response (no sensitive data)
- Client shows "Check your email" confirmation
- User clicks verification link: GET /api/auth/verify?token=xxx
- Server validates token, updates emailVerified: true
- Redirects to /dashboard with success message
This level of detail helps AI implement the exact flow you envision.
Platform-Specific Best Practices
Performance Requirements
Be specific about performance expectations:
- • Page load: Under 2 seconds on 3G
- • API response: Under 200ms average
- • Bundle size: Under 500KB initial
- • Lighthouse score: 90+ on all metrics
Accessibility Standards
Include WCAG 2.1 AA compliance requirements:
- • Keyboard navigation for all interactive elements
- • ARIA labels for screen readers
- • Color contrast ratio 4.5:1 minimum
- • Focus indicators visible and clear
Quality Checklist
Before AI Generation
Technical stack specified
Business rules documented
User stories include acceptance criteria
Error states defined
Data validation rules included
Performance requirements set
After AI Implementation
All user stories implemented
Error handling works correctly
Validation prevents invalid data
Accessibility requirements met
Performance targets achieved
Tests pass and coverage adequate
Common Anti-Patterns
Avoid These Mistakes
- • "Make it responsive" without breakpoint specifications
- • "Handle errors gracefully" without defining error scenarios
- • "Optimize performance" without measurable criteria
- • "Follow best practices" without specifying which practices
- • "Make it secure" without security requirements
- • "Add proper validation" without validation rules
Best Practices
- • Specify breakpoints: mobile (320px), tablet (768px), desktop (1024px)
- • Define error scenarios: network failures, validation errors, 404s
- • Set performance targets: LCP under 2.5s, CLS under 0.1
- • Reference specific patterns: "Use React Hook Form with Zod validation"
- • List security measures: HTTPS, CSRF protection, input sanitization
- • Detail validation rules: required fields, formats, length limits