agents-generator 实操手册：七步生成 AGENTS.md，九条模板占位符填充规则，八问验收

agents-generator 实操手册七步生成 AGENTS.md九条模板占位符填充规则八问验收【免费下载链接】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本文拆解 AASAgentic Awesome Skills仓库中 agents-generator skill 的模板占位符填充规则这个 AGENTS.md 生成器如何在七步流水线里把检测到的真实项目证据填入assets/*.md模板的{{PLACEHOLDER}}为任意代码仓库产出项目专属的AGENTS.md与.agents/rules/*.md并通过八项验收标准。问题先行对 Agent 的决策价值才是生死线你大概率见过那种专业模板架构图里画着Component、Service数据流写着validate input命令区列着npm run dev——每个词都对但没有任何一个词属于当前项目。对 AI Agent 来说这类内容的危害比没有 AGENTS.md更严重模型会把这些泛化描述当成项目事实去执行用错误的包管理器跑命令、按虚构的架构改代码。agents-generatorcategory: developer-tools风险等级critical版本1.2.3的全部设计都围绕一个目标让输出里的每一句话都携带决策信息。它支持 full / minimal / update / dry-run 四种模式内置包管理器检测、monorepo 支持、备份、托管块、置信度评分和命令校验。证据链16 步顺序检测决定输出的每一句这个 skill 的三块参考文档分工明确decision-matrix.md 定义完整检测逻辑template-filling-guide.md 定义占位符填充规则example-output/README.md 提供质量基准。输入侧是一条 16 步顺序检测链前一步的结论会影响后一步的判断包管理器 → 项目类型 → 框架 → monorepo 工具 → 语言 → CSS 方案 → 测试 → 校验 → ORM → 状态管理 → API 客户端 → 表单 → 认证 → i18n → 后端模式 → Lint 与质量工具。输出侧只有一条原则写进文件的每个事实都必须能在目标项目中被再次验证。证据来源只有四类——package.json、锁文件与配置文件、目录结构与源码符号、git 历史。写不出证据的占位符宁可整节省略。这条原则贯穿后文所有填充规则。哪些规则文件会被生成、哪些不会信号速查检测器读完依赖清单、锁文件和目录结构后得到一组信号。下面的表就是看到什么、生成什么的速查依据检测器读到的证据对生成内容的影响package.json里有workspacesMonorepo产出包依赖规则与共享包重建命令turbo.json/nx.json/lerna.json命令适配为turbo run/nx/lerna rundeps 含next且存在app/或pages/App Router默认服务端组件或 Pages RoutergetServerSidePropsnestjs/core模块架构、guards、DTO 规则trpc/*一套与 REST 完全不同的后端规则react-hook-form/formik生成forms.mdnext-intl/react-i18next生成i18n.mdprisma/drizzle-orm生成database.mdstyled-components或存在.module.css生成规则不同的非 Tailwindstyling.mdnext-auth/clerk/nextjs/lucia路由保护规则tanstack/react-query/swr与 Zustand/Redux 不同的服务端状态规则devDeps 含vitest/jest/playwright生成命令正确的testing.md无 TypeScript跳过tsc改用不同类型的类型安全规则规则文件本身的触发条件同样写死在 decision-matrix.md 的 Rule File Selection 里规则文件触发条件architecture.md、git-workflow.md、sdd-workflow.md总是生成frontend-patterns.md存在前端框架时styling.md检测到 Tailwind/CSS Modules/styled-components纯 CSS 不算database.md检测到 Prisma/Drizzle/Knex/TypeORM/Mongoosetesting.mddevDeps 出现测试运行器server-actions.md存在use server文件、API 路由或 NestJS/Express/Fastify 后端只生成实际适用的规则是硬性要求纯前端项目里不得出现后端规则没有 ORM 的项目里不得出现数据库规则。九条占位符填充规则逐条拆解九个核心占位符按用途分成三组先管能跑起来的执行类再管看得清楚的结构类最后管守得住规矩的约定类。执行类命令、验证循环与测试数{{ESSENTIAL_COMMANDS}}只列真实存在的脚本键规则要点只收录package.json中脚本键确实存在的命令格式为{pm} run key或{pm} key与检测到的包管理器严格匹配bun 不带runnpm 用npm runpnpm/yarn 按惯例映射脚本缺失就整行省略绝不发明命令核心行覆盖 dev、build、lint、test、test:run、test:coveragedoctor/lint-staged 存在才加。数据出处package.json的 scripts 键值表与检测到的锁文件。验收信号输出里每一条命令都能在 SKILL.md 的硬性规则命令必须真实存在于 package.json scripts下通过复核在 agents-full.md 中它渲染为Command | Purpose | When三列表格多出何时运行决策列如pnpm test:run— Single-run tests — Before committing。这也是安全设计的一部分包脚本是仓库方控制的可执行代码把脚本写进文档不等于获得执行授权。skill 默认不运行项目脚本只检测并记录候选的 format/lint 命令是否执行由你在审查脚本正文后单独授权。{{VERIFICATION_CYCLE}}用验证过的命令拼装验证循环规则要点按{typecheck} → {lint} → {test} → {doctor}顺序组装只保留工具确实存在的步骤命令格式取自package.json原样。{typecheck}在 TypeScript 下是tsc --noEmitbun 项目为bunx tsc --noEmit无 TS 则跳过{lint}取{pm} run lint或检测到的 lint 命令{test}取test:run与test中单次运行的那个{doctor}仅在检测到 react-doctor 时加入。数据出处scripts 键值 tsconfig/锁文件/lint 配置的检测结果边界情况无测试运行器、无 lint、无 TS分别跳过对应步骤。验收信号基准示例bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor的每一步都能回溯到package.json中存在的命令。{{TEST_COUNT}}测试数是数出来的不是估出来的规则要点遍历所有测试文件统计实际出现的test()/it()调用次数报告 N tests 的真实数字无法精确统计时降级为 N test files同时附报测试运行器及版本、环境node/jsdom、覆盖率提供方与目标、是否严格 TDD 模式yes/no。数据出处测试文件源码中的调用计数运行器信息取自 devDeps 与配置文件。验收信号testing.md 模板要求输出 Total: N tests 或 N test files运行器精确到版本Vitest X.Y.Z基准案例是 74 tests5 个测试文件全部位于lib/。结构类架构图、数据流与路由表{{ARCHITECTURE_DIAGRAM}}用真实目录名画 ASCII 图规则要点必须使用项目实际存在的目录名绘制展示真实的 import 连接——哪个文件引用哪个文件禁止出现标注Component或Service的笼统方框monorepo 画包依赖箭头单应用画app/ → components/ lib/ → 外部服务的连接。数据出处目录树扫描与源码 import 语句。验收信号图里出现app/、components/、lib/downloader/这类打开仓库就能找到的目录名任何成员都能拿源码逐格核对。{{DATA_FLOW}}把函数调用用真名喊出来规则要点编号步骤 真实函数名——写detectPlatform()而不是validate input写ttdl(url)而不是call API完整链路覆盖用户操作 → 前端 → 后端/服务端动作 → 外部库/数据库 → 响应 → UI 更新步骤间用 ASCII 箭头连接。数据出处源码中的函数定义与调用关系。验收信号基准链路detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()全部可 grep 命中。强调真名不是文风偏好——Agent 后续正是靠这些名字在源码中定位入口与边界这也与 server-actions.md 模板中REQUEST_FLOW编号的典型请求流的设计互相呼应。{{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、API 路由、动态路由。数据出处路由目录的全量文件扫描。验收信号小节标题随框架变化Next.js App Router 用 RoutesNestJS/Express 用 Endpoints且漏掉任何一个路由文件都算不通过。约定类版本表、提交示例与全局约定{{STACK_TABLE}}版本逐个钉死规则要点每一行必须给出package.json中的精确版本号永远不出现latest或X.Y.Z行格式固定为层 | 技术 | 版本architecture.md 模板中为Layer | Technology | Version覆盖范围包含 framework、UI、runtime、ORM、validation、testing、linting、analytics、fonts。数据出处deps/devDeps 与配置文件。验收信号基准输出里的Vitest 4.x、ESLint 10 react-doctor 0.9.3这类条目每一格都能回查到依赖清单。{{COMMIT_EXAMPLES}}从真实 git 历史里取提交示例规则要点提供 2~3 个使用项目近期 git 历史中真实文件名或功能名的示例格式type: message每行一条有git log --oneline -5可用时必须读取它来获取真实素材。数据出处仓库最近的 git 提交记录。验收信号示例落在 git-workflow.md 模板规定的约束内——Conventional Commits 类型feat:/fix:/refactor:/test:/chore:/docs:、单次提交只含一个逻辑变更、短祈使句、无句尾句号、禁止 Co-Authored-By 或 AI 署名并按项目语言COMMIT_LANGUAGE书写。{{GLOBAL_CONVENTIONS}}每条约定都要能从配置文件验证规则要点列 5~8 条项目专属约定每条必须能在配置文件中找到对应证据填充方向覆盖包管理器、导入约定、命名、语言、校验方式等。数据出处锁文件、deps 清单、tsconfig 等配置。验收信号正例与反例的差距一目了然——✅ Bun siempre. No npm ni yarn.检测自 bun.lock ✅ Sin librería de validación externa — TypeScript types guards manuales.deps 中无 zod ❌ Usar buenas prácticas de TypeScript.泛化无法验证 ❌ Código limpio y documentado.泛化无法验证{{CODE_STYLE}}执行同一标准只写可验证的约定——TypeScript strict、no any、单双引号、分号、导入约定、UI 语言。- We use TypeScript 不行- TypeScript strict mode 才行。七步走完一次完整生成以下按 SKILL.md 的 Execution Steps 还原整条链路git rev-parse --show-toplevel确定项目根目录。先定包管理器bun.lock→bunpnpm-lock.yaml→pnpmpackage-lock.json→npmyarn.lock→yarn绝不默认 npm。读取package.jsonscripts、deps、workspaces把 scripts 留作后续命令校验的基准。读取非机密配置文件并探查目录结构。⚠️ 绝不读取.env*的值仅允许读纯占位形式的.env.example环境变量名只能从它的占位符与process.env.NAME源码引用推导。选择模式full / minimal / update / dry-run有歧义时先问你。Full 模式读取assets/agents-full.md与各规则模板逐项填充占位符输出AGENTS.md——内容包裹在!-- AGENTS-GENERATED-START --/!-- AGENTS-GENERATED-END --托管块之间——并生成.agents/rules/*.md。托管块的意义在于下次更新只重写标记内的内容标记之外的人工修改原样保留。后处理扫描{{、TODO、...并修正校验所有命令都存在于 scriptsAGENTS.md超 300 行发出警告、超 500 行强制迁移内容到规则文件用 Conventional Commits 格式汇总变更最后报告检测内容、生成/跳过内容与置信度评分。各模式的模板骨架分工agents-full.md承载 25 小节与全部占位符说明agents-minimal.md是 30 行标准格式无 YAML frontmatter、无规则文件、无 ASCII 图monorepo 子包使用agents-nested.md检测到 Claude Code.claude/或CLAUDE.md时依据assets/claude.md生成只指向 AGENTS.md 的瘦身版CLAUDE.md检测到 Cursor/Copilot/Gemini CLI/Windsurf 时依据assets/platform.md生成对应平台文件Codex 原生支持 AGENTS.md无需额外文件。验收八问怎么判断输出合格对照 example-output/README.md 的八项关键检查逐条追问一次生成结果检查项通过标准失败信号命令精确写bun dev而非npm run dev能由doctor: npx react-doctorlatest读出bun doctor包管理器张冠李戴命令查无此键验证循环真实bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor每条命令都在package.json中循环里出现未安装工具的步骤全局约定匹配技术栈Sin librería de validación externa — TypeScript types guards manuales (isDownloadError())凭空冒出 Zod para validación架构图具体ASCII 图展示真实目录app/、components/、lib/downloader/通用方框与占位标签数据流真名detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()validation → API call → database路由表完整每个路由文件都在列带类型client/server与项目 UI 语言描述漏路由、缺类型或描述语言不一致测试数量准确74 tests 来自实际测试文件的计数拍脑袋的估算值无占位残骸全文搜索{{、TODO、add here、...命中数为零任一残留词出现还有一组隐形契约条件型占位符遵循不适用即省略原则避免输出空壳小节。{{SERVER_ACTION_VS_API_SECTION}}仅在 Server Actions 与 API 路由并存时生成对比说明{{RATE_LIMIT_SECTION}}仅在存在 rate-limit 中间件时生成含限额与过期时间{{LANGUAGE_SECTION}}仅在项目使用 i18n 或非英语 UI 时生成。它不做什么四条能力边界产出的永远是提案。生成结果需人工评审后再提交采纳与否的裁判权始终在你手里skill 不会替你做合并决定。校验半径止于项目内部。命令校验只覆盖目标项目里可见的 scripts 与文件它无法证明某个工具、服务或平台命令在你的每一台机器、每一个 CI 环境里都能跑通。文档化不等于执行许可。项目提供的包脚本是不可信的可执行代码把脚本读进文档不构成运行授权默认情况下它一条项目脚本都不会执行。写入被锁死在你指定的项目范围内。它不越界写文件也不替代项目自身的安全、构建或部署评审。顺带一提这个 skill 在仓库中有两份镜像——plugins/agentic-awesome-skills-claude/skills/agents-generator/与 plugins/agentic-awesome-skills/skills/agents-generator/两者包含相同的模板、参考文档与填充规则交叉对照阅读不会踩到版本差。生成结果需人工评审后再提交——这也是这个 skill 反复强调的最后一道工序。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考