1. 项目概述AI项目规则生成器的核心价值如果你和我一样每天都要和Cursor、Claude Code、Antigravity IDE这些AI编程助手打交道那你肯定也遇到过这个痛点每次开一个新项目都得花大量时间去配置.cursorrules、AGENTS.md这些指导文件。手动写吧费时费力还容易遗漏关键规则不写吧AI助手就像个无头苍蝇生成的代码风格不一甚至可能引入安全漏洞。更头疼的是现在市面上各种AI技能库Skill Sources层出不穷格式五花八门有CATALOG.md索引的有按文件夹组织的还有直接一个README列清单的。手动从这些海量技能里挑出适合当前项目的无异于大海捞针。naravid19/ai-project-rules-generator这个项目就是来解决这个问题的。它本质上是一个智能的、自动化的项目规则与AI技能发现引擎。你只需要在项目根目录运行它它就能自动分析你的项目技术栈然后像一位经验丰富的架构师一样从你配置的多个技能源中精准找出最相关的AI技能最后生成一份量身定制的、高质量的.cursorrules和AGENTS.md文件。整个过程完全自动化你不再需要手动浏览、筛选技能极大地提升了开发效率和AI协作的规范性。这个工具的核心创新在于其基于格式的自动技能发现Format-Based Skill Discovery机制。它不关心技能库具体叫什么名字而是通过识别技能源的组织结构格式CATALOG、FOLDER、SEARCH_ENGINE、README、WORKFLOW来适配不同的搜索策略。这意味着无论是官方的anthropic-skills还是社区维护的awesome-claude-skills甚至是专注于科学计算的claude-scientific-skills只要格式对得上它都能无缝接入并为你所用。2. 核心设计思路与工作流拆解2.1 六阶段结构化工作流从分析到验证这个生成器的核心是一个精心设计的六阶段工作流Stage 0-5。这个结构不是随意划分的而是为了确保生成规则的完整性和高质量。每个阶段都有明确的目标和时间预估整个流程大约在30到60分钟内完成对于动辄需要数小时手动配置来说效率提升是巨大的。Stage 0: 用户偏好设置2-5分钟这是可选的起点但强烈建议进行配置。你可以通过交互式的python scripts/wizard.py向导或者直接编辑.rulesrc.yaml配置文件来设定生成规则。这里的关键决策包括目标平台是只给Cursor用还是需要同时支持Claude、Gemini、Copilot等9个平台工具会根据你的选择生成对应平台兼容的指令文件。严格等级选择balanced平衡、strict严格或relaxed宽松。这直接影响生成规则的细致程度和强制性。在金融或安全敏感项目中我通常会选择strict。技能源路径这是核心配置之一。你可以指定多个技能根目录工具会按顺序扫描。例如你可以把公司共享的技能库路径放在前面个人项目本地的.agent/放在后面实现优先使用团队规范技能。Stage 1: 项目分析10-15分钟工具会像侦探一样自主扫描你的项目目录。它不只是看文件扩展名而是通过分析package.json、pyproject.toml、go.mod、项目结构、依赖关系等来准确判断你的技术栈是React前端还是FastAPI后端、架构模式是否是微服务以及可能用到的AI工具。这个阶段的分析结果将直接决定后续搜索技能时使用的17个关键词类别。Stage 2: 技能发现5-10分钟这是整个工具的“智能”所在。基于Stage 1的分析结果工具会使用提炼出的关键词如apifastapitestingpytest去扫描你在Stage 0配置的所有技能源。它根据每个技能源的格式采取不同的搜索策略对于CATALOG格式如antigravity-awesome-skills它会搜索CATALOG.md表格中的行。对于FOLDER格式如awesome-claude-skills它会遍历文件夹读取每个技能目录下的SKILL.md、AGENTS.md等文件。对于SEARCH_ENGINE格式它会调用内置的搜索工具。 搜索到的技能会进行相关性排序确保最匹配的技能排在前面。这里有个实用技巧如果你的技能库很大比如那个巨大的CATALOG可以使用--limit参数限制返回结果数量让AI助手后续的总结和集成更聚焦。Stage 3: 生成.cursorrules10-20分钟利用前两个阶段的成果工具开始构建项目的“宪法”。.cursorrules文件会包含项目身份清晰定义项目类型、主要语言和框架。关键规则按严重性等级 关键 / 重要 / 建议组织这是确保代码质量的核心。代码异味与最佳实践用对比表格的形式明确指出项目中要避免的坏味道和应该采用的好模式。渐进式披露复杂的规则会分层级组织先给出核心要求再在子章节展开细节避免信息过载。Stage 4: 生成AGENTS.md10-15分钟这个文件是写给AI助手看的“工作手册”。它会列出已发现的可用技能告诉AI助手在这个项目里可以调用哪些现成的“外挂”。说明如何查找更多技能提供一个清晰的指南说明如果遇到新问题AI该如何自己去技能库里搜索例如“如果你需要处理数据库迁移可以去CATALOG里搜索migration或alembic关键词”。提供项目特定的提示词基于项目分析给出一些针对性的上下文和提示。Stage 5: 验证与统计5-10分钟生成不是终点质量把关更重要。工具会运行验证脚本validate-output.ps1或.sh对生成的文件进行启发式评分满分50分默认38分通过。评分维度包括完整性、准确性、特异性、可扫描性和一致性。同时它会输出一份生成统计面板告诉你扫描了多少技能、生成了多少行规则、质量得分如何让你对结果心中有数。2.2 多平台支持与格式兼容性设计这个工具的另一个强大之处在于它的普适性。它不是为了某一个特定的AI IDE设计的而是通过抽象层支持了主流的9个AI编程平台。其设计哲学是一次分析多处生成。目标平台输出文件设计考量Cursor.cursorrules或.cursor/rules/*.mdcCursor的规则系统成熟支持多文件因此生成结构化的Markdown。Claude CodeCLAUDE.md.claude/skills/Claude Code通常使用一个主指令文件并可能支持技能文件夹因此生成组合。Antigravity IDE.agent/skills/*/SKILL.md.agent/workflows/Antigravity明确区分技能和工作流因此按它的目录结构生成。GitHub Copilot.github/copilot-instructions.md.github/prompts/Copilot的指令通常放在.github目录下遵循其社区约定。其他平台 (Gemini, Codex等)AGENTS.md对于没有明确规范的其他平台生成一个通用的AGENTS.md作为总指导文件。这种设计确保了无论你的团队混用哪种工具生成的规则都能被正确理解和应用。在实际操作中我通常会在.rulesrc.yaml里配置target_platforms: [Cursor, Claude Code]这样就能同时得到两个平台的定制化文件非常方便。3. 从零开始安装、配置与实战演练3.1 环境准备与快速安装开始之前你需要确保两样东西一个支持工作流或技能的AI助手比如Cursor以及至少一个AI技能源。技能源就像是一个个的工具箱里面装满了处理特定任务的预制指令。第一步获取技能源如果你还没有技能源最快的方法是使用项目提供的快速安装脚本它会帮你克隆一些推荐的集合。我个人习惯先建立一个共享的技能根目录方便所有项目复用。# Linux/macOS: 建立一个共享技能库并安装所有推荐的技能源 mkdir -p ~/shared-ai-skills/.agent cd ~/shared-ai-skills curl -sL https://raw.githubusercontent.com/naravid19/ai-project-rules-generator/main/setup.sh | bash -s -- --skill-source all --skill-root .# Windows (PowerShell): 同样建立共享库 New-Item -ItemType Directory -Force -Path C:\Users\$env:USERNAME\Documents\AI-Skills\.agent Set-Location C:\Users\$env:USERNAME\Documents\AI-Skills irm https://raw.githubusercontent.com/naravid19/ai-project-rules-generator/main/setup.ps1 | iex -SkillSource all -SkillRoot .注意--skill-source all会安装多个大型技能库可能需要一些时间和磁盘空间。如果你的项目领域明确比如是科研项目可以使用--skill-source scientific只安装科学计算相关的技能包这样发现过程会更精准、快速。第二步安装规则生成器工作流接下来在你的项目目录中安装生成器本身。它本质上是一个Markdown格式的工作流文件。# 进入你的项目目录 cd /path/to/your/project # 创建工作流目录并下载 mkdir -p .agent/workflows curl -o .agent/workflows/create-project-rules.md https://raw.githubusercontent.com/naravid19/ai-project-rules-generator/main/workflows/create-project-rules.md现在你的项目结构应该类似这样your-project/ ├── .agent/ │ └── workflows/ │ └── create-project-rules.md # 刚下载的生成器工作流 ├── src/ ├── package.json (或 pyproject.toml 等) └── ... (其他项目文件)而你的共享技能库在另一个位置比如~/shared-ai-skills/.agent/里面包含了克隆下来的各种技能包。3.2 深度配置解析.rulesrc.yaml 的学问虽然可以直接运行工作流但花几分钟配置.rulesrc.yaml能让结果质量提升一个档次。这个配置文件是控制生成行为的“总开关”。我们来剖析一个我常用的高级配置# .rulesrc.yaml target_platforms: - Cursor - Claude Code # 注释掉不需要的平台以加快生成速度 # - Antigravity IDE # - GitHub Copilot severity_level: strict # 对于生产项目我倾向于严格级别 # 技能源配置关键顺序决定优先级 skill_sources: - path: C:/Users/MyUser/Documents/AI-Skills/.agent # 1. 先搜共享库团队规范 - path: .agent # 2. 再搜项目本地库项目特定技能 # 自定义关键词补充自动分析可能遗漏的领域 custom_keywords: - graphql # 如果项目用了GraphQL但依赖分析没识别 - websocket - rate-limiting output_language: en # 输出语言支持中文‘zh’ template_style: progressive # 渐进式披露对新手AI助手更友好 quality_threshold: 40 # 我将通过标准提高到40/50 preview_mode: true # 生成前先预览确认无误再写入 existing_files: merge # 如果已有规则文件尝试合并而非覆盖配置要点与避坑指南skill_sources的顺序至关重要工具按列表顺序扫描。把共享的、包含团队通用规范的技能库路径放在前面这样发现的技能会优先使用团队标准。项目本地的.agent放在后面用于覆盖或补充项目特有的技能。custom_keywords的妙用自动分析不是万能的。如果你用了比较新的或小众的技术比如trpcsupabase或者有一些特殊的架构关注点比如event-sourcing一定要在这里加上。这能确保技能发现环节不会遗漏相关领域。preview_mode: true这是一个安全网。开启后工具会在真正写入文件前在终端或AI对话中展示即将生成的文件结构和主要内容。你可以检查技能发现是否准确、规则是否合理确认无误后再执行写入操作。理解existing_files策略ask每次遇到已存在文件都询问最安全。overwrite直接覆盖适用于全新项目或决心重构。merge尝试合并新旧内容。注意合并逻辑是启发式的对于复杂的规则文件合并后可能需要人工检查。skip跳过已存在的文件只生成新的。3.3 完整实战为一个FastAPI后端项目生成规则假设我们有一个名为taskflow-api的FastAPI后端项目现在来为它生成规则。步骤1项目初始化与配置cd /path/to/taskflow-api # 创建基础项目结构假设已存在 # 配置.rulesrc.yaml cat .rulesrc.yaml EOF target_platforms: - Cursor - Claude Code severity_level: balanced skill_sources: - path: ~/shared-ai-skills/.agent - path: .agent custom_keywords: - fastapi - sqlmodel - alembic - pytest - docker output_language: en preview_mode: true EOF步骤2运行工作流在Cursor或Claude Code中打开项目然后执行工作流命令/create-project-rules或者直接对AI助手说“请为这个FastAPI项目创建专业的项目规则。”步骤3交互与监控工作流启动后它会进入Stage 0如果没配置.rulesrc.yaml则会交互式提问。之后你会在AI助手的回复中看到它逐步推进分析阶段它会列出检测到的技术栈比如“Python 3.11 FastAPI SQLModel Alembic Pytest”。检查一下是否准确。技能发现阶段你会看到它开始扫描你配置的技能源并输出类似这样的日志[INFO] Scanning skill source: ~/shared-ai-skills/.agent (Format: CATALOG) [INFO] Found skill: FastAPI Best Practices (Relevance: High) [INFO] Found skill: Pytest with Async Fixtures (Relevance: High) [INFO] Found skill: SQLModel CRUD Patterns (Relevance: Medium)预览阶段如果开启工具会展示生成的.cursorrules大纲和将要集成的技能列表。这时你可以仔细审查比如发现它漏掉了“JWT认证”相关的技能你可以中断流程在custom_keywords里加上jwt、authentication然后重新运行。步骤4验收生成结果完成后你的项目根目录下会新增或更新两个文件.cursorrules和AGENTS.md或CLAUDE.md等取决于配置。打开.cursorrules你应该能看到高度定制化的内容例如在**Critical Rules ()**部分会有针对FastAPI项目的硬性规定比如“必须使用Pydantic进行输入验证”、“禁止将数据库会话对象全局传递”。在Code Smells表格里会列出本项目常见的反模式如“在路径操作函数中直接进行数据库查询”对应“应使用依赖注入的Service层”。规则中会引用在技能发现阶段找到的具体技能比如“关于异步测试参考已集成的‘Pytest with Async Fixtures’技能”。而AGENTS.md则会像一个导航手册告诉AI助手“本项目已集成关于FastAPI、SQLModel和Pytest的技能如果你需要处理数据库迁移可以查阅‘Alembic Migration Workflow’技能。”步骤5运行验证最后运行验证脚本确保生成的文件质量达标。# 在项目根目录 ./scripts/validate-output.sh # 或者指定更高的阈值 ./scripts/validate-output.sh --threshold 42如果验证通过你就可以放心地让AI助手基于这些新规则来协助你开发了。你会发现AI生成的代码更符合项目规范提出的建议也更精准因为它“懂”了这个项目的上下文和可用的工具集。4. 高级技巧与疑难问题排查4.1 技能发现机制深度解析与调优技能发现是工具最核心也最复杂的部分。理解其内部机制能帮你更好地配置和诊断问题。1. 格式探测的优先级与逻辑工具按以下顺序判断一个技能源目录的格式CATALOG如果目录下存在CATALOG.md文件并且该文件包含技能表格通常有| Name | Description |这样的Markdown表格则判定为CATALOG格式。这是效率最高的格式因为搜索是在结构化的表格中进行的。FOLDER如果目录下存在直接子文件夹且这些文件夹中包含SKILL.md、AGENTS.md或CLAUDE.md等技能定义文件则判定为FOLDER格式。工具会为每个这样的文件夹创建一个“技能实体”。SEARCH_ENGINE如果目录下存在search.py或类似的搜索工具脚本则判定为该格式工具会调用这个脚本进行搜索。README如果目录下存在README.md且内容包含类似技能分类列表的结构则通过解析README来发现技能。WORKFLOW如果根目录存在CLAUDE.md或AGENTS.md并且可能包含一些隐藏的集成配置如.claude-plugin但没有明显的技能子文件夹树则判定为一个工作流包。2. 如何诊断技能发现失败如果你发现生成的规则里没有包含你期望的技能可以按以下步骤排查运行发现脚本手动测试这是最直接的调试方法。# 1. 首先检查格式识别是否正确 python scripts/discover-skills.py --agent-dir ~/shared-ai-skills/.agent --format # 输出会显示每个子目录被识别为什么格式。检查你的技能库是否被正确识别。 # 2. 用你项目的关键词进行搜索测试 python scripts/discover-skills.py --agent-dir ~/shared-ai-skills/.agent --keywords fastapi sqlmodel pytest --limit 20检查技能源结构确认你的技能库符合上述格式之一。一个常见的错误是从GitHub克隆的仓库可能带有一层额外的父文件夹例如awesome-claude-skills-main你需要确保--agent-dir指向的是包含实际技能文件夹的那一层。验证单个技能能力提取如果发现脚本找到了技能但生成规则时没引用其内容可以提取单个技能看看。python scripts/extract-capabilities.py ~/shared-ai-skills/.agent/awesome-claude-skills/fastapi-best-practices这个命令会输出该技能目录下的主要能力描述检查SKILL.md等文件是否可读、格式是否正确。3. 性能优化技巧使用--limit参数当扫描大型CATALOG源如antigravity-awesome-skills时一次搜索可能返回上百条结果这会影响后续处理速度。在运行工作流时如果AI助手提示发现技能过多你可以在交互中指示它“使用--limit 25进行搜索”或者在.rulesrc.yaml的custom_keywords部分通过注释暗示更具体的关键词从而让发现阶段更聚焦。分层配置技能源不要把所有技能库都混在一个目录里。可以建立general/通用技能、frontend/、backend/、scientific/科学计算等子目录。然后在.rulesrc.yaml中根据项目类型只配置相关的技能源路径这样可以大幅减少不必要的扫描。4.2 处理混合技能源与冲突解决在实际使用中你可能会从多个来源获取技能比如同时使用了官方的anthropic-skills和社区的awesome-claude-skills。这两个源里可能有同名或功能相似的技能比如都有“Code Review”技能。工具的冲突解决策略是优先顺序First-Win。 在skill_sources列表里排在前面的路径中的技能会优先被采用。后面路径中同名的技能会被忽略。这个设计是为了保证一致性。因此你应该把最权威、最符合团队标准的技能库放在列表最前面。例如你的配置是skill_sources: - path: /company/standard-skills # 公司规范技能库 - path: ~/personal/claude-skills # 个人收集的技能库 - path: .agent # 项目临时技能那么即使三个地方都有“Python Debugging”技能也只会采用/company/standard-skills里的版本。4.3 自定义模板与规则扩展虽然工具能自动生成但每个团队都有自己独特的编码规范和习惯。项目内置的10个模板React、FastAPI、Flutter等是很好的起点但你可能需要在此基础上进行定制。方法一修改生成后的文件最直接的方法是在工具生成.cursorrules和AGENTS.md后手动添加一些团队特有的规则。例如在.cursorrules的“Critical Rules”部分加上## 团队特定规则 - **所有REST API响应必须包裹在{“code”: 0 “data”: ... “msg”: “”}的标准格式中。** - **错误码定义必须引用 common/error_codes.py 文件。**下次生成时使用existing_files: merge配置工具会尝试保留你的这些自定义部分。但要注意自动合并可能不完美需要人工复核。方法二创建团队基础模板更系统的方法是基于templates/目录下的某个模板创建你团队的基础版本。复制templates/python-fastapi/目录到你的内部知识库。修改其中的.cursorrules和AGENTS.md文件注入团队规范。将修改后的模板目录作为一个“技能源”或“模板源”进行管理。未来你可以通过修改工作流或配置让工具优先从你的团队模板目录读取基础规则然后再进行技能发现和补充。这需要一定的脚本修改能力但一劳永逸。4.4 常见问题排查速查表问题现象可能原因解决方案运行/create-project-rules无反应或报错1. 工作流文件未正确下载。2. AI助手不支持工作流指令。1. 检查.agent/workflows/create-project-rules.md文件是否存在且内容完整。2. 确认你使用的AI IDE如Cursor支持并启用了工作流功能。技能发现结果为“未找到相关技能”1.skill_sources路径配置错误。2. 技能源格式不被识别。3. 项目分析得出的关键词太泛或太偏。1. 使用discover-skills.py --format手动检查路径和格式识别。2. 在.rulesrc.yaml中添加custom_keywords明确指定技术栈关键词。3. 确保技能源目录下确实有相关技能的文件夹或文件。生成的规则文件内容空洞、泛泛而谈1. 技能发现阶段失败或找到的技能不相关。2. 项目本身文件太少分析阶段无法提取有效信息。1. 参考4.1节进行技能发现调试。2. 在项目目录中放置一些有代表性的源码文件如主要的app.py、package.json再重新运行。3. 尝试提高severity_level为strict。验证脚本评分低于阈值1. 生成的文件存在占位符未替换。2. 文件结构不完整缺少某些章节。3. 存在指向不存在的本地路径的引用。1. 检查生成的.cursorrules和AGENTS.md搜索TODO、FIXME或{{等占位符并手动完善。2. 运行验证脚本时会输出详细的扣分项根据提示修改文件。合并现有文件时出现混乱合并逻辑无法处理复杂的手工修改。1. 备份你原有的规则文件。2. 使用existing_files: overwrite让工具生成全新的文件然后再将备份中的重要自定义内容手动迁移过去。3. 或者在生成前将旧文件重命名生成后再用对比工具进行差异化合并。工作流执行时间过长超过1小时1. 技能源路径配置过多或包含非常大的仓库如完整的awesome-skills。2. 网络问题导致克隆或读取技能源慢。1. 精简skill_sources只包含必要的技能库。2. 在技能发现阶段使用--limit参数限制返回数量。3. 考虑将大型技能库在本地缓存并使用绝对路径指向缓存位置避免每次从网络读取。4.5 维护与更新策略这个工具本身和技能库都在不断进化。为了保持最佳效果建议建立定期更新的习惯更新工具工作流关注项目GitHub仓库的Release定期用新的create-project-rules.md文件替换旧的。更新技能源定期进入你的共享技能根目录对克隆的各个技能库执行git pull获取最新的社区技能。审查生成的规则在项目发展的关键节点如引入新技术栈、架构重大调整后重新运行规则生成确保规则与项目现状同步。贡献反馈如果你发现了工具的Bug或者有改进建议可以到项目的GitHub Issues页面提交。如果你创建了针对特定技术栈的优质技能也可以考虑贡献给社区。经过几个月的实践这个AI项目规则生成器已经成了我新项目启动的标配流程。它节省的远不止是手动编写规则的那一两个小时更重要的是它建立了一个可重复、高质量、与团队知识库联动的AI协作规范起点。当每个新项目都基于一套智能发现的、贴合技术栈的最佳实践来运行时整个团队的代码质量和开发体验都能得到显著的提升。