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

加餐 | 10 个企业级 AGENTS.md 模板覆盖 Go、Java、Python、TypeScript本加餐提供10 份可直接改造落地的AGENTS.md模板覆盖 PythonAPI/数据、Go服务/CLI、JavaSpring/DDD、TypeScriptNext/Node、React SPA 与多语言 Monorepo。每份模板均包含项目语境、目录结构、架构规则、编码规范、测试与安全等区块。文末附使用指南如何裁剪、如何与 CI/LLM 对齐、如何避免模板腐化。总原则所有模板通用先写边界再写风格架构与依赖方向比「用不用某种格式」更重要。规则必须可验证每条MUST尽量对应扫描器或测试类型或明确为人工评审项。保持版本与 owner模板不是一次性文档需指定维护者与变更流程。给 LLM 的提示把「禁止事项」写得更具体把「示例路径」写清楚减少模型臆造文件。模板 1Python 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 - MUSTpresentation 不得直接访问 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或自定义脚本。模板 2Python 数据管线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 可跑的「轻量校验」。模板 3Go 微服务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 - MUSTinternal 边界不可被外部模块导入 - MUSThandler 薄业务逻辑在 service/usecase - MUST NOT在领域层引入 gin/echo/net/http 具体类型 - MUSTcontext.Context 作为第一参数传递禁止存储在结构体中长期保存 ## 编码规范 - golangci-lint 全量启用格式化 gofmt - 错误处理wrap 错误带域信息对外映射统一在中间件 - 并发明确 goroutine 生命周期禁止泄漏与无界队列 ## 测试 - 表驱动单测覆盖核心规则API 用 httptest - 对客户端集成使用 docker compose 或 mock写明策略 ## 安全 - 输入校验DTO validator默认最小权限 - 依赖扫描govulncheck ## PR 自检清单 - [ ] 是否引入新的跨 package 循环依赖 - [ ] 是否暴露新的 metrics/trace - [ ] 是否更新 OpenAPI/Proto如有模板 4Go 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 与示例模板 5Java Spring Boot 服务# AGENTS.md — Java Spring Boot ## 项目语境 - 服务职责一句话 - Java 17Spring Boot 3.x构建Maven/Gradle写明 ## 目录结构示例 - domain/ 实体、值对象、领域服务 - application/ 用例服务、事务边界 - infrastructure/ JPA、消息、外部系统 - interfaces/ REST Controller、DTO、Mapper ## 架构规则MUST - MUSTController 只做编排与校验不写业务规则 - 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 文档模板 6Java 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依赖方向指向 domainadapter 仅依赖 port - MUST聚合不变量在模型内保证跨聚合用领域事件或应用服务编排 - MUST NOTadapter 之间横向调用必须通过用例 ## 编码规范 - 命名体现 ubiquitous language禁止「通用」DTO 污染领域 - 映射层明确Anti-Corruption Layer 位置固定 ## 测试 - 领域单测不依赖 Springadapter 用集成测试 ## 安全 - 出站调用必须超时/重试/熔断策略在 adapter 实现 ## PR 自检清单 - [ ] 是否引入新的上下文映射是否需要更新上下文图 - [ ] 领域事件是否幂等模板 7TypeScript Next.js 全栈# AGENTS.md — Next.jsApp Router ## 项目语境 - 产品边界一句话 - Next.js 版本包管理pnpmNode 版本 ## 目录结构 - app/ 路由与 server actions如使用 - components/ UI 组件按域分子目录 - lib/ 共享工具无业务语义 - server/ 服务端用例、数据访问封装 - types/ 共享类型 ## 架构规则MUST - MUST禁止在客户端 bundle 引入服务端密钥依赖 - MUST数据访问集中在 server 层组件层不直接拼 SQL/HTTP 细节按你们封装 - MUST NOT在 use client 组件中泄露内部 API 密钥 - MUSTServer Actions 输入校验使用 zod或等价 ## 编码规范 - ESLint PrettierTypeScript strict - 组件拆分展示 vs 容器避免巨型页面文件 ## 测试 - Vitest/Jest Testing Library关键交互 e2ePlaywright ## 安全 - CSP、Cookie 策略、CSRF按部署模式写明 - 依赖审计pnpm audit ## PR 自检清单 - [ ] 是否区分 RSC/Client 边界 - [ ] 是否新增需要环境变量是否更新 .env.example模板 8TypeScript 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 - MUSThandler 薄错误映射集中 - MUST NOT在 domain 引入框架类型 - MUST所有外部 IO 具备超时默认重试策略可配置 ## 编码规范 - eslint typescript-eslint strict - 日志结构化request id 贯通 ## 测试 - 单测 supertest 集成数据库用 test container 或内存替代写明 ## 安全 - 输入校验速率限制鉴权中间件默认开启 - SSRF 防护对外 URL fetch 需白名单/解析校验 ## PR 自检清单 - [ ] 是否变更 API 契约是否同步客户端 SDK - [ ] 是否评估性能热点N1模板 9React 前端 SPAVite# AGENTS.md — React SPA ## 项目语境 - 应用类型管理后台/用户端路由React Router版本写明 ## 目录结构 - src/features/feature/ 按特性分包页面、组件、api、model - src/shared/ 设计系统级组件与 hooks - src/app/ 入口、providers、路由表 ## 架构规则MUST - MUSTfeature 间禁止深层相对路径耦合共享只能通过 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模板 10Monorepo多语言 / 多包# 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 自检清单 - [ ] 是否动到共享契约是否同步所有消费者 - [ ] 是否评估对其他包的构建时影响使用指南如何把模板变成「你们公司的真规则」先选 8 条 MUST越少越能执行其余降级为 SHOULD。每条规则绑定验证方式CI 步骤、扫描器、或 Code Review checklist。与 LLM 协作把模板路径写进团队系统提示要求生成代码引用对应目录。每季度审计删除过时条目合并重复规则避免文档膨胀导致无人阅读。与 CodeSentinel 对齐将MUST NOT高频违规转为自动化规则降低审查摩擦。小结这 10 份模板不是「标准答案」而是高起点的企业级骨架。你可以按项目体量裁剪但请保留四根支柱架构边界、可验证规则、测试与安全、变更自检。当你把 AGENTS.md 当作持续运营资产时AI 与自动化才能真正成为加速器而不是架构噪声的放大器。