agentleFS
marcowuethrichmarcowuethrich/green-print/.claude/skills/kotlin-project-feature-implementation/SKILL.md

kotlin-project-feature-implementation

Skill1 starsChanged 17 days agoMITView on GitHub

Use when implementing or extending a feature in a Kotlin Multiplatform project. Provides pre-coding inspection, KMP source-set discipline, state pipeline design, architectural defaults, security/performance guardrails, and implementation rules. Forward-looking only — not a review skill.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. mimoccc/my-claude-skills★ 198% same

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

92 rules. About 0 are common, 88 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈88

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Use this skill when implementing a new feature or extending an existing flow in a Kotlin Multiplatform project.

    line 14
  2. Distinctive:

    Do not optimize for speed of output alone.

    line 20
  3. Distinctive:

    Do not invent new structure if the codebase already has a valid one.

    line 74
  4. Distinctive:

    Before writing code, understand how the existing app already solves similar problems.

    line 80
  5. Distinctive:

    Do not introduce parallel patterns unless the current pattern is clearly broken and the task explicitly requires changing it.

    line 82
  6. Distinctive:

    keep business logic out of UI

    line 89
  7. Distinctive:

    prefer explicit, readable code over clever abstractions

    line 91
  8. Distinctive:

    Do not start coding before grounding the implementation in the current codebase.

    line 110
  9. Distinctive:

    Follow this workflow for every feature unless explicitly told otherwise.

    line 116
  10. Distinctive:

    Before making changes, produce a short implementation plan that includes:

    line 132
  11. Distinctive:

    Prefer vertical slices such as:

    line 147
  12. Distinctive:

    Avoid broad end-to-end rewrites unless explicitly requested.

    line 155
  13. Distinctive:

    Before considering the task done, check for:

    line 158
  14. Distinctive:

    No ad hoc dependency access in composables

    line 181
  15. Distinctive:

    No repository or data-source calls from UI code

    line 182
  16. Distinctive:

    No business rules in composables

    line 183
  17. Very specific:

    No DTOs or persistence models in UiState

    line 184
  18. Distinctive:

    No platform-specific APIs in shared composables

    line 185
  19. Distinctive:

    Prefer stateless rendering composables where possible

    line 188
  20. Distinctive:

    Keep one-time effects separate from persistent UI state

    line 189
  21. Distinctive:

    When a new reusable UI pattern is needed:

    line 209
  22. Distinctive:

    place it in the right module/file

    line 213
  23. Distinctive:

    Do not over-abstract one-off UI fragments prematurely.

    line 215
  24. Distinctive:

    Do not hardcode user-facing strings.

    line 219
  25. Distinctive:

    All product-facing text should:

    line 221
  26. Distinctive:

    use resource-based strings according to project conventions

    line 222
  27. Distinctive:

    follow the app’s default product tone and language unless the task says otherwise

    line 223
  28. Distinctive:

    use parameterized resources where dynamic values are involved

    line 224
  29. Distinctive:

    Do not become a god object

    line 245
  30. Distinctive:

    Keep lifecycle/platform wiring out of shared state-holder logic unless the project explicitly puts it there

    line 246
  31. Distinctive:

    call use cases/repositories

    line 250
  32. Distinctive:

    do lightweight mapping from domain results into UI state

    line 253
  33. Distinctive:

    Add a domain layer only when at least one of these is true:

    line 277
  34. Distinctive:

    Do not add pass-through use cases to satisfy an architecture diagram.

    line 284
  35. Distinctive:

    Do not merge local and remote state ad hoc in the UI/state holder unless the codebase explicitly already does that and it is justified.

    line 312
  36. Very specific:

    Before placing any new file in commonMain, confirm it is valid for all declared targets.

    line 318
  37. Very specific:

    Do not default to expect/actual before checking whether an interface plus injected implementation would be simpler.

    line 325
  38. Distinctive:

    do not place feature logic inside bridge implementations

    line 328
  39. Distinctive:

    do not place platform APIs in shared code

    line 329
  40. Distinctive:

    prefer shared business logic, mapping, validation, and state logic when it truly applies to all targets

    line 330
  41. Distinctive:

    prefer platform-specific placement for OS integrations, permissions, storage APIs, platform navigation adapters, native SDK interop, or …

    line 331
  42. Distinctive:

    Keep feature changes local to the owning module wherever possible

    line 337
  43. Distinctive:

    Do not bypass module APIs for implementation convenience

    line 338
  44. Distinctive:

    If a change requires touching many modules, treat that as a signal that boundaries may need review.

    line 339
  45. Distinctive:

    Do not let one feature reach directly into another feature’s internal implementation details

    line 341
  46. Distinctive:

    Follow the route model and entry-point patterns already established

    line 347
  47. Distinctive:

    Do not re-architect navigation as part of a feature implementation unless explicitly scoped

    line 348
  48. Distinctive:

    Keep navigation decisions explicit and predictable

    line 351
  49. Distinctive:

    Do not mix navigation events into persistent state

    line 352
  50. Distinctive:

    Do not leak these upward casually.

    line 366
  51. Distinctive:

    use case input/output models

    line 371
  52. Distinctive:

    Do not pollute domain models with:

    line 374
  53. Distinctive:

    Do not pass a single “god model” through all layers just to reduce mapping work.

    line 384
  54. Distinctive:

    If a screen requires a screen-specific projection, create the right UI model instead of overloading a domain model.

    line 393
  55. Distinctive:

    Avoid ambiguous collections of booleans that create contradictory states.

    line 402
  56. Distinctive:

    Do not let multiple unrelated async paths mutate shared state in ways that are hard to reason about.

    line 422
  57. Distinctive:

    Do not create multiple writable sources of truth for the same data type unless this is clearly intentional and carefully coordinated.

    line 446
  58. Distinctive:

    Do not do heavy or repeated work directly inside composables.

    line 471
  59. Distinctive:

    Use side-effect APIs intentionally.

    line 498
  60. Distinctive:

    use stable keys where appropriate

    line 515
  61. Distinctive:

    avoid expensive per-item computation in composition

    line 517
  62. Distinctive:

    avoid re-rendering whole lists due to broad state coupling

    line 518
  63. Distinctive:

    Do not leave expensive work ambiguously on main thread.

    line 525
  64. Distinctive:

    All async work should have clear ownership and lifecycle.

    line 534
  65. Distinctive:

    Do not accidentally swallow cancellation.

    line 542
  66. Distinctive:

    Do not silently fail.

    line 552
  67. Distinctive:

    Use the right abstraction:

    line 561
  68. Distinctive:

    Treat trust boundaries seriously.

    line 598
  69. Distinctive:

    Do not rely on hidden buttons or client-side checks as security.

    line 601
  70. Distinctive:

    Do not surface raw backend/internal errors directly to users unless explicitly appropriate.

    line 632
  71. Distinctive:

    Use the project’s DI pattern consistently.

    line 638
  72. Very specific:

    Before introducing a new component/helper/mapper:

    line 657
  73. Distinctive:

    check for an existing one

    line 658
  74. Distinctive:

    Do not create generic abstractions too early.

    line 667
  75. Distinctive:

    Treat internal code as APIs for future maintainers.

    line 684
  76. Distinctive:

    Write tests alongside implementation, not after.

    line 704
  77. Distinctive:

    Use shared tests where logic is shared.

    line 718
  78. Distinctive:

    Use platform-specific test infrastructure only where the code is actually platform-specific.

    line 719
  79. Distinctive:

    Do not defer meaningful tests unless explicitly told to.

    line 721
  80. Distinctive:

    Do not assume all clients, servers, and data are updated simultaneously.

    line 759
  81. Distinctive:

    Prefer common code unless platform-specific behavior is actually required.

    line 786
  82. Distinctive:

    Do not introduce platform divergence casually.

    line 788
  83. Distinctive:

    Avoid APIs or patterns that make shared code harder to port, test, or maintain.

    line 791
  84. Distinctive:

    Consider whether the implementation will behave consistently on iOS and Android.

    line 794
  85. Distinctive:

    Do not assume behavior that only makes sense for one target.

    line 797
  86. Distinctive:

    When the project has no established feature structure, this shape is a reasonable default:

    line 803
  87. Distinctive:

    Write code as if it must pass:

    line 834
  88. Distinctive:

    When using this skill to guide implementation, produce:

    line 888
  89. Distinctive:

    If the task is clearly an editing task and not just analysis, keep the plan concise and then proceed with implementation.

    line 942
  90. Distinctive:

    When asked to implement a feature, respond in this structure unless told otherwise:

    line 948
  91. Distinctive:

    Do not optimize for cleverness.

    line 977
  92. Distinctive:

    Do not optimize for broad refactors.

    line 978

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Kotlin Multiplatform Feature Implementation

