1. 项目概述为AI编程助手制定“家规”如果你和我一样日常开发已经离不开像 Cursor、Windsurf 这类 AI 驱动的 IDE那你肯定也遇到过类似的烦恼每次新建一个项目或者换到另一个项目都得花时间跟 AI 助手“交代”一遍项目背景、技术栈偏好、代码规范。说少了AI 生成的代码可能不符合项目习惯说多了每次手动创建配置文件又太麻烦。这个痛点正是agent-rules-generator这个工具诞生的初衷。简单来说agent-rules-generator是一个交互式的命令行工具它的核心使命就是帮你自动化生成那些给 AI 助手看的“规则手册”。目前主要支持生成两种主流格式给 Cursor AI 用的.agent.md文件以及给 Windsurf IDE 用的.windsurfrules文件。它就像一个贴心的项目管家通过一系列交互式问答摸清你的项目底细是 Web 应用、CLI 工具还是库用了 React 还是 Vue数据库选 PostgreSQL 还是 MongoDB然后为你量身打造一份详尽、结构化的配置说明。这样一来你的 AI 助手从“入职”第一天起就能深刻理解你的项目上下文和团队规范生成更精准、更符合预期的代码。我最初接触这个工具时它还有些“偏科”主要面向 Web 应用。但经过 v1.1.0 版本的重构它已经进化得非常“全能”了。现在支持6 种不同的项目类型包括 Web 应用、CLI 工具、库/包、移动应用、桌面应用和 API/后端服务。最关键的是它采用了条件式提问流当你声明项目是“CLI 工具”时它绝不会多问你一句关于前端框架或数据库选型的问题整个交互过程变得极其高效和精准。对于需要频繁在不同技术栈项目间切换或者团队需要统一 AI 协作规范的开发者来说这个工具能省下大量重复沟通的成本让 AI 真正成为得力的、懂规矩的“结对编程”伙伴。2. 核心设计思路从“一刀切”到“量体裁衣”这个工具的设计演进很好地反映了一个优秀工具是如何从解决具体问题进化到提供通用解决方案的。早期的版本v1.1.0之前存在一个明显的局限性它本质上是一个“React 中心化”的 Web 应用配置生成器。无论你是什么项目它都会按部就班地问你前端框架、后端框架、数据库这对于开发 CLI 工具或纯后端库的开发者来说一半以上的问题都是无关噪音。2.1 项目类型驱动的架构重构为了解决这个问题项目进行了大规模的重构核心思路是引入“项目类型”作为整个配置流程的驱动引擎。这不仅仅是前端多几个选项那么简单而是从数据模型到交互逻辑的全面改造。首先是定义清晰的项目类型元数据。工具内部维护了一个项目类型的“知识库”对于每一种类型如web-app,cli-tool,library都明确定义了核心特征这类项目的典型目标、产出物和生命周期是怎样的技术栈范围哪些技术问题是相关的哪些是绝对不该问的例如cli-tool类型会关心commander.js、yargs这类 CLI 框架以及配置文件的格式JSON/YAML但完全不会涉及react或vue。默认规则模板不同类型的项目其.agent.md文件的侧重点不同。Web 应用可能更强调组件结构、状态管理和 API 集成而库项目则更关注 API 设计、导出格式、版本管理和测试覆盖率。其次实现了动态的问题编排引擎。这是工具变得“聪明”的关键。整个交互流程不再是静态的问卷而是一个动态决策树。当你选择了“CLI 工具”后引擎会加载为该类型预设的问题集同时过滤掉所有标记为“不相关”的模块。背后的project_types.js和project_configurator.js模块协同工作确保了问题流的上下文连贯性和无冗余。实操心得动态配置的陷阱实现这种动态流时一个常见的坑是状态管理。比如用户中途想返回修改项目类型这时已经收集的部分答案可能会与新类型产生冲突例如之前为 Web 应用选择的 React在切换到 CLI 工具后变得无效。agent-rules-generator的处理方式是在切换关键路径如项目类型时会提示用户之前的某些配置可能需要重置或者提供智能的默认值迁移。在实际开发类似工具时一定要设计好配置数据的版本和兼容性以及清晰的回退和重置策略。2.2 模块化与关注点分离另一个值得称道的设计是工具彻底的模块化。将近 800 行的单体 CLI 代码被拆分为 13 个职责清晰的独立模块存放在lib/目录下。这种架构带来了几个实实在在的好处可维护性每个模块专注于一个单一任务如recipe_manager.js只管配方的选择和应用windsurf_manager.js专门处理 Windsurf 的集成逻辑。代码行数被严格控制多数模块在 300 行以内阅读和修改起来非常轻松。可测试性独立的模块意味着可以独立测试。项目包含了 13 个测试文件共计 181 个测试用例对每个核心功能点都进行了覆盖。例如recipe_creator.test.js专门测试配方创建流程的 34 个场景windsurf_customization_flow.test.js则确保了 Windsurf 定制化流程的 9 个关键交互不出错。这种细粒度的测试保证了重构和新增功能时的信心。可扩展性如果你想为工具新增一个支持平台比如另一个新兴的 AI IDE理论上你只需要参照windsurf_manager.js的模式创建一个新的xxx_manager.js模块并在主协调器agent_rules_cli.js中注册相应的调用入口即可不会影响到其他已有功能。这种架构模式非常值得在构建复杂 CLI 工具时借鉴。它通过依赖注入将inquirer,chalk, 配置对象等共享资源传递给模块来降低耦合使得每个模块都像是一个可插拔的零件。3. 核心功能解析与实操要点3.1 交互式 CLI不只是问答更是引导运行agent-rules-generator命令后你会进入一个色彩分明、步骤清晰的命令行交互界面。这个过程远不止是收集信息它更像是一个有经验的同事在帮你梳理项目规范。流程拆解项目概览收集首先会询问项目名称、描述、版本等基础信息。这里有个小技巧工具会尝试从当前目录的package.json中自动读取这些信息如果存在会提供给你作为默认值非常贴心。项目类型选择这是整个流程的“决策点”。你会看到 6 个选项每个都有简明的图标和描述。选择后后续的所有问题都会基于这个选择进行筛选和定制。技术栈深度定制这是工具最强大的部分。以选择“Web 应用程序”为例前端框架它会列出 React, Vue, Angular, Svelte 等主流选项并可能根据你的选择追问状态管理库如 Redux, Pinia、构建工具Vite, Webpack等子选项。后端框架同样选择 Node.js (Express/Fastify)、Python (Django/FastAPI)、Java (Spring Boot) 等会触发不同的后续问题。数据库关系型、文档型或是内存数据库不同的选择会影响生成的规则中对数据模型、ORM 使用约定的描述。所有这些技术选项都关联着预定义的“最佳实践指南”。例如选择 React TypeScript生成的.agent.md中会自动包含关于使用函数组件、interface定义 Props、避免any类型等具体规则。规则与工作流定义接下来会询问代码风格缩进、引号、Git 工作流Git Flow, GitHub Flow、是否使用 CI/CD 等。这些答案会直接转化为配置文件中可执行的指令或强烈建议。注意事项预设与灵活的平衡工具提供了丰富的预设但绝不是死板的。在几乎所有步骤你都有“自定义”或“跳过”的选项。比如技术栈列表里没有你用的边缘框架你可以手动输入。对于代码规范你可以选择直接采用PrettierESLint的通用配置也可以详细定义每一条规则。这种“引导为主自定义为辅”的设计既降低了新手的心智负担又满足了老手的定制化需求。3.2 配方系统站在巨人的肩膀上“配方”Recipe是agent-rules-generator的一个杀手级功能。你可以把它理解为一套针对特定技术栈如 “React TypeScript Vite Tailwind CSS”的、经过优化的规则模板合集。配方的工作机制远程仓库集成工具内置了从远程 GitHub 仓库ubuntupunk/agent-rules-recipes获取配方列表的能力。这意味着社区贡献的新配方比如针对 Next.js 15 或 SvelteKit 2.0 的可以随时被所有用户发现和使用工具本身无需频繁更新版本。交互式应用在 CLI 流程中你可以选择“从配方开始”然后浏览或搜索社区配方。选中一个配方后工具会加载该配方的预定义技术栈和规则你只需要确认或微调一些项目特定的信息如项目名就能瞬间生成一个高度成熟的配置文件。本地创建与管理你也可以通过交互式向导创建自己的配方。这个过程同样智能它会引导你输入配方名称、描述、分类前端、后端、全栈等然后通过一系列问题收集技术栈并最终生成一个结构化的 YAML 或 JSON 文件。你可以将其提交到远程仓库贡献给社区也可以保存在本地供团队内部复用。配方文件解析一个典型的配方 YAML 文件结构如下name: React TypeScript Vite 全栈启动器 description: 适用于现代 React 全栈应用的最佳实践配置包含前端、Node.js 后端及 PostgreSQL。 category: web-app author: 社区贡献者 version: 1.0.0 techStack: frontend: [React, TypeScript, Vite, Tailwind CSS] backend: [Node.js, Express, TypeScript] database: [PostgreSQL, Prisma] rules: codingStandards: - 使用函数组件和 React Hooks。 - 所有组件 Props 必须用 TypeScript interface 明确定义。 - 使用 ES6 语法和 async/await 处理异步。 projectStructure: - src/ 目录下按功能模块划分 (features/)。 - 共享工具函数放在 src/lib/。 workflow: - 使用 GitHub Actions 进行 CI运行 lint、type-check 和测试。这个结构化的配方确保了生成的规则文件既全面又具体。3.3 多平台输出适配工具的核心产出是配置文件但它需要为不同的“消费者”AI 平台生成不同格式的“菜单”。.agent.md(For Cursor AI)这是一个标准的 Markdown 文件。它的优势是可读性极强不仅 AI 能理解开发者也能直接阅读和维护。内容通常包括项目简介、技术栈详情、目录结构说明、代码规范命名、注释、样式、Git 提交规范、测试策略、部署指南等。它相当于项目的“百科全书式”上下文。.windsurfrules(For Windsurf)这是 Windsurf IDE 特有的配置文件格式。它更侧重于 IDE 集成层面的指令比如代码生成时的偏好优先使用箭头函数还是函数声明、自动导入的规则、对某些 API 的禁用或提醒等。格式可能更接近 JSON 或某种 DSL内容上会更精炼、更具操作性。Gemini CLI 集成这是一个很巧妙的“桥接”功能。Gemini CLI 本身可能不直接读取.agent.md但工具可以生成或修改 Gemini CLI 的配置文件~/.gemini/settings.json或项目内的.gemini/settings.json将其上下文文件context file指向刚刚生成的.agent.md。这样当你在这个项目目录下使用 Gemini CLI 时它就能自动加载项目的完整上下文实现了跨工具的统一规则管理。实操心得文件命名与位置的约定为了让 AI 助手能自动识别这些规则文件遵守命名和位置约定至关重要。.agent.md和.windsurfrules通常必须放在项目根目录。有些工具可能会在子目录中查找但根目录是最通用、最保险的做法。对于团队项目应该将这些文件纳入版本控制如 Git这样任何克隆项目的新成员其 AI 助手都能立即获得正确的配置。4. 从安装到生成完整实操流程4.1 环境准备与安装工具基于 Node.js因此你需要先确保系统已安装 Node.js版本 14.0.0。对于开发者推荐使用 Bun 以获得更快的依赖安装和测试速度但这不是必须的。安装方式选择全局安装推荐给大多数用户这是最简单的方式安装后可以在任何目录下直接使用agent-rules-generator命令。# 使用 npm npm install -g agent-rules-generator # 或使用 Bun速度更快 bun add -g agent-rules-generator安装完成后可以通过agent-rules-generator或简写的generate-agent-rules命令启动工具。从源码运行适合贡献者或尝鲜git clone https://github.com/ubuntupunk/agent-rules-generator.git cd agent-rules-generator bun install # 或 npm install node index.js # 直接运行源码4.2 一步步生成你的第一个规则文件假设我们要为一个新的“个人博客后端 API”项目生成规则技术栈是 Node.js Express TypeScript PostgreSQL。启动工具在项目根目录下打开终端运行agent-rules-generator。欢迎与初始化你会看到一个格式友好的欢迎界面然后工具会检查当前目录尝试读取已有的package.json来预填信息。选择项目类型? 请选择您的项目类型: (使用方向键选择) ❯ Web 应用程序 CLI 工具 库/包 移动应用程序 桌面应用程序 API/后端服务这里我们选择“API/后端服务”。这个选择至关重要它会立刻过滤掉所有前端相关的问题。填写项目基础信息输入项目名称如my-blog-api、描述、版本号等。如果目录下已有package.json这些字段会自动填充。配置技术栈后端框架从列表中选择Express。随后可能会问你是否使用TypeScript选择“是”。数据库选择PostgreSQL。工具可能会进一步询问 ORM/查询构建器的偏好例如Prisma、TypeORM或原生 SQL。其他服务可能会问及缓存Redis、消息队列、API 文档工具Swagger/OpenAPI等根据实际情况选择。定义开发规范代码风格可以选择已有的风格指南如 Airbnb JavaScript Style Guide或自定义缩进、分号等规则。Git 工作流选择分支策略如main/develop的 Git Flow或基于main的 GitHub Flow。测试框架选择Jest或MochaChai。CI/CD是否设置 GitHub Actions 或 GitLab CI 的流水线。选择输出格式? 请选择要生成的规则文件: (可多选按空格键选择/取消按回车键确认) ❯ ◉ .agent.md (用于 Cursor AI) ◉ .windsurfrules (用于 Windsurf) ◯ 配置 Gemini CLI 以使用 .agent.md可以全选工具会一次性生成所有需要的文件。生成与预览工具会根据你的所有回答渲染模板生成文件。在最终写入前通常会提供一个预览机会让你确认内容是否符合预期。文件生成确认后工具会在当前目录创建.agent.md和.windsurfrules文件。如果选择了配置 Gemini CLI它还会创建或更新.gemini/settings.json文件。至此你的项目就有了专属的 AI 助手“说明书”。下次你或你的队友在这个项目中使用 Cursor 或 Windsurf 时AI 就能基于这些规则提供高度上下文相关的协助了。4.3 使用配方加速启动如果你知道你的技术栈恰好有一个社区配方过程会更快捷启动工具后在主菜单中选择“从配方开始”或类似选项。工具会从远程仓库拉取配方列表并以可搜索的方式展示。你可以搜索 “Express TypeScript PostgreSQL”。选择匹配的配方工具会加载其中预定义的所有技术栈和规则。你只需要补充项目名称等个性化信息即可瞬间生成全套配置。这非常适合快速启动一个符合主流最佳实践的新项目。5. 常见问题与排查技巧实录在实际使用和参与贡献的过程中我遇到并总结了一些典型问题和解决方法。5.1 安装与运行问题问题1全局安装后命令未找到 (command not found: agent-rules-generator)原因这通常是因为 Node.js 的全局安装目录 (npm或bun的bin目录) 没有被添加到系统的PATH环境变量中。排查与解决首先确认安装是否成功npm list -g agent-rules-generator或bun pm ls -g | grep agent-rules-generator。查找全局 bin 目录npm:npm config get prefix然后查看prefix/bin/目录。Bun:bun pm bin -g直接输出路径。将上述路径添加到你的 shell 配置文件如~/.bashrc,~/.zshrc的PATH变量中例如export PATH$PATH:$(bun pm bin -g)。重启终端或运行source ~/.zshrc。问题2运行时报错提示某些模块找不到如Cannot find module chalk原因依赖没有正确安装可能发生在从源码运行的情况下。解决确保在项目根目录下重新安装依赖bun install或npm install。如果问题依旧尝试删除node_modules文件夹和bun.lockb/package-lock.json文件后重新安装。5.2 配方系统相关问题3无法下载或列表远程配方原因网络问题或者远程配方仓库 (ubuntupunk/agent-rules-recipes) 的地址有变动。排查检查网络连接。运行工具时添加--verbose或-v标志如果支持查看详细的网络请求日志。工具可能会在本地缓存配方列表检查缓存是否过期。缓存文件通常位于~/.cache/或项目内的windsurf_recipes/目录下尝试删除缓存文件后重试。临时方案如果只是需要某个特定配方可以手动从 GitHub 仓库下载对应的.yaml文件放在本地目录然后使用工具内的“从本地文件加载配方”功能如果提供。问题4自定义配方验证失败原因在创建或提交配方时工具的验证脚本 (scripts/validate_recipes.js) 会对配方文件的格式、必填字段、技术栈有效性等进行检查。解决使用验证脚本自查node scripts/validate_recipes.js --file your_recipe.yaml。查看具体的错误信息。常见错误包括缺少name或category字段、techStack中使用了工具不支持的技术名称、YAML 格式缩进错误等。可以使用--fix参数尝试自动修复一些格式问题node scripts/validate_recipes.js --file your_recipe.yaml --fix。参考examples/目录下的示例配方文件确保结构一致。5.3 生成文件与 AI 助手集成问题5生成的.agent.md文件 AI 助手似乎没读取排查步骤确认文件位置与名称确保文件名为.agent.md注意开头的点并且位于项目的根目录下。这是 Cursor 等工具默认查找的位置。检查文件内容打开.agent.md确认其内容是可读的 Markdown并且包含了项目相关的具体信息。一个过于空泛或格式错误的文件可能被 AI 忽略。重启 AI 助手/IDE有时 AI 助手需要重启或重新加载项目上下文才能识别新添加的规则文件。查阅 AI 助手文档确认你使用的 AI 助手Cursor, Windsurf是否支持以及如何支持.agent.md文件。不同工具的实现细节可能有差异。问题6.windsurfrules文件在 Windsurf 中不生效排查步骤Windsurf 版本确保你使用的 Windsurf 版本支持.windsurfrules文件。该功能可能需要较新的版本。文件语法.windsurfrules可能有其特定的语法如 JSON、YAML 或自定义 DSL。使用工具生成的文件通常是符合规范的但可以对比官方文档或示例检查。Windsurf 设置有些 IDE 可能需要手动启用或指定规则文件路径。检查 Windsurf 的设置中是否有关于“项目规则”或“AI 配置”的选项。查看日志如果 Windsurf 有开发者控制台或日志输出查看加载项目时是否有关于解析.windsurfrules的错误信息。5.4 参与开发与调试问题7如何为新的项目类型或技术栈添加支持这是贡献的核心。步骤大致如下修改lib/project_types.js在PROJECT_TYPES对象中定义新的类型明确其label,value,description以及关键的relevantQuestions数组列出所有需要问的问题模块 ID。更新问题流逻辑在lib/project_configurator.js中确保新的类型能正确触发对应的问题模块。可能需要创建新的问题模块或扩展现有模块。添加技术栈指南在lib/generator_lib.js或相关的模板文件中为新技术栈添加对应的规则片段和最佳实践描述。更新配方系统如果新类型有通用的技术栈组合可以在recipes/目录下创建对应的示例配方。编写测试在test/目录下为新的类型和功能添加测试用例确保覆盖率。运行测试执行bun test确保所有测试通过没有破坏现有功能。问题8运行测试时某个特定测试套件失败策略使用bun test test/your_failing_suite.test.js单独运行失败的套件查看详细错误堆栈。常见原因环境差异测试可能依赖特定的环境变量或文件路径。检查测试文件开头的设置。网络依赖涉及远程配方下载的测试 (recipe_download.test.js) 可能因网络超时而失败。考虑是否需要在测试中模拟网络请求。副作用某个测试没有正确清理状态影响了后续测试。确保测试是独立的使用beforeEach和afterEach钩子进行设置和清理。这个工具的价值在于它将一个看似琐碎但实际影响开发效率的任务——为 AI 助手提供项目上下文——变得标准化、自动化和可共享。通过将社区的最佳实践沉淀为“配方”它让每个开发者都能快速为新项目建立高质量的 AI 协作规范。无论是个人项目快速启动还是团队寻求统一的代码生成标准agent-rules-generator都提供了一个非常务实且强大的解决方案。它的模块化设计和活跃的社区贡献模式也让我相信它会随着 AI 编程生态的发展而持续进化。