Agent-Skills.md

Agent Skills: Skill: Scalable Thinking

Design for scale while keeping implementation simple (KISS).

UncategorizedID: nguyenthienthanh/aura-frog/scalable-thinking

Repository

nguyenthienthanh/aura-frog
nguyenthienthanh
142

Install this agent skill to your local

pnpm dlx add-skill https://github.com/nguyenthienthanh/aura-frog/tree/HEAD/aura-frog/skills/scalable-thinking

Skill Files

Browse the full folder contents for scalable-thinking.

Download Skill

Loading file tree…

aura-frog/skills/scalable-thinking/SKILL.md

Skill Metadata

Name
scalable-thinking
Description
"Design for scale while keeping implementation simple (KISS)."

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Skill: Scalable Thinking

Principle: 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 |

Where to Apply

Data Models

Separate related data into proper tables (not JSON strings). Enables querying, indexing, partitioning.

APIs

RESTful resource paths with versioning: /api/v1/users/:userId/processes. Cacheable, evolvable.

Database

Normalized tables with foreign keys and indexes. Not JSON blobs that can't be filtered.

File Structure

Feature-based: src/features/{feature}/{hooks,components,api}/ + src/shared/.

Scalable Patterns

  • Pagination: Cursor-based ?limit=20&cursor=abc with { nextCursor, hasMore }
  • Centralized config: Single config object with env-based values
  • Structured errors: AppError with code + statusCode

Anti-Patterns

| Anti-Pattern | Instead | |--------------|---------| | Build for hypothetical 1M users | Simple monolith first | | Pre-optimize with Redis | In-memory cache, add Redis when measured | | Abstract for 1 use case | Direct impl, abstract at 2-3 examples | | Microservices from day 1 | Monolith, split when team/features grow |

Checklist

Before designing: Can model support 10x? Can I query needed data? Natural partition keys? API versioned? Pagination for lists?

During: Standard patterns? Simplest solution? Junior dev understandable? No abstractions until 3+ examples?

When to Scale Up

Add complexity when: DB queries > 2s, API p95 > 500ms, error rate > 1%, 10x growth in 3 months, team > 5. Until then: keep simple, measure everything.