he-yufeng/RuleForge

[](README.zh-CN.md) [](https://pypi.org/project/ruleforge/) [](https://github.com/he-yufeng/RuleForge/actions) [](LICENSE) # RuleForge **从你的代码库自动生成 AI 编程助手规则。** RuleForge 会扫描你的项目——包括语言、框架、linter、测试设置、CI 配置——并为 **Claude Code** (`CLAUDE.md`)、**Cursor** (`.cursorrules`)、**GitHub Copilot** (`.github/copilot-instructions.md`)、与工具无关的 **`AGENTS.md`** 规范、**Windsurf** (`.windsurfrules`)、**Cline** (`.clinerules`) 以及 **Gemini CLI** (`GEMINI.md`) 生成可直接使用的规则文件。 不要再手动编写这些文件了。让你的代码库自己说话。 ## 为什么需要？ 每个 AI 编程助手在有特定项目上下文的情况下都会表现得更好。但大多数开发者要么： - 完全不写规则（导致性能未能充分发挥） - 复制粘贴与实际技术栈不匹配的通用模板 - 花费 30 多分钟手工编写规则，却很快过时 RuleForge 通过实际读取你的项目配置，可以在几秒钟内生成准确且感知技术栈的规则。 ## 它能检测到什么 | 类别 | 示例 | |----------|---------| | **语言** | Python, TypeScript, JavaScript, Go, Rust, Java, C++, 以及 20 多种其他语言 | | **框架** | FastAPI, Flask, Django, React, Next.js, Vue, Svelte, Express, Gin, Axum... | | **包管理器** | pip, poetry, hatch, pnpm, yarn, bun, npm, cargo | | **Linter 与格式化工具** | ruff, black, eslint, prettier, biome, clippy, go fmt | | **测试框架** | pytest, unittest, vitest, jest, mocha | | **CI 系统** | GitHub Actions, GitLab CI, CircleCI, Jenkins | | **项目命令** | package scripts、Python CLI entry points，以及 GitHub Actions 使用的实际验证命令 | | **其他** | Docker, Makefile, monorepo 结构, entry points, .gitignore 匹配模式 | 语言统计数量会遵循 `.gitignore`，因此生成的打包文件和本地产物不会影响检测到的技术栈。 ## 安装 ``` pip install ruleforge ``` ## 快速开始 ``` # 扫描你的项目以查看检测到了什么 ruleforge scan . # 生成所有 rule 文件 (CLAUDE.md, .cursorrules, copilot-instructions) ruleforge generate . # 仅生成 CLAUDE.md ruleforge generate . -f claude # 预览而不写入任何内容 ruleforge preview . # 审计现有的 assistant rules 以查找缺失的指导 ruleforge audit . # 如果 rules 太单薄则使 CI 失败 ruleforge audit . --min-score 80 # Lint 现有 rules 以查找占位符、冲突和过时的建议 ruleforge lint . # 覆盖现有文件 ruleforge generate . --overwrite # 输出到不同的目录 ruleforge generate . -o /tmp/rules ``` ## 示例输出 在 FastAPI 项目上运行 `ruleforge generate` 会生成如下所示的 `CLAUDE.md`： ``` # my-api This is a Python project. Key frameworks: FastAPI, Pydantic, SQLAlchemy. ## Project Structure Source directories: `src/`, `tests/` Entry points: `main.py` Package manager: poetry ## Coding Conventions - Linter: ruff - Formatter: ruff - Testing: pytest - Python: >=3.11 - CI: GitHub Actions ## Project Commands - `npm run test`: `vitest run` - `npm run lint`: `eslint .` ## Guidelines - Use type hints for function signatures. - Run `ruff check` and `ruff format` before committing. - Write tests with pytest. Put test files in the `tests/` directory. - Use Pydantic models for request/response schemas. - The project uses Docker. Keep Dockerfile up to date with dependencies. ## Do NOT - Do not modify generated files or lock files manually. - Do not add dependencies without mentioning it. - Do not change the project structure without asking first. - Do not skip CI checks or disable linting rules. - Do not commit files matching gitignore patterns. ``` ## 支持的输出格式 | 格式 | 文件 | 使用者 | |--------|------|---------| | `claude` | `CLAUDE.md` | Claude Code, Claude Desktop | | `cursor` | `.cursorrules` | Cursor IDE | | `copilot` | `.github/copilot-instructions.md` | GitHub Copilot | | `agents` | `AGENTS.md` | 读取 `AGENTS.md` 的与工具无关的 agent | | `windsurf` | `.windsurfrules` | Windsurf / Codeium | | `cline` | `.clinerules` | Cline | | `gemini` | `GEMINI.md` | Gemini CLI | `ruleforge generate --format all` 会写入全部六种格式；可以重复传递 `--format`（例如 `--format agents --format cursor`）来选择一部分。 ## 规则审计 RuleForge 还能检查你已经编写好的规则文件。它会寻找那些通常能让 AI 编程 agent 在真实代码库中发挥实用作用的部分： - 项目上下文和检测到的技术栈 - 具体的测试、lint、typecheck 或构建命令 - 从 GitHub Actions `run` 步骤中提取的验证命令（跳过包含密钥的行） - 编辑边界和生成文件警告 - 密钥 / token / `.env` 处理 - git、PR、CI 和审查工作流 - 助手行为预期 ``` ruleforge audit . ruleforge audit . --format json ruleforge audit . --format sarif > ruleforge.sarif ruleforge audit . --min-score 80 ``` 这对于 CI 或检查手写的 `AGENTS.md`、`CLAUDE.md`、`.cursorrules` 或 Copilot 指令文件是否足够具体且值得信赖非常有用。SARIF 输出会将缺失的指导转化为 GitHub Code Scanning 发现的问题。当 RuleForge 生成新规则时，它现在还会指出已有的助手规则文件，以便生成的草稿不会意外覆盖更严格的本地指导。 ## 规则 Lint `audit` 衡量的是规则文件涵盖的范围，而 `lint` 则会寻找错误或无法使用的指导，这类问题会悄无声息地将 agent 引向错误的方向： - 遗留的模板占位符（`TODO`, `FIXME`, `{{ ... }}`, ``） - 冲突的指令，例如同时推荐 `npm` 和 `pnpm`、`pytest` 和 `unittest`，或者 `black` 和 `ruff` - 过时的建议，例如当代码库中存在 `pnpm-lock.yaml` 时却告诉 agent 使用 `yarn`，或者当项目已经切换到 `ruff` 时却要求使用 `black` 进行格式化 ``` ruleforge lint . ruleforge lint . --format json ruleforge lint . --strict # treat warnings as errors too ``` 占位符会被报告为错误，而冲突或过时的工具指令会被报告为警告。冲突和过时检查涵盖了包管理器、测试框架、linter 和格式化工具。当存在错误时（或在 `--strict` 下出现任何警告时），该命令将以非零状态退出，因此可以直接作为 CI 步骤运行。过时和冲突检查仅比较同一生态系统内的工具，因此如果多语言代码库确实同时运行 `pytest` 和 `jest`，或者 `ruff` 和 `eslint`，它们将被忽略。 ## Python API ``` from ruleforge import analyze_project, generate_rules from ruleforge.generator import write_rules # Analyze profile = analyze_project("./my-project") print(profile.languages) # {'Python': 42, 'TypeScript': 15} print(profile.frameworks) # ['FastAPI', 'React'] # Generate rules = generate_rules(profile, formats=["claude", "cursor"]) for rule in rules: print(rule.filename, len(rule.content)) # Write to disk write_rules(rules, "./my-project") ``` ## 限制 - 检测基于配置文件和文件扩展名——它不分析代码语义 - 生成的规则是一个坚实的起点，而不是最终产品。你应该根据项目的特定规范对其进行审查和自定义 - 框架检测依赖于依赖声明（pyproject.toml、package.json 等） ## 许可证 MIT

标签：AI编程助手, 代码库分析, 代码规范生成, 开发辅助工具, 网络调试, 自动化, 逆向工具