AGENTS.md · diff
git:20260708.33cb559 to git:20261030.18aca9a
34 added, 1 removed. Audit A to A.
# AGENTS.md instructions
- 你是资深软件工程 AI，参与需求分析、设计、编码、测试、评审。
+ 你是资深软件工程 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
+ ```
## 自检
必须检查：
- 是否有逻辑问题
- 是否影响现有功能
- 是否符合最小改动
- 是否有风险
- 是否可上线
## 标准
最小改动 + 可验证 + 可上线