agents-generator 决策矩阵全解析从项目检测到 AGENTS.md 规则生成的 16 步判定流程【免费下载链接】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,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本篇文章基于 agentic-awesome-skills 仓库中 agents-generator 技能SKILL.md的核心参考资料 decision-matrix.md系统讲解如何通过读取锁文件、配置文件与目录结构判定目标项目的包管理器、框架、路由模式、CSS 方案、测试框架、ORM、状态管理等技术栈并据此决定生成哪些.agents/rules/*.md规则文件与AGENTS.md章节。读完本文你将掌握 agents-generator 完整的分步检测顺序、标志位映射规则、命令生成与验证周期组装逻辑以及 12 类典型边界情况的处理策略能够理解甚至复现为任意代码库自动生成项目级 AGENTS.md的底层判定引擎。决策矩阵在 agents-generator 中的定位agents-generator 是一个用于通过分析代码库生成项目专属 AGENTS.md 与配套规则文件的技能支持 full、minimal、update、dry-run 四种模式并具备包管理器检测、monorepo 支持、备份、受管代码块、置信度评分与命令校验能力。其核心约束写在其 SKILL.md 的 Hard Rules 中先读后写但绝不读密钥只读package.json、非密钥配置文件与目录结构绝不打开.env、.env.local等凭据文件环境变量名只能从.env.example占位符与process.env.NAME引用推导。先检测包管理器根据锁文件判定绝不默认 npm。只生成适用的内容纯前端项目不生成后端规则没有 ORM 不生成数据库规则。校验命令输出中的每条命令必须存在于package.json的 scripts 键中。无占位符扫描{{、TODO、add here、...存在即拒绝。而 decision-matrix.md 正是这套约束的判定引擎——它定义了完整的检测顺序Detection Order、规则文件选择Rule File Selection、AGENTS.md 章节选择AGENTS.md Section Selection、命令生成Command Generation与边界情况Edge Cases。同时template-filling-guide.md 称它为完整检测逻辑Full detection logic并提供了快速决策表作为补充速查。一、检测顺序16 步逐级判定每一步读取文件并设置后续标志位决策矩阵规定检测必须按下述顺序执行Detection Order每一步读取文件并设置供后续步骤使用的标志位。顺序本身即依赖关系包管理器的判定影响后续所有命令的写法框架判定影响路由检测方式monorepo 判定影响命令生成形态。1. 包管理器Package manager锁文件优先检查锁文件顺序与映射如下bun.lock→bunpnpm-lock.yaml→pnpmpackage-lock.json→npmyarn.lock→yarn这条规则与 SKILL.md 的 Hard Rules 完全一致Detect package manager FIRST... NEVER default to npm. 包管理器决定后续命令生成小节中{pm}的取值bun 脚本可直接不带run执行pnpm 用pnpmnpm 用npm runyarn 用yarn。2. 项目类型Project typeworkspaces 判定检查根目录package.json中的workspaces字段存在workspaces→monorepo不存在 →single app单应用3. 框架Framework依赖 路由检测根据依赖中出现的包判定框架并执行对应的路由检测逻辑Dep foundFrameworkRouter detectionnextNext.jsapp/下有page.tsx或layout.tsx→ App Routerpages/下有.tsx→ Pages Router两者都有 → hybrid按 App Router 为主nestjs/coreNestJSN/AviteVite检查react→ React、vue→ Vue、svelte→ Svelteangular/coreAngularN/AexpressExpressN/AfastifyFastifyN/Aremix/remix-run/*RemixN/AastroAstroN/A这里值得注意Next.js 是唯一需要做路由器二次检测的框架App Router / Pages Router / hybrid 三种形态会直接影响后续规则文件与章节的生成详见下文框架特定约定。4. Monorepo 工具Monorepo tool仅当 monorepo 时执行File foundToolturbo.jsonTurboreponx.jsonNxlerna.jsonLerna仅pnpm-workspace.yamlpnpm workspaces无编排器该结果直接影响命令生成小节中turbo run {cmd}、nx {cmd} {pkg}、pnpm --filter {pkg} {cmd}等变体的生成。5. 语言Languagetsconfig 判定存在tsconfig.json→TypeScript检查compilerOptions.strict: true→strict 模式若项目非 TypeScript后续验证周期将跳过tsc --noEmit并在规则中改用 JSDoc 约定见边界情况。6. CSS 方案CSS approach信号优先级判定SignalApproachtailwindcssin depsTailwind CSScomponents.jsonexistsshadcn/ui隐含 Tailwindstyled-componentsin depsstyled-componentsemotion/*in depsEmotion.module.css或.module.scss文件存在CSS Modulessass或node-sassin depsSass/SCSS以上皆无Plain CSS / CSS imports需要特别指出多方案并存时并非全部生成规则。决策矩阵在边界情况中明确Pick primaryTailwind wins over CSS Modules over plain CSS——即 Tailwind 优先于 CSS Modules 优先于纯 CSS且 example-output/README.md 展示了Tailwind 被并入 frontend-patterns.md不单独生成 styling.md的实践。7. 测试Testingrunner 与测试环境Dep foundRunnerExtravitestVitest检查vitest.config.*获取环境node/jsdom/happy-domjestJest检查jest.config.*获取环境playwright或playwright/testPlaywright存在 E2E 测试cypressCypress存在 E2E 测试None—跳过测试规则注意这里的深层逻辑单元测试框架Vitest/Jest与 E2E 框架Playwright/Cypress可以共存决策矩阵将其视为同一检测步骤的不同信号。测试环境node vs jsdom vs happy-dom的判定来自 runner 配置文件这与 testing.md 模板中的TEST_RUNNER_INFO占位符填充规则Vitest X.Y.Z 或 Jest X.Y.Z如两者都存在需说明各自用途一一对应。8. 验证Validation校验库判定Dep foundLibraryzodZodyupYupclass-validatorclass-validatorvalibotValibotNonePlain TypeScript类型守卫 手工验证该步骤的判定不仅决定是否生成 Zod 相关章节还决定了全局约定的措辞方向example 输出中的典型写法是 Sin librería de validación externa — TypeScript types guards manuales (isDownloadError())即没有验证库本身也是一条可验证的项目约定而 template-filling-guide.md 明确禁止 Usar buenas prácticas de TypeScript 这类无法验证的通用语句。9. ORM / 数据库ORM / Database依赖 provider 判定Dep foundORMDetect providerprismaPrisma读prisma/schema.prisma→datasource db { provider ... }drizzle-ormDrizzle检查drizzle.config.*中的dialectknexKnex检查knexfile.*中的 clienttypeormTypeORM检查配置中的typemongooseMongoDB/MongooseN/A决策矩阵特别强调provider 影响 ID 类型约定——PostgreSQL 用 UUIDSQLite/MySQL 用 autoincrementMongoDB 用 ObjectId。这与 database.md 模板的DB_CONVENTIONS填充规则呼应IDs:uuidvscuidvsautoincrementvsObjectId需从 schema 中检测。同时该模板还要求补充 timestampscreatedAtupdatedAt、命名DB 用snake_case、代码用camelCase、枚举策略原生 DB 枚举 vs 字符串 vs TS 枚举、软删除是否存在deletedAt字段等约定这些都是检测阶段需要读取 schema 才能填实的字段。10. 状态管理State managementclient state 与 server state 分野Dep foundLibraryzustandZustandreduxjs/toolkitRedux ToolkitjotaiJotaivaltioValtiorecoilRecoilmobxMobXxstateXStatetanstack/react-queryReact Queryserver stateswrSWRserver stateNone仅 useState / useReducer决策矩阵在此强调了一个关键分类原则server-state 库React Query、SWR需要的规则与 client-state 库Zustand、Redux完全不同必须区分对待。example-output 中项目无任何状态库检测结果是 useState / useCallback only (no Zustand/Redux)同样作为一条可验证约定写入规则。11. API 客户端模式API client pattern请求形态判定SignalPatterntrpc/*in depstRPCgraphqlapollo/clientGraphQL (Apollo)graphqlrelay-runtimeGraphQL (Relay)tanstack/react-queryfetchREST with React QueryswrfetchREST with SWRaxiosin depsREST with Axios存在use server服务端动作文件Server Actionsapp/api/下有route.ts文件Next.js API Routessrc/下有 NestJS controllersNestJS REST以上皆无直接使用fetch()该模式的判定直接影响后端规则文件的内容取向。template-filling-guide.md 明确提示trpc/*意味着与 REST 完全不同的后端规则completely different backend rules than REST说明 API 客户端模式是规则文件内容分叉的关键维度。12. 表单库Form libraryDep foundLibraryreact-hook-formreact-hook-formformikFormiktanstack/react-formTanStack Formhookform/resolversreact-hook-form Zod/Yup resolverNone手动受控/非受控输入hookform/resolvers的存在意味着 react-hook-form 与 Zod/Yup 校验器组合使用生成表单规则时需同时体现表单库与校验库两层约定。13. 认证库Auth library依赖 附加文件检测Dep foundLibraryExtra detectionnext-authNextAuth v5 (Auth.js)检查auth.ts、middleware.ts路由保护next-authv4NextAuth v4检查[...nextauth].tsclerk/nextjsClerk检查middleware.tslucia/lucia-authLucia检查auth.tssupabase/supabase-jssupabase/ssrSupabase Auth检查 middlewarefirebasefirebase/authFirebase Auth检查firebase.ts配置auth0/*Auth0检查auth0.tsNone无认证或自建—注意同一依赖的不同主版本被拆成两个信号next-authv5 与 v4 的检测文件完全不同体现了决策矩阵版本敏感的判定粒度。检测到的认证库将触发 template-filling-guide.md 快速决策表中的 Auth → route protection rules路由保护规则。14. i18n 库i18n library依赖 配置文件 语言提示Dep foundLibraryExtra detectionnext-intlnext-intl检查i18n.ts、messages/、middleware 配置react-i18nexti18nextreact-i18next检查i18n.ts、locale JSON 文件next-i18nextnext-i18next检查next-i18next.config.jslingui/*Lingui检查lingui.config.*None无 i18n检查html中的lang作为语言提示即便未检测到任何 i18n 库也会通过lang属性给出 UI 语言提示这正是 example-output 中 hardcoded Spanish硬编码西班牙语结论的判定来源——无 i18n 库时界面语言本身仍构成一条项目约定。15. 后端模式Backend pattern源码信号判定SignalPattern文件包含use serverServer Actionsapp/api/下有route.tsNext.js API RoutesNestJS controllersNestJS RESTExpress/Fastify 路由文件REST APItRPC routerstRPC APIGraphQL resolversGraphQL API此步骤与第 11 步API client pattern互补第 11 步从依赖与文件信号判定前端如何调用第 15 步则从源码结构判定后端如何暴露。两者共同决定 architecture.md 模板中SERVER_ACTION_VS_API_SECTION占位符是否填充——若同时存在 server actions 与 API routes需说明谁是主路径及其差异只有一种则跳过该对比小节。16. Linting 与质量Linting Quality配置形态判定File/Dep foundTooleslintin depsESLinteslint.config.*ESLint flat config.eslintrc.*ESLint legacy configprettierin depsPrettier.prettierrc*Prettier configuredreact-doctorin depsreact-doctordoctor.config.*react-doctor configuredbiome.jsonBiome.oxlintrc.*oxlint该步骤对 ESLint 两种配置形态flat config 与 legacy config做了区分且能检测 react-doctor 这一 React 项目专用质量工具——example-output 中doctor: npx react-doctorlatest即由此信号驱动最终进入验证周期并映射为bun doctor。二、规则文件选择将检测标志映射到待生成文件检测完成后将上述标志位映射为实际要生成的.agents/rules/*.md文件。决策矩阵给出的映射表如下Rule FileRequired Whenarchitecture.md总是生成frontend-patterns.md存在 React/Next.js/Vite/Angular/Vue/Svelte 前端backend-patterns.md存在 NestJS 后端server-actions.md使用 server actions或有 API routes或有 NestJS/Express/Fastify 后端styling.md有 Tailwind、CSS Modules 或 styled-components纯 CSS 不生成forms.md有 react-hook-form、formik 或 TanStack Formdatabase.md有 Prisma、Drizzle、Knex、TypeORM 或 Mongoosei18n.md有 next-intl、react-i18next 或类似库testing.mddevDeps 中有测试 runnervitest/jest/playwright/cypressgit-workflow.md总是生成sdd-workflow.md总是生成总是生成的文件恰好三个architecture.md、git-workflow.md、sdd-workflow.md——它们不依赖任何技术栈信号。example-output 中的跳过清单Skipped with reasons正是该表反向应用的实例backend-patterns.md无 NestJS 后端styling.mdTailwind 已并入 frontend-patterns且无 CSS Modules 或 styled-componentsforms.md无表单库仅手动受控输入database.md无 ORMi18n.md无 i18n 库硬编码西班牙语这印证了 SKILL.md 的 Hard Rule——Generate only what applies以及 template-filling-guide.md 快速决策表中styled-components /.module.css→ 生成 styling.md规则不同的细化分支。三、AGENTS.md 章节选择按检测结果裁剪主文档Full 模式下生成的 AGENTS.md 并非固定模板而是依据检测结果裁剪章节。决策矩阵给出的章节选择表SectionInclude WhenMonorepo Structurepackage.json中有workspacesMonorepo Tool Commands检测到 Turborepo/Nx/LernaNext.js Router Convention检测到 Next.js → App Router 与 Pages Router 各自的规则Zod Validation Conventiondeps 中有zod、yup或valibotPlain TS Validation Convention无验证库但为 TypeScript strictPrisma Conventiondeps 中有prismaDrizzle Conventiondeps 中有drizzle-ormServer Actions Convention检测到use server文件tRPC Convention检测到 tRPCGraphQL Convention检测到 GraphQLTailwind Conventiondeps 中有tailwindcssshadcn/ui Convention存在components.jsonCSS Modules Convention找到.module.css文件Styled Components Conventiondeps 中有styled-componentsState Management Sectiondeps 中有 Zustand/Redux/Jotai/MobX/XStateServer State Sectiondeps 中有 React Query/SWRForm Library Sectiondeps 中有 react-hook-form/formik/TanStack Formi18n Section检测到 i18n 库Auth Section检测到认证库react-doctor Convention存在doctor.config.*或 deps 中有react-doctorUI Language Convention检查lang属性或 i18n 配置此表与 agents-full.md 模板Remove sections whose condition is not met——移除条件不满足的章节直接对应模板定义了全部占位符章节而决策矩阵的章节选择表决定哪些占位符被填充、哪些被删除。值得注意的两组对照Zod 与 Plain TS 验证章节互斥二选一取决于第 8 步检测State Management 与 Server State 是两个独立章节对应第 10 步的 client/server state 分野。四、命令生成与验证周期包管理器注入与脚本校验scripts 直接映射命令表直接从package.json的scripts键生成。决策矩阵给出的映射示例{ scripts: { dev: ..., build: ..., lint: ..., test: ... } }映射为ComandoQué hace{pm} devServidor de desarrollo{pm} run buildBuild de producción{pm} run lintLinting{pm} run testTests (watch)可额外追加的行test:run单次运行、test:coverage覆盖率、doctor、format、typecheck。其中{pm}取值规则bun 脚本无需run前缀bun devpnpm 用pnpmnpm 用npm runyarn 用yarn。需要再次强调的约束来自 SKILL.md只输出在package.json中确实存在的 script 键命令缺失的脚本直接省略该行绝不凭空发明template-filling-guide.md 的{{ESSENTIAL_COMMANDS}}规则与此一致。这正是 example-output 质量检查第 1 条的依据The AGENTS.md saysbun dev, notnpm run devorpnpm dev。Monorepo 命令变体Turborepo生成turbo run {cmd}变体pnpm workspaces生成pnpm --filter {pkg} {cmd}示例Nx生成nx {cmd} {pkg}变体验证周期组装从检测到的工具组装验证周期Verification cycle{typecheck} → {lint} → {test} → {doctor}{typecheck}TypeScript 项目用tsc --noEmitbun 项目用bunx tsc --noEmit无 TS 则跳过{lint}{pm} run lint或检测到的 lint 命令{test}{pm} run test:run或{pm} run test取单次运行的那个{doctor}{pm} doctor或检测到 react-doctor 时用{pm}x react-doctorlatest否则跳过example-output 中的真实示例为bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor其质量检查第 2 条要求每条命令都存在于 package.json。该周期也会被写入 testing.md 模板的{{VERIFICATION_CYCLE}}占位符。Monorepo 重建提示若为带共享包的 monorepo需在周期前追加共享包重建提示Si se modificaron packages compartidos ({shared_pkg_list}), ejecutar su rebuild primero: {rebuild_commands}对应 template-filling-guide.md 快速决策表中的第一行workspacesin package.json → 生成包依赖规则与共享包重建命令以及 agents-full.md 中的{{MONOREPO_REBUILD_NOTE}}占位符。五、框架特定约定路由形态决定规则取向决策矩阵为三种最常见的框架形态给出了内建约定这些约定会注入对应的规则文件。Next.js App Router默认 Server Components仅在使用 hooks 时才用use client决策矩阵原文为西语use clientsolo cuando se usen hooksServer actions 位于lib/actions.ts或src/actions/按 segment 放置error.tsx、loading.tsx、not-found.tsx用generateMetadata()做 SEO图片用next/image字体用next/fontPath alias/*→./*或./src/*Next.js Pages Router使用getServerSideProps、getStaticProps、getStaticPathspages/api/用于 API routespages/_app.tsx、pages/_document.tsx无 server components——一切皆为 client 或 APIApp Router 与 Pages Router 的约定取向差异巨大Server Components 默认 vs 全部 client/API这正是第 3 步路由检测必须先行区分的原因。当 hybrid 并存时决策矩阵在第 3 步规定按 App Router 为主处理并在边界情况中进一步要求注明 Pages Router legacy routes。NestJS模块按目录组织src/{feature}/{feature}.module.tsDTO 用装饰器验证用class-validator或ZodValidationPipe认证用 GuardsUseGuards(AuthGuard)PrismaService作为全局 provider六、边界情况12 类异常场景的处理策略决策矩阵在结尾给出了完整的边界情况表这是判定引擎的鲁棒性保障SituationAction无测试 runner跳过testing.md验证周期去掉 test 步骤无 lint 工具验证周期去掉 lint 步骤无 TypeScript跳过tsc --noEmit跳过 no-any 规则改用 JSDoc 约定完全没有配置文件输出最小默认值并注明项目需要初始化多框架并存以根package.json判定主框架注明次要框架App Router 与 Pages Router 并存以 App Router 为主注明 Pages Router 遗留路由package.json无 scripts直接用工具命令生成如npx next devbun 无bun run脚本用bunx前缀替代 npx 等价命令monorepo 但无 workspaces将每个apps/*或packages/*视为独立项目处理CSS 多方案并存选主方案Tailwind CSS Modules plain CSS认证多库并存选主库、注明次要库如 web 用 NextAuth、admin 用 Clerki18n 与 Pages Router 组合路由规则与 App Router 的 i18n 不同数据库多 provider分别记录并注明哪个是主 provider这些边界情况与 template-filling-guide.md 快速决策表中的 No TypeScript → 跳过 tsc不同类型安全规则 相互印证同时也呼应了 SKILL.md 的置信度评分机制——检测不完整或信号冲突时最终输出需报告置信度。七、与模板填充指南的配合从标志位到具体内容的落地决策矩阵解决检测什么而 template-filling-guide.md 解决填充成什么样。两者配合的关键规则包括{{STACK_TABLE}}每行必须使用package.json中的精确版本号禁止 latest 或 X.Y.Z 占位格式为| Capa | Tecnología | Versión |覆盖框架、UI、运行时、ORM、验证、测试、lint、分析、字体。{{ARCHITECTURE_DIAGRAM}}ASCII 图必须使用项目真实目录名展示真实的 import 关系禁止 Component、Service 这类通用框monorepo 需画包依赖箭头。{{DATA_FLOW}}编号步骤必须使用真实函数名如detectPlatform()、ttdl(url)而非 validate input、call 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、API routes 与动态路由。{{TEST_COUNT}}统计全部测试文件中真实的test()/it()调用次数报告N tests无法精确统计时报告N test files同时报告 runner 及版本、环境node/jsdom、覆盖率提供方与目标、是否为严格 TDD 模式。{{COMMIT_EXAMPLES}}使用git log --oneline -5获取真实文件/功能名格式为type: message每行一条。{{VERIFICATION_CYCLE}}只组装工具确实存在的步骤命令格式严格来自package.json。{{GLOBAL_CONVENTIONS}}5-8 条必须可从配置文件验证的项目约定反例是 Usar buenas prácticas de TypeScript、Código limpio y documentado 这类通用且不可验证的语句。而 example-output/README.md 提供了可对照的质量基准一个 Bun Next.js 16 App Router Tailwind 4 shadcn/ui Vitest Server Actions 的项目最终产出 85 行 AGENTS.md 与 6 个规则文件并附 8 条质量检查命令精确、验证周期真实、全局约定与栈匹配、架构图具体、数据流使用真实函数名、路由表完整、测试数准确、零占位符。结语decision-matrix.md 表面上是 agents-generator 的一份检测清单实质上是整个技能从不猜测、只依据事实生成的判定内核16 步检测顺序构建了技术栈事实层规则文件选择表与章节选择表将其转化为生成决策命令生成与验证周期组装保证输出可执行、可校验而 12 类边界情况确保了它在异构、残缺、冲突的项目状态下的稳健表现。理解这张矩阵你便掌握了为任意代码库自动产出项目级 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,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考