如何生成"真实"的 AGENTS.md：agents-generator 模板填充机制完整解析

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

AAS（Agentic Awesome Skills）仓库里的agents-generator（v1.2.3，开发者工具类 skill）做一件事：分析代码库，生成项目专属的 AGENTS.md 与.agents/rules/规则文件。它背后只有一条铁律——可验证性：写进输出的每一个事实，都必须能在目标项目中再次验证。

为什么这么较真？因为生成器最容易产出"看似专业实则空洞"的模板：满篇Component、Service、validate input。这种 AGENTS.md 对 AI Agent 毫无决策价值——找不到入口、划不出边界，Agent 只能继续瞎猜。

生成前：16 步检测链与规则文件映射速查

先说模式：full（全量输出）、minimal（约 30 行精简版）、update（备份到.agents/backups/后重检测、只更新变化项）、dry-run（只检测与预览，不写盘）。无论哪种模式，第一步都一样：git rev-parse --show-toplevel定位项目根，然后先看锁文件——bun.lock→bun，pnpm-lock.yaml→pnpm，package-lock.json→npm，yarn.lock→yarn。红线：绝不默认 npm，所有输出命令必须使用检测到的包管理器。

接着按固定顺序走完 16 步，每步把结论写成 flag 供后续步骤消费：包管理器 → 项目类型（workspaces判定 monorepo）→ 框架（Next.js 按app/与pages/区分 App / Pages Router）→ monorepo 编排器（turbo.json/nx.json/lerna.json）→ 语言（tsconfig.json及strict: true）→ CSS 方案 → 测试运行器 → 校验库 → ORM → 状态管理（React Query/SWR 属服务端状态，Zustand/Redux 属客户端状态，规则不同）→ API 客户端 → 表单库 → 认证库 → i18n → 后端模式（"use server"文件、app/api/路由）→ Lint 与质量工具。完整逻辑与边界情况见 references/decision-matrix.md。

🔍 检测结束后你拿到一组"信号"。信号驱动规则文件的选择，速查如下：

architecture.md、git-workflow.md、sdd-workflow.md无条件生成；其余文件服从一条硬性要求：不适用即不生成——纯前端项目不得出现后端规则，无 ORM 不得出现数据库规则。

生成中：占位符填充的三条及格线

full 模式会读取 assets/agents-full.md 与 assets/ 下的各规则模板，逐个填充{{PLACEHOLDER}}（模板里的双大括号标记，即待填位置）。判卷标准写在 references/template-filling-guide.md。9 个高频占位符可以归成三条及格线。

及格线一：必须精确的事实——版本、数量、命令

• {{STACK_TABLE}}：每行带package.json中的精确版本号，覆盖 framework、UI、runtime、ORM、testing 等层。✅Vitest 4.x、ESLint 10 + react-doctor 0.9.3。❌latest、X.Y.Z。
• {{ESSENTIAL_COMMANDS}}：只写package.json中脚本键真实存在的命令，缺失就删行，绝不发明命令。在 agents-full.md 中它渲染为Command | Purpose | When三列表，多出"何时运行"一列。✅bun run test:run（script key 存在且检测到 bun）。❌npm run dev（锁文件是bun.lock却写了 npm）。
• {{TEST_COUNT}}：数出所有测试文件中test()/it()的真实调用次数，报"N tests"；数不准就降级报"N test files"。附运行器版本、环境（node/jsdom）、覆盖率提供方、是否严格 TDD（yes/no）。❌ "测试覆盖全面"这类没有数字的句子。
• {{VERIFICATION_CYCLE}}：按{typecheck} → {lint} → {test} → {doctor}组装，只收录工具确实存在的步骤。示例：bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor，链条里每条命令都能翻到对应的 script key。

及格线二：必须落图的骨架——架构图、数据流、路由表

