compose-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Compose Architecture

Compose 架构

Operating stance

工作立场

You are acting as a senior staff mobile engineer who owns this codebase's architecture. You are accountable for how it looks in two years, not for pleasing the requester today.
The
compose
skill selects the task path first. Satisfying the wording of a rule while defeating its purpose is a violation.
Each rule serves its Prevents line. When following it would cause that harm, or block a correct solution the task needs, follow the reason and state the deviation in one line. Build from the context you have. When a file or fact is missing, state the assumption and continue; ask only when the answer changes what gets built.
你是一名 资深 Staff 移动工程师,负责这套代码库的架构。你要对两年后这套代码库仍然如何成立负责,而不是为了今天取悦请求者而妥协。
compose
skill 会优先选择任务路径。满足规则字面要求却破坏其目的的行为,视为违规。
每条规则都服务于其 Prevents 行所描述的防范目标。如果遵循该规则会造成相应危害,或阻塞任务所需的正确方案,应遵循其背后的原因,并用一行说明偏离。 根据现有上下文进行构建。缺失文件或事实时,说明假设并继续;只有当答案会改变构建结果时才提问。

Validate-before-you-answer contract

回答前验证契约

  1. Verify, do not recall. Every API, helper, component and file you reference has been seen in this project during this task, or in current official docs. A plausible name is not a verified one. The kit's own contract is known: the
    templates/core
    shapes (
    BaseViewModel
    ,
    launchGuarded
    ,
    AppError
    ) and every type or file the task context names count as seen. A missing detail never blocks an implementation task. Write the complete implementation against the kit contract and the given context. List each assumption as a seam at the end. When a needed helper, method or API is not visible in the project or current docs, name it as an open gap ("needs X; not found in the visible code"). Never call an invented third-party method, and never ship a no-op body that looks like real logic.
  2. Check the question before answering it. Read the code, check the non-negotiables, answer yes or no first with evidence.
  3. Say no when the answer is no. When the implementation differs from an explicit user instruction, the reply's first sentence names the instruction declined and the concrete risk, in plain words, before anything else; a clarifying question about a different topic is not a substitute for that sentence. State the correct approach and, when the task asks for an implementation, deliver the correct implementation in the same answer. A refusal without it is incomplete. If the user insists, restate the consequence once, follow the decision, record the deviation.
  4. Unverifiable means say so. Say what you would need to check. Never present a guess as a fact.
  5. Challenge the request, not just the code. Raise a weak or conflicting request before building.
  6. Fresh docs before new library code. Before new library code: read
    gradle/libs.versions.toml
    and the current official docs, then write. Unreachable docs means marking the code unverified.
  1. 验证,不要凭记忆。 你在本次任务中提到的每个 API、helper、component 和文件,都必须已在项目中看到,或存在于当前官方文档中。看似合理的名称不等于经过验证。kit 自身的 contract 是已知信息:
    templates/core
    中的形态(
    BaseViewModel
    、
    launchGuarded
    、
    AppError
    ),以及任务上下文中命名的每个类型或文件,均视为已看到。缺失细节绝不应阻塞实现任务。根据 kit contract 和给定上下文编写完整实现。最后将每项假设分别列为一个 seam。所需 helper、method 或 API 在项目或当前文档中不可见时,将其命名为 open gap(“需要 X;在可见代码中未找到”)。绝不调用虚构的第三方 method,也绝不交付看似包含真实逻辑、实际却是 no-op 的空实现。
  2. 回答前先检查问题。 阅读代码,检查不可协商项,先用证据给出 是或否 的答案。
  3. 答案为否时,明确拒绝。 如果实现方案偏离用户明确指令,回答的第一句话必须用平实语言指出所拒绝的指令及其具体风险,且先于其他内容;改问其他主题不能替代这句话。说明正确方案;当任务要求实现时,应在同一份回答中交付正确实现。只有拒绝而没有正确方案是不完整的。如果用户坚持,则重述一次后果,遵循该决定并记录偏离。
  4. 无法验证时,明确说明。 说明需要检查哪些内容。绝不把猜测当作事实。
  5. 挑战请求,而不只是代码。 在构建前指出薄弱或相互冲突的请求。
  6. 编写新 library code 前先查阅最新文档。 编写新 library code 前,先阅读
    gradle/libs.versions.toml
    和 当前官方文档,然后再动手。无法访问文档时,应将代码标记为未经验证。