Use this skill when implementing a new feature or extending an existing flow in a Kotlin Multiplatform project.

This skill is forward-looking only. It is not a review skill. It does not produce verdicts or issue severity ratings. For post-implementation or PR review, use kotlin-kmp-code-review instead.

Your job is to deliver production-grade code that fits the existing architecture, respects the shared UI system, preserves module boundaries, and remains easy to maintain over time.

Do not optimize for speed of output alone.
Optimize for correctness, scalability, maintainability, security, consistency, and clean evolution of the existing codebase.


What this skill does

  • Provides a pre-coding inspection checklist to read the codebase before writing anything
  • States the architectural defaults to implement against
  • Gives layer-by-layer implementation rules
  • Defines KMP source-set placement discipline
  • Defines state pipeline and data ownership expectations
  • Enforces shared UI system usage
  • Adds performance, coroutine, concurrency, and security guardrails
  • Defines the expected output format for an implementation plan

Primary goals

For every implementation, optimize for:

  1. Architectural consistency
  2. Small, coherent diffs
  3. Business logic in the right layer
  4. Strong separation of concerns
  5. Model and boundary integrity
  6. Predictable state management
  7. Shared UI system consistency
  8. Composable, reusable design
  9. Compose performance
  10. Coroutine and threading correctness
  11. Concurrency and race-condition safety
  12. Security and privacy safety
  13. Source-of-truth discipline
  14. Testability
  15. Migration and rollout safety
  16. Long-term maintainability

