AI项目规则生成器：自动化配置AI编程助手规则与技能发现

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的分析结果，工具会使用提炼出的关键词（如api，fastapi，testing，pytest），去扫描你在Stage 0配置的所有技能源。它根据每个技能源的格式采取不同的搜索策略：

• 对于CATALOG格式（如antigravity-awesome-skills），它会搜索CATALOG.md表格中的行。
• 对于FOLDER格式（如awesome-claude-skills），它会遍历文件夹，读取每个技能目录下的SKILL.md、AGENTS.md等文件。
• 对于SEARCH_ENGINE格式，它会调用内置的搜索工具。 搜索到的技能会进行相关性排序，确保最匹配的技能排在前面。这里有个实用技巧：如果你的技能库很大（比如那个巨大的CATALOG），可以使用--limit参数限制返回结果数量，让AI助手后续的总结和集成更聚焦。

Stage 3: 生成.cursorrules（10-20分钟）利用前两个阶段的成果，工具开始构建项目的“宪法”。.cursorrules文件会包含：

• 项目身份：清晰定义项目类型、主要语言和框架。
• 关键规则：按严重性等级（🔴 关键 / 🟠 重要 / 🟡 建议）组织，这是确保代码质量的核心。
• 代码异味与最佳实践：用对比表格的形式，明确指出项目中要避免的坏味道和应该采用的好模式。
• 渐进式披露：复杂的规则会分层级组织，先给出核心要求，再在子章节展开细节，避免信息过载。

Stage 4: 生成AGENTS.md（10-15分钟）这个文件是写给AI助手看的“工作手册”。它会：

• 列出已发现的可用技能：告诉AI助手在这个项目里可以调用哪些现成的“外挂”。
• 说明如何查找更多技能：提供一个清晰的指南，说明如果遇到新问题，AI该如何自己去技能库里搜索（例如，“如果你需要处理数据库迁移，可以去CATALOG里搜索migration或alembic关键词”）。
• 提供项目特定的提示词：基于项目分析，给出一些针对性的上下文和提示。

Stage 5: 验证与统计（5-10分钟）生成不是终点，质量把关更重要。工具会运行验证脚本（validate-output.ps1或.sh），对生成的文件进行启发式评分（满分50分，默认38分通过）。评分维度包括完整性、准确性、特异性、可扫描性和一致性。同时，它会输出一份生成统计面板，告诉你扫描了多少技能、生成了多少行规则、质量得分如何，让你对结果心中有数。

2.2 多平台支持与格式兼容性设计

这个工具的另一个强大之处在于它的普适性。它不是为了某一个特定的AI IDE设计的，而是通过抽象层，支持了主流的9个AI编程平台。其设计哲学是：一次分析，多处生成。

这种设计确保了无论你的团队混用哪种工具，生成的规则都能被正确理解和应用。在实际操作中，我通常会在.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 # 如果已有规则文件，尝试合并而非覆盖

配置要点与避坑指南：

1. skill_sources的顺序至关重要：工具按列表顺序扫描。把共享的、包含团队通用规范的技能库路径放在前面，这样发现的技能会优先使用团队标准。项目本地的.agent放在后面，用于覆盖或补充项目特有的技能。
2. custom_keywords的妙用：自动分析不是万能的。如果你用了比较新的或小众的技术（比如trpc，supabase），或者有一些特殊的架构关注点（比如event-sourcing），一定要在这里加上。这能确保技能发现环节不会遗漏相关领域。
3. preview_mode: true：这是一个安全网。开启后，工具会在真正写入文件前，在终端或AI对话中展示即将生成的文件结构和主要内容。你可以检查技能发现是否准确、规则是否合理，确认无误后再执行写入操作。
4. 理解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助手的回复中看到它逐步推进：

1. 分析阶段：它会列出检测到的技术栈，比如“Python 3.11， FastAPI， SQLModel， Alembic， Pytest”。检查一下是否准确。
2. 技能发现阶段：你会看到它开始扫描你配置的技能源，并输出类似这样的日志：

   [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)

3. 预览阶段（如果开启）：工具会展示生成的.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. 格式探测的优先级与逻辑工具按以下顺序判断一个技能源目录的格式：

1. CATALOG：如果目录下存在CATALOG.md文件，并且该文件包含技能表格（通常有| Name | Description |这样的Markdown表格），则判定为CATALOG格式。这是效率最高的格式，因为搜索是在结构化的表格中进行的。
2. FOLDER：如果目录下存在直接子文件夹，且这些文件夹中包含SKILL.md、AGENTS.md或CLAUDE.md等技能定义文件，则判定为FOLDER格式。工具会为每个这样的文件夹创建一个“技能实体”。
3. SEARCH_ENGINE：如果目录下存在search.py或类似的搜索工具脚本，则判定为该格式，工具会调用这个脚本进行搜索。
4. README：如果目录下存在README.md，且内容包含类似技能分类列表的结构，则通过解析README来发现技能。
5. 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/目录下的某个模板，创建你团队的基础版本。

1. 复制templates/python-fastapi/目录到你的内部知识库。
2. 修改其中的.cursorrules和AGENTS.md文件，注入团队规范。
3. 将修改后的模板目录作为一个“技能源”或“模板源”进行管理。未来，你可以通过修改工作流或配置，让工具优先从你的团队模板目录读取基础规则，然后再进行技能发现和补充。这需要一定的脚本修改能力，但一劳永逸。

4.4 常见问题排查速查表

4.5 维护与更新策略

这个工具本身和技能库都在不断进化。为了保持最佳效果，建议建立定期更新的习惯：

1. 更新工具工作流：关注项目GitHub仓库的Release，定期用新的create-project-rules.md文件替换旧的。
2. 更新技能源：定期进入你的共享技能根目录，对克隆的各个技能库执行git pull，获取最新的社区技能。
3. 审查生成的规则：在项目发展的关键节点（如引入新技术栈、架构重大调整后），重新运行规则生成，确保规则与项目现状同步。
4. 贡献反馈：如果你发现了工具的Bug，或者有改进建议，可以到项目的GitHub Issues页面提交。如果你创建了针对特定技术栈的优质技能，也可以考虑贡献给社区。

经过几个月的实践，这个AI项目规则生成器已经成了我新项目启动的标配流程。它节省的远不止是手动编写规则的那一两个小时，更重要的是，它建立了一个可重复、高质量、与团队知识库联动的AI协作规范起点。当每个新项目都基于一套智能发现的、贴合技术栈的最佳实践来运行时，整个团队的代码质量和开发体验都能得到显著的提升。