本加餐提供10 份可直接改造落地的AGENTS.md模板，覆盖 Python（API/数据）、Go（服务/CLI）、Java（Spring/DDD）、TypeScript（Next/Node）、React SPA 与多语言 Monorepo。每份模板均包含：项目语境、目录结构、架构规则、编码规范、测试与安全等区块。文末附使用指南：如何裁剪、如何与 CI/LLM 对齐、如何避免模板腐化。总原则（所有模板通用）先写边界，再写风格：架构与依赖方向比「用不用某种格式」更重要。规则必须可验证：每条MUST尽量对应扫描器或测试类型（或明确为人工评审项）。保持版本与 owner：模板不是一次性文档，需指定维护者与变更流程。给 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）