# java-spring-coder

**Repository Path**: FrankEvils/java-spring-coder

## Basic Information

- **Project Name**: java-spring-coder
- **Description**: ai 的 java编码规范和 skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# java-spring-coder

一套面向 AI 编码助手的 Java/Spring 提示词与 Skill 资产，当前包含“Quest 规划”和“Java/Spring 实现”两类能力：先把需求拆成可执行 Quest Map，再按目标仓库的本地约束逐关实现，而不是直接输出通用模板代码。

## 适用场景

- 使用 Codex、ChatGPT、Claude 等 AI 助手编写或重构 Java/Spring Boot 代码
- 需要先把 PRD 或功能需求拆成渐进式 Quest Map，再把单个 Quest 交给实现型 skill 落地
- 需要让 AI 优先遵循当前仓库的包结构、返回包装、DTO/VO 命名、异常体系、日志规范
- 需要为不同项目沉淀一套“稳定规则 + 按需专题 + 仓库适配”的可复用资产
- 需要做表驱动代码生成，但不希望 AI 机械套用单一模板

## 设计目标

这套内容重点解决两个常见问题：

1. AI 容易把某个项目的局部写法误当成 Java/Spring 全局真理。
2. AI 虽然懂通用最佳实践，但不了解目标仓库的真实约束，导致生成代码“不像这个项目”。

因此本仓库采用三层结构：

- `rule/`：沉淀跨项目相对稳定的 Java/Spring 基线规则
- `skills/`：提供可触发的 Skill，分别负责 Quest 规划编排与 Java/Spring 实现
- `references/`：把事务、缓存、测试、交付等大块知识拆成按需专题，避免主提示词过胖

## 目录结构

```text
.
├── README.md
├── README.en.md
├── rule/
│   └── java-spring-baseline.md
└── skills/
    ├── java-spring-coder/
    │   ├── SKILL.md
    │   ├── agents/
    │   │   └── openai.yaml
    │   └── references/
    │       ├── java-spring-data-access.md
    │       ├── java-spring-runtime-topics.md
    │       └── java-spring-quality-and-delivery.md
    └── prd-quest-map/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        └── references/
            ├── implementation-brief.md
            └── quest-map-format.md
```

## 核心内容说明

### 1. `rule/java-spring-baseline.md`

这是跨项目通用基线，只保留相对稳定成立的规则，例如：

- 先读仓库规则，再写代码
- 新代码优先构造器注入
- Controller 保持薄层
- 参数校验、日志、异常、对象映射、幂等与性能的基本要求

它不负责规定某个具体项目一定使用什么返回包装、父类、DTO 后缀或 DAO 分层。

### 2. `skills/prd-quest-map/SKILL.md`

这是新的 Quest 规划 Skill，负责：

- 从 PRD / 功能需求生成 Quest Map
- 将任务拆成微关卡并写清楚黑盒验收标准
- 在同一份 Quest Map 内维护 quest 状态
- 为实现阶段生成当前关卡的 `Quest Implementation Brief`

它不负责写业务代码，而是负责“规划与交接”。

### 3. `skills/java-spring-coder/SKILL.md`

这是核心 Skill，负责把“先适配仓库，再写代码”变成可执行工作流。它强调：

- 编码前先检查仓库规则和相邻模块实现
- 先区分“稳定规则”和“项目可变规则”
- 修改旧模块时，优先镜像最近邻风格
- 新功能缺少强先例时，再回退到基线规则
- 表驱动生成只能把模板当起点，不能反客为主覆盖项目实际结构
- 如果输入来自 Quest Map 的当前关卡 Brief，只实现这一关，不顺手扩到后续关卡

### 4. `skills/java-spring-coder/references/*.md`

这些文件是按需专题知识，不应该默认全部塞进主提示词。

- `java-spring-data-access.md`
  处理对象转换、数据库设计、批量处理、事务、多数据源、空安全
- `java-spring-runtime-topics.md`
  处理并发、缓存、配置安全、异步、消息事务、安全和性能