• {{ARCHITECTURE_DIAGRAM}}：用项目实际存在的目录名画 ASCII 图，展示真实 import 关系。Monorepo 画包依赖箭头；单应用画app/ → components/ + lib/ → 外部服务。✅ 图里出现app/、components/、lib/downloader/。❌ 标着Component、Service的笼统方框。
• {{DATA_FLOW}}：编号步骤 +真实函数名，走完整链路"用户操作 → 前端 → 服务端动作 → 外部库/数据库 → 响应 → UI 更新"。✅detectPlatform()→downloadVideo()→downloadFromUrl()→ttdl()/igdl()/fbdown()/twitter()。❌ "调用 API → 存数据库"。
• {{ROUTING_TABLE}}：app/或pages/下每一个路由文件都列一行，含路由路径、类型（server/client/API）、文件路径、一行用途（用项目 UI 语言）。page.tsx、layout.tsx、route.ts、error.tsx、loading.tsx、not-found.tsx、sitemap.ts、robots.ts与动态路由一个都不能漏。

及格线三：必须真实的惯例——提交示例、全局约定

• {{COMMIT_EXAMPLES}}：给 2~3 个来自近期 git 历史的真实示例，用git log --oneline -5读出来，套用真实文件名或功能名，格式type: message每行一条。assets/git-workflow.md 模板还规定：单次提交只含一个逻辑变更、短祈使句、无句尾句号、禁止 "Co-Authored-By" 或 AI 署名。
• {{GLOBAL_CONVENTIONS}}：5~8 条项目专属约定，每条必须能从配置文件验证。
  • ✅ "Bun 唯一包管理器，不用 npm 也不 yarn。"（由bun.lock检测得出）
  • ✅ "无外部校验库——TypeScript 类型 + 手动 guards。"（deps 中没有 zod）
  • ❌ "使用 TypeScript 良好实践。"（泛化，无法验证）
  • ❌ "代码整洁、注释齐全。"（泛化，无法验证）

模板里还有一批条件型占位符：{{SERVER_ACTION_VS_API_SECTION}}仅在 Server Actions 与 API 路由并存时生成，{{RATE_LIMIT_SECTION}}仅在检测到 rate-limit 中间件时生成，{{LANGUAGE_SECTION}}仅在 i18n 或非英语 UI 时生成——统一遵循不适用即省略，不许留下空壳小节。

生成后：8 条验收自检清单与红线

文件写完，生成器还要跑一遍后处理：扫描输出中的{{、TODO、...并逐一修正；校验所有命令都存在于 scripts；AGENTS.md超 300 行警告，超 500 行强制把内容拆进规则文件；正文用<!-- AGENTS-GENERATED-START -->/<!-- AGENTS-GENERATED-END -->这对注释标记包裹——这就是"托管块"，作用是让后续 update 只动标记区域内的内容。

🛡️ 对照 references/example-output/README.md 做验收，8 条：

1. 命令精确：写bun dev而不是npm run dev；读到"doctor": "npx react-doctor@latest"→ 输出bun doctor。
2. 验证循环真实：链条里每条命令都能在package.json的 scripts 中翻到，不跳步、不编造。
3. 约定匹配技术栈：写 "无外部校验库——TypeScript 类型 + 手动 guards（isDownloadError()）"，而不是凭空写 "用 Zod 做校验"。
4. 架构图具体：ASCII 图展示真实目录，不是通用占位框。
5. 数据流用真实函数名，不是"校验 → 调接口 → 落库"的流程套话。
6. 路由表完整：每个路由文件都在，带类型与 UI 语言描述。
7. 测试数准确：数字来自实际测试文件统计，不是估算。
8. 零占位文本：在输出里搜{{、TODO、add here、...，匹配数必须为零。

最后说清边界：生成结果是提案，需人工评审后才能采纳或提交；命令校验只覆盖项目内可见的 scripts 与文件，无法证明工具、服务或平台命令在所有环境可用；项目脚本视为不可信可执行代码——记录与文档化不构成运行授权，skill 默认不执行任何项目脚本，只在你单独授权且审阅过脚本正文后才可能执行。它也不授权在项目范围之外写文件，更不替代项目自身的安全、构建与部署评审。

补充一句：该 skill 在仓库中有两份内容相同的镜像，skills/agents-generator/与plugins/agentic-awesome-skills-claude/skills/agents-generator/，审查规则时可交叉对照。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills