Design for scale while keeping implementation simple (KISS).
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: scalable-thinking description: "Design for scale while keeping implementation simple (KISS)." autoInvoke: false priority: high triggers:
Purpose: Design for scale while keeping implementation simple (KISS) Priority: HIGH Auto-invokes: Architecture, API design, data modeling, database schema
"Think Scalable, Build Simple"
| Aspect | Scalable Thinking (WHAT) | KISS (HOW) |
|---|---|---|
| Data Model | Normalized, indexed | Simple queries |
| API | Versioned, RESTful | Standard CRUD |
| Code Structure | Feature-based | Flat hierarchy |
| Config | Centralized | Single file |
❌ Non-Scalable:
interface User {
id: string
preferences: string // JSON string - can't query
}
✅ Scalable (Simple Implementation):
interface User { id: string; name: string; email: string }
interface UserPreference { userId: string; key: string; value: string }
// Simple queries, can index by key, can partition by userId
❌ Non-Scalable:
POST /api/process { everything... }
✅ Scalable (Simple):
POST /api/v1/users/:userId/processes
GET /api/v1/processes/:processId
Benefits: Versionable, RESTful, cacheable, evolvable
❌ Non-Scalable:
CREATE TABLE orders (
id UUID PRIMARY KEY,
items JSON -- Can't filter by item
);
✅ Scalable (Simple):
CREATE TABLE orders (
id UUID PRIMARY KEY,
user_id UUID REFERENCES users(id),
INDEX idx_user_id (user_id)
);
CREATE TABLE order_items (
order_id UUID REFERENCES orders(id),
product_id UUID,
INDEX idx_order_id (order_id)
);
❌ Non-Scalable:
src/utils.ts # 5000 lines
src/components.tsx # All components
✅ Scalable:
src/features/auth/hooks/, components/, api/
src/features/posts/hooks/, components/, api/
src/shared/hooks/, components/, utils/
// ❌ Returns all records
GET /api/users → [...50,000 users]
// ✅ Cursor-based
GET /api/users?limit=20&cursor=abc123
→ { data: [...], pagination: { nextCursor, hasMore } }
const config = {
api: { baseUrl: process.env.API_URL, timeout: 5000 },
features: { /* feature flags */ },
limits: { maxFileSize: 10 * 1024 * 1024 }
}
class AppError extends Error {
constructor(
message: string,
public code: string,
public statusCode: number = 500
) { super(message) }
}
throw new AppError('User not found', 'USER_NOT_FOUND', 404)
| Anti-Pattern | Instead Do |
|---|---|
| Build for hypothetical 1M users | Simple monolith first, scale when data shows need |
| Pre-optimize with Redis | In-memory cache first, add Redis when measured |
| Abstract for 1 use case | Direct implementation, abstract at 2-3 examples |
| Microservices from day 1 | Monolith, split when team/features grow |
Add Complexity When:
Until Then: Keep it simple, measure everything
Remember: Scalable ≠ Complex. Scalable = Can grow. KISS = Simple to maintain.
Applied In: Phase 2 (Design), Phase 5 (Implementation) Version: 1.0.0 | Last Updated: 2025-11-28