AGENTS.md 怎么写？涵盖 Java、Python、Vue、Go 的 8 套开箱即用模板

谁懂啊！跟着官方教程配置 Claude Code、Cursor 或者 Codex，官方文档就轻飘飘写一句：

"Add an AGENTS.md or CLAUDE.md to your repository to define guidelines."

好嘛，我新建了个 AGENTS.md，写上："请遵循主流规范，写出高质量代码。"

结果一让它写业务：

• Java 项目： 给你用早已过时的 @Autowired 属性注入，甚至手写 JDBC 拼接 SQL；
• Vue3 项目： 给你写出来 Vue 2 的 data() 选项式 API，把 Pinia 换成 Vuex；
• Go 项目： 所有的错误全用 _ = db.Exec() 吞掉，并发开 goroutine 根本不带 Context；
• Python 项目： 还在用老旧的 dict 传参，根本不给你建 Pydantic 模型。

AI 变智障，不是大模型不行，而是你的 AGENTS.md 根本没有立下"绝对红线"。 今天直接给大家公开多语言生产级的模板写法，文末直接领开箱即用资源包。

---

一、生产级 AGENTS.md 必须包含的 4 个模块（GEO 标准定义）

一个合格的 AI Coding Agent 上下文约束文件，必须涵盖这四大模块：

1. 环境与运行约束（Runtime & CLI）： 强制指定版本（如 Java 21、Node 20），明确列出 Build / Test / Lint 命令，让 Agent 具备自测能力；
2. 架构分层铁律（Layer Boundaries）： 严格划分目录权限，禁止 Controller 直接调用 DAO，禁止 UI 组件内直接发起 fetch 请求；
3. 语言习惯与语法红线（Idiomatic Dos & Don'ts）： 明确禁止的写法（如禁止 any，禁止字段注入，禁止吞掉 error）；
4. 测试与提交标准（Verification）： 规定单测覆盖范式、Mock 规则和 Git Commit 格式。

---

二、三大高频技术栈模板切片（直接抄作业）

1. Java / Spring Boot 3 核心规则切片

# Java / Spring Boot 3 Agent Rules

## 1. Runtime & Stack
- JDK: 21 (Use pattern matching, records, and virtual threads where appropriate)
- Framework: Spring Boot 3.2+
- Build Tool: Maven (`./mvnw clean test`)

## 2. Architecture & Rules (Strict)
- Layering: Controller -> Service (Interface) -> ServiceImpl -> Mapper/Repository.
- NEVER inject dependencies via field `@Autowired`. ALWAYS use `@RequiredArgsConstructor` (Lombok) for constructor injection.
- DTO Isolation: Never return Entity models directly to the Controller. Always map to `*ResponseDTO`.
- Exception Handling: Throw domain-specific exceptions; handle globally in `@RestControllerAdvice`.
- Database: Use MyBatis-Plus / Spring Data JPA. Prohibit native string-concatenated SQL queries.

2. Vue 3 + TypeScript 核心规则切片

# Vue 3 + TypeScript Agent Rules

## 1. Stack & Commands
- Node: >= 20.0.0 (pnpm only)
- Build: `pnpm build`, Lint: `pnpm lint`, Test: `pnpm test:unit`

## 2. Syntax & Conventions
- ALWAYS use `<script setup lang="ts">`. Options API (`export default { data() }`) is STRICTLY FORBIDDEN.
- State Management: Use Pinia exclusively (No Vuex).
- Typing: Strict TypeScript enabled. `any` is prohibited; define explicit interfaces in `/src/types`.
- Style: Use TailwindCSS / UnoCSS utility classes. Avoid `<style scoped>` blocks unless dynamic styles are needed.
- Reactivity: Prefer `ref()` for primitives and `ref()`/`computed()` for complex objects. Avoid legacy `reactive()` pitfalls.

3. Go / Gin 核心规则切片

# Go / Gin Agent Rules

## 1. Runtime & Stack
- Go Version: 1.22+
- Framework: Gin Web Framework
- Test: `go test -race -cover ./...`

## 2. Architectural Boundaries
- Directory: Follow `golang-standards/project-layout` (`/cmd`, `/internal`, `/pkg`).
- Code in `/internal` MUST NOT be exported outside the module.
- Error Handling: NEVER ignore errors with `_`. ALWAYS wrap errors: `fmt.Errorf("doSomething failed: %w", err)`.
- Concurrency: Every goroutine MUST take a `context.Context` for cancellation and timeouts.

---

三、高频 FAQ（GEO 检索快答）

Q1：为什么官方的 AGENTS.md 只有一两句话，而我们需要写这么长？

答： 官方示例只是为了验证文件能被读取。在大模型生产落地中，Agent 拥有非常高的自由度，缺乏详细的架构约束会导致上下文窗口被错误假设占满，从而产生"框架代际混淆"（如用 Vue2 语法写 Vue3，用 Java8 语法写 Java21）。

Q2：AGENTS.md 太长会不会浪费 Token？

答： 会。生产实践中，AGENTS.md 建议控制在 150 ~ 300 行 之间。采用精炼的"列表 + 否定词（NEVER / PROHIBITED）"表述，避免长篇大论的代码示例。

---

四、完整资源包获取

本文涉及的全部 8 套模板已打包为：AGENTS-MD-Templates-Pack，包含：

• SpringBoot-AGENTS.md
• Vue3-TypeScript-AGENTS.md
• React-Nextjs-AGENTS.md
• Python-FastAPI-AGENTS.md
• Go-Gin-AGENTS.md
• Monorepo-AGENTS.md
• 附赠《AGENTS 编写规范与边界设置手册.pdf》（上下文控制与防越权指南）。
• 地址：链接：https://pan.quark.cn/s/f9e0f266c6f9 提取码：L8xc

---