Default architecture assumptions

Unless the project clearly does otherwise, implement features using:

  • UI driven from immutable state
  • user events flowing into a state holder
  • repositories owning data access and coordination
  • domain layer only when business logic is complex, reused, or meaningfully reduces state-holder complexity
  • shared logic in commonMain only when valid for all declared targets
  • platform code at the edges
  • narrow module APIs and cohesive feature ownership
  • tests alongside new logic, not deferred

Do not invent new structure if the codebase already has a valid one. Match conventions unless there is a clear reason not to, and state that reason explicitly in the implementation plan.


Implementation philosophy

Before writing code, understand how the existing app already solves similar problems.

Do not introduce parallel patterns unless the current pattern is clearly broken and the task explicitly requires changing it.

Default behavior:

  • preserve existing architecture
  • extend existing modules rather than creating shadow flows
  • reuse existing components before creating new ones
  • make the smallest coherent implementation that solves the task correctly
  • keep business logic out of UI
  • avoid unrelated refactors
  • prefer explicit, readable code over clever abstractions

Step 0: Read before writing

Inspect the relevant existing feature before writing any code. Identify:

  1. Module boundaries — which modules own the feature area, and what their public APIs are
  2. Source-set placement — what is in commonMain vs platform source sets; where new code belongs
  3. Route and navigation ownership — where routes are defined, how new screens integrate
  4. State-holder pattern in use — ViewModel, presenter, state machine; what the existing contract looks like
  5. Repository and data-source abstractions — existing interfaces, implementations, source-of-truth rules, error model
  6. Domain layer presence and rationale — whether it exists, whether it adds value, whether new logic belongs there
  7. Error-model conventions — exceptions, result wrappers, sealed error types; what the project uses consistently
  8. Existing tests — test locations, test doubles, patterns already established
  9. Shared UI system usage — existing shared components, spacing tokens, typography patterns, strings/localization patterns
  10. Similar flows already implemented — find the closest existing feature and copy the pattern, not just the visual result

Do not start coding before grounding the implementation in the current codebase.


Required workflow

Follow this workflow for every feature unless explicitly told otherwise.

Step 1: Inspect first

