45-加餐 10 个企业级 AGENTS.md 模板(覆盖 Go Java Python TypeScript)

少林码僧
4 阅读11分钟

加餐 | 10 个企业级 AGENTS.md 模板（覆盖 Go、Java、Python、TypeScript）

本加餐提供 10 份可直接改造落地 的 AGENTS.md 模板，覆盖 Python（API/数据）、Go（服务/CLI）、Java（Spring/DDD）、TypeScript（Next/Node）、React SPA 与 多语言 Monorepo。每份模板均包含：项目语境、目录结构、架构规则、编码规范、测试与安全 等区块。文末附 使用指南：如何裁剪、如何与 CI/LLM 对齐、如何避免模板腐化。

总原则（所有模板通用）

  1. 先写边界，再写风格：架构与依赖方向比「用不用某种格式」更重要。
  2. 规则必须可验证：每条 MUST 尽量对应扫描器或测试类型（或明确为人工评审项）。
  3. 保持版本与 owner：模板不是一次性文档，需指定维护者与变更流程。
  4. 给 LLM 的提示：把「禁止事项」写得更具体，把「示例路径」写清楚，减少模型臆造文件。

模板 1：Python FastAPI 微服务

# AGENTS.md — Python FastAPI 微服务

## 项目语境
- 服务职责（一句话）：<例如：订单读写与状态机，不负责支付扣款>
- 运行时：Python 3.11+；框架：FastAPI；包管理：uv/poetry（二选一写明）

## 目录结构（示例）
- `app/domain/` 领域模型与不变量
- `app/application/` 用例编排（依赖端口）
- `app/infrastructure/` DB/缓存/外部 API 适配器
- `app/presentation/` HTTP 路由、DTO、依赖注入
- `tests/` 单元与集成测试（镜像目录）

## 架构规则（MUST）
- MUST：presentation 不得直接访问 infrastructure 的具体实现类，只能通过端口（Protocol/接口）
- MUST：跨聚合写入必须通过用例层编排，禁止在路由函数里拼业务规则
- MUST：对外 DTO 与领域实体分离，禁止把 ORM 模型直接返回给客户端
- MUST NOT：在领域层引入 FastAPI/HTTP 相关依赖

## 编码规范
- 类型注解覆盖公共 API；使用 `ruff` + `black`（或等价组合）
- 异常分层：领域异常 vs HTTP 异常映射在 presentation 层统一处理
- 日志：结构化 JSON；禁止打印敏感字段；关联 `trace_id`

## 测试
- 领域纯逻辑 100% 单元测试优先
- 用例层可用 fake adapter；关键路径至少 1 条集成测试（Testcontainers 可选）
- 覆盖率阈值：<写数字>；新增代码默认不降低覆盖率

## 安全
- 输入校验用 schema；默认拒绝宽松解析
- 密钥只来自环境变量/密钥管理；禁止写入仓库
- 依赖漏洞扫描：`pip-audit` / OSV（择一写入 CI）

## PR 自检清单
- [ ] 是否新增跨层依赖？
- [ ] 是否补充测试与观测字段（metrics/log）？
- [ ] 是否更新 API 文档（OpenAPI）？

适用场景：中小型领域服务、需要清晰分层的 REST API。
使用建议：把 MUST 条目映射到 import-linter 或自定义脚本。

模板 2：Python 数据管线（Spark / Ray）

# AGENTS.md — Python 数据管线（Spark/Ray）

## 项目语境
- 管线目标：<批处理/流处理/训练数据生成>
- 引擎：Spark 3.x 或 Ray <版本>；编排：Airflow/Prefect/Dagster（写明）

## 目录结构
- `pipelines/` 任务定义与 DAG 入口
- `transforms/` 可复用转换（纯函数优先）
- `io/` 数据源与 sink 适配
- `quality/` 数据质量检查（Great Expectations / 自定义）
- `metadata/` schema、分区策略、血缘记录

