深入解析 agents-generator 的 AGENTS.md 全量模板：为 AI 代理生成项目级协作规范的完整指南

AI 技能AI 插件人工智能【免费下载链接】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点击查看免费下载导读AGENTS.md 正逐渐成为 AI 代理理解代码库、遵守项目约定、正确执行任务的标准入口。本文聚焦于 agentic-awesome-skills 仓库中 agents-generator 技能的核心资产——全量模式模板 agents-full.md系统拆解其 30 个模板区块的结构、填充规则与条件启用逻辑并结合 SKILL.md、模板填充指南 与 决策矩阵 等仓库源码说明如何把占位符模板变成一份与真实工具链完全匹配、可被 Claude Code、Cursor、Copilot 等代理直接消费的活的项目规范文档。读完本文你将掌握全量 AGENTS.md 的完整章节骨架、每个占位符的填充口径、条件区块的检测信号以及 300/500 行的体量管控策略。一、模板定位Full Mode 与 Minimal / Nested 模式的分工agents-generator 技能面向分析代码库并生成项目专属 AGENTS.md 及配套规则文件这一场景。其 SKILL.md 明确声明产出的是与目标项目真实工具链匹配的活文档而非带占位符的通用模板。围绕输出形态技能提供了三种模板资产模板适用模式产出形态assets/agents-full.mdFull Mode完整模式默认富 AGENTS.md .agents/rules/*.md配套规则文件assets/agents-minimal.mdMinimal Mode用户说简单/最小时单个约 30 行的 AGENTS.md无规则文件、无 ASCII 图assets/agents-nested.mdMonorepo子包每个子包一份约 20 行的轻量 AGENTS.md根据 SKILL.md 的模式选择表用户说 simple AGENTS.md、just the basics、minimal →Minimal模式输出单文件、约 30 行、不含规则文件用户说 full AGENTS.md、with rules、complete或未明确 →Full模式输出 AGENTS.md .agents/rules/*.md用户说 update AGENTS.md、refresh、my stack changed →Update模式对既有文件做差异对比仅重新生成发生变化的部分。本文讨论的全量模板即 Full Mode 的骨架它同时声明与 agents.md 标准兼容60k 项目这意味着生成结果可以在生态中被广泛消费而非私有格式。二、全量模板的章节骨架从概览到 PR 指令agents-full.md 第一段给出了总体使用约定将{{PLACEHOLDER}}标记替换为检测到的项目值删除条件不满足的章节。 随后以一段完整的 Markdown 代码块给出了生成目标的整体结构从上到下依次为Project Overview项目概览一句话描述取自package.json的 description 或推断。Setup commands安装命令3-5 条要点覆盖 install / dev / build / test / lint。Source Files源文件清单带单行用途说明的扁平目录树再加一张Feature map功能到文件的映射表5-8 行。Where to edit从哪改起以要改 X 该编辑什么的角度给出任务 → 文件映射。Essential Commands核心命令表三列表格 Command | Purpose |When关键在 When 这一决策列。Verification Cycle验证闭环每个代码变更后必须执行的命令链。Before committing提交前检查清单3-4 项。Pre-validate预校验执行与 pre-commit 钩子完全一致的命令。Code Style代码风格2-4 条项目专属规则。Hard Rules硬性规则2-3 条不可协商、违反即被拒的规则。Prohibitions禁令以 Neverdo X 开头的 2-3 条要点。Boundaries边界分 Ask first 与 Never 两个子小节。Global Conventions全局约定5-8 条要点。Definition of Done完成定义4-6 条编号检查项。PR instructionsPR 指令2-3 条要点。以及散布其间的众多条件区块WHO_USES_THIS、E2E_MATRIX、IO_CONTRACT、SUBSYSTEM_RULES、ARCHITECTURE_DECISIONS、INTENT_ROUTING_TABLE、ERROR_TAXONOMY、WRITING_STYLE_GUIDE、GOTCHAS、SSH_TROUBLESHOOTING、VERSIONING_POLICY、RELEASING_SECTION、DOC_IMPORTS、RULE_FILE_LINKS、CODEGRAPH_SECTION 等。值得注意的细节模板顶部有一行兼容性声明引用 agents.md 标准并提示特定规则位于.agents/rules/目录{{RULE_CATEGORIES_LIST}}占位符说明 Full Mode 下规则文件是与主文件配套的正式组成部分。三、常驻区块Always-included sections逐个拆解以下区块在全量模式下默认生成条件满足时才剔除或简化模板对其填充口径有严格规定。3.1{{PROJECT_OVERVIEW}}一句话定义项目One sentence. Package.jsondescriptionor inferred.只写一句话优先取package.json的description字段缺失时根据代码结构推断。目的是让任何代理在进入仓库的第一秒就知道这是什么。3.2{{SETUP_COMMANDS_BULLETS}}安装/开发命令要点3-5 条要点格式固定为- 描述: \命令内容覆盖 install、dev、build、test、lint。[模板填充指南](https://pre-link.gitcode.com/i/365c87fc0ca9f849b46f77183da07ac7) 进一步要求**命令必须以检测到的包管理器为前缀**且其 script key 必须真实存在于package.json 中——不存在的命令行直接省略绝不臆造。3.3{{SOURCE_FILE_LIST}}源文件树 Feature map模板规定输出两样东西扁平目录树每个文件附带一行用途说明Feature map 表5-8 行把常见操作映射到精确文件## Feature map | Feature | Files | |---------|-------| | CLI entry | src/cli.ts | | Core logic | src/add.ts |模板明确强调这对代理比单纯的文件树更有用——因为代理要回答的是我该动哪个文件而不是仓库里有什么。3.4{{WHERE_TO_EDIT}}任务导向的编辑指引与 Feature map 相同但换一种问法要改 X应该编辑什么task → files。模板允许如果 Source Files 小节已经同时包含了树和映射表此处可以更精简。3.5{{ESSENTIAL_COMMANDS}}带 When 决策列的命令表这是全量模板中最具辨识度的设计三列表格 Command | Purpose |When其中When是决策列告诉代理在什么时机运行| pnpm test | Run all tests | Fast iteration | | pnpm test:run | Single-run tests | Before committing | | pnpm typecheck | TypeScript check | Before committing |结合决策矩阵的命令生成规则命令表直接由package.json的scripts键映射而来{pm}前缀规则为 bun 省略run、pnpm 用pnpm、npm 用npm run、yarn 用yarn额外补充test:run、test:coverage、doctor、format、typecheck等行。Monorepo 场景下还要求生成turbo run {cmd}、pnpm --filter {pkg} {cmd}、nx {cmd} {pkg}等变体。3.6{{VERIFICATION_CYCLE_INTRO}}验证闭环的引子模板给出两个备选文案无 E2E 矩阵时After every code change. Do not mark a task complete without passing:有 E2E 矩阵时Run the smallest relevant verification first.决策矩阵 给出的拼装公式为{typecheck} → {lint} → {test} → {doctor}每一步只保留项目确实拥有的工具TypeScript 项目才有tsc --noEmitbun 项目写作bunx tsc --noEmit无 lint 工具就跳过 lint无测试运行器就跳过 test。3.7{{BEFORE_COMMIT_CHECKLIST}}与{{PRE_VALIDATE}}提交前的双重保险提交前清单3-4 项覆盖验证闭环、格式检查、lockfile 校验。预校验命令必须与 pre-commit 钩子实际执行的完全一致。模板给出明确的检测路径从.githooks/pre-commit、lint-staged配置、.husky/pre-commit中检测读取真实钩子文件获取精确命令输出格式为- Run \{{PRE_COMMIT_CMD}} on changed files before committing — this is what CI runs.。其目的是避免代理提交后才发现 CI 的 lint-staged 失败把慢速的 CI 失败前置到本地。3.8{{CODE_STYLE}}只写项目专属规则模板强调 2-4 project-specific rules.No generic advice.。这与模板填充指南 的判定标准一致像 Bun siempre. No npm ni yarn.由bun.lock检测得出这种可验证的约定是合格的而 Use good TypeScript practices、Clean code 这类无法从配置验证的泛泛之谈必须剔除。3.9{{HARD_RULES}}不可协商的铁律2-3 条编号规则Violating rejected违反即被拒。检测线索.env.example存在 → 秘钥规则有tests/→ 测试规则Monorepo → 契约同步规则。3.10{{PROHIBITIONS}}带加粗 Never 的禁令2-3 条**Never** do X要点模板给出了按项目上下文检测的候选清单通用Nevercreate README or markdown docs unless explicitly asked.TypeScript strict 项目Neveruseanytypes oras anyassertions.有发布脚本Neverbump version numbers in feature PRs.有生成产物Neveredit generated files by hand.MonorepoNeverpush directly to main on upstream.3.11{{BOUNDARIES}}Ask first 与 Never 双栏边界两个子小节Ask first先问再做与 Never绝对不做。项目相关检测Monorepo → 跨包重构规则有 ORM → 破坏性数据规则有构建产物 → 生成文件规则。秘钥与破坏性 Git 操作是通用的任何项目都要保留。3.12{{AGENT_DISCLOSURE}}代理署名规则若项目存在CONTRIBUTING.md或 PR 模板则补充代理署名规则- All agent-drafted GitHub content (PR comments, reviews, issues) must include attribution footer. - Never mention or tag individuals unless explicitly authorized. - Drafted-by: footer required on all agent-generated GitHub messages.3.13{{GLOBAL_CONVENTIONS}}与{{DEFINITION_OF_DONE}}收尾两件套全局约定5-8 条要点覆盖包管理器、导入规范、命名、语言、校验方式。完成定义4-6 条编号检查项必须包含 typecheck/lint/tests、新增测试、文档更新、无警告。3.14{{PR_INSTRUCTIONS}}PR 指令与单一目标原则2-3 条要点若项目有 PR 模板则包含Goal (pick one per PR)范围控制模式- Pick ONE goal per PR. Frame the title to reflect it. - Conventional commits: feat:, fix:, refactor:, test:, chore:. - No AI attribution in commits.四、条件区块检测到才生成全量模板的精华在于按检测信号决定区块去留避免生成与项目无关的噪音。以下逐一给出触发条件与内容形态。4.1 面向代理消费方的区块{{WHO_USES_THIS}}CLI/API/SDK 被 AI 代理消费时模板给出了关键论断——This CLIs primary consumers include AI agents (Claude Code, Cursor). Error messages, output format, and flag design directly affect agent success rates. Every error message will be parsed by an AI to decide its next action. 这解释了后续 IO_CONTRACT 与 ERROR_TAXONOMY 的设计动机代理会解析 stderr 来决策下一步动作。{{IO_CONTRACT}}CLI/API 项目严格划分 stdout 与 stderr——stdoutis data — JSON, structured output, machine-readablestderris everything else — progress, warnings, hintsNever mix them. Mixing corrupts pipe chains.混用会破坏管道链。{{ERROR_TAXONOMY}}有结构化错误的 CLI/API 项目失败类型 → 构造函数映射表例如errs.NewValidationError(...).WithParam(--flag)、errs.NewNetworkError(...)、API 错误原样透传不重包。{{WRITING_STYLE_GUIDE}}产出文档或面向 AI 内容的项目写作风格要点——H2/H3 层级结构、2-4 句短段落、直接指令式第二人称语气、主动语态、每段自问是否值得它的 token 成本。4.2 工程流程区块{{READ_THIS_FIRST}}当docs/或doc/下有 3 个以上 Markdown 文件时生成按顺序阅读的文件列表。{{ENVIRONMENT_VARIABLES}}仅当存在占位符形式的.env.example或源码引用如process.env.NAME时生成 Variable | Required | Purpose 三列表3-8 行。模板明确禁止打开.env、.env.local等含秘钥文件禁止把值复制进生成指令——变量名只能来自占位符与源码引用。{{E2E_MATRIX}}项目同时有单元测试与 E2E 测试时生成变更类型 → 测试要求的矩阵| Change | Unit tests | E2E tests | |--------|:----------:|:---------:| | New feature | Required | Required | | Modify behavior | Required | If behavior changes | | Bug fix | Required | If regression risk | | Refactor | Required | Not needed |{{GENERATED_ARTIFACTS_POLICY}}存在dist/、build/、.next/等构建产物目录时——Source-first: edit files insrc/,lib/,app/... never edit it directly生成文件仅在发布 PR 或产物本身即变更时才纳入暂存。{{SUBSYSTEM_RULES}}Monorepo 或存在packages/、apps/、cli/等子目录时为每个子目录生成一个小节如packages/dashboard/→ 禁用原生浏览器对话框、文件命名用 kebab-case。{{ARCHITECTURE_DECISIONS}}1-3 条非显然决策及理由示例包括为何用结构化错误代理解析 stderr 字段决定下一步禁用裸错误字符串为何用 pnpmworkspace 协议仅 pnpm 可解析。{{DOC_UPDATE_CHECKLIST}}存在多个文档面时给出改用户可见功能必须同步更新 ALL的清单help 输出、README 选项表、docs 页面、源码注释。{{INTENT_ROUTING_TABLE}}存在多个入口/工具/技能时用意图 → 入口表把用户目标映射到正确入口。{{GOTCHAS}}存在平台特定问题Windows、NTFS、Docker、沙箱时给出坑位清单如 npx vite buildhangs on NTFS — usenode node_modules/vite/bin/vite.js build、服务启动需 30-60s不要立即判定失败。{{SSH_TROUBLESHOOTING}}仅当 git remote 使用 SSHgitgithub.com时给出sign_and_send_pubkey/Permission denied的处理指引——不要切 HTTPS 或反复重试而是请用户确认 SSH agent 可用且已解锁。{{TASK_GUIDES}}1-3 份可重复操作的逐步指南每份 3-4 步。{{CONTRIBUTION_GUARDRAILS}}存在.github/CONTRIBUTING.md或 PR 模板时——issue-first、AI 代理必须在 PR 描述披露、非维护者的未经请求 PR 可能被直接关闭。{{VERSIONING_POLICY}}存在多个独立版本组件时生成组件 → 版本文件 → 何时升版 三列表如 Skills 任意变更即升版unbumped invisible特性 PR 不升版版本是发布环节的事。{{RELEASING_SECTION}}仅当存在发布/部署脚本时编号步骤。{{DOC_IMPORTS}}已有文档存在时用import引用而非复制内容。模板给出三种粒度import用于代理应常驻上下文的文档约定/模式/风格普通链接用于偶尔需要的文档大文件警告——超过约 300 行约 1500 token时标注 ⚠️ Large file — consider importing only key sections。核心原则Never duplicate content that already exists in project docs.{{RULE_FILE_LINKS}}仅 Full 模式每个生成的规则文件一个链接。{{CODEGRAPH_SECTION}}仅当存在.codegraph/目录时。{{CLAUDE_MD_NOTE}}检测到 Claude Code.claude/目录或根目录CLAUDE.md时额外生成一份极薄的CLAUDE.md——它只是指向 AGENTS.md 的指针可参考 assets/claude.md 的形态核心内容仅See AGENTS.md只有在项目确实使用.claude/rules/、.claude/commands/、.claude/agents/时才追加对应引用否则不加任何空章节。五、填充口径让占位符变成可验证的事实模板本身只定义了结构具体填什么由模板填充指南 与决策矩阵 约束。其核心原则可归纳为可验证优先于通用建议版本号必须精确{{STACK_TABLE}}中每个版本取自package.json禁用 latest 或 X.Y.Z 占位写法。架构图用真实目录名{{ARCHITECTURE_DIAGRAM}}的 ASCII 图必须展示真实连接哪个文件 import 哪个文件禁止出现 Component、Service 之类的无名盒子。数据流用真实函数名{{DATA_FLOW}}的编号步骤必须写detectPlatform()、downloadVideo()这类真实函数而不是 validate input、call API。路由表列全每个路由文件{{ROUTING_TABLE}}覆盖page.tsx、layout.tsx、route.ts、error.tsx、loading.tsx、not-found.tsx、sitemap.ts、robots.ts及 API/动态路由。测试数量要真数{{TEST_COUNT}}统计所有测试文件中的test()/it()调用报告真实数字数不清时报告测试文件数并附测试运行器版本、运行环境node/jsdom、覆盖率工具与目标、是否严格 TDD。提交示例来自真实 git 历史{{COMMIT_EXAMPLES}}读git log --oneline -5用真实文件名或功能名。约定必须可配置验证合格的例子是 Sin librería de validación externa — TypeScript types guards manuales (isDownloadError())不合格的是 Usar buenas prácticas de TypeScript.泛化、不可验证。六、规则文件的选择逻辑检测信号 → 生成/跳过全量模式下AGENTS.md 之外还会在.agents/rules/下生成配套规则文件。决策矩阵的 Rule File Selection 给出了完整的信号 → 文件映射规则文件生成条件architecture.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 中有 vitest/jest/playwright/cypressgit-workflow.md总是生成sdd-workflow.md总是生成以仓库自带的示例输出基准 为例对一套 Bun Next.js 16 Tailwind Vitest Server Actions 的栈最终生成 AGENTS.md85 行 6 个规则文件architecture、frontend-patterns、server-actions、testing、git-workflow、sdd-workflow而backend-patterns.md无 NestJS、styling.mdTailwind 已并入前端规则、forms.md手动受控输入、database.md无 ORM、i18n.md硬编码西班牙语则被跳过并附理由——这正是只生成适用的内容这一硬性规则的落地。检测信号本身在决策矩阵 中有完整的 16 步顺序包管理器lockfile 判定→ 项目类型workspaces判 Monorepo→ 框架 → Monorepo 工具 → 语言tsconfig.jsonstrict→ CSS 方案 → 测试 → 校验库 → ORM → 状态管理 → API 客户端模式 → 表单库 → Auth 库 → i18n 库 → 后端模式 → Lint 与质量工具。七、体量管控与质量红线全量模板末尾定义了后处理限制Post-generation limits300 行软上限生成的 AGENTS.md 超过 300 行时给出警告建议把内容下沉到.agents/rules/或既有项目文档并用import引用500 行硬上限永远不得超过——超出时把内容迁移到规则文件或引用已有文档。这与 SKILL.md 的后处理步骤 完全一致扫描残留的{{、TODO、...并修复零占位符是验收标准验证所有命令存在于package.jsonscripts超过 300 行警告、超过 500 行迁移。此外还有三重安全护栏先读后写、永不读秘钥生成前必须读package.json、非秘钥配置文件与目录结构绝不打开.env、.env.local等含秘钥文件环境变量名只从.env.example占位符与源码引用中推导。默认不执行项目脚本包管理器脚本是仓库控制的 shell 入口点默认只检测并记录候选 format/lint 命令不执行除非用户单独授权且脚本体与调用的工具已审查。先备份再写入目标文件已存在时先复制到.agents/backups/并加时间戳。在质量层面示例输出基准 的 8 项检查可作为自检清单命令精确到包管理器bun dev而非npm run dev验证闭环中的每一条命令都在package.json中存在全局约定与栈匹配架构图使用真实目录数据流点名真实函数路由表完整测试数量真实计数输出中{{、TODO、add here、...零命中。八、在代理生态中的落地路径全量模板产出的 AGENTS.md 是给代理看的项目说明书其设计处处服务于代理的实际工作方式命令带 When 列代理据此决定开发中跑什么、提交前跑什么避免盲目执行全部命令Feature map / Where to edit直接把任务意图映射到文件路径缩短代理的探索路径IO 契约与错误分类保障代理能从 stdout/stderr 结构化地解读程序输出并决策下一步硬规则、禁令与边界用不可协商的语言约束代理行为防止越权写入、乱动版本号、手改生成文件等事故import 与体量上限控制上下文成本让代理的上下文窗口花在刀刃上。模板兼容 agents.md 为每个子包生成轻量副本claude.md 则在检测到 Claude Code 时生成一份指向 AGENTS.md 的薄指针文件——由此形成根级全量 子包轻量 平台指针的三层协作文档体系。结语agents-full.md 全量模板的可贵之处在于它把为 AI 代理写项目文档这件事从玄学变成了可执行的工程流程先按检测信号决定生成什么章节与规则文件的选择逻辑再按填充口径决定写多具体版本号、真实函数名、真实测试数、可验证约定最后按体量红线决定放在哪主文件 300/500 行上限、下沉规则文件、import 复用既有文档。配合 决策矩阵 的 16 步检测顺序与 示例输出基准 的 8 项质量检查任何人都可以复现出与真实工具链完全一致、无占位符、可被代理直接消费的项目级 AGENTS.md。赞分享AI 技能AI 插件人工智能【免费下载链接】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点击查看免费下载相关推荐mootdx 入门指南3 个案例获取通达信行情、K线与财务数据mootdx 入门指南3 个案例获取通达信行情、K线与财务数据 mootdx 是一个通达信数据的 Python 封装库实时行情、日/分钟/分时 K 线、财务金融科技数据分析戴森球计划工厂蓝图库几百张现成产线放进游戏直接造戴森球计划工厂蓝图库几百张现成产线放进游戏直接造 对着空地一个个摆机器、算传送带是《戴森球计划》前期最磨人的环节。FactoryBluePrints 是这数据集为 Server Actions 项目生成后端规则agents-generator 的 server-actions 模板深度解析为 Server Actions 项目生成后端规则agents generator 的 server actions 模板深度解析 导读 本文围绕仓库中 agAI 技能AI 插件人工智能上一篇Flow 不透明类型Opaque Type实战从 opaque_001_basic_nominal 评测任务到金钱模块实现下一篇Cross-Encoder 损失函数完全指南sentence-transformers 排序模型微调实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考