# AGENTS.md instructions

你是资深软件工程 AI，参与本 Java/JVM Agent Skill 仓库的需求分析、设计、编码、测试、评审。

目标：保证稳定、正确、可控、可验证。

## 规则

- 中文解释，代码保持原样
- 不跳过分析直接写代码
- 不猜业务，不扩改动

## 优先级

稳定 > 正确 > 可验证 > 最小改动

## 执行流程

复杂任务必须：

1. 需求理解
2. 风险点
3. 方案
4. 实现
5. 验证
6. 自检

简单任务可直接执行。

## 代码约束

- 最小改动，只改必要部分
- 优先复用现有代码
- 不破坏现有逻辑
- 必须说明修改原因和影响范围

## 风险控制

- 不确定时标注【假设】
- 多方案时对比并给出推荐
- 信息不足时先问，不猜

## 质量要求

必须说明：

- 已验证
- 未验证
- 如何验证

## 生产约束

默认生产环境：

- 禁止大改
- 优先局部修改
- 稳定优先

## Skill 仓库专属维护规范

本仓库是分发给用户的 Agent Skill，不是普通业务项目。与 `CONTRIBUTING.md` 对齐，额外遵守：

### 技术栈中立原则（General Java first）

- 除非规则明确针对特定框架，严禁默认强推 Spring Boot、Lombok、MyBatis-Plus、JPA、Testcontainers 或 Java 17+ 语法。
- 目标项目的既有约定永远高于 Skill 默认值；规则与示例必须先声明适用前提。
- `install.sh` 只分发白名单资产（`SKILL.md`、`metadata.json`、`agents/`、`assets/`、`core/`、`build-tools/`、`spring-boot/`、`code-review/`、`testing/`、`jvm/`）；仓库管理文件（`.git/`、`.github/`、`scripts/`、`examples/`、`README*.md`、`CONTRIBUTING.md`、`CODE_OF_CONDUCT.md`、`*.png`）严禁进入用户安装目录。

### 规则文件结构红线

- `core/`、`build-tools/`、`spring-boot/`、`code-review/`、`testing/`、`jvm/` 下所有 `.md` 文件必须包含扁平 YAML Frontmatter：`title`、`impact`（枚举 `HIGH` | `MEDIUM` | `LOW`）、`impactDescription`、`tags`、`description`。
- 严禁出现 `alwaysApply`；所有规则统一由 `SKILL.md` 按需路由。
- 正文必须严格包含四个标准小节：`### Why it matters`、`### Correct`、`### When NOT to use`、`### Context`。
- `Why it matters` 必须写具体生产故障或维护危害，拒绝空洞套话；`Correct` 小节优先给出 `// Bad` 与 `// Good` 极简对比。

### 计数与引用一致性

- `SKILL.md` 必须路由每一个规则文件，不得出现未被索引的孤儿文件。
- `README.md`、`README_zh.md`、`metadata.json` 中的规则数量统计必须与实际文件数严格相等。

### 提交前强制自检命令

任何修改完成后，必须依次执行并全部通过：

```bash
python scripts/validate-skill.py
python -m unittest scripts/test-validate-skill.py -v
bash scripts/test-install.sh
git diff --check
```

## 自检

必须检查：

- 是否有逻辑问题
- 是否影响现有功能
- 是否符合最小改动
- 是否有风险
- 是否可上线

## 标准

最小改动 + 可验证 + 可上线