## 架构规则（MUST）
- MUST：转换函数幂等；可重跑不产生重复主键数据（或写清去重策略）
- MUST：分区与压缩格式在元数据中声明（例如 `parquet/zstd`）
- MUST NOT：在 worker 内硬编码集群地址或密钥
- MUST：大表变更需要向后兼容的 schema 演进策略

## 编码规范
- Spark：避免 UDF，优先内置函数；必须 UDF 时写明原因与测试
- Ray：注意对象存储序列化成本；任务粒度可观测（timeline）

## 测试
- 小样例数据集做 golden test；关键指标（行数、空值率）断言
- 性能回归：对关键 stage 记录基准（可在 CI  nightly）

## 安全与合规
- PII 字段清单；脱敏/哈希策略；日志脱敏
- 数据出境与留存策略（如适用）

## PR 自检清单
- [ ] 是否更新数据契约（schema）？
- [ ] 是否增加质量检查与告警阈值？
- [ ] 是否评估成本（shuffle/扫描量）？

适用场景：数据平台、训练数据生产、离线特征工程。
使用建议：把质量检查与分区策略写成 CI 可跑的「轻量校验」。

模板 3：Go 微服务（gin / echo）

# AGENTS.md — Go 微服务（gin/echo）

## 项目语境
- 服务边界：<一句话>
- Go 版本：1.22+；模块路径：`module example.com/xxx`

## 目录结构（建议）
- `cmd/<svc>/main.go` 启动入口
- `internal/<domain>/` 领域与用例
- `internal/infra/` DB、消息、外部 client
- `internal/api/` HTTP handler、路由、middleware
- `pkg/` 仅放稳定可复用且无业务语义的库（尽量少）

## 架构规则（MUST）
- MUST：`internal` 边界不可被外部模块导入
- MUST：handler 薄；业务逻辑在 service/usecase
- MUST NOT：在领域层引入 `gin`/`echo`/`net/http` 具体类型
- MUST：context.Context 作为第一参数传递；禁止存储在结构体中长期保存

## 编码规范
- `golangci-lint` 全量启用；格式化 `gofmt`
- 错误处理：wrap 错误带域信息；对外映射统一在中间件
- 并发：明确 goroutine 生命周期；禁止泄漏与无界队列

## 测试
- 表驱动单测覆盖核心规则；API 用 `httptest`
- 对客户端集成使用 docker compose 或 mock（写明策略）

## 安全
- 输入校验：DTO + validator；默认最小权限
- 依赖扫描：`govulncheck`

## PR 自检清单
- [ ] 是否引入新的跨 package 循环依赖？
- [ ] 是否暴露新的 metrics/trace？
- [ ] 是否更新 OpenAPI/Proto（如有）？

模板 4：Go CLI 工具

# AGENTS.md — Go CLI

## 项目语境
- CLI 用途：<一句话>
- 发布：单二进制；配置：环境变量 + 配置文件（写明优先级）

## 目录结构
- `cmd/<cli>/main.go`
- `internal/app/` 命令树、参数解析
- `internal/core/` 纯逻辑
- `internal/io/` 文件/网络交互

## 架构规则（MUST）
- MUST：核心逻辑可测试（不绑定 `os.Args` 直接解析在 main）
- MUST：退出码规范（0/1/2…）与错误消息用户友好
- MUST NOT：在库代码里 `log.Fatal`（除非明确为 cmd 层）

## 编码规范
- 长任务显示进度；支持 `--json` 输出（如适用）
- 日志级别可控；默认 stderr

## 测试
- golden file 测试 CLI 输出；对文件系统使用临时目录

## 安全
- 谨慎处理路径参数；防路径穿越
- 不在日志打印 token

## PR 自检清单
- [ ] 是否破坏向后兼容的命令行参数？
- [ ] 是否更新 `--help` 与示例？

模板 5：Java Spring Boot 服务

# AGENTS.md — Java Spring Boot

## 项目语境
- 服务职责：<一句话>
- Java 17+；Spring Boot 3.x；构建：Maven/Gradle（写明）

## 目录结构（示例）
- `domain/` 实体、值对象、领域服务
- `application/` 用例服务、事务边界
- `infrastructure/` JPA、消息、外部系统
- `interfaces/` REST Controller、DTO、Mapper