- `java-spring-quality-and-delivery.md`
  处理 Apifox、测试规范、评审清单

如果后续需要记录某个具体仓库的局部适配经验，建议单独建适配文件，不要直接写死进全局 Skill。

## 使用方式

### 方式一：把它当作 AI 提示词资产仓库

适合你自己维护提示词、规则和专题文件。

推荐使用顺序：

1. 先读 `rule/java-spring-baseline.md`
2. 用 `skills/prd-quest-map/SKILL.md` 把 PRD 或功能需求拆成 Quest Map
3. 为当前 Quest 生成 `Quest Implementation Brief`
4. 再触发 `skills/java-spring-coder/SKILL.md` 落地当前 Quest
5. 任务涉及事务、缓存、测试等主题时，再按需读取 `references/`
6. 如果目标仓库已有本地规则，以目标仓库规则为准

### 方式二：安装为 Codex Skill

如果你在 Codex 环境中使用，可以把对应 skill 安装到本地技能目录后分别触发。

典型调用意图：

- “用 `$prd-quest-map` 把这个 PRD 拆成可执行 Quest Map，并给我当前第一关的实现简报”
- “用 `$java-spring-coder` 先检查这个 Spring Boot 模块的本地风格，再实现新增接口”
- “用 `$java-spring-coder` 根据当前 Quest Brief 实现这一关，先不要动下一关”
- “基于数据表生成 MyBatis Plus 实体、Mapper、Service，但先看目标模块是否已有 Infra/Repository 分层”

## Prompt / Skill 编写原则

本仓库背后的方法论很简单：

- 不把单个项目经验冒充成通用规范
- 不为了追求“最佳实践”而破坏现有模块一致性
- 不把所有知识都塞进一个超长提示词
- 让 AI 优先做“上下文识别”，再做“代码生成”

如果后续你继续补充 Prompt 或 Skill，建议优先判断新增内容属于哪一类：

- 跨项目稳定规则：放进 `rule/`
- 可执行工作流：放进对应 `SKILL.md`
- 大块专题知识：放进 `references/`
- 某个仓库的局部适配经验：单独建适配文件，不要硬编码进全局 Skill

## 一个推荐工作流

1. 先让 AI 阅读目标仓库中的 `AGENTS.md`、`CLAUDE.md`、相邻模块代码和本仓库的基线规则
2. 用 `$prd-quest-map` 生成或更新 Quest Map，并锁定当前 Quest
3. 让 Quest Skill 输出当前关卡的 `Quest Implementation Brief`
4. 再用 `$java-spring-coder` 只实现当前 Quest
5. 完成后回到 Quest Skill 更新状态，再决定是否继续下一关
6. 涉及事务、缓存、消息、测试等专题时，再加载对应 references

## 当前内容的优势与注意点

### 优势

- 核心思路明确，避免 AI 生搬硬套通用模板
- Quest 规划 Skill 与实现 Skill 职责分离，边界更清晰
- Skill 与 references 拆分合理，符合渐进加载思路
- `baseline`、`skill`、`references` 三层边界基本清楚

### 注意点

- 中英文 README 需要持续保持同步，避免双语说明出现职责漂移
- 如果后续增加更多项目适配文件，建议统一放在单独目录并加命名约定，避免和通用专题混在一起

## 参与维护建议

- 每次新增规则前，先判断它是不是“跨项目稳定成立”
- 同一条规则尽量只在一个地方维护，避免 `baseline` 和 `references` 重复
- 新增 Skill 时，优先保持主文件精简，把大块知识下沉到引用文件
- 如果某条规范只在单个仓库成立，不要直接写进全局 Skill

## 后续可继续补强的方向

- 增加更多仓库适配样例，例如不同公司/不同脚手架的 Spring 风格
- 为代码生成场景补一份表驱动模板选择指南
- 为 review 场景补一份 Java/Spring 缺陷清单型 Prompt
- 为 Quest Map 增加更明确的状态流转示例和多轮协作样例