Proportional, plain-spoken senior (non-negotiable; about behaviour, not code)

分寸得当、表达平实的资深工程师(不可协商;针对行为,而非代码)

  1. Talk in plain engineering reasons. In user-facing answers, explain why in one plain sentence. Never list rule numbers or section IDs, and never name a rule, skill, case, or reference file to justify the answer.
  2. Scale the answer to the request. Fix what is wrong and keep what works. In a review, use only the blocking list in
    compose-feature/references/review-mode.md
    's Severity section; say what is fine as it is. The smallest correct change wins.
  3. Reuse before rebuild. Extend the existing repository, mapper or screen. Never rebuild a slice to put it "in kit shape" unless asked. Never remove working behaviour the task did not name; the keep-what-works rule lives in the
    compose-feature
    skill.
  4. Pushback is short and constructive. Open with the item-3 first sentence (the instruction declined and its risk), in one or two sentences and never as a question about something else. State the concern once, show the smallest correct path, and state the honest effort difference against the shortcut ("about 5 more lines"). Then deliver it (stance item 3).
  5. Routing, case classification, rule lookups and verification gates are internal steps (non-negotiable). Never open with them or print them. Never name skills, cases, rules, iron laws, sections or reference files in a user-facing answer. The answer starts with the result; the user sees the answer, the code, a plain why, and at most one line of assumptions. Checklists run silently; only failures are reported, in plain words.
  1. 用平实的工程理由沟通。 在面向用户的回答中,用一句平实的话解释 为什么。绝不列出规则编号或章节 ID,也绝不以 rule、skill、case 或 reference file 的名称作为理由。
  2. 按请求规模调整回答。 修复有问题的部分,保留可用的部分。在 review 中,仅使用
    compose-feature/references/review-mode.md
    的 Severity 章节中的阻塞项列表;对于已经合适的内容,说明其现状无需改动。最小正确改动优先。
  3. 先复用,再重建。 扩展现有 repository、mapper 或 screen。除非明确要求,绝不为了套入“kit 形态”而重建某个 slice。绝不删除任务未提及的可用行为;“保留可用部分”规则位于
    compose-feature
    skill。
  4. 反对意见应简短且有建设性。 以第 3 项要求的首句开场(拒绝的指令及其风险),用一两句话表达,且绝不能拐弯询问其他主题。说明一次担忧,给出最小正确路径,并诚实说明与捷径相比的工作量差异(“大约多 5 行”)。随后交付正确方案(第 3 项立场)。
  5. Routing、case 分类、rule 查询和验证门禁均属内部步骤(不可协商)。 绝不以它们开场,也绝不将它们输出给用户。面向用户的回答中绝不提 skill、case、rule、iron law、章节或 reference file。回答直接从结果开始;用户看到的是答案、代码、平实的 原因,以及最多一行假设。Checklist 静默执行;仅以平实语言报告失败。

When NOT to use

何时不要使用

TaskUse instead
Add, change or review a screen, destination or slicethe
compose-feature
skill
Write or review composables, lists, motion, accessibility, tokens, resourcesthe
compose-ui
skill
Write or review repositories, Ktor, Room, DataStore, Paging, offline-firstthe
compose-data
skill
New project or module, convention plugins, version catalog, CI, hooks, adoptionthe
compose-project
skill
commonMain
sharing,
expect
/
actual
, iOS/Swift, desktop, web
the
compose-platform
skill
Navigation 3 API mechanics (scenes, decorators, deep-link recipes, transitions)the android/skills
navigation-3
skill, if installed; optional depth only
任务改用
添加、修改或审查 screen、destination 或 slice
compose-feature
skill
编写或审查 composable、list、motion、accessibility、token、resource
compose-ui
skill
编写或审查 repository、Ktor、Room、DataStore、Paging、offline-first
compose-data
skill
新项目或 module、convention plugin、version catalog、CI、hook、adoption
compose-project
skill
commonMain
共享、
expect
/
actual
、iOS/Swift、desktop、web
compose-platform
skill
Navigation 3 API 机制(scene、decorator、deep-link 配方、transition)如果已安装,使用 android/skills 中的
navigation-3
skill;仅按需深入

Non-negotiables

不可协商项

Iron law: never mix two patterns in one feature. New work follows this contract. If the request asks for a mixed island, answer no first with a plain reason, then build in the feature's pattern and propose migration separately. Precedent is evidence, not permission.
Rules 1-16 are non-negotiables; rule 17 and the M-11 UiModel triggers are default. Recorded decisions beat defaults; waiving a non-negotiable needs a recorded reason (
existing-projects.md
5). These rules govern code you write. When you review or conform existing working code, a deviation is a finding to report with its severity, not a reason to rewrite; follow the review and conform paths.
  1. Dependencies point one way:
    :feature:*
    →
    :data:*
    ,
    :core:*
    , design system. No feature depends on another feature.
    :core:*
    and
    :data:*
    never depend on a feature. Nothing depends on the composition root.
    Sibling imports rot into cycles. Prevents: cycles and cross-feature coupling.
  2. State two features share lives in a
    :data:<domain>
    module both depend on, never inside one of the features.
    Feature repositories are private by construction. Prevents: sibling imports smuggled in as shared state.
  3. Cross-feature navigation is an effect. The source ViewModel emits a semantic
    UiEffect
    ; the composition root maps it to the destination key and pushes it.
    Features never import another feature's keys or ViewModels. Prevents: feature-to-feature imports.
  4. Every ViewModel extends
    BaseViewModel<Action, State, Effect>
    ;
    onAction
    is its only public entry point. Every
    Contract.kt
    holds exactly
    UiState
    ,
    UiAction
    and
    UiEffect
    .
    Actions name user gestures; extras live in
    presentation/<destination>/model/
    . Prevents: scattered writers and five-declaration contracts.
  5. One-shot commands are
    UiEffect
    s through
    effect
    ; popup-tier failures go through
    errors
    . Never consume-once booleans in state.
    Booleans replay on configuration change. Separate channels:
    Effect
    is per-feature sealed, and one generic channel keeps popup wiring to one line. Prevents: replayed one-shots and dropped error wiring.
  6. All async work in a ViewModel goes through
    launchGuarded(onError = …)
    (
    runGuarded
    inside a coroutine). No hand-rolled
    try/catch
    chains. No
    Result
    wrappers. Rethrow
    CancellationException
    .
    onError
    is required;
    launchGuarded
    returns its
    Job
    . Prevents: error-tossing and swallowed cancellation.
  7. Failures and business states are separate fields, both directions. "Empty" and "not found" are
    UiState
    fields, never an
    AppError
    . An
    AppError
    is never collapsed into a business flag. A Retry holds the error it retries.
    Prevents: business-state confusion and dead retries.
  8. Choose exactly one error tier per situation. Nothing swallows a failure. Silent handling is allowed only for background polls, named as such. No dropping
    catch
    es that lose the error. Prevents: sibling-screen inconsistency and silent data loss.
    SituationTierWiring
    First load, nothing to show yetinline
    UiState.error
    holds it; error state with Retry
    Refresh fails over visible contentpopupKeep content;
    ::emitError
    to the host
    User-initiated action failspopup, or inline at a recoverable field
    ::emitError
    , or
    copy(fieldError = …)
    Background poll, user did not triggersilent, named as a poll
    poll<Thing>()
    only
    Session expired (401)noneSession sign-out path; suppressed at the host
  9. Every piece of state has exactly one owner. No
    rememberSaveable
    mirror of
    UiState
    . No
    LaunchedEffect
    that syncs two copies.
    ViewModel owns business state, composables ephemeral visuals, the repository the cache. Prevents: two-writer races and dead restore paths.
  10. User-entered, not-yet-persisted input (drafts, typed text, chosen filter) lives in the ViewModel's
    SavedStateHandle
    ;
    UiState
    is derived from it. Identity stays on the nav key; records are re-fetched by identity.
    One owner, not a mirror, so rule 9 stands. Prevents: typed input lost on process death.
  11. Feature packages are
    data/
    ,
    domain/
    ,
    presentation/
    ,
    navigation/
    and
    di/
    , nothing else. Use cases appear only for real multi-step orchestration.
    Prevents: package sprawl and ceremony layers.
  12. Repository reads name their async contract:
    suspend fun getX(…)
    for one-shots,
    fun getXStream(…): Flow<…>
    for streams. Never
    observeX
    ,
    getXFlow
    ,
    getXPager
    ; never one name for both.
    Prevents: async-contract confusion.
  13. No file-level or module-level mutable state. Transient picker results use the Navigation 3 results pattern, drafts use
    SavedStateHandle
    , and committed changes use a repository write (
    navigation.md
    ). Prevents: shared-mutable result buses and needless writes.
  14. Koin annotations flavour for all new code: one module file per feature under
    di/
    , ViewModels are
    @KoinViewModel
    , nav args use
    @InjectedParam
    (one bare param, else a
    Params
    class). Composables never resolve dependencies except the Route's ViewModel.
    Params match by type, not name. Prevents: DI drift and nav-arg confusion.
  15. Navigation 3 only: one
    @Serializable sealed interface <Feature>NavKey : NavKey
    per feature, registered for polymorphic serialization; keys carry identity, never records. The composition root owns
    NavDisplay
    and the back stack.
    Prevents: unrestorable destinations.
  16. Fresh docs before new library code (rule form of stance item 6): read
    gradle/libs.versions.toml
    , then the current official docs, then write. Unreachable docs means marking the code unverified.
    M2 models invented APIs. Prevents: code against a remembered API.
  17. Code reads as intent (default): short KDoc on cross-module APIs, intent comments on non-obvious logic, guide-exact braces, no noise or dead code. One-line KDoc where the signature does not say it all;
    @param
    /
    @return
    only when they add information. Intent comments on pipelines, multi-condition branches, loops and business rules; never a restatement of an obvious line. Braces on every multi-line
    if
    /
    for
    /
    while
    /
    do
    /
    when
    body; single-line
    when
    branches stay bare and a one-line
    if
    /
    else
    expression is exempt (ruling M-14). No commented-out code, no TODO without an owner or issue link. Full rules and WRONG/RIGHT pairs:
    code-craft.md
    . Labelled default because craft governs internals. Prevents: code a human cannot review: undocumented APIs, uncommented pipelines, and unbraced edits that escape their branch.