## 架构规则（MUST）
- MUST：Controller 只做编排与校验，不写业务规则
- MUST：领域模型与持久化模型分离（禁止 Entity 直接当 API 返回）
- MUST NOT：在 domain 依赖 Spring 注解（除非团队明确允许并统一策略）
- MUST：对外 API 版本化策略（URL/Header）写清楚

## 编码规范
- Checkstyle/Spotless/ErrorProne（择一组合）
- 异常映射：业务异常 vs 系统异常

## 测试
- JUnit5 + Testcontainers（可选）
- 合同测试：consumer-driven（如适用）

## 安全
- Spring Security 默认开启；CSRF/CORS 策略写明
- 依赖漏洞：OWASP Dependency-Check / Snyk（选一）

## PR 自检清单
- [ ] 是否修改数据库迁移脚本（Flyway/Liquibase）？
- [ ] 是否评估事务边界与隔离级别？
- [ ] 是否更新 API 文档？

模板 6：Java DDD 六边形（Ports & Adapters）

# AGENTS.md — Java DDD 六边形

## 项目语境
- 限界上下文：<名称>；对外集成：<列表>

## 目录结构
- `domain/model/` 聚合、实体、值对象、领域事件
- `domain/service/` 领域服务（谨慎使用）
- `application/port/in` 入站端口（用例接口）
- `application/port/out` 出站端口（仓库、网关接口）
- `application/usecase/` 用例实现
- `adapter/in/web/` 入站适配器
- `adapter/out/persistence/` 出站适配器

## 架构规则（MUST）
- MUST：依赖方向指向 domain；adapter 仅依赖 port
- MUST：聚合不变量在模型内保证；跨聚合用领域事件或应用服务编排
- MUST NOT：adapter 之间横向调用（必须通过用例）

## 编码规范
- 命名体现 ubiquitous language；禁止「通用」DTO 污染领域
- 映射层明确：Anti-Corruption Layer 位置固定

## 测试
- 领域单测不依赖 Spring；adapter 用集成测试

## 安全
- 出站调用必须超时/重试/熔断策略（在 adapter 实现）

## PR 自检清单
- [ ] 是否引入新的上下文映射？是否需要更新上下文图？
- [ ] 领域事件是否幂等？

模板 7：TypeScript Next.js 全栈

# AGENTS.md — Next.js（App Router）

## 项目语境
- 产品边界：<一句话>
- Next.js <版本>；包管理：pnpm；Node <版本>

## 目录结构
- `app/` 路由与 server actions（如使用）
- `components/` UI 组件（按域分子目录）
- `lib/` 共享工具（无业务语义）
- `server/` 服务端用例、数据访问封装
- `types/` 共享类型

## 架构规则（MUST）
- MUST：禁止在客户端 bundle 引入服务端密钥依赖
- MUST：数据访问集中在 server 层；组件层不直接拼 SQL/HTTP 细节（按你们封装）
- MUST NOT：在 `use client` 组件中泄露内部 API 密钥
- MUST：Server Actions 输入校验使用 zod（或等价）

## 编码规范
- ESLint + Prettier；TypeScript strict
- 组件拆分：展示 vs 容器；避免巨型页面文件

## 测试
- Vitest/Jest + Testing Library；关键交互 e2e（Playwright）

## 安全
- CSP、Cookie 策略、CSRF（按部署模式写明）
- 依赖审计：`pnpm audit`

## PR 自检清单
- [ ] 是否区分 RSC/Client 边界？
- [ ] 是否新增需要环境变量？是否更新 `.env.example`？

模板 8：TypeScript Node.js 后端

# AGENTS.md — Node.js 后端（REST/GraphQL）

## 项目语境
- API 类型：<REST/GraphQL>；框架：<express/fastify/nest>（写明）

## 目录结构
- `src/domain/` 纯业务规则
- `src/application/` 用例
- `src/infrastructure/` DB、队列、第三方 SDK
- `src/interface/http/` controller、路由、middleware