Before implementing:

  • identify the feature/module involved
  • identify navigation entry points
  • identify existing presentation/state patterns
  • identify domain/use case patterns
  • identify repository/data/API boundaries
  • identify existing shared UI components
  • identify similar features/screens already implemented
  • identify whether the change belongs in shared code or platform-specific code
  • identify source-of-truth expectations
  • identify security/trust-boundary implications if the feature touches auth, session, deep links, payments, files, web content, roles, or PII

Step 2: Plan before editing

Before making changes, produce a short implementation plan that includes:

  1. files to inspect
  2. files likely to change
  3. new files likely to be added
  4. business logic placement
  5. data ownership and source-of-truth decisions
  6. state pipeline changes required
  7. API/data implications
  8. source-set placement decisions
  9. risks and edge cases
  10. tests that should be added

Step 3: Implement the smallest coherent slice

Implement only what is required for the requested slice.

Prefer vertical slices such as:

  • models + mapper + repository contract
  • ViewModel/state changes
  • UI rendering for known state
  • API integration for one path
  • loading/error handling
  • one interaction flow at a time

Avoid broad end-to-end rewrites unless explicitly requested.

Step 4: Self-check before finishing

Before considering the task done, check for:

  • architecture drift
  • large ViewModels
  • logic in the wrong layer
  • DTO leakage across boundaries
  • ambiguous or contradictory state
  • shared UI system misuse
  • hardcoded strings
  • Compose recomposition risks
  • coroutine/threading issues
  • cancellation and exception handling issues
  • race conditions or duplicate-submission risks
  • source-of-truth confusion
  • security/privacy issues
  • missing tests

Layer-by-layer implementation rules

UI layer

  • Render from immutable UiState
  • No ad hoc dependency access in composables
  • No repository or data-source calls from UI code
  • No business rules in composables
  • No DTOs or persistence models in UiState
  • No platform-specific APIs in shared composables
  • Handle all reachable states explicitly: loading, success, empty, error, partial-data, retry
  • Handle responsive layout needs at this layer, not in lower layers
  • Prefer stateless rendering composables where possible
  • Keep one-time effects separate from persistent UI state

Shared UI system rules

The feature must follow the existing project UI system.

Use and prefer:

  • shared UI components already in the codebase
  • layout abstractions when they already exist and fit
  • spacing tokens instead of ad hoc spacing values
  • shared typography and theme styles
  • project-approved color and styling patterns
  • existing shared primitives before creating new ones

Avoid:

  • hardcoded spacing/dimensions when tokens already exist
  • direct generic Compose primitives when a project abstraction already exists and fits
  • duplicate UI patterns that should become shared components
  • ad hoc styling inconsistent with the rest of the app

When a new reusable UI pattern is needed:

  • extract it cleanly
  • give it a meaningful name
  • keep it focused
  • place it in the right module/file

Do not over-abstract one-off UI fragments prematurely.

Strings and localization rules

Do not hardcode user-facing strings.

All product-facing text should:

  • use resource-based strings according to project conventions
  • follow the app’s default product tone and language unless the task says otherwise
  • use parameterized resources where dynamic values are involved

This applies to:

  • titles
  • labels
  • button text
  • placeholders
  • snackbars
  • empty states
  • error messages
  • helper text
  • accessibility text where relevant

State holder

  • Expose exactly one immutable observable state stream, or the single state output pattern the project uses
  • Separate one-time effects from persistent UiState
  • Consume user actions/events as inputs; do not let UI coordinate work directly
  • Coordinate lower layers; do not own data-layer logic inline
  • Do not become a god object
  • Keep lifecycle/platform wiring out of shared state-holder logic unless the project explicitly puts it there

A state holder is allowed to:

  • receive user intents
  • call use cases/repositories
  • coordinate screen state
  • expose state/effects
  • do lightweight mapping from domain results into UI state

A state holder should not grow into:

  • a workflow engine
  • a validator bag
  • a mapper dumping ground
  • a formatting layer
  • an analytics monolith
  • a place for unrelated helper functions

When complexity rises:

  • extract mappers
  • extract validators
  • extract state transformers/reducers
  • extract use cases/domain services
  • split reusable logic into separate classes/files

Pattern note:
On Android, ViewModel is the standard state holder and integrates with the lifecycle natively. On KMP targets without Android ViewModel, use the equivalent presenter or state-machine pattern the project has established. The shape must remain the same: one observable state output and separate effects regardless of the underlying implementation.


Domain layer

Add a domain layer only when at least one of these is true:

  • the business rule is reused by more than one state holder or flow
  • the business rule is non-trivial and benefits from isolated testing
  • extracting it makes the state holder meaningfully smaller and clearer
  • the logic represents business concepts that should not live in the data or presentation layer

Do not add pass-through use cases to satisfy an architecture diagram.
A use case that only forwards a repository call with no meaningful isolation is net-negative.

Business logic should primarily live here when it is:

  • reusable
  • non-trivial
  • worth testing in isolation
  • needed to keep the state holder focused

Data layer

  • Repositories expose domain-facing interfaces, not DTOs, not persistence schemas, not HTTP response shapes
  • Repositories coordinate local and remote sources internally
  • Callers should not see data-source coordination details
  • DTOs and persistence models live below the repository boundary and do not cross it upward
  • Preserve the project’s established error model consistently across new repositories
  • New data sources must have a single, narrow responsibility
  • Source-of-truth decisions must be explicit

Be clear about:

  • where reads come from
  • where writes go
  • how cache/local/remote coordination works
  • how refresh/invalidation works
  • how optimistic updates reconcile, if applicable

Do not merge local and remote state ad hoc in the UI/state holder unless the codebase explicitly already does that and it is justified.


Source sets

Before placing any new file in commonMain, confirm it is valid for all declared targets.

Decision order:

  1. Does it compile and behave correctly on all targets with no platform-specific API? → commonMain
  2. Is it valid for a platform family? → intermediate source set such as appleMain or iosMain
  3. Does it genuinely differ per target? → platform source set with a shared abstraction in commonMain if needed

Do not default to expect/actual before checking whether an interface plus injected implementation would be simpler.

Additional rules:

  • do not place feature logic inside bridge implementations
  • do not place platform APIs in shared code
  • prefer shared business logic, mapping, validation, and state logic when it truly applies to all targets
  • prefer platform-specific placement for OS integrations, permissions, storage APIs, platform navigation adapters, native SDK interop, or target-specific lifecycle wiring

Module boundaries

  • Keep feature changes local to the owning module wherever possible
  • Do not bypass module APIs for implementation convenience
  • If a change requires touching many modules, treat that as a signal that boundaries may need review; flag it in the plan
  • New public module APIs should be as narrow as needed and no wider
  • Do not let one feature reach directly into another feature’s internal implementation details

Navigation

  • Follow the route model and entry-point patterns already established
  • Do not re-architect navigation as part of a feature implementation unless explicitly scoped
  • Preserve back/up behavior that matches user expectations
  • Model deep-link entry realistically: the back stack after entry should be coherent, not empty
  • Keep navigation decisions explicit and predictable
  • Do not mix navigation events into persistent state

Model and boundary rules

Each layer should speak in the right model type.

Data layer models

Use:

  • DTOs / transport models
  • persistence entities
  • remote/local data-source models

Do not leak these upward casually.

Domain layer models

Use:

  • business-oriented models
  • use case input/output models
  • validation/business concepts

Do not pollute domain models with:

  • Compose/UI concerns
  • persistence-only concerns
  • transport-specific details

Presentation layer models

Use:

  • explicit UI state models
  • screen-specific UI models when needed

Do not pass a single “god model” through all layers just to reduce mapping work.

Mapping rules

Mapping responsibilities must be:

  • explicit
  • predictable
  • easy to discover
  • easy to test

If a screen requires a screen-specific projection, create the right UI model instead of overloading a domain model.


State management rules

State must be predictable and testable.

Prefer explicit state

Avoid ambiguous collections of booleans that create contradictory states.

Prefer:

  • clear state data classes
  • sealed sub-states when appropriate
  • explicit fields with clear ownership
  • state transformations that are easy to follow

Separate durable state from transient effects

Do not mix:

  • screen state
  • navigation events
  • snackbars/toasts
  • permission requests
  • one-time confirmations or one-time errors

Handle transient effects explicitly and safely.

State ownership

A screen’s state should have clear ownership. Do not let multiple unrelated async paths mutate shared state in ways that are hard to reason about.

Avoid impossible states

Always ask:

  • can this screen end up loading and success and blocking error at once?
  • can stale data remain visible incorrectly?
  • can a retried request corrupt the state?
  • can multiple async updates interleave unpredictably?

Data ownership decisions

For each new data type or flow, define:

  • source of truth
  • who owns reads
  • who owns writes
  • whether there is caching
  • whether offline behavior matters
  • how refresh/retry/invalidation works
  • whether partial data is acceptable
  • whether optimistic updates exist and how they reconcile

Do not create multiple writable sources of truth for the same data type unless this is clearly intentional and carefully coordinated.


State pipeline design

For each feature flow, define:

  • UiState shape
  • user actions/events
  • one-time effects
  • loading → success path
  • loading → error path
  • retry path
  • empty-state handling
  • partial-data handling
  • stale-response handling if multiple requests can overlap

State transitions should be explicit and easy to test.


Compose implementation rules

1. Compose is for rendering, not heavy work

Do not do heavy or repeated work directly inside composables.

Avoid in composition:

  • large filtering/sorting/mapping chains
  • expensive derived calculations
  • repeated object creation that could be stabilized
  • broad state observation when a smaller slice is enough

Prefer:

  • precomputed UI state
  • smaller composables
  • stable UI models
  • remember only when justified
  • derivedStateOf only when it materially helps
  • state hoisting where appropriate

2. Recomposition discipline

Implement UI in ways that reduce unnecessary recomposition.

Watch for:

  • unstable parameters
  • lambdas recreated unnecessarily
  • list items depending on overly broad parent state
  • derived values recalculated every recomposition
  • collecting state too high in the tree

3. Side-effects correctness

Use side-effect APIs intentionally.

Be careful with:

  • LaunchedEffect
  • DisposableEffect
  • SideEffect
  • rememberCoroutineScope
  • snapshotFlow

Do not:

  • launch work from composition without lifecycle reasoning
  • use incorrect keys
  • accidentally restart work
  • capture stale values

4. Lazy list discipline

For lists:

  • use stable keys where appropriate
  • extract item content cleanly
  • avoid expensive per-item computation in composition
  • avoid re-rendering whole lists due to broad state coupling

Coroutine and threading rules

1. Use the right dispatcher

Do not leave expensive work ambiguously on main thread.

Be explicit about:

  • IO/network work
  • database/persistence work
  • CPU-heavy transformations
  • testable dispatcher injection if the project pattern expects it

2. Respect structured concurrency

All async work should have clear ownership and lifecycle.

Avoid:

  • detached jobs
  • work that outlives the screen/feature scope unintentionally
  • nested launches that obscure cancellation or sequencing

3. Preserve cancellation semantics

Do not accidentally swallow cancellation.

Be careful with:

  • broad catch
  • blanket runCatching
  • generic failure wrappers that also catch CancellationException

Cancellation is not a normal failure and should usually propagate.

4. Error handling must be intentional

Do not silently fail.

Prefer:

  • explicit error mapping
  • clear UI failure states
  • domain-level error modeling where useful
  • observability for important failures

5. Flow usage must be intentional

Use the right abstraction:

  • Flow
  • StateFlow
  • SharedFlow

Avoid:

  • duplicate collectors without need
  • replay misuse
  • expensive transformations duplicated per collector
  • collecting raw streams in UI when state should already be prepared upstream

Concurrency and race-condition rules

Assume async interactions can race unless you deliberately prevent it.

Design flows to handle:

  • repeated taps
  • duplicate submissions
  • stale responses arriving after newer ones
  • retries
  • refresh while another request is in flight
  • partial failures
  • concurrent state updates

Prefer:

  • explicit coordination
  • deterministic update rules
  • idempotent or guarded submit behavior
  • latest-wins or first-wins semantics chosen intentionally
  • debounce/throttle where necessary

Security and privacy rules

Treat trust boundaries seriously.

Never assume UI gating is real authorization

Do not rely on hidden buttons or client-side checks as security.

Handle sensitive data minimally

Avoid:

  • exposing tokens unnecessarily
  • passing PII through layers that do not need it
  • logging sensitive values
  • including sensitive data in analytics or crash reporting
  • caching sensitive data casually

Be defensive with external input

Be careful with:

  • deep links
  • URLs
  • WebViews
  • file/URI handling
  • backend-provided text/data
  • user-provided input
  • route parameters

Validate and parse defensively.

Session/auth safety

Consider:

  • stale session state
  • logout cleanup
  • resume/re-entry paths
  • expired auth
  • privileged state left hanging after session changes

Error exposure

Do not surface raw backend/internal errors directly to users unless explicitly appropriate.


Dependency injection and construction rules

Use the project’s DI pattern consistently.

Avoid:

  • ad hoc construction of important collaborators inside feature code
  • hidden service locator patterns
  • singleton everything
  • stateful dependencies with overly broad scope

Prefer:

  • explicit dependency injection
  • scope aligned to ownership/lifecycle
  • construction that is easy to test
  • small, well-defined dependency surfaces

Reusability and file organization rules

Reuse before creating

Before introducing a new component/helper/mapper:

  • check for an existing one
  • extend or adapt existing patterns if appropriate

Extract only real reuse

Extract reusable code when:

  • duplication is real
  • the abstraction has a clear name
  • it improves maintainability

Do not create generic abstractions too early.

Keep files focused

Prefer:

  • one meaningful class/component/mapper/validator per file when appropriate
  • discoverable organization
  • focused files

Avoid:

  • giant files with multiple unrelated responsibilities
  • helper types buried inside unrelated files
  • dumping many unrelated private utilities together

Internal API design rules

Treat internal code as APIs for future maintainers.

Prefer:

  • intention-revealing names
  • narrow interfaces
  • immutable public surfaces by default
  • parameters that are hard to misuse
  • cohesive responsibilities

Avoid:

  • boolean parameter smells
  • broad signatures
  • APIs that force callers to know too much
  • weak naming
  • mutable public state unless truly needed

Tests

Write tests alongside implementation, not after.

At minimum, test:

  • state-holder transitions for the new flow
  • loading → success
  • loading → error
  • retry
  • empty/partial-data handling where relevant
  • business rules in new domain use cases, if any
  • repository coordination logic, mappers, and error-handling paths
  • navigation decision logic for any conditional routing
  • parsing/serialization or boundary mapping where important
  • concurrency-sensitive behavior where multiple async paths interact

Use shared tests where logic is shared.
Use platform-specific test infrastructure only where the code is actually platform-specific.

Do not defer meaningful tests unless explicitly told to.


Observability rules

For important flows, make failures diagnosable.

Prefer:

  • meaningful logs where the project expects them
  • explicit failure handling
  • useful diagnostics for critical paths
  • privacy-safe logging and analytics

Avoid:

  • silent failures
  • vague catch-and-ignore code
  • noisy logs with low value
  • logs that expose sensitive data

Backward compatibility and rollout rules

Implement code so it can survive:

  • partial rollout
  • evolving backend schemas
  • missing fields
  • unknown enum values
  • partially available backend functionality
  • migration-sensitive local persistence changes

Prefer:

  • tolerant parsing where appropriate
  • graceful degradation
  • feature isolation
  • rollout-safe assumptions

Do not assume all clients, servers, and data are updated simultaneously.


Accessibility and UX robustness rules

Implement UI that behaves well under:

  • slow network
  • partial data
  • empty states
  • errors
  • retries
  • disabled states

Ensure:

  • users get feedback for important actions
  • retry/recovery paths exist when needed
  • degraded states are understandable
  • accessibility semantics are added where relevant and supported by the existing pattern

KMP-specific rules

Because this is KMP, always consider:

Common vs platform-specific placement

Prefer common code unless platform-specific behavior is actually required.

Do not introduce platform divergence casually.

Portability

Avoid APIs or patterns that make shared code harder to port, test, or maintain.

Cross-platform behavior consistency

Consider whether the implementation will behave consistently on iOS and Android.

Cross-platform threading assumptions

Do not assume behavior that only makes sense for one target.


Recommended feature structure

When the project has no established feature structure, this shape is a reasonable default:

feature-<name>/
  presentation/
    <FeatureName>Screen.kt
    <FeatureName>ViewModel.kt
    <FeatureName>UiState.kt
    <FeatureName>UiAction.kt
    <FeatureName>UiEffect.kt
    <FeatureName>Route.kt
  domain/
    <FeatureName>UseCase.kt
    <FeatureName>Model.kt
  data/
    <FeatureName>Repository.kt
    <FeatureName>RepositoryImpl.kt
    <FeatureName>RemoteSource.kt
    <FeatureName>LocalSource.kt
    <FeatureName>Dto.kt
    <FeatureName>Mapper.kt
  di/
    <FeatureName>Module.kt

The folder shape is not the goal. Cohesive ownership and predictable placement are. Match existing structure unless it is clearly broken.


Lint and static analysis expectations

Write code as if it must pass:

  • ktlint
  • detekt
  • Android/Kotlin lint
  • Compose-specific static analysis where relevant

Avoid:

  • long methods
  • long files
  • high complexity
  • deep nesting
  • magic numbers
  • dead code
  • poor visibility choices
  • nullable misuse
  • misleading scope-function usage
  • unused helpers/imports
  • weak naming

Anti-patterns to prevent

  • starting to write code before reading the existing structure
  • multiple writable sources of truth for the same data type
  • direct repository or data-source access from composables
  • pass-through use cases that add ceremony without isolation benefit
  • DTOs or persistence models flowing into UiState
  • platform-specific APIs in commonMain
  • feature logic embedded in bridge implementations
  • treating loading, error, empty, and partial-data states as afterthoughts
  • inconsistent error modeling relative to the rest of the codebase
  • new module APIs wider than the feature needs
  • massive ViewModels
  • business logic in composables
  • broad state observation causing extra recomposition
  • blocking work on main
  • swallowing cancellation
  • unstructured coroutine launches
  • race conditions in submit/refresh flows
  • duplicated UI patterns that should be components
  • giant files with mixed responsibilities
  • insecure token/session handling
  • sensitive data in logs
  • unclear source of truth
  • brittle schema assumptions
  • APIs that are easy to misuse
  • hardcoded user-facing strings
  • raw spacing/dimensions instead of design tokens where the system already provides them

Required output format

When using this skill to guide implementation, produce:

  1. Pre-coding inspection summary
    • modules and source sets affected
    • state-holder pattern in use
    • repository/data-source conventions observed
    • domain layer presence and rationale
    • error model in use
    • existing UI system patterns
    • existing test patterns
  2. Data ownership decisions
    • source of truth for each new data type
    • who owns writes, who owns reads
    • offline/cache considerations if relevant
  3. State pipeline design
    • UiState shape
    • user actions/events
    • one-time effects
    • loading → success
    • loading → error
    • retry
    • empty state
    • partial-data path if relevant
  4. Layer plan
    • which files to create or modify
    • in which module
    • in which source set
    • what stays in shared code vs platform code
    • domain layer: yes/no and why
  5. Implementation
    • code changes
  6. Tests to add
    • state-holder transition tests
    • domain use case tests if applicable
    • repository/mapper tests
    • concurrency/boundary tests if needed
    • which test source set each test lives in
  7. Risks and edge cases
    • source-set correctness risks
    • navigation edge cases
    • partial-data and error-path risks
    • concurrency/retry risks
    • security/trust-boundary risks
    • configuration/lifecycle edge cases
  8. Assumptions
    • any architectural assumption made that is not directly verified in the codebase

If the task is clearly an editing task and not just analysis, keep the plan concise and then proceed with implementation.


Default response structure

When asked to implement a feature, respond in this structure unless told otherwise:

  1. Pre-coding inspection summary
  2. Data ownership decisions
  3. State pipeline design
  4. Layer plan
  5. Risks and edge cases
  6. Implementation
  7. Tests added or recommended
  8. Assumptions

Final instruction

Implement like an architect who will have to maintain this code for years.

Be strict about:

  • correctness
  • architecture boundaries
  • scalability
  • maintainability
  • consistency
  • performance
  • security
  • privacy
  • testability
  • rollout safety

Do not optimize for cleverness.
Do not optimize for broad refactors.
Optimize for clean, production-grade evolution of the existing codebase.


References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.