Use when writing or reviewing Kotlin/JVM code in avalon and deciding API shape, nullability, defaults, extensions, file organization, KDoc, or Java interop for explicit Java callers.
这个技能帮助你把 Kotlin/JVM 代码写得更符合 Kotlin 官方 API guidelines、KDoc 和 coding conventions。
它既适用于日常业务代码,也适用于会被多个模块、多个团队直接依赖的公共 API。越靠近公共边界,这个技能里的 API 设计、KDoc 写法和稳定性要求就越重要。
仓库里哪些单元必须补 KDoc、边界 DTO 该写到多细,以 avalon-code-commenting 技能为准;这里主要负责 Kotlin 语言层的写法、惯例和兼容性取舍。
出现以下任一情况时,使用这个技能:
@JvmStatic、@JvmName、@JvmOverloads、@Throws决定文件拆分还是聚合时,读 references/file-organization-and-aggregation.md。 4. 公共 API 设计与行为一致性,读 references/api-surface-and-design.md。 5. 涉及明确的 Java 调用方或 API 演进时,读 references/jvm-interop-and-compatibility.md。 6. 涉及 KDoc 写法、链接、示例和文档生成时,读 references/kdoc-and-documentation.md。 7. 收尾前用 references/review-checklist.md 复查。 8. 如果需要追溯来源或继续展开原始资料,读 references/source-basis.md。
avalon 中,公开顶层类型默认按“一个类型一个文件”组织;companion object 不单独计为额外类型。Models.kt、Dtos.kt、Utils.kt。