## 架构规则（MUST）
- MUST：handler 薄；错误映射集中
- MUST NOT：在 domain 引入框架类型
- MUST：所有外部 IO 具备超时；默认重试策略可配置

## 编码规范
- `eslint` + `typescript-eslint` strict
- 日志结构化；request id 贯通

## 测试
- 单测 + supertest 集成；数据库用 test container 或内存替代（写明）

## 安全
- 输入校验；速率限制；鉴权中间件默认开启
- SSRF 防护：对外 URL fetch 需白名单/解析校验

## PR 自检清单
- [ ] 是否变更 API 契约？是否同步客户端 SDK？
- [ ] 是否评估性能热点（N+1）？

模板 9：React 前端 SPA（Vite）

# AGENTS.md — React SPA

## 项目语境
- 应用类型：管理后台/用户端；路由：React Router（版本写明）

## 目录结构
- `src/features/<feature>/` 按特性分包（页面、组件、api、model）
- `src/shared/` 设计系统级组件与 hooks
- `src/app/` 入口、providers、路由表

## 架构规则（MUST）
- MUST：feature 间禁止深层相对路径耦合；共享只能通过 `shared` 或明确 public API
- MUST：网络层集中（api client），禁止在组件里散落 `fetch` 细节（除非极薄封装）
- MUST NOT：把业务规则写进巨型 `useEffect`

## 编码规范
- TypeScript strict；组件 props 类型完整
- 状态管理策略：<Zustand/Redux RTK/Query>（写明边界）

## 测试
- 单元 + 组件测试；关键路径 e2e

## 安全
- XSS：谨慎 `dangerouslySetInnerHTML`；必须白名单清洗
- 依赖审计与 SBOM（如企业要求）

## PR 自检清单
- [ ] 是否引入可访问性回归？
- [ ] 是否评估包体积（lazy/route split）？

模板 10：Monorepo（多语言 / 多包）

# AGENTS.md — Monorepo（多语言）

## 仓库地图
- `services/order-go/` Go 服务（见子目录 AGENTS.md）
- `services/billing-py/` Python 服务
- `apps/web/` 前端
- `packages/proto/` 共享契约（proto/openapi）
- `packages/ts-sdk/` 生成 SDK（如有）

## 全局架构规则（MUST）
- MUST：跨服务契约变更必须走 `packages/proto` 或中心化 OpenAPI，并版本化
- MUST：各服务保持独立部署单元；禁止共享运行时全局状态
- MUST NOT：为了省事在 `packages/` 引入业务耦合的「万能 util 垃圾场」

## 依赖与构建
- 包管理：pnpm workspace / Gradle composite（写明）
- CI：变更检测（affected）必须启用，避免全量构建拖垮团队

## 测试策略
- 契约测试优先；跨服务集成测试控制在少数黄金路径

## 安全
- 统一密钥管理策略；禁止子项目各自一套「临时 .env」

## 治理
- 子项目可维护 `AGENTS.md` 扩展；本文件定义全局冲突裁决规则

## PR 自检清单
- [ ] 是否动到共享契约？是否同步所有消费者？
- [ ] 是否评估对其他包的构建时影响？

使用指南：如何把模板变成「你们公司的真规则」

  1. 先选 8 条 MUST：越少越能执行；其余降级为 SHOULD。
  2. 每条规则绑定验证方式：CI 步骤、扫描器、或 Code Review checklist。
  3. 与 LLM 协作：把模板路径写进团队系统提示；要求生成代码引用对应目录。
  4. 每季度审计：删除过时条目，合并重复规则，避免文档膨胀导致无人阅读。
  5. 与 CodeSentinel 对齐：将 MUST NOT 高频违规转为自动化规则，降低审查摩擦。

小结

这 10 份模板不是「标准答案」，而是 高起点的企业级骨架。你可以按项目体量裁剪，但请保留四根支柱：架构边界、可验证规则、测试与安全、变更自检。当你把 AGENTS.md 当作持续运营资产时，AI 与自动化才能真正成为加速器，而不是架构噪声的放大器。

avatar
文章
阅读
粉丝