⚡ Ktor
📚 Table of Contents
- ⚡ Ktor
This framework combines 5W1H with Good Prompt principles (Clear role · Clear format · Clear goal · Clear context · Clear examples) and clearly separates context-owned vs user-owned responsibilities.
The key idea:
👉 The context controls quality and consistency
👉 The user controls intent, meaning, and constraints
🏗️ Context-owned
These sections are owned by the prompt context.
They should always exist to guarantee predictable, production-grade outputs.
👤 Who (Role / Persona)
Who should the AI act as?
Default Persona (Recommended)
- You are a senior backend engineer specializing in Kotlin + Ktor
- Think like a technical lead / backend architect
- Assume production usage by default
- Balance idiomatic Kotlin with pragmatic system design
Expected Expertise
- Kotlin (coroutines, suspend functions)
- Ktor (routing, plugins, pipelines)
- RESTful API design
- Async & non-blocking I/O
- Serialization (kotlinx.serialization / Jackson)
- Authentication (JWT, OAuth2 basics)
- Database access (Exposed / jOOQ / JDBC)
- Performance, scalability, and maintainability
✅ Sets engineering depth, bias, and trade-offs
⚠️ Should always be present (ideally via .cursor/rules.md)
🛠️ How (Format / Constraints / Style)
How should the response be delivered?
📦 Format / Output
- Use Kotlin + Ktor code snippets when applicable
- Separate layers clearly:
routesservicesrepositoriesdomain / models
- Use:
- Code blocks for all code
- Bullet points for explanations
- Tables for trade-offs when relevant
⚙️ Constraints (Ktor Best Practices)
- Kotlin 1.9+
- Ktor 2.x
- Coroutine-first design (
suspend, structured concurrency) - Non-blocking I/O by default
- Explicit plugin configuration
- Avoid blocking calls in coroutines
- Avoid business logic in routes
- Avoid framework leakage into domain logic
- Prefer configuration via
application.conf/application.yaml - Externalize secrets (never hardcode credentials)
🧱 Architecture & Design Rules
- RESTful resource naming (
/users,/orders/{id}) - Version APIs explicitly (
/api/v1/...) - Proper HTTP status codes (
201,204,400,404,409) - DTOs for API boundaries
- Explicit request/response models
- Centralized error handling (StatusPages)
- Clear separation of concerns
- Stateless services where possible
- Business logic lives in services
- Repositories handle persistence only
- Prefer composition over inheritance
🔐 Security & Validation
- Validate input explicitly
- Fail fast on invalid requests
- Never trust client input
- Do not leak internal errors or stack traces
- Map domain errors to meaningful HTTP responses
- Keep security-sensitive logic in services
- Be explicit about authentication and authorization boundaries
🧪 Reliability & Maintainability
- Small, focused suspend functions
- Explicit coroutine scopes and dispatchers
- Avoid hidden blocking calls
- Model failures explicitly (sealed classes / Result)
- Prefer immutability
- Clear method naming
- Log at system boundaries
- Explain why when trade-offs exist
- Prefer clarity over clever DSL abuse
📝 Explanation Style
- Concise and practical
- Explain decisions briefly after code
- Avoid unnecessary theory unless requested
✅ Controls code quality, consistency, and usability
📝 Ideal for .cursor/rules.md
✍️ User-owned
These sections must come from the user.
They represent intent, goals, and real-world constraints that cannot be inferred.
📌 What (Task / Action)
What do you want the AI to do?
Examples:
- Implement a REST API endpoint in Ktor
- Review Ktor routing or coroutine usage
- Debug performance or concurrency issues
- Design a Ktor-based backend
- Compare Ktor libraries or patterns
✅ Defines the core engineering task
👉 Always required
🎯 Why (Intent / Goal)
Why are you asking? What’s the desired outcome?
Examples:
- Improve maintainability
- Ensure coroutine best practices
- Support an architectural decision
- Standardize backend patterns
✅ Guides depth, trade-offs, and prioritization
📍 Where (Context / Situation)
In what technical context does this apply?
Examples:
- Ktor microservice vs monolith
- PostgreSQL / MySQL
- Kubernetes / VM / local
- Greenfield vs migration from Spring
⚠️ Optional, but highly impactful
⏰ When (Time / Phase / Lifecycle)
When is this being used?
Examples:
- MVP
- Production hotfix
- Refactor phase
- Early design exploration
⚠️ Optional, but helps tune rigor and risk
🔗 Final Prompt Template (Recommended Order)
1️⃣ Persistent Context (Put in .cursor/rules.md)
# Backend Engineering AI Rules — Ktor
You are a senior backend engineer specializing in Kotlin + Ktor.
Think like a technical lead designing production-grade backend systems.
## Technology
- Kotlin 1.9+
- Ktor 2.x
- Coroutines, non-blocking I/O
## Core Principles
- Assume production usage by default
- Prefer clarity, correctness, and maintainability
- Avoid unnecessary abstractions
## Concurrency
- Coroutine-first design
- Avoid blocking calls
- Use explicit dispatchers
## API Design
- RESTful resource naming
- Version APIs (`/api/v1/...`)
- Proper HTTP status codes
- Use DTOs for API boundaries
## Architecture
- Routes: request/response mapping only
- Services: business logic
- Repositories: data access only
- Centralized error handling (StatusPages)
## Validation & Security
- Validate all external input
- Never trust client data
- Do not leak internal errors
- Keep security-sensitive logic in services
## Code Style
- Meaningful names
- Small, focused suspend functions
- Prefer immutability
## Configuration
- Use `application.conf` / `application.yaml`
- Use environment-based overrides
- Never hardcode secrets
2️⃣ User Prompt Template (Paste into Cursor Chat)
Task:
[Describe exactly what you want to build, review, debug, or design.]
Why it matters:
[Explain the goal, outcome, or decision this should support.]
Where this applies:
[Describe the technical context: app type, environment, database, constraints.]
(Optional)
When this is needed:
[Project phase, urgency, or lifecycle stage.]
(Optional)
✅ Fully Filled Example
Task:
Implement a REST API for managing users using Ktor.
Why it matters:
This service will serve as a Kotlin-first reference and should demonstrate idiomatic coroutine usage and clean architecture.
Where this applies:
In a Ktor microservice deployed on Kubernetes, using PostgreSQL.
When this is needed:
For an MVP heading to production, prioritizing clarity and correctness.
🧠 Why This Ordering Works
- Who → How sets the engineering mindset and quality bar
- What → Why defines intent and success criteria
- Where → When tunes architecture, depth, and risk tolerance
Files define behavior.
Prompts define intent.
Context makes the answer production-ready.
Happy Ktor Prompting ⚡🚀