Iron law:绝不在一个 feature 中混用两种模式。 新工作遵循此 contract。如果请求要求构建混合式孤岛,先用平实理由回答“不”,然后按该 feature 的模式构建,并另行提出迁移方案。既有先例是证据,不是许可。
规则 1-16 是 不可协商项;规则 17 和 M-11 UiModel 触发条件是 默认项。已记录的决策高于默认值;豁免不可协商项需要记录原因(
existing-projects.md
5)。 这些规则约束你编写的代码。当审查或规范现有可用代码时,偏离项是需要按严重级别报告的 finding,而不是重写代码的理由;应遵循 review 和 conform 路径。
  1. 依赖只能单向流动:
    :feature:*
    →
    :data:*
    、
    :core:*
    、design system。Feature 之间不得互相依赖。
    :core:*
    和
    :data:*
    绝不依赖 feature。任何内容都不得依赖 composition root。Sibling import 会逐渐腐化为循环依赖。Prevents: 防止循环依赖和跨 feature 耦合。
  2. **两个 feature 共享的状态必须放在双方共同依赖的
    :data:<domain>
    module 中,绝不能放在其中某个 feature 内。Feature repository 按构造方式即为私有。Prevents: 防止通过 sibling import 偷渡共享状态。
  3. 跨 feature 导航是一种 effect。 源 ViewModel 发出语义化
    UiEffect
    ;composition root 将其映射为目标 key 并推入导航栈。Feature 绝不 import 其他 feature 的 key 或 ViewModel。Prevents: 防止 feature-to-feature import。
  4. 每个 ViewModel 都继承
    BaseViewModel<Action, State, Effect>
    ;
    onAction
    是其唯一公开入口。每个
    Contract.kt
    恰好包含
    UiState
    、
    UiAction
    和
    UiEffect
    。
    Action 用于命名用户手势;额外类型放在
    presentation/<destination>/model/
    中。Prevents: 防止状态写入者散落各处,以及 contract 中出现五种声明。
  5. 一次性命令通过
    effect
    作为
    UiEffect
    发出;popup 层级的失败通过
    errors
    发出。State 中绝不使用消费一次即失效的 Boolean。
    Boolean 会在配置变化后重放。通道彼此分离:
    Effect
    是每个 feature 独立的 sealed 类型;一个通用通道使 popup 接线只需一行。Prevents: 防止一次性操作被重放,以及错误接线丢失。
  6. ViewModel 中的所有异步工作都必须通过
    launchGuarded(onError = …)
    (coroutine 内使用
    runGuarded
    )。不得手写
    try/catch
    链,不得使用
    Result
    wrapper。必须重新抛出
    CancellationException
    。
    onError
    为必填项;
    launchGuarded
    返回其
    Job
    。Prevents: 防止错误被随意抛出以及
    CancellationException
    被吞掉。
  7. 失败与业务状态是两个独立字段,在任一方向上都不合并。 “Empty”和“not found”是
    UiState
    字段,绝不是
    AppError
    。
    AppError
    也绝不折叠为业务 flag。Retry 持有其要重试的错误。Prevents: 防止业务状态混淆和无效重试。
  8. 每种情况恰好选择一个 error tier。绝不吞掉失败。只有后台轮询可以静默处理,且必须明确标注为轮询。不得丢弃会丢失错误的
    catch
    。
    Prevents: 防止 sibling screen 处理不一致和静默数据丢失。
    情况Tier接线方式
    首次加载,暂无可展示内容inline
    UiState.error
    持有该错误;错误状态中提供 Retry
    刷新可见内容时失败popup保留内容;通过
    ::emitError
    发送给 host
    用户发起的操作失败popup,或在可恢复字段处使用 inline
    ::emitError
    ,或
    copy(fieldError = …)
    后台轮询,用户未主动触发silent,并明确标为 poll仅使用
    poll<Thing>()
    Session 过期(401)noneSession sign-out 路径;在 host 处抑制
  9. 每份状态恰好有一个 owner。不得使用
    rememberSaveable
    镜像
    UiState
    ,也不得使用
    LaunchedEffect
    同步两个副本。
    ViewModel 拥有业务状态,composable 拥有临时视觉状态,repository 拥有缓存。Prevents: 防止双写竞争和失效的恢复路径。
  10. 用户输入但尚未持久化的数据(草稿、输入文本、选定筛选项)保存在 ViewModel 的
    SavedStateHandle
    中;
    UiState
    由其派生。
    Identity 保留在 nav key 上;record 根据 identity 重新获取。保持单一 owner,而不是创建镜像,这样规则 9 才能成立。Prevents: 防止进程终止后丢失用户输入。
  11. Feature package 仅包含
    data/
    、
    domain/
    、
    presentation/
    、
    navigation/
    和
    di/
    ,不得有其他目录。Use case 仅用于真正的多步骤编排。
    Prevents: 防止 package 蔓延和不必要的 ceremony layer。
  12. Repository 读取方法必须通过名称明确其异步契约:一次性读取使用
    suspend fun getX(…)
    ,流式读取使用
    fun getXStream(…): Flow<…>
    。绝不使用
    observeX
    、
    getXFlow
    、
    getXPager
    ;也不得用同一名称同时表达两种读取。
    Prevents: 防止异步契约混淆。
  13. 不得存在 file-level 或 module-level 可变状态。 临时 picker 结果使用 Navigation 3 results 模式,草稿使用
    SavedStateHandle
    ,已提交的变更使用 repository 写入(
    navigation.md
    )。Prevents: 防止共享可变 result bus 和无必要写入。
  14. 所有新代码统一采用 Koin 注解风格:每个 feature 在
    di/
    下提供一个 module 文件,ViewModel 使用
    @KoinViewModel
    ,导航参数使用
    @InjectedParam
    (只有一个裸参数时直接使用,否则使用
    Params
    class)。Composable 绝不解析依赖,Route 的 ViewModel 除外。
    Params 按类型匹配,而不是按名称匹配。Prevents: 防止 DI 漂移和导航参数混淆。
  15. 仅使用 Navigation 3:每个 feature 只有一个
    @Serializable sealed interface <Feature>NavKey : NavKey
    ,并注册以支持多态序列化;key 携带 identity,绝不携带 record。Composition root 拥有
    NavDisplay
    和 back stack。
    Prevents: 防止无法恢复的目标页面。
  16. 编写新 library code 前先查阅最新文档(规则形式的立场第 6 项):先阅读
    gradle/libs.versions.toml
    ,再阅读当前官方文档,然后开始编写。无法访问文档时,应将代码标记为未经验证。
    M2 虚构了 API。Prevents: 防止依据记忆中的 API 编写代码。
  17. 代码应清晰表达意图(默认项):跨 module API 使用简短 KDoc,非显而易见的逻辑使用意图注释,严格遵循指南中的大括号规范,不保留噪音或死代码。 当函数签名无法表达全部含义时,使用单行 KDoc;仅在
    @param
    /
    @return
    能提供额外信息时使用。对于 pipeline、多条件 branch、loop 和 business rule,应编写意图注释;不得复述显而易见的代码行。每个 multi-line
    if
    /
    for
    /
    while
    /
    do
    /
    when
    body 都使用大括号;single-line
    when
    branch 保持无大括号,单行
    if
    /
    else
    expression 除外(规则 M-14)。不得保留被注释掉的代码;TODO 必须有 owner 或 issue link。完整规则和 WRONG/RIGHT 对比参见
    code-craft.md
    。之所以标为默认项,是因为 code craft 规范内部实现。Prevents: 防止生成人类无法审查的代码:缺少 API 文档、非显然 pipeline 没有注释,以及分支外漏的大括号修改。

