Skip to content

binayshaw7777/Leaflekt-Maps / .agents/skills/clean-code

clean-code

Verified

ALWAYS invoke this skill before writing, editing, generating, or refactoring ANY code. Do not write or modify code directly without first loading and following these Clean Code guidelines. Use when writing new functions/classes, refactoring existing code, reviewing code, fixing bugs, or any task that produces code output.

FileKindSize
SKILL.mdskill md4.2 KB
references/api_dto_clean.mdmarkdown3.0 KB
references/classes.mdmarkdown6.9 KB
references/comments.mdmarkdown5.7 KB
references/dataToDomainFlow.mdmarkdown7.4 KB
references/error-handling.mdmarkdown8.8 KB
references/formatting.mdmarkdown4.9 KB
references/functions.mdmarkdown12.9 KB
references/naming.mdmarkdown4.0 KB
references/rules-card.mdmarkdown3.6 KB
references/testing.mdmarkdown7.3 KB

references/api_dto_clean.md

View on GitHub
# API DTO Design Skills (KMP)

This guide defines how to design and manage Request and Response data classes (DTOs) in a clean, scalable way across a Kotlin Multiplatform project.

---

## Core Principle

DTOs are data carriers — nothing more.

- No business logic
- No UI logic
- No formatting logic
- Only serialization and deserialization

---

## Project Structure

Organize DTOs by feature and type:

```text
data/
 └── remote/
      └── auth/
           ├── request/
           ├── response/
           └── mapper/
```

---

## Naming Conventions

**Requests** — always end with `Request`
- `LoginRequest`
- `RegisterRequest`
- `GoogleLoginRequest`

**Responses** — always end with `Response`
- `AuthTokensResponse`
- `UserProfileResponse`

---

## DTO Rules

### 1. Keep DTOs Minimal

Only include fields required by the API contract.

```kotlin
@Serializable
data class LoginRequest(
    val email: String,
    val password: String,
)
```

---

### 2. Match Backend Naming

If the backend uses the same field names, no annotation is needed. If names differ, use `@SerialName`.

```kotlin
@SerialName("id_token")
val idToken: String
```

---

### 3. Nullable Fields

Use `?` only when the API can actually return null. Avoid adding nullability as a precaution.

---

### 4. Default Values

Use defaults only when:
- The API allows missing fields
- Safe parsing is required

```kotlin
val profilePictureUrl: String? = null
```

---

## Mapping

Never use DTOs directly in business logic. Always map to a domain model first.

```kotlin
fun AuthTokensResponse.toDomain() = AuthTokens(
    accessToken = accessToken,
    refreshToken = refreshToken
)
```

This is the most important rule in DTO design. The mapper is the boundary between the API layer and the rest of the application.

---

## What Not to Do

- Do not add validation logic inside DTOs
- Do not add UI formatting or utility functions
- Do not reuse the same DTO across multiple layers
- Do not expose DTOs to the UI layer

---

## Separation of Concerns

| Layer | Responsibility |
|-------|---------------|
| DTO | API contract only |
| Domain | Business logic |
| UI | Presentation |

---

## KMP Best Practices

- Annotate all DTOs with `@Serializable`
- Keep DTOs platform-independent
- Avoid platform-specific types in shared DTO classes

---

## Versioning and Safety

- Add new fields as nullable to avoid crashes on older API versions
- Never remove fields without coordinating with the backend team

---

## Example Flow

```text
UI → Domain Model → Mapper → DTO → API
API → DTO → Mapper → Domain Model → UI
```

---

## Pre-Implementation Checklist

Before adding a new DTO:

- [ ] Is it API-specific and nothing else?
- [ ] Does the name end with `Request` or `Response`?
- [ ] Are there any unnecessary fields?
- [ ] Is there any logic inside? (there should be none)
- [ ] Is the mapper implemented?

---

## The Final Rule

> DTOs should be boring. If they feel smart, you are doing it wrong.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall