project-context-ingestion

项目上下文梳理

来源映射：源自 Kotlin_Spring_Developer_Pipeline.md（SK-01）的一级关键技能。

使命

在提出代码、修复、测试或架构建议之前，准确理解代码仓库。 将此技能作为所有其他 Kotlin + Spring 技能的默认第一步。

优先检查

• 阅读 settings.gradle.kts、根目录的 build.gradle.kts、各模块构建文件、gradle.properties、gradle/libs.versions.toml，以及 Gradle wrapper 属性文件（如有）。
• 阅读 application.yml、application.yaml、application.properties 及特定 profile 的变体。
• 阅读顶层包或模块布局，以及有代表性的 controller、service、repository、配置类和测试类。
• 如有运行时和交付相关文件，也要阅读：Dockerfile、docker-compose*.yml、Kubernetes 或 Helm 清单、CI 工作流、.env.example 和部署脚本。
• 在建议使用任何新注解、库或 Spring API 之前，先检查依赖和插件声明。

梳理项目地图

• 记录 Kotlin 版本、Spring Boot 版本、Spring Framework 代际、Gradle 版本、JDK 或 toolchain 版本，以及会影响建议的主要库。
• 记录项目使用的是 MVC 还是 WebFlux、JPA、JDBC、jOOQ、MyBatis 还是 R2DBC、同步式还是基于协程的服务，以及使用了哪套测试技术栈。
• 记录是否启用了 kotlin("plugin.spring")、kotlin("plugin.jpa")、kotlin("plugin.serialization")、KAPT 或 KSP 等编译器插件。
• 记录代码仓库属于单模块、多模块、模块化单体还是每个仓库一个服务。
• 记录包的边界和显而易见的架构规则，例如 web -> service -> persistence 或六边形架构适配器。
• 记录生效的配置前缀、profiles、密钥加载模式，以及条件 Bean 的使用情况。

工作顺序

1. 从构建和配置文件入手。不要从业务代码开始。
2. 推断兼容性约束。将这些约束视为后续所有建议必须遵守的硬性边界。
3. 梳理模块及其职责。标出 HTTP、持久化、消息传递、安全和测试所在的位置。
4. 确认框架模式：MVC 还是 WebFlux、阻塞式还是响应式持久化、Servlet 还是 Netty、同步式还是协程风格。
5. 识别 Kotlin 和 Spring 的陷阱标记：
   • 存在 AOP 注解，但缺少 plugin.spring
   • 存在 JPA 实体，但缺少 plugin.jpa
   • 手动指定依赖版本，可能与 Spring Boot BOM 冲突
   • 同一请求流中混用阻塞式和响应式技术栈
   • 配置重复或按 profile 分散
6. 只总结当前任务所需的信息。不要罗列完整的文件清单。
7. 如果代码仓库不完整，说明缺失的证据，并基于有限假设继续。

需要产出的内容

返回一份简洁的项目简介，包含以下部分：

• 技术栈：框架模式、持久化模式、测试技术栈、构建技术栈。
• 兼容性约束：确切版本或明确指出未知项。
• 架构地图：模块或包及其职责边界。
• 运行配置：profiles、属性绑定风格、运行时和密钥约定。
• 风险标记：可能导致通用建议失效的项目特定陷阱。
• 后续命令或文件：接下来最值得检查的内容。

决策规则

• 优先采用代码仓库中的事实，而不是依赖记忆中的惯例。
• 如果多个模块的版本或技术栈风格不一致，应明确指出，不要强行统一。
• 如果构建文件与运行时代码暗示了不同做法，应将其视为风险，而非细节。
• 即使任务范围很窄，编辑代码前仍要检查最低限度的构建和配置上下文。
• 如果之后调用了其他技能，应将梳理出的约束传递给它，而不是从头重读所有内容。

高级上下文信号

• 区分应用模块和库模块。仓库中的共享库可能会有意避免使用 Spring Boot 插件、bootJar 或仅用于运行时的依赖。
• 检查构建逻辑是否位于约定插件、buildSrc 或纳入构建的 build-logic 中。这些位置经常会覆盖模块构建文件表面呈现的配置。
• 检查 javax.* 与 jakarta.* 导入，以确定代码库所处的迁移阶段。这会影响哪些 Spring、Hibernate 和验证方面的建议适用。
• 检查项目是否使用 OpenAPI codegen、QueryDSL、jOOQ、protobuf 或 MapStruct 等生成的源码。生成代码会影响安全编辑的范围。
• 检查 spring.jpa.open-in-view、spring.main.lazy-initialization、spring.aot.enabled 或与 native-image 相关的设置是否启用。这些设置会改变哪些建议是安全的。
• 检查系统是否依赖 Config Server、Vault、Helm 模板化配置或环境变量替换等平台功能。本地文件可能无法反映完整的运行时情况。
• 检查可观测性、追踪和关联 ID 是否属于一等规范。这会影响控制器、客户端和故障处理方面的建议。
• 检查服务是否拥有自己的数据库架构、共享数据库，或通过 outbox 或 CDC 集成。这会改变迁移和事务方面的指导。

专家启发式

• 如果仓库混用了 JPA 和 R2DBC，或 MVC 和 WebFlux，应确定这是按模块划分的有意边界，还是意外形成的混合架构。这两种情况的建议大不相同。
• 如果仓库在阻塞式持久化之上使用 Kotlin 协程，应指出除非持久化层是响应式的，否则这仍然属于阻塞式架构。
• 如果存在多个依赖管理来源，应确定它们的优先级。真正的事实来源可能是 Spring Boot 插件、版本目录、公司约定插件或平台 BOM。
• 如果测试使用的技术栈与生产环境不同，应明确说明。例如，测试使用 H2 而生产环境使用 Postgres，就不能依赖许多关于持久化的假设。
• 如果仓库没有明显的架构规则，应将其报告为限制，而不是凭空设想代码库并未遵循的整洁架构。

防护措施

• 不要建议使用与项目实际采用的 Spring Boot 主版本不同版本中的 API 或注解。
• 添加依赖或插件配置块前，应先检查项目是否已通过 BOM、版本目录或约定插件引入这些依赖或插件。
• 如果存在 spring-boot-starter-webflux 或协程 Web 栈，不要假设项目使用 MVC。
• 不要仅因存在数据库就假设使用 JPA。应先确认实际采用的持久化技术。
• 在识别当前结构和团队规范之前，不要提出架构重构建议。

出现以下情况时提高警惕

• 同时存在 servlet 和响应式启动器，且没有明确原因。
• data class 实体与 JPA 或 Hibernate 同时使用。
• 使用 @Transactional、@Cacheable 或 @Async，但没有 Kotlin Spring 插件。
• 在由 Boot 管理的构建中，为 Jackson、Hibernate、Netty、Logback 或 SLF4J 显式指定版本。
• 特定 profile 的配置文件以不一致的结构重新定义相同属性。

质量标准

良好的技能执行结果会让后续建议更加精准、范围更明确，也更容易验证。 糟糕的执行结果会在尚未确认仓库实际使用的技术栈、版本和规范之前，就开始建议编写代码。