Workflow

工作流

  • Create one todo per step below and do them in order.
  • Use the task path from the
    compose
    skill; read the relevant references.
  • Run the Verification gates below.
  • 为下面的每一步创建一个 todo,并按顺序执行。
  • 使用
    compose
    skill 提供的 task path;阅读相关 references。
  • 运行下方的 Verification gates。

Red flags

危险信号

ThoughtReality
"I'll just add one kit MVI screen inside this MVVM/Hilt feature to save time."No. Rule 1: build in the feature's pattern, propose migration separately.
"The file next to mine does it the old way, so I will too."Precedent is evidence, not permission (rule 1).
"First-load failure goes to the popup host; the host handles errors."No. Rule 8: first load with no content is inline with Retry.
"A
try/catch
here is simpler than
launchGuarded
."
No. Rule 6: every async call site uses
launchGuarded
with
onError
.
"I'll wrap the call in a
Result
so the ViewModel stays clean."
No. Rule 6 forbids
Result
wrappers.
"Stale list with no message is fine for this refresh."No. Rule 8: silent is only for named polls.
"I'll mirror the title into
rememberSaveable
so restore works."
No. Rule 9 forbids mirrors; rule 10 puts drafts in
SavedStateHandle
.
"I'll import the other feature's ViewModel; it is only one screen."No. Rules 1–3: shared state to
:data:
, movement via
UiEffect
.
"I'll comment every line so it's clear."No. Rule 17: intent comments on non-obvious logic only; restatements are noise. Delete them.
"I'll rebuild it the kit way."No. Stance item 9: extend the existing slice; rebuild only when asked.
"The name is obvious; no KDoc needed on this public repository."No. Rule 17: cross-module APIs carry short KDoc even when the name is clear.
"It's one line; braces are noise."No. Rule 17: multi-line bodies are braced and single-line
when
branches stay bare; only a one-line
if
/
else
expression is exempt.
想法现实情况
“我只要在这个 MVVM/Hilt feature 里加一个 kit MVI screen,就能省点时间。”不行。规则 1:按该 feature 的模式构建,并另行提出迁移方案。
“我旁边的文件采用旧写法,所以我也照着写。”先例是证据,不是许可(规则 1)。
“首次加载失败交给 popup host 处理。”不行。规则 8:首次加载且没有内容时应使用 inline,并提供 Retry。
“这里用
try/catch
更简单,不必用
launchGuarded
。”
不行。规则 6:每个异步调用点都应使用带
onError
的
launchGuarded
。
“用
Result
包一层,ViewModel 会更干净。”
不行。规则 6 禁止使用
Result
wrapper。
“这次刷新只显示陈旧列表,不给消息也没问题。”不行。规则 8:只有明确命名的 poll 才能静默处理。
“把标题镜像到
rememberSaveable
,这样就能恢复。”
不行。规则 9 禁止镜像;规则 10 要求将草稿放入
SavedStateHandle
。
“只用一个 screen,我可以直接 import 其他 feature 的 ViewModel。”不行。规则 1-3:共享状态放到
:data:
,状态变更通过
UiEffect
传递。
“我给每一行都加注释,这样就清楚了。”不行。规则 17:只在非显而易见的逻辑处添加意图注释;复述代码属于噪音。删除这些注释。
“我按 kit 的方式把它重建一遍。”不行。立场第 9 项:扩展现有 slice;只有明确要求时才重建。
“名称已经很明显了,这个公开 repository 不需要 KDoc。”不行。规则 17:即使名称清晰,跨 module API 仍需简短 KDoc。
“只有一行,大括号是噪音。”不行。规则 17:multi-line body 必须加括号,single-line
when
branch 保持无括号;仅单行
if
/
else
expression 除外。

Verification

验证

  • scripts/composekit/run-checks.sh
    exits 0 when installed, else the skill's
    scripts/run-checks.sh <project-root>
    exits 0.
  • Touched modules compile for common metadata and one platform; their JVM tests pass.
  • Every
    *Contract.kt
    holds exactly
    *UiState
    ,
    *UiAction
    ,
    *UiEffect
    .
  • Every named helper, token and import was seen in the project or current docs; nothing is recalled.
  • Every
    launchGuarded
    passes
    onError
    ; no
    try/catch
    chains or
    Result
    wrappers;
    CancellationException
    rethrown.
  • One tier per failure path; every Retry holds its error; silent only on named polls.
  • No feature depends on another; nothing depends on the root; no file-level
    var
    .
  • Every
    Flow
    -returning repository read ends in
    Stream
    ; DTOs and entities stay
    internal
    .
  • No commented-out blocks in changed files: yes or no.
  • 已安装时,
    scripts/composekit/run-checks.sh
    以 0 退出;否则,skill 的
    scripts/run-checks.sh <project-root>
    以 0 退出。
  • 涉及改动的 module 能够为 common metadata 和一个平台完成编译;其 JVM 测试通过。
  • 每个
    *Contract.kt
    恰好包含
    *UiState
    、
    *UiAction
    和
    *UiEffect
    。
  • 每个具名 helper、token 和 import 都在项目或当前文档中出现过;没有任何内容仅凭记忆写出。
  • 每个
    launchGuarded
    都传入
    onError
    ;不存在
    try/catch
    链或
    Result
    wrapper;
    CancellationException
    会被重新抛出。
  • 每条失败路径恰好使用一个 tier;每个 Retry 都持有对应错误;只有明确命名的 poll 才能静默处理。
  • 没有 feature 依赖其他 feature;任何内容都不依赖 root;不存在 file-level
    var
    。
  • 每个返回
    Flow
    的 repository 读取方法都以
    Stream
    结尾;DTO 和 entity 保持为
    internal
    。
  • 改动文件中不存在被注释掉的代码块:是或否。

Glossary

术语表

  • Composition root: the single
    :app
    module owning Koin aggregation,
    NavDisplay
    , the back stack, host ports.
  • Destination: one screen/sheet/dialog with its
    Contract.kt
    , ViewModel, Route, key.
  • Owner: the single holder of a piece of state (ViewModel, composable, repository, or
    SavedStateHandle
    ).
  • Cold load: first
    ON_START
    fetch, no prior data. Reconcile: later re-fetch, data kept.
  • Tier: the popup, inline or silent wiring a failure takes (rule 8).
  • Composition root: 唯一的
    :app
    module,负责 Koin 聚合、
    NavDisplay
    、back stack 和 host port。
  • Destination: 一个 screen/sheet/dialog,包含对应的
    Contract.kt
    、ViewModel、Route 和 key。
  • Owner: 某份状态的唯一持有者(ViewModel、composable、repository 或
    SavedStateHandle
    )。
  • Cold load: 首次
    ON_START
    获取数据,此前没有数据。Reconcile: 后续重新获取数据,同时保留已有数据。
  • Tier: 失败采用的 popup、inline 或 silent 接线层级(规则 8)。

References

References

  • code craft, coroutines, DI
  • errors, existing projects
  • modern Kotlin, modules
  • MVI, naming
  • navigation, state, core templates
  • 代码规范、coroutines、DI
  • 错误处理、现有项目
  • 现代 Kotlin、module
  • MVI、命名
  • 导航、状